'\" 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 .