1FC(1P)                     POSIX Programmer's Manual                    FC(1P)
2
3
4

PROLOG

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

NAME

12       fc — process the command history list
13

SYNOPSIS

15       fc [-r] [-e editor] [first [last]]
16
17       fc -l [-nr] [first [last]]
18
19       fc -s [old=new] [first]
20

DESCRIPTION

22       The fc utility shall list, or shall edit and re-execute, commands  pre‐
23       viously entered to an interactive sh.
24
25       The  command history list shall reference commands by number. The first
26       number in the list is selected arbitrarily. The relationship of a  num‐
27       ber to its command shall not change except when the user logs in and no
28       other process is accessing the list, at which time the system may reset
29       the  numbering  to  start the oldest retained command at another number
30       (usually 1). When the number reaches  an  implementation-defined  upper
31       limit,  which  shall  be no smaller than the value in HISTSIZE or 32767
32       (whichever is greater), the shell may wrap the  numbers,  starting  the
33       next  command  with  a  lower number (usually 1). However, despite this
34       optional wrapping of  numbers,  fc  shall  maintain  the  time-ordering
35       sequence of the commands. For example, if four commands in sequence are
36       given the numbers 32766, 32767, 1 (wrapped), and 2  as  they  are  exe‐
37       cuted,  command  32767  is  considered  the command previous to 1, even
38       though its number is higher.
39
40       When commands are edited (when the -l option  is  not  specified),  the
41       resulting  lines  shall  be  entered at the end of the history list and
42       then re-executed by sh.  The fc command that caused the  editing  shall
43       not  be entered into the history list. If the editor returns a non-zero
44       exit status, this shall suppress the entry into the  history  list  and
45       the command re-execution.  Any command line variable assignments or re‐
46       direction operators used with fc  shall  affect  both  the  fc  command
47       itself as well as the command that results; for example:
48
49
50           fc -s -- -1 2>/dev/null
51
52       reinvokes  the previous command, suppressing standard error for both fc
53       and the previous command.
54

OPTIONS

56       The fc  utility  shall  conform  to  the  Base  Definitions  volume  of
57       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
58
59       The following options shall be supported:
60
61       -e editor Use the editor named by editor to edit the commands. The edi‐
62                 tor string is a utility name, subject to search via the  PATH
63                 variable  (see  the  Base Definitions volume of POSIX.1‐2017,
64                 Chapter 8, Environment Variables).  The value in  the  FCEDIT
65                 variable shall be used as a default when -e is not specified.
66                 If FCEDIT is null or unset, ed shall be used as the editor.
67
68       -l        (The letter ell.) List the commands rather than  invoking  an
69                 editor on them. The commands shall be written in the sequence
70                 indicated by the first and last operands, as affected by  -r,
71                 with each command preceded by the command number.
72
73       -n        Suppress command numbers when listing with -l.
74
75       -r        Reverse  the order of the commands listed (with -l) or edited
76                 (with neither -l nor -s).
77
78       -s        Re-execute the command without invoking an editor.
79

OPERANDS

81       The following operands shall be supported:
82
83       first, last
84                 Select the commands to list or edit. The number  of  previous
85                 commands  that  can  be  accessed  shall be determined by the
86                 value of the HISTSIZE variable. The value of first or last or
87                 both shall be one of the following:
88
89                 [+]number A  positive  number  representing a command number;
90                           command  numbers  can  be  displayed  with  the  -l
91                           option.
92
93                 -number   A  negative decimal number representing the command
94                           that was executed number  of  commands  previously.
95                           For  example,  -1  is the immediately previous com‐
96                           mand.
97
98                 string    A string indicating the most recently entered  com‐
99                           mand  that  begins with that string. If the old=new
100                           operand is not also specified with -s,  the  string
101                           form  of the first operand cannot contain an embed‐
102                           ded <equals-sign>.
103
104                 When the synopsis form with -s is used:
105
106                  *  If first is omitted, the previous command shall be used.
107
108                 For the synopsis forms without -s:
109
110                  *  If last is omitted, last shall default  to  the  previous
111                     command when -l is specified; otherwise, it shall default
112                     to first.
113
114                  *  If first and last are both omitted, the previous 16  com‐
115                     mands  shall  be  listed  or  the previous single command
116                     shall be edited (based on the -l option).
117
118                  *  If first and last are both present, all of  the  commands
119                     from first to last shall be edited (without -l) or listed
120                     (with -l).  Editing multiple  commands  shall  be  accom‐
121                     plished  by  presenting to the editor all of the commands
122                     at one time, each command starting  on  a  new  line.  If
123                     first  represents a newer command than last, the commands
124                     shall be listed or edited in reverse sequence, equivalent
125                     to  using -r.  For example, the following commands on the
126                     first line are equivalent to the  corresponding  commands
127                     on the second:
128
129
130                         fc -r 10 20    fc    30 40
131                         fc    20 10    fc -r 40 30
132
133                  *  When  a  range  of  commands  is used, it shall not be an
134                     error to specify first or last values that are not in the
135                     history  list; fc shall substitute the value representing
136                     the oldest or newest command in the list, as appropriate.
137                     For  example,  if there are only ten commands in the his‐
138                     tory list, numbered 1 to 10:
139
140
141                         fc -l
142                         fc 1 99
143
144                     shall list and edit, respectively, all ten commands.
145
146       old=new   Replace the first occurrence of string old in the commands to
147                 be re-executed by the string new.
148

STDIN

150       Not used.
151

INPUT FILES

153       None.
154

ENVIRONMENT VARIABLES

156       The following environment variables shall affect the execution of fc:
157
158       FCEDIT    This  variable,  when  expanded by the shell, shall determine
159                 the default value for the -e editor option's  editor  option-
160                 argument. If FCEDIT is null or unset, ed shall be used as the
161                 editor.
162
163       HISTFILE  Determine a pathname naming a command history  file.  If  the
164                 HISTFILE variable is not set, the shell may attempt to access
165                 or create a file .sh_history in the directory referred to  by
166                 the  HOME  environment  variable.  If the shell cannot obtain
167                 both read and write access to, or create, the  history  file,
168                 it shall use an unspecified mechanism that allows the history
169                 to operate properly. (References to history ``file'' in  this
170                 section  shall  be understood to mean this unspecified mecha‐
171                 nism in such cases.) An implementation may choose  to  access
172                 this  variable  only when initializing the history file; this
173                 initialization shall occur when fc or  sh  first  attempt  to
174                 retrieve  entries  from,  or add entries to, the file, as the
175                 result of commands issued by the user, the file named by  the
176                 ENV   variable,  or  implementation-defined  system  start-up
177                 files. In some historical shells, the history  file  is  ini‐
178                 tialized  just  after the ENV file has been processed. There‐
179                 fore, it is implementation-defined whether  changes  made  to
180                 HISTFILE  after  the  history  file  has been initialized are
181                 effective.  Implementations may choose to disable the history
182                 list  mechanism  for users with appropriate privileges who do
183                 not set HISTFILE; the specific circumstances under which this
184                 occurs  are implementation-defined. If more than one instance
185                 of the shell is using the same history file, it  is  unspeci‐
186                 fied how updates to the history file from those shells inter‐
187                 act. As entries are deleted from the history file, they shall
188                 be  deleted oldest first. It is unspecified when history file
189                 entries are physically removed from the history file.
190
191       HISTSIZE  Determine a decimal number representing the limit to the num‐
192                 ber  of  previous commands that are accessible. If this vari‐
193                 able is unset, an unspecified default greater than  or  equal
194                 to  128  shall be used. The maximum number of commands in the
195                 history list is unspecified, but shall be at  least  128.  An
196                 implementation  may  choose to access this variable only when
197                 initializing the history file, as described  under  HISTFILE.
198                 Therefore, it is unspecified whether changes made to HISTSIZE
199                 after the history file has been initialized are effective.
200
201       LANG      Provide a default value for  the  internationalization  vari‐
202                 ables  that are unset or null. (See the Base Definitions vol‐
203                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
204                 ables  for  the  precedence of internationalization variables
205                 used to determine the values of locale categories.)
206
207       LC_ALL    If set to a non-empty string value, override  the  values  of
208                 all the other internationalization variables.
209
210       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
211                 bytes of text data as characters (for example, single-byte as
212                 opposed  to  multi-byte  characters  in  arguments  and input
213                 files).
214
215       LC_MESSAGES
216                 Determine the locale that should be used to affect the format
217                 and  contents  of  diagnostic  messages  written  to standard
218                 error.
219
220       NLSPATH   Determine the location of message catalogs for the processing
221                 of LC_MESSAGES.
222

ASYNCHRONOUS EVENTS

224       Default.
225

STDOUT

227       When the -l option is used to list commands, the format of each command
228       in the list shall be as follows:
229
230
231           "%d\t%s\n", <line number>, <command>
232
233       If both the -l and -n options are specified, the format of each command
234       shall be:
235
236
237           "\t%s\n", <command>
238
239       If  the  <command>  consists of more than one line, the lines after the
240       first shall be displayed as:
241
242
243           "\t%s\n", <continued-command>
244

STDERR

246       The standard error shall be used only for diagnostic messages.
247

OUTPUT FILES

249       None.
250

EXTENDED DESCRIPTION

252       None.
253

EXIT STATUS

255       The following exit values shall be returned:
256
257        0    Successful completion of the listing.
258
259       >0    An error occurred.
260
261       Otherwise, the exit status shall be that of the  commands  executed  by
262       fc.
263

CONSEQUENCES OF ERRORS

265       Default.
266
267       The following sections are informative.
268

APPLICATION USAGE

270       Since editors sometimes use file descriptors as integral parts of their
271       editing, redirecting their file descriptors as part of the  fc  command
272       can  produce  unexpected results. For example, if vi is the FCEDIT edi‐
273       tor, the command:
274
275
276           fc -s | more
277
278       does not work correctly on many systems.
279
280       Users on windowing systems may want to have separate history files  for
281       each window by setting HISTFILE as follows:
282
283
284           HISTFILE=$HOME/.sh_hist$$
285

EXAMPLES

287       None.
288

RATIONALE

290       This utility is based on the fc built-in of the KornShell.
291
292       An  early  proposal specified the -e option as [-e editor [old= new ]],
293       which is not historical practice. Historical practice in fc  of  either
294       [-e  editor]  or  [-e  -  [  old=  new  ]]  is acceptable, but not both
295       together. To clarify this, a new option -s was introduced replacing the
296       [-e -].  This resolves the conflict and makes fc conform to the Utility
297       Syntax Guidelines.
298
299       HISTFILE  Some implementations of the KornShell check for the superuser
300                 and do not create a history file unless HISTFILE is set. This
301                 is done primarily to avoid creating  unlinked  files  in  the
302                 root  file  system  when  logging in during single-user mode.
303                 HISTFILE must be set for the superuser to have history.
304
305       HISTSIZE  Needed to limit the size of history files. It is  the  intent
306                 of  the  standard  developers  that when two shells share the
307                 same history file, commands that are  entered  in  one  shell
308                 shall be accessible by the other shell. Because of the diffi‐
309                 culties of synchronization over a network, the  exact  nature
310                 of the interaction is unspecified.
311
312       The initialization process for the history file can be dependent on the
313       system start-up files, in that they may contain  commands  that  effec‐
314       tively  preempt  the  settings  the user has for HISTFILE and HISTSIZE.
315       For example, function definition commands are recorded in  the  history
316       file. If the system administrator includes function definitions in some
317       system start-up file called before the ENV file, the  history  file  is
318       initialized  before the user can influence its characteristics. In some
319       historical shells, the history file is initialized just after  the  ENV
320       file has been processed. Because of these situations, the text requires
321       the initialization process to be implementation-defined.
322
323       Consideration was given to omitting the fc utility in favor of the com‐
324       mand line editing feature in sh.  For example, in vi editing mode, typ‐
325       ing "<ESC>v" is equivalent to:
326
327
328           EDITOR=vi fc
329
330       However, the fc utility allows the user the flexibility to edit  multi‐
331       ple commands simultaneously (such as fc 10 20) and to use editors other
332       than those supported by sh for command line editing.
333
334       In the KornShell, the alias r (``re-do'') is preset to fc -e - (equiva‐
335       lent  to  the POSIX fc -s).  This is probably an easier command name to
336       remember than fc (``fix command''), but it does not  meet  the  Utility
337       Syntax  Guidelines.   Renaming  fc  to hist or redo was considered, but
338       since this description closely matches  historical  KornShell  practice
339       already,  such  a  renaming  was seen as gratuitous.  Users are free to
340       create aliases whenever odd historical names  such  as  fc,  awk,  cat,
341       grep, or yacc are standardized by POSIX.
342
343       Command numbers have no ordering effects; they are like serial numbers.
344       The -r option and -number operand address the sequence of command  exe‐
345       cution,  regardless  of serial numbers. So, for example, if the command
346       number wrapped back to 1 at some arbitrary point,  there  would  be  no
347       ambiguity  associated  with  traversing the wrap point. For example, if
348       the command history were:
349
350
351           32766: echo 1
352           32767: echo 2
353           1: echo 3
354
355       the number -2 refers to command 32767 because it is the second previous
356       command, regardless of serial number.
357

FUTURE DIRECTIONS

359       None.
360

SEE ALSO

362       sh
363
364       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
365       Variables, Section 12.2, Utility Syntax Guidelines
366
368       Portions of this text are reprinted and reproduced in  electronic  form
369       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
370       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
371       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
372       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
373       event of any discrepancy between this version and the original IEEE and
374       The Open Group Standard, the original IEEE and The Open Group  Standard
375       is  the  referee document. The original Standard can be obtained online
376       at http://www.opengroup.org/unix/online.html .
377
378       Any typographical or formatting errors that appear  in  this  page  are
379       most likely to have been introduced during the conversion of the source
380       files to man page format. To report such errors,  see  https://www.ker
381       nel.org/doc/man-pages/reporting_bugs.html .
382
383
384
385IEEE/The Open Group                  2017                               FC(1P)
Impressum