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

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 re-
       direction 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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001, 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  immedi-
	      ately 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 equal 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  start-
		 ing  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.  (Refer-
	      ences 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 vari-
	      able, 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 unspeci-
	      fied, 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
	      IEEE Std 1003.1-2001,  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	%s
", <line number>, <command>

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

	      "	%s
", <command>

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

	      "	%s
", <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 com-
       mand 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 replac-
       ing 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  his-
       tory 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

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
       ogy -- 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 .

IEEE
/The Open Group						       2003								     FC(P)