diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/fc.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/fc.1p | 595 |
1 files changed, 595 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/fc.1p b/man-pages-posix-2017/man1p/fc.1p new file mode 100644 index 0000000..47bb688 --- /dev/null +++ b/man-pages-posix-2017/man1p/fc.1p @@ -0,0 +1,595 @@ +'\" et +.TH FC "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fc +\(em process the command history list +.SH SYNOPSIS +.LP +.nf +fc \fB[\fR-r\fB] [\fR-e \fIeditor\fB] [\fIfirst \fB[\fIlast\fB]]\fR +.P +fc -l\fB [\fR-nr\fB] [\fIfirst \fB[\fIlast\fB]]\fR +.P +fc -s\fB [\fIold\fR=\fInew\fB] [\fIfirst\fB]\fR +.fi +.SH DESCRIPTION +The +.IR fc +utility shall list, or shall edit and re-execute, commands previously +entered to an interactive +.IR sh . +.P +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 +.IR HISTSIZE +or 32\|767 (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, +.IR fc +shall maintain the time-ordering sequence of the commands. For +example, if four commands in sequence are given the numbers 32\|766, +32\|767, 1 (wrapped), and 2 as they are executed, command 32\|767 is +considered the command previous to 1, even though its number is +higher. +.P +When commands are edited (when the +.BR \-l +option is not specified), the resulting lines shall be entered at the +end of the history list and then re-executed by +.IR sh . +The +.IR fc +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 +.IR fc +shall affect both the +.IR fc +command itself as well as the command that results; for example: +.sp +.RS 4 +.nf + +fc -s -- -1 2>/dev/null +.fi +.P +.RE +.P +reinvokes the previous command, suppressing standard error for both +.IR fc +and the previous command. +.SH OPTIONS +The +.IR fc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-e\ \fIeditor\fR" 10 +Use the editor named by +.IR editor +to edit the commands. The +.IR editor +string is a utility name, subject to search via the +.IR PATH +variable (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables"). +The value in the +.IR FCEDIT +variable shall be used as a default when +.BR \-e +is not specified. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fB\-l\fP" 10 +(The letter ell.) List the commands rather than invoking an editor on +them. The commands shall be written in the sequence indicated by the +.IR first +and +.IR last +operands, as affected by +.BR \-r , +with each command preceded by the command number. +.IP "\fB\-n\fP" 10 +Suppress command numbers when listing with +.BR \-l . +.IP "\fB\-r\fP" 10 +Reverse the order of the commands listed (with +.BR \-l ) +or edited (with neither +.BR \-l +nor +.BR \-s ). +.IP "\fB\-s\fP" 10 +Re-execute the command without invoking an editor. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfirst\fR,\ \fIlast\fR" 10 +Select the commands to list or edit. The number of previous commands +that can be accessed shall be determined by the value of the +.IR HISTSIZE +variable. The value of +.IR first +or +.IR last +or both shall be one of the following: +.RS 10 +.IP "\fB[+]\fInumber\fR" 10 +A positive number representing a command number; command numbers can be +displayed with the +.BR \-l +option. +.IP "\fB\-\fInumber\fR" 10 +A negative decimal number representing the command that was executed +.IR number +of commands previously. For example, \-1 is the immediately previous +command. +.IP "\fIstring\fR" 10 +A string indicating the most recently entered command that begins with +that string. If the +.IR old =\c +.IR new +operand is not also specified with +.BR \-s , +the string form of the +.IR first +operand cannot contain an embedded +<equals-sign>. +.P +When the synopsis form with +.BR \-s +is used: +.IP " *" 4 +If +.IR first +is omitted, the previous command shall be used. +.P +For the synopsis forms without +.BR \-s : +.IP " *" 4 +If +.IR last +is omitted, +.IR last +shall default to the previous command when +.BR \-l +is specified; otherwise, it shall default to +.IR first . +.IP " *" 4 +If +.IR first +and +.IR last +are both omitted, the previous 16 commands shall be listed or the +previous single command shall be edited (based on the +.BR \-l +option). +.IP " *" 4 +If +.IR first +and +.IR last +are both present, all of the commands from +.IR first +to +.IR last +shall be edited (without +.BR \-l ) +or listed (with +.BR \-l ). +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 +.IR first +represents a newer command than +.IR last , +the commands shall be listed or edited in reverse sequence, equivalent +to using +.BR \-r . +For example, the following commands on the first line are equivalent to +the corresponding commands on the second: +.RS 4 +.sp +.RS 4 +.nf + +fc -r 10 20 fc 30 40 +fc 20 10 fc -r 40 30 +.fi +.P +.RE +.RE +.IP " *" 4 +When a range of commands is used, it shall not be an error to specify +.IR first +or +.IR last +values that are not in the history list; +.IR fc +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: +.RS 4 +.sp +.RS 4 +.nf + +fc -l +fc 1 99 +.fi +.P +.RE +.P +shall list and edit, respectively, all ten commands. +.RE +.RE +.IP "\fIold\fP=\fInew\fR" 10 +Replace the first occurrence of string +.IR old +in the commands to be re-executed by the string +.IR new . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fc : +.IP "\fIFCEDIT\fP" 10 +This variable, when expanded by the shell, shall determine the default +value for the +.BR \-e +.IR editor +option's +.IR editor +option-argument. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fIHISTFILE\fP" 10 +Determine a pathname naming a command history file. If the +.IR HISTFILE +variable is not set, the shell may attempt to access or create a file +.BR .sh_history +in the directory referred to by the +.IR HOME +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 +.IR fc +or +.IR sh +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 +.IR ENV +variable, or implementation-defined system start-up files. In some +historical shells, the history file is initialized just after the +.IR ENV +file has been processed. Therefore, it is implementation-defined +whether changes made to +.IR HISTFILE +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 +.IR HISTFILE ; +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. +.IP "\fIHISTSIZE\fP" 10 +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 +.IR HISTFILE . +Therefore, it is unspecified whether changes made to +.IR HISTSIZE +after the history file has been initialized are effective. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \-l +option is used to list commands, the format of each command in the list +shall be as follows: +.sp +.RS 4 +.nf + +"%d\et%s\en", <\fIline number\fR>, <\fIcommand\fR> +.fi +.P +.RE +.P +If both the +.BR \-l +and +.BR \-n +options are specified, the format of each command shall be: +.sp +.RS 4 +.nf + +"\et%s\en", <\fIcommand\fR> +.fi +.P +.RE +.P +If the <\fIcommand\fP> consists of more than one line, the lines after +the first shall be displayed as: +.sp +.RS 4 +.nf + +"\et%s\en", <\fIcontinued-command\fR> +.fi +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion of the listing. +.IP >0 6 +An error occurred. +.P +Otherwise, the exit status shall be that of the commands executed by +.IR fc . +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since editors sometimes use file descriptors as integral parts of their +editing, redirecting their file descriptors as part of the +.IR fc +command can produce unexpected results. For example, if +.IR vi +is the +.IR FCEDIT +editor, the command: +.sp +.RS 4 +.nf + +fc -s | more +.fi +.P +.RE +.P +does not work correctly on many systems. +.P +Users on windowing systems may want to have separate history files for +each window by setting +.IR HISTFILE +as follows: +.sp +.RS 4 +.nf + +HISTFILE=$HOME/.sh_hist$$ +.fi +.P +.RE +.SH "EXAMPLES" +None. +.SH RATIONALE +This utility is based on the +.IR fc +built-in of the KornShell. +.P +An early proposal specified the +.BR \-e +option as +.BR [\-e +.IR editor +.BR [ \c +.IR old \c += +.IR new +.BR ]\|] , +which is not historical practice. Historical practice in +.IR fc +of either +.BR [\-e +.IR editor \c +.BR ] +or +.BR "[\-e \- [" +.IR old \c += +.IR new +.BR ]\|] +is acceptable, but not both together. To clarify this, a new option +.BR \-s +was introduced replacing the +.BR "[\-e \-]" . +This resolves the conflict and makes +.IR fc +conform to the Utility Syntax Guidelines. +.IP "\fIHISTFILE\fP" 10 +Some implementations of the KornShell check for the superuser +and do not create a history file unless +.IR HISTFILE +is set. This is done primarily to avoid creating unlinked files in the +root file system when logging in during single-user mode. +.IR HISTFILE +must be set for the superuser to have history. +.IP "\fIHISTSIZE\fP" 10 +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. +.P +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 +.IR HISTFILE +and +.IR HISTSIZE . +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 +.IR ENV +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 +.IR ENV +file has been processed. Because of these situations, the text requires +the initialization process to be implementation-defined. +.P +Consideration was given to omitting the +.IR fc +utility in favor of the command line editing feature in +.IR sh . +For example, in +.IR vi +editing mode, typing +.BR \(dq<ESC> v\(dq +is equivalent to: +.sp +.RS 4 +.nf + +EDITOR=vi fc +.fi +.P +.RE +.P +However, the +.IR fc +utility allows the user the flexibility to edit multiple commands +simultaneously (such as +.IR fc +10 20) and to use editors other than those supported by +.IR sh +for command line editing. +.P +In the KornShell, the alias +.BR r +(``re-do'') is preset to +.IR fc +.BR "\-e \-" +(equivalent to the POSIX +.IR fc +.BR \-s ). +This is probably an easier command name to remember than +.IR fc +(``fix command''), but it does not meet the Utility Syntax Guidelines. +Renaming +.IR fc +to +.IR hist +or +.IR redo +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 +.IR fc , +.IR awk , +.IR cat , +.IR grep , +or +.IR yacc +are standardized by POSIX. +.P +Command numbers have no ordering effects; they are like serial numbers. +The +.BR \-r +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 4 +.nf + +32766: echo 1 +32767: echo 2 +1: echo 3 +.fi +.P +.RE +.P +the number \-2 refers to command 32\|767 because it is the second +previous command, regardless of serial number. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |