Import of man-pages 1.70

[thirdparty/man-pages.git] / man1p / fc.1p

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