xenial (1) fc.1posix.gz

Provided by: manpages-posix_2013a-1_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‐2008, 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‐2008,
                 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‐2008, 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‐2008, Chapter 8, Environment Variables, Section 12.2, Utility
       Syntax Guidelines

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers,  Inc
       and  The  Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 .