FC(1)                      POSIX Programmer's Manual                     FC(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       fc -- process the command history list

SSYYNNOOPPSSIISS
       fc [[-r]] [[-e _e_d_i_t_o_r]] [[_f_i_r_s_t [[_l_a_s_t]]]]

       fc -l [[-nr]] [[_f_i_r_s_t [[_l_a_s_t]]]]

       fc -s [[_o_l_d=_n_e_w]] [[_f_i_r_s_t]]

DDEESSCCRRIIPPTTIIOONN
       The _f_c utility shall list, or shall edit and re-execute, commands
       previously entered to an interactive _s_h.

       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 _H_I_S_T_S_I_Z_E 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, _f_c 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 --ll option is not specified), the
       resulting lines shall be entered at the end of the history list and
       then re-executed by _s_h.  The _f_c 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 _f_c shall affect both the _f_c 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 _f_c
       and the previous command.

OOPPTTIIOONNSS
       The _f_c utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

       --ee _e_d_i_t_o_r Use the editor named by _e_d_i_t_o_r to edit the commands. The
                 _e_d_i_t_o_r string is a utility name, subject to search via the
                 _P_A_T_H variable (see the Base Definitions volume of
                 POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s).  The value
                 in the _F_C_E_D_I_T variable shall be used as a default when --ee is
                 not specified. If _F_C_E_D_I_T is null or unset, _e_d shall be used
                 as the editor.

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

       --nn        Suppress command numbers when listing with --ll.

       --rr        Reverse the order of the commands listed (with --ll) or edited
                 (with neither --ll nor --ss).

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

OOPPEERRAANNDDSS
       The following operands shall be supported:

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

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

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

                 _s_t_r_i_n_g    A string indicating the most recently entered
                           command that begins with that string. If the
                           _o_l_d=_n_e_w operand is not also specified with --ss, the
                           string form of the _f_i_r_s_t operand cannot contain an
                           embedded <equals-sign>.

                 When the synopsis form with --ss is used:

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

                 For the synopsis forms without --ss:

                  *  If _l_a_s_t is omitted, _l_a_s_t shall default to the previous
                     command when --ll is specified; otherwise, it shall default
                     to _f_i_r_s_t.

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

                  *  If _f_i_r_s_t and _l_a_s_t are both present, all of the commands
                     from _f_i_r_s_t to _l_a_s_t shall be edited (without --ll) or listed
                     (with --ll).  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 _f_i_r_s_t represents a newer command than _l_a_s_t, the
                     commands shall be listed or edited in reverse sequence,
                     equivalent to using --rr.  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 _f_i_r_s_t or _l_a_s_t values that are not in the
                     history list; _f_c 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.

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

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _f_c:

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

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

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

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

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

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

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

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


           "%d\t%s\n", <_l_i_n_e _n_u_m_b_e_r>, <_c_o_m_m_a_n_d>

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


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

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


           "\t%s\n", <_c_o_n_t_i_n_u_e_d_-_c_o_m_m_a_n_d>

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       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
       _f_c.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Since editors sometimes use file descriptors as integral parts of their
       editing, redirecting their file descriptors as part of the _f_c command
       can produce unexpected results. For example, if _v_i is the _F_C_E_D_I_T
       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 _H_I_S_T_F_I_L_E as follows:


           HISTFILE=$HOME/.sh_hist$$

EEXXAAMMPPLLEESS
       None.

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

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

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

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

       Consideration was given to omitting the _f_c utility in favor of the
       command line editing feature in _s_h.  For example, in _v_i editing mode,
       typing ""<<EESSCC>>v" is equivalent to:


           EDITOR=vi fc

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

       In the KornShell, the alias rr (``re-do'') is preset to _f_c --ee --
       (equivalent to the POSIX _f_c --ss).  This is probably an easier command
       name to remember than _f_c (``fix command''), but it does not meet the
       Utility Syntax Guidelines.  Renaming _f_c to _h_i_s_t or _r_e_d_o 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 _f_c, _a_w_k,
       _c_a_t, _g_r_e_p, or _y_a_c_c are standardized by POSIX.

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

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _s_h

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

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



IEEE/The Open Group                  2017                                FC(1)
