1KSH(1)                      General Commands Manual                     KSH(1)


6       ksh,  rksh  -  KornShell, a standard/restricted command and programming
7       language


10       ksh [ ±abcefhiklmnprstuvxBCDEGH ] [ ±o option ] ... [ - ] [ arg ... ]
11       rksh [ ±abcefhiklmnpstuvxBCDEGH ] [ ±o option ] ... [ - ] [ arg ... ]


14       Ksh is a command and programming language that executes  commands  read
15       from a terminal or a file.  Rksh is a restricted version of the command
16       interpreter ksh; it is used to set up login names and  execution  envi‐
17       ronments whose capabilities are more controlled than those of the stan‐
18       dard shell.  See Invocation below for the meaning of arguments  to  the
19       shell.
21   Definitions.
22       A metacharacter is one of the following characters:
24              ;   &   (   )   |   <   >   new-line   space   tab
26       A  blank  is a tab or a space.  An identifier is a sequence of letters,
27       digits, or underscores starting with a letter or  underscore.   Identi‐
28       fiers  are used as components of variable names.  A vname is a sequence
29       of one or more identifiers separated by a . and optionally preceded  by
30       a  ..  Vnames are used as function and variable names.  A word is a se‐
31       quence of characters from the character set defined by the current  lo‐
32       cale, excluding non-quoted metacharacters.
34       A  command  is a sequence of characters in the syntax of the shell lan‐
35       guage.  The shell reads each command and carries out the desired action
36       either  directly or by invoking separate utilities.  A built-in command
37       is a command that is carried out by the shell itself without creating a
38       separate  process.   Some  commands are built in purely for convenience
39       and are not documented here.  Built-ins that cause side effects in  the
40       shell environment and built-ins that are found before performing a path
41       search (see Execution below) are documented here.  For historical  rea‐
42       sons,  some  of these built-ins behave differently than other built-ins
43       and are called special built-ins.
45   Commands.
46       A simple-command is a list of variable assignments  (see  Variable  As‐
47       signments  below)  or  a sequence of blank separated words which may be
48       preceded by a list of variable  assignments  (see  Environment  below).
49       The  first  word specifies the name of the command to be executed.  Ex‐
50       cept as specified below, the remaining words are passed as arguments to
51       the  invoked  command.   The  command name is passed as argument 0 (see
52       exec(2)).  The value of a simple-command is its exit status;  0-255  if
53       it  terminates  normally;  256+signum  if it terminates abnormally (the
54       name of the signal corresponding to the exit status can be obtained via
55       the -l option of the kill built-in utility).
57       A  pipeline  is a sequence of one or more commands separated by |.  The
58       standard output of each command but the last is connected by a  socket‐
59       pair(2)  or (if the posix shell option is on) by a pipe(2) to the stan‐
60       dard input of the next command.  Each command except the  last  is  run
61       asynchronously  in a subshell (see Subshells below).  If the monitor or
62       pipefail option is on, or the pipeline is preceded by the reserved word
63       time,  then  the shell waits for all component commands in the pipeline
64       to terminate; otherwise, the shell only waits for  the  last  component
65       command.   The exit status of a pipeline is the exit status of its last
66       component command, unless the pipefail option is enabled.   Each  pipe‐
67       line can be preceded by the reserved word !  which causes the exit sta‐
68       tus of the pipeline to become 0 if the exit status of the last  command
69       is non-zero, and 1 if the exit status of the last command is 0.
71       A  list  is  a sequence of one or more pipelines separated by ;, &, |&,
72       &&, or ||, and optionally terminated by ;, &, or  |&.   Of  these  five
73       symbols,  ;,  &, and |& have equal precedence, which is lower than that
74       of && and ||.  The symbols && and || also  have  equal  precedence.   A
75       semicolon (;) causes sequential execution of the preceding pipeline; an
76       ampersand (&) causes asynchronous execution of the  preceding  pipeline
77       (i.e.,  the shell does not wait for that pipeline to finish).  The sym‐
78       bol |& causes asynchronous execution of the preceding pipeline  with  a
79       two-way  pipe  established  to the parent shell; the standard input and
80       output of the spawned pipeline can be written to and read from  by  the
81       parent shell by applying the redirection operators <& and >& with arg p
82       to commands and by using -p option of the built-in  commands  read  and
83       print described later.  The symbol && (||) causes the list following it
84       to be executed only if the preceding pipeline returns a zero (non-zero)
85       value.   One  or more new-lines may appear in a list instead of a semi‐
86       colon, to delimit a command.  The first item  of the first pipeline  of
87       a  list  that is a simple command not beginning with a redirection, and
88       not occurring within a while, until, or if list, can be preceded  by  a
89       semicolon.   This  semicolon is ignored unless the showme option is en‐
90       abled as described with the set built-in below.
92       A command is either a simple-command or a  compound-command,  which  is
93       one of the following.  Unless otherwise stated, the value returned by a
94       command is that of the last simple-command executed in the command.
96       for vname [ in word ... ] ;do list ;done
97              Each time a for command is executed, vname is set  to  the  next
98              word  taken  from the in word list.  If in word ...  is omitted,
99              then the for command executes the do list once  for  each  posi‐
100              tional  parameter that is set starting from 1 (see Parameter Ex‐
101              pansion below).  Execution ends when there are no more words  in
102              the list.
104       for (( [expr1] ; [expr2] ; [expr3] )) ;do list ;done
105              The  arithmetic  expression expr1 is evaluated first (see Arith‐
106              metic Evaluation below).  The arithmetic expression expr2 is re‐
107              peatedly evaluated until it evaluates to zero and when non-zero,
108              list is executed and the arithmetic expression expr3  evaluated.
109              If any expression is omitted, then it behaves as if it evaluated
110              to 1.
112       select vname [ in word ... ] ;do list ;done
113              A select command prints on standard error  (file  descriptor  2)
114              the set of words, each preceded by a number.  If in word ...  is
115              omitted, then the positional parameters starting from 1 are used
116              instead  (see  Parameter  Expansion  below).   The PS3 prompt is
117              printed and a line is read from the  standard  input.   If  this
118              line consists of the number of one of the listed words, then the
119              value of the variable vname is set to the word corresponding  to
120              this  number.   If  this  line  is  empty, the selection list is
121              printed again.  Otherwise the value of the variable vname is set
122              to  the  empty string.  The contents of the line read from stan‐
123              dard input is saved in the variable REPLY.  The list is executed
124              for  each selection until a break or end-of-file is encountered.
125              If the REPLY variable is set to the empty string by  the  execu‐
126              tion of list, then the selection list is printed before display‐
127              ing the PS3 prompt for the next selection.
129       case word in [ [(]pattern [ | pattern ] ... ) list ;; ] ... esac
130              A case command executes the list associated with the first  pat‐
131              tern that matches word.  The form of the patterns is the same as
132              that used for pathname expansion (see Pathname Expansion below).
133              The ;; operator causes execution of case to terminate.  If ;& is
134              used in place of ;; the next subsequent list, if any,   is  exe‐
135              cuted.
137       if list ;then list [ ;elif list ;then list ] ... [ ;else list ] ;fi
138              The list following if is executed and, if it returns a zero exit
139              status, the list following the first then is  executed.   Other‐
140              wise,  the  list following elif is executed and, if its value is
141              zero, the list following the next  then  is  executed.   Failing
142              each successive elif list, the else list is executed.  If the if
143              list has non-zero exit status and there is no  else  list,  then
144              the if command returns a zero exit status.
146       while list ;do list ;done
147       until list ;do list ;done
148              A  while  command repeatedly executes the while list and, if the
149              exit status of the last command in the list  is  zero,  executes
150              the  do  list; otherwise the loop terminates.  If no commands in
151              the do list are executed, then the while command returns a  zero
152              exit  status;  until may be used in place of while to negate the
153              loop termination test.
155       while inputredirection ;do list ;done
156              Filescan loop. This is defined by a lone input redirection  fol‐
157              lowing  while (see Input/Output below).  It is faster than using
158              the read built-in command in a regular while  loop.   The  shell
159              reads  lines  from the file or stream opened by inputredirection
160              until the end is reached or the loop is broken.  For  each  line
161              read,  the command list is executed with the line's contents as‐
162              signed to the REPLY variable and the line's  fields  split  into
163              the  positional  parameters  (see Field Splitting and Positional
164              Parameters below).  Within the list,  standard  input  is  redi‐
165              rected to /dev/null.  If the posix compatibility shell option is
166              on, this loop type is disabled and inputredirection is processed
167              like a lone redirection in any other context.
169       ((expression))
170              The expression is evaluated using the rules for arithmetic eval‐
171              uation described below.  If the value of the arithmetic  expres‐
172              sion  is non-zero, the exit status is 0, otherwise the exit sta‐
173              tus is 1.
175       (list)
176              Execute list in a subshell (see Subshells below).  Note, that if
177              two  adjacent  open  parentheses are needed for nesting, a space
178              must be inserted to avoid evaluation as an arithmetic command as
179              described above.
181       { list;}
182              list  is simply executed.  Note that unlike the metacharacters (
183              and ), { and } are reserved words and must occur at  the  begin‐
184              ning of a line or after a ; in order to be recognized.
186       [[ expression ]]
187              Evaluates expression and returns a zero exit status when expres‐
188              sion is true.  See Conditional Expressions below, for a descrip‐
189              tion of expression.
191       function varname { list ;} [ redirection ... ]
192       varname () compound-command [ redirection ... ]
193              Define  a  function  which is referenced by varname.  A function
194              whose varname contains a .  is called a discipline function  and
195              the  portion  of the varname preceding the last .  must refer to
196              an existing variable.  The body of the function is the  list  of
197              commands  between { and }.  A function defined with the function
198              varname syntax can also be used as an argument to the .  special
199              built-in  command  to get the equivalent behavior as if the var‐
200              name() syntax were used to define it.  (See Functions below.)
202       namespace identifier { list ;}
203              Defines or uses the name space identifier and runs the  commands
204              in list in this name space.  (See Name Spaces below.)
206       time [ pipeline ]
207              If  pipeline is omitted the user and system time for the current
208              shell and completed child processes is printed on  standard  er‐
209              ror.   Otherwise,  pipeline  is executed and the elapsed time as
210              well as the user and system time are printed on standard  error.
211              The TIMEFORMAT variable may be set to a format string that spec‐
212              ifies how the timing information should be displayed.  See Shell
213              Variables below for a description of the TIMEFORMAT variable.
215       The  following reserved words are recognized as reserved only when they
216       are the first word of a command and are not quoted:
218       if then else elif fi case esac for while until do done { } function se‐
219       lect time [[ ]] !
221   Variable Assignments.
222       One  or  more variable assignments can start a simple command or can be
223       arguments to the typeset, enum, export, or  readonly  special  built-in
224       commands  as  well  as  to other declaration commands created as types.
225       The syntax for an assignment is of the form:
227       varname=word
228       varname[word]=word
229              No space is permitted between varname and the = or between = and
230              word.
232       varname=(assign_list)
233              No  space  is permitted between varname and the =.  The variable
234              varname is unset before the assignment.  An assign_list  can  be
235              one of the following:
236                      word ...
237                             Indexed array assignment.
238                      [word]=word ...
239                             Associative  array  assignment.   If  preceded by
240                             typeset -a this will create an indexed array  in‐
241                             stead.
242                      assignment ...
243                             Compound  variable  assignment.   This  creates a
244                             compound variable varname  with  subvariables  of
245                             the  form  varname.name,  where  name is the name
246                             portion of assignment.  The value of varname will
247                             contain  all the assignment elements.  Additional
248                             assignments made to subvariables of varname  will
249                             also  be  displayed  as part of the value of var‐
250                             name.  If no assignments are  specified,  varname
251                             will  be a compound variable allowing subsequence
252                             child elements to be defined.
253                      typeset [options] assignment ...
254                             Nested variable assignment.  Multiple assignments
255                             can  be specified by separating each of them with
256                             a ;.  The previous value is unset before the  as‐
257                             signment.   Other  declaration  commands  such as
258                             readonly, enum, and  other  declaration  commands
259                             can be used in place of typeset.
260                      . filename
261                             Include  the  assignment  commands  contained  in
262                             filename.
264       In addition, a += can be used in place of the = to signify adding to or
265       appending  to  the previous value.  When += is applied to an arithmetic
266       type, word is evaluated as an arithmetic expression and  added  to  the
267       current value.  When applied to a string variable, the value defined by
268       word is appended to the value.  For compound assignments, the  previous
269       value  is not unset and the new values are appended to the current ones
270       provided that the types are compatible.
272       The right hand side of a variable assignment undergoes all  the  expan‐
273       sion  listed below except word splitting, brace expansion, and pathname
274       expansion.  When the left hand side is  an  assignment  is  a  compound
275       variable  and  the  right  hand is the name of a compound variable, the
276       compound variable on the right will be copied or appended to  the  com‐
277       pound variable on the left.
280       A  word beginning with # causes that word and all the following charac‐
281       ters up to a new-line to be ignored.
283   Aliasing.
284       The first word of each command is replaced by the text of an  alias  if
285       an alias for this word has been defined.  An alias name consists of any
286       number of characters excluding metacharacters, quoting characters, file
287       expansion  characters,  parameter  expansion  and  command substitution
288       characters, the characters / and =.  The replacement string can contain
289       any  valid shell script including the metacharacters listed above.  The
290       first word of each command in the replaced text, other  than  any  that
291       are  in  the process of being replaced, will be tested for aliases.  If
292       the last character of the alias value is a blank then the word  follow‐
293       ing the alias will also be checked for alias substitution.  Aliases can
294       be used to redefine built-in commands but cannot be  used  to  redefine
295       the  reserved  words  listed  above.  Aliases can be created and listed
296       with the alias command and can be removed with the unalias command.
298       Aliasing is performed when scripts are read, not while  they  are  exe‐
299       cuted.   Therefore,  for  an alias to take effect, the alias definition
300       command has to be executed before  the  command  which  references  the
301       alias is read.
303       The  following  aliases  are automatically preset when the shell is in‐
304       voked as an interactive shell.  Preset aliases can be  unset  or  rede‐
305       fined.
306                           history=′hist -l′
307                           r=′hist -s′
309   Tilde Expansion.
310       After  alias  substitution is performed, each word is checked to see if
311       it begins with an unquoted .  For tilde expansion, word also refers to
312       the  word  portion  of parameter expansion (see Parameter Expansion be‐
313       low).  If a word is preceded by a tilde, then it is checked up to  a  /
314       to  see  if it matches a user name in the password database (see getpw‐
315       name(3)).  If a match is found, the and the matched  login  name  are
316       replaced  by  the  login directory of the matched user.  If no match is
317       found, the original text is left unchanged.  A by itself, or in front
318       of  a  /,  is  replaced by $HOME, unless the HOME variable is unset, in
319       which case the current user's home directory as configured in the oper‐
320       ating  system is used.  A followed by a + or - is replaced by $PWD or
321       $OLDPWD respectively.
323       In addition, when expanding a variable assignment (see Variable Assign‐
324       ments  above),  tilde  expansion is attempted when the value of the as‐
325       signment begins with a , and when a appears after a  :.   A  :  also
326       terminates a user name following a .
328       The  tilde  expansion mechanism may be extended or modified by defining
329       one of the discipline functions  .sh.tilde.set  or  .sh.tilde.get  (see
330       Functions and Discipline Functions below).  If either exists, then upon
331       encountering a tilde word to expand, that function is called  with  the
332       tilde  word  assigned  to either .sh.value (for the .sh.tilde.set func‐
333       tion) or .sh.tilde (for the .sh.tilde.get function).  Performing  tilde
334       expansion  within  a discipline function will not recursively call that
335       function, but default tilde expansion remains active, so literal tildes
336       should  still  be  quoted where required.  Either function may assign a
337       replacement string to .sh.value.  If this value is non-empty  and  does
338       not  start  with  a , it replaces the default tilde expansion when the
339       function terminates.  Otherwise, the tilde expansion is left unchanged.
341   Subshells.
342       A subshell is a separate execution environment that is a  complete  du‐
343       plicate  of  the  current shell environment, except for two things: all
344       traps are reset to default except those for signals that are being  ig‐
345       nored,  and subshells cannot be interactive (i.e., they have no command
346       prompt).  Changes made within a subshell do not affect the parent envi‐
347       ronment and are lost when the subshell exits.
349       Particular  care should be taken not to confuse a subshell with a newly
350       invoked shell that is merely a child process of the current shell,  and
351       which (unlike a subshell) starts from scratch in terms of variables and
352       functions and may be interactive.  Beware of shell tutorials on the In‐
353       ternet that confuse these.
355       Subshells cannot be created or invoked using any command.  Instead, the
356       following are automatically run in a subshell:
358               •  any command or group of commands enclosed in parentheses;
360               •  command substitutions of the first and third form (see  Com‐
361                  mand Substitution below);
363               •  process substitutions (see Process Substitution below);
365               •  all elements of a pipeline except the last;
367               •  any  command  executed asynchronously (i.e., in a background
368                  process).
370       Creating processes is expensive, so as a  performance  optimization,  a
371       subshell of a non-interactive shell may share the process of its parent
372       environment. Such a subshell is known as a virtual subshell.  Subshells
373       are  virtual unless or until something (such as asynchronous execution,
374       or an attempt to set a process limit using the ulimit built-in command,
375       or  other implementation- or system-defined requirements) makes it nec‐
376       essary to fork(2) it into a separate process.  Barring any bugs in  the
377       shell,  virtual  subshells  should  be indistinguishable from real sub‐
378       shells except by their execution speed and their process ID.   See  the
379       description of the .sh.pid variable below for more information.
381   Command Substitution.
382       The  standard  output  from a command list enclosed in parentheses pre‐
383       ceded by a dollar sign ( $(list) ), or in a brace group preceded  by  a
384       dollar  sign  (  ${ list;} ), or in a pair of grave accents (``) may be
385       used as part or all of a word; trailing new-lines are removed.  In  the
386       second case, the { and } are treated as a reserved words so that { must
387       be followed by a blank and } must appear at the beginning of  the  line
388       or  follow  a  ;.  In the third (obsolete) form, the string between the
389       quotes is processed for special quoting characters before  the  command
390       is  executed (see Quoting below).  The command substitution $(cat file)
391       can be replaced by the equivalent but  faster  $(<file).   The  command
392       substitution $(n<#) will expand to the current byte offset for file de‐
393       scriptor n.  Except for the second form, the command list is run  in  a
394       subshell  so  that  no side effects are possible.  For the second form,
395       the final } will be recognized as a reserved word after any token.
397   Arithmetic Expansion.
398       An arithmetic expression enclosed in double parentheses preceded  by  a
399       dollar  sign  (  $(()) ) is replaced by the value of the arithmetic ex‐
400       pression within the double parentheses.
402   Process Substitution.
403       Each command argument of the form <(list) or >(list) will  run  process
404       list asynchronously connected to some file in /dev/fd if this directory
405       exists, or else a fifo in a temporary directory.  The name of this file
406       will  become  the  argument  to the command.  If the form with > is se‐
407       lected then writing on this file will provide input for list.  If <  is
408       used,  then  the  file passed as an argument will contain the output of
409       the list process.  For example,
411              paste <(cut -f1  file1)  <(cut  -f3  file2)  |  tee  >(process1)
412              >(process2)
414       cuts fields 1 and 3 from the files file1 and file2 respectively, pastes
415       the results together, and  sends  it  to  the  processes  process1  and
416       process2,  as  well  as putting it onto the standard output.  Note that
417       the file, which is passed as an argument to  the  command,  is  a  UNIX
418       pipe(2) so programs that expect to lseek(2) on the file will not work.
420       Process  substitution  of  the form <(list) can also be used with the <
421       redirection operator which causes the output of list to be standard in‐
422       put or the input for whatever file descriptor is specified.
424   Parameter Expansion.
425       A parameter is a variable, one or more digits, or any of the characters
426       *, @, #, ?, -, $, and !.  A variable is denoted by a vname.  To  create
427       a variable whose vname contains a ., a variable whose vname consists of
428       everything before the last . must already  exist.   A  variable  has  a
429       value  and  zero  or more attributes.  Variables can be assigned values
430       and attributes by using the typeset special built-in command.  The  at‐
431       tributes  supported  by  the shell are described later with the typeset
432       special built-in command.  Exported variables pass their attributes  to
433       the  environment  so that a newly invoked ksh that is a child or exec'd
434       process of the current shell will automatically import them, unless the
435       posix shell option is on.
437       The  shell supports both indexed and associative arrays.  An element of
438       an array variable is referenced by a subscript.  A subscript for an in‐
439       dexed  array  is  denoted  by  an arithmetic expression (see Arithmetic
440       Evaluation below) between a [ and a ].  To assign values to an  indexed
441       array, use vname=(value ...) or set -A vname  value ... .  The value of
442       all  non-negative  subscripts  must  be  in  the  range  of  0  through
443       4,194,303.  A negative subscript is treated as an offset from the maxi‐
444       mum current index +1 so that -1 refers to the  last  element.   Indexed
445       arrays  can  be declared with the -a option to typeset.  Indexed arrays
446       need not be declared.  Any reference to a variable with  a  valid  sub‐
447       script is legal and an array will be created if necessary.
449       An  associative array is created with the -A option to typeset.  A sub‐
450       script for an associative array is denoted by a string enclosed between
451       [ and ].
453       Referencing  any array without a subscript is equivalent to referencing
454       the array with subscript 0.
456       The value of a variable may be assigned by writing:
458              vname=value [ vname=value ] ...
460       or
462              vname[subscript]=value [ vname[subscript]=value ] ...
464       Note that no space is allowed before or after the =.
466       Attributes assigned by the typeset special built-in  command  apply  to
467       all  elements of the array.  An array element can be a simple variable,
468       a compound variable or an array variable.  An element of an indexed ar‐
469       ray can be either an indexed array or an associative array.  An element
470       of an associative array can also be either.  To refer to an array  ele‐
471       ment  that  is  part  of an array element, concatenate the subscript in
472       brackets.  For example, to refer to the foobar element of  an  associa‐
473       tive  array  that is defined as the third element of the indexed array,
474       use ${vname[3][foobar]}
476       A nameref is a variable that is a reference  to  another  variable.   A
477       nameref is created with the -n attribute of typeset or with the equiva‐
478       lent nameref command.  The value of the variable at the  time  of  that
479       command  becomes  the  variable  that  will  be referenced whenever the
480       nameref variable is used.  The name of a nameref cannot  contain  a  ..
481       When  a  variable or function name contains a ., and the portion of the
482       name up to the first . matches the name of a nameref, the variable  re‐
483       ferred to is obtained by replacing the nameref portion with the name of
484       the variable referenced by the nameref.  If a nameref is  used  as  the
485       index  of  a for loop, a name reference is established for each item in
486       the list.
488       A nameref provides a convenient way to refer to the variable  inside  a
489       function  whose name is passed as an argument to a function.  For exam‐
490       ple, if the name of a variable is passed as the  first  argument  to  a
491       function, the command typeset -n var=$1 (a.k.a.  nameref var=$1) inside
492       the function causes references and assignments to var to be  references
493       and assignments to the variable whose name has been passed to the func‐
494       tion.  Note that, for this to work, the positional  parameter  must  be
495       assigned directly to the nameref as part of the declaration command, as
496       in the example above; only that idiom can allow one function to  access
497       a  local  variable  of  another.   For instance, typeset -n var; var=$1
498       won't cross that barrier, nor will typeset foo=$1; typeset -n var=foo.
500       If any of the floating point attributes, -E, -F, or -X, or the  integer
501       attribute,  -i,  is  set for vname, then the value is subject to arith‐
502       metic evaluation as described below.
504       Positional parameters, parameters denoted by a number, may be  assigned
505       values with the set special built-in command.  Parameter $0 is set from
506       argument zero when the shell is invoked.
508       The character $ is used to introduce substitutable parameters.
510       ${parameter}
511              The shell reads all the characters from ${ to the matching }  as
512              part  of the same word even if it contains braces or metacharac‐
513              ters.  The value, if any, of the parameter is substituted.   The
514              braces  are  required  when  parameter  is followed by a letter,
515              digit, or underscore that is not to be interpreted  as  part  of
516              its  name,  when the variable name contains a ..  The braces are
517              also required when a variable is subscripted unless it  is  part
518              of an Arithmetic Expression or a Conditional Expression.  If pa‐
519              rameter is one or more digits then it is a positional parameter.
520              A  positional  parameter of more than one digit must be enclosed
521              in braces.  If parameter is * or @, then all the positional  pa‐
522              rameters,  starting  with  $1,  are  substituted (separated by a
523              field separator character).  If an array vname  with  last  sub‐
524              script * @, or for indexed arrays of the form sub1 ..  sub2.  is
525              used, then the value for each of the elements between  sub1  and
526              sub2  inclusive  (or  all  elements for * and @) is substituted,
527              separated by the first character of the value of IFS.
529       ${#parameter}
530              If parameter is * or @, the number of positional  parameters  is
531              substituted.   Otherwise, the length of the value of the parame‐
532              ter is substituted.
534       ${#vname[*]}
535       ${#vname[@]}
536              The number of elements in the array vname is substituted.
538       ${@vname}
539              Expands to the type name (See Type  Variables    below)  or  at‐
540              tributes of the variable referred to by vname.
542       ${!vname}
543              Expands  to the name of the variable referred to by vname.  This
544              will be vname except when vname is a name reference.
546       ${!vname[subscript]}
547              Expands to name of the subscript unless subscript is *,  @.   or
548              of the form sub1 ..  sub2.  When subscript is *, the list of ar‐
549              ray subscripts for vname is generated.  For a variable  that  is
550              not  an array, the value is 0 if the variable is set.  Otherwise
551              it is the empty string.  When subscript is @, same as above, ex‐
552              cept  that  when  used  in  double  quotes, each array subscript
553              yields a separate argument.  When subscript is of the form  sub1
554              ..   sub2  it expands to the list of subscripts between sub1 and
555              sub2 inclusive using the same quoting rules as @.
557       ${!prefix@}
558       ${!prefix*}
559              These both expand to the names of the variables whose names  be‐
560              gin  with prefix.  The expansions otherwise work like $@ and $*,
561              respectively (see under Quoting below).
563       ${parameter:-word}
564              If parameter is set and has a non-empty value,  then  substitute
565              its value; otherwise substitute word.
567       ${parameter:=word}
568              If  parameter is not set or has the empty string value, then set
569              it to word; the value of the parameter is then substituted.  Po‐
570              sitional parameters may not be assigned to in this way.
572       ${parameter:?word}
573              If  parameter  is set and has a non-empty value, then substitute
574              its value; otherwise, print word and exit from the shell (if not
575              interactive).   If  word  is  omitted then a standard message is
576              printed.
578       ${parameter:+word}
579              If parameter is set and has a non-empty  value  then  substitute
580              word; otherwise substitute the empty string.
582       In the above, word is not evaluated unless it is to be used as the sub‐
583       stituted string, so that, in the following  example,  pwd  is  executed
584       only if d is not set or has the empty string value:
586              print ${d:-$(pwd)}
588       If  the colon (:) is omitted from the above expressions, then the shell
589       only checks whether parameter is set or not.
591       ${parameter:offset:length}
592       ${parameter:offset}
593              Expands to the portion of the value of parameter starting at the
594              character (counting from 0) determined by expanding offset as an
595              arithmetic expression and consisting of the number of characters
596              determined  by  the arithmetic expression defined by length.  In
597              the second form, the remainder of the value is used.  If A nega‐
598              tive  offset  counts  backwards from the end of parameter.  Note
599              that one or more blanks is required in front of a minus sign  to
600              prevent  the shell from interpreting the operator as :-.  If pa‐
601              rameter is * or @, or is an array name indexed by * or  @,  then
602              offset  and  length  refer to the array index and number of ele‐
603              ments respectively.  A negative offset is taken relative to  one
604              greater  than the highest subscript for indexed arrays.  The or‐
605              der for associative arrays is unspecified.
607       ${parameter#pattern}
608       ${parameter##pattern}
609              If the shell pattern matches the beginning of the value  of  pa‐
610              rameter,  then  the  value of this expansion is the value of the
611              parameter with the matched portion deleted; otherwise the  value
612              of  this parameter is substituted.  In the first form the small‐
613              est matching pattern is deleted  and  in  the  second  form  the
614              largest matching pattern is deleted.  When parameter is @, *, or
615              an array variable with subscript @ or *, the substring operation
616              is applied to each element in turn.
618       ${parameter%pattern}
619       ${parameter%%pattern}
620              If  the shell pattern matches the end of the value of parameter,
621              then the value of this expansion is the value of  the  parameter
622              with the matched part deleted; otherwise substitute the value of
623              parameter.  In the first form the smallest matching  pattern  is
624              deleted  and  in the second form the largest matching pattern is
625              deleted.  When parameter is @, *, or an array variable with sub‐
626              script  @  or *, the substring operation is applied to each ele‐
627              ment in turn.
629       ${parameter/pattern/string}
630       ${parameter//pattern/string}
631       ${parameter/#pattern/string}
632       ${parameter/%pattern/string}
633              Expands parameter and replaces the longest match of pattern with
634              the  given  string.  Each occurrence of \n in string is replaced
635              by the portion of parameter that matches  the  n-th  subpattern.
636              In  the  first form, only the first occurrence of pattern is re‐
637              placed.  In the second form, each match for pattern is  replaced
638              by the given string.  The third form restricts the pattern match
639              to the beginning of the string while the fourth  form  restricts
640              the  pattern  match  to the end of the string.  In the first and
641              second forms, an empty pattern never matches.  In the third  and
642              fourth  forms, an empty pattern matches the beginning or the end
643              of the string, respectively.  When string is empty, the  pattern
644              will  be  deleted  and  the / in front of string may be omitted.
645              When parameter is @, *, or an array variable with subscript @ or
646              *,  the  substitution  operation  is  applied to each element in
647              turn.  In this case, the string portion of word will be re-eval‐
648              uated for each element.
650   Shell Variables.
651       The following parameters are automatically set by the shell:
652              #      The number of positional parameters in decimal.
654              -      Options supplied to the shell on invocation or by the set
655                     command.
657              ?      The exit status returned by the  last  executed  command.
658                     Its  meaning  depends on the command or function that de‐
659                     fines it, but there are conventions that  other  commands
660                     often  depend  on:  zero  typically  means  'success'  or
661                     'true', one typically means 'non-success' or 'false', and
662                     a value greater than one typically indicates some kind of
663                     error. Only the 8 least significant bits of $? (values  0
664                     to  255)  are preserved when the exit status is passed on
665                     to a parent process, but within the same (sub)shell envi‐
666                     ronment,  it  is  a  signed integer value with a range of
667                     possible values as shown by the commands getconf  INT_MIN
668                     and getconf INT_MAX. Shell functions that run in the cur‐
669                     rent environment may return status values in this range.
671              $      The process ID of the main shell process. Note that  this
672                     value will not change in a subshell, even if the subshell
673                     runs in a different process.  See also .sh.pid.
675              _      Initially, the value of _ is an absolute pathname of  the
676                     shell  or script being executed as passed in the environ‐
677                     ment.  Subsequently it is assigned the last  argument  of
678                     the previous command.  This parameter is not set for com‐
679                     mands which are asynchronous.   This  parameter  is  also
680                     used  to  hold  the  name  of the matching MAIL file when
681                     checking for mail.  While defining a compound variable or
682                     a  type,  _ is initialized as a reference to the compound
683                     variable or type.  When a discipline function is invoked,
684                     _  is  initialized as a reference to the variable associ‐
685                     ated with the call to this function.  Finally when  _  is
686                     used  as the name of the first variable of a type defini‐
687                     tion, the new type is derived from the type of the  first
688                     variable. (See Type Variables  below.)
690              !      The  process ID of the last background command invoked or
691                     the most recent job put in the  background  with  the  bg
692                     built-in command.
694              .sh.command
695                     When  processing a DEBUG trap, this variable contains the
696                     current command line that is about to run.  The value  is
697                     in  the same format as the output generated by the xtrace
698                     option (minus the preceding PS4 prompt).
700              .sh.edchar
701                     This variable contains the value of the keyboard  charac‐
702                     ter  (or sequence of characters if the first character is
703                     an ESC, ASCII 033) that has been entered when  processing
704                     a  KEYBD  trap (see Key Bindings below).  If the value is
705                     changed as part of the trap action, then  the  new  value
706                     replaces the key (or key sequence) that caused the trap.
708              .sh.edcol
709                     The  character  position of the cursor at the time of the
710                     most recent KEYBD trap.
712              .sh.edmode
713                     Upon executing a KEYBD trap action,  the  value  of  this
714                     variable is set to the ESC control character if the shell
715                     is in vi input mode (See Vi Editing Mode  below),  or  to
716                     the empty string value otherwise.
718              .sh.edtext
719                     The  characters  in  the  input buffer at the time of the
720                     most recent KEYBD trap.  The variable is unset  when  not
721                     processing a KEYBD trap.
723              .sh.file
724                     The  pathname  of the file that contains the current com‐
725                     mand.
727              .sh.fun
728                     The name of the current function that is being executed.
730              .sh.level
731                     Set to the  current  call  depth  of  functions  and  dot
732                     scripts.  Normally, this variable is read-only, but while
733                     executing a DEBUG trap,  its  value  may  be  changed  to
734                     switch  the  current function scope to that of the speci‐
735                     fied level for the duration of the trap  run,  making  it
736                     possible to access a parent scope for debugging purposes.
737                     When trap execution ends, the variable and the scope  are
738                     restored.   It is an error to assign a value lower than 0
739                     (the global scope) or higher than the current call depth.
741              .sh.lineno
742                     Set during a DEBUG trap to the line number for the caller
743                     of each function.
745              .sh.match
746                     Whenever a match is found in a pattern matching operation
747                     using either the [[ compound command (see Conditional Ex‐
748                     pressions  below) or the expansions ${parameter#pattern},
749                     ${parameter%pattern}, ${parameter/pattern/string}, or one
750                     of  their  variants  (see Parameter Expansion above), the
751                     match and its subpattern matches are stored in  this  in‐
752                     dexed  array,  overwriting its previous values.  The 0-th
753                     element stores the complete match and  the  i-th  element
754                     stores  the  i-th submatch.  For //, the array is two-di‐
755                     mensional, with the first subscript indicating  the  most
756                     recent  match  and  subpattern match, and the second sub‐
757                     script indicating which match  with  0  representing  the
758                     first  match.  If no match is found, .sh.match is not re‐
759                     set or modified.  Note that even matching operations per‐
760                     formed on the .sh.match variable itself will overwrite it
761                     upon finding a match.
763              .sh.math
764                     Used for defining arithmetic  functions  (see  Arithmetic
765                     Evaluation  below)  and  stores  the list of user defined
766                     arithmetic functions.
768              .sh.name
769                     Set to the name of the variable at the time that a disci‐
770                     pline function is invoked.
772              .sh.subscript
773                     Set  to  the  name  subscript of the variable at the time
774                     that a discipline function is invoked.
776              .sh.subshell
777                     The current depth for subshells and command substitution.
779              .sh.pid
780                     Set to the process ID of the current shell process.   Un‐
781                     like $$, this is updated in a subshell when it forks into
782                     a new process.  Note that a virtual subshell may have  to
783                     fork mid-execution due to various system- and implementa‐
784                     tion-dependent requirements, so the value should  not  be
785                     counted  on  to  remain  the same from one command to the
786                     next.  If a persistent process ID is required for a  sub‐
787                     shell,  it  must  be  ensured  it  is  running in its own
788                     process first.  Any attempt to set a process limit  using
789                     the  ulimit built-in command, such as ulimit -t unlimited
790                     2>/dev/null, is a reliable way to make a subshell fork if
791                     it hasn't already.
793              .sh.ppid
794                     Set  to the process ID of the parent of the current shell
795                     process.  Unlike $PPID, this is  updated  in  a  subshell
796                     when  it  forks into a new process.  The same note as for
797                     .sh.pid applies.
799              .sh.value
800                     Set to the value of the variable at the time that the set
801                     or  append  discipline  function is invoked.  When a user
802                     defined arithmetic function  is  invoked,  the  value  of
803                     .sh.value  is  saved  and .sh.value is set to long double
804                     precision floating point.  .sh.value is restored when the
805                     function returns.
807              .sh.version
808                     Set to a value that identifies the version of this shell.
810              COLUMNS
811                     Width of the terminal window in character positions.  Up‐
812                     dated automatically at initialization and on receiving  a
813                     SIGWINCH  signal.  The shell uses the value to define the
814                     width of the edit window for the shell edit modes and for
815                     printing select lists.
817              KSH_VERSION
818                     A name reference to .sh.version.
820              LINENO The current line number within the script or function be‐
821                     ing executed.
823              LINES  Height of the terminal window in lines.  Updated automat‐
824                     ically at initialization and on receiving a SIGWINCH sig‐
825                     nal.  The shell uses the value to  determine  the  column
826                     length for printing select lists: they are printed verti‐
827                     cally until about two thirds of LINES lines are filled.
829              OLDPWD The previous working directory set by the cd command.
831              OPTARG The value of the last option argument  processed  by  the
832                     getopts built-in command.
834              OPTIND The  index  of  the last option argument processed by the
835                     getopts built-in command.
837              PPID   The process ID of the parent of the main  shell  process.
838                     Note  that this value will not change in a subshell, even
839                     if the subshell runs in a different  process.   See  also
840                     .sh.ppid.
842              PWD    The present working directory set by the cd command.
844              RANDOM Each  time this variable is referenced, a random integer,
845                     uniformly distributed between 0 and 32767, is  generated.
846                     The  sequence of random numbers can be initialized by as‐
847                     signing a numeric value to RANDOM.
849              REPLY  This variable is set by the select statement and  by  the
850                     read built-in command when no arguments are supplied.
852              SECONDS
853                     Each time this variable is referenced, the number of sec‐
854                     onds since shell invocation is returned.  If  this  vari‐
855                     able  is  assigned  a value, then the value returned upon
856                     reference will be the value that was  assigned  plus  the
857                     number of seconds since the assignment.
859              SHLVL  An integer variable that is incremented and exported each
860                     time the shell is invoked.  If SHLVL is not in the  envi‐
861                     ronment when the shell is invoked, it is set to 1.
863       The following variables are used by the shell:
864              CDPATH The search path for the cd command.
866              EDITOR If  the  VISUAL  variable  is  not set, the value of this
867                     variable will be checked for  certain  patterns  and  the
868                     corresponding  editing  option  will  be turned on as de‐
869                     scribed with VISUAL below.
871              ENV    If this variable is set, then parameter  expansion,  com‐
872                     mand substitution, and arithmetic expansion are performed
873                     on the value to generate the pathname of the script  that
874                     will  be executed when the shell is invoked interactively
875                     (see Invocation below).  This file is typically used  for
876                     alias  and  function  definitions.   The default value is
877                     $HOME/.kshrc.  On systems  that  support  a  system  wide
878                     /etc/ksh.kshrc  initialization file, if the filename gen‐
879                     erated by the expansion of ENV begins with  /./  or  ././
880                     the system wide initialization file will not be executed.
882              FCEDIT Obsolete  name  for  the default editor name for the hist
883                     command.  FCEDIT is not used when HISTEDIT is set.
885              FIGNORE
886                     A pattern that defines the set of filenames that will  be
887                     ignored when performing filename matching.
889              FPATH  The  search  path for function definitions.  The directo‐
890                     ries in this path are searched for a file with  the  same
891                     name  as the function or command when a function with the
892                     -u attribute is referenced and  when  a  command  is  not
893                     found.   If an executable file with the name of that com‐
894                     mand is found, then it is read and executed in  the  cur‐
895                     rent  environment.   Unlike  PATH,  the current directory
896                     must be represented explicitly by .  rather than by adja‐
897                     cent : characters or a beginning or ending :.
899              histchars
900                     This  variable  can  be used to specify up to three ASCII
901                     characters that control history  expansion  (see  History
902                     Expansion  below).   The  first  (default: !) signals the
903                     start of a history expansion.  The second (default: ^) is
904                     used  for  short-form substitutions.  The third (default:
905                     #), when found as the first character of a  word,  causes
906                     history expansion to be skipped for the rest of the words
907                     on the line.  Multi-byte characters (e.g. UTF-8) are  not
908                     supported and produce undefined results.
910              HISTCMD
911                     Number of the current command in the history file.
913              HISTEDIT
914                     Name for the default editor name for the hist command.
916              HISTFILE
917                     If  this  variable is set when the shell is invoked, then
918                     the value is the pathname of the file that will  be  used
919                     to  store  the  command history (see Command Re-entry be‐
920                     low).
922              HISTSIZE
923                     If this variable is set when the shell is  invoked,  then
924                     the number of previously entered commands that are acces‐
925                     sible by this shell will be greater than or equal to this
926                     number.  The default is 512.
928              HOME   The default argument (home directory) for the cd command.
930              IFS    Internal  field separators, normally space, tab, and new-
931                     line that are used to separate  the  results  of  command
932                     substitution  or  parameter  expansion  and  to  separate
933                     fields with the built-in command read.  The first charac‐
934                     ter of the IFS variable is used to separate arguments for
935                     the "$*" expansion (see Quoting below).  Each single  oc‐
936                     currence  of  an  IFS character in the string to be split
937                     that is not in the isspace character class, and any adja‐
938                     cent  characters in IFS that are in the isspace character
939                     class, delimit a field.  One or more  characters  in  IFS
940                     that  belong  to  the  isspace  character class delimit a
941                     field.  In addition, if the same  isspace  character  ap‐
942                     pears consecutively inside IFS and the posix shell option
943                     is not on, this character is treated as if it were not in
944                     the  isspace  class - for example, if IFS consists of two
945                     tab characters, then two adjacent tab characters  delimit
946                     an empty field.
948              JOBMAX This  variable  defines  the maximum number running back‐
949                     ground jobs that can run at a time.  When this  limit  is
950                     reached, the shell will wait for a job to complete before
951                     starting a new job.
953              LANG   This variable determines the locale category for any cat‐
954                     egory  not specifically selected with a variable starting
955                     with LC_ or LANG.
957              LC_ALL This variable overrides the value of  the  LANG  variable
958                     and any other LC_ variable.
960              LC_COLLATE
961                     This  variable determines the locale category for charac‐
962                     ter collation information.
964              LC_CTYPE
965                     This variable determines the locale category for  charac‐
966                     ter  handling  functions.   It  determines  the character
967                     classes for pattern matching (see Pathname Expansion  be‐
968                     low).
970              LC_NUMERIC
971                     This variable determines the locale category for the dec‐
972                     imal point character.
974              MAIL   If this variable is set to the name of a  mail  file  and
975                     the  MAILPATH variable is not set, then the shell informs
976                     the user of arrival of mail in the specified file.
978              MAILCHECK
979                     This variable specifies how often (in seconds) the  shell
980                     will check for changes in the modification time of any of
981                     the files specified by the MAILPATH  or  MAIL  variables.
982                     The  default  value  is  600  seconds.  When the time has
983                     elapsed the shell will  check  before  issuing  the  next
984                     prompt.
986              MAILPATH
987                     A  colon  (  :  )  separated list of file names.  If this
988                     variable is set, then the shell informs the user  of  any
989                     modifications  to  the specified files that have occurred
990                     within the last MAILCHECK seconds.  Each file name can be
991                     followed by a ?  and a message that will be printed.  The
992                     message will undergo parameter expansion, command substi‐
993                     tution, and arithmetic expansion with the variable $_ de‐
994                     fined as the name of the file that has changed.  The  de‐
995                     fault message is you have mail in $_.
997              PATH   The  search path for commands (see Execution below).  The
998                     user may not change PATH if executing under rksh  (except
999                     in .profile).
1001              PS1    Every  time  a new command line is started on an interac‐
1002                     tive shell, the value of this variable is expanded to re‐
1003                     solve  backslash  escaping,  parameter expansion, command
1004                     substitution, and arithmetic expansion.  The  result  de‐
1005                     fines  the  primary  prompt string for that command line.
1006                     The default is ``$ ''.  The character !  in  the  primary
1007                     prompt string is replaced by the command number (see Com‐
1008                     mand Re-entry below).  Two successive  occurrences  of  !
1009                     will  produce  a  single  !   when  the  prompt string is
1010                     printed.  Note that any terminal escape sequences used in
1011                     the  PS1 prompt thus need every instance of !  in them to
1012                     be changed to !!.
1014              PS2    Secondary prompt string, by default ``> ''.
1016              PS3    Selection prompt string used within a select loop, by de‐
1017                     fault ``#? ''.
1019              PS4    The  value  of  this  variable  is expanded for parameter
1020                     evaluation, command substitution, and  arithmetic  expan‐
1021                     sion  and  precedes  each line of an execution trace.  By
1022                     default, PS4 is ``+ ''.  In addition when PS4  is  unset,
1023                     the execution trace prompt is also ``+ ''.
1025              SHELL  The pathname of the shell is kept in the environment.  At
1026                     invocation, if the basename  of  this  variable  is  rsh,
1027                     rksh, or krsh, then the shell becomes restricted.
1029              TIMEFORMAT
1030                     The  value  of  this parameter is used as a format string
1031                     specifying how the timing information for pipelines  pre‐
1032                     fixed  with  the  time reserved word should be displayed.
1033                     The % character introduces a format sequence that is  ex‐
1034                     panded  to a time value or other information.  The format
1035                     sequences and their meanings are as follows.
1036                     %%        A literal %.
1037                     %[p][l]R  The elapsed time in seconds.
1038                     %[p][l]U  The number of CPU seconds spent in user mode.
1039                     %[p][l]S  The number of CPU seconds spent in system mode.
1040                     %P        The CPU percentage, computed as (U + S) / R.
1042                     The brackets denote optional portions.  The optional p is
1043                     a  digit  specifying  the  precision, the number of frac‐
1044                     tional digits after a decimal point.  A value of 0 causes
1045                     no decimal point or fraction to be output.  At most three
1046                     places after the decimal point can be  displayed;  values
1047                     of p greater than 3 are treated as 3.  If p is not speci‐
1048                     fied, the value 3 is used.
1050                     The optional l specifies a longer format, including hours
1051                     if  greater  than  zero, minutes, and seconds of the form
1052                     HHhMMmSS.FFs.  The value of p determines whether  or  not
1053                     the fraction is included.  Seconds are zero-padded unless
1054                     the posix shell option is on.
1056                     All other characters are  output  without  change  and  a
1057                     trailing newline is added.  If the variable is unset, the
1058                     default value, $'\nreal\t%2lR\nuser\t%2lU\nsys\t%2lS', is
1059                     used.   If  the  value is empty, no timing information is
1060                     displayed.
1062              TMOUT  Terminal read timeout. If set to  a  value  greater  than
1063                     zero,  the  read built-in command and the select compound
1064                     command time out after TMOUT seconds when input is from a
1065                     terminal.   An interactive shell will issue a warning and
1066                     allow for an extra 60 second timeout grace period  before
1067                     terminating  if  a  line  is  not entered within the pre‐
1068                     scribed number of seconds while reading from a  terminal.
1069                     (Note that the shell can be compiled with a maximum bound
1070                     for this value which cannot be exceeded.)
1072              VISUAL The value of this variable is scanned when the  shell  is
1073                     invoked and whenever its value is changed; if it is found
1074                     to match certain patterns, the corresponding line  editor
1075                     (see  In-line Editing Options below) is activated.  If it
1076                     matches the pattern *[Vv][Ii]*, the vi option  is  turned
1077                     on; else if it matches the pattern *gmacs*, the gmacs op‐
1078                     tion is turned on; else if it matches the pattern *macs*,
1079                     the  emacs  option is turned on.  If none of the patterns
1080                     match, emacs is turned on by default upon initializing an
1081                     interactive shell.  If the value is changed by assignment
1082                     and none of the patterns match, no options  are  changed.
1083                     The value of VISUAL overrides the value of EDITOR.
1085       The  shell gives default values to PATH, PS1, PS2, PS3, PS4, MAILCHECK,
1086       FCEDIT, TMOUT and IFS, while HOME, SHELL, ENV, histchars, and MAIL  are
1087       not  set  at  all  by the shell (although HOME is set by login(1)).  On
1088       some systems MAIL and SHELL are also set by login(1).
1090   Field Splitting.
1091       After parameter expansion and command substitution, the results of sub‐
1092       stitutions  are scanned for the field separator characters (those found
1093       in IFS) and split into distinct fields where such characters are found.
1094       Explicit  empty  fields ("" or ′′) are retained.  Implicit empty fields
1095       (those resulting from parameters that are unset or  have  empty  string
1096       values  or  from  command  substitutions yielding the empty string, and
1097       that are not quoted with "") are removed.
1099   Brace Expansion.
1100       If the braceexpand (-B) option is set then each word, as  well  as  any
1101       fields  resulting  from field splitting (see above), are checked to see
1102       if they contain one or more of the brace  patterns  {*,*},  {l1..l2}  ,
1103       {n1..n2} , {n1..n2% fmt} , {n1..n2 ..n3} , or {n1..n2 ..n3%fmt} , where
1104       * represents any character, l1,l2 are letters and n1,n2,n3  are  signed
1105       numbers and fmt is a format specified as used by printf.  In each case,
1106       fields are created by prepending the characters before the  {  and  ap‐
1107       pending  the characters after the } to each of the strings generated by
1108       the characters between the { and }.  The resulting fields  are  checked
1109       to see if they have any brace patterns.
1111       In  the first form, a field is created for each string between { and ,,
1112       between , and ,, and between , and }.  The string represented by *  can
1113       contain  embedded  matching { and } without quoting.  Otherwise, each {
1114       and } with * must be quoted.
1116       In the seconds form, l1 and l2 must both be either upper case  or  both
1117       be lower case characters in the C locale.  In this case a field is cre‐
1118       ated for each character from l1 through l2.
1120       In the remaining forms, a field is created for each number starting  at
1121       n1 and continuing until it reaches n2 incrementing n1 by n3.  The cases
1122       where n3 is not specified behave as if n3 where 1 if n1<=n2 and -1 oth‐
1123       erwise.   If forms which specify %fmt any format flags, widths and pre‐
1124       cisions can be specified and fmt can  end  in  any  of  the  specifiers
1125       cdiouxX.   For  example,  {a,z}{1..5..3%02d}{b..c}x  expands  to  the 8
1126       fields, a01bx, a01cx, a04bx, a04cx, z01bx, z01cx, z04bx and z04cx.
1128   Pathname Expansion.
1129       This is also known as globbing or sometimes filename generation.  Path‐
1130       name  expansion  is disabled if the -f a.k.a.  --noglob shell option is
1131       on.  Otherwise, if certain special characters are found in a word or in
1132       a  field  resulting  from field splitting (see above), then the word or
1133       field is regarded as a pattern.  Each literal word is scanned  for  the
1134       characters  *,  ?,  [, and (, but fields resulting from field splitting
1135       are scanned only for the characters *, ?, and [ for compatibility  rea‐
1136       sons (in which case the ( character is not special and any pattern syn‐
1137       tax described below that involves parentheses does not apply).
1139       Each file name component that contains a recognized  pattern  character
1140       is  replaced  with a lexicographically sorted set of names that matches
1141       the pattern from that directory.  If no file name is found that matches
1142       the  pattern, then that component of the filename is left unchanged un‐
1143       less the pattern is prefixed with ∼(N), in which case it is removed  as
1144       described  below.   The  special  traversal  names .  and ..  are never
1145       matched.  If FIGNORE is set, then each file name component that matches
1146       the  pattern defined by the value of FIGNORE is ignored when generating
1147       the matching filenames.  If FIGNORE is not set, the character .  at the
1148       start  of  each  file  name  component will be ignored unless the first
1149       character of the pattern corresponding to this component is the charac‐
1150       ter  .   itself.   Note  that,  for uses of pattern matching other than
1151       pathname expansion, the / and .  are not treated specially.
1153              *      Matches any string, including  the  empty  string.   When
1154                     used  for  filename  expansion, if the globstar option is
1155                     on, an isolated pattern of two adjacent *s will match all
1156                     files  and  zero  or more directories and subdirectories.
1157                     If followed by a / then only directories and  subdirecto‐
1158                     ries will match.
1159              ?      Matches any single character.
1160              [...]  Matches  any  one  of the enclosed characters.  A pair of
1161                     characters separated by - matches any character lexically
1162                     between the pair, inclusive.  If the first character fol‐
1163                     lowing the opening [ is a !  or ^, then any character not
1164                     enclosed  is matched.  A - can be included in the charac‐
1165                     ter set by putting it as the first or last character.
1166                     Within [ and ], character classes can be  specified  with
1167                     the syntax [:class:], where class is one of the following
1168                     classes defined in the ANSI C standard (note that word is
1169                     equivalent to alnum plus the character _):
1170                     alnum  alpha  blank  cntrl  digit graph lower print punct
1171                     space upper word xdigit
1172                     Within [ and ], an equivalence  class  can  be  specified
1173                     with  the  syntax [=c=] which matches all characters with
1174                     the same primary collation weight (as defined by the cur‐
1175                     rent  locale) as the character c.  Within [ and ], [.sym‐
1176                     bol.]  matches the collating symbol symbol.
1178       A pattern-list is a list of one or more patterns  separated  from  each
1179       other  with  a & or |.  A & signifies that all patterns must be matched
1180       whereas | requires that only one pattern be  matched.   Composite  pat‐
1181       terns can be formed with one or more of the following subpatterns:
1182              ?(pattern-list)
1183                     Optionally matches any one of the given patterns.
1184              *(pattern-list)
1185                     Matches zero or more occurrences of the given patterns.
1186              +(pattern-list)
1187                     Matches one or more occurrences of the given patterns.
1188              {n}(pattern-list)
1189                     Matches n occurrences of the given patterns.
1190              {m,n}(pattern-list)
1191                     Matches  from  m  to n occurrences of the given patterns.
1192                     If m is omitted, 0 will be used.  If  n  is  omitted,  at
1193                     least m occurrences will be matched.
1194              @(pattern-list)
1195                     Matches exactly one of the given patterns.
1196              !(pattern-list)
1197                     Matches anything except one of the given patterns.
1199       By  default,  each  pattern or subpattern will match the longest string
1200       possible consistent with generating the longest overall match.  If more
1201       than  one  match is possible, the one starting closest to the beginning
1202       of the string will be chosen.   However, for each of the above compound
1203       patterns,  a  - can be inserted in front of the ( to cause the shortest
1204       match to the specified pattern-list to be used.
1206       When pattern-list is contained within parentheses, the backslash  char‐
1207       acter  \ is treated specially even when inside a character class.   All
1208       ANSI C character escapes are recognized and match the specified charac‐
1209       ter.  In addition, the following escape sequences are recognized:
1210              \d     Matches any character in the digit class.
1211              \D     Matches any character not in the digit class.
1212              \s     Matches any character in the space class.
1213              \S     Matches any character not in the space class.
1214              \w     Matches any character in the word class.
1215              \W     Matches any character not in the word class.
1217       A  pattern  of  the form %(pattern-pair(s)) is a subpattern that can be
1218       used to match nested character expressions.   Each  pattern-pair  is  a
1219       two-character  sequence that cannot contain & or |.  The first pattern-
1220       pair specifies the starting and ending characters for the match.   Each
1221       subsequent  pattern-pair represents the beginning and ending characters
1222       of a nested group that will be skipped over when counting starting  and
1223       ending  character  matches.  The behavior is unspecified when the first
1224       character of a pattern-pair is alphanumeric, except for the following:
1225              D      Causes the ending character to terminate the  search  for
1226                     this pattern without finding a match.
1227              E      Causes  the  ending character to be interpreted as an es‐
1228                     cape character.
1229              L      Causes the ending character to be interpreted as a  quote
1230                     character,  causing  all  characters  to  be ignored when
1231                     looking for a match.
1232              Q      Causes the ending character to be interpreted as a  quote
1233                     character,  causing  all characters other than any escape
1234                     character to be ignored when looking for a match.
1236       Thus, %({}Q"E\), matches characters starting at { until the matching  }
1237       is found, not counting any { or } that is inside a double-quoted string
1238       or preceded by the escape character \.  Without the  {},  this  pattern
1239       matches any C language string.
1241       Each  subpattern  in a composite pattern is numbered, starting at 1, by
1242       the location of the ( within the pattern.  The sequence \n, where n  is
1243       a  single digit and \n comes after the nth subpattern, matches the same
1244       string as the subpattern itself.
1246       Finally, a pattern can contain subpatterns of the  form  ∼(options:pat‐
1247       tern-list),  where either options or :pattern-list can be omitted.  Un‐
1248       like the other compound patterns, these subpatterns are not counted  in
1249       the numbered subpatterns.  :pattern-list must be omitted for options E,
1250       F, G, N, P, V, and X below.  If options is present, it can  consist  of
1251       one or more of the following:
1252              +      Enable the following options.  This is the default.
1253              -      Disable the following options.
1254              E      The  remainder  of  the pattern uses extended regular ex‐
1255                     pression syntax like the -E option of  the  grep(1)  com‐
1256                     mand.
1257              F      The  remainder of the pattern uses the fixed pattern syn‐
1258                     tax of the -F option of the grep(1) command.
1259              G      The remainder of the pattern uses basic  regular  expres‐
1260                     sion syntax like the grep(1) command without options.
1261              K      The  remainder  of the pattern uses shell pattern syntax.
1262                     This is the default.
1263              N      When it is the first letter and is used with pathname ex‐
1264                     pansion,  and  no matches occur, the file pattern expands
1265                     to the empty  string  instead  of  remaining  unexpanded.
1266                     Otherwise, it is ignored.
1267              X      The  remainder  of the pattern uses augmented regular ex‐
1268                     pression syntax like the -X option of the AT&T  AST  ver‐
1269                     sion of the grep(1) command.
1270              P      The remainder of the pattern uses perl(1) regular expres‐
1271                     sion syntax.  Not all perl regular expression  syntax  is
1272                     currently implemented.
1273              V      The  remainder  of  the pattern uses System V regular ex‐
1274                     pression syntax.
1275              i      Always treat the match as case-insensitive, regardless of
1276                     the globcasedetect shell option.
1277              g      File the longest match (greedy).  This is the default.
1278              l      Left-anchor the pattern.  This is the default for K style
1279                     patterns.
1280              r      Right-anchor the pattern.  This  is  the  default  for  K
1281                     style patterns.
1283       If both options and :pattern-list are specified, then the options apply
1284       only to  pattern-list.  Otherwise, these options remain in effect until
1285       they  are  disabled by a subsequent ∼(...) or at the end of the subpat‐
1286       tern containing ∼(...).
1288   Quoting.
1289       Each of the metacharacters listed earlier (see Definitions above) has a
1290       special  meaning  to  the shell and causes termination of a word unless
1291       quoted.  A character may be quoted (i.e., made to stand for itself)  by
1292       preceding  it with a \.  The pair \new-line is removed.  All characters
1293       enclosed between a pair of single quote marks (′′) that is not preceded
1294       by  a  $  are  quoted.   A single quote cannot appear within the single
1295       quotes.  A single quoted string preceded by an unquoted $ is  processed
1296       as an ANSI C string except for the following:
1297              \0     Causes the remainder of the string to be ignored.
1298              \E     Equivalent to the escape character (ASCII 033),
1299              \e     Equivalent to the escape character (ASCII 033),
1300              \cx    Expands to the character control-x.
1301              \C[.name.]
1302                     Expands to the collating element name.
1304       Inside  double quote marks (""), parameter and command substitution oc‐
1305       cur and \ quotes the characters \, `, ", and $.  A $ in front of a dou‐
1306       ble quoted string will be ignored in the "C" or "POSIX" locale, and may
1307       cause the string to be replaced by a locale specific string  otherwise.
1308       The meaning of $* and $@ is identical when not quoted or when used as a
1309       variable assignment value or as a file name.  However, when used  as  a
1310       command  argument,  "$*"  is  equivalent to "$1d$2d...", where d is the
1311       first character of the IFS variable, whereas "$@" is equivalent to "$1"
1312       "$2" ....  Inside grave quote marks (``), \ quotes the characters \, `,
1313       and $.  If the grave quotes occur within double  quotes,  then  \  also
1314       quotes the character ".
1316       The  special  meaning  of  reserved  words or aliases can be removed by
1317       quoting any character of the reserved word.  The recognition  of  func‐
1318       tion  names or built-in command names listed below cannot be altered by
1319       quoting them.
1321   Arithmetic Evaluation.
1322       The shell performs arithmetic evaluation for arithmetic  expansion,  to
1323       evaluate an arithmetic command, to evaluate an indexed array subscript,
1324       and to evaluate arguments to the built-in commands  shift  and  let  as
1325       well  as  arguments to numeric format specifiers given to print -f  and
1326       printf.  Evaluations are  performed  using  double  precision  floating
1327       point  arithmetic  or  long double precision floating point for systems
1328       that provide this data type.  Floating point constants follow the  ANSI
1329       C  programming  language floating point conventions.  The case-insensi‐
1330       tive floating point constants NaN and Inf can be used to represent "not
1331       a  number"  and infinity respectively, unless the posix shell option is
1332       on.  Integer constants follow the ANSI C programming  language  integer
1333       constant  conventions although only single byte character constants are
1334       recognized and character casts are not recognized.   In  addition  con‐
1335       stants  can  be of the form [base#]n where base is a decimal number be‐
1336       tween two and sixty-four representing the arithmetic base and  n  is  a
1337       number  in  that base.  The digits above 9 are represented by the lower
1338       case letters, the upper case letters, @, and _ respectively.  For bases
1339       less  than  or equal to 36, upper and lower case characters can be used
1340       interchangeably.
1342       An arithmetic expression uses the same syntax, precedence, and associa‐
1343       tivity  of  expression as the C language.  All the C language operators
1344       that apply to floating point quantities can be used.  In addition,  the
1345       operator  **  can be used for exponentiation.  It has higher precedence
1346       than multiplication and is left associative.   In  addition,  when  the
1347       value  of an arithmetic variable or subexpression can be represented as
1348       a long integer, all C language integer  arithmetic  operations  can  be
1349       performed.   Variables  can  be referenced by name within an arithmetic
1350       expression without using the parameter expansion syntax.  When a  vari‐
1351       able is referenced, its value is evaluated as an arithmetic expression.
1353       Any  of the following math library functions that are in the C math li‐
1354       brary can be used within an arithmetic expression:
1356       abs acos acosh asin asinh atan atan2 atanh cbrt ceil copysign cos  cosh
1357       erf  erfc  exp  exp10  exp2 expm1 fabs fdim finite float floor fma fmax
1358       fmin fmod fpclass fpclassify hypot ilogb  int  isfinite  isgreater  is‐
1359       greaterequal  isinf  isinfinite  isless islessequal islessgreater isnan
1360       isnormal issubnormal isunordered iszero j0 j1 jn ldexp lgamma log log10
1361       log1p log2 logb nearbyint nextafter nexttoward pow remainder rint round
1362       scalb scalbn signbit sin sinh sqrt tan tanh tgamma trunc y0 y1 yn
1364       In addition, arithmetic functions can be  defined  as  shell  functions
1365       with a variant of the function name syntax,
1367       function .sh.math.name ident ... { list ;}
1368              where  name  is the function name used in the arithmetic expres‐
1369              sion and each identifier, ident is a name reference to the  long
1370              double   precision   floating  point  argument.   The  value  of
1371              .sh.value when the function returns is the value of  this  func‐
1372              tion.   User  defined  functions  can take up to 3 arguments and
1373              override C math library functions.
1375       An internal representation of a variable as a double precision floating
1376       point can be specified with the -E [n], -F [n], or -X [n] option of the
1377       typeset special built-in command.  The -E option causes  the  expansion
1378       of the value to be represented using scientific notation when it is ex‐
1379       panded.  The optional option argument n defines the number of  signifi‐
1380       cant  figures.  The -F option causes the expansion to be represented as
1381       a floating decimal number when it is expanded.  The  -X  option  causes
1382       the  expansion  to  be  represented  using the %a format defined by ISO
1383       C-99.  The optional option argument n defines the number of places  af‐
1384       ter the decimal (or radix) point in this case.
1386       An  internal integer representation of a variable can be specified with
1387       the -i [n] option of the typeset special  built-in  command.   The  op‐
1388       tional  option  argument n specifies an arithmetic base to be used when
1389       expanding the variable.  If you do not specify an arithmetic base, base
1390       10 will be used.
1392       Arithmetic evaluation is performed on the value of each assignment to a
1393       variable with the -E, -F, -X, or -i attribute.   Assigning  a  floating
1394       point  number  to  a variable whose type is an integer causes the frac‐
1395       tional part to be truncated.
1397   Prompting.
1398       When used interactively, the shell prompts with the value of PS1  after
1399       expanding  it for parameter expansion, command substitution, and arith‐
1400       metic expansion, before reading a command.  In addition, each single  !
1401       in  the prompt is replaced by the command number.  A !!  is required to
1402       place !  in the prompt.  If at any time a new-line is typed and further
1403       input is needed to complete a command, then the secondary prompt (i.e.,
1404       the value of PS2) is issued.
1406   Conditional Expressions.
1407       A conditional expression is used with the [[ compound command  to  test
1408       attributes  of files and to compare strings.  Field splitting and path‐
1409       name expansion are not performed on the words between [[ and ]].   Each
1410       expression  can  be constructed from one or more of the following unary
1411       or binary expressions:
1412              string Same as -n string below.
1413              -a file
1414                     Same as -e below.  This is obsolete.
1415              -b file
1416                     True if file exists and is a block special file.
1417              -c file
1418                     True if file exists and is a character special file.
1419              -d file
1420                     True if file exists and is a directory.
1421              -e file
1422                     True if file exists.
1423              -f file
1424                     True if file exists and is an ordinary file.
1425              -g file
1426                     True if file exists and it has its setgid bit set.
1427              -k file
1428                     True if file exists and it has its sticky bit set.
1429              -n string
1430                     True if length of string is non-zero.
1431              -o ?option
1432                     True if option named option is a valid option name.
1433              -o option
1434                     True if option named option is on.
1435              -p file
1436                     True if file exists and is a fifo special file or a pipe.
1437              -r file
1438                     True if file exists and is readable by current process.
1439              -s file
1440                     True if file exists and has size greater than zero.
1441              -t fildes
1442                     True if file descriptor number fildes is open and associ‐
1443                     ated with a terminal device.
1444              -u file
1445                     True if file exists and it has its setuid bit set.
1446              -v name
1447                     True  if  variable  name  is a valid variable name and is
1448                     set.
1449              -w file
1450                     True if file exists and is writable by current process.
1451              -x file
1452                     True if file exists and is executable by current process.
1453                     If  file exists and is a directory, then true if the cur‐
1454                     rent process has permission to search in the directory.
1455              -z string
1456                     True if length of string is zero.
1457              -L file
1458                     True if file exists and is a symbolic link.
1459              -h file
1460                     True if file exists and is a symbolic link.
1461              -N file
1462                     True if file exists and the modification time is  greater
1463                     than the last access time.
1464              -O file
1465                     True if file exists and is owned by the effective user ID
1466                     of this process.
1467              -G file
1468                     True if file exists and its group matches  the  effective
1469                     group ID of this process.
1470              -R name
1471                     True if variable name is a name reference.
1472              -S file
1473                     True if file exists and is a socket.
1474              file1 -nt file2
1475                     True  if  file1  exists  and  file2 does not, or file1 is
1476                     newer than file2.
1477              file1 -ot file2
1478                     True if file2 exists and file1  does  not,  or  file1  is
1479                     older than file2.
1480              file1 -ef file2
1481                     True if file1 and file2 exist and refer to the same file.
1482              string == pattern
1483                     True  if string matches pattern.  Any part of pattern can
1484                     be quoted to cause it to be matched as a string.  With  a
1485                     successful  match to a pattern, the .sh.match array vari‐
1486                     able will contain the match and subpattern matches.
1487              string = pattern
1488                     Same as == above, but is obsolete.
1489              string != pattern
1490                     True if string does not match pattern.  When  the  string
1491                     matches  the  pattern  the  .sh.match array variable will
1492                     contain the match and subpattern matches.
1493              string =∼ ere
1494                     True if string matches the pattern ∼(E)ere where  ere  is
1495                     an extended regular expression.
1496              string1 < string2
1497                     True if string1 comes before string2 based on ASCII value
1498                     of their characters.
1499              string1 > string2
1500                     True if string1 comes after string2 based on ASCII  value
1501                     of their characters.
1503       The following obsolete arithmetic comparisons are also permitted:
1504              exp1 -eq exp2
1505                     True if exp1 is equal to exp2.
1506              exp1 -ne exp2
1507                     True if exp1 is not equal to exp2.
1508              exp1 -lt exp2
1509                     True if exp1 is less than exp2.
1510              exp1 -gt exp2
1511                     True if exp1 is greater than exp2.
1512              exp1 -le exp2
1513                     True if exp1 is less than or equal to exp2.
1514              exp1 -ge exp2
1515                     True if exp1 is greater than or equal to exp2.
1517       In  each  of  the  above expressions, if file is of the form /dev/fd/n,
1518       where n is an integer, then the test is applied to the open file  whose
1519       descriptor  number  is n.  The posix shell option disables this special
1520       handling.
1522       A compound expression can be constructed from these primitives by using
1523       any of the following, listed in decreasing order of precedence:
1524              (expression)
1525                     True if expression is true.  Used to group expressions.
1526              ! expression
1527                     True if expression is false.
1528              expression1 && expression2
1529                     True if expression1 and expression2 are both true.
1530              expression1 || expression2
1531                     True if either expression1 or expression2 is true.
1533   Input/Output.
1534       Before  a  command  is executed, its input and output may be redirected
1535       using a special notation interpreted by the shell.  The  following  may
1536       appear  anywhere in a simple-command or may precede or follow a command
1537       and are not passed on to the invoked  command.   Command  substitution,
1538       parameter  expansion,  and  arithmetic  expansion  occur before word or
1539       digit is used except as noted below.  Pathname expansion occurs only if
1540       the  shell is interactive and the pattern matches a single file.  Field
1541       splitting is not performed.
1543       In each  of  the  following  redirections,  if  file  is  of  the  form
1544       /dev/sctp/host/port,  /dev/tcp/host/port,  or /dev/udp/host/port, where
1545       host is a hostname or host address, and port is a service given by name
1546       or an integer port number, then the redirection attempts to make a tcp,
1547       sctp or udp connection to the corresponding socket.
1549       No intervening space is allowed between the characters  of  redirection
1550       operators.
1552       <word         Use file word as standard input (file descriptor 0).
1554       >word         Use file word as standard output (file descriptor 1).  If
1555                     the file does not exist then it is created.  If the  file
1556                     exists,  and  the  noclobber option is on, this causes an
1557                     error; otherwise, it is truncated to zero length.
1559       >|word        Same as >, except that it overrides the noclobber option.
1561       >;word        Write output to a temporary file.  If  the  command  com‐
1562                     pletes  successfully rename it to word, otherwise, delete
1563                     the temporary file.  >;word cannot be used with the  exec
1564                     and redirect built-ins.
1566       >>word        Use  file  word  as standard output.  If the file exists,
1567                     then output is appended to it (by first  seeking  to  the
1568                     end-of-file); otherwise, the file is created.
1570       <>word        Open  file  word for reading and writing as standard out‐
1571                     put.  If the posix option is active, it defaults to stan‐
1572                     dard input instead.
1574       <>;word       The  same  as <>word except that if the command completes
1575                     successfully, word is truncated to the offset at  command
1576                     completion.  <>;word cannot be used with the exec and re‐
1577                     direct built-ins.
1579       <<[-]word     The shell input is read up to a line that is the same  as
1580                     word after any quoting has been removed, or to an end-of-
1581                     file.   No  parameter  expansion,  command  substitution,
1582                     arithmetic  expansion  or pathname expansion is performed
1583                     on word.  The resulting document, called a here-document,
1584                     becomes  the standard input.  If any character of word is
1585                     quoted, then no interpretation is placed upon the charac‐
1586                     ters  of  the  document;  otherwise, parameter expansion,
1587                     command substitution,  and  arithmetic  expansion  occur,
1588                     \new-line  is  ignored,  and  \ must be used to quote the
1589                     characters \, $, `.  If - is appended  to  <<,  then  all
1590                     leading  tabs  are  stripped from word and from the docu‐
1591                     ment.  If # is appended to <<, then  leading  spaces  and
1592                     tabs  will be stripped off the first line of the document
1593                     and up to an equivalent indentation will be stripped from
1594                     the remaining lines and from word.  A tab stop is assumed
1595                     to occur at every 8 columns for the purposes of determin‐
1596                     ing the indentation.
1598       <<<word       A  short  form of here document in which word becomes the
1599                     contents of the here-document after any parameter  expan‐
1600                     sion,  command substitution, and arithmetic expansion oc‐
1601                     cur.
1603       <&digit       The standard input is  duplicated  from  file  descriptor
1604                     digit (see dup(2)).
1606       >&digit       The  standard  output  is duplicated from file descriptor
1607                     digit.
1609       <&digit-      The file descriptor given by digit is moved  to  standard
1610                     input.
1612       >&digit-      The  file  descriptor given by digit is moved to standard
1613                     output.
1615       <&-           The standard input is closed.
1617       >&-           The standard output is closed.
1619       <&p           The input from the co-process is moved to standard input.
1621       >&p           The output to the co-process is moved to standard output.
1623       <#((expr))    Evaluate arithmetic expression expr and position file de‐
1624                     scriptor 0 to the resulting value bytes from the start of
1625                     the file.  The variables CUR and EOF evaluate to the cur‐
1626                     rent  offset  and  end-of-file  offset  respectively when
1627                     evaluating expr.
1629       >#((offset))  The same as <# except applies to file descriptor 1.
1631       <#pattern     Seeks forward to the beginning of the next line  contain‐
1632                     ing pattern.
1634       <##pattern    The  same  as <# except that the portion of the file that
1635                     is skipped is copied to standard output.
1637       If one of the above is preceded by a digit, with no intervening  space,
1638       then  the  file  descriptor number referred to is that specified by the
1639       digit (instead of the default 0 or 1).  If one of the above, other than
1640       >&- and the ># and <# forms, is preceded by {varname} with no interven‐
1641       ing space, then a file descriptor number > 9 will be  selected  by  the
1642       shell  and  stored  in  the variable varname, so it can be read from or
1643       written to with redirections like <& $varname or >& $varname.   If  >&-
1644       or the any of the ># and <# forms is preceded by {varname} the value of
1645       varname defines the file descriptor to close or position.  For example:
1647              ... 2>&1
1649       means file descriptor 2 is to be opened for writing as a  duplicate  of
1650       file descriptor 1 and
1652              exec {n}<file
1654       means  open  file  named file for reading and store the file descriptor
1655       number in variable n.
1657       A special shorthand redirection operator &>word  is  available;  it  is
1658       equivalent  to  >word 2>&1. It cannot be preceded by any digit or vari‐
1659       able name. This shorthand is disabled if the posix shell option is  ac‐
1660       tive.
1662       The  order  in  which  redirections  are specified is significant.  The
1663       shell evaluates each redirection in  terms  of  the  (file  descriptor,
1664       file) association at the time of evaluation.  For example:
1666              ... 1>fname 2>&1
1668       first associates file descriptor 1 with file fname.  It then associates
1669       file descriptor 2 with the file associated with file descriptor 1 (i.e.
1670       fname).   If the order of redirections were reversed, file descriptor 2
1671       would be associated with the terminal (assuming file descriptor  1  had
1672       been) and then file descriptor 1 would be associated with file fname.
1674       If  a  command is followed by & and job control is not active, then the
1675       default standard input for the command is  the  empty  file  /dev/null.
1676       Otherwise,  the environment for the execution of a command contains the
1677       file descriptors of the invoking  shell  as  modified  by  input/output
1678       specifications.
1680   Environment.
1681       The  environment (see environ(7)) is a list of name-value pairs that is
1682       passed to an executed program in the same  way  as  a  normal  argument
1683       list.   The  names  must  be  identifiers  and the values are character
1684       strings.  The shell interacts with the environment in several ways.  On
1685       invocation,  the shell scans the environment and creates a variable for
1686       each name found, giving it the corresponding value and  attributes  and
1687       marking  it export.  Executed commands inherit the environment.  If the
1688       user modifies the values of these variables or creates new ones,  using
1689       the export or typeset -x commands, they become part of the environment.
1690       The environment seen by any executed command is thus  composed  of  any
1691       name-value pairs originally inherited by the shell, whose values may be
1692       modified by the current shell, plus any additions which must  be  noted
1693       in export or typeset -x commands.
1695       The  environment for any simple-command or function may be augmented by
1696       prefixing it with one or more variable assignments.  A variable assign‐
1697       ment argument is a word of the form identifier=value.  Thus:
1699              TERM=450 cmd args                  and
1700              (export TERM; TERM=450; cmd args)
1702       are  equivalent  (as far as the above execution of cmd is concerned ex‐
1703       cept for special built-in commands listed below - those that are marked
1704       with ).
1706       If the obsolete -k option is set, all variable assignment arguments are
1707       placed in the environment, even if they occur after the  command  name.
1708       The following first prints a=b c and then c:
1710              echo a=b c
1711              set -k
1712              echo a=b c
1714       This  feature  is  intended for use with scripts written for early ver‐
1715       sions of the shell and its use in new scripts is strongly  discouraged.
1716       It is likely to disappear someday.
1718   Functions.
1719       For  historical  reasons,  there  are two ways to define functions, the
1720       name() syntax and the function name syntax, described in  the  Commands
1721       section  above.   Shell  functions  are  read in and stored internally.
1722       Alias names are resolved when the function is read.  Functions are exe‐
1723       cuted like commands with the arguments passed as positional parameters.
1724       (See Execution below.)
1726       Functions defined by the function name syntax and called by  name  exe‐
1727       cute  in the same process as the caller and share all files and present
1728       working directory with the caller.  Traps caught by the caller are  re‐
1729       set to their default action inside the function.  A trap condition that
1730       is not caught or ignored by the function causes the function to  termi‐
1731       nate  and  the condition to be passed on to the caller.  A trap on EXIT
1732       set inside a function is executed in the environment of the caller  af‐
1733       ter  the  function completes.  Ordinarily, variables are shared between
1734       the calling program and the function.   However,  the  typeset  special
1735       built-in  command  used within a function defines local variables whose
1736       scope includes the current function.  They can be passed  to  functions
1737       that  they  call in the variable assignment list that precedes the call
1738       or as arguments passed as name references.  Errors within functions re‐
1739       turn control to the caller.
1741       Functions defined with the name() syntax and functions defined with the
1742       function name syntax that are invoked with the .  special built-in  are
1743       executed  in the caller's environment and share all variables and traps
1744       with the caller.  Errors within these  function  executions  cause  the
1745       script that contains them to abort.
1747       The  special  built-in  command  return is used to return from function
1748       calls.
1750       Function names can be listed with the -f or +f option  of  the  typeset
1751       special  built-in command.  The text of functions, when available, will
1752       also be listed with -f.  Functions can be undefined with the -f  option
1753       of the unset special built-in command.
1755       Ordinarily, functions are unset when the shell executes a shell script.
1756       Functions that need to be defined across separate  invocations  of  the
1757       shell  should  be  placed  in a directory and the FPATH variable should
1758       contain the name of this directory.  They may also be specified in  the
1759       ENV file.
1761   Discipline Functions.
1762       Each  variable  can  have  zero or more discipline functions associated
1763       with it.  The shell initially understands  the  discipline  names  get,
1764       set,  append,  and  unset but can be added when defining new types.  On
1765       most systems others can be added at run time via the C programming  in‐
1766       terface extension provided by the builtin built-in utility.  If the get
1767       discipline is defined for a variable, it is invoked whenever the  given
1768       variable  is referenced.  If the variable .sh.value is assigned a value
1769       inside the discipline function, the referenced variable  will  evaluate
1770       to  this  value  instead.  If the set discipline is defined for a vari‐
1771       able, it is invoked whenever the given variable is  assigned  a  value.
1772       If the append discipline is defined for a variable, it is invoked when‐
1773       ever a value is appended to the given variable.  The variable .sh.value
1774       is  given the value of the variable before invoking the discipline, and
1775       the variable will be assigned the value of .sh.value after  the  disci‐
1776       pline  completes.   If  .sh.value  is unset inside the discipline, then
1777       that value is unchanged.  If the unset  discipline  is  defined  for  a
1778       variable, it is invoked whenever the given variable is unset.
1780       The  variable  .sh.name contains the name of the variable for which the
1781       discipline function is called, .sh.subscript is the  subscript  of  the
1782       variable,  and  .sh.value  will contain the value being assigned inside
1783       the set discipline function.  The variable _  is  a  reference  to  the
1784       variable  including  the  subscript  if  any.   For the set discipline,
1785       changing .sh.value will change the value that gets assigned.   Finally,
1786       the  expansion  ${var.name}, when name is the name of a discipline, and
1787       there is no variable of this name, is equivalent to the command substi‐
1788       tution ${ var.name;}.
1791   Name Spaces.
1792       Commands and functions that are executed as part of the list of a name‐
1793       space command that modify variables or create new ones,  create  a  new
1794       variable  whose  name is the name of the name space as given by identi‐
1795       fier preceded by ..  When a variable whose name is name is  referenced,
1796       it is first searched for using .identifier.name.  Similarly, a function
1797       defined by a command in the namespace list is created  using  the  name
1798       space name preceded by a ..
1800       When  the list of a namespace command contains a namespace command, the
1801       names of variables and functions that are created consist of the  vari‐
1802       able or function name preceded by the list of identifiers each preceded
1803       by ..
1805       Outside of a name space, a variable or function created inside  a  name
1806       space can be referenced by preceding it with the name space name.
1808       By default, variables starting with .sh are in the sh name space.
1811   Type Variables.
1812       Typed  variables provide a way to create data structure and objects.  A
1813       type can be defined either by a shared library, by  the  enum  built-in
1814       command  described  below, or by using the new -T option of the typeset
1815       built-in command.  With the -T option of typeset, the type name, speci‐
1816       fied  as  an option argument to -T, is set with a compound variable as‐
1817       signment that defines the type.  Function definitions can appear inside
1818       the  compound variable assignment and these become discipline functions
1819       for this type and can be invoked or redefined by each instance  of  the
1820       type.   The  function  name create is treated specially.  It is invoked
1821       for each instance of the type that is created but is not inherited  and
1822       cannot be redefined for each instance.
1824       When  a  type  is  defined  a  special built-in command of that name is
1825       added.  These built-ins are declaration commands and  follow  the  same
1826       expansion  rules  as  the  built-in  commands  described below that are
1827       marked with a ‡ symbol. These commands can subsequently be used  inside
1828       further  type definitions.  The man page for these commands can be gen‐
1829       erated by using the --man option or any of the  other  --  options  de‐
1830       scribed  with  getopts.   The -r, -a, -A, -h, and -S options of typeset
1831       are permitted with each of these new built-ins.
1833       An instance of a type is created by invoking the type name followed  by
1834       one  or  more instance names.  Each instance of the type is initialized
1835       with a copy of the subvariables except for subvariables  that  are  de‐
1836       fined  with the -S option.  Variables defined with the -S are shared by
1837       all instances of the type.  Each instance can change the value  of  any
1838       subvariable  and  can  also define new discipline functions of the same
1839       names as those defined by the type definition as well as  any  standard
1840       discipline  names.   No  additional subvariables can be defined for any
1841       instance.
1843       When defining a type, if the value of a subvariable is not set and  the
1844       -r  attribute  is specified, it causes the subvariable to be a required
1845       subvariable.  Whenever an instance of a type is created,  all  required
1846       subvariables must be specified.  These subvariables become read-only in
1847       each instance.
1849       When unset is invoked on a subvariable within a type, and the -r attri‐
1850       bute  has  not been specified for this field, the value is reset to the
1851       default value associative with the type.  Invoking unset on a type  in‐
1852       stance  not  contained within another type deletes all subvariables and
1853       the variable itself.
1855       A type definition can be derived from another type definition by defin‐
1856       ing  the  first subvariable name as _ and defining its type as the base
1857       type.  Any remaining definitions will be  additions  and  modifications
1858       that  apply  to the new type.  If the new type name is the same as that
1859       of the base type, the type will be replaced and the original type  will
1860       no longer be accessible.
1862       The typeset command with the -T and no option argument or operands will
1863       write all the type definitions to standard output in a form that can be
1864       read in to create all they types.
1866   Jobs.
1867       If  the  monitor option of the set command is turned on, an interactive
1868       shell associates a job with each pipeline.  It keeps a table of current
1869       jobs,  printed by the jobs command, and assigns them small integer num‐
1870       bers.  When a job is started asynchronously with &, the shell prints  a
1871       line which looks like:
1873            [1] 1234
1875       indicating that the job which was started asynchronously was job number
1876       1 and had one (top-level) process, whose process ID was 1234.
1878       This paragraph and the next require features that are not in  all  ver‐
1879       sions  of UNIX and may not apply.  If you are running a job and wish to
1880       do something else you may hit the key ^Z (control-Z) which sends a STOP
1881       signal  to the current job.  The shell will then normally indicate that
1882       the job has been `Stopped', and print another prompt.  You can then ma‐
1883       nipulate  the  state of this job, putting it in the background with the
1884       bg command, or run some other commands and then  eventually  bring  the
1885       job  back  into  the  foreground  with the foreground command fg.  A ^Z
1886       takes effect immediately and is like an interrupt in that pending  out‐
1887       put and unread input are discarded when it is typed.
1889       A  job  being  run in the background will stop if it tries to read from
1890       the terminal.  Background jobs are normally allowed to produce  output,
1891       but this can be disabled by giving the command stty tostop.  If you set
1892       this tty option, then background jobs will stop when they try  to  pro‐
1893       duce output like they do when they try to read input.
1895       There are several ways to refer to jobs in the shell.  A job can be re‐
1896       ferred to by the process ID of any process of the job or by one of  the
1897       following:
1898              %number
1899                     The job with the given number.
1900              %string
1901                     Any job whose command line begins with string.
1902              %?string
1903                     Any job whose command line contains string.
1904              %%     Current job.
1905              %+     Equivalent to %%.
1906              %-     Previous job.
1908       The shell learns immediately whenever a process changes state.  It nor‐
1909       mally informs you whenever a job becomes blocked  so  that  no  further
1910       progress is possible, but only just before it prints a prompt.  This is
1911       done so that it does not otherwise disturb your work.  The  notify  op‐
1912       tion of the set command causes the shell to print these job change mes‐
1913       sages as soon as they occur.
1915       When the monitor option is on, each background job that completes trig‐
1916       gers any trap set for CHLD.
1918       When  you try to leave the shell while jobs are running or stopped, you
1919       will be warned that `You have stopped(running) jobs.'  You may use  the
1920       jobs  command  to  see  what  they are.  If you immediately try to exit
1921       again, the shell will not warn you a second time, and the stopped  jobs
1922       will be terminated.  When a login shell receives a HUP signal, it sends
1923       a HUP signal to each job that has not been  disowned  with  the  disown
1924       built-in command described below.
1926   Signals.
1927       The INT and QUIT signals for an invoked command are ignored if the com‐
1928       mand is followed by & and the monitor option is not active.  Otherwise,
1929       signals have the values inherited by the shell from its parent (but see
1930       also the trap built-in command below).
1932   Execution.
1933       Each time a command is read, the above expansions and substitutions are
1934       carried  out.   If the command name matches one of the Special Built-in
1935       Commands listed below, it is executed within the current shell process.
1936       Next,  the  command name is checked to see if it matches a user defined
1937       function.  If it does, the positional parameters are saved and then re‐
1938       set to the arguments of the function call.  A function is also executed
1939       in the current shell process.  When the function completes or issues  a
1940       return,  the  positional parameter list is restored.  For functions de‐
1941       fined with the function name syntax, any trap set on  EXIT  within  the
1942       function is executed.  The exit value of a function is the value of the
1943       last command executed.  If a command name is  not  a  special  built-in
1944       command  or a user defined function, but it is one of the built-in com‐
1945       mands listed below, it is executed in the current shell process.
1947       The shell variables PATH followed by the  variable  FPATH  defines  the
1948       list of directories to search for the command name.  Alternative direc‐
1949       tory names are separated by a colon (:).  The default path is the value
1950       that was output by getconf PATH at the time ksh was compiled.  The cur‐
1951       rent directory can be specified by two or more adjacent colons, or by a
1952       colon  at  the  beginning or end of the path list.  If the command name
1953       contains a /, then the search path is not used.  Otherwise, each direc‐
1954       tory in the list of directories defined by PATH and FPATH is checked in
1955       order.  If the directory being searched is contained in FPATH and  con‐
1956       tains  a  file whose name matches the command being searched, then this
1957       file is loaded into the current shell environment as if it were the ar‐
1958       gument  to  the . command except that only preset aliases are expanded,
1959       and a function of the given name is executed as described above.
1961       If this directory is not in FPATH the shell  first  determines  whether
1962       there is a built-in version of a command corresponding to a given path‐
1963       name and if so it is invoked in the current process.  If no built-in is
1964       found,  the shell checks for a file named .paths in this directory.  If
1965       found and there is a line of the form FPATH=path where  path  names  an
1966       existing  directory  then  that directory is searched immediately after
1967       the current directory as if it were found in the  FPATH  variable.   If
1968       path does not begin with /, it is checked for relative to the directory
1969       being searched.
1971       The .paths file is then checked for a line of the form  PLUGIN_LIB=lib‐
1972       name  [  :  libname  ]  ...  .   Each  library named by libname will be
1973       searched for as if it were an option argument to builtin -f, and if  it
1974       contains a built-in of the specified name this will be executed instead
1975       of a command by this name.  Any built-in loaded from  a  library  found
1976       this  way  will  be associated with the directory containing the .paths
1977       file so it will only execute if not found in an earlier directory.
1979       Finally, the directory will be checked for a file of  the  given  name.
1980       If  the file has execute permission but is not an a.out file, it is as‐
1981       sumed to be a file containing shell  commands.   A  separate  shell  is
1982       spawned  to  read  it.   All non-exported variables are removed in this
1983       case.  If the shell command file doesn't have read  permission,  or  if
1984       the  setuid and/or setgid bits are set on the file, then the shell exe‐
1985       cutes an agent whose job it is to set up the  permissions  and  execute
1986       the  shell with the shell command file passed down as an open file.  If
1987       the .paths contains a line of the form name=value in the first or  sec‐
1988       ond  line, then the environment variable name is modified by prepending
1989       the directory specified by value to the directory list.   If  value  is
1990       not  an  absolute  directory, then it specifies a directory relative to
1991       the directory that the executable was found.  If the environment  vari‐
1992       able  name  does  not already exist it will be added to the environment
1993       list for the specified command.  A parenthesized command is executed in
1994       a subshell without removing non-exported variables.
1996   Command Re-entry.
1997       The  text  of  the  last HISTSIZE (default 512) commands entered from a
1998       terminal device is saved in a history file.  The file $HOME/.sh_history
1999       is  used if the HISTFILE variable is not set or if the file it names is
2000       not writable.  A shell can  access  the  commands  of  all  interactive
2001       shells which use the same named HISTFILE.  The built-in command hist is
2002       used to list or edit a portion of this file.  The portion of  the  file
2003       to be edited or listed can be selected by number or by giving the first
2004       character or characters of the command.  A single command or  range  of
2005       commands  can be specified.  If you do not specify an editor program as
2006       an argument to hist then the value of the variable  HISTEDIT  is  used.
2007       If  HISTEDIT is unset, the obsolete variable FCEDIT is used.  If FCEDIT
2008       is not defined, then /bin/ed is used.  The edited command(s) is printed
2009       and  re-executed  upon leaving the editor unless you quit without writ‐
2010       ing.  The -s option (and in obsolete versions, the editor  name  -)  is
2011       used  to skip the editing phase and to re-execute the command.  In this
2012       case a substitution parameter of the form old=new can be used to modify
2013       the  command  before  execution.  For example, with the preset alias r,
2014       which is aliased to ′hist -s′, typing `r bad=good  c'  will  re-execute
2015       the  most  recent command which starts with the letter c, replacing the
2016       first occurrence of the string bad with the string good.
2018   History Expansion.
2019       History expansions introduce words from the history list into the input
2020       stream, making it easy to repeat commands, repeat arguments of a previ‐
2021       ous command in the current command, or fix typos in the  previous  com‐
2022       mand.  The history expansion facility is an alternative to history con‐
2023       trol via the fc or hist built-in command.  To enable it, turn on the -H
2024       or  histexpand  option using the set command (see Built-in Commands be‐
2025       low).
2027       History expansions begin with the character !.  They may begin anywhere
2028       in  the  input.   The  !  may  be preceded by a \ or enclosed in single
2029       quotes to prevent its special meaning.  A ! is  also  passed  unchanged
2030       when  it  is followed by a space, tab, newline, = or (.  History expan‐
2031       sions do not nest.  They are parsed separately before the shell  parser
2032       is invoked, so they can override shell grammar rules.
2034       By  default,  the  expanded version of any line that contains a history
2035       expansion is printed, added to the history, and then  immediately  exe‐
2036       cuted.   History  expansions are never added to the history themselves,
2037       regardless of whether they succeed or fail due to an error.   Normally,
2038       this  means  that a command line with an erroneous history expansion is
2039       lost and needs to be retyped from scratch, but if the histreedit  shell
2040       option  is  turned  on and a line editor is active (see In-line Editing
2041       Options below), the erroneous line is pre-filled into the next prompt's
2042       input  buffer for correcting.  The histverify option causes the same to
2043       be done for the results of successful history expansions, allowing ver‐
2044       ification and editing before execution.
2046       A  history  expansion  may have an event specification, which indicates
2047       the event from which words are to be taken, a  word  designator,  which
2048       selects  particular  words  from  the  chosen event, and/or a modifier,
2049       which manipulates the selected words.
2051       An event specification can be:
2053           n       A number, referring to a particular event.
2054           -n      An offset, referring to the  event  n  before  the  current
2055                   event.
2056           #       The current event.
2057           !       The previous event (equivalent to -1).
2058           s       The  most  recent  event  whose  first word begins with the
2059                   string s.
2060           ?s?     The most recent event which contains  the  string  s.   The
2061                   second  ? can be omitted if it is immediately followed by a
2062                   newline.
2064       For example, consider this bit of someone's history list  as  might  be
2065       output by the hist -l command:
2067           9        nroff -man wumpus.man
2068           10       cp wumpus.man wumpus.man.old
2069           11       vi wumpus.man
2070           12       diff wumpus.man.old wumpus.man
2072       The  commands  are  shown with their event numbers.  The current event,
2073       which we haven't typed in yet, is event 13.  !11 and !-2 refer to event
2074       11.   !!  refers to the previous event, 12.  !! can be abbreviated ! if
2075       it is followed by : (see below).  !n refers to event  9,  which  begins
2076       with  n.   !?old? also refers to event 12, which contains old.  Without
2077       word designators or modifiers, history references simply expand to  the
2078       entire  event, so we might type !cp to redo the copy command or !!|more
2079       if the diff output scrolled off the top of the screen.
2081       To select words from an event, the event specification can be  followed
2082       by  a  : and a designator for the desired words.  The words of an input
2083       line are numbered from 0, the first word (usually the command name) be‐
2084       ing  0,  the second word (first argument) being 1, etc.  The basic word
2085       designators are:
2087           0       The first word (command name).
2088           n       The nth argument.
2089           ^       The first argument, equivalent to 1.
2090           $       The last argument.
2091           %       The word matched by the most recent ?s? search.
2092           x-y     A range of words.
2093           -y      Equivalent to 0-y.
2094           *       Equivalent to ^-$, but returns nothing if  the  event  con‐
2095                   tains only 1 word.
2096           x*      Equivalent to x-$.
2097           x-      Equivalent to x*, but omitting the last word ($).
2099       Selected  words  are inserted into the command line separated by single
2100       blanks.  For example, the diff command in the  previous  example  might
2101       have been typed as diff !!:1.old !!:1 (using :1 to select the first ar‐
2102       gument from the previous event) or diff !-2:2 !-2:1 to select and  swap
2103       the  arguments  from the cp command.  If we didn't care about the order
2104       of the diff, we might have said diff !-2:1-2 or simply diff !-2:*.  The
2105       cp  command  might have been written cp wumpus.man !#:1.old, using # to
2106       refer to the current event.  !n:- hurkle.man would reuse the first  two
2107       words from the nroff command to say nroff -man hurkle.man.
2109       The  :  separating the event specification from the word designator can
2110       be omitted if the argument selector begins with a ^, $, *, % or -.  For
2111       example,  our diff command might have been diff !!^.old !!^ or, equiva‐
2112       lently, diff !!$.old !!$.  However, if !! is abbreviated !, an argument
2113       selector  beginning  with  - will be interpreted as an event specifica‐
2114       tion.
2116       The word(s) in a history reference can be edited by following them with
2117       one or more modifiers, each preceded by a colon (:):
2119           h       Remove a trailing pathname component, leaving the head.
2120           t       Remove all leading pathname components, leaving the tail.
2121           r       Remove a filename extension .xxx, leaving the root name.
2122           e       Remove all but the extension.
2123           s/l/r/  Substitute  l  for  r.   l is simply a string like r, not a
2124                   regular expression as in the eponymous ed(1) command.   Any
2125                   character  may  be used as the delimiter in place of /; a \
2126                   can be used to quote the delimiter inside  l  and  r.   The
2127                   character & in the r is replaced by l; \ also quotes &.  If
2128                   l is empty, the l from the previous substitution  is  used,
2129                   or if there is none, the s from the most recent ?s? search.
2130                   The trailing delimiter may be omitted if it is  immediately
2131                   followed by a newline.
2132           &       Repeat the previous substitution.
2133           g       Global  substitution, for example :gs/foo/bar/ or :g&.  Ap‐
2134                   plies the s or & modifier to the entire command line.
2135           a       Same as g.
2136           p       Print the new command line but do not execute it.
2137           q       Quote the expanded words, preventing further expansions.
2138           x       Like q, but break into words at blanks, tabs and newlines.
2140       Modifiers are applied to only the first modifiable word (unless g or  a
2141       is used).  It is an error for no word to be modifiable.
2143       For  example,  the  diff  command  might have been written as diff wum‐
2144       pus.man.old !#^:r, using :r to remove .old from the first  argument  on
2145       the  same  line  (!#^).  We might follow mail -s "I forgot my password"
2146       rot with !:s/rot/root to correct the spelling of root.
2148       History expansions also occur when an input line begins with  ^.   When
2149       it  is  the  first character on an input line, it is an abbreviation of
2150       !:s^.  Thus we might have said ^rot^root to make the  spelling  correc‐
2151       tion  in the previous example.  This is the only history expansion that
2152       does not explicitly begin with !.
2154       If a word on a command line begins with the history  comment  character
2155       #,  history  expansion is ignored for the rest of that line.  This usu‐
2156       ally causes the shell parser (which uses the same character to signal a
2157       comment)  to  treat  the  rest of the line as a comment as well, but as
2158       history expansion is parsed separately from the shell grammar and  with
2159       different  rules,  this cannot be guaranteed in all cases.  If the his‐
2160       tory comment character is changed, the shell grammar comment  character
2161       does not change along with it.
2163       The  three  characters  used to signal history expansion can be changed
2164       using the histchars shell variable; see Shell Variables above.
2166   In-line Editing Options.
2167       Normally, each command line entered from a terminal  device  is  simply
2168       typed  followed by a new-line (`RETURN' or `LINE FEED').  If either the
2169       emacs, gmacs, or vi option is active, the user  can  edit  the  command
2170       line.   To  be in either of these edit modes, set the corresponding op‐
2171       tion.  An editing option is automatically selected each time the VISUAL
2172       or  EDITOR  variable  is  assigned a value matching any of these editor
2173       names; for details, see Shell Variables above under VISUAL.
2175       The editing features require that the user's terminal  accept  `RETURN'
2176       as  carriage return without line feed and that a space (` ') must over‐
2177       write the current character on the screen.
2179       Unless the multiline option is on, the editing modes implement  a  con‐
2180       cept  where  the  user is looking through a window at the current line.
2181       The window width is the value of COLUMNS if it  is  defined,  otherwise
2182       80.   If  the window width is too small to display the prompt and leave
2183       at least 8 columns to enter input, the prompt  is  truncated  from  the
2184       left.  If the line is longer than the window width minus two, a mark is
2185       displayed at the end of the window to notify the user.  As  the  cursor
2186       moves  and  reaches  the window boundaries, the window will be centered
2187       about the cursor.  The mark is a > (<, *) if the line  extends  on  the
2188       right (left, both) side(s) of the window.
2190       The  search  commands  in  each edit mode provide access to the history
2191       file.  Only strings are matched, not patterns, although a leading ^  in
2192       the  string  restricts the match to begin at the first character in the
2193       line.
2195       Each of the edit modes has an operation to list the files  or  commands
2196       that match a partially entered word.  When applied to the first word on
2197       the line, or the first word after a ;, |, &, or (, and  the  word  does
2198       not  begin  with  or contain a /, the list of aliases, functions, and
2199       executable commands defined by the PATH variable that could  match  the
2200       partial word is displayed.  Otherwise, the list of files that match the
2201       given word is displayed.  If the partially entered word does  not  con‐
2202       tain  any  file expansion characters, a * is appended before generating
2203       these lists.  After displaying the generated list, the  input  line  is
2204       redrawn.   These  operations  are  called command name listing and file
2205       name listing, respectively.  There are additional operations,  referred
2206       to  as  command name completion and file name completion, which compute
2207       the list of matching commands or files, but  instead  of  printing  the
2208       list,  replace  the current word with a complete or partial match.  For
2209       file name completion, if the match is unique, a / is  appended  if  the
2210       file is a directory and a space is appended if the file is not a direc‐
2211       tory.  Otherwise, the longest common prefix for all the matching  files
2212       replaces  the  word.   For command name completion, only the portion of
2213       the file names after the last / are used to find  the  longest  command
2214       prefix.   If  only  a single name matches this prefix, then the word is
2215       replaced with the command name followed by a space.  When using  a  tab
2216       for  completion  that  does  not yield a unique match, a subsequent tab
2217       will provide a numbered list of matching alternatives.  A specific  se‐
2218       lection can be made by entering the selection number followed by a tab.
2219       Neither completion nor listing  operations  are  attempted  before  the
2220       first character in a line.
2222   Key Bindings.
2223       The  KEYBD  trap  can  be  used to intercept keys as they are typed and
2224       change the characters that are actually seen by the shell.   This  trap
2225       is  executed  after  each character (or sequence of characters when the
2226       first character is ESC) is entered while reading from a terminal.   The
2227       variable  .sh.edchar contains the character or character sequence which
2228       generated the trap.  Changing the value of .sh.edchar in the  trap  ac‐
2229       tion  causes  the shell to behave as if the new value were entered from
2230       the keyboard rather than the original value.
2232       The variable .sh.edcol is set to the input column number of the  cursor
2233       at  the  time of the input.  The variable .sh.edmode is set to ESC when
2234       in vi input mode (see below) and set to  the  empty  string  otherwise.
2235       Prepending ${.sh.editmode} to a value assigned to .sh.edchar will cause
2236       the shell to change to control mode if it is not already in this mode.
2238       This trap is not invoked for characters entered as arguments to editing
2239       directives, or while reading input for a character search.
2241   Emacs Editing Mode.
2242       This mode is entered by enabling either the emacs or gmacs option.  The
2243       only difference between these two modes is the way they handle ^T.   To
2244       edit,  the  user  moves  the cursor to the point needing correction and
2245       then inserts or deletes characters or words as needed.  All the editing
2246       commands  are control characters or escape sequences.  The notation for
2247       control characters is caret (^) followed by the character.   For  exam‐
2248       ple,  ^F  is the notation for control F.  This is entered by depressing
2249       `f' while holding down the `CTRL' (control) key.  The  `SHIFT'  key  is
2250       not depressed.  (The notation ^?  indicates the DEL (delete) key.)
2252       The  notation  for escape sequences is M- followed by a character.  For
2253       example, M-f (pronounced Meta f) is entered by  depressing  ESC  (ASCII
2254       033)  followed  by `f'.  (M-F would be the notation for ESC followed by
2255       `SHIFT' (capital) `F'.)
2257       All edit commands operate from any place on the line (not just  at  the
2258       beginning).   Neither  the  `RETURN' nor the `LINE FEED' key is entered
2259       after edit commands except when noted.
2261       The M-[ multi-character commands below are DEC VT220  escape  sequences
2262       generated  by  special keys on standard PC keyboards, such as the arrow
2263       keys.  You could type them directly but they are meant to recognize the
2264       keys in question, which are indicated in parentheses.
2266       ^F        Move cursor forward (right) one character.
2267       M-[C      (Right arrow) Same as ^F.
2268       M-f       Move  cursor forward one word.  (The emacs editor's idea of a
2269                 word is a string of characters consisting  of  only  letters,
2270                 digits and underscores.)
2271       M-[1;3C   (Alt-Right arrow) Same as M-f.
2272       M-[1;5C   (Ctrl-Right arrow) Same as M-f.
2273       M-[1;9C   (iTerm2 Alt-Right arrow) Same as M-f.
2274       ^B        Move cursor backward (left) one character.
2275       M-[D      (Left arrow) Same as ^B.
2276       M-b       Move cursor backward one word.
2277       M-[1;3D   (Alt-Left arrow) Same as M-b.
2278       M-[1;5D   (Ctrl-Left arrow) Same as M-b.
2279       M-[1;9D   (iTerm2 Alt-Left arrow) Same as M-b.
2280       ^A        Move cursor to start of line.
2281       M-[H      (Home) Same as ^A.
2282       M-[1~     Same as ^A.
2283       M-[7~     Same as ^A.
2284       ^E        Move cursor to end of line.
2285       M-[F      (End) Same as ^E.
2286       M-[4~     Same as ^E.
2287       M-[8~     Same as ^E.
2288       M-[Y      Same as ^E.
2289       M-OA      (Up Arrow) Same as M-[A.
2290       M-OB      (Down Arrow) Same as M-[B.
2291       M-OC      (Right Arrow) Same as M-[C.
2292       M-OD      (Left Arrow) Same as M-[D.
2293       M-O5C     (Ctrl-Right Arrow) Same as M-f.
2294       M-O5D     (Ctrl-Left Arrow) Same as M-b.
2295       ^]char    Move cursor forward to character char on current line.
2296       M-^]char  Move cursor backward to character char on current line.
2297       ^X^X      Interchange the cursor and mark.
2298       erase     (User  defined erase character as defined by the stty(1) com‐
2299                 mand, usually ^H.)  Delete previous character.
2300       lnext     (User defined  literal  next  character  as  defined  by  the
2301                 stty(1)  command,  or  ^V  if not defined.)  Removes the next
2302                 character's editing features (if any).
2303       ^D        Delete current character.
2304       M-[3~     (Forward delete) Same as ^D.
2305       M-d       Delete current word.
2306       M-[3;5~   (Ctrl-Delete) Same as M-d.
2307       M-^H      (Meta-backspace) Delete previous word.
2308       M-h       Delete previous word.
2309       M-^?      (Meta-DEL) Delete previous word (if your interrupt  character
2310                 is ^?  (DEL, the default) then this command will not work).
2311       ^T        Transpose  current  character with previous character and ad‐
2312                 vance the cursor in emacs mode.  Transpose two previous char‐
2313                 acters in gmacs mode.
2314       ^C        Capitalize current character.
2315       M-c       Capitalize current word.
2316       M-l       Change the current word to lower case.
2317       ^K        Delete  from  the cursor to the end of the line.  If preceded
2318                 by a numerical parameter whose value is less than the current
2319                 cursor  position,  then  delete from given position up to the
2320                 cursor.  If preceded by a numerical parameter whose value  is
2321                 greater  than  the  current cursor position, then delete from
2322                 cursor up to given cursor position.
2323       ^W        Kill from the cursor to the mark.
2324       M-p       Push the region from the cursor to the mark on the stack.
2325       kill      (User defined kill character as defined by the  stty(1)  com‐
2326                 mand,  usually  ^U.)   Kill  the entire current line.  If two
2327                 kill characters are entered in succession, all  kill  charac‐
2328                 ters  from then on cause a line feed (useful when using paper
2329                 terminals).  A subsequent pair of kill characters undoes this
2330                 change.
2331       ^Y        Restore  last  item removed from line. (Yank item back to the
2332                 line.)
2333       ^X^E      Return the command hist -e  ${VISUAL:-${EDITOR:-vi}}  in  the
2334                 input  buffer  to call a full editor — vi by default — on the
2335                 current command line.
2336       ^L        Line feed and print current line.
2337       M-^L      Clear the screen.
2338       ^@        (Null character) Set mark.
2339       M-space   (Meta space) Set mark.
2340       ^J        (New line) Execute the current line.
2341       ^M        (Return) Execute the current line.
2342       eof       End-of-file character, normally ^D, is processed as  an  End-
2343                 of-file only if the current line is empty.
2344       ^P        Fetch previous command.  Each time ^P is entered the previous
2345                 command back in time is accessed.  Moves back one  line  when
2346                 not on the first line of a multi-line command.
2347       M-[A      (Up  arrow)  If  the  cursor is at the end of the line, it is
2348                 equivalent to ^R with string set to the contents of the  cur‐
2349                 rent line.  Otherwise, it is equivalent to ^P.
2350       M-<       Fetch the least recent (oldest) history line.
2351       M->       Fetch the most recent (youngest) history line.
2352       ^N        Fetch  next  command  line.  Each time ^N is entered the next
2353                 command line forward in time is accessed.
2354       M-[B      (Down arrow) Equivalent to ^N.
2355       ^Rstring  Reverse search history for a previous command line containing
2356                 string.   If a parameter of zero is given, the search is for‐
2357                 ward.  String is terminated by a `RETURN' or `NEW LINE'.   If
2358                 string  is  preceded by a ^, the matched line must begin with
2359                 string.  If string is omitted, then  the  next  command  line
2360                 containing  the most recent string is accessed.  In this case
2361                 a parameter of zero reverses the direction of the search.
2362       ^G        Exit reverse search mode.
2363       ^O        Operate - Execute the current line and fetch  the  next  line
2364                 relative to current line from the history file.
2365       M-digits  (Escape)  Define numeric parameter, the digits are taken as a
2366                 parameter to the next command.  The commands  that  accept  a
2367                 parameter are ^F, ^B, erase, ^C, ^D, ^K, ^R, ^P, ^N, ^], M-.,
2368                 M-^], M-_, M-=, M-b, M-c, M-d, M-f, M-h, M-l, M-^H,  and  the
2369                 arrow keys and forward-delete key.
2370       M-letter  Soft-key  -  Your  alias list is searched for an alias by the
2371                 name _letter and if an alias of this  name  is  defined,  its
2372                 value  will  be inserted on the input queue.  The letter must
2373                 not be one of the above meta-functions.
2374       M-[letter Soft-key - Your alias list is searched for an  alias  by  the
2375                 name  __letter  and  if an alias of this name is defined, its
2376                 value will be inserted on the input queue.  This can be  used
2377                 to program function keys on many terminals.
2378       M-.       The  last  word  of  the  previous command is inserted on the
2379                 line.  If preceded by a numeric parameter, the value of  this
2380                 parameter  determines  which  word  to insert rather than the
2381                 last word.
2382       M-_       Same as M-..
2383       M-*       Attempt pathname expansion on the current word.  An  asterisk
2384                 is appended if the word doesn't match any file or contain any
2385                 special pattern characters.
2386       M-ESC     Command or file name completion as described above.
2387       ^I tab    Attempts command or file name completion as described  above.
2388                 If a partial completion occurs, repeating this will behave as
2389                 if M-= were entered.  If no match is found or  entered  after
2390                 space, a tab is inserted.
2391       M-=       If not preceded by a numeric parameter, it generates the list
2392                 of matching commands or file names as described above.   Oth‐
2393                 erwise,  the  word  under  the cursor is replaced by the item
2394                 corresponding to the value of the numeric parameter from  the
2395                 most  recently generated command or file list.  If the cursor
2396                 is not on a word, it is inserted instead.
2397       ^U        Multiply parameter of next command by 4.
2398       \         If the backslashctrl shell option is on (which is the default
2399                 setting),  this  escapes the next character.  Editing charac‐
2400                 ters, the user's erase,  kill  and  interrupt  (normally  ^C)
2401                 characters  may  be  entered in a command line or in a search
2402                 string if preceded by a \.  The \ removes  the  next  charac‐
2403                 ter's editing features (if any).  See also lnext which is not
2404                 subject to any shell option.
2405       M-^V      Display version of the shell.
2406       M-[2~     (Insert) Escape the next character.
2407       M-#       If the line does not begin with a #, a # is inserted  at  the
2408                 beginning  of  the line and after each new-line, and the line
2409                 is entered.  This causes a comment to be inserted in the his‐
2410                 tory file.  If the line begins with a #, the # is deleted and
2411                 one # after each new-line is also deleted.
2413   Vi Editing Mode.
2414       There are two typing modes.  Initially, when you enter  a  command  you
2415       are in the input mode.  To edit, the user enters control mode by typing
2416       ESC (033) and moves the cursor to the point needing correction and then
2417       inserts  or  deletes  characters or words as needed.  Most control com‐
2418       mands accept an optional repeat count prior to the command.
2420       The notation for control characters used below is ^ followed by a char‐
2421       acter.  For instance, ^H is entered by holding down the Control key and
2422       pressing H.  ^[ (Control+[) is equivalent to the ESC key.  The notation
2423       for escape sequences is ^[ followed by one or more characters.
2425       The ^[[ (ESC [) multi-character commands below are DEC VT220 escape se‐
2426       quences generated by special keys on standard PC keyboards, such as the
2427       arrow  keys,  which  are  indicated in parentheses. When in input mode,
2428       these keys will switch you to control mode before performing the  asso‐
2429       ciated  action.  These sequences can use preceding repeat count parame‐
2430       ters, but only when the ^[ and the subsequent [ are  entered  into  the
2431       input buffer at the same time, such as when pressing one of those keys.
2433        Input Edit Commands
2434              By default the editor is in input mode.
2436              erase     (User  defined  erase  character  as  defined  by  the
2437                        stty(1) command, usually ^H or  #.)   Delete  previous
2438                        character.
2439              ^W        Delete the previous blank separated word.
2440              eof       As the first character of the line causes the shell to
2441                        terminate unless the ignoreeof option is set.   Other‐
2442                        wise this character is ignored.
2443              lnext     (User defined literal next character as defined by the
2444                        stty(1) or ^V if not defined.)  Removes the next char‐
2445                        acter's editing features (if any).
2446              \         If  the backslashctrl shell option is on (which is the
2447                        default setting), this escapes the next erase or  kill
2448                        character.
2449              ^I tab    Attempts  command or file name completion as described
2450                        above and returns to input mode. If a partial  comple‐
2451                        tion  occurs,  repeating this will behave as if = were
2452                        entered from control mode.  If no match  is  found  or
2453                        entered after space, a tab is inserted.
2455        Motion Edit Commands
2456              These commands will move the cursor.
2458              [count]l  Cursor forward (right) one character.
2459              [count]^[[C
2460                        (Right arrow) Same as l.
2461              [count]w  Cursor forward one alphanumeric word.
2462              [count]W  Cursor  to the beginning of the next word that follows
2463                        a blank.
2464              [count]e  Cursor to end of word.
2465              [count]E  Cursor to end of the current blank delimited word.
2466              [count]h  Cursor backward (left) one character.
2467              [count]^[[D
2468                        (Left arrow) Same as h.
2469              [count]b  Cursor backward one word.
2470              [count]B  Cursor to preceding blank separated word.
2471              [count]|  Cursor to column count.
2472              [count]fc Find the next character c in the current line.
2473              [count]Fc Find the previous character c in the current line.
2474              [count]tc Equivalent to f followed by h.
2475              [count]Tc Equivalent to F followed by l.
2476              [count];  Repeats count times, the last  single  character  find
2477                        command, f, F, t, or T.
2478              [count],  Reverses  the last single character find command count
2479                        times.
2480              0         Cursor to start of line.
2481              ^[[H      (Home) Same as 0.
2482              ^[[1~     Same as 0.
2483              ^[[7~     Same as 0.
2484              ^[[1;3D   (Alt-Left arrow) Same as b.
2485              ^[[1;5D   (Ctrl-Left arrow) Same as b.
2486              ^[[1;9D   (iTerm2 Alt-Left arrow) Same as b.
2487              ^[[1;3C   (Alt-Right arrow) Same as w.
2488              ^[[1;5C   (Ctrl-Right arrow) Same as w.
2489              ^[[1;9C   (iTerm2 Alt-Right arrow) Same as w.
2490              ^[[2~     (Insert) Same as i.
2491              ^[[3;5~   (Ctrl-Delete) Same as dw.
2492              ^[OA      (Up Arrow) Same as ^[[A.
2493              ^[OB      (Down Arrow) Same as ^[[B.
2494              ^[OC      (Right Arrow) Same as ^[[C.
2495              ^[OD      (Left Arrow) Same as ^[[D.
2496              ^[O5C     (Ctrl-Right Arrow) Same as w.
2497              ^[O5D     (Ctrl-Left Arrow) Same as b.
2498              ^         Cursor to first non-blank character in line.
2499              $         Cursor to end of line.
2500              ^[[F      (End) Same as $.
2501              ^[[4~     Same as $.
2502              ^[[8~     Same as $.
2503              ^[[Y      Same as $.
2504              ^G        Exit reverse search mode.
2505              %         Moves to balancing (, ), {, }, [, or ].  If cursor  is
2506                        not  on  one of the above characters, the remainder of
2507                        the line is searched for the first occurrence  of  one
2508                        of the above characters first.
2510        Search Edit Commands
2511              These commands access your command history.
2513              [count]k  Fetch  previous  command.   Each time k is entered the
2514                        previous command back in time is accessed.
2515              [count]-  Equivalent to k.
2516              [count]^[[A
2517                        (Up arrow) If cursor is at the end of the line  it  is
2518                        equivalent to / with string set to the contents of the
2519                        current line.  Otherwise, it is equivalent to k.
2520              [count]j  Fetch next command.  Each time j is entered  the  next
2521                        command forward in time is accessed.
2522              [count]+  Equivalent to j.
2523              [count]^[[B
2524                        (Down arrow) Equivalent to j.
2525              [count]G  The  command  number count is fetched.  The default is
2526                        the least recent history command.
2527              /string   Search backward through history for a previous command
2528                        containing string.  String is terminated by a `RETURN'
2529                        or `NEW LINE'.  If string is  preceded  by  a  ^,  the
2530                        matched  line  must  begin  with string.  If string is
2531                        empty, the previous string will be used.
2532              ?string   Same as / except that search will be  in  the  forward
2533                        direction.
2534              n         Search  for  next  match of the last pattern to / or ?
2535                        commands.
2536              N         Search for next match of the last pattern to /  or  ?,
2537                        but in reverse direction.
2539        Text Modification Edit Commands
2540              These commands will modify the line.
2542              a         Enter  input  mode  and  enter  text after the current
2543                        character.
2544              A         Append text to the end of the line.  Equivalent to $a.
2545              [count]cmotion
2546              c[count]motion
2547                        Delete current character through  the  character  that
2548                        motion  would move the cursor to and enter input mode.
2549                        If motion is c, the entire line will  be  deleted  and
2550                        input mode entered.
2551              C         Delete  the  current character through the end of line
2552                        and enter input mode.  Equivalent to c$.
2553              S         Equivalent to cc.
2554              [count]s  Replace characters under the cursor in input mode.
2555              D         Delete the current character through the end of  line.
2556                        Equivalent to d$.
2557              [count]dmotion
2558              d[count]motion
2559                        Delete  current  character  through the character that
2560                        motion would move to.  If motion is  d  ,  the  entire
2561                        line will be deleted.
2562              i         Enter  input  mode  and insert text before the current
2563                        character.
2564              I         Insert text  before  the  first  non-blank  character.
2565                        Equivalent to ^i.
2566              [count]P  Place  the  previous text modification before the cur‐
2567                        sor.
2568              [count]p  Place the previous text modification after the cursor.
2569              R         Enter input mode and replace characters on the  screen
2570                        with characters you type overlay fashion.
2571              [count]rc Replace the count character(s) starting at the current
2572                        cursor position with c, and advance the cursor.
2573              [count]x  Delete current character.
2574              [count]^[[3~
2575                        (Forward delete) Same as x.
2576              [count]X  Delete preceding character.
2577              [count].  Repeat the previous text modification command.
2578              [count]Invert the case of the count character(s) starting  at
2579                        the current cursor position and advance the cursor.
2580              [count]_  Causes  the  count  word of the previous command to be
2581                        appended and input mode entered.   The  last  word  is
2582                        used if count is omitted.
2583              *         Causes  an  *  to  be appended to the current word and
2584                        pathname expansion attempted.  If no match  is  found,
2585                        it rings the bell.  Otherwise, the word is replaced by
2586                        the matching pattern and input mode is entered.
2587              \         Command or file name completion as described above.
2589        Other Edit Commands
2590              Miscellaneous commands.
2592              [count]ymotion
2593              y[count]motion
2594                        Yank current character through character  that  motion
2595                        would move the cursor to and puts them into the delete
2596                        buffer.  The text and cursor are unchanged.
2597              yy        Yanks the entire line.
2598              Y         Yanks from current position to end of  line.   Equiva‐
2599                        lent to y$.
2600              u         Undo the last text modifying command.
2601              U         Undo  all the text modifying commands performed on the
2602                        line.
2603              [count]v  Returns the command hist  -e  ${VISUAL:-${EDITOR:-vi}}
2604                        count  in  the input buffer to call a full editor — vi
2605                        by default — on a history entry.  If count is omitted,
2606                        then the current line is used.
2607              ^L        Line  feed and print current line.  Has effect only in
2608                        control mode.
2609              ^J        (New line) Execute the  current  line,  regardless  of
2610                        mode.
2611              ^M        (Return) Execute the current line, regardless of mode.
2612              #         If  the  first  character  of the command is a #, then
2613                        this command deletes this # and each # that follows  a
2614                        newline.   Otherwise, sends the line after inserting a
2615                        # in front of each line in the  command.   Useful  for
2616                        causing the current line to be inserted in the history
2617                        as a comment  and  uncommenting  previously  commented
2618                        commands in the history file.
2619              [count]=  If  count  is  not specified, it generates the list of
2620                        matching commands or file names  as  described  above.
2621                        Otherwise,  the  word  under the cursor is replaced by
2622                        the count item from the most recently  generated  com‐
2623                        mand or file list.  If the cursor is not on a word, it
2624                        is inserted instead.
2625              @letter   Your alias list is searched for an alias by  the  name
2626                        _letter  and  if an alias of this name is defined, its
2627                        value will be inserted on the input queue for process‐
2628                        ing.
2629              ^V        Display version of the shell.
2631   Built-in Commands.
2632       The simple-commands listed below are built in to the shell and are exe‐
2633       cuted in the same process as the shell.  The effects of any  added  In‐
2634       put/Output  redirections  are local to the command, except for the exec
2635       and redirect commands.  Unless otherwise indicated, the output is writ‐
2636       ten  on  standard  output (file descriptor 1) and the exit status, when
2637       there is no syntax error, is zero.  Except  for  :,  true,  false,  and
2638       echo,  all  built-in commands accept -- to indicate end of options, and
2639       are self-documenting.
2641       The self-documenting commands interpret the option --man as  a  request
2642       to  display that command's own manual page, --help as a request to dis‐
2643       play the OPTIONS section from their manual page, and -?  as  a  request
2644       to  print a brief usage message.  All these are processed as error mes‐
2645       sages, so they are written on standard error (file descriptor 2) and to
2646       pipe them into a pager such as more(1) you need to add a 2>&1 redirect‐
2647       ion before the |. The display of boldface text depends on whether stan‐
2648       dard error is on a terminal, so is disabled when using a pager. Export‐
2649       ing the ERROR_OPTIONS environment variable with a value containing  em‐
2650       phasis will force this on; a value containing noemphasis forces it off.
2651       The test/[ command needs an additional -- argument to  recognize  self-
2652       documentation  options, e.g. test --man --.  The exec and redirect com‐
2653       mands, as they make redirections permanent, should use  self-documenta‐
2654       tion  options  in  a  subshell when redirecting, for example: (redirect
2655       --man) 2>&1.  There are advanced output options as  well;  see  getopts
2656       --man for more information.
2658       Commands  that  are  preceded  by  a  † symbol below are special built-
2659       in commands and are treated specially in the following ways:
2660              1.     Variable assignment lists preceding the command remain in
2661                     effect when the command completes.
2662              2.     I/O  redirections  are  processed  after variable assign‐
2663                     ments.
2664              3.     Errors cause a script that contains them to abort.
2665              4.     They are not valid function names.
2667       Commands that are preceded by a ‡  symbol  below  are  declaration com‐
2668       mands.   Any  following  words that are in the format of a variable as‐
2669       signment are expanded with the same rules  as  a  variable  assignment.
2670       This  means  that  tilde expansion is performed after the = sign, array
2671       assignments of the form varname=(assign_list) are supported, and  field
2672       splitting and pathname expansion are not performed.
2674: [ arg ... ]
2675              The command only expands parameters.
2677. name [ arg ... ]
2678              If  name  is  a function defined with the function name reserved
2679              word syntax, the function is executed in the current environment
2680              (as  if  it had been defined with the name() syntax).  Otherwise
2681              if name refers to a file, the file is read in its  entirety  and
2682              the commands are executed in the current shell environment.  The
2683              search path specified by PATH is used to find the directory con‐
2684              taining  the  file.  If any arguments arg are given, they become
2685              the positional parameters while processing the  .   command  and
2686              the original positional parameters are restored upon completion.
2687              Otherwise the positional parameters  are  unchanged.   The  exit
2688              status is the exit status of the last command executed.
2690       [ expression ]
2691              The  [  command  is the same as test, with the exception that an
2692              additional closing ] argument is required. See test below.
2694       alias [ -ptx ]  [ name[ =value  ] ] ...
2695              alias with no arguments prints the list of aliases in  the  form
2696              name=value  on  standard  output.  The -p option causes the word
2697              alias to be inserted before each one.  When one  or  more  argu‐
2698              ments  are  given, an alias is defined for each name whose value
2699              is given.  A trailing space in value causes the next word to  be
2700              checked  for  alias substitution.  With the -t option, each name
2701              is looked up as a command in $PATH and its path is added to  the
2702              hash  table  as  a  'tracked  alias'.  If no name is given, this
2703              prints the hash table. See hash.  Without  the  -t  option,  for
2704              each  name in the argument list for which no value is given, the
2705              name and value of the alias is printed.  The obsolete -x  option
2706              has no effect in most contexts, although if it's used with -t it
2707              will suppress all output.  The exit status is non-zero if a name
2708              is  given,  but  no value, and no alias has been defined for the
2709              name.
2711       autoload name ...
2712              Marks each name undefined so that the  FPATH  variable  will  be
2713              searched  to  find  the function definition when the function is
2714              referenced.  The same as typeset -fu.
2716       bg [ job... ]
2717              This command is only on systems that support job control.   Puts
2718              each  specified job into the background.  The current job is put
2719              in the background if job is not specified.  See Jobs for  a  de‐
2720              scription of the format of job.
2722break [ n ]
2723              Exit  from  the  enclosing for, while, until, or select loop, if
2724              any.  If n is specified, then break n levels.
2726       builtin [ -ds ] [ -f file ] [ name ... ]
2727              If name is not specified, and no -f  option  is  specified,  the
2728              built-ins  are printed on standard output.  The -s option prints
2729              only the special built-ins.  Otherwise, each name represents the
2730              pathname  whose basename is the name of the built-in.  The entry
2731              point function name is determined by prepending b_ to the built-
2732              in  name.   A built-in specified by a pathname will only be exe‐
2733              cuted when that pathname would be found during the path  search.
2734              Built-ins found in libraries loaded via the .paths file will as‐
2735              sociate with the pathname of the directory containing the .paths
2736              file.
2738              The  ISO  C/C++ prototype is b_mycommand(int argc, char *argv[],
2739              void *context) for the builtin command mycommand where  argv  is
2740              array  an of argc elements and context is an optional pointer to
2741              a Shell_t structure as described in <ast/shell.h>.
2743              Special built-ins cannot be bound to a pathname or deleted.  The
2744              -d  option deletes each of the given built-ins.  On systems that
2745              support dynamic loading, the -f option names  a  shared  library
2746              containing  the  code  for built-ins.  The shared library prefix
2747              and/or suffix, which depend on the system, can be omitted.  Once
2748              a library is loaded, its symbols become available for subsequent
2749              invocations of builtin.  Multiple  libraries  can  be  specified
2750              with separate invocations of the builtin command.  Libraries are
2751              searched in the reverse order in which they are specified.  When
2752              a  library  is  loaded,  it  looks for a function in the library
2753              whose name is lib_init() and invokes this function with an argu‐
2754              ment of 0.
2756       cd [ -L ] [ -eP ] [ arg ]
2757       cd [ -L ] [ -eP ] old new
2758              This  command  can be in either of two forms.  In the first form
2759              it changes the current directory to arg.  If arg is - the direc‐
2760              tory  is  changed to the previous directory.  The shell variable
2761              HOME is the default arg.  The variable PWD is set to the current
2762              directory.   The  shell  variable CDPATH defines the search path
2763              for the directory containing arg.  Alternative  directory  names
2764              are  separated  by  a  colon (:).  The default path is the empty
2765              string (specifying the current directory).  Note that  the  cur‐
2766              rent  directory  may  be  specified by a dot (.)  or by an empty
2767              path name, either of which  can  appear  immediately  after  the
2768              equal  sign or between the colon delimiters anywhere else in the
2769              path list.  If arg begins with a / then the search path  is  not
2770              used.   Otherwise,  each  directory  in the path is searched for
2771              arg.
2772              The second form of cd substitutes the string new for the  string
2773              old  in  the current directory name, PWD, and tries to change to
2774              this new directory.
2775              By default, symbolic link names are treated literally when find‐
2776              ing  the  directory  name.  This is equivalent to the -L option.
2777              The -P option causes symbolic links to be resolved  when  deter‐
2778              mining the directory.  The last instance of -L or -P on the com‐
2779              mand line determines which method is used.
2780              If -e and -P are both in effect and the correct PWD could not be
2781              determined  after  successfully  changing the directory, cd will
2782              return with exit status one and produce no output.  If any other
2783              error  occurs  while  both  flags are active, the exit status is
2784              greater than one.
2785              The cd command may not be executed by rksh.
2787       command [ -pvxV ] name [ arg ... ]
2788              With the -v option, command is equivalent to the built-in whence
2789              command  described  below.   The -V option causes command to act
2790              like whence -v.
2792              Without the -v or -V options, command executes name with the ar‐
2793              guments  given  by  arg.   Functions  and  aliases  will  not be
2794              searched for when finding name.  If name  refers  to  a  special
2795              built-in,  as marked with in this manual, command disables the
2796              special properties described above for that mark, executing  the
2797              command  as a regular built-in.  (For example, using command set
2798              -o option-name prevents a script from terminating  when  an  in‐
2799              valid option name is given.)
2801              The  -p  option causes the operating system's standard utilities
2802              path (as output by getconf PATH) to be searched rather than  the
2803              one defined by the value of PATH.
2805              The  -x option searches for name as an external command, bypass‐
2806              ing built-ins.  If the arguments contain at least one word  that
2807              expands  to  multiple arguments, for example *.txt or "$@", then
2808              the -x option also allows executing external commands with argu‐
2809              ment  lists  that  are  longer than the operating system allows.
2810              This functionality is similar to xargs(1) but is easier to  use.
2811              The  shell  does  this by invoking the external command multiple
2812              times if needed, dividing the expanded argument  list  over  the
2813              invocations.  Any arguments that come before the first word that
2814              expands to multiple arguments, as well as any  that  follow  the
2815              last  such  word,  are repeated for each invocation. This allows
2816              each invocation to use the same command options, as well as  the
2817              same  trailing  destination arguments for commands like cp(1) or
2818              mv(1).  When all invocations are  completed,  command  -x  exits
2819              with the status of the invocation that had the highest exit sta‐
2820              tus.  (Note that command -x may still  fail  with  an  "argument
2821              list  too  long"  error if a single argument exceeds the maximum
2822              length of the argument list, or if a long  arguments  list  con‐
2823              tains no word that expands to multiple arguments.)
2825compound vname[=value] ...
2826              Causes  each vname to be a compound variable.  The same as type‐
2827              set -C.
2829continue [ n ]
2830              Resume the next iteration of the enclosing for, while, until, or
2831              select loop.  If n is specified, then resume at the n-th enclos‐
2832              ing loop.
2834       disown [ job... ]
2835              Causes the shell not to send a HUP signal to each given job,  or
2836              all  active  jobs  if  job is omitted, when a login shell termi‐
2837              nates.
2839       echo [ arg ... ]
2840              When the first arg does not begin with a -, and none of the  ar‐
2841              guments contain a \, then echo prints each of its arguments sep‐
2842              arated by a space and terminated by a new-line.  Otherwise,  the
2843              behavior  of  echo  is  system dependent and print or printf de‐
2844              scribed below should be used.  See echo(1)  for  usage  and  de‐
2845              scription.
2847enum [ -i ] type[=(value ...) ] ...
2848              Creates,  for  each type specified, an enumeration type declara‐
2849              tion command named type.  Variables of the created type can only
2850              store   any   one  of  the  values  given.   For  example,  enum
2851              bool=(false true) creates a Boolean variable type of which vari‐
2852              ables may be declared like bool x=true y=false.  If =(value ...)
2853              is omitted, then type must be an indexed array variable with  at
2854              least  two  elements  and  the  values are taken from this array
2855              variable.  If -i is specified the values  are  case-insensitive.
2856              Declaration commands are created as special builtins that cannot
2857              be removed or overridden by shell functions.  Each created  dec‐
2858              laration  command has a --man option that shows documentation on
2859              its type's behavior and possible values.
2861              Within arithmetic expressions (see Arithmetic Evaluation above),
2862              enumeration type values translate to index numbers between 0 and
2863              the number of defined values minus 1. It  is  an  error  for  an
2864              arithmetic  expression  to assign a value outside of that range.
2865              Decimal fractions are ignored.  Taking the bool  type  from  the
2866              example  above,  if a variable of this type is used in an arith‐
2867              metic expression, false translates to 0 and true to 1.  Enumera‐
2868              tion  values  may also be used directly in an arithmetic expres‐
2869              sion that refers to a variable of an enumeration type.  To  con‐
2870              tinue  our  example,  for  a bool variable v, ((v==true)) is the
2871              same as ((v==1)) and if a variable named true exists, it is  ig‐
2872              nored.
2874eval [ arg ... ]
2875              The  arguments  are read as input to the shell and the resulting
2876              command(s) executed.
2878exec [ -c ] [ -a name ] [ arg ... ]
2879              If arg is given, the command specified by the arguments is  exe‐
2880              cuted  in  place  of  this shell without creating a new process.
2881              The value of the SHLVL environment variable is decreased by one,
2882              unless  the  shell replaced is a subshell.  The -c option causes
2883              the environment to be cleared before applying  variable  assign‐
2884              ments associated with the exec invocation.  The -a option causes
2885              name rather than the first arg, to become argv[0]  for  the  new
2886              process.   If  arg  is  not  given and only I/O redirections are
2887              given, then this command persistently modifies file  descriptors
2888              as in redirect.
2890exit [ n ]
2891              Causes  the  shell  to exit with the exit status specified by n.
2892              The value will be the least significant 8 bits of n  (if  speci‐
2893              fied)  or  of  the exit status of the last command executed.  An
2894              end-of-file will also cause the shell to exit, except for an in‐
2895              teractive shell that has the ignoreeof option turned on (see set
2896              below).
2898       †‡ export [ -p ] [ name[=value] ] ...
2899              If name is not given, the names and values of each variable with
2900              the  export  attribute  are  printed with the values quoted in a
2901              manner that allows them to be re-input.  The export  command  is
2902              the  same  as  typeset -x except that if you use export within a
2903              function, no local variable is created.  The  -p  option  causes
2904              the  word export to be inserted before each one.  Otherwise, the
2905              given names are marked for automatic export to  the  environment
2906              of subsequently-executed commands.
2908       false  Does nothing, and exits 1. Used with until for infinite loops.
2910       fc [ -e ename  ] [ -N num ] [ -nlr ] [ first [ last ] ]
2911       fc -s  [ old=new ] [ command ]
2912              The same as hist.
2914       fg [ job... ]
2915              This  command is only on systems that support job control.  Each
2916              job specified is brought to the foreground and waited for in the
2917              specified order.  Otherwise, the current job is brought into the
2918              foreground.  See Jobs for a description of the format of job.
2920float vname[=value] ...
2921              Declares each vname to be a long  floating  point  number.   The
2922              same as typeset -lE.
2924       functions [ -Stux ] [ name ... ]
2925              Lists functions.  The same as typeset -f.
2927       getconf [ name [ pathname ] ]
2928              Prints the current value of the configuration parameter given by
2929              name.  The configuration parameters  are  defined  by  the  IEEE
2930              POSIX  1003.1 and IEEE POSIX 1003.2 standards.  (See pathconf(2)
2931              and sysconf(3).)  The pathname argument is required for  parame‐
2932              ters whose value depends on the location in the file system.  If
2933              no arguments are given, getconf prints the names and  values  of
2934              the  current  configuration  parameters.  The pathname / is used
2935              for each of the parameters that requires pathname.
2937       getopts [ -a name ] optstring vname [ arg ... ]
2938              Checks arg for legal options.  If arg is omitted, the positional
2939              parameters are used.  An option argument begins with a + or a -.
2940              An option not beginning with + or - or the argument -- ends  the
2941              options.  Options beginning with + are only recognized when opt‐
2942              string begins with a +.  optstring  contains  the  letters  that
2943              getopts recognizes.  If a letter is followed by a :, that option
2944              is expected to have an argument.  The options can  be  separated
2945              from  the  argument by blanks.  The option -?  causes getopts to
2946              generate a usage message on standard error.  The -a argument can
2947              be  used to specify the name to use for the usage message, which
2948              defaults to $0.
2949              getopts places the next option letter it finds  inside  variable
2950              vname  each  time  it  is  invoked.   The  option letter will be
2951              prepended with a + when arg begins with a +.  The index  of  the
2952              next arg is stored in OPTIND.  The option argument, if any, gets
2953              stored in OPTARG.
2954              A leading : in optstring causes getopts to store the  letter  of
2955              an  invalid  option in OPTARG, and to set vname to ?  for an un‐
2956              known option and to : when a required option argument  is  miss‐
2957              ing.  Otherwise, getopts prints an error message.  The exit sta‐
2958              tus is non-zero when there are no more options.
2959              There is no way to specify any of the options :, +, -, ?, [, and
2960              ].  The option # can only be specified as the first option.
2962       hash [ -r ] [ utility ]
2963              hash  displays  or modifies the hash table with the locations of
2964              recently used programs. If given no arguments, it lists all com‐
2965              mand/path  associations  (a.k.a.  'tracked aliases') in the hash
2966              table. Otherwise, hash performs a PATH search for  each  utility
2967              supplied  and  adds the result to the hash table.  The -r option
2968              empties the hash table. This can also be achieved  by  resetting
2969              PATH.
2971       hist [ -e ename  ] [ -N num ] [ -nlr ] [ first [ last ] ]
2972       hist -s [ old=new ] [ command ]
2973              In the first form, a range of commands from first to last is se‐
2974              lected from the last HISTSIZE commands that were  typed  at  the
2975              terminal.   The  arguments  first and last may be specified as a
2976              number or as a string.  A string is used to locate the most  re‐
2977              cent  command starting with the given string.  A negative number
2978              is used as an offset to the current command number.  If  the  -l
2979              option  is selected, the commands are listed on standard output.
2980              Otherwise, the editor program ename is invoked on  a  file  con‐
2981              taining these keyboard commands.  If ename is not supplied, then
2982              the value of the variable HISTEDIT is used.  If HISTEDIT is  not
2983              set,  then FCEDIT (default /bin/ed) is used as the editor.  When
2984              editing is complete, the edited command(s) is  executed  if  the
2985              changes have been saved.  If last is not specified, then it will
2986              be set to first.  If first is not specified, the default is  the
2987              previous command for editing and -16 for listing.  The option -r
2988              reverses the order of the commands and the option -n  suppresses
2989              command  numbers  when  listing.  In the second form, command is
2990              interpreted as first described above and defaults  to  the  last
2991              command  executed.   The resulting command is executed after the
2992              optional substitution  old=new  is  performed.   The  option  -N
2993              causes hist to start num commands back.
2995integer vname[=value] ...
2996              Declares  each  vname  to be a long integer number.  The same as
2997              typeset -li.
2999       jobs [ -lnp ] [ job ... ]
3000              Lists information about each given job; or all  active  jobs  if
3001              job  is omitted.  The -l option lists process IDs in addition to
3002              the normal information.  The -n option only displays  jobs  that
3003              have  stopped  or  exited  since  last  notified.  The -p option
3004              causes only the process group to be listed.  See Jobs for a  de‐
3005              scription of the format of job.
3007       kill [ -s signame ] job ...
3008       kill [ -n signum ] job ...
3009       kill -Ll [ sig ... ]
3010              Sends either the TERM (terminate) signal or the specified signal
3011              to the specified jobs or processes.  Signals are either given by
3012              number  with  the  -n  option  or by name with the -s option (as
3013              given in <signal.h>, stripped of the prefix ``SIG''.  For  back‐
3014              ward compatibility, the n and s can be omitted and the number or
3015              name placed immediately after the -.  If the signal  being  sent
3016              is  TERM  (terminate)  or  HUP (hangup), then the job or process
3017              will be sent a CONT (continue) signal if it is stopped.  The ar‐
3018              gument job can be the process ID of a process that is not a mem‐
3019              ber of one of the active jobs.  See Jobs for  a  description  of
3020              the  format  of  job.  In the third form, kill -l or kill -L, if
3021              sig is not specified, the signal names are listed.  The  -l  op‐
3022              tion lists only the signal names.  The -L option lists each sig‐
3023              nal name and corresponding number.  Otherwise, for each sig that
3024              is  a name, the corresponding signal number is listed.  For each
3025              sig that is a number, the signal name corresponding to the least
3026              significant 8 bits of sig is listed.
3028       let arg ...
3029              Each  arg  is  a separate arithmetic expression to be evaluated.
3030              let only recognizes octal numbers starting with 0 when  the  set
3031              option  letoctal  is  on.  See Arithmetic Evaluation above for a
3032              description of arithmetic expression evaluation.
3033              The exit status is 0 if the value of the last expression is non-
3034              zero, and 1 otherwise.
3036nameref vname[=refname] ...
3037              Declares  each  vname to be a variable name reference.  The same
3038              as typeset -n.
3040       print [ -CRenprsv ] [ -u unit ] [ -f format ] [ arg ... ]
3041              With no options or with option - or --, each arg is  printed  on
3042              standard  output.   The  -f  option  causes  the arguments to be
3043              printed as described by printf.  In this case, any e,  n,  r,  R
3044              options  are  ignored.   Otherwise, unless the -C, -R, -r, or -v
3045              are specified, the following escape conventions will be applied:
3046              \a     The alert character (ASCII 07).
3047              \b     The backspace character (ASCII 010).
3048              \c     Causes print to end without processing more arguments and
3049                     not adding a new-line.
3050              \f     The formfeed character (ASCII 014).
3051              \n     The newline character (ASCII 012).
3052              \r     The carriage return character (ASCII 015).
3053              \t     The tab character (ASCII 011).
3054              \v     The vertical tab character (ASCII 013).
3055              \E     The escape character (ASCII 033).
3056              \\     The backslash character \.
3057              \0x    The  character  defined  by  the  1,  2, or 3-digit octal
3058                     string given by x.
3060              The -R option will print all subsequent  arguments  and  options
3061              other than -n.  The -e causes the above escape conventions to be
3062              applied.  This is the default behavior.  It reverses the  effect
3063              of  an  earlier  -r.   The  -p option causes the arguments to be
3064              written onto the pipe of the process spawned with |& instead  of
3065              standard  output.   The  -v option treats each arg as a variable
3066              name and writes the value in the printf %B format.  The  -C  op‐
3067              tion  treats each arg as a variable name and writes the value in
3068              the printf %#B format.  The -s option causes the arguments to be
3069              written  onto  the history file instead of standard output.  The
3070              -u option can be used to specify a  one  digit  file  descriptor
3071              unit  number  unit  on which the output will be placed.  The de‐
3072              fault is 1.  If the option -n is used, no new-line is  added  to
3073              the output.
3075       printf [ -v vname ] format [ arg ... ]
3076              The  arguments  arg are printed on standard output in accordance
3077              with the ANSI C formatting  rules  associated  with  the  format
3078              string format.  If the number of arguments exceeds the number of
3079              format specifications, the format string is reused to format re‐
3080              maining arguments.  The following extensions can also be used:
3081              %b     A %b format can be used instead of %s to cause escape se‐
3082                     quences in the corresponding arg to be  expanded  as  de‐
3083                     scribed in print.
3084              %B     A %B option causes each of the arguments to be treated as
3085                     variable names and the binary value of variable  will  be
3086                     printed.  The alternate flag # causes a compound variable
3087                     to be output on a single line.  This is most  useful  for
3088                     compound variables and variables whose attribute is -b.
3089              %H     A %H format can be used instead of %s to cause characters
3090                     in arg that are special in HTML and XML to be  output  as
3091                     their entity name.  The alternate flag # formats the out‐
3092                     put for use as a URI.
3093              %p     A %p format will convert the given number to hexadecimal.
3094              %P     A %P format can be used instead of %s to cause arg to  be
3095                     interpreted  as  an  extended  regular  expression and be
3096                     printed as a shell pattern.
3097              %q     A %q format can be used instead of %s to  cause  the  re‐
3098                     sulting string to be quoted in a manner than can be rein‐
3099                     put to the shell.  When q is preceded by the  alternative
3100                     format specifier, #, the string is quoted in manner suit‐
3101                     able as a field in a .csv format file.
3102              %(date-format)T
3103                     A %(date-format)T format can be used to treat an argument
3104                     as a date/time string and to format the date/time accord‐
3105                     ing to the date-format.
3106              %Q     A %Q format will convert the given number of  seconds  to
3107                     readable time.
3108              %R     A  %R format can be used instead of %s to cause arg to be
3109                     interpreted as a shell pattern and to be  printed  as  an
3110                     extended regular expression.
3111              %Z     A %Z format will output a byte whose value is 0.
3112              %d     The precision field of the %d format can be followed by a
3113                     .  and the output base.  In this case, the # flag charac‐
3114                     ter causes base# to be prepended.
3115              #      The  # flag, when used with the %d format without an out‐
3116                     put base, displays the output in powers of 1000 indicated
3117                     by  one  of the following suffixes: k M G T P E, and when
3118                     used with the %i format displays the output in powers  of
3119                     1024 indicated by one of the following suffixes: Ki Mi Gi
3120                     Ti Pi Ei.
3121              =      The = flag centers the output within the specified  field
3122                     width.
3123              L      The  L  flag, when used with the %c or %s formats, treats
3124                     precision as character width instead of byte count.
3125              ,      The , flag, when used with the %d or  %f  formats,  sepa‐
3126                     rates  groups of digits with the grouping delimiter (, on
3127                     groups of 3 in the C locale).
3129              The -v option assigns the output directly to a variable  instead
3130              of  writing it to standard output. This is faster than capturing
3131              the output using a command substitution and avoids the  latter's
3132              stripping  of final linefeed characters (\n). The vname argument
3133              should be a valid variable name, optionally with one or more ar‐
3134              ray  subscripts  in  square brackets.  Note that square brackets
3135              should be quoted to avoid pathname expansion.
3138       pwd [ -LP ]
3139              Outputs the value of the current working directory.  The -L  op‐
3140              tion  is  the default; it prints the logical name of the current
3141              directory.  If the -P option is given, all  symbolic  links  are
3142              resolved  from  the  name.  The last instance of -L or -P on the
3143              command line determines which method is used.
3145       read [ -ACSaprsv ] [ -d delim ] [ -n n ] [ -N n ] [ -t timeout ]  [  -u
3146       unit ] [ vname?prompt ] [ vname ... ]
3147              The  shell  input  mechanism.  One line is read and is broken up
3148              into fields using the characters in IFS as separators.  The  es‐
3149              cape character, \, is used to remove any special meaning for the
3150              next character and for line continuation.  The  first  field  is
3151              assigned  to  the  first  vname,  the second field to the second
3152              vname, etc., with leftover fields assigned to  the  last  vname.
3153              If  vname  is  omitted, then REPLY is used as the default vname.
3154              When vname has the binary attribute and -n or -N  is  specified,
3155              the  bytes  that are read are stored directly into the variable.
3156              If you append ?prompt to the first vname, then read will display
3157              prompt  on  standard error before reading if standard input is a
3158              terminal or pipe; the ? should be  quoted  to  protect  it  from
3159              pathname  expansion.  The exit status is 0 unless an end-of-file
3160              is encountered or read has timed out.  The options for the  read
3161              command have meaning as follows:
3162              -A      Causes  the  variable  vname  to be unset and each field
3163                      that is read to be stored in successive elements of  the
3164                      indexed array vname.
3165              -C      Causes the variable vname to be read as a compound vari‐
3166                      able.  Blanks will be ignored when finding the beginning
3167                      open parenthesis.
3168              -N      Causes n bytes to be read unless an end-of-file has been
3169                      encountered or the read times out because of the -t  op‐
3170                      tion.
3171              -S      Causes  the  line  to be treated like a record in a .csv
3172                      format file so that double quotes can be used  to  allow
3173                      the  delimiter  character  and the new-line character to
3174                      appear within a field.
3175              -a      Same as -A.
3176              -d      Causes the read to continue to the  first  character  of
3177                      delim  instead of the newline control character.  Multi‐
3178                      byte characters for delim are not supported.
3179              -n      Causes at most n bytes to be  read  instead  of  a  full
3180                      line, but will return when reading from a slow device as
3181                      soon as any characters have been read.
3182              -p      Input is read from the current co-process spawned by the
3183                      shell  using  ⎪&.  An end-of-file causes read to discon‐
3184                      nect the co-process so that another can be created.
3185              -r      Raw mode. The \ character is not treated specially.
3186              -s      The input will be saved as  a  command  in  the  history
3187                      file.
3188              -t      Used to specify a timeout in seconds when reading from a
3189                      terminal or pipe.
3190              -u      This option can be used to specify a one-digit file  de‐
3191                      scriptor  unit  unit  to read from.  The file descriptor
3192                      can be opened with the exec or  redirect  built-in  com‐
3193                      mand.   If unit is p, input is read from the current co-
3194                      process as with the -p option.   The  default  value  of
3195                      unit is 0.
3196              -v      The  value  of the first vname will be used as a default
3197                      value when reading from a terminal device.
3199       †‡ readonly [ -p ] [ vname[=value] ] ...
3200              If vname is not given, the names and  values  of  each  variable
3201              with  the  read-only attribute is printed with the values quoted
3202              in a manner that allows them to  be  re-input.   The  -p  option
3203              causes the word readonly to be inserted before each one.  Other‐
3204              wise, the given vnames are marked read-only and these names can‐
3205              not  be  changed  by subsequent assignment.  Unlike typeset -r ,
3206              readonly does not create a function-local scope  and  the  given
3207              vnames  are marked globally read-only by default.  When defining
3208              a type, if the value of a read-only subvariable is not  defined,
3209              the value is required when creating each instance.
3211       redirect
3212              This  command  only  accepts  input/output redirections.  It can
3213              open and close files and modify file descriptors from 0 to 9  as
3214              specified  by  the  input/output  redirection  list (see the In‐
3215              put/Output section above), with the difference that  the  effect
3216              persists  past  the execution of the redirect command.  When in‐
3217              voking another program, file descriptors  greater  than  2  that
3218              were  opened  with this mechanism are only passed on if they are
3219              explicitly redirected to themselves as part  of  the  invocation
3220              (e.g. 4>&4) or if the posix option is set.
3222return [ n ]
3223              Causes  a shell function, dot script (see . and source), or pro‐
3224              file script to return to the invoking shell environment with the
3225              exit  status specified by n.  This status value can use the full
3226              signed integer range as shown by the  commands  getconf  INT_MIN
3227              and  getconf  INT_MAX. A value outside that range will produce a
3228              warning and an exit status of 128.  If n is  omitted,  then  the
3229              value  of  $? is assumed, i.e., the exit status of the last com‐
3230              mand executed is passed on.  If return is invoked while not in a
3231              function,  dot  script,  or  profile script, then it behaves the
3232              same as exit.
3234set [ ±BCGHabefhkmnprstuvx ] [ ±o [ option ] ] ... [ ±A  vname  ]   [
3235       arg ... ]
3236              The options for this command have meaning as follows:
3237              -A      Array  assignment.   Unset the variable vname and assign
3238                      values sequentially from the arg list.  If +A  is  used,
3239                      the variable vname is not unset first.
3240              -B      Enable  brace  group expansion. On by default, except if
3241                      ksh is invoked as sh or rsh.
3242              -C      Prevents redirection > from truncating  existing  files.
3243                      Files  that are created are opened with the O_EXCL mode.
3244                      Requires >| to truncate a file when turned on.
3245              -G      Enables recursive pathname  expansion.   This  adds  the
3246                      double-star  pattern  **  to the pathname expansion (see
3247                      Pathname Expansion above).  By itself,  it  matches  the
3248                      recursive contents of the current directory, which is to
3249                      say, all files and directories in the current  directory
3250                      and  in  all its subdirectories, sub-subdirectories, and
3251                      so on.  If the pathname pattern ends in **/, only direc‐
3252                      tories  and  subdirectories  are matched, including sym‐
3253                      bolic links that point to directories.  A  prefixed  di‐
3254                      rectory  name is not included in the results unless that
3255                      directory was itself found by a  pattern.  For  example,
3256                      dir/** matches the recursive contents of dir but not dir
3257                      itself, whereas di[r]/** matches both dir itself and the
3258                      recursive contents of dir.  Symbolic links to non-direc‐
3259                      tories are not followed.  Symbolic links to  directories
3260                      are  followed if they are specified literally or match a
3261                      pattern as described under Pathname Expansion,  but  not
3262                      if they result from a double-star pattern.
3263              -H      Enable !-style history expansion similar to csh(1).  See
3264                      History Expansion above.
3265              -a      All variables that are assigned a value while  this  op‐
3266                      tion  is on are automatically exported, unless they have
3267                      a dot in their name.  Variables  created  in  namespaces
3268                      declared  with  the  namespace  keyword (see Name Spaces
3269                      above) are only exported while their name space  is  ac‐
3270                      tive.
3271              -b      Prints  job  completion messages as soon as a background
3272                      job changes state  rather  than  waiting  for  the  next
3273                      prompt.  If one of the shell line editors is in use (see
3274                      In-line Editing Options above), the  completion  message
3275                      is inserted directly above the command line being typed.
3276              -e      Unless  contained  in a || or && command, or the command
3277                      following an if while or until command or in  the  pipe‐
3278                      line  following !, if a command has a non-zero exit sta‐
3279                      tus, execute the ERR trap, if set, and exit.  This  mode
3280                      is disabled while reading profiles.
3281              -f      Disables pathname expansion.
3282              -h      Obsolete; no effect.
3283              -k      All  variable assignment arguments are placed in the en‐
3284                      vironment for a command, not just those that precede the
3285                      command name.
3286              -m      Background jobs will run in a separate process group and
3287                      a line will print upon completion.  The exit  status  of
3288                      background  jobs is reported in a completion message.  A
3289                      pipeline will not terminate until all component commands
3290                      of  the  pipeline  have terminated.  On systems with job
3291                      control, this option is turned on automatically for  in‐
3292                      teractive shells.
3293              -n      Read  commands  and check them for syntax errors, but do
3294                      not execute them.  Ignored for interactive shells.
3295              -o      The following argument can be one of the  following  op‐
3296                      tion names:
3297                      allexport
3298                              Same as -a.
3299                      backslashctrl
3300                              The  backslash character \ escapes the next con‐
3301                              trol character in the emacs built-in editor  and
3302                              the  next  erase  or  kill  character  in the vi
3303                              built-in editor.  On by default.
3304                      bgnice  All background jobs are run at a lower priority.
3305                              This is the default mode.
3306                      braceexpand
3307                              Same as -B.
3308                      emacs   Activates  the  emacs-style command line editor.
3309                              See Emacs Editing Mode above.
3310                      errexit Same as -e.
3311                      functrace
3312                              Causes the -x option's state and the DEBUG  trap
3313                              action  to be inherited by functions defined us‐
3314                              ing the function keyword (see  Functions  above)
3315                              instead of being reset to default.  Changes made
3316                              to them within the  function  do  not  propagate
3317                              back  to  the parent scope.  Similarly, this op‐
3318                              tion also causes the DEBUG trap action to be in‐
3319                              herited by subshells.
3320                      globcasedetect
3321                              When  this  option  is  turned on, globbing (see
3322                              Pathname Expansion above) and file name  listing
3323                              and  completion  (see  In-line  Editing  Options
3324                              above) automatically become case-insensitive  on
3325                              file systems where the difference between upper-
3326                              and lowercase is ignored for file names. This is
3327                              transparently  determined for each directory, so
3328                              a path pattern that spans multiple file  systems
3329                              can  be part case-sensitive and part case-insen‐
3330                              sitive.  In more precise terms, each slash-sepa‐
3331                              rated  path  name component pattern p is treated
3332                              as ~(i:p) if its parent directory  exists  on  a
3333                              case-insensitive  file  system.   This option is
3334                              only present on operating systems  that  support
3335                              case-insensitive file systems.
3336                      globstar
3337                              Same as -G.
3338                      gmacs   Activates  the  emacs-style  command line editor
3339                              with modified ^T.  See Emacs Editing Mode above.
3340                      histexpand
3341                              Same as -H.
3342                      histreedit
3343                              If a history expansion (see -H) fails, the  com‐
3344                              mand  line  is  reloaded  into the next prompt's
3345                              edit buffer, allowing corrections.
3346                      histverify
3347                              The results of a history expansion (see -H)  are
3348                              not immediately executed.  Instead, the expanded
3349                              line is loaded into the next prompt's edit  buf‐
3350                              fer, allowing further changes.
3351                      ignoreeof
3352                              An  interactive  shell  will not exit on end-of-
3353                              file.  The command exit must be used.
3354                      keyword Same as -k.
3355                      letoctal
3356                              The let command allows  octal  numbers  starting
3357                              with  0.   On by default if ksh is invoked as sh
3358                              or rsh.
3359                      markdirs
3360                              All directory names resulting from pathname  ex‐
3361                              pansion have a trailing / appended.
3362                      monitor Same as -m.
3363                      multiline
3364                              The  built-in editors will use multiple lines on
3365                              the screen for lines that are  longer  than  the
3366                              width  of the screen.  This may not work for all
3367                              terminals.  The shell uses  the  system  default
3368                              tput(1)  command  to  obtain the terminal escape
3369                              codes for the necessary operations.   Multi-line
3370                              editing is disabled if this fails.  On most sys‐
3371                              tems, setting the TERM variable to  your  termi‐
3372                              nal's type and exporting it corrects this situa‐
3373                              tion.  The multiline option  is  ineffectual  on
3374                              systems  whose  tput(1) command supports neither
3375                              terminfo(5) nor termcap(5) capability names.
3376                      noclobber
3377                              Same as -C.
3378                      noexec  Same as -n.
3379                      noglob  Same as -f.
3380                      nolog   Obsolete; has no effect.
3381                      notify  Same as -b.
3382                      nounset Same as -u.
3383                      pipefail
3384                              The exit status of the entire pipeline  will  be
3385                              that  of  the last component command that exited
3386                              with a non-zero exit status, or zero if no  com‐
3387                              mand  exited  with  a non-zero exit status.  The
3388                              shell will wait for all  component  commands  of
3389                              the pipeline to terminate, instead of only wait‐
3390                              ing for the last component command.
3391                      posix   Enables the POSIX standard mode for maximum com‐
3392                              patibility  with  other compliant shells. At the
3393                              moment that the posix option is  turned  on,  it
3394                              also turns on letoctal and turns off -B/braceex‐
3395                              pand; the reverse is done when posix  is  turned
3396                              back off. (These options can still be controlled
3397                              independently  in  between.)  Furthermore,   the
3398                              posix option is automatically turned on upon in‐
3399                              vocation if the shell is invoked as sh  or  rsh,
3400                              or  if  -o  posix or --posix is specified on the
3401                              shell invocation command line, or when executing
3402                              scripts  without  a #! path with this option ac‐
3403                              tive in the invoking shell. In  that  case,  the
3404                              invoked  shell  will  not import type attributes
3405                              for variables (such  as  integer  or  left/right
3406                              justify) from the environment.
3407                              In addition, while on, the posix option
3408                              •  disables  exporting  variable type attributes
3409                                 to the environment for other ksh processes to
3410                                 import;
3411                              •  disallows  brace  expansion on the results of
3412                                 unquoted expansions  (if  the  -B/braceexpand
3413                                 option is turned back on);
3414                              •  disables  the  special  handling  of repeated
3415                                 isspace class characters in the IFS variable;
3416                              •  causes file descriptors > 2 to be  left  open
3417                                 when invoking another program;
3418                              •  disables the &> redirection shorthand;
3419                              •  disables  fast  filescan  loops of type while
3420                                 inputredirection ;do list ;done;
3421                              •  makes the <> redirection operator default  to
3422                                 redirecting  standard  input  if  no file de‐
3423                                 scriptor number precedes it;
3424                              •  causes the  shell  to  use  a  standard  UNIX
3425                                 pipe(2) instead of a socketpair(2) to connect
3426                                 commands in a pipeline (when reading directly
3427                                 from a pipeline, the <#pattern and <##pattern
3428                                 redirection operators will not work  and  the
3429                                 -n  option  to the read built-in will not re‐
3430                                 turn early when reading from a slow device);
3431                              •  disables the special floating point constants
3432                                 Inf and NaN in arithmetic evaluation so that,
3433                                 e.g., $((inf))  and  $((nan))  refer  to  the
3434                                 variables by those names;
3435                              •  enables  the recognition of a leading zero as
3436                                 introducing an octal number in all arithmetic
3437                                 evaluation contexts, except in the let built-
3438                                 in while letoctal is off;
3439                              •  disables zero-padding of seconds in the  out‐
3440                                 put of the time and times built-ins;
3441                              •  stops  the  .  command  (but not source) from
3442                                 looking up functions defined with  the  func‐
3443                                 tion syntax;
3444                              •  disables  the recognition of unexpanded shell
3445                                 arithmetic expressions for the numerical con‐
3446                                 version  specifiers  of  the  printf built-in
3447                                 command, causing them to print a warning  for
3448                                 operands  that are not valid decimal, 0x-pre‐
3449                                 fixed hexadecimal or  0-prefixed  octal  num‐
3450                                 bers;
3451                              •  disables the special handling of /dev/fd/n in
3452                                 file existence and access test  operators  in
3453                                 test/[  and  [[,  causing these to operate on
3454                                 the file /dev/fd/n in the file system;
3455                              •  disables the recognition of unexpanded  shell
3456                                 arithmetic  expressions in the numerical com‐
3457                                 parison operators -eq, -ne, -gt, -ge, -lt and
3458                                 -le  of  the test/[ built-in command, causing
3459                                 them to accept only decimal numbers as  oper‐
3460                                 ands;
3461                              •  changes  the  test/[ built-in command to make
3462                                 its deprecated expr1 -a expr2  and  expr1  -o
3463                                 expr2 operators work even if expr1 equals "!"
3464                                 or "(" (which means the nonstandard unary  -a
3465                                 file  and  -o  option operators cannot be di‐
3466                                 rectly negated using ! or wrapped  in  paren‐
3467                                 theses); and
3468                              •  disables  a  hack that makes test -t ([ -t ])
3469                                 equivalent to test -t 1 ([ -t 1 ]).
3470                      privileged
3471                              Same as -p.
3472                      showme  When enabled, simple commands or pipelines  pre‐
3473                              ceded by a semicolon (;) will be displayed as if
3474                              the xtrace option were enabled but will  not  be
3475                              executed.   Otherwise, the leading ; will be ig‐
3476                              nored.
3477                      trackall
3478                              Same as -h.
3479                      verbose Same as -v.
3480                      vi      Activates the vi-style command line editor, ini‐
3481                              tially  in  input  mode.   See  Vi  Editing Mode
3482                              above.
3483                      viraw   Obsolete; has no effect.
3484                      xtrace  Same as -x.
3486                      If no option name is supplied, then the  current  option
3487                      settings are printed.
3489              -p      Disables  processing of the $HOME/.profile file and uses
3490                      the file /etc/suid_profile  instead  of  the  ENV  file.
3491                      This  mode is on whenever the effective UID (GID) is not
3492                      equal to the real UID (GID).  Turning  this  off  causes
3493                      the  effective UID and GID to be set to the real UID and
3494                      GID.
3495              -r      Enables the restricted shell.  This option cannot be un‐
3496                      set once set.
3497              -s      Sort the positional parameters lexicographically.
3498              -t      (Obsolete).   Exit  after reading and executing one com‐
3499                      mand.
3500              -u      Treat unset parameters as an  error  when  substituting.
3501                      $@ and $* are exempt.
3502              -v      Print shell input lines as they are read.
3503              -x      Print commands and their arguments as they are executed.
3504              --      Do  not  change any of the options; useful in setting $1
3505                      to a value beginning with -.   If  no  arguments  follow
3506                      this option then the positional parameters are unset.
3508              As an obsolete feature, if the first arg is - then the -x and -v
3509              options are turned off and the next arg is treated as the  first
3510              argument.   Using  +  rather  than  - causes these options to be
3511              turned off.  These options can also be used upon  invocation  of
3512              the  shell.  The current set of options may be found in $-.  Un‐
3513              less -A is specified, the remaining arguments are positional pa‐
3514              rameters  and are assigned, in order, to $1 $2 ....  If no argu‐
3515              ments are given, then the names and values of all variables  are
3516              printed on the standard output.
3518shift [ n ]
3519              The  positional  parameters  from $n+1 ...  are renamed $1 ... ,
3520              default n is 1.  The parameter n can be any  arithmetic  expres‐
3521              sion  that evaluates to a non-negative number less than or equal
3522              to $#.
3524       sleep [ -s ] duration
3525              Suspends execution for the number of decimal  seconds  or  frac‐
3526              tions  of  a second given by duration.  duration can be an inte‐
3527              ger, floating point value or ISO 8601  duration  specifying  the
3528              length of time to sleep.  The option -s causes the sleep builtin
3529              to terminate when it receives any signal.  If  duration  is  not
3530              specified  in  conjunction with -s, sleep will wait for a signal
3531              indefinitely.
3533       source name [ arg ... ]
3534              Same as ., except it is not treated as a special  built-in  com‐
3535              mand.
3537       stop job ...
3538              Sends  a  SIGSTOP  signal  to one or more processes specified by
3539              job, suspending them until they receive SIGCONT.   The  same  as
3540              kill -s STOP.
3542       suspend
3543              Sends a SIGSTOP signal to the main shell process, suspending the
3544              script or child shell session until it receives SIGCONT (for in‐
3545              stance,  when  typing  fg  in  the  parent shell). Equivalent to
3546              kill -s STOP "$$", except that it accepts no  operands  and  re‐
3547              fuses to suspend a login shell.
3549       test expression
3550              The  test and [ commands execute conditional expressions similar
3551              to those specified for the [[ compound command under Conditional
3552              Expressions  above,  but with several important differences. The
3553              =, == and != operators test for string (in)equality without pat‐
3554              tern  matching;  == is nonstandard and unportable. The && and ||
3555              operators are not available. Instead, the -a and -o binary oper‐
3556              ators  can  be  used,  but they are fraught with pitfalls due to
3557              grammatical ambiguities and therefore deprecated in favor of in‐
3558              voking  separate  test commands. Most importantly, as test and [
3559              are simple regular commands, field splitting and pathname expan‐
3560              sion  are  performed  on  all their arguments and all aspects of
3561              regular shell grammar (such as redirection) remain active.  This
3562              is usually harmful, so care must be taken to quote arguments and
3563              expansions to avoid this. To avoid  the  many  pitfalls  arising
3564              from  these  issues,  the [[ compound command should be used in‐
3565              stead. The primary purpose of the test and [ commands is compat‐
3566              ibility with other shells that lack [[.
3568              The  test/[  command  does not parse options except if there are
3569              two arguments and the second is --. To access the  inline  docu‐
3570              mentation  with  an  option  such  as --man, you need one of the
3571              forms test --man -- or [ --man -- ].
3573       times  Displays the accumulated user and system  CPU  times,  one  line
3574              with  the times used by the shell and another with those used by
3575              all of the shell's child processes. No  options  are  supported.
3576              Seconds are zero-padded unless the posix shell option is on.
3578trap [ -p ] [ action ] [ sig ] ...
3579              The  -p  option causes the trap action associated with each trap
3580              as specified by the arguments to  be  printed  with  appropriate
3581              quoting.   Otherwise,  action will be processed as if it were an
3582              argument to eval when the shell receives  signal(s)  sig.   Each
3583              sig can be given as a number or as the name of the signal.  Trap
3584              commands are executed in order of signal number.  Any attempt to
3585              set  a trap on a signal that was ignored on entry to the current
3586              shell is ineffective.  If action is omitted and the first sig is
3587              a  number,  or if action is -, then the trap(s) for each sig are
3588              reset to their original values.  If action is the empty  string,
3589              then  this signal is ignored by the shell and by the commands it
3590              invokes.  If sig is ERR then action will be executed whenever  a
3591              command has a non-zero exit status.  If sig is DEBUG then action
3592              will be executed before each command.  The variable  .sh.command
3593              will contain the current command line when action is running, in
3594              the same format as the output generated  by  the  xtrace  option
3595              (minus  the  preceding  PS4  prompt).  If the exit status of the
3596              trap is 2 the command will not be executed.  If the exit  status
3597              of  the  trap  is 255 and inside a function or a dot script, the
3598              function or dot script will return.  If sig is 0 or EXIT and the
3599              trap statement is executed inside the body of a function defined
3600              with the function name syntax, then the command action  is  exe‐
3601              cuted  after  the function completes.  If sig is 0 or EXIT for a
3602              trap set outside any function then the command  action  is  exe‐
3603              cuted on exit from the shell.  If sig is KEYBD, then action will
3604              be executed whenever a key is read while in emacs, gmacs, or  vi
3605              mode.   The trap command with no arguments prints a list of com‐
3606              mands associated with each signal number.
3608       An exit or return without an argument in a trap  action  will  preserve
3609       the exit status of the command that invoked the trap.
3611       true   Does nothing, and exits 0. Used with while for infinite loops.
3613       type [ -afpPqt ] name ...
3614              The same as whence -v.
3616       †‡  typeset [ ±ACHSbflmnprstux ] [ ±EFLRXZi[n] ]   [ +-M  [ mapname ] ]
3617       [ -T  [ tname=(assign_list) ] ] [ -h  str  ]  [  -a  [  [type]  ]  ]  [
3618       vname[=value ]  ] ...
3619              Sets  attributes  and  values for shell variables and functions.
3620              When invoked inside a function defined with  the  function  name
3621              syntax, a new instance of the variable vname is created, and the
3622              variable's value and type are restored when  the  function  com‐
3623              pletes.  The following list of attributes may be specified:
3624              -A     Declares  vname  to  be an associative array.  Subscripts
3625                     are strings rather than arithmetic expressions.
3626              -C     Causes each vname to be a  compound  variable.  If  value
3627                     names a compound variable, it is copied into vname.  Oth‐
3628                     erwise, the empty compound value is assigned to vname.
3629              -a     Declares vname to be an indexed array. This  is  the  de‐
3630                     fault.  Subscripts are numerical and start at 0.  To make
3631                     it possible to use alphanumeric enumeration constants  of
3632                     a  given  type as subscripts, an option value of the form
3633                     [type] can be specified (including the surrounding square
3634                     brackets),  which  should be quoted to avoid pathname ex‐
3635                     pansion), where type must be the name of  an  enumeration
3636                     type created with the enum command.
3637              -E     Declares  vname  to  be a double precision floating point
3638                     number.  If n is non-zero, it defines the number of  sig‐
3639                     nificant  figures  that  are  used  when expanding vname.
3640                     Otherwise, ten significant figures will be used.
3641              -F     Declares vname to be a double  precision  floating  point
3642                     number.   If  n  is  non-zero,  it  defines the number of
3643                     places after the decimal point that are used when expand‐
3644                     ing  vname.  Otherwise ten places after the decimal point
3645                     will be used.
3646              -H     This option provides UNIX to host-name  file  mapping  on
3647                     non-UNIX machines.
3648              -L     Left  justify and remove leading blanks from value.  If n
3649                     is non-zero, it defines the width of the field, otherwise
3650                     it  is  determined by the width of the value of first as‐
3651                     signment.  When the variable is assigned to, it is filled
3652                     on  the  right with blanks or truncated, if necessary, to
3653                     fit into the field.  The -R option is turned off.
3654              -M     Use the character mapping mapping defined by  wctrans(3).
3655                     such  as  tolower  and  toupper when assigning a value to
3656                     each of the specified operands.  When mapping  is  speci‐
3657                     fied  and  there are not operands, all variables that use
3658                     this mapping are written to standard output.   When  map‐
3659                     ping  is  omitted  and  there are no operands, all mapped
3660                     variables are written to standard output.
3661              -R     Right justify and fill with leading blanks.  If n is non-
3662                     zero,  it defines the width of the field, otherwise it is
3663                     determined by the width of the value of first assignment.
3664                     The  field  is  left filled with blanks or truncated from
3665                     the end if the variable is reassigned.  The -L option  is
3666                     turned off.
3667              -S     When used within the assign_list of a type definition, it
3668                     causes the specified subvariable to be shared by all  in‐
3669                     stances of the type.  When used inside a function defined
3670                     with the function reserved word, the specified  variables
3671                     will have function static scope.  Otherwise, the variable
3672                     is unset prior to processing the assignment list.
3673              -T     If followed by tname, it creates a type  named  by  tname
3674                     using the compound assignment assign_list to tname.  Oth‐
3675                     erwise, it writes all the type  definitions  to  standard
3676                     output.
3677              -X     Declares  vname  to  be a double precision floating point
3678                     number and expands using the %a format of ISO-C99.  If  n
3679                     is  non-zero,  it  defines the number of hex digits after
3680                     the radix point that is used when expanding  vname.   The
3681                     default is 10.
3682              -Z     Right  justify  and  fill with leading zeros if the first
3683                     non-blank character is a digit and the -L option has  not
3684                     been  set.  Remove leading zeros if the -L option is also
3685                     set.  If n is non-zero,  it  defines  the  width  of  the
3686                     field,  otherwise  it  is  determined by the width of the
3687                     value of first assignment.
3688              -f     The names refer to function names  rather  than  variable
3689                     names.   No  assignments  can  be made and the only other
3690                     valid options are -S, -t, -u and -x.  The -S can be  used
3691                     with  discipline  functions defined in a type to indicate
3692                     that the function is static.  For a static function,  the
3693                     same method will be used by all instances of that type no
3694                     matter which instance references it.  In addition, it can
3695                     only  use value of variables from the original type defi‐
3696                     nition.  These discipline functions cannot  be  redefined
3697                     in  any  type instance.  The -t option turns on execution
3698                     tracing for this function.  The  -u  option  causes  this
3699                     function to be marked undefined.  The FPATH variable will
3700                     be searched to find  the  function  definition  when  the
3701                     function  is  referenced.  If no options other than -f is
3702                     specified, then the function definition will be displayed
3703                     on standard output.  If +f is specified, then a line con‐
3704                     taining the function name followed  by  a  shell  comment
3705                     containing  the  line  number  and  path name of the file
3706                     where this function was defined, if  any,  is  displayed.
3707                     The  exit  status  can  be  used to determine whether the
3708                     function is defined so that typeset -f .sh.math.name will
3709                     return  0 when math function name is defined and non-zero
3710                     otherwise.
3711              -b     The variable can hold any number of bytes of  data.   The
3712                     data  can be text or binary.  The value is represented by
3713                     the base64 encoding of the data.  If -Z  is  also  speci‐
3714                     fied, the size in bytes of the data in the buffer will be
3715                     determined by the size associated with the  -Z.   If  the
3716                     base64  string  assigned results in more data, it will be
3717                     truncated.  Otherwise, it will be filled with bytes whose
3718                     value  is zero.  The printf format %B can be used to out‐
3719                     put the actual data in this buffer instead of the  base64
3720                     encoding of the data.
3721              -g     Forces  variables to be created or modified at the global
3722                     scope, even when typeset is executed in  a  function  de‐
3723                     fined  by  the function name syntax (see Functions above)
3724                     or in a name space (see Name Spaces above).
3725              -h     Used within type definitions to add information when gen‐
3726                     erating  information  about  the  subvariable  on the man
3727                     page.  It is ignored when used outside of a type  defini‐
3728                     tion.   When  used  with -f the information is associated
3729                     with the corresponding discipline function.
3730              -i     Declares vname to be represented internally  as  integer.
3731                     The  right  hand side of an assignment is evaluated as an
3732                     arithmetic expression when assigning to an integer.  If n
3733                     is  non-zero, it defines the output arithmetic base, oth‐
3734                     erwise the output base will be ten.
3735              -l     Used with -i, -E or -F, to indicate long integer, or long
3736                     float.  Otherwise, all uppercase characters are converted
3737                     to lowercase.  The uppercase option, -u, is  turned  off.
3738                     Equivalent to -M tolower .
3739              -m     Moves  or renames the variable.  The value is the name of
3740                     a variable whose value will be moved to vname.  The orig‐
3741                     inal  variable  will  be  unset.  Cannot be used with any
3742                     other options.
3743              -n     Declares vname to be a reference to  the  variable  whose
3744                     name  is defined by the value of variable vname.  This is
3745                     usually used to reference a variable  inside  a  function
3746                     whose  name  has  been  passed as an argument.  Cannot be
3747                     used with other options except -g.
3748              -p     The name, attributes and values for the given vnames  are
3749                     written  on standard output in a form that can be used as
3750                     shell input.  If +p is specified, then the values are not
3751                     displayed.
3752              -r     The  given  vnames  are  marked read-only and these names
3753                     cannot be changed by subsequent assignment.
3754              -s     When given along  with  -i,  restricts  integer  size  to
3755                     short.
3756              -t     Tags  the variables.  Tags are user definable and have no
3757                     special meaning to the shell.
3758              -u     When given along with  -i,  specifies  unsigned  integer.
3759                     Otherwise,  all lowercase characters are converted to up‐
3760                     percase.   The  lowercase  option,  -l,  is  turned  off.
3761                     Equivalent to -M toupper .
3762              -x     The  given  vnames are marked for automatic export to the
3763                     environment of subsequently-executed commands.  Variables
3764                     whose names contain a .  cannot be exported.
3766              The  -i,  -F,  -E, and -X options cannot be specified along with
3767              -R, -L, or -Z.  The -b option cannot be specified along with -L,
3768              -u,  or  -l.   The -f, -m, -n, and -T options cannot be used to‐
3769              gether with any other option.
3771              Using + rather than - causes these options to be turned off.  If
3772              no  vname  arguments are given, a list of vnames (and optionally
3773              the values) of the variables is printed.  (Using + rather than -
3774              keeps  the  values  from  being  printed.)  The -p option causes
3775              typeset followed by the option letters to be printed before each
3776              name  rather than the names of the options.  If any option other
3777              than -p is given, only those variables which  have  all  of  the
3778              given options are printed.  Otherwise, the vnames and attributes
3779              of all variables that have attributes are printed.
3781       ulimit [ -HSaMctdfkxlqenVuPpmrRbiswTv ] [ limit ]
3782              Set or display a resource limit.  The available resource  limits
3783              are  listed  below.   Many systems do not support one or more of
3784              these limits.  The limit for a specified resource  is  set  when
3785              limit  is  specified.  The value of limit can be a number in the
3786              unit specified below with each resource, or the value unlimited.
3787              The -H and -S options specify whether the hard limit or the soft
3788              limit for the given resource is set.  A hard limit cannot be in‐
3789              creased once it is set.  A soft limit can be increased up to the
3790              value of the hard limit.  If neither the H nor S option is spec‐
3791              ified, the limit applies to both.  The current resource limit is
3792              printed when limit is omitted.  In this case, the soft limit  is
3793              printed  unless  H is specified.  When more than one resource is
3794              specified, then the limit name and unit is  printed  before  the
3795              value.
3796              -a     Lists all of the current resource limits.
3797              -b     The socket buffer size in bytes.
3798              -c     The number of 512-byte blocks on the size of core dumps.
3799              -d     The number of K-bytes on the size of the data area.
3800              -e     The scheduling priority.
3801              -f     The  number of 512-byte blocks on files that can be writ‐
3802                     ten by the current process or by child  processes  (files
3803                     of any size may be read).
3804              -i     The signal queue size.
3805              -k     The max number of kqueues created by the current user.
3806              -l     The locked address space in K-bytes.
3807              -M     The address space limit in K-bytes.
3808              -m     The number of K-bytes on the size of physical memory.
3809              -n     The number of file descriptors plus 1.
3810              -P     The max number of pseudo-terminals created by the current
3811                     user.
3812              -p     The number of 512-byte blocks for pipe buffering.
3813              -q     The message queue size in K-bytes.
3814              -R     The max time a real-time process can run before blocking,
3815                     in  microseconds.   If this limit is exceeded the process
3816                     is sent a SIGXCPU signal.
3817              -r     The max real-time priority.
3818              -s     The number of K-bytes on the size of the stack area.
3819              -T     The number of threads.
3820              -t     The number of CPU seconds to be used by each process.
3821              -u     The number of processes.
3822              -V     The number of open vnode monitors.
3823              -v     The number of K-bytes for virtual memory.
3824              -w     The swap size in K-bytes.
3825              -x     The number of file locks.
3827              If no option is given, -f is assumed.
3829       umask [ -S ] [ mask ]
3830              The user file-creation mask is set to mask (see umask(2)).  mask
3831              can  either  be an octal number or a symbolic value as described
3832              in chmod(1).  If a symbolic value is given, the new umask  value
3833              is  the complement of the result of applying mask to the comple‐
3834              ment of the previous umask value.  If mask is omitted, the  cur‐
3835              rent  value  of  the  mask is printed.  The -S option causes the
3836              mode to be printed as a symbolic value.  Otherwise, the mask  is
3837              printed in octal.
3839       unalias [ -a ] name ...
3840              The  aliases  given  by  the  list of names are removed from the
3841              alias list.  The -a option causes all the aliases to be unset.
3843unset [ -fnv ] vname ...
3844              The variables given by the list of vnames are unassigned,  i.e.,
3845              except  for  subvariables  within  a  type, their values and at‐
3846              tributes are erased.  For subvariables of a type, the values are
3847              reset  to  the default value from the type definition.  Readonly
3848              variables cannot be unset.  If the -f option is  set,  then  the
3849              names  refer  to  function names.  If the -v option is set, then
3850              the names refer to variable names.  The -f option overrides  -v.
3851              If -n is set and name is a name reference, then name will be un‐
3852              set rather than the variable that it references.  The default is
3853              equivalent  to -v.  Unsetting LINENO, MAILCHECK, OPTARG, OPTIND,
3854              RANDOM, SECONDS, TMOUT, and _ removes their special meaning even
3855              if they are subsequently assigned to.
3857       wait [ job ... ]
3858              Wait  for  the  specified job and report its termination status.
3859              If job is not given, then all currently active  child  processes
3860              are  waited  for.   The exit status from this command is that of
3861              the last process waited for if job is specified; otherwise it is
3862              zero.  See Jobs for a description of the format of job.
3864       whence [ -afpPqtv ] name ...
3865              For each name, indicate how it would be interpreted if used as a
3866              command name.
3867              The -v option produces a more verbose  report.   The  -f  option
3868              skips the search for functions.  The -p and -P options do a path
3869              search for name even if name is an alias, a function, or  a  re‐
3870              served word.  Both of these options turn off the -v option.  The
3871              -q option causes whence to enter quiet mode.  whence will return
3872              zero  if all arguments are built-ins, functions, or are programs
3873              found on the path.  The -t option only outputs the type  of  the
3874              given  command.  Like -p and -P, -t will turn off the -v option.
3875              The -a option is similar to the -v option but causes all  inter‐
3876              pretations of the given name to be reported.
3878   Invocation.
3879       If  the shell is invoked by exec(2), initialization depends on argument
3880       zero ($0) as follows.  If the first character of $0 is -, or the -l op‐
3881       tion is given on the invocation command line, then the shell is assumed
3882       to be a login shell.  If the basename of the command path in $0 is rsh,
3883       rksh,  or  krsh, then the shell becomes restricted.  If the basename is
3884       sh or rsh, or the -o posix option is given on  the  invocation  command
3885       line,  then the shell is initialized in full POSIX compliance mode (see
3886       the set builtin command above for more information).   After  this,  if
3887       the  shell  was  assumed  to  be  a login shell, commands are read from
3888       /etc/profile and then from $HOME/.profile if it exists.  Alternatively,
3889       the  option  -l causes the shell to be treated as a login shell.  Next,
3890       for interactive shells, commands are read from the file named by ENV if
3891       the  file exists, its name being determined by performing parameter ex‐
3892       pansion, command substitution, and arithmetic expansion on the value of
3893       that environment variable.  If the -s option is not present and arg and
3894       a file by the name of arg exists,  then  it  reads  and  executes  this
3895       script.   Otherwise,  if  the  first  arg  does not contain a /, a path
3896       search is performed on the first arg  to  determine  the  name  of  the
3897       script to execute.  The script arg must have execute permission and any
3898       setuid and setgid settings will be ignored.  If the script is not found
3899       on  the  path,  arg  is  processed as if it named a built-in command or
3900       function.  Commands are then read as described below; the following op‐
3901       tions are interpreted by the shell when it is invoked:
3903       -D      A  list  of  all double quoted strings that are preceded by a $
3904               will be printed on standard output and  the  shell  will  exit.
3905               This  set  of  strings  will be subject to language translation
3906               when the locale is not C or POSIX.  No commands  will  be  exe‐
3907               cuted.
3909       -E or -o rc or --rc
3910               Read  the  file named by the ENV variable or by $HOME/.kshrc if
3911               not defined after the profiles.  On by default for  interactive
3912               shells. Use +E, +o rc or --norc to turn off.
3914       -c      Read and execute a script from the first arg instead of a file.
3915               The second arg, if present, becomes that script's command  name
3916               ($0).   Any third and further args become positional parameters
3917               starting at $1.
3919       -s      Read and execute a script from  standard  input  instead  of  a
3920               file.   The  command  name ($0) cannot be set.  Any args become
3921               the positional parameters  starting  at  $1.   This  option  is
3922               forced on if no arg is given and is ignored if -c is also spec‐
3923               ified.
3925       -i or -o interactive or --interactive
3926               If the -i option is present or if the  shell's  standard  input
3927               and standard error are attached to a terminal (as told by tcge‐
3928               tattr(3)), then this shell is interactive.  In this  case  TERM
3929               is  ignored (so that kill 0 does not kill an interactive shell)
3930               and INTR is caught and ignored (so that wait is interruptible).
3931               In all cases, QUIT is ignored by the shell.
3933       -r or -o restricted or --restricted
3934               If the -r option is present, the shell is a restricted shell.
3936       The remaining options and arguments are described under the set command
3937       above.  An optional - as the first argument is ignored.
3939   Rksh Only.
3940       Rksh is used to set up login names and execution environments whose ca‐
3941       pabilities  are  more controlled than those of the standard shell.  The
3942       actions of rksh are identical to those of ksh, except that the  follow‐
3943       ing are disallowed:
3945              •      unsetting the restricted option
3947              •      changing directory (see cd(1))
3949              •      setting  or  unsetting  the value or attributes of SHELL,
3950                     ENV, FPATH, or PATH
3952              •      specifying path or command names containing /
3954              •      redirecting output (>, >|, <>, and >>)
3956              •      adding or deleting built-in commands
3958              •      using command -p to invoke a command
3960       The restrictions above are enforced after .profile and  the  ENV  files
3961       are interpreted.
3963       When  a  command  to be executed is found to be a shell procedure, rksh
3964       invokes ksh to execute it.  Thus, it is possible to provide to the end-
3965       user  shell  procedures that have access to the full power of the stan‐
3966       dard shell, while imposing a limited menu of commands; this scheme  as‐
3967       sumes  that the end-user does not have write and execute permissions in
3968       the same directory.
3970       The net effect of these rules is that the writer of  the  .profile  has
3971       complete  control over user actions, by performing guaranteed setup ac‐
3972       tions and leaving the user in an appropriate  directory  (probably  not
3973       the login directory).
3975       The  system  administrator often sets up a directory of commands (e.g.,
3976       /usr/rbin) that can be safely invoked by rksh.


3979       Errors detected by the shell, such as syntax errors, cause the shell to
3980       return a non-zero exit status.  If the shell is being used non-interac‐
3981       tively, then execution of the shell file is abandoned unless the  error
3982       occurs inside a subshell in which case the subshell is abandoned.  Oth‐
3983       erwise, the shell returns the exit status of the last command  executed
3984       (see  also  the  exit  command above).  Run time errors detected by the
3985       shell are reported by printing the command or function name and the er‐
3986       ror  condition.   If  the  line  number  that  the error occurred on is
3987       greater than one, then the line number is also printed in square brack‐
3988       ets ([]) after the command or function name.


3991       /etc/profile
3992              The system wide initialization file, executed for login shells.
3994       $HOME/.profile
3995              The  personal initialization file, executed for login shells af‐
3996              ter /etc/profile.
3998       $HOME/.kshrc
3999              Default personal initialization file, executed  for  interactive
4000              shells when ENV is not set.
4002       /etc/suid_profile
4003              Alternative  initialization  file,  executed instead of the per‐
4004              sonal initialization file when the real and  effective  user  or
4005              group ID do not match.
4007       /dev/null
4008              The null device.


4011       cat(1),  cd(1),  chmod(1),  cut(1), date(1), echo(1), emacs(1), env(1),
4012       gmacs(1), grep(1), stty(1), test(1), umask(1), vi(1), dup(2),  exec(2),
4013       fork(2),   getpwnam(3),   ioctl(2),  lseek(2),  paste(1),  pathconf(2),
4014       pipe(2), sysconf(3), umask(2),  ulimit(2),  wait(2),  strftime(3),  wc‐
4015       trans(3), rand(3), a.out(5), profile(5), environ(7).
4017       Morris  I. Bolsky and David G. Korn, The New KornShell Command and Pro‐
4018       gramming Language, Prentice Hall, 1995.
4020       POSIX - Part 2: Shell and  Utilities,  IEEE  Std  1003.2-1992,  ISO/IEC
4021       9945-2, IEEE, 1993.


4024       If  a command is executed, and then a command with the same name is in‐
4025       stalled in a directory in the search path before  the  directory  where
4026       the  original  command  was  found, the shell will continue to exec the
4027       original command.  Use the hash command or the -t option of  the  alias
4028       command to correct this situation.
4030       Using  the  hist  built-in command within a compound command will cause
4031       the whole command to disappear from the history file.
4033       The built-in command . file reads the whole file  before  any  commands
4034       are  executed.   Therefore, alias and unalias commands in the file will
4035       not apply to any commands defined in the file.
4037       Traps are not processed  while  a  job  is  waiting  for  a  foreground
4038       process.   Thus,  a trap on CHLD won't be executed until the foreground
4039       job terminates.
4041       In locales that use a multibyte character set such as UTF-8, the  KEYBD
4042       trap is only triggered for ASCII characters (1-127).
4044       It  is  a good idea to leave a space after the comma operator in arith‐
4045       metic expressions to prevent the comma from being  interpreted  as  the
4046       decimal point character in certain locales.
4050                                                                        KSH(1)