diff options
Diffstat (limited to 'man1p/fc.1p')
| -rw-r--r-- | man1p/fc.1p | 476 |
1 files changed, 476 insertions, 0 deletions
diff --git a/man1p/fc.1p b/man1p/fc.1p new file mode 100644 index 000000000..fdd8ccadb --- /dev/null +++ b/man1p/fc.1p @@ -0,0 +1,476 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fc +.SH NAME +fc \- process the command history list +.SH SYNOPSIS +.LP +\fBfc\fP \fB[\fP\fB-r\fP\fB][\fP\fB-e\fP \fIeditor\fP\fB] +[\fP\fIfirst\fP\fB[\fP\fIlast\fP\fB]]\fP\fB +.br +.sp +fc -l\fP\fB[\fP\fB-nr\fP\fB] [\fP\fIfirst\fP\fB[\fP\fIlast\fP\fB]]\fP\fB +.br +.sp +fc -s\fP\fB[\fP\fIold\fP\fB=\fP\fInew\fP\fB][\fP\fIfirst\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfc\fP utility shall list, or shall edit and re-execute, commands +previously entered to an interactive \fIsh\fP. +.LP +The command history list shall reference commands by number. The first +number in the list is selected arbitrarily. The +relationship of a number to its command shall not change except when +the user logs in and no other process is accessing the list, +at which time the system may reset the numbering to start the oldest +retained command at another number (usually 1). When the +number reaches an implementation-defined upper limit, which shall +be no smaller than the value in \fIHISTSIZE\fP or 32767 +(whichever is greater), the shell may wrap the numbers, starting the +next command with a lower number (usually 1). However, despite +this optional wrapping of numbers, \fIfc\fP shall maintain the time-ordering +sequence of the commands. For example, if four +commands in sequence are given the numbers 32766, 32767, 1 (wrapped), +and 2 as they are executed, command 32767 is considered the +command previous to 1, even though its number is higher. +.LP +When commands are edited (when the \fB-l\fP option is not specified), +the resulting lines shall be entered at the end of the +history list and then re-executed by \fIsh\fP. The \fIfc\fP command +that caused the editing +shall not be entered into the history list. If the editor returns +a non-zero exit status, this shall suppress the entry into the +history list and the command re-execution. Any command line variable +assignments or redirection operators used with \fIfc\fP shall +affect both the \fIfc\fP command itself as well as the command that +results; for example: +.sp +.RS +.nf + +\fBfc -s -- -1 2>/dev/null +\fP +.fi +.RE +.LP +reinvokes the previous command, suppressing standard error for both +\fIfc\fP and the previous command. +.SH OPTIONS +.LP +The \fIfc\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-e\ \fP \fIeditor\fP +Use the editor named by \fIeditor\fP to edit the commands. The \fIeditor\fP +string is a utility name, subject to search via +the \fIPATH\fP variable (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 8, Environment Variables). The value in the \fIFCEDIT\fP variable +shall be used as a +default when \fB-e\fP is not specified. If \fIFCEDIT\fP is null or +unset, \fIed\fP shall be +used as the editor. +.TP 7 +\fB-l\fP +(The letter ell.) List the commands rather than invoking an editor +on them. The commands shall be written in the sequence +indicated by the \fIfirst\fP and \fIlast\fP operands, as affected +by \fB-r\fP, with each command preceded by the command +number. +.TP 7 +\fB-n\fP +Suppress command numbers when listing with \fB-l\fP. +.TP 7 +\fB-r\fP +Reverse the order of the commands listed (with \fB-l\fP) or edited +(with neither \fB-l\fP nor \fB-s\fP). +.TP 7 +\fB-s\fP +Re-execute the command without invoking an editor. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfirst\fP,\ \fIlast\fP +Select the commands to list or edit. The number of previous commands +that can be accessed shall be determined by the value of +the \fIHISTSIZE\fP variable. The value of \fIfirst\fP or \fIlast\fP +or both shall be one of the following: +.TP 7 +\fB[+]\fP\fInumber\fP +.RS +A positive number representing a command number; command numbers can +be displayed with the \fB-l\fP option. +.RE +.TP 7 +\fB-\fP\fInumber\fP +.RS +A negative decimal number representing the command that was executed +\fInumber\fP of commands previously. For example, -1 is +the immediately previous command. +.RE +.TP 7 +\fIstring\fP +.RS +A string indicating the most recently entered command that begins +with that string. If the \fIold\fP= \fInew\fP operand is +not also specified with \fB-s\fP, the string form of the \fIfirst\fP +operand cannot contain an embedded equal sign. +.RE +.sp +.LP +When the synopsis form with \fB-s\fP is used: +.RS +.IP " *" 3 +If \fIfirst\fP is omitted, the previous command shall be used. +.LP +.RE +.LP +For the synopsis forms without \fB-s\fP: +.RS +.IP " *" 3 +If \fIlast\fP is omitted, \fIlast\fP shall default to the previous +command when \fB-l\fP is specified; otherwise, it shall +default to \fIfirst\fP. +.LP +.IP " *" 3 +If \fIfirst\fP and \fIlast\fP are both omitted, the previous 16 commands +shall be listed or the previous single command shall +be edited (based on the \fB-l\fP option). +.LP +.IP " *" 3 +If \fIfirst\fP and \fIlast\fP are both present, all of the commands +from \fIfirst\fP to \fIlast\fP shall be edited (without +\fB-l\fP) or listed (with \fB-l\fP). Editing multiple commands shall +be accomplished by presenting to the editor all of the +commands at one time, each command starting on a new line. If \fIfirst\fP +represents a newer command than \fIlast\fP, the +commands shall be listed or edited in reverse sequence, equivalent +to using \fB-r\fP. For example, the following commands on the +first line are equivalent to the corresponding commands on the second: +.sp +.RS +.nf + +\fBfc -r 10 20 fc 30 40 +fc 20 10 fc -r 40 30 +\fP +.fi +.RE +.LP +.IP " *" 3 +When a range of commands is used, it shall not be an error to specify +\fIfirst\fP or \fIlast\fP values that are not in the +history list; \fIfc\fP shall substitute the value representing the +oldest or newest command in the list, as appropriate. For +example, if there are only ten commands in the history list, numbered +1 to 10: +.sp +.RS +.nf + +\fBfc -l +fc 1 99 +\fP +.fi +.RE +.LP +shall list and edit, respectively, all ten commands. +.LP +.RE +.TP 7 +\fIold\fP=\fInew\fP +Replace the first occurrence of string \fIold\fP in the commands to +be re-executed by the string \fInew\fP. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfc\fP: +.TP 7 +\fIFCEDIT\fP +This variable, when expanded by the shell, shall determine the default +value for the \fB-e\fP \fIeditor\fP option's +\fIeditor\fP option-argument. If \fIFCEDIT\fP is null or unset, \fIed\fP +shall be used as the +editor. +.TP 7 +\fIHISTFILE\fP +Determine a pathname naming a command history file. If the \fIHISTFILE\fP +variable is not set, the shell may attempt to access +or create a file \fB.sh_history\fP in the directory referred to by +the \fIHOME\fP environment variable. If the shell cannot +obtain both read and write access to, or create, the history file, +it shall use an unspecified mechanism that allows the history to +operate properly. (References to history "file" in this section shall +be understood to mean this unspecified mechanism in such +cases.) An implementation may choose to access this variable only +when initializing the history file; this initialization shall +occur when \fIfc\fP or \fIsh\fP first attempt to retrieve entries +from, or add entries to, the +file, as the result of commands issued by the user, the file named +by the \fIENV\fP variable, or implementation-defined system +start-up files. In some historical shells, the history file is initialized +just after the \fIENV\fP file has been processed. +Therefore, it is implementation-defined whether changes made to \fIHISTFILE\fP +after the history file has been initialized are +effective. Implementations may choose to disable the history list +mechanism for users with appropriate privileges who do not set +\fIHISTFILE ;\fP the specific circumstances under which this occurs +are implementation-defined. If more than one instance of the +shell is using the same history file, it is unspecified how updates +to the history file from those shells interact. As entries are +deleted from the history file, they shall be deleted oldest first. +It is unspecified when history file entries are physically +removed from the history file. +.TP 7 +\fIHISTSIZE\fP +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is +unset, an unspecified default greater than or equal to 128 shall be +used. The maximum number of commands in the history list is +unspecified, but shall be at least 128. An implementation may choose +to access this variable only when initializing the history +file, as described under \fIHISTFILE .\fP Therefore, it is unspecified +whether changes made to \fIHISTSIZE\fP after the history +file has been initialized are effective. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-l\fP option is used to list commands, the format of each +command in the list shall be as follows: +.sp +.RS +.nf + +\fB"%d\\t%s\\n", <\fP\fIline number\fP\fB>, <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.LP +If both the \fB-l\fP and \fB-n\fP options are specified, the format +of each command shall be: +.sp +.RS +.nf + +\fB"\\t%s\\n", <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.LP +If the <\fIcommand\fP> consists of more than one line, the lines after +the first shall be displayed as: +.sp +.RS +.nf + +\fB"\\t%s\\n", <\fP\fIcontinued-command\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion of the listing. +.TP 7 +>0 +An error occurred. +.sp +.LP +Otherwise, the exit status shall be that of the commands executed +by \fIfc\fP. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since editors sometimes use file descriptors as integral parts of +their editing, redirecting their file descriptors as part of +the \fIfc\fP command can produce unexpected results. For example, +if \fIvi\fP is the +\fIFCEDIT\fP editor, the command: +.sp +.RS +.nf + +\fBfc -s | more +\fP +.fi +.RE +.LP +does not work correctly on many systems. +.LP +Users on windowing systems may want to have separate history files +for each window by setting \fIHISTFILE\fP as follows: +.sp +.RS +.nf + +\fBHISTFILE=$HOME/.sh_hist$$ +\fP +.fi +.RE +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +This utility is based on the \fIfc\fP built-in of the KornShell. +.LP +An early proposal specified the \fB-e\fP option as \fB[-e\fP \fIeditor\fP +\fB[\fP \fIold\fP = \fInew\fP \fB]]\fP, which +is not historical practice. Historical practice in \fIfc\fP of either +\fB[-e\fP \fIeditor\fP \fB]\fP or \fB[-e - [\fP +\fIold\fP = \fInew\fP \fB]]\fP is acceptable, but not both together. +To clarify this, a new option \fB-s\fP was introduced +replacing the \fB[-e -]\fP. This resolves the conflict and makes \fIfc\fP +conform to the Utility Syntax Guidelines. +.TP 7 +\fIHISTFILE\fP +Some implementations of the KornShell check for the superuser and +do not create a history file unless \fIHISTFILE\fP is set. +This is done primarily to avoid creating unlinked files in the root +file system when logging in during single-user mode. +\fIHISTFILE\fP must be set for the superuser to have history. +.TP 7 +\fIHISTSIZE\fP +Needed to limit the size of history files. It is the intent of the +standard developers that when two shells share the same +history file, commands that are entered in one shell shall be accessible +by the other shell. Because of the difficulties of +synchronization over a network, the exact nature of the interaction +is unspecified. +.sp +.LP +The initialization process for the history file can be dependent on +the system start-up files, in that they may contain commands +that effectively preempt the settings the user has for \fIHISTFILE\fP +and \fIHISTSIZE .\fP For example, function definition +commands are recorded in the history file. If the system administrator +includes function definitions in some system start-up file +called before the \fIENV\fP file, the history file is initialized +before the user can influence its characteristics. In some +historical shells, the history file is initialized just after the +\fIENV\fP file has been processed. Because of these situations, +the text requires the initialization process to be implementation-defined. +.LP +Consideration was given to omitting the \fIfc\fP utility in favor +of the command line editing feature in \fIsh\fP. For example, in \fIvi\fP +editing mode, typing +\fB"<ESC> v"\fP is equivalent to: +.sp +.RS +.nf + +\fBEDITOR=vi fc +\fP +.fi +.RE +.LP +However, the \fIfc\fP utility allows the user the flexibility to edit +multiple commands simultaneously (such as \fIfc\fP 10 +20) and to use editors other than those supported by \fIsh\fP for +command line editing. +.LP +In the KornShell, the alias \fBr\fP (``re-do") is preset to \fIfc\fP +\fB-e -\fP (equivalent to the POSIX \fIfc\fP +\fB-s\fP). This is probably an easier command name to remember than +\fIfc\fP (``fix command"), but it does not meet the Utility +Syntax Guidelines. Renaming \fIfc\fP to \fIhist\fP or \fIredo\fP was +considered, but since this description closely matches +historical KornShell practice already, such a renaming was seen as +gratuitous. Users are free to create aliases whenever odd +historical names such as \fIfc\fP, \fIawk\fP, \fIcat\fP, +\fIgrep\fP, or \fIyacc\fP are standardized by +POSIX. +.LP +Command numbers have no ordering effects; they are like serial numbers. +The \fB-r\fP option and -\fInumber\fP operand address +the sequence of command execution, regardless of serial numbers. So, +for example, if the command number wrapped back to 1 at some +arbitrary point, there would be no ambiguity associated with traversing +the wrap point. For example, if the command history +were: +.sp +.RS +.nf + +\fB32766: echo 1 +32767: echo 2 +1: echo 3 +\fP +.fi +.RE +.LP +the number -2 refers to command 32767 because it is the second previous +command, regardless of serial number. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsh\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |