1ZSHBUILTINS(1)              General Commands Manual             ZSHBUILTINS(1)
2
3
4

NAME

6       zshbuiltins - zsh built-in commands
7

SHELL BUILTIN COMMANDS

9       Some shell builtin commands take options as described in individual en‐
10       tries; these are often referred to in the  list  below  as  `flags'  to
11       avoid  confusion  with  shell options, which may also have an effect on
12       the behaviour of builtin commands.  In this introductory section,  `op‐
13       tion'  always  has the meaning of an option to a command that should be
14       familiar to most command line users.
15
16       Typically, options are single letters preceded by a  hyphen  (-).   Op‐
17       tions  that take an argument accept it either immediately following the
18       option letter or after white space, for example `print -C3  {1..9}'  or
19       `print  -C  3 {1..9}' are equivalent.  Arguments to options are not the
20       same as arguments to the command; the documentation indicates which  is
21       which.   Options that do not take an argument may be combined in a sin‐
22       gle word, for example `print -rca -- *' and `print -r -c -a --  *'  are
23       equivalent.
24
25       Some  shell  builtin commands also take options that begin with `+' in‐
26       stead of `-'.  The list below makes clear which commands these are.
27
28       Options (together with their individual arguments, if any) must  appear
29       in  a  group before any non-option arguments; once the first non-option
30       argument has been found, option processing is terminated.
31
32       All builtin commands other than `echo' and precommand  modifiers,  even
33       those that have no options, can be given the argument `--' to terminate
34       option processing.  This indicates that the following words are non-op‐
35       tion  arguments,  but  is  otherwise  ignored.  This is useful in cases
36       where arguments to the command may begin with `-'.  For historical rea‐
37       sons,  most builtin commands (including `echo') also recognize a single
38       `-' in a separate word for this purpose; note that this is  less  stan‐
39       dard and use of `--' is recommended.
40
41       - simple command
42              See the section `Precommand Modifiers' in zshmisc(1).
43
44       . file [ arg ... ]
45              Read  commands  from  file and execute them in the current shell
46              environment.
47
48              If file does not contain a slash, or if PATH_DIRS  is  set,  the
49              shell  looks  in  the  components of $path to find the directory
50              containing file.  Files in the current directory  are  not  read
51              unless  `.'  appears  somewhere  in  $path.   If  a  file  named
52              `file.zwc' is found, is newer than file,  and  is  the  compiled
53              form  (created with the zcompile builtin) of file, then commands
54              are read from that file instead of file.
55
56              If any arguments arg are given, they become the  positional  pa‐
57              rameters;  the  old  positional parameters are restored when the
58              file is done executing.  However, if no arguments are given, the
59              positional  parameters  remain those of the calling context, and
60              no restoring is done.
61
62              If file was not found the return status  is  127;  if  file  was
63              found  but  contained  a  syntax error the return status is 126;
64              else the return status is the exit status of  the  last  command
65              executed.
66
67       : [ arg ... ]
68              This  command  does nothing, although normal argument expansions
69              is performed which may have effects on shell parameters.  A zero
70              exit status is returned.
71
72       alias [ {+|-}gmrsL ] [ name[=value] ... ]
73              For  each  name with a corresponding value, define an alias with
74              that value.  A trailing space in value causes the next  word  to
75              be  checked for alias expansion.  If the -g flag is present, de‐
76              fine a global alias; global aliases are expanded even if they do
77              not occur in command position.
78
79              If the -s flag is present, define a suffix alias: if the command
80              word on a command line is in the form `text.name', where text is
81              any  non-empty  string,  it  is  replaced  by  the  text  `value
82              text.name'.  Note that name is treated as a literal string,  not
83              a  pattern.   A  trailing  space in value is not special in this
84              case.  For example,
85
86                     alias -s ps='gv --'
87
88              will cause the command `*.ps' to be expanded to  `gv  --  *.ps'.
89              As  alias  expansion  is  carried out earlier than globbing, the
90              `*.ps' will then be expanded.  Suffix aliases constitute a  dif‐
91              ferent name space from other aliases (so in the above example it
92              is still possible to create an alias for the command ps) and the
93              two sets are never listed together.
94
95              For  each  name  with no value, print the value of name, if any.
96              With no arguments, print all  currently  defined  aliases  other
97              than  suffix aliases.  If the -m flag is given the arguments are
98              taken as patterns (they should be quoted to preserve  them  from
99              being  interpreted  as  glob patterns), and the aliases matching
100              these patterns are printed.  When printing aliases  and  one  of
101              the  -g,  -r  or  -s  flags is present, restrict the printing to
102              global, regular or suffix aliases, respectively; a regular alias
103              is one which is neither a global nor a suffix alias.   Using `+'
104              instead of `-', or ending the option list  with  a  single  `+',
105              prevents the values of the aliases from being printed.
106
107              If  the  -L  flag  is present, then print each alias in a manner
108              suitable for putting in a startup script.  The  exit  status  is
109              nonzero  if  a  name (with no value) is given for which no alias
110              has been defined.
111
112              For more on aliases, include common problems,  see  the  section
113              ALIASING in zshmisc(1).
114
115       autoload [ {+|-}RTUXdkmrtWz ] [ -w ] [ name ... ]
116              See  the  section `Autoloading Functions' in zshmisc(1) for full
117              details.  The fpath parameter will be searched to find the func‐
118              tion definition when the function is first referenced.
119
120              If name consists of an absolute path, the function is defined to
121              load from the file given (searching as usual for dump  files  in
122              the  given  location).  The name of the function is the basename
123              (non-directory part) of the file.  It is normally  an  error  if
124              the function is not found in the given location; however, if the
125              option -d is given,  searching  for  the  function  defaults  to
126              $fpath.  If a function is loaded by absolute path, any functions
127              loaded from it that are marked for autoload without an  absolute
128              path  have  the  load  path  of  the parent function temporarily
129              prepended to $fpath.
130
131              If the option -r or -R is given, the function  is  searched  for
132              immediately and the location is recorded internally for use when
133              the function is executed; a relative path is expanded using  the
134              value  of  $PWD.  This protects against a change to $fpath after
135              the call to autoload.  With -r, if the function is not found, it
136              is  silently  left unresolved until execution; with -R, an error
137              message is printed and command  processing  aborted  immediately
138              the  search  fails,  i.e. at the autoload command rather than at
139              function execution..
140
141              The flag -X may be used only inside a shell function.  It causes
142              the calling function to be marked for autoloading and then imme‐
143              diately loaded and executed, with the  current  array  of  posi‐
144              tional parameters as arguments.  This replaces the previous def‐
145              inition of the function.  If no function definition is found, an
146              error  is  printed and the function remains undefined and marked
147              for autoloading.  If an argument is given, it is used as  a  di‐
148              rectory  (i.e.  it does not include the name of the function) in
149              which the function is to be found; this may be combined with the
150              -d  option  to allow the function search to default to $fpath if
151              it is not in the given location.
152
153              The flag +X attempts to load each name as  an  autoloaded  func‐
154              tion,  but  does  not execute it.  The exit status is zero (suc‐
155              cess) if the function was not previously defined and  a  defini‐
156              tion for it was found.  This does not replace any existing defi‐
157              nition of the function.  The exit status is nonzero (failure) if
158              the  function  was  already  defined  or  when no definition was
159              found.  In the latter case the function  remains  undefined  and
160              marked  for  autoloading.   If ksh-style autoloading is enabled,
161              the function created will contain the contents of the file  plus
162              a call to the function itself appended to it, thus giving normal
163              ksh autoloading behaviour on the first call to the function.  If
164              the  -m flag is also given each name is treated as a pattern and
165              all functions already marked for autoload that match the pattern
166              are loaded.
167
168              With  the  -t  flag, turn on execution tracing; with -T, turn on
169              execution tracing only for the current function, turning it  off
170              on  entry  to any called functions that do not also have tracing
171              enabled.
172
173              With the -U flag, alias expansion is suppressed when  the  func‐
174              tion is loaded.
175
176              With the -w flag, the names are taken as names of files compiled
177              with the zcompile builtin, and all functions defined in them are
178              marked for autoloading.
179
180              The flags -z and -k mark the function to be autoloaded using the
181              zsh or ksh style, as if the option KSH_AUTOLOAD  were  unset  or
182              were  set,  respectively.  The flags override the setting of the
183              option at the time the function is loaded.
184
185              Note that the autoload command makes no attempt  to  ensure  the
186              shell  options  set  during the loading or execution of the file
187              have any particular value.  For this, the emulate command can be
188              used:
189
190                     emulate zsh -c 'autoload -Uz func'
191
192              arranges that when func is loaded the shell is in native zsh em‐
193              ulation, and this emulation is also applied when func is run.
194
195              Some of the functions of autoload are also provided by functions
196              -u  or functions -U, but autoload is a more comprehensive inter‐
197              face.
198
199       bg [ job ... ]
200       job ... &
201              Put each specified job in the background, or the current job  if
202              none is specified.
203
204       bindkey
205              See the section `Zle Builtins' in zshzle(1).
206
207       break [ n ]
208              Exit from an enclosing for, while, until, select or repeat loop.
209              If an arithmetic expression n is specified, then break n  levels
210              instead of just one.
211
212       builtin name [ args ... ]
213              Executes the builtin name, with the given args.
214
215       bye    Same as exit.
216
217       cap    See the section `The zsh/cap Module' in zshmodules(1).
218
219       cd [ -qsLP ] [ arg ]
220       cd [ -qsLP ] old new
221       cd [ -qsLP ] {+|-}n
222              Change  the  current  directory.   In the first form, change the
223              current directory to arg, or to the value of $HOME if arg is not
224              specified.  If arg is `-', change to the previous directory.
225
226              Otherwise,  if arg begins with a slash, attempt to change to the
227              directory given by arg.
228
229              If arg does not begin with a slash,  the  behaviour  depends  on
230              whether the current directory `.' occurs in the list of directo‐
231              ries contained in the shell parameter cdpath.  If it  does  not,
232              first  attempt  to change to the directory arg under the current
233              directory, and if that fails but cdpath is set and  contains  at
234              least  one  element attempt to change to the directory arg under
235              each component of cdpath in turn until successful.  If  `.'  oc‐
236              curs  in  cdpath,  then  cdpath is searched strictly in order so
237              that `.' is only tried at the appropriate point.
238
239              The order of testing cdpath is modified if the  option  POSIX_CD
240              is set, as described in the documentation for the option.
241
242              If  no  directory is found, the option CDABLE_VARS is set, and a
243              parameter named arg exists whose  value  begins  with  a  slash,
244              treat  its  value as the directory.  In that case, the parameter
245              is added to the named directory hash table.
246
247              The second form of cd substitutes the string new for the  string
248              old in the name of the current directory, and tries to change to
249              this new directory.
250
251              The third form of cd extracts an entry from the directory stack,
252              and  changes  to  that  directory.  An argument of the form `+n'
253              identifies a stack entry by counting from the left of  the  list
254              shown  by  the dirs command, starting with zero.  An argument of
255              the form `-n' counts from the right.  If the PUSHD_MINUS  option
256              is set, the meanings of `+' and `-' in this context are swapped.
257              If the POSIX_CD option is set, this form of cd is not recognised
258              and will be interpreted as the first form.
259
260              If  the  -q (quiet) option is specified, the hook function chpwd
261              and the functions in the array chpwd_functions are  not  called.
262              This  is  useful for calls to cd that do not change the environ‐
263              ment seen by an interactive user.
264
265              If the -s option is specified, cd refuses to change the  current
266              directory  if  the  given pathname contains symlinks.  If the -P
267              option is given or the CHASE_LINKS option is set, symbolic links
268              are  resolved  to  their true values.  If the -L option is given
269              symbolic links are retained in the directory (and not  resolved)
270              regardless of the state of the CHASE_LINKS option.
271
272       chdir  Same as cd.
273
274       clone  See the section `The zsh/clone Module' in zshmodules(1).
275
276       command [ -pvV ] simple command
277              The  simple command argument is taken as an external command in‐
278              stead  of  a  function  or  builtin  and  is  executed.  If  the
279              POSIX_BUILTINS option is set, builtins will also be executed but
280              certain special properties of them are suppressed. The  -p  flag
281              causes  a  default path to be searched instead of that in $path.
282              With the -v flag, command is similar to whence and with  -V,  it
283              is equivalent to whence -v.
284
285              See also the section `Precommand Modifiers' in zshmisc(1).
286
287       comparguments
288              See the section `The zsh/computil Module' in zshmodules(1).
289
290       compcall
291              See the section `The zsh/compctl Module' in zshmodules(1).
292
293       compctl
294              See the section `The zsh/compctl Module' in zshmodules(1).
295
296       compdescribe
297              See the section `The zsh/computil Module' in zshmodules(1).
298
299       compfiles
300              See the section `The zsh/computil Module' in zshmodules(1).
301
302       compgroups
303              See the section `The zsh/computil Module' in zshmodules(1).
304
305       compquote
306              See the section `The zsh/computil Module' in zshmodules(1).
307
308       comptags
309              See the section `The zsh/computil Module' in zshmodules(1).
310
311       comptry
312              See the section `The zsh/computil Module' in zshmodules(1).
313
314       compvalues
315              See the section `The zsh/computil Module' in zshmodules(1).
316
317       continue [ n ]
318              Resume  the  next  iteration of the enclosing for, while, until,
319              select or repeat loop. If an arithmetic expression n  is  speci‐
320              fied,  break  out  of  n-1 loops and resume at the nth enclosing
321              loop.
322
323       declare
324              Same as typeset.
325
326       dirs [ -c ] [ arg ... ]
327       dirs [ -lpv ]
328              With no arguments, print the contents of  the  directory  stack.
329              Directories  are added to this stack with the pushd command, and
330              removed with the cd or popd commands.  If arguments  are  speci‐
331              fied,  load  them  onto  the directory stack, replacing anything
332              that was there, and push the current directory onto the stack.
333
334              -c     clear the directory stack.
335
336              -l     print directory names in full instead of using of using ~
337                     expressions  (see Dynamic and Static named directories in
338                     zshexpn(1)).
339
340              -p     print directory entries one per line.
341
342              -v     number the directories in the stack when printing.
343
344       disable [ -afmprs ] name ...
345              Temporarily disable the named hash table elements  or  patterns.
346              The  default is to disable builtin commands.  This allows you to
347              use an external command with the same name as a builtin command.
348              The  -a  option  causes  disable  to  act  on  regular or global
349              aliases.  The -s option causes disable to act on suffix aliases.
350              The  -f option causes disable to act on shell functions.  The -r
351              options causes disable to act on reserved words.  Without  argu‐
352              ments  all  disabled  hash table elements from the corresponding
353              hash table are printed.  With the  -m  flag  the  arguments  are
354              taken  as  patterns (which should be quoted to prevent them from
355              undergoing filename expansion), and all hash table elements from
356              the  corresponding  hash  table matching these patterns are dis‐
357              abled.  Disabled objects can be enabled with the enable command.
358
359              With the option -p, name ... refer to elements  of  the  shell's
360              pattern  syntax  as  described  in the section `Filename Genera‐
361              tion'.  Certain elements can be disabled  separately,  as  given
362              below.
363
364              Note  that  patterns not allowed by the current settings for the
365              options EXTENDED_GLOB, KSH_GLOB and SH_GLOB are  never  enabled,
366              regardless  of  the setting here.  For example, if EXTENDED_GLOB
367              is not active, the pattern ^ is ineffective even if `disable  -p
368              "^"'  has  not been issued.  The list below indicates any option
369              settings that restrict the use of the  pattern.   It  should  be
370              noted  that  setting SH_GLOB has a wider effect than merely dis‐
371              abling patterns as certain expressions, in particular those  in‐
372              volving parentheses, are parsed differently.
373
374              The  following  patterns  may  be disabled; all the strings need
375              quoting on the command line to prevent them  from  being  inter‐
376              preted  immediately as patterns and the patterns are shown below
377              in single quotes as a reminder.
378
379              '?'    The pattern character ?  wherever  it  occurs,  including
380                     when preceding a parenthesis with KSH_GLOB.
381
382              '*'    The pattern character * wherever it occurs, including re‐
383                     cursive globbing and when preceding  a  parenthesis  with
384                     KSH_GLOB.
385
386              '['    Character classes.
387
388              '<' (NO_SH_GLOB)
389                     Numeric ranges.
390
391              '|' (NO_SH_GLOB)
392                     Alternation  in  grouped  patterns,  case  statements, or
393                     KSH_GLOB parenthesised expressions.
394
395              '(' (NO_SH_GLOB)
396                     Grouping using single parentheses.  Disabling  this  does
397                     not  disable  the  use  of parentheses for KSH_GLOB where
398                     they are introduced by a special character, nor for  glob
399                     qualifiers  (use  `setopt  NO_BARE_GLOB_QUAL'  to disable
400                     glob qualifiers that use parentheses only).
401
402              '~' (EXTENDED_GLOB)
403                     Exclusion in the form A~B.
404
405              '^' (EXTENDED_GLOB)
406                     Exclusion in the form A^B.
407
408              '#' (EXTENDED_GLOB)
409                     The pattern character # wherever it occurs, both for rep‐
410                     etition of a previous pattern and for indicating globbing
411                     flags.
412
413              '?(' (KSH_GLOB)
414                     The grouping form ?(...).  Note this is also disabled  if
415                     '?' is disabled.
416
417              '*(' (KSH_GLOB)
418                     The  grouping form *(...).  Note this is also disabled if
419                     '*' is disabled.
420
421              '+(' (KSH_GLOB)
422                     The grouping form +(...).
423
424              '!(' (KSH_GLOB)
425                     The grouping form !(...).
426
427              '@(' (KSH_GLOB)
428                     The grouping form @(...).
429
430       disown [ job ... ]
431       job ... &|
432       job ... &!
433              Remove the specified jobs from the job table; the shell will  no
434              longer  report their status, and will not complain if you try to
435              exit an interactive shell with them running or stopped.   If  no
436              job is specified, disown the current job.
437
438              If  the  jobs are currently stopped and the AUTO_CONTINUE option
439              is not set, a warning is printed  containing  information  about
440              how  to make them running after they have been disowned.  If one
441              of the latter two forms is used, the jobs will automatically  be
442              made  running,  independent  of the setting of the AUTO_CONTINUE
443              option.
444
445       echo [ -neE ] [ arg ... ]
446              Write each arg on the standard output, with a  space  separating
447              each one.  If the -n flag is not present, print a newline at the
448              end.  echo recognizes the following escape sequences:
449
450              \a     bell character
451              \b     backspace
452              \c     suppress subsequent characters and final newline
453              \e     escape
454              \f     form feed
455              \n     linefeed (newline)
456              \r     carriage return
457              \t     horizontal tab
458              \v     vertical tab
459              \\     backslash
460              \0NNN  character code in octal
461              \xNN   character code in hexadecimal
462              \uNNNN unicode character code in hexadecimal
463              \UNNNNNNNN
464                     unicode character code in hexadecimal
465
466              The -E flag, or the BSD_ECHO option,  can  be  used  to  disable
467              these escape sequences.  In the latter case, -e flag can be used
468              to enable them.
469
470              Note that for standards compliance a double dash does not termi‐
471              nate  option  processing; instead, it is printed directly.  How‐
472              ever, a single dash does terminate  option  processing,  so  the
473              first  dash, possibly following options, is not printed, but ev‐
474              erything following it is printed as  an  argument.   The  single
475              dash  behaviour is different from other shells.  For a more por‐
476              table way of printing text, see printf, and for a more  control‐
477              lable way of printing text within zsh, see print.
478
479       echotc See the section `The zsh/termcap Module' in zshmodules(1).
480
481       echoti See the section `The zsh/terminfo Module' in zshmodules(1).
482
483       emulate [ -lLR ] [ {zsh|sh|ksh|csh} [ flags ... ] ]
484              Without any argument print current emulation mode.
485
486              With single argument set up zsh options to emulate the specified
487              shell as much as possible.  csh will never  be  fully  emulated.
488              If  the argument is not one of the shells listed above, zsh will
489              be used as a default; more precisely, the tests performed on the
490              argument  are  the same as those used to determine the emulation
491              at startup based on the shell name, see the section  COMPATIBIL‐
492              ITY  in zsh(1) .  In addition to setting shell options, the com‐
493              mand also restores the pristine state of pattern enables, as  if
494              all patterns had been enabled using enable -p.
495
496              If  the  emulate  command occurs inside a function that has been
497              marked for execution tracing with functions -t then  the  xtrace
498              option  will  be turned on regardless of emulation mode or other
499              options.  Note that code executed inside the function by the  .,
500              source,  or  eval  commands  is not considered to be running di‐
501              rectly from the function, hence does not provoke this behaviour.
502
503              If the -R switch is given, all settable  options  are  reset  to
504              their  default  value  corresponding  to the specified emulation
505              mode, except for certain options describing the interactive  en‐
506              vironment;  otherwise, only those options likely to cause porta‐
507              bility problems in scripts and functions are altered.  If the -L
508              switch  is  given, the options LOCAL_OPTIONS, LOCAL_PATTERNS and
509              LOCAL_TRAPS will be set as well, causing the effects of the emu‐
510              late  command  and any setopt, disable -p or enable -p, and trap
511              commands to be local to the immediately surrounding shell  func‐
512              tion,  if any; normally these options are turned off in all emu‐
513              lation modes except ksh. The -L  switch  is  mutually  exclusive
514              with the use of -c in flags.
515
516              If  there  is  a single argument and the -l switch is given, the
517              options that would be set or unset (the  latter  indicated  with
518              the  prefix  `no') are listed.  -l can be combined with -L or -R
519              and the list will be modified in the appropriate way.  Note  the
520              list  does not depend on the current setting of options, i.e. it
521              includes all options that may  in  principle  change,  not  just
522              those that would actually change.
523
524              The  flags  may be any of the invocation-time flags described in
525              the section INVOCATION in zsh(1), except that `-o EMACS' and `-o
526              VI'  may not be used.  Flags such as `+r'/`+o RESTRICTED' may be
527              prohibited in some circumstances.
528
529              If -c arg appears in flags, arg is evaluated while the requested
530              emulation  is temporarily in effect.  In this case the emulation
531              mode and all options are restored to their previous  values  be‐
532              fore emulate returns.  The -R switch may precede the name of the
533              shell to emulate; note this has a meaning distinct from  includ‐
534              ing -R in flags.
535
536              Use  of -c enables `sticky' emulation mode for functions defined
537              within the evaluated expression:  the emulation mode is  associ‐
538              ated  thereafter with the function so that whenever the function
539              is executed the emulation (respecting the -R switch, if present)
540              and  all  options  are set (and pattern disables cleared) before
541              entry to the function, and the state is restored after exit.  If
542              the  function  is called when the sticky emulation is already in
543              effect, either within an `emulate shell -c' expression or within
544              another  function with the same sticky emulation, entry and exit
545              from the function do not cause options to be altered (except due
546              to  standard processing such as the LOCAL_OPTIONS option).  This
547              also applies to functions marked for autoload within the  sticky
548              emulation; the appropriate set of options will be applied at the
549              point the function is loaded as well as when it is run.
550
551              For example:
552
553                     emulate sh -c 'fni() { setopt cshnullglob; }
554                     fno() { fni; }'
555                     fno
556
557              The two functions fni and fno are defined with sticky sh  emula‐
558              tion.  fno is then executed, causing options associated with em‐
559              ulations to be set to their values in sh.  fno then  calls  fni;
560              because  fni  is  also marked for sticky sh emulation, no option
561              changes take place on entry to or exit from it.  Hence  the  op‐
562              tion  cshnullglob, turned off by sh emulation, will be turned on
563              within fni and remain on return to fno.  On exit from  fno,  the
564              emulation  mode  and  all  options will be restored to the state
565              they were in before entry to the temporary emulation.
566
567              The documentation above is typically sufficient for the intended
568              purpose  of  executing code designed for other shells in a suit‐
569              able environment.  More detailed rules follow.
570              1.     The sticky emulation  environment  provided  by  `emulate
571                     shell  -c'  is  identical  to that provided by entry to a
572                     function marked for sticky emulation as a consequence  of
573                     being  defined  in such an environment.  Hence, for exam‐
574                     ple, the sticky emulation is  inherited  by  subfunctions
575                     defined within functions with sticky emulation.
576              2.     No change of options takes place on entry to or exit from
577                     functions that are not marked for sticky emulation, other
578                     than  those that would normally take place, even if those
579                     functions are called within sticky emulation.
580              3.     No special handling is provided for functions marked  for
581                     autoload nor for functions present in wordcode created by
582                     the zcompile command.
583              4.     The presence or absence of the -R switch to emulate  cor‐
584                     responds  to different sticky emulation modes, so for ex‐
585                     ample `emulate sh -c', `emulate -R sh  -c'  and  `emulate
586                     csh -c' are treated as three distinct sticky emulations.
587              5.     Difference  in  shell options supplied in addition to the
588                     basic emulation also mean the sticky emulations are  dif‐
589                     ferent,  so for example `emulate zsh -c' and `emulate zsh
590                     -o cbases -c' are treated as distinct sticky emulations.
591
592       enable [ -afmprs ] name ...
593              Enable the named hash table elements, presumably  disabled  ear‐
594              lier  with  disable.  The default is to enable builtin commands.
595              The -a option causes enable to act on regular or global aliases.
596              The  -s  option  causes enable to act on suffix aliases.  The -f
597              option causes enable to act on shell functions.  The  -r  option
598              causes  enable  to act on reserved words.  Without arguments all
599              enabled hash table elements from the  corresponding  hash  table
600              are  printed.   With the -m flag the arguments are taken as pat‐
601              terns (should be quoted) and all hash table  elements  from  the
602              corresponding  hash  table  matching these patterns are enabled.
603              Enabled objects can be disabled with the  disable  builtin  com‐
604              mand.
605
606              enable  -p  reenables  patterns  disabled with disable -p.  Note
607              that it does not override globbing options; for example, `enable
608              -p  "~"' does not cause the pattern character ~ to be active un‐
609              less the EXTENDED_GLOB option is also set.  To enable all possi‐
610              ble  patterns  (so  that  they may be individually disabled with
611              disable -p), use `setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB'.
612
613       eval [ arg ... ]
614              Read the arguments as input to the shell and execute the result‐
615              ing  command(s) in the current shell process.  The return status
616              is the same as if the commands had been executed directly by the
617              shell;  if  there  are no args or they contain no commands (i.e.
618              are an empty string or whitespace) the return status is zero.
619
620       exec [ -cl ] [ -a argv0 ] [ command [ arg ... ] ]
621              Replace the current shell with command rather than forking.   If
622              command  is  a  shell  builtin  command or a shell function, the
623              shell executes it, and exits when the command is complete.
624
625              With -c clear the environment; with -l prepend - to the  argv[0]
626              string of the command executed (to simulate a login shell); with
627              -a argv0 set the argv[0] string of the  command  executed.   See
628              the section `Precommand Modifiers' in zshmisc(1).
629
630              If  the  option  POSIX_BUILTINS  is set, command is never inter‐
631              preted as a shell builtin command or shell function.  This means
632              further precommand modifiers such as builtin and noglob are also
633              not interpreted within the shell.  Hence command is always found
634              by searching the command path.
635
636              If  command  is omitted but any redirections are specified, then
637              the redirections will take effect in the current shell.
638
639       exit [ n ]
640              Exit the shell with the exit status specified by  an  arithmetic
641              expression n; if none is specified, use the exit status from the
642              last command executed.  An EOF condition  will  also  cause  the
643              shell to exit, unless the IGNORE_EOF option is set.
644
645              See  notes at the end of the section JOBS in zshmisc(1) for some
646              possibly unexpected interactions of the exit command with jobs.
647
648       export [ name[=value] ... ]
649              The specified names are marked for automatic export to the envi‐
650              ronment  of subsequently executed commands.  Equivalent to type‐
651              set -gx.  If a parameter specified does not already exist, it is
652              created in the global scope.
653
654       false [ arg ... ]
655              Do nothing and return an exit status of 1.
656
657
658       fc [ -e ename ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ last ] ]
659       fc -l [ -LI ] [ -nrdfEiD ] [ -t timefmt ] [ -m match ]
660             [ old=new ... ] [ first [ last ] ]
661       fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]
662       fc -P
663       fc -ARWI [ filename ]
664              The fc command controls the interactive history mechanism.  Note
665              that reading and writing of history options is only performed if
666              the  shell  is  interactive.  Usually this is detected automati‐
667              cally, but it can be forced by setting  the  interactive  option
668              when starting the shell.
669
670              The  first  two  forms  of this command select a range of events
671              from first to last from the history list.  The  arguments  first
672              and  last  may be specified as a number or as a string.  A nega‐
673              tive number is used as an offset to the  current  history  event
674              number.  A string specifies the most recent event beginning with
675              the given string.  All substitutions old=new, if any,  are  then
676              performed on the text of the events.
677
678              In addition to the number range,
679              -I     restricts to only internal events (not from $HISTFILE)
680              -L     restricts  to  only  local events (not from other shells,
681                     see SHARE_HISTORY in zshoptions(1) -- note that $HISTFILE
682                     is considered local when read at startup)
683              -m     takes  the first argument as a pattern (should be quoted)
684                     and only the history events  matching  this  pattern  are
685                     considered
686
687              If first is not specified, it will be set to -1 (the most recent
688              event), or to -16 if the -l flag is given.  If last is not spec‐
689              ified,  it  will  be  set  to  first, or to -1 if the -l flag is
690              given.  However, if the current event has added entries  to  the
691              history with `print -s' or `fc -R', then the default last for -l
692              includes all new history entries since the current event began.
693
694              When the -l flag is given, the resulting events  are  listed  on
695              standard  output.   Otherwise the editor program specified by -e
696              ename is invoked on a file containing these history events.   If
697              -e  is  not given, the value of the parameter FCEDIT is used; if
698              that is not set the value of the parameter EDITOR  is  used;  if
699              that  is  not  set  a builtin default, usually `vi' is used.  If
700              ename is `-', no editor is invoked.  When editing  is  complete,
701              the edited command is executed.
702
703              The  flag  -r  reverses  the order of the events and the flag -n
704              suppresses event numbers when listing.
705
706              Also when listing,
707              -d     prints timestamps for each event
708              -f     prints full time-date stamps in the US  `MM/DD/YY  hh:mm'
709                     format
710              -E     prints  full time-date stamps in the European `dd.mm.yyyy
711                     hh:mm' format
712              -i     prints  full  time-date  stamps  in  ISO8601  `yyyy-mm-dd
713                     hh:mm' format
714              -t fmt prints  time  and date stamps in the given format; fmt is
715                     formatted with the strftime function with the zsh  exten‐
716                     sions  described  for the %D{string} prompt format in the
717                     section EXPANSION OF PROMPT SEQUENCES in zshmisc(1).  The
718                     resulting formatted string must be no more than 256 char‐
719                     acters or will not be printed
720              -D     prints elapsed times; may be combined with one of the op‐
721                     tions above
722
723              `fc  -p'  pushes  the  current  history  list  onto  a stack and
724              switches to a new history list.  If the -a option is also speci‐
725              fied,  this  history  list will be automatically popped when the
726              current function scope is exited, which is a much  better  solu‐
727              tion than creating a trap function to call `fc -P' manually.  If
728              no arguments are specified, the  history  list  is  left  empty,
729              $HISTFILE  is  unset, and $HISTSIZE & $SAVEHIST are set to their
730              default values.  If one argument is given, $HISTFILE is  set  to
731              that filename, $HISTSIZE & $SAVEHIST are left unchanged, and the
732              history file is read in (if it exists)  to  initialize  the  new
733              list.   If a second argument is specified, $HISTSIZE & $SAVEHIST
734              are instead set to the single specified numeric value.  Finally,
735              if a third argument is specified, $SAVEHIST is set to a separate
736              value from $HISTSIZE.  You are free to change these  environment
737              values  for  the new history list however you desire in order to
738              manipulate the new history list.
739
740              `fc -P' pops the history list back to an older list saved by `fc
741              -p'.   The  current  list is saved to its $HISTFILE before it is
742              destroyed (assuming that $HISTFILE and $SAVEHIST are set  appro‐
743              priately,  of  course).  The values of $HISTFILE, $HISTSIZE, and
744              $SAVEHIST are restored to the values they had when `fc  -p'  was
745              called.   Note  that  this  restoration can conflict with making
746              these variables "local", so your best bet is to avoid local dec‐
747              larations  for  these  variables  in functions that use `fc -p'.
748              The one other guaranteed-safe  combination  is  declaring  these
749              variables  to be local at the top of your function and using the
750              automatic option (-a) with `fc -p'.  Finally, note  that  it  is
751              legal to manually pop a push marked for automatic popping if you
752              need to do so before the function exits.
753
754              `fc -R' reads the history from the given file,  `fc  -W'  writes
755              the  history out to the given file, and `fc -A' appends the his‐
756              tory out to the given file.  If no filename  is  specified,  the
757              $HISTFILE  is  assumed.   If  the -I option is added to -R, only
758              those events that are not already contained within the  internal
759              history  list are added.  If the -I option is added to -A or -W,
760              only those events  that  are  new  since  last  incremental  ap‐
761              pend/write  to  the  history  file are appended/written.  In any
762              case, the created file will have no more than $SAVEHIST entries.
763
764       fg [ job ... ]
765       job ...
766              Bring each specified job in turn to the foreground.  If  no  job
767              is specified, resume the current job.
768
769       float [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ n ] ] [ name[=value] ... ]
770              Equivalent  to  typeset  -E,  except  that options irrelevant to
771              floating point numbers are not permitted.
772
773       functions [ {+|-}UkmtTuWz ] [ -x num ] [ name ... ]
774       functions -c oldfn newfn
775       functions -M [-s] mathfn [ min [ max [ shellfn ] ] ]
776       functions -M [ -m pattern ... ]
777       functions +M [ -m ] mathfn ...
778              Equivalent to typeset -f, with the exception of the -c,  -x,  -M
779              and  -W  options.   For  functions  -u and functions -U, see au‐
780              toload, which provides additional options.
781
782              The -x option indicates that any functions output will have each
783              leading  tab for indentation, added by the shell to show syntac‐
784              tic structure, expanded to the given number num of spaces.   num
785              can also be 0 to suppress all indentation.
786
787              The  -W option turns on the option WARN_NESTED_VAR for the named
788              function or functions only.  The option is  turned  off  at  the
789              start  of nested functions (apart from anonoymous functions) un‐
790              less the called function also has the -W attribute.
791
792              The -c option causes oldfn to be copied to newfn.  The  copy  is
793              efficiently  handled internally by reference counting.  If oldfn
794              was marked for autoload it is first loaded and if this fails the
795              copy fails.  Either function may subsequently be redefined with‐
796              out affecting the other.  A typical idiom is that oldfn  is  the
797              name of a library shell function which is then redefined to call
798              newfn, thereby installing a modified version of the function.
799
800              Use of the -M option may not be combined with any of the options
801              handled by typeset -f.
802
803              functions -M mathfn defines mathfn as the name of a mathematical
804              function recognised in all forms  of  arithmetical  expressions;
805              see  the  section `Arithmetic Evaluation' in zshmisc(1).  By de‐
806              fault mathfn may take any number of  comma-separated  arguments.
807              If  min  is given, it must have exactly min args; if min and max
808              are both given, it must have at least min and at most max  args.
809              max may be -1 to indicate that there is no upper limit.
810
811              By  default  the  function is implemented by a shell function of
812              the same name; if shellfn is specified it gives the name of  the
813              corresponding  shell function while mathfn remains the name used
814              in arithmetical expressions.  The name of the function in $0  is
815              mathfn  (not shellfn as would usually be the case), provided the
816              option FUNCTION_ARGZERO is in effect.  The positional parameters
817              in  the shell function correspond to the arguments of the mathe‐
818              matical function call.  The result of the last arithmetical  ex‐
819              pression  evaluated  inside  the shell function (even if it is a
820              form that normally only returns a status) gives  the  result  of
821              the mathematical function.
822
823              If  the additional option -s is given to functions -M, the argu‐
824              ment to the function is a single string:  anything  between  the
825              opening  and matching closing parenthesis is passed to the func‐
826              tion as a single argument, even if it includes commas  or  white
827              space.   The minimum and maximum argument specifiers must there‐
828              fore be 1 if given.  An empty  argument  list  is  passed  as  a
829              zero-length string.
830
831              functions -M with no arguments lists all such user-defined func‐
832              tions in the same form as a definition.  With the additional op‐
833              tion  -m  and  a  list  of arguments, all functions whose mathfn
834              matches one of the pattern arguments are listed.
835
836              function +M removes the list of mathematical functions; with the
837              additional  option  -m the arguments are treated as patterns and
838              all functions whose mathfn  matches  the  pattern  are  removed.
839              Note  that  the shell function implementing the behaviour is not
840              removed (regardless of whether its name coincides with mathfn).
841
842              For example, the following prints the cube of 3:
843
844                     zmath_cube() { (( $1 * $1 * $1 )) }
845                     functions -M cube 1 1 zmath_cube
846                     print $(( cube(3) ))
847
848              The following string function takes a single argument, including
849              the commas, so prints 11:
850
851                     stringfn() { (( $#1 )) }
852                     functions -Ms stringfn
853                     print $(( stringfn(foo,bar,rod) ))
854
855       getcap See the section `The zsh/cap Module' in zshmodules(1).
856
857       getln [ -AclneE ] name ...
858              Read the top value from the buffer stack and put it in the shell
859              parameter name.  Equivalent to read -zr.
860
861       getopts optstring name [ arg ... ]
862              Checks the args for legal options.  If the args are omitted, use
863              the  positional parameters.  A valid option argument begins with
864              a `+' or a `-'.  An argument not beginning with a `+' or a  `-',
865              or  the argument `--', ends the options.  Note that a single `-'
866              is not considered a valid option argument.   optstring  contains
867              the letters that getopts recognizes.  If a letter is followed by
868              a `:', that option requires an argument.   The  options  can  be
869              separated from the argument by blanks.
870
871              Each  time  it  is  invoked, getopts places the option letter it
872              finds in the shell parameter name, prepended with a `+' when arg
873              begins  with  a  `+'.   The  index  of the next arg is stored in
874              OPTIND.  The option argument, if any, is stored in OPTARG.
875
876              The first option to be examined may be changed by explicitly as‐
877              signing  to  OPTIND.   OPTIND  has an initial value of 1, and is
878              normally set to 1 upon entry to a shell  function  and  restored
879              upon  exit (this is disabled by the POSIX_BUILTINS option).  OP‐
880              TARG is not reset and retains its value  from  the  most  recent
881              call  to  getopts.   If either of OPTIND or OPTARG is explicitly
882              unset, it remains unset, and the index or option argument is not
883              stored.  The option itself is still stored in name in this case.
884
885              A leading `:' in optstring causes getopts to store the letter of
886              any invalid option in OPTARG, and to set name to `?' for an  un‐
887              known  option  and  to  `:' when a required argument is missing.
888              Otherwise, getopts sets name to `?' and prints an error  message
889              when  an  option  is  invalid.   The exit status is nonzero when
890              there are no more options.
891
892       hash [ -Ldfmrv ] [ name[=value] ] ...
893              hash can be used to directly modify the contents of the  command
894              hash  table,  and  the named directory hash table.  Normally one
895              would modify these tables by modifying one's PATH (for the  com‐
896              mand  hash  table)  or  by creating appropriate shell parameters
897              (for the named directory hash table).  The choice of hash  table
898              to  work  on  is determined by the -d option; without the option
899              the command hash table is used, and with the  option  the  named
900              directory hash table is used.
901
902              A command name starting with a / is never hashed, whether by ex‐
903              plicit use of the hash command or otherwise.  Such a command  is
904              always found by direct look up in the file system.
905
906              Given  no  arguments,  and neither the -r or -f options, the se‐
907              lected hash table will be listed in full.
908
909              The -r option causes the selected hash table to be emptied.   It
910              will  be subsequently rebuilt in the normal fashion.  The -f op‐
911              tion causes the selected hash table to be fully rebuilt  immedi‐
912              ately.   For the command hash table this hashes all the absolute
913              directories in the PATH, and for the named directory hash  table
914              this adds all users' home directories.  These two options cannot
915              be used with any arguments.
916
917              The -m option causes the  arguments  to  be  taken  as  patterns
918              (which  should  be  quoted)  and  the elements of the hash table
919              matching those patterns are printed.  This is the  only  way  to
920              display a limited selection of hash table elements.
921
922              For  each name with a corresponding value, put `name' in the se‐
923              lected hash table, associating it with the pathname `value'.  In
924              the  command hash table, this means that whenever `name' is used
925              as a command argument, the shell will try to  execute  the  file
926              given by `value'.  In the named directory hash table, this means
927              that `value' may be referred to as `~name'.
928
929              For each name with no corresponding value, attempt to  add  name
930              to the hash table, checking what the appropriate value is in the
931              normal manner for that hash  table.   If  an  appropriate  value
932              can't be found, then the hash table will be unchanged.
933
934              The -v option causes hash table entries to be listed as they are
935              added by explicit specification.  If has no effect if used  with
936              -f.
937
938              If the -L flag is present, then each hash table entry is printed
939              in the form of a call to hash.
940
941       history
942              Same as fc -l.
943
944       integer [ {+|-}Hghlprtux ] [ {+|-}LRZi [ n ] ] [ name[=value] ... ]
945              Equivalent to typeset -i, except that options irrelevant to  in‐
946              tegers are not permitted.
947
948       jobs [ -dlprs ] [ job ... ]
949       jobs -Z string
950              Lists  information  about  each given job, or all jobs if job is
951              omitted.  The -l flag lists process IDs, and the -p  flag  lists
952              process  groups.   If the -r flag is specified only running jobs
953              will be listed and if the -s flag is given only stopped jobs are
954              shown.   If  the  -d flag is given, the directory from which the
955              job was started (which may not be the current directory  of  the
956              job) will also be shown.
957
958              The  -Z  option  replaces  the  shell's argument and environment
959              space with the given string,  truncated  if  necessary  to  fit.
960              This will normally be visible in ps (ps(1)) listings.  This fea‐
961              ture is typically used by daemons, to indicate their state.
962
963       kill [ -s signal_name | -n signal_number | -sig ] job ...
964       kill -l [ sig ... ]
965              Sends either SIGTERM or the specified signal to the  given  jobs
966              or  processes.  Signals are given by number or by names, with or
967              without the `SIG' prefix.  If  the  signal  being  sent  is  not
968              `KILL'  or  `CONT', then the job will be sent a `CONT' signal if
969              it is stopped.  The argument job can be the process ID of a  job
970              not in the job list.  In the second form, kill -l, if sig is not
971              specified the signal names are listed.  Otherwise, for each  sig
972              that  is a name, the corresponding signal number is listed.  For
973              each sig that is a signal number or a  number  representing  the
974              exit  status  of  a process which was terminated or stopped by a
975              signal the name of the signal is printed.
976
977              On some systems, alternative signal names are allowed for a  few
978              signals.  Typical examples are SIGCHLD and SIGCLD or SIGPOLL and
979              SIGIO, assuming they correspond to the same signal number.  kill
980              -l  will  only list the preferred form, however kill -l alt will
981              show if the alternative form corresponds  to  a  signal  number.
982              For example, under Linux kill -l IO and kill -l POLL both output
983              29, hence kill -IO and kill -POLL have the same effect.
984
985              Many systems will allow process IDs to be  negative  to  kill  a
986              process group or zero to kill the current process group.
987
988       let arg ...
989              Evaluate  each arg as an arithmetic expression.  See the section
990              `Arithmetic Evaluation'  in  zshmisc(1)  for  a  description  of
991              arithmetic  expressions.   The  exit status is 0 if the value of
992              the last expression is nonzero, 1 if it is zero, and 2 if an er‐
993              ror occurred.
994
995       limit [ -hs ] [ resource [ limit ] ] ...
996              Set  or  display  resource limits.  Unless the -s flag is given,
997              the limit applies only the children of  the  shell.   If  -s  is
998              given  without  other arguments, the resource limits of the cur‐
999              rent shell is set to the previously set resource limits  of  the
1000              children.
1001
1002              If limit is not specified, print the current limit placed on re‐
1003              source, otherwise set the limit to the specified value.  If  the
1004              -h flag is given, use hard limits instead of soft limits.  If no
1005              resource is given, print all limits.
1006
1007              When looping over multiple resources, the shell will abort imme‐
1008              diately  if  it detects a badly formed argument.  However, if it
1009              fails to set a limit for some other reason it will continue try‐
1010              ing to set the remaining limits.
1011
1012              resource can be one of:
1013
1014              addressspace
1015                     Maximum amount of address space used.
1016              aiomemorylocked
1017                     Maximum  amount  of  memory  locked in RAM for AIO opera‐
1018                     tions.
1019              aiooperations
1020                     Maximum number of AIO operations.
1021              cachedthreads
1022                     Maximum number of cached threads.
1023              coredumpsize
1024                     Maximum size of a core dump.
1025              cputime
1026                     Maximum CPU seconds per process.
1027              datasize
1028                     Maximum data size (including stack) for each process.
1029              descriptors
1030                     Maximum value for a file descriptor.
1031              filesize
1032                     Largest single file allowed.
1033              kqueues
1034                     Maximum number of kqueues allocated.
1035              maxproc
1036                     Maximum number of processes.
1037              maxpthreads
1038                     Maximum number of threads per process.
1039              memorylocked
1040                     Maximum amount of memory locked in RAM.
1041              memoryuse
1042                     Maximum resident set size.
1043              msgqueue
1044                     Maximum number of bytes in POSIX message queues.
1045              posixlocks
1046                     Maximum number of POSIX locks per user.
1047              pseudoterminals
1048                     Maximum number of pseudo-terminals.
1049              resident
1050                     Maximum resident set size.
1051              sigpending
1052                     Maximum number of pending signals.
1053              sockbufsize
1054                     Maximum size of all socket buffers.
1055              stacksize
1056                     Maximum stack size for each process.
1057              swapsize
1058                     Maximum amount of swap used.
1059              vmemorysize
1060                     Maximum amount of virtual memory.
1061
1062              Which of these resource limits are available depends on the sys‐
1063              tem.  resource can be abbreviated to any unambiguous prefix.  It
1064              can also be an integer, which corresponds to the integer defined
1065              for the resource by the operating system.
1066
1067              If argument corresponds to a number which is out of the range of
1068              the resources configured into the shell, the shell will  try  to
1069              read or write the limit anyway, and will report an error if this
1070              fails.  As the shell does not store such  resources  internally,
1071              an  attempt  to  set the limit will fail unless the -s option is
1072              present.
1073
1074              limit is a number, with an optional scaling factor, as follows:
1075
1076              nh     hours
1077              nk     kilobytes (default)
1078              nm     megabytes or minutes
1079              ng     gigabytes
1080              [mm:]ss
1081                     minutes and seconds
1082
1083              The limit command is not made  available  by  default  when  the
1084              shell  starts in a mode emulating another shell.  It can be made
1085              available with the command `zmodload -F zsh/rlimits b:limit'.
1086
1087       local [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ]
1088              Same as typeset, except that the options -g, and -f are not per‐
1089              mitted.   In  this  case the -x option does not force the use of
1090              -g, i.e. exported variables will be local to functions.
1091
1092       log    List all users currently logged in who are affected by the  cur‐
1093              rent setting of the watch parameter.
1094
1095       logout [ n ]
1096              Same as exit, except that it only works in a login shell.
1097
1098       noglob simple command
1099              See the section `Precommand Modifiers' in zshmisc(1).
1100
1101       popd [ -q ] [ {+|-}n ]
1102              Remove  an  entry  from the directory stack, and perform a cd to
1103              the new top directory.  With no argument, the current top  entry
1104              is removed.  An argument of the form `+n' identifies a stack en‐
1105              try by counting from the left of the list shown by the dirs com‐
1106              mand,  starting  with  zero.   An argument of the form -n counts
1107              from the right.  If the PUSHD_MINUS option is set, the  meanings
1108              of `+' and `-' in this context are swapped.
1109
1110              If  the  -q (quiet) option is specified, the hook function chpwd
1111              and the functions in the array $chpwd_functions are not  called,
1112              and  the new directory stack is not printed.  This is useful for
1113              calls to popd that do not change the environment seen by an  in‐
1114              teractive user.
1115
1116       print [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C cols ]
1117             [ -v name ] [ -xX tabstop ] [ -R [ -en ]] [ arg ... ]
1118              With  the  `-f' option the arguments are printed as described by
1119              printf.  With no flags or with the flag `-', the  arguments  are
1120              printed  on  the  standard output as described by echo, with the
1121              following differences: the escape  sequence  `\M-x'  (or  `\Mx')
1122              metafies  the  character  x  (sets  the highest bit), `\C-x' (or
1123              `\Cx') produces a control character (`\C-@' and `\C-?' give  the
1124              characters NULL and delete), a character code in octal is repre‐
1125              sented by `\NNN' (instead of `\0NNN'), and `\E' is a synonym for
1126              `\e'.   Finally,  if  not in an escape sequence, `\' escapes the
1127              following character and is not printed.
1128
1129              -a     Print arguments with the column incrementing first.  Only
1130                     useful with the -c and -C options.
1131
1132              -b     Recognize  all the escape sequences defined for the bind‐
1133                     key command, see the section `Zle Builtins' in zshzle(1).
1134
1135              -c     Print the arguments in columns.  Unless -a is also given,
1136                     arguments are printed with the row incrementing first.
1137
1138              -C cols
1139                     Print  the  arguments in cols columns.  Unless -a is also
1140                     given, arguments are printed with  the  row  incrementing
1141                     first.
1142
1143              -D     Treat  the  arguments  as paths, replacing directory pre‐
1144                     fixes  with  ~  expressions  corresponding  to  directory
1145                     names, as appropriate.
1146
1147              -i     If  given  together  with  -o or -O, sorting is performed
1148                     case-independently.
1149
1150              -l     Print the arguments separated by newlines instead of spa‐
1151                     ces.   Note:  if the list of arguments is empty, print -l
1152                     will still output one  empty  line.  To  print  a  possi‐
1153                     bly-empty  list of arguments one per line, use print -C1,
1154                     as in `print -rC1 -- "$list[@]"'.
1155
1156              -m     Take the first argument as a pattern (should be  quoted),
1157                     and remove it from the argument list together with subse‐
1158                     quent arguments that do not match this pattern.
1159
1160              -n     Do not add a newline to the output.
1161
1162              -N     Print the arguments separated and  terminated  by  nulls.
1163                     Again,  print  -rNC1  -- "$list[@]" is a canonical way to
1164                     print an arbitrary list as null-delimited records.
1165
1166              -o     Print the arguments sorted in ascending order.
1167
1168              -O     Print the arguments sorted in descending order.
1169
1170              -p     Print the arguments to the input of the coprocess.
1171
1172              -P     Perform prompt expansion (see  EXPANSION  OF  PROMPT  SE‐
1173                     QUENCES in zshmisc(1)).  In combination with `-f', prompt
1174                     escape sequences are parsed only within interpolated  ar‐
1175                     guments, not within the format string.
1176
1177              -r     Ignore the escape conventions of echo.
1178
1179              -R     Emulate  the BSD echo command, which does not process es‐
1180                     cape sequences unless the -e flag is given.  The -n  flag
1181                     suppresses  the  trailing  newline.   Only  the -e and -n
1182                     flags are recognized after -R; all  other  arguments  and
1183                     options are printed.
1184
1185              -s     Place  the  results in the history list instead of on the
1186                     standard output.  Each argument to the print  command  is
1187                     treated  as  a  single word in the history, regardless of
1188                     its content.
1189
1190              -S     Place the results in the history list instead of  on  the
1191                     standard  output.  In this case only a single argument is
1192                     allowed; it will be split into words as if it were a full
1193                     shell command line.  The effect is similar to reading the
1194                     line from a history file with the  HIST_LEX_WORDS  option
1195                     active.
1196
1197              -u n   Print the arguments to file descriptor n.
1198
1199              -v name
1200                     Store the printed arguments as the value of the parameter
1201                     name.
1202
1203              -x tab-stop
1204                     Expand leading tabs on each line of output in the printed
1205                     string  assuming  a  tab  stop every tab-stop characters.
1206                     This is appropriate for formatting code that may  be  in‐
1207                     dented with tabs.  Note that leading tabs of any argument
1208                     to print, not just the first, are expanded, even if print
1209                     is  using  spaces to separate arguments (the column count
1210                     is maintained across arguments but may  be  incorrect  on
1211                     output owing to previous unexpanded tabs).
1212
1213                     The  start of the output of each print command is assumed
1214                     to be aligned with a tab stop.  Widths of multibyte char‐
1215                     acters  are handled if the option MULTIBYTE is in effect.
1216                     This option is ignored if other formatting options are in
1217                     effect,  namely  column  alignment or printf style, or if
1218                     output is to a special location such as shell history  or
1219                     the command line editor.
1220
1221              -X tab-stop
1222                     This  is  similar  to  -x,  except  that  all tabs in the
1223                     printed string are expanded.  This is appropriate if tabs
1224                     in  the  arguments are being used to produce a table for‐
1225                     mat.
1226
1227              -z     Push the arguments onto the editing buffer  stack,  sepa‐
1228                     rated by spaces.
1229
1230              If  any  of `-m', `-o' or `-O' are used in combination with `-f'
1231              and there are no arguments (after the  removal  process  in  the
1232              case of `-m') then nothing is printed.
1233
1234       printf [ -v name ] format [ arg ... ]
1235              Print  the arguments according to the format specification. For‐
1236              matting rules are the same as used in C.  The  same  escape  se‐
1237              quences  as for echo are recognised in the format. All C conver‐
1238              sion specifications ending in one of csdiouxXeEfgGn are handled.
1239              In  addition  to this, `%b' can be used instead of `%s' to cause
1240              escape sequences in the argument to be recognised and  `%q'  can
1241              be used to quote the argument in such a way that allows it to be
1242              reused as shell input. With the numeric  format  specifiers,  if
1243              the  corresponding  argument  starts with a quote character, the
1244              numeric value of the following character is used as  the  number
1245              to  print;  otherwise the argument is evaluated as an arithmetic
1246              expression. See the  section  `Arithmetic  Evaluation'  in  zsh‐
1247              misc(1)  for a description of arithmetic expressions. With `%n',
1248              the corresponding argument is taken as an  identifier  which  is
1249              created as an integer parameter.
1250
1251              Normally, conversion specifications are applied to each argument
1252              in order but they can explicitly specify the nth argument is  to
1253              be  used by replacing `%' by `%n$' and `*' by `*n$'.  It is rec‐
1254              ommended that you do not mix references of this  explicit  style
1255              with  the normal style and the handling of such mixed styles may
1256              be subject to future change.
1257
1258              If arguments remain unused after formatting, the  format  string
1259              is reused until all arguments have been consumed. With the print
1260              builtin, this can be suppressed by using the -r option. If  more
1261              arguments  are  required by the format than have been specified,
1262              the behaviour is as if zero or an empty string had  been  speci‐
1263              fied as the argument.
1264
1265              The -v option causes the output to be stored as the value of the
1266              parameter name, instead of printed. If name is an array and  the
1267              format  string is reused when consuming arguments then one array
1268              element will be used for each use of the format string.
1269
1270       pushd [ -qsLP ] [ arg ]
1271       pushd [ -qsLP ] old new
1272       pushd [ -qsLP ] {+|-}n
1273              Change the current directory, and push the old current directory
1274              onto the directory stack.  In the first form, change the current
1275              directory to arg.  If arg is not specified, change to the second
1276              directory  on the stack (that is, exchange the top two entries),
1277              or change to $HOME if the PUSHD_TO_HOME  option  is  set  or  if
1278              there  is only one entry on the stack.  Otherwise, arg is inter‐
1279              preted as it would be by cd.  The meaning of old and new in  the
1280              second form is also the same as for cd.
1281
1282              The third form of pushd changes directory by rotating the direc‐
1283              tory list.  An argument of the form `+n' identifies a stack  en‐
1284              try by counting from the left of the list shown by the dirs com‐
1285              mand, starting with zero.  An argument of the form  `-n'  counts
1286              from  the right.  If the PUSHD_MINUS option is set, the meanings
1287              of `+' and `-' in this context are swapped.
1288
1289              If the -q (quiet) option is specified, the hook  function  chpwd
1290              and  the functions in the array $chpwd_functions are not called,
1291              and the new directory stack is not printed.  This is useful  for
1292              calls to pushd that do not change the environment seen by an in‐
1293              teractive user.
1294
1295              If  the  option  -q  is  not  specified  and  the  shell  option
1296              PUSHD_SILENT is not set, the directory stack will be printed af‐
1297              ter a pushd is performed.
1298
1299              The options -s, -L and -P have the same meanings as for  the  cd
1300              builtin.
1301
1302       pushln [ arg ... ]
1303              Equivalent to print -nz.
1304
1305       pwd [ -rLP ]
1306              Print  the  absolute  pathname of the current working directory.
1307              If the -r or the -P flag is specified, or the CHASE_LINKS option
1308              is  set  and the -L flag is not given, the printed path will not
1309              contain symbolic links.
1310
1311       r      Same as fc -e -.
1312
1313
1314       read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d delim ]
1315            [ -u n ] [ name[?prompt] ] [ name ...  ]
1316              Read one line and break it into fields using the  characters  in
1317              $IFS  as  separators, except as noted below.  The first field is
1318              assigned to the first name, the second field to the second name,
1319              etc.,  with  leftover fields assigned to the last name.  If name
1320              is omitted then REPLY is used for scalars and reply for arrays.
1321
1322              -r     Raw mode: a `\' at the end of a  line  does  not  signify
1323                     line continuation and backslashes in the line don't quote
1324                     the following character and are not removed.
1325
1326              -s     Don't echo back characters if reading from the terminal.
1327
1328              -q     Read only one character from the terminal and set name to
1329                     `y'  if  this  character was `y' or `Y' and to `n' other‐
1330                     wise.  With this flag set the return status is zero  only
1331                     if the character was `y' or `Y'.  This option may be used
1332                     with a timeout (see -t); if the read times  out,  or  en‐
1333                     counters  end  of  file,  status 2 is returned.  Input is
1334                     read from the terminal unless one of -u or -p is present.
1335                     This option may also be used within zle widgets.
1336
1337              -k [ num ]
1338                     Read  only  one (or num) characters.  All are assigned to
1339                     the first name, without word splitting.  This flag is ig‐
1340                     nored  when -q is present.  Input is read from the termi‐
1341                     nal unless one of -u or -p is present.  This  option  may
1342                     also be used within zle widgets.
1343
1344                     Note  that  despite  the  mnemonic `key' this option does
1345                     read full characters, which may consist of multiple bytes
1346                     if the option MULTIBYTE is set.
1347
1348              -z     Read one entry from the editor buffer stack and assign it
1349                     to the first  name,  without  word  splitting.   Text  is
1350                     pushed  onto  the stack with `print -z' or with push-line
1351                     from the line editor (see zshzle(1)).  This flag  is  ig‐
1352                     nored when the -k or -q flags are present.
1353
1354              -e
1355              -E     The  input  read is printed (echoed) to the standard out‐
1356                     put.  If the -e flag is used, no input is assigned to the
1357                     parameters.
1358
1359              -A     The  first  name is taken as the name of an array and all
1360                     words are assigned to it.
1361
1362              -c
1363              -l     These flags are allowed only if called inside a  function
1364                     used  for  completion (specified with the -K flag to com‐
1365                     pctl).  If the -c flag is given, the words of the current
1366                     command are read. If the -l flag is given, the whole line
1367                     is assigned as a scalar.  If both flags are  present,  -l
1368                     is used and -c is ignored.
1369
1370              -n     Together with -c, the number of the word the cursor is on
1371                     is read.  With -l, the index of the character the  cursor
1372                     is on is read.  Note that the command name is word number
1373                     1, not word 0, and that when the cursor is at the end  of
1374                     the  line,  its character index is the length of the line
1375                     plus one.
1376
1377              -u n   Input is read from file descriptor n.
1378
1379              -p     Input is read from the coprocess.
1380
1381              -d delim
1382                     Input is terminated by the first character of  delim  in‐
1383                     stead of by newline.
1384
1385              -t [ num ]
1386                     Test if input is available before attempting to read.  If
1387                     num is present, it must begin with a digit  and  will  be
1388                     evaluated  to  give  a  number of seconds, which may be a
1389                     floating point number; in this case the read times out if
1390                     input  is  not available within this time.  If num is not
1391                     present, it is taken to be zero, so that read returns im‐
1392                     mediately  if  no  input  is  available.   If no input is
1393                     available, return status 1 and do not set any variables.
1394
1395                     This option is not available when reading from the editor
1396                     buffer  with  -z, when called from within completion with
1397                     -c or -l, with -q which clears  the  input  queue  before
1398                     reading,  or  within zle where other mechanisms should be
1399                     used to test for input.
1400
1401                     Note that read does not attempt to alter the  input  pro‐
1402                     cessing  mode.   The  default mode is canonical input, in
1403                     which an entire line is read at a time, so usually  `read
1404                     -t'  will not read anything until an entire line has been
1405                     typed.  However, when reading from the terminal  with  -k
1406                     input  is processed one key at a time; in this case, only
1407                     availability of the first character is  tested,  so  that
1408                     e.g. `read -t -k 2' can still block on the second charac‐
1409                     ter.  Use two instances of `read -t -k' if  this  is  not
1410                     what is wanted.
1411
1412              If the first argument contains a `?', the remainder of this word
1413              is used as a prompt on standard error when the shell is interac‐
1414              tive.
1415
1416              The  value (exit status) of read is 1 when an end-of-file is en‐
1417              countered, or when -c or -l is present and the  command  is  not
1418              called  from a compctl function, or as described for -q.  Other‐
1419              wise the value is 0.
1420
1421              The behavior of some combinations of the -k, -p, -q, -u  and  -z
1422              flags  is  undefined.   Presently  -q cancels all the others, -p
1423              cancels -u, -k cancels -z, and otherwise -z cancels both -p  and
1424              -u.
1425
1426              The -c or -l flags cancel any and all of -kpquz.
1427
1428       readonly
1429              Same as typeset -r.  With the POSIX_BUILTINS option set, same as
1430              typeset -gr.
1431
1432       rehash Same as hash -r.
1433
1434       return [ n ]
1435              Causes a shell function or `.' script to return to the  invoking
1436              script with the return status specified by an arithmetic expres‐
1437              sion n. If n is omitted, the return status is that of  the  last
1438              command executed.
1439
1440              If  return  was  executed from a trap in a TRAPNAL function, the
1441              effect is different for zero and non-zero return  status.   With
1442              zero  status  (or  after  an  implicit  return at the end of the
1443              trap), the shell will return to whatever it was previously  pro‐
1444              cessing; with a non-zero status, the shell will behave as inter‐
1445              rupted except that the return status of the  trap  is  retained.
1446              Note  that the numeric value of the signal which caused the trap
1447              is passed as  the  first  argument,  so  the  statement  `return
1448              $((128+$1))'  will  return  the same status as if the signal had
1449              not been trapped.
1450
1451       sched  See the section `The zsh/sched Module' in zshmodules(1).
1452
1453
1454       set [ {+|-}options | {+|-}o [ option_name ] ] ... [ {+|-}A [ name ] ]
1455           [ arg ... ]
1456              Set the options for the shell and/or set the positional  parame‐
1457              ters,  or  declare and set an array.  If the -s option is given,
1458              it causes the specified arguments to be sorted before  assigning
1459              them to the positional parameters (or to the array name if -A is
1460              used).  With +s sort arguments in  descending  order.   For  the
1461              meaning  of  the  other  flags, see zshoptions(1).  Flags may be
1462              specified by name using the -o option. If no option name is sup‐
1463              plied  with  -o, the current option states are printed:  see the
1464              description of setopt below for more information on the  format.
1465              With  +o they are printed in a form that can be used as input to
1466              the shell.
1467
1468              If the -A flag is specified, name is set to an array  containing
1469              the  given args; if no name is specified, all arrays are printed
1470              together with their values.
1471
1472              If +A is used and name is an array, the given arguments will re‐
1473              place  the  initial elements of that array; if no name is speci‐
1474              fied, all arrays are printed without their values.
1475
1476              The behaviour of arguments after -A name or +A name  depends  on
1477              whether the option KSH_ARRAYS is set.  If it is not set, all ar‐
1478              guments following name are treated as values for the array,  re‐
1479              gardless  of  their  form.   If the option is set, normal option
1480              processing continues at that point; only regular  arguments  are
1481              treated as values for the array.  This means that
1482
1483                     set -A array -x -- foo
1484
1485              sets array to `-x -- foo' if KSH_ARRAYS is not set, but sets the
1486              array to foo and turns on the option `-x' if it is set.
1487
1488              If the -A flag is not present, but there  are  arguments  beyond
1489              the  options,  the positional parameters are set.  If the option
1490              list (if any) is terminated by `--', and there  are  no  further
1491              arguments, the positional parameters will be unset.
1492
1493              If no arguments and no `--' are given, then the names and values
1494              of all parameters are printed on the standard  output.   If  the
1495              only argument is `+', the names of all parameters are printed.
1496
1497              For historical reasons, `set -' is treated as `set +xv' and `set
1498              - args' as `set +xv -- args' when in any  other  emulation  mode
1499              than zsh's native mode.
1500
1501       setcap See the section `The zsh/cap Module' in zshmodules(1).
1502
1503       setopt [ {+|-}options | {+|-}o option_name ] [ -m ] [ name ... ]
1504              Set  the  options  for  the shell.  All options specified either
1505              with flags or by name are set.
1506
1507              If no arguments are supplied, the names of all options currently
1508              set  are printed.  The form is chosen so as to minimize the dif‐
1509              ferences from the default options for the current emulation (the
1510              default  emulation  being  native  zsh,  shown  as <Z> in zshop‐
1511              tions(1)).  Options that are on by default for the emulation are
1512              shown  with  the prefix no only if they are off, while other op‐
1513              tions are shown without the prefix no and only if they  are  on.
1514              In  addition  to  options  changed from the default state by the
1515              user, any options activated automatically by the shell (for  ex‐
1516              ample,  SHIN_STDIN  or  INTERACTIVE)  will be shown in the list.
1517              The format is further modified by the  option  KSH_OPTION_PRINT,
1518              however  the  rationale for choosing options with or without the
1519              no prefix remains the same in this case.
1520
1521              If the -m flag is given the  arguments  are  taken  as  patterns
1522              (which  should  be  quoted  to protect them from filename expan‐
1523              sion), and all options with names matching  these  patterns  are
1524              set.
1525
1526              Note  that  a bad option name does not cause execution of subse‐
1527              quent shell code to be aborted; this is behaviour  is  different
1528              from  that  of  `set  -o'.  This is because set is regarded as a
1529              special builtin by the POSIX standard, but setopt is not.
1530
1531       shift [ -p ] [ n ] [ name ... ]
1532              The positional parameters ${n+1} ...  are  renamed  to  $1  ...,
1533              where  n is an arithmetic expression that defaults to 1.  If any
1534              names are given then the arrays with these names are shifted in‐
1535              stead of the positional parameters.
1536
1537              If the option -p is given arguments are instead removed (popped)
1538              from the end rather than the start of the array.
1539
1540       source file [ arg ... ]
1541              Same as  `.',  except  that  the  current  directory  is  always
1542              searched  and  is  always  searched first, before directories in
1543              $path.
1544
1545       stat   See the section `The zsh/stat Module' in zshmodules(1).
1546
1547       suspend [ -f ]
1548              Suspend the execution of the shell (send it a SIGTSTP) until  it
1549              receives  a  SIGCONT.   Unless the -f option is given, this will
1550              refuse to suspend a login shell.
1551
1552       test [ arg ... ]
1553       [ [ arg ... ] ]
1554              Like the system version of test.  Added for  compatibility;  use
1555              conditional  expressions  instead  (see the section `Conditional
1556              Expressions').  The main differences between the conditional ex‐
1557              pression syntax and the test and [ builtins are:  these commands
1558              are not handled syntactically, so for example an empty  variable
1559              expansion  may  cause  an  argument to be omitted; syntax errors
1560              cause status 2 to be returned instead  of  a  shell  error;  and
1561              arithmetic operators expect integer arguments rather than arith‐
1562              metic expressions.
1563
1564              The command attempts to implement POSIX and its extensions where
1565              these are specified.  Unfortunately there are intrinsic ambigui‐
1566              ties in the syntax; in particular there is  no  distinction  be‐
1567              tween  test operators and strings that resemble them.  The stan‐
1568              dard attempts to resolve these for small  numbers  of  arguments
1569              (up to four); for five or more arguments compatibility cannot be
1570              relied on.  Users are urged wherever possible to  use  the  `[['
1571              test syntax which does not have these ambiguities.
1572
1573       times  Print  the  accumulated  user and system times for the shell and
1574              for processes run from the shell.
1575
1576       trap [ arg ] [ sig ... ]
1577              arg is a series of commands (usually quoted to protect  it  from
1578              immediate  evaluation by the shell) to be read and executed when
1579              the shell receives any of the signals specified by one  or  more
1580              sig  args.  Each sig can be given as a number, or as the name of
1581              a signal either with or without the string SIG in front (e.g. 1,
1582              HUP, and SIGHUP are all the same signal).
1583
1584              If arg is `-', then the specified signals are reset to their de‐
1585              faults, or, if no sig args are present, all traps are reset.
1586
1587              If arg is an empty string, then the specified  signals  are  ig‐
1588              nored by the shell (and by the commands it invokes).
1589
1590              If  arg  is  omitted but one or more sig args are provided (i.e.
1591              the first argument is a valid signal number or name), the effect
1592              is the same as if arg had been specified as `-'.
1593
1594              The trap command with no arguments prints a list of commands as‐
1595              sociated with each signal.
1596
1597              If sig is ZERR then arg will be executed after each command with
1598              a nonzero exit status.  ERR is an alias for ZERR on systems that
1599              have no SIGERR signal (this is the usual case).
1600
1601              If sig is DEBUG then arg will be executed before each command if
1602              the  option  DEBUG_BEFORE_CMD is set (as it is by default), else
1603              after each command.  Here, a `command' is what is described as a
1604              `sublist'  in the shell grammar, see the section SIMPLE COMMANDS
1605              & PIPELINES in zshmisc(1).  If DEBUG_BEFORE_CMD is  set  various
1606              additional  features  are  available.   First, it is possible to
1607              skip the next command by setting the option  ERR_EXIT;  see  the
1608              description  of the ERR_EXIT option in zshoptions(1).  Also, the
1609              shell parameter ZSH_DEBUG_CMD is set to the string corresponding
1610              to  the  command  to  be executed following the trap.  Note that
1611              this string is reconstructed from the internal  format  and  may
1612              not be formatted the same way as the original text.  The parame‐
1613              ter is unset after the trap is executed.
1614
1615              If sig is 0 or EXIT and the trap statement  is  executed  inside
1616              the  body  of a function, then the command arg is executed after
1617              the function completes.  The value of $? at the start of  execu‐
1618              tion is the exit status of the shell or the return status of the
1619              function exiting.  If sig is 0 or EXIT and the trap statement is
1620              not executed inside the body of a function, then the command arg
1621              is executed when the shell terminates; the trap runs before  any
1622              zshexit hook functions.
1623
1624              ZERR, DEBUG, and EXIT traps are not executed inside other traps.
1625              ZERR and DEBUG traps are  kept  within  subshells,  while  other
1626              traps are reset.
1627
1628              Note  that traps defined with the trap builtin are slightly dif‐
1629              ferent from those defined as `TRAPNAL () { ... }', as the latter
1630              have  their  own function environment (line numbers, local vari‐
1631              ables, etc.) while the former use the environment of the command
1632              in which they were called.  For example,
1633
1634                     trap 'print $LINENO' DEBUG
1635
1636              will  print  the  line number of a command executed after it has
1637              run, while
1638
1639                     TRAPDEBUG() { print $LINENO; }
1640
1641              will always print the number zero.
1642
1643              Alternative signal names are allowed  as  described  under  kill
1644              above.   Defining a trap under either name causes any trap under
1645              an alternative name to be removed.  However, it  is  recommended
1646              that  for consistency users stick exclusively to one name or an‐
1647              other.
1648
1649       true [ arg ... ]
1650              Do nothing and return an exit status of 0.
1651
1652       ttyctl [ -fu ]
1653              The -f option freezes the tty (i.e. terminal or terminal  emula‐
1654              tor),  and  -u unfreezes it.  When the tty is frozen, no changes
1655              made to the tty settings by external programs will be honored by
1656              the  shell,  except  for  changes in the size of the screen; the
1657              shell will simply reset the settings to their previous values as
1658              soon as each command exits or is suspended.  Thus, stty and sim‐
1659              ilar programs have no effect when the tty is  frozen.   Freezing
1660              the  tty  does not cause the current state to be remembered: in‐
1661              stead, it causes future changes to the state to be blocked.
1662
1663              Without options it reports whether the  terminal  is  frozen  or
1664              not.
1665
1666              Note  that,  regardless of whether the tty is frozen or not, the
1667              shell needs to change the settings when the line editor  starts,
1668              so  unfreezing  the  tty does not guarantee settings made on the
1669              command line are preserved.  Strings  of  commands  run  between
1670              editing  the  command line will see a consistent tty state.  See
1671              also the shell variable STTY for a means of initialising the tty
1672              before running external commands.
1673
1674       type [ -wfpamsS ] name ...
1675              Equivalent to whence -v.
1676
1677
1678       typeset [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ n ] ]
1679               [ + ] [ name[=value] ... ]
1680       typeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ n ] ]
1681               [ + | SCALAR[=value] array[=(value ...)] [ sep ] ]
1682       typeset -f [ {+|-}TUkmtuz ] [ + ] [ name ... ]
1683              Set or display attributes and values for shell parameters.
1684
1685              Except  as  noted below for control flags that change the behav‐
1686              ior, a parameter is created for each name that does not  already
1687              refer  to  one.  When inside a function, a new parameter is cre‐
1688              ated for every name (even those that already exist), and is  un‐
1689              set  again  when the function completes.  See `Local Parameters'
1690              in zshparam(1).  The same rules apply to special  shell  parame‐
1691              ters, which retain their special attributes when made local.
1692
1693              For  each  name=value  assignment,  the parameter name is set to
1694              value.
1695
1696              If the shell option TYPESET_SILENT is not set, for each  remain‐
1697              ing  name  that  refers  to a parameter that is already set, the
1698              name and value of the parameter are printed in the  form  of  an
1699              assignment.  Nothing is printed for newly-created parameters, or
1700              when any attribute flags listed below are given along  with  the
1701              name.   Using  `+'  instead  of  minus to introduce an attribute
1702              turns it off.
1703
1704              If no name is present, the names and values  of  all  parameters
1705              are printed.  In this case the attribute flags restrict the dis‐
1706              play to only  those  parameters  that  have  the  specified  at‐
1707              tributes,  and  using  `+' rather than `-' to introduce the flag
1708              suppresses printing of the values of parameters when there is no
1709              parameter name.
1710
1711              All  forms  of  the command handle scalar assignment.  Array as‐
1712              signment is possible if any of the reserved words  declare,  ex‐
1713              port, float, integer, local, readonly or typeset is matched when
1714              the line is parsed (N.B. not when it is executed).  In this case
1715              the  arguments  are  parsed as assignments, except that the `+='
1716              syntax and the GLOB_ASSIGN option are not supported, and  scalar
1717              values  after  =  are  not split further into words, even if ex‐
1718              panded (regardless of the setting  of  the  KSH_TYPESET  option;
1719              this option is obsolete).
1720
1721              Examples  of  the  differences between command and reserved word
1722              parsing:
1723
1724                     # Reserved word parsing
1725                     typeset svar=$(echo one word) avar=(several words)
1726
1727              The above creates a scalar parameter svar and an array parameter
1728              avar as if the assignments had been
1729
1730                     svar="one word"
1731                     avar=(several words)
1732
1733              On the other hand:
1734
1735                     # Normal builtin interface
1736                     builtin typeset svar=$(echo two words)
1737
1738              The builtin keyword causes the above to use the standard builtin
1739              interface to typeset in which argument parsing is  performed  in
1740              the  same  way  as  for  other commands.  This example creates a
1741              scalar svar containing the value two and another scalar  parame‐
1742              ter  words with no value.  An array value in this case would ei‐
1743              ther cause an error or be treated as  an  obscure  set  of  glob
1744              qualifiers.
1745
1746              Arbitrary arguments are allowed if they take the form of assign‐
1747              ments after command line expansion; however, these only  perform
1748              scalar assignment:
1749
1750                     var='svar=val'
1751                     typeset $var
1752
1753              The  above  sets  the  scalar  parameter  svar to the value val.
1754              Parentheses around the value within var would  not  cause  array
1755              assignment  as  they will be treated as ordinary characters when
1756              $var is substituted.  Any non-trivial expansion in the name part
1757              of  the  assignment  causes  the  argument to be treated in this
1758              fashion:
1759
1760                     typeset {var1,var2,var3}=name
1761
1762              The above syntax is valid, and has the expected effect  of  set‐
1763              ting  the  three  parameters  to the same value, but the command
1764              line is parsed as a set of three normal command  line  arguments
1765              to  typeset after expansion.  Hence it is not possible to assign
1766              to multiple arrays by this means.
1767
1768              Note that each interface to any of the commands my  be  disabled
1769              separately.   For example, `disable -r typeset' disables the re‐
1770              served word interface to typeset, exposing  the  builtin  inter‐
1771              face,  while  `disable typeset' disables the builtin.  Note that
1772              disabling the reserved word  interface  for  typeset  may  cause
1773              problems  with the output of `typeset -p', which assumes the re‐
1774              served word interface is available in order to restore array and
1775              associative array values.
1776
1777              Unlike parameter assignment statements, typeset's exit status on
1778              an assignment that involves a command substitution does not  re‐
1779              flect  the  exit status of the command substitution.  Therefore,
1780              to test for an error in a  command  substitution,  separate  the
1781              declaration of the parameter from its initialization:
1782
1783                     # WRONG
1784                     typeset var1=$(exit 1) || echo "Trouble with var1"
1785
1786                     # RIGHT
1787                     typeset var1 && var1=$(exit 1) || echo "Trouble with var1"
1788
1789              To  initialize a parameter param to a command output and mark it
1790              readonly, use typeset -r param or readonly param after  the  pa‐
1791              rameter assignment statement.
1792
1793              If  no  attribute  flags are given, and either no name arguments
1794              are present or the flag +m is used,  then  each  parameter  name
1795              printed  is preceded by a list of the attributes of that parame‐
1796              ter (array, association, exported, float, integer, readonly,  or
1797              undefined  for  autoloaded parameters not yet loaded).  If +m is
1798              used with attribute flags, and all those  flags  are  introduced
1799              with  +, the matching parameter names are printed but their val‐
1800              ues are not.
1801
1802              The following control flags change the behavior of typeset:
1803
1804              +      If `+' appears by itself in a separate word as  the  last
1805                     option,  then the names of all parameters (functions with
1806                     -f) are printed, but the  values  (function  bodies)  are
1807                     not.   No  name  arguments may appear, and it is an error
1808                     for any other options to follow `+'.  The effect  of  `+'
1809                     is  as if all attribute flags which precede it were given
1810                     with a `+' prefix.  For example, `typeset -U +' is equiv‐
1811                     alent  to  `typeset +U' and displays the names of all ar‐
1812                     rays having the uniqueness attribute, whereas `typeset -f
1813                     -U  +'  displays the names of all autoloadable functions.
1814                     If + is the only option, then  type  information  (array,
1815                     readonly,  etc.)  is  also printed for each parameter, in
1816                     the same manner as `typeset +m "*"'.
1817
1818              -g     The -g (global) means that any resulting  parameter  will
1819                     not  be  restricted  to local scope.  Note that this does
1820                     not necessarily mean that the parameter will  be  global,
1821                     as the flag will apply to any existing parameter (even if
1822                     unset) from an enclosing function.  This  flag  does  not
1823                     affect  the parameter after creation, hence it has no ef‐
1824                     fect when listing existing parameters, nor does the  flag
1825                     +g have any effect except in combination with -m (see be‐
1826                     low).
1827
1828              -m     If the -m flag is given the name arguments are  taken  as
1829                     patterns  (use quoting to prevent these from being inter‐
1830                     preted as file patterns).  With no attribute  flags,  all
1831                     parameters  (or functions with the -f flag) with matching
1832                     names are printed (the shell option TYPESET_SILENT is not
1833                     used in this case).
1834
1835                     If the +g flag is combined with -m, a new local parameter
1836                     is created for every matching parameter that is  not  al‐
1837                     ready local.  Otherwise -m applies all other flags or as‐
1838                     signments to the existing parameters.
1839
1840                     Except when assignments are made with  name=value,  using
1841                     +m forces the matching parameters and their attributes to
1842                     be printed, even inside a function.  Note that -m is  ig‐
1843                     nored  if no patterns are given, so `typeset -m' displays
1844                     attributes but `typeset -a +m' does not.
1845
1846              -p [ n ]
1847                     If the -p option is  given,  parameters  and  values  are
1848                     printed  in the form of a typeset command with an assign‐
1849                     ment, regardless of other flags and options.   Note  that
1850                     the  -H flag on parameters is respected; no value will be
1851                     shown for these parameters.
1852
1853                     -p may be followed by an optional integer argument.  Cur‐
1854                     rently  only  the value 1 is supported.  In this case ar‐
1855                     rays and associative arrays are printed with newlines be‐
1856                     tween indented elements for readability.
1857
1858              -T [ scalar[=value] array[=(value ...)] [ sep ] ]
1859                     This  flag has a different meaning when used with -f; see
1860                     below.  Otherwise the -T option requires  zero,  two,  or
1861                     three  arguments  to  be present.  With no arguments, the
1862                     list of parameters created  in  this  fashion  is  shown.
1863                     With  two  or three arguments, the first two are the name
1864                     of a scalar and of an array  parameter  (in  that  order)
1865                     that  will  be  tied  together in the manner of $PATH and
1866                     $path.  The optional third argument is a single-character
1867                     separator  which will be used to join the elements of the
1868                     array to form the scalar; if absent, a colon is used,  as
1869                     with $PATH.  Only the first character of the separator is
1870                     significant;  any  remaining  characters   are   ignored.
1871                     Multibyte characters are not yet supported.
1872
1873                     Only  one  of  the scalar and array parameters may be as‐
1874                     signed an initial value (the restrictions  on  assignment
1875                     forms described above also apply).
1876
1877                     Both  the scalar and the array may be manipulated as nor‐
1878                     mal.  If one is unset, the other  will  automatically  be
1879                     unset  too.   There  is  no  way of untying the variables
1880                     without unsetting them, nor of converting the type of one
1881                     of  them  with another typeset command; +T does not work,
1882                     assigning an array to scalar is an error, and assigning a
1883                     scalar to array sets it to be a single-element array.
1884
1885                     Note  that  both  `typeset  -xT ...'  and `export -T ...'
1886                     work, but only the scalar  will  be  marked  for  export.
1887                     Setting the value using the scalar version causes a split
1888                     on all separators (which cannot be quoted).  It is possi‐
1889                     ble to apply -T to two previously tied variables but with
1890                     a different separator character, in which case the  vari‐
1891                     ables  remain  joined  as  before  but  the  separator is
1892                     changed.
1893
1894                     When an existing scalar is tied to a new array, the value
1895                     of  the  scalar  is preserved but no attribute other than
1896                     export will be preserved.
1897
1898              Attribute flags that transform the final value (-L, -R, -Z,  -l,
1899              -u) are only applied to the expanded value at the point of a pa‐
1900              rameter expansion expression using `$'.  They  are  not  applied
1901              when  a  parameter  is retrieved internally by the shell for any
1902              purpose.
1903
1904              The following attribute flags may be specified:
1905
1906              -A     The names refer to associative array parameters; see `Ar‐
1907                     ray Parameters' in zshparam(1).
1908
1909              -L [ n ]
1910                     Left  justify  and  remove  leading blanks from the value
1911                     when the parameter is expanded.  If n is nonzero, it  de‐
1912                     fines the width of the field.  If n is zero, the width is
1913                     determined by the width of the value of the first assign‐
1914                     ment.   In  the case of numeric parameters, the length of
1915                     the complete value assigned to the parameter is  used  to
1916                     determine the width, not the value that would be output.
1917
1918                     The width is the count of characters, which may be multi‐
1919                     byte characters if the MULTIBYTE  option  is  in  effect.
1920                     Note  that the screen width of the character is not taken
1921                     into account; if this is required, use padding  with  pa‐
1922                     rameter  expansion  flags  ${(ml...)...}  as described in
1923                     `Parameter Expansion Flags' in zshexpn(1).
1924
1925                     When the parameter is expanded, it is filled on the right
1926                     with  blanks  or truncated if necessary to fit the field.
1927                     Note truncation can lead to unexpected results  with  nu‐
1928                     meric  parameters.   Leading  zeros are removed if the -Z
1929                     flag is also set.
1930
1931              -R [ n ]
1932                     Similar to -L, except that right justification  is  used;
1933                     when  the parameter is expanded, the field is left filled
1934                     with blanks or truncated from the end.  May not  be  com‐
1935                     bined with the -Z flag.
1936
1937              -U     For  arrays  (but  not for associative arrays), keep only
1938                     the first occurrence of each duplicated value.  This  may
1939                     also  be  set for tied parameters (see -T) or colon-sepa‐
1940                     rated special parameters like PATH or FIGNORE, etc.  Note
1941                     the  flag takes effect on assignment, and the type of the
1942                     variable being assigned to is  determinative;  for  vari‐
1943                     ables  with  shared values it is therefore recommended to
1944                     set the flag for all interfaces, e.g.  `typeset  -U  PATH
1945                     path'.
1946
1947                     This  flag has a different meaning when used with -f; see
1948                     below.
1949
1950              -Z [ n ]
1951                     Specially handled if set along with the -L flag.   Other‐
1952                     wise,  similar  to -R, except that leading zeros are used
1953                     for padding instead of  blanks  if  the  first  non-blank
1954                     character  is  a digit.  Numeric parameters are specially
1955                     handled: they are always eligible for  padding  with  ze‐
1956                     roes, and the zeroes are inserted at an appropriate place
1957                     in the output.
1958
1959              -a     The names refer to array parameters.  An array  parameter
1960                     may be created this way, but it may be assigned to in the
1961                     typeset statement only if the reserved word form of type‐
1962                     set  is  enabled (as it is by default).  When displaying,
1963                     both normal and associative arrays are shown.
1964
1965              -f     The names refer to functions rather than parameters.   No
1966                     assignments  can  be made, and the only other valid flags
1967                     are -t, -T, -k, -u, -U and -z.  The flag -t turns on exe‐
1968                     cution  tracing  for  this function; the flag -T does the
1969                     same, but turns off tracing for any named (not anonymous)
1970                     function  called  from the present one, unless that func‐
1971                     tion also has the -t or -T flag.  The  -u  and  -U  flags
1972                     cause  the function to be marked for autoloading; -U also
1973                     causes alias expansion to be suppressed when the function
1974                     is loaded.  See the description of the `autoload' builtin
1975                     for details.
1976
1977                     Note that the builtin functions provides the  same  basic
1978                     capabilities  as typeset -f but gives access to a few ex‐
1979                     tra options; autoload gives  further  additional  options
1980                     for the case typeset -fu and typeset -fU.
1981
1982              -h     Hide:  only  useful  for special parameters (those marked
1983                     `<S>' in the table in zshparam(1)), and for local parame‐
1984                     ters  with  the  same name as a special parameter, though
1985                     harmless for others.  A special parameter with  this  at‐
1986                     tribute  will not retain its special effect when made lo‐
1987                     cal.  Thus after `typeset -h PATH', a function containing
1988                     `typeset  PATH'  will  create an ordinary local parameter
1989                     without the usual behaviour of PATH.  Alternatively,  the
1990                     local parameter may itself be given this attribute; hence
1991                     inside a function `typeset -h PATH' creates  an  ordinary
1992                     local parameter and the special PATH parameter is not al‐
1993                     tered in any way.  It is also possible to create a  local
1994                     parameter  using  `typeset  +h  special', where the local
1995                     copy of special will retain its  special  properties  re‐
1996                     gardless  of having the -h attribute.  Global special pa‐
1997                     rameters loaded from shell modules  (currently  those  in
1998                     zsh/mapfile  and  zsh/parameter)  are automatically given
1999                     the -h attribute to avoid name clashes.
2000
2001              -H     Hide value: specifies that typeset will not  display  the
2002                     value  of the parameter when listing parameters; the dis‐
2003                     play for such parameters is always as if the `+' flag had
2004                     been  given.   Use  of the parameter is in other respects
2005                     normal, and the option does not apply if the parameter is
2006                     specified  by  name,  or  by  pattern with the -m option.
2007                     This is on by default for the parameters in  the  zsh/pa‐
2008                     rameter and zsh/mapfile modules.  Note, however, that un‐
2009                     like the -h flag this is also useful for non-special  pa‐
2010                     rameters.
2011
2012              -i [ n ]
2013                     Use  an internal integer representation.  If n is nonzero
2014                     it defines the output arithmetic base,  otherwise  it  is
2015                     determined  by  the first assignment.  Bases from 2 to 36
2016                     inclusive are allowed.
2017
2018              -E [ n ]
2019                     Use an internal double-precision floating point represen‐
2020                     tation.  On output the variable will be converted to sci‐
2021                     entific notation.  If n is nonzero it defines the  number
2022                     of significant figures to display; the default is ten.
2023
2024              -F [ n ]
2025                     Use an internal double-precision floating point represen‐
2026                     tation.  On output the  variable  will  be  converted  to
2027                     fixed-point decimal notation.  If n is nonzero it defines
2028                     the number of digits to display after the decimal  point;
2029                     the default is ten.
2030
2031              -l     Convert  the  result to lower case whenever the parameter
2032                     is expanded.  The value is not converted when assigned.
2033
2034              -r     The given names are marked readonly.  Note that  if  name
2035                     is  a  special  parameter,  the readonly attribute can be
2036                     turned on, but cannot then be turned off.
2037
2038                     If the POSIX_BUILTINS option is set, the readonly  attri‐
2039                     bute  is  more restrictive: unset variables can be marked
2040                     readonly and cannot then be set; furthermore,  the  read‐
2041                     only attribute cannot be removed from any variable.
2042
2043                     It  is  still  possible to change other attributes of the
2044                     variable though, some of which like -U or -Z would affect
2045                     the  value. More generally, the readonly attribute should
2046                     not be relied on as a security mechanism.
2047
2048                     Note that in zsh (like in pdksh  but  unlike  most  other
2049                     shells)  it  is still possible to create a local variable
2050                     of the same name as this is considered a different  vari‐
2051                     able (though this variable, too, can be marked readonly).
2052                     Special variables that have  been  made  readonly  retain
2053                     their value and readonly attribute when made local.
2054
2055              -t     Tags  the named parameters.  Tags have no special meaning
2056                     to the shell.  This flag has  a  different  meaning  when
2057                     used with -f; see above.
2058
2059              -u     Convert  the  result to upper case whenever the parameter
2060                     is expanded.  The value is not converted  when  assigned.
2061                     This  flag has a different meaning when used with -f; see
2062                     above.
2063
2064              -x     Mark for automatic export to the  environment  of  subse‐
2065                     quently  executed  commands.  If the option GLOBAL_EXPORT
2066                     is set, this implies the option -g, unless +g is also ex‐
2067                     plicitly  given; in other words the parameter is not made
2068                     local to the enclosing function.  This is for compatibil‐
2069                     ity with previous versions of zsh.
2070
2071       ulimit [ -HSa ] [ { -bcdfiklmnpqrsTtvwx | -N resource } [ limit ] ... ]
2072              Set  or  display  resource limits of the shell and the processes
2073              started by the shell.  The value of limit can be a number in the
2074              unit specified below or one of the values `unlimited', which re‐
2075              moves the limit on the resource, or `hard', which uses the  cur‐
2076              rent value of the hard limit on the resource.
2077
2078              By  default, only soft limits are manipulated. If the -H flag is
2079              given use hard limits instead of soft limits.  If the -S flag is
2080              given together with the -H flag set both hard and soft limits.
2081
2082              If no options are used, the file size limit (-f) is assumed.
2083
2084              If limit is omitted the current value of the specified resources
2085              are printed.  When more than one resource value is printed,  the
2086              limit name and unit is printed before each value.
2087
2088              When looping over multiple resources, the shell will abort imme‐
2089              diately if it detects a badly formed argument.  However,  if  it
2090              fails to set a limit for some other reason it will continue try‐
2091              ing to set the remaining limits.
2092
2093              Not all the following resources are supported  on  all  systems.
2094              Running ulimit -a will show which are supported.
2095
2096              -a     Lists all of the current resource limits.
2097              -b     Socket buffer size in bytes (N.B. not kilobytes)
2098              -c     512-byte blocks on the size of core dumps.
2099              -d     Kilobytes on the size of the data segment.
2100              -f     512-byte blocks on the size of files written.
2101              -i     The number of pending signals.
2102              -k     The number of kqueues allocated.
2103              -l     Kilobytes on the size of locked-in memory.
2104              -m     Kilobytes on the size of physical memory.
2105              -n     open file descriptors.
2106              -p     The number of pseudo-terminals.
2107              -q     Bytes in POSIX message queues.
2108              -r     Maximum  real  time priority.  On some systems where this
2109                     is not available, such as NetBSD, this has the  same  ef‐
2110                     fect as -T for compatibility with sh.
2111              -s     Kilobytes on the size of the stack.
2112              -T     The number of simultaneous threads available to the user.
2113              -t     CPU seconds to be used.
2114              -u     The number of processes available to the user.
2115              -v     Kilobytes on the size of virtual memory.  On some systems
2116                     this refers to the limit called `address space'.
2117              -w     Kilobytes on the size of swapped out memory.
2118              -x     The number of locks on files.
2119
2120              A resource may also be specified by integer in the form `-N  re‐
2121              source',  where  resource corresponds to the integer defined for
2122              the resource by the operating system.  This may be used  to  set
2123              the  limits for resources known to the shell which do not corre‐
2124              spond to option letters.  Such limits will be shown by number in
2125              the output of `ulimit -a'.
2126
2127              The  number may alternatively be out of the range of limits com‐
2128              piled into the shell.  The shell will try to read or  write  the
2129              limit anyway, and will report an error if this fails.
2130
2131       umask [ -S ] [ mask ]
2132              The umask is set to mask.  mask can be either an octal number or
2133              a symbolic value as described in chmod(1).  If mask is  omitted,
2134              the  current value is printed.  The -S option causes the mask to
2135              be printed as a symbolic value.  Otherwise, the mask is  printed
2136              as  an octal number.  Note that in the symbolic form the permis‐
2137              sions you specify are those which are to be allowed (not denied)
2138              to the users specified.
2139
2140       unalias [ -ams ] name ...
2141              Removes  aliases.  This command works the same as unhash -a, ex‐
2142              cept that the -a option removes all regular or  global  aliases,
2143              or  with  -s  all suffix aliases: in this case no name arguments
2144              may appear.  The options -m (remove by pattern) and  -s  without
2145              -a (remove listed suffix aliases) behave as for unhash -a.  Note
2146              that the meaning of -a is different between unalias and unhash.
2147
2148       unfunction
2149              Same as unhash -f.
2150
2151       unhash [ -adfms ] name ...
2152              Remove the element named name from an internal hash table.   The
2153              default  is remove elements from the command hash table.  The -a
2154              option causes unhash to remove regular or global  aliases;  note
2155              when  removing a global aliases that the argument must be quoted
2156              to prevent it from being expanded before  being  passed  to  the
2157              command.   The -s option causes unhash to remove suffix aliases.
2158              The -f option causes unhash to remove shell functions.   The  -d
2159              options  causes  unhash  to remove named directories.  If the -m
2160              flag is given the arguments are taken  as  patterns  (should  be
2161              quoted)  and  all  elements of the corresponding hash table with
2162              matching names will be removed.
2163
2164       unlimit [ -hs ] resource ...
2165              The resource limit for each resource is set to the  hard  limit.
2166              If  the  -h  flag  is given and the shell has appropriate privi‐
2167              leges, the hard resource limit for  each  resource  is  removed.
2168              The  resources  of  the shell process are only changed if the -s
2169              flag is given.
2170
2171              The unlimit command is not made available by  default  when  the
2172              shell  starts in a mode emulating another shell.  It can be made
2173              available with the command `zmodload -F zsh/rlimits b:unlimit'.
2174
2175       unset [ -fmv ] name ...
2176              Each named parameter is unset.  Local  parameters  remain  local
2177              even  if unset; they appear unset within scope, but the previous
2178              value will still reappear when the scope ends.
2179
2180              Individual elements of associative array parameters may be unset
2181              by  using  subscript  syntax on name, which should be quoted (or
2182              the entire command prefixed with noglob)  to  protect  the  sub‐
2183              script from filename generation.
2184
2185              If  the -m flag is specified the arguments are taken as patterns
2186              (should be quoted) and all parameters with  matching  names  are
2187              unset.  Note that this cannot be used when unsetting associative
2188              array elements, as the subscript will be treated as part of  the
2189              pattern.
2190
2191              The  -v  flag  specifies that name refers to parameters. This is
2192              the default behaviour.
2193
2194              unset -f is equivalent to unfunction.
2195
2196       unsetopt [ {+|-}options | {+|-}o option_name ] [ name ... ]
2197              Unset the options for the shell.  All options  specified  either
2198              with  flags or by name are unset.  If no arguments are supplied,
2199              the names of all options currently unset are printed.  If the -m
2200              flag  is given the arguments are taken as patterns (which should
2201              be quoted to preserve them from being interpreted as  glob  pat‐
2202              terns),  and  all options with names matching these patterns are
2203              unset.
2204
2205       vared  See the section `Zle Builtins' in zshzle(1).
2206
2207       wait [ job ... ]
2208              Wait for the specified jobs or processes.  If job is  not  given
2209              then  all currently active child processes are waited for.  Each
2210              job can be either a job specification or the process ID of a job
2211              in  the job table.  The exit status from this command is that of
2212              the job waited for.  If job represents an unknown job or process
2213              ID,  a  warning  is printed (unless the POSIX_BUILTINS option is
2214              set) and the exit status is 127.
2215
2216              It is possible  to  wait  for  recent  processes  (specified  by
2217              process ID, not by job) that were running in the background even
2218              if the process has exited.  Typically the  process  ID  will  be
2219              recorded  by  capturing the value of the variable $! immediately
2220              after the process has been started.  There is  a  limit  on  the
2221              number  of process IDs remembered by the shell; this is given by
2222              the value of the system configuration parameter CHILD_MAX.  When
2223              this  limit  is  reached, older process IDs are discarded, least
2224              recently started processes first.
2225
2226              Note there is no protection against  the  process  ID  wrapping,
2227              i.e.  if  the wait is not executed soon enough there is a chance
2228              the process waited for is the wrong  one.   A  conflict  implies
2229              both process IDs have been generated by the shell, as other pro‐
2230              cesses are not recorded, and that the user is potentially inter‐
2231              ested in both, so this problem is intrinsic to process IDs.
2232
2233       whence [ -vcwfpamsS ] [ -x num ] name ...
2234              For each name, indicate how it would be interpreted if used as a
2235              command name.
2236
2237              If name is not an alias,  built-in  command,  external  command,
2238              shell  function,  hashed  command,  or a reserved word, the exit
2239              status shall be non-zero, and -- if -v, -c, or -w was passed  --
2240              a  message will be written to standard output.  (This is differ‐
2241              ent from other shells that write that message  to  standard  er‐
2242              ror.)
2243
2244              whence  is most useful when name is only the last path component
2245              of a command, i.e. does not include a `/'; in  particular,  pat‐
2246              tern  matching only succeeds if just the non-directory component
2247              of the command is passed.
2248
2249              -v     Produce a more verbose report.
2250
2251              -c     Print the results  in  a  csh-like  format.   This  takes
2252                     precedence over -v.
2253
2254              -w     For  each  name,  print `name: word' where word is one of
2255                     alias, builtin, command, function,  hashed,  reserved  or
2256                     none,  according  as  name  corresponds  to  an  alias, a
2257                     built-in command, an external command, a shell  function,
2258                     a command defined with the hash builtin, a reserved word,
2259                     or is not recognised.  This takes precedence over -v  and
2260                     -c.
2261
2262              -f     Causes  the contents of a shell function to be displayed,
2263                     which would otherwise not happen unless the -c flag  were
2264                     used.
2265
2266              -p     Do  a  path  search  for name even if it is an alias, re‐
2267                     served word, shell function or builtin.
2268
2269              -a     Do a search for all occurrences of  name  throughout  the
2270                     command  path.   Normally  only  the  first occurrence is
2271                     printed.
2272
2273              -m     The arguments are taken as patterns  (pattern  characters
2274                     should  be  quoted), and the information is displayed for
2275                     each command matching one of these patterns.
2276
2277              -s     If a pathname contains symlinks, print  the  symlink-free
2278                     pathname as well.
2279
2280              -S     As  -s, but if the pathname had to be resolved by follow‐
2281                     ing  multiple  symlinks,  the  intermediate   steps   are
2282                     printed, too.  The symlink resolved at each step might be
2283                     anywhere in the path.
2284
2285              -x num Expand tabs when outputting shell functions using the  -c
2286                     option.  This has the same effect as the -x option to the
2287                     functions builtin.
2288
2289       where [ -wpmsS ] [ -x num ] name ...
2290              Equivalent to whence -ca.
2291
2292       which [ -wpamsS ] [ -x num ] name ...
2293              Equivalent to whence -c.
2294
2295       zcompile [ -U ] [ -z | -k ] [ -R | -M ] file [ name ... ]
2296       zcompile -ca [ -m ] [ -R | -M ] file [ name ... ]
2297       zcompile -t file [ name ... ]
2298              This builtin  command  can  be  used  to  compile  functions  or
2299              scripts,  storing  the  compiled  form in a file, and to examine
2300              files containing the compiled  form.   This  allows  faster  au‐
2301              toloading of functions and sourcing of scripts by avoiding pars‐
2302              ing of the text when the files are read.
2303
2304              The first form (without the -c, -a or -t options) creates a com‐
2305              piled file.  If only the file argument is given, the output file
2306              has the name `file.zwc' and will be placed in the same directory
2307              as  the  file.  The shell will load the compiled file instead of
2308              the normal function file when the function  is  autoloaded;  see
2309              the section `Autoloading Functions' in zshmisc(1) for a descrip‐
2310              tion of how autoloaded functions are  searched.   The  extension
2311              .zwc stands for `zsh word code'.
2312
2313              If  there is at least one name argument, all the named files are
2314              compiled into the output file given as the first  argument.   If
2315              file  does  not end in .zwc, this extension is automatically ap‐
2316              pended.  Files containing multiple compiled functions are called
2317              `digest'  files,  and are intended to be used as elements of the
2318              FPATH/fpath special array.
2319
2320              The second form, with the -c or -a options, writes the  compiled
2321              definitions  for all the named functions into file.  For -c, the
2322              names must be functions currently  defined  in  the  shell,  not
2323              those  marked  for  autoloading.   Undefined  functions that are
2324              marked for autoloading may be written by using the -a option, in
2325              which case the fpath is searched and the contents of the defini‐
2326              tion files for those functions,  if  found,  are  compiled  into
2327              file.   If both -c and -a are given, names of both defined func‐
2328              tions and functions marked for autoloading may be given.  In ei‐
2329              ther  case, the functions in files written with the -c or -a op‐
2330              tion will be autoloaded as if the KSH_AUTOLOAD option  were  un‐
2331              set.
2332
2333              The reason for handling loaded and not-yet-loaded functions with
2334              different options is that some definition files for  autoloading
2335              define  multiple functions, including the function with the same
2336              name as the file, and, at the end, call that function.  In  such
2337              cases  the  output  of  `zcompile -c' does not include the addi‐
2338              tional functions defined in the file, and any other  initializa‐
2339              tion code in the file is lost.  Using `zcompile -a' captures all
2340              this extra information.
2341
2342              If the -m option is combined with -c or -a, the names  are  used
2343              as  patterns  and  all  functions whose names match one of these
2344              patterns will be written. If no name is given,  the  definitions
2345              of  all functions currently defined or marked as autoloaded will
2346              be written.
2347
2348              Note the second form cannot be used for compiling functions that
2349              include  redirections  as  part  of  the  definition rather than
2350              within the body of the function; for example
2351
2352                     fn1() { { ... } >~/logfile }
2353
2354              can be compiled but
2355
2356                     fn1() { ... } >~/logfile
2357
2358              cannot.  It is possible to use the first  form  of  zcompile  to
2359              compile  autoloadable  functions  that include the full function
2360              definition instead of just the body of the function.
2361
2362              The third form, with the -t option, examines  an  existing  com‐
2363              piled  file.  Without further arguments, the names of the origi‐
2364              nal files compiled into it are listed.  The first line of output
2365              shows  the  version of the shell which compiled the file and how
2366              the file will be used (i.e. by reading it directly or by mapping
2367              it  into memory).  With arguments, nothing is output and the re‐
2368              turn status is set to zero if definitions  for  all  names  were
2369              found  in  the compiled file, and non-zero if the definition for
2370              at least one name was not found.
2371
2372              Other options:
2373
2374              -U     Aliases are not expanded when compiling the named files.
2375
2376              -R     When the compiled file is read, its contents  are  copied
2377                     into  the  shell's memory, rather than memory-mapped (see
2378                     -M).  This happens automatically on systems that  do  not
2379                     support memory mapping.
2380
2381                     When compiling scripts instead of autoloadable functions,
2382                     it is often desirable to use this option;  otherwise  the
2383                     whole  file, including the code to define functions which
2384                     have already been defined,  will  remain  mapped,  conse‐
2385                     quently wasting memory.
2386
2387              -M     The  compiled file is mapped into the shell's memory when
2388                     read. This is done in such a way that multiple  instances
2389                     of  the  shell  running  on the same host will share this
2390                     mapped file.  If neither -R nor -M is given, the zcompile
2391                     builtin  decides what to do based on the size of the com‐
2392                     piled file.
2393
2394              -k
2395              -z     These options are used when the  compiled  file  contains
2396                     functions which are to be autoloaded. If -z is given, the
2397                     function will be autoloaded as if the KSH_AUTOLOAD option
2398                     is  not  set,  even if it is set at the time the compiled
2399                     file is read, while if the -k is given, the function will
2400                     be  loaded as if KSH_AUTOLOAD is set.  These options also
2401                     take precedence over any -k or -z  options  specified  to
2402                     the  autoload  builtin.  If  neither  of these options is
2403                     given, the function will be loaded as determined  by  the
2404                     setting  of  the KSH_AUTOLOAD option at the time the com‐
2405                     piled file is read.
2406
2407                     These options may also appear as many times as  necessary
2408                     between  the listed names to specify the loading style of
2409                     all following functions, up to the next -k or -z.
2410
2411                     The created file always contains two versions of the com‐
2412                     piled  format,  one  for  big-endian machines and one for
2413                     small-endian machines.  The upshot of this  is  that  the
2414                     compiled file is machine independent and if it is read or
2415                     mapped, only one half of the file is actually  used  (and
2416                     mapped).
2417
2418       zformat
2419              See the section `The zsh/zutil Module' in zshmodules(1).
2420
2421       zftp   See the section `The zsh/zftp Module' in zshmodules(1).
2422
2423       zle    See the section `Zle Builtins' in zshzle(1).
2424
2425       zmodload [ -dL ] [ -s ] [ ... ]
2426       zmodload -F [ -alLme -P param ] module [ [+-]feature ... ]
2427       zmodload -e [ -A ] [ ... ]
2428       zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...
2429       zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...
2430       zmodload -A [ -L ] [ modalias[=module] ... ]
2431       zmodload -R modalias ...
2432              Performs operations relating to zsh's loadable modules.  Loading
2433              of modules while the shell is running (`dynamical  loading')  is
2434              not  available on all operating systems, or on all installations
2435              on a particular operating system, although the zmodload  command
2436              itself is always available and can be used to manipulate modules
2437              built into versions of the shell  executable  without  dynamical
2438              loading.
2439
2440              Without  arguments the names of all currently loaded binary mod‐
2441              ules are printed.  The -L option causes this list to be  in  the
2442              form  of  a  series  of zmodload commands.  Forms with arguments
2443              are:
2444
2445              zmodload [ -is ] name ...
2446              zmodload -u [ -i ] name ...
2447                     In the simplest case, zmodload  loads  a  binary  module.
2448                     The  module  must  be in a file with a name consisting of
2449                     the specified name followed by a standard suffix, usually
2450                     `.so' (`.sl' on HPUX).  If the module to be loaded is al‐
2451                     ready loaded the duplicate module is ignored.   If  zmod‐
2452                     load  detects an inconsistency, such as an invalid module
2453                     name or circular dependency list, the current code  block
2454                     is  aborted.  If it is available, the module is loaded if
2455                     necessary, while if it is not available, non-zero  status
2456                     is silently returned.  The option -i is accepted for com‐
2457                     patibility but has no effect.
2458
2459                     The named module is searched for in the same way  a  com‐
2460                     mand  is,  using $module_path instead of $path.  However,
2461                     the path search is performed even when  the  module  name
2462                     contains  a  `/', which it usually does.  There is no way
2463                     to prevent the path search.
2464
2465                     If the module supports  features  (see  below),  zmodload
2466                     tries  to  enable all features when loading a module.  If
2467                     the module was successfully loaded but not  all  features
2468                     could be enabled, zmodload returns status 2.
2469
2470                     If  the  option  -s  is given, no error is printed if the
2471                     module was not available (though other errors  indicating
2472                     a  problem with the module are printed).  The return sta‐
2473                     tus indicates if the module was loaded.  This  is  appro‐
2474                     priate if the caller considers the module optional.
2475
2476                     With -u, zmodload unloads modules.  The same name must be
2477                     given that was given when the module was loaded,  but  it
2478                     is not necessary for the module to exist in the file sys‐
2479                     tem.  The -i option suppresses the error if the module is
2480                     already unloaded (or was never loaded).
2481
2482                     Each  module has a boot and a cleanup function.  The mod‐
2483                     ule will not be loaded if its boot function fails.  Simi‐
2484                     larly  a module can only be unloaded if its cleanup func‐
2485                     tion runs successfully.
2486
2487              zmodload -F [ -almLe -P param ] module [ [+-]feature ... ]
2488                     zmodload -F allows more selective control over  the  fea‐
2489                     tures  provided  by  modules.  With no options apart from
2490                     -F, the module named module is loaded, if it was not  al‐
2491                     ready  loaded, and the list of features is set to the re‐
2492                     quired state.  If no features are specified,  the  module
2493                     is loaded, if it was not already loaded, but the state of
2494                     features is unchanged.  Each feature may be preceded by a
2495                     +  to  turn the feature on, or - to turn it off; the + is
2496                     assumed if neither character is present.  Any feature not
2497                     explicitly mentioned is left in its current state; if the
2498                     module was not previously loaded this means any such fea‐
2499                     tures will remain disabled.  The return status is zero if
2500                     all features were set, 1 if the module  failed  to  load,
2501                     and  2  if some features could not be set (for example, a
2502                     parameter couldn't be added because there was a different
2503                     parameter of the same name) but the module was loaded.
2504
2505                     The  standard  features are builtins, conditions, parame‐
2506                     ters and math functions; these are indicated by the  pre‐
2507                     fix  `b:',  `c:'  (`C:' for an infix condition), `p:' and
2508                     `f:', respectively, followed by the name that the  corre‐
2509                     sponding  feature  would have in the shell.  For example,
2510                     `b:strftime'  indicates  a  builtin  named  strftime  and
2511                     p:EPOCHSECONDS  indicates a parameter named EPOCHSECONDS.
2512                     The module may provide other (`abstract') features of its
2513                     own as indicated by its documentation; these have no pre‐
2514                     fix.
2515
2516                     With -l or  -L,  features  provided  by  the  module  are
2517                     listed.   With -l alone, a list of features together with
2518                     their states is shown, one feature  per  line.   With  -L
2519                     alone,  a  zmodload  -F  command that would cause enabled
2520                     features of the module to be turned on  is  shown.   With
2521                     -lL,  a zmodload -F command that would cause all the fea‐
2522                     tures to be set to their current state is shown.  If  one
2523                     of  these  combinations is given with the option -P param
2524                     then the parameter param is set to an array of  features,
2525                     either features together with their state or (if -L alone
2526                     is given) enabled features.
2527
2528                     With the option -L the module name may be omitted; then a
2529                     list  of  all  enabled features for all modules providing
2530                     features is printed in the form of zmodload -F  commands.
2531                     If  -l  is also given, the state of both enabled and dis‐
2532                     abled features is output in that form.
2533
2534                     A set of features may be provided together with -l or  -L
2535                     and  a  module name; in that case only the state of those
2536                     features is considered.  Each feature may be preceded  by
2537                     +  or  -  but  the character has no effect.  If no set of
2538                     features is provided, all features are considered.
2539
2540                     With -e, the command  first  tests  that  the  module  is
2541                     loaded;  if it is not, status 1 is returned.  If the mod‐
2542                     ule is loaded, the list of features given as an  argument
2543                     is  examined.  Any feature given with no prefix is simply
2544                     tested to see if the  module  provides  it;  any  feature
2545                     given  with  a  prefix + or - is tested to see if is pro‐
2546                     vided and in the given state.  If the tests on  all  fea‐
2547                     tures  in  the  list  succeed, status 0 is returned, else
2548                     status 1.
2549
2550                     With -m, each entry in the  given  list  of  features  is
2551                     taken as a pattern to be matched against the list of fea‐
2552                     tures provided by the module.  An initial + or - must  be
2553                     given  explicitly.   This may not be combined with the -a
2554                     option as autoloads must be specified explicitly.
2555
2556                     With -a, the given list of features  is  marked  for  au‐
2557                     toload  from  the  specified module, which may not yet be
2558                     loaded.  An optional +  may  appear  before  the  feature
2559                     name.   If  the  feature is prefixed with -, any existing
2560                     autoload is removed.  The options -l and -L may  be  used
2561                     to list autoloads.  Autoloading is specific to individual
2562                     features; when the module is loaded  only  the  requested
2563                     feature  is  enabled.  Autoload requests are preserved if
2564                     the module is subsequently  unloaded  until  an  explicit
2565                     `zmodload  -Fa  module -feature' is issued.  It is not an
2566                     error to request an autoload for a feature  of  a  module
2567                     that is already loaded.
2568
2569                     When  the  module  is  loaded  each  autoload  is checked
2570                     against the features actually provided by the module;  if
2571                     the  feature  is  not  provided  the  autoload request is
2572                     deleted.  A warning message is output; if the  module  is
2573                     being loaded to provide a different feature, and that au‐
2574                     toload is successful, there is no effect on the status of
2575                     the  current command.  If the module is already loaded at
2576                     the time when zmodload -Fa is run, an  error  message  is
2577                     printed and status 1 returned.
2578
2579                     zmodload  -Fa  can be used with the -l, -L, -e and -P op‐
2580                     tions for listing and testing the existence of  autoload‐
2581                     able features.  In this case -l is ignored if -L is spec‐
2582                     ified.  zmodload -FaL with no module name lists autoloads
2583                     for all modules.
2584
2585                     Note  that  only standard features as described above can
2586                     be autoloaded; other features require the  module  to  be
2587                     loaded before enabling.
2588
2589              zmodload -d [ -L ] [ name ]
2590              zmodload -d name dep ...
2591              zmodload -ud name [ dep ... ]
2592                     The -d option can be used to specify module dependencies.
2593                     The modules named in the second and subsequent  arguments
2594                     will be loaded before the module named in the first argu‐
2595                     ment.
2596
2597                     With -d and one argument, all dependencies for that  mod‐
2598                     ule are listed.  With -d and no arguments, all module de‐
2599                     pendencies are listed.  This listing is by default  in  a
2600                     Makefile-like  format.  The -L option changes this format
2601                     to a list of zmodload -d commands.
2602
2603                     If -d and -u are both used, dependencies are removed.  If
2604                     only  one  argument  is  given, all dependencies for that
2605                     module are removed.
2606
2607              zmodload -ab [ -L ]
2608              zmodload -ab [ -i ] name [ builtin ... ]
2609              zmodload -ub [ -i ] builtin ...
2610                     The -ab option defines autoloaded builtins.   It  defines
2611                     the  specified  builtins.   When any of those builtins is
2612                     called, the module specified in  the  first  argument  is
2613                     loaded  and  all  its features are enabled (for selective
2614                     control of features use `zmodload  -F  -a'  as  described
2615                     above).   If  only  the name is given, one builtin is de‐
2616                     fined, with the same name as the module.   -i  suppresses
2617                     the  error  if  the  builtin  is  already  defined or au‐
2618                     toloaded, but not if another builtin of the same name  is
2619                     already defined.
2620
2621                     With  -ab  and  no arguments, all autoloaded builtins are
2622                     listed, with the module  name  (if  different)  shown  in
2623                     parentheses  after  the  builtin  name.   The  -L  option
2624                     changes this format to a list of zmodload -a commands.
2625
2626                     If -b is used together with the  -u  option,  it  removes
2627                     builtins  previously defined with -ab.  This is only pos‐
2628                     sible if the builtin is not yet  loaded.   -i  suppresses
2629                     the error if the builtin is already removed (or never ex‐
2630                     isted).
2631
2632                     Autoload requests are retained if the  module  is  subse‐
2633                     quently unloaded until an explicit `zmodload -ub builtin'
2634                     is issued.
2635
2636              zmodload -ac [ -IL ]
2637              zmodload -ac [ -iI ] name [ cond ... ]
2638              zmodload -uc [ -iI ] cond ...
2639                     The -ac option is used  to  define  autoloaded  condition
2640                     codes.  The cond strings give the names of the conditions
2641                     defined by the module. The optional -I option is used  to
2642                     define  infix condition names. Without this option prefix
2643                     condition names are defined.
2644
2645                     If given no condition names, all defined names are listed
2646                     (as  a  series  of  zmodload commands if the -L option is
2647                     given).
2648
2649                     The -uc option removes definitions for autoloaded  condi‐
2650                     tions.
2651
2652              zmodload -ap [ -L ]
2653              zmodload -ap [ -i ] name [ parameter ... ]
2654              zmodload -up [ -i ] parameter ...
2655                     The  -p  option  is like the -b and -c options, but makes
2656                     zmodload work on autoloaded parameters instead.
2657
2658              zmodload -af [ -L ]
2659              zmodload -af [ -i ] name [ function ... ]
2660              zmodload -uf [ -i ] function ...
2661                     The -f option is like the -b, -p,  and  -c  options,  but
2662                     makes zmodload work on autoloaded math functions instead.
2663
2664              zmodload -a [ -L ]
2665              zmodload -a [ -i ] name [ builtin ... ]
2666              zmodload -ua [ -i ] builtin ...
2667                     Equivalent to -ab and -ub.
2668
2669              zmodload -e [ -A ] [ string ... ]
2670                     The -e option without arguments lists all loaded modules;
2671                     if the -A option is also  given,  module  aliases  corre‐
2672                     sponding  to loaded modules are also shown.  If arguments
2673                     are provided, nothing is printed; the  return  status  is
2674                     set  to  zero if all strings given as arguments are names
2675                     of loaded modules and to one if at least on string is not
2676                     the  name  of  a loaded module.  This can be used to test
2677                     for the availability of things  implemented  by  modules.
2678                     In  this case, any aliases are automatically resolved and
2679                     the -A flag is not used.
2680
2681              zmodload -A [ -L ] [ modalias[=module] ... ]
2682                     For each argument, if both modalias and module are given,
2683                     define modalias to be an alias for the module module.  If
2684                     the module modalias is ever subsequently  requested,  ei‐
2685                     ther via a call to zmodload or implicitly, the shell will
2686                     attempt to load module instead.  If module is not  given,
2687                     show  the  definition  of  modalias.  If no arguments are
2688                     given, list all defined module aliases.  When listing, if
2689                     the  -L  flag  was  also  given, list the definition as a
2690                     zmodload command to recreate the alias.
2691
2692                     The existence of aliases for modules is completely  inde‐
2693                     pendent  of  whether the name resolved is actually loaded
2694                     as a module: while the alias exists, loading and  unload‐
2695                     ing  the  module under any alias has exactly the same ef‐
2696                     fect as using the resolved name, and does not affect  the
2697                     connection  between the alias and the resolved name which
2698                     can be removed either by zmodload -R or by redefining the
2699                     alias.   Chains of aliases (i.e. where the first resolved
2700                     name is itself an alias) are valid so long as  these  are
2701                     not  circular.   As  the  aliases take the same format as
2702                     module names, they may include path separators:  in  this
2703                     case,  there  is  no requirement for any part of the path
2704                     named to exist as the alias will be resolved first.   For
2705                     example, `any/old/alias' is always a valid alias.
2706
2707                     Dependencies  added to aliased modules are actually added
2708                     to the resolved module; these remain if the alias is  re‐
2709                     moved.   It is valid to create an alias whose name is one
2710                     of the standard shell modules and  which  resolves  to  a
2711                     different module.  However, if a module has dependencies,
2712                     it will not be possible to use  the  module  name  as  an
2713                     alias  as the module will already be marked as a loadable
2714                     module in its own right.
2715
2716                     Apart from the above, aliases can be used in the zmodload
2717                     command  anywhere  module  names  are required.  However,
2718                     aliases will not be shown in lists of loaded modules with
2719                     a bare `zmodload'.
2720
2721              zmodload -R modalias ...
2722                     For each modalias argument that was previously defined as
2723                     a module alias via zmodload -A, delete the alias.  If any
2724                     was  not defined, an error is caused and the remainder of
2725                     the line is ignored.
2726
2727              Note that zsh makes no distinction  between  modules  that  were
2728              linked  into  the shell and modules that are loaded dynamically.
2729              In both cases this builtin command has to be used to make avail‐
2730              able  the  builtins  and other things defined by modules (unless
2731              the module is autoloaded on these  definitions).  This  is  true
2732              even for systems that don't support dynamic loading of modules.
2733
2734       zparseopts
2735              See the section `The zsh/zutil Module' in zshmodules(1).
2736
2737       zprof  See the section `The zsh/zprof Module' in zshmodules(1).
2738
2739       zpty   See the section `The zsh/zpty Module' in zshmodules(1).
2740
2741       zregexparse
2742              See the section `The zsh/zutil Module' in zshmodules(1).
2743
2744       zsocket
2745              See the section `The zsh/net/socket Module' in zshmodules(1).
2746
2747       zstyle See the section `The zsh/zutil Module' in zshmodules(1).
2748
2749       ztcp   See the section `The zsh/net/tcp Module' in zshmodules(1).
2750
2751
2752
2753zsh 5.8.1                      February 12, 2022                ZSHBUILTINS(1)
Impressum