Provided by: manpages-posix_2017a-2_all bug

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.

NAME

       fc — process the command history list

SYNOPSIS

       fc [-r] [-e editor] [first [last]]

       fc -l [-nr] [first [last]]

       fc -s [old=new] [first]

DESCRIPTION

       The fc utility shall list, or shall edit and re-execute, commands previously entered to an
       interactive sh.

       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 HISTSIZE 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, fc 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.

       When commands are edited (when the -l option is not specified), the resulting lines  shall
       be entered at the end of the history list and then re-executed by sh.  The 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 fc
       shall affect both the fc command itself as well as the command that results; for example:

           fc -s -- -1 2>/dev/null

       reinvokes  the  previous  command, suppressing standard error for both fc and the previous
       command.

OPTIONS

       The fc utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2,
       Utility Syntax Guidelines.

       The following options shall be supported:

       -e editor Use  the  editor  named  by  editor to edit the commands. The editor string is a
                 utility name, subject to search via the PATH variable (see the Base  Definitions
                 volume  of  POSIX.1‐2017,  Chapter  8, Environment Variables).  The value in the
                 FCEDIT variable shall be used as a default when -e is not specified.  If  FCEDIT
                 is null or unset, ed shall be used as the editor.

       -l        (The  letter ell.) List the commands rather than invoking an editor on them. The
                 commands shall be written in the  sequence  indicated  by  the  first  and  last
                 operands, as affected by -r, with each command preceded by the command number.

       -n        Suppress command numbers when listing with -l.

       -r        Reverse  the  order  of the commands listed (with -l) or edited (with neither -l
                 nor -s).

       -s        Re-execute the command without invoking an editor.

OPERANDS

       The following operands shall be supported:

       first, last
                 Select the commands to list or edit. The number of previous commands that can be
                 accessed shall be determined by the value of the HISTSIZE variable. The value of
                 first or last or both shall be one of the following:

                 [+]number A positive number representing a command number; command  numbers  can
                           be displayed with the -l option.

                 -number   A  negative  decimal number representing the command that was executed
                           number of commands previously. For  example,  -1  is  the  immediately
                           previous command.

                 string    A string indicating the most recently entered command that begins with
                           that string. If the old=new operand is not also specified with -s, the
                           string  form  of the first operand cannot contain an embedded <equals-
                           sign>.

                 When the synopsis form with -s is used:

                  *  If first is omitted, the previous command shall be used.

                 For the synopsis forms without -s:

                  *  If last is omitted, last shall default to the previous command  when  -l  is
                     specified; otherwise, it shall default to first.

                  *  If first and last are both omitted, the previous 16 commands shall be listed
                     or the previous single command shall be edited (based on the -l option).

                  *  If first and last are both present, all of the commands from first  to  last
                     shall be edited (without -l) or listed (with -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 first represents a newer
                     command than last, the  commands  shall  be  listed  or  edited  in  reverse
                     sequence,  equivalent  to  using -r.  For example, the following commands on
                     the first line are equivalent to the corresponding commands on the second:

                         fc -r 10 20    fc    30 40
                         fc    20 10    fc -r 40 30

                  *  When a range of commands is used, it shall not be an error to specify  first
                     or  last  values  that  are not in the history list; 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:

                         fc -l
                         fc 1 99

                     shall list and edit, respectively, all ten commands.

       old=new   Replace the first occurrence of string old in the commands to be re-executed  by
                 the string new.

STDIN

       Not used.

INPUT FILES

       None.

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of fc:

       FCEDIT    This variable, when expanded by the shell, shall determine the default value for
                 the -e editor option's editor option-argument. If FCEDIT is null  or  unset,  ed
                 shall be used as the editor.

       HISTFILE  Determine  a pathname naming a command history file. If the HISTFILE variable is
                 not set, the shell may attempt to access or create a  file  .sh_history  in  the
                 directory  referred  to  by  the  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  fc or 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
                 ENV   variable,   or  implementation-defined  system  start-up  files.  In  some
                 historical shells, the history file is initialized just after the ENV  file  has
                 been  processed. Therefore, it is implementation-defined whether changes made to
                 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 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.

       HISTSIZE  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 HISTFILE.  Therefore, it is unspecified whether changes made  to
                 HISTSIZE after the history file has been initialized are effective.

       LANG      Provide a default value for the internationalization variables that are unset or
                 null.  (See  the  Base  Definitions  volume  of   POSIX.1‐2017,   Section   8.2,
                 Internationalization   Variables  for  the  precedence  of  internationalization
                 variables used to determine the values of locale categories.)

       LC_ALL    If set to a non-empty string  value,  override  the  values  of  all  the  other
                 internationalization variables.

       LC_CTYPE  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).

       LC_MESSAGES
                 Determine  the  locale  that should be used to affect the format and contents of
                 diagnostic messages written to standard error.

       NLSPATH   Determine the location of message catalogs for the processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       When the -l option is used to list commands, the format of each command in the list  shall
       be as follows:

           "%d\t%s\n", <line number>, <command>

       If both the -l and -n options are specified, the format of each command shall be:

           "\t%s\n", <command>

       If  the  <command>  consists  of  more  than  one line, the lines after the first shall be
       displayed as:

           "\t%s\n", <continued-command>

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0    Successful completion of the listing.

       >0    An error occurred.

       Otherwise, the exit status shall be that of the commands executed by fc.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       Since editors  sometimes  use  file  descriptors  as  integral  parts  of  their  editing,
       redirecting  their  file  descriptors  as  part  of  the fc command can produce unexpected
       results. For example, if vi is the FCEDIT editor, the command:

           fc -s | more

       does not work correctly on many systems.

       Users on windowing systems may want to have separate history  files  for  each  window  by
       setting HISTFILE as follows:

           HISTFILE=$HOME/.sh_hist$$

EXAMPLES

       None.

RATIONALE

       This utility is based on the fc built-in of the KornShell.

       An  early  proposal  specified  the  -e  option  as  [-e editor [old= new ]], which is not
       historical practice. Historical practice in fc of either [-e editor] or [-e - [  old=  new
       ]]  is  acceptable, but not both together. To clarify this, a new option -s was introduced
       replacing the [-e -].  This resolves the conflict and makes  fc  conform  to  the  Utility
       Syntax Guidelines.

       HISTFILE  Some  implementations of the KornShell check for the superuser and do not create
                 a history file unless HISTFILE is set. This is done primarily to avoid  creating
                 unlinked  files in the root file system when logging in during single-user mode.
                 HISTFILE must be set for the superuser to have history.

       HISTSIZE  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.

       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 HISTFILE and 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 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 ENV file has been processed. Because of these  situations,  the
       text requires the initialization process to be implementation-defined.

       Consideration  was  given  to omitting the fc utility in favor of the command line editing
       feature in sh.  For example, in vi editing mode, typing "<ESC>v" is equivalent to:

           EDITOR=vi fc

       However, the fc utility  allows  the  user  the  flexibility  to  edit  multiple  commands
       simultaneously  (such as fc 10 20) and to use editors other than those supported by sh for
       command line editing.

       In the KornShell, the alias r (``re-do'') is preset to fc -e - (equivalent to the POSIX fc
       -s).   This  is probably an easier command name to remember than fc (``fix command''), but
       it does not meet the  Utility  Syntax  Guidelines.   Renaming  fc  to  hist  or  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 fc, awk, cat, grep, or yacc are standardized by
       POSIX.

       Command numbers have no ordering effects; they are like serial numbers.  The -r option and
       -number  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:

           32766: echo 1
           32767: echo 2
           1: echo 3

       the number -2 refers  to  command  32767  because  it  is  the  second  previous  command,
       regardless of serial number.

FUTURE DIRECTIONS

       None.

SEE ALSO

       sh

       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment Variables, Section
       12.2, Utility Syntax Guidelines

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 .

       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 .