1ZSHBUILTINS(1) General Commands Manual ZSHBUILTINS(1)
2
6 zshbuiltins - zsh built-in commands
7
9 - simple command
10 See the section `Precommand Modifiers'.
11 . file [ arg ... ]
13 Read commands from file and execute them in the current shell
14 environment.
15 If file does not contain a slash, or if PATH_DIRS is set, the
17 shell looks in the components of $path to find the directory
18 containing file. Files in the current directory are not read
19 unless `.' appears somewhere in $path. If a file named
20 `file.zwc' is found, is newer than file, and is the compiled
21 form (created with the zcompile builtin) of file, then commands
22 are read from that file instead of file.
23 If any arguments arg are given, they become the positional
25 parameters; the old positional parameters are restored when the
26 file is done executing. If file was not found the return status
27 is 127; if file was found but contained a syntax error the
28 return status is 126; else the return status is the exit status
29 of the last command executed.
30 : [ arg ... ]
32 This command does nothing, although normal argument expansions
33 is performed which may have effects on shell parameters. A zero
34 exit status is returned.
35 alias [ {+|-}gmrsL ] [ name[=value] ... ]
37 For each name with a corresponding value, define an alias with
38 that value. A trailing space in value causes the next word to
39 be checked for alias expansion. If the -g flag is present,
40 define a global alias; global aliases are expanded even if they
41 do not occur in command position.
42 If the -s flags is present, define a suffix alias: if the com‐
44 mand word on a command line is in the form `text.name', where
45 text is any non-empty string, it is replaced by the text `value
46 text.name'. Note that name is treated as a literal string, not
47 a pattern. A trailing space in value is not special in this
48 case. For example,
49 alias -s ps=gv
51 will cause the command `*.ps' to be expanded to `gv *.ps'. As
53 alias expansion is carried out earlier than globbing, the `*.ps'
54 will then be expanded. Suffix aliases constitute a different
55 name space from other aliases (so in the above example it is
56 still possible to create an alias for the command ps) and the
57 two sets are never listed together.
58 For each name with no value, print the value of name, if any.
60 With no arguments, print all currently defined aliases other
61 than suffix aliases. If the -m flag is given the arguments are
62 taken as patterns (they should be quoted to preserve them from
63 being interpreted as glob patterns), and the aliases matching
64 these patterns are printed. When printing aliases and one of
65 the -g, -r or -s flags is present, restrict the printing to
66 global, regular or suffix aliases, respectively; a regular alias
67 is one which is neither a global nor a suffix alias. Using `+'
68 instead of `-', or ending the option list with a single `+',
69 prevents the values of the aliases from being printed.
70 If the -L flag is present, then print each alias in a manner
72 suitable for putting in a startup script. The exit status is
73 nonzero if a name (with no value) is given for which no alias
74 has been defined.
75 For more on aliases, include common problems, see the section
77 ALIASING in zshmisc(1).
78 autoload [ {+|-}UXkmtz ] [ -w ] [ name ... ]
80 Equivalent to functions -u, with the exception of -X/+X and -w.
81 The flag -X may be used only inside a shell function, and may
83 not be followed by a name. It causes the calling function to be
84 marked for autoloading and then immediately loaded and executed,
85 with the current array of positional parameters as arguments.
86 This replaces the previous definition of the function. If no
87 function definition is found, an error is printed and the func‐
88 tion remains undefined and marked for autoloading.
89 The flag +X attempts to load each name as an autoloaded func‐
91 tion, but does not execute it. The exit status is zero (suc‐
92 cess) if the function was not previously defined and a defini‐
93 tion for it was found. This does not replace any existing defi‐
94 nition of the function. The exit status is nonzero (failure) if
95 the function was already defined or when no definition was
96 found. In the latter case the function remains undefined and
97 marked for autoloading. If ksh-style autoloading is enabled,
98 the function created will contain the contents of the file plus
99 a call to the function itself appended to it, thus giving normal
100 ksh autoloading behaviour on the first call to the function. If
101 the -m flag is also given each name is treated as a pattern and
102 all functions already marked for autoload that match the pattern
103 are loaded.
104 With the -w flag, the names are taken as names of files compiled
106 with the zcompile builtin, and all functions defined in them are
107 marked for autoloading.
108 The flags -z and -k mark the function to be autoloaded using the
110 zsh or ksh style, as if the option KSH_AUTOLOAD were unset or
111 were set, respectively. The flags override the setting of the
112 option at the time the function is loaded.
113 Note that the autoload command makes no attempt to ensure the
115 shell options set during the loading or execution of the file
116 have any particular value. For this, the emulate command can be
117 used:
118 emulate zsh -c 'autoload -Uz func'
120 arranges that when func is loaded the shell is in native zsh
122 emulation, and this emulation is also applied when func is run.
123 bg [ job ... ]
125 job ... &
126 Put each specified job in the background, or the current job if
127 none is specified.
128 bindkey
130 See the section `Zle Builtins' in zshzle(1).
131 break [ n ]
133 Exit from an enclosing for, while, until, select or repeat loop.
134 If n is specified, then break n levels instead of just one.
135 builtin name [ args ... ]
137 Executes the builtin name, with the given args.
138 bye Same as exit.
140 cap See the section `The zsh/cap Module' in zshmodules(1).
142 cd [ -qsLP ] [ arg ]
144 cd [ -qsLP ] old new
145 cd [ -qsLP ] {+|-}n
146 Change the current directory. In the first form, change the
147 current directory to arg, or to the value of $HOME if arg is not
148 specified. If arg is `-', change to the previous directory.
149 Otherwise, if arg begins with a slash, attempt to change to the
151 directory given by arg.
152 If arg does not begin with a slash, the behaviour depends on
154 whether the current directory `.' occurs in the list of directo‐
155 ries contained in the shell parameter cdpath. If it does not,
156 first attempt to change to the directory arg under the current
157 directory, and if that fails but cdpath is set and contains at
158 least one element attempt to change to the directory arg under
159 each component of cdpath in turn until successful. If `.'
160 occurs in cdpath, then cdpath is searched strictly in order so
161 that `.' is only tried at the appropriate point.
162 The order of testing cdpath is modified if the option POSIX_CD
164 is set, as described in the documentation for the option.
165 If no directory is found, the option CDABLE_VARS is set, and a
167 parameter named arg exists whose value begins with a slash,
168 treat its value as the directory. In that case, the parameter
169 is added to the named directory hash table.
170 The second form of cd substitutes the string new for the string
172 old in the name of the current directory, and tries to change to
173 this new directory.
174 The third form of cd extracts an entry from the directory stack,
176 and changes to that directory. An argument of the form `+n'
177 identifies a stack entry by counting from the left of the list
178 shown by the dirs command, starting with zero. An argument of
179 the form `-n' counts from the right. If the PUSHD_MINUS option
180 is set, the meanings of `+' and `-' in this context are swapped.
181 If the -q (quiet) option is specified, the hook function chpwd
183 and the functions in the array chpwd_functions are not called.
184 This is useful for calls to cd that do not change the environ‐
185 ment seen by an interactive user.
186 If the -s option is specified, cd refuses to change the current
188 directory if the given pathname contains symlinks. If the -P
189 option is given or the CHASE_LINKS option is set, symbolic links
190 are resolved to their true values. If the -L option is given
191 symbolic links are retained in the directory (and not resolved)
192 regardless of the state of the CHASE_LINKS option.
193 chdir Same as cd.
195 clone See the section `The zsh/clone Module' in zshmodules(1).
197 command [ -pvV ] simple command
199 The simple command argument is taken as an external command
200 instead of a function or builtin and is executed. If the
201 POSIX_BUILTINS option is set, builtins will also be executed but
202 certain special properties of them are suppressed. The -p flag
203 causes a default path to be searched instead of that in $path.
204 With the -v flag, command is similar to whence and with -V, it
205 is equivalent to whence -v.
206 See also the section `Precommand Modifiers'.
208 comparguments
210 See the section `The zsh/computil Module' in zshmodules(1).
211 compcall
213 See the section `The zsh/compctl Module' in zshmodules(1).
214 compctl
216 See the section `The zsh/compctl Module' in zshmodules(1).
217 compdescribe
219 See the section `The zsh/computil Module' in zshmodules(1).
220 compfiles
222 See the section `The zsh/computil Module' in zshmodules(1).
223 compgroups
225 See the section `The zsh/computil Module' in zshmodules(1).
226 compquote
228 See the section `The zsh/computil Module' in zshmodules(1).
229 comptags
231 See the section `The zsh/computil Module' in zshmodules(1).
232 comptry
234 See the section `The zsh/computil Module' in zshmodules(1).
235 compvalues
237 See the section `The zsh/computil Module' in zshmodules(1).
238 continue [ n ]
240 Resume the next iteration of the enclosing for, while, until,
241 select or repeat loop. If n is specified, break out of n-1
242 loops and resume at the nth enclosing loop.
243 declare
245 Same as typeset.
246 dirs [ -c ] [ arg ... ]
248 dirs [ -lpv ]
249 With no arguments, print the contents of the directory stack.
250 Directories are added to this stack with the pushd command, and
251 removed with the cd or popd commands. If arguments are speci‐
252 fied, load them onto the directory stack, replacing anything
253 that was there, and push the current directory onto the stack.
254 -c clear the directory stack.
256 -l print directory names in full instead of using of using ~
258 expressions.
259 -p print directory entries one per line.
261 -v number the directories in the stack when printing.
263 disable [ -afmrs ] name ...
265 Temporarily disable the named hash table elements. The default
266 is to disable builtin commands. This allows you to use an
267 external command with the same name as a builtin command. The
268 -a option causes disable to act on regular or global aliases.
269 The -s option causes disable to act on suffix aliases. The -f
270 option causes disable to act on shell functions. The -r options
271 causes disable to act on reserved words. Without arguments all
272 disabled hash table elements from the corresponding hash table
273 are printed. With the -m flag the arguments are taken as pat‐
274 terns (which should be quoted to prevent them from undergoing
275 filename expansion), and all hash table elements from the corre‐
276 sponding hash table matching these patterns are disabled. Dis‐
277 abled objects can be enabled with the enable command.
278 disown [ job ... ]
280 job ... &|
281 job ... &!
282 Remove the specified jobs from the job table; the shell will no
283 longer report their status, and will not complain if you try to
284 exit an interactive shell with them running or stopped. If no
285 job is specified, disown the current job.
286 If the jobs are currently stopped and the AUTO_CONTINUE option
288 is not set, a warning is printed containing information about
289 how to make them running after they have been disowned. If one
290 of the latter two forms is used, the jobs will automatically be
291 made running, independent of the setting of the AUTO_CONTINUE
292 option.
293 echo [ -neE ] [ arg ... ]
295 Write each arg on the standard output, with a space separating
296 each one. If the -n flag is not present, print a newline at the
297 end. echo recognizes the following escape sequences:
298 \a bell character
300 \b backspace
301 \c suppress final newline
302 \e escape
303 \f form feed
304 \n linefeed (newline)
305 \r carriage return
306 \t horizontal tab
307 \v vertical tab
308 \\ backslash
309 \0NNN character code in octal
310 \xNN character code in hexadecimal
311 \uNNNN unicode character code in hexadecimal
312 \UNNNNNNNN
313 unicode character code in hexadecimal
314 The -E flag, or the BSD_ECHO option, can be used to disable
316 these escape sequences. In the latter case, -e flag can be used
317 to enable them.
318 echotc See the section `The zsh/termcap Module' in zshmodules(1).
320 echoti See the section `The zsh/terminfo Module' in zshmodules(1).
322 emulate [ -LR ] [ {zsh|sh|ksh|csh} [ flags ... ] ]
324 Without any argument print current emulation mode.
325 With single argument set up zsh options to emulate the specified
327 shell as much as possible. csh will never be fully emulated.
328 If the argument is not one of the shells listed above, zsh will
329 be used as a default; more precisely, the tests performed on the
330 argument are the same as those used to determine the emulation
331 at startup based on the shell name, see the section COMPATIBIL‐
332 ITY in zsh(1) .
333 If the emulate command occurs inside a function that has been
335 marked for execution tracing with functions -t then the xtrace
336 option will be turned on regardless of emulation mode or other
337 options. Note that code executed inside the function by the .,
338 source, or eval commands is not considered to be running
339 directly from the function, hence does not provoke this behav‐
340 iour.
341 If the -R switch is given, all settable options are reset to
343 their default value corresponding to the specified emulation
344 mode, except for certain options describing the interactive
345 environment; otherwise, only those options likely to cause
346 portability problems in scripts and functions are altered. If
347 the -L switch is given, the options LOCAL_OPTIONS and
348 LOCAL_TRAPS will be set as well, causing the effects of the emu‐
349 late command and any setopt and trap commands to be local to the
350 immediately surrounding shell function, if any; normally these
351 options are turned off in all emulation modes except ksh. The -L
352 switch is mutually exclusive with the use of -c in flags.
353 The flags may be any of the invocation-time flags described in
355 the section INVOCATION in zsh(1), except that `-o EMACS' and `-o
356 VI' may not be used. Flags such as `+r'/`+o RESTRICTED' may be
357 prohibited in some circumstances.
358 If -c arg appears in flags, arg is evaluated while the requested
360 emulation is temporarily in effect. In this case the emulation
361 mode and all options are restored to their previous values
362 before emulate returns. The -R switch may precede the name of
363 the shell to emulate; note this has a meaning distinct from
364 including -R in flags.
365 Use of -c enables `sticky' emulation mode for functions defined
367 within the evaluated expression: the emulation mode is associ‐
368 ated thereafter with the function so that whenever the function
369 is executed the emulation (respecting the -R switch, if present)
370 and all options are set before entry to the function, and
371 restored after exit. If the function is called when the sticky
372 emulation is already in effect, either within an `emulate shell
373 -c' expression or within another function with the same sticky
374 emulation, entry and exit from the function do not cause options
375 to be altered (except due to standard processing such as the
376 LOCAL_OPTIONS option). This also applies to functions marked
377 for autoload within the sticky emulation; the appropriate set of
378 options will be applied at the point the function is loaded as
379 well as when it is run.
380 For example:
382 emulate sh -c 'fni() { setopt cshnullglob; }
384 fno() { fni; }'
385 fno
386 The two functions fni and fno are defined with sticky sh emula‐
388 tion. fno is then executed, causing options associated with
389 emulations to be set to their values in sh. fni then calls fno;
390 because fno is also marked for sticky sh emulation, no option
391 changes take place on entry to or exit from it. Hence the
392 option cshnullglob, turned off by sh emulation, will be turned
393 on within fni and remain on on return to fno. On exit from fno,
394 the emulation mode and all options will be restored to the state
395 they were in before entry to the temporary emulation.
396 The documentation above is typically sufficient for the intended
398 purpose of executing code designed for other shells in a suit‐
399 able environment. More detailed rules follow.
400 1. The sticky emulation environment provided by `emulate
401 shell -c' is identical to that provided by entry to a
402 function marked for sticky emulation as a consequence of
403 being defined in such an environment. Hence, for exam‐
404 ple, the sticky emulation is inherited by subfunctions
405 defined within functions with sticky emulation.
406 2. No change of options takes place on entry to or exit from
407 functions that are not marked for sticky emulation, other
408 than those that would normally take place, even if those
409 functions are called within sticky emulation.
410 3. No special handling is provided for functions marked for
411 autoload nor for functions present in wordcode created by
412 the zcompile command.
413 4. The presence or absence of the -R switch to emulate cor‐
414 responds to different sticky emulation modes, so for
415 example `emulate sh -c', `emulate -R sh -c' and `emulate
416 csh -c' are treated as three distinct sticky emulations.
417 5. Difference in shell options supplied in addition to the
418 basic emulation also mean the sticky emulations are dif‐
419 ferent, so for example `emulate zsh -c' and `emulate zsh
420 -o cbases -c' are treated as distinct sticky emulations.
421 enable [ -afmrs ] name ...
423 Enable the named hash table elements, presumably disabled ear‐
424 lier with disable. The default is to enable builtin commands.
425 The -a option causes enable to act on regular or global aliases.
426 The -s option causes enable to act on suffix aliases. The -f
427 option causes enable to act on shell functions. The -r option
428 causes enable to act on reserved words. Without arguments all
429 enabled hash table elements from the corresponding hash table
430 are printed. With the -m flag the arguments are taken as pat‐
431 terns (should be quoted) and all hash table elements from the
432 corresponding hash table matching these patterns are enabled.
433 Enabled objects can be disabled with the disable builtin com‐
434 mand.
435 eval [ arg ... ]
437 Read the arguments as input to the shell and execute the result‐
438 ing command(s) in the current shell process. The return status
439 is the same as if the commands had been executed directly by the
440 shell; if there are no args or they contain no commands (i.e.
441 are an empty string or whitespace) the return status is zero.
442 exec [ -cl ] [ -a argv0 ] simple command
444 Replace the current shell with an external command rather than
445 forking. With -c clear the environment; with -l prepend - to
446 the argv[0] string of the command executed (to simulate a login
447 shell); with -a argv0 set the argv[0] string of the command exe‐
448 cuted. See the section `Precommand Modifiers'.
449 exit [ n ]
451 Exit the shell with the exit status specified by n; if none is
452 specified, use the exit status from the last command executed.
453 An EOF condition will also cause the shell to exit, unless the
454 IGNORE_EOF option is set.
455 export [ name[=value] ... ]
457 The specified names are marked for automatic export to the envi‐
458 ronment of subsequently executed commands. Equivalent to type‐
459 set -gx. If a parameter specified does not already exist, it is
460 created in the global scope.
461 false [ arg ... ]
463 Do nothing and return an exit status of 1.
464 fc [ -e ename ] [ -m match ] [ old=new ... ] [ first [ last ] ]
466 fc -l [ -nrdfEiD ] [ -t timefmt ] [ -m match ]
467 [ old=new ... ] [ first [ last ] ]
468 fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]
469 fc -P
470 fc -ARWI [ filename ]
471 Select a range of commands from first to last from the history
472 list. The arguments first and last may be specified as a number
473 or as a string. A negative number is used as an offset to the
474 current history event number. A string specifies the most
475 recent event beginning with the given string. All substitutions
476 old=new, if any, are then performed on the commands.
477 If the -l flag is given, the resulting commands are listed on
479 standard output. If the -m flag is also given the first argu‐
480 ment is taken as a pattern (should be quoted) and only the his‐
481 tory events matching this pattern will be shown. Otherwise the
482 editor program ename is invoked on a file containing these his‐
483 tory events. If ename is not given, the value of the parameter
484 FCEDIT is used; if that is not set the value of the parameter
485 EDITOR is used; if that is not set a builtin default, usually
486 `vi' is used. If ename is `-', no editor is invoked. When
487 editing is complete, the edited command is executed.
488 If first is not specified, it will be set to -1 (the most recent
490 event), or to -16 if the -l flag is given. If last is not spec‐
491 ified, it will be set to first, or to -1 if the -l flag is
492 given.
493 The flag -r reverses the order of the commands and the flag -n
495 suppresses command numbers when listing.
496 Also when listing,
498 -d prints timestamps for each command
499 -f prints full time-date stamps in the US `MM/DD/YY hh:mm'
500 format
501 -E prints full time-date stamps in the European `dd.mm.yyyy
502 hh:mm' format
503 -i prints full time-date stamps in ISO8601 `yyyy-mm-dd
504 hh:mm' format
505 -t fmt prints time and date stamps in the given format; fmt is
506 formatted with the strftime function with the zsh exten‐
507 sions described for the %D{string} prompt format in the
508 section EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The
509 resulting formatted string must be no more than 256 char‐
510 acters or will not be printed.
511 -D prints elapsed times; may be combined with one of the
512 options above.
513 `fc -p' pushes the current history list onto a stack and
515 switches to a new history list. If the -a option is also speci‐
516 fied, this history list will be automatically popped when the
517 current function scope is exited, which is a much better solu‐
518 tion than creating a trap function to call `fc -P' manually. If
519 no arguments are specified, the history list is left empty,
520 $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to their
521 default values. If one argument is given, $HISTFILE is set to
522 that filename, $HISTSIZE & $SAVEHIST are left unchanged, and the
523 history file is read in (if it exists) to initialize the new
524 list. If a second argument is specified, $HISTSIZE & $SAVEHIST
525 are instead set to the single specified numeric value. Finally,
526 if a third argument is specified, $SAVEHIST is set to a separate
527 value from $HISTSIZE. You are free to change these environment
528 values for the new history list however you desire in order to
529 manipulate the new history list.
530 `fc -P' pops the history list back to an older list saved by `fc
532 -p'. The current list is saved to its $HISTFILE before it is
533 destroyed (assuming that $HISTFILE and $SAVEHIST are set appro‐
534 priately, of course). The values of $HISTFILE, $HISTSIZE, and
535 $SAVEHIST are restored to the values they had when `fc -p' was
536 called. Note that this restoration can conflict with making
537 these variables "local", so your best bet is to avoid local dec‐
538 larations for these variables in functions that use `fc -p'.
539 The one other guaranteed-safe combination is declaring these
540 variables to be local at the top of your function and using the
541 automatic option (-a) with `fc -p'. Finally, note that it is
542 legal to manually pop a push marked for automatic popping if you
543 need to do so before the function exits.
544 `fc -R' reads the history from the given file, `fc -W' writes
546 the history out to the given file, and `fc -A' appends the his‐
547 tory out to the given file. If no filename is specified, the
548 $HISTFILE is assumed. If the -I option is added to -R, only
549 those events that are not already contained within the internal
550 history list are added. If the -I option is added to -A or -W,
551 only those events that are new since last incremental
552 append/write to the history file are appended/written. In any
553 case, the created file will have no more than $SAVEHIST entries.
554 fg [ job ... ]
556 job ...
557 Bring each specified job in turn to the foreground. If no job
558 is specified, resume the current job.
559 float [ {+|-}EFHghlprtux ] [ -LRZ [ n ]] [ name[=value] ... ]
561 Equivalent to typeset -E, except that options irrelevant to
562 floating point numbers are not permitted.
563 functions [ {+|-}UXkmtTuz ] [ name ... ]
565 functions -M mathfn [ min [ max [ shellfn ] ] ]
566 functions -M [ -m pattern ... ]
567 functions +M [ -m ] mathfn
568 Equivalent to typeset -f, with the exception of the -M option.
569 Use of the -M option may not be combined with any of the options
570 handled by typeset -f.
571 functions -M mathfn defines mathfn as the name of a mathematical
573 function recognised in all forms of arithmetical expressions;
574 see the section `Arithmetic Evaluation' in zshmisc(1). By
575 default mathfn may take any number of comma-separated arguments.
576 If min is given, it must have exactly min args; if min and max
577 are both given, it must have at least min and at most max args.
578 max may be -1 to indicate that there is no upper limit.
579 By default the function is implemented by a shell function of
581 the same name; if shellfn is specified it gives the name of the
582 corresponding shell function while mathfn remains the name used
583 in arithmetical expressions. The name of the function in $0 is
584 mathfn (not shellfn as would usually be the case), provided the
585 option FUNCTION_ARGZERO is in effect. The positional parameters
586 in the shell function correspond to the arguments of the mathe‐
587 matical function call. The result of the last arithmetical
588 expression evaluated inside the shell function (even if it is a
589 form that normally only returns a status) gives the result of
590 the mathematical function.
591 functions -M with no arguments lists all such user-defined func‐
593 tions in the same form as a definition. With the additional
594 option -m and a list of arguments, all functions whose mathfn
595 matches one of the pattern arguments are listed.
596 function +M removes the list of mathematical functions; with the
598 additional option -m the arguments are treated as patterns and
599 all functions whose mathfn matches the pattern are removed.
600 Note that the shell function implementing the behaviour is not
601 removed (regardless of whether its name coincides with mathfn).
602 For example, the following prints the cube of 3:
604 zmath_cube() { (( $1 * $1 * $1 )) }
606 functions -M cube 1 1 zmath_cube
607 print $(( cube(3) ))
608 getcap See the section `The zsh/cap Module' in zshmodules(1).
610 getln [ -AclneE ] name ...
612 Read the top value from the buffer stack and put it in the shell
613 parameter name. Equivalent to read -zr.
614 getopts optstring name [ arg ... ]
616 Checks the args for legal options. If the args are omitted, use
617 the positional parameters. A valid option argument begins with
618 a `+' or a `-'. An argument not beginning with a `+' or a `-',
619 or the argument `--', ends the options. Note that a single `-'
620 is not considered a valid option argument. optstring contains
621 the letters that getopts recognizes. If a letter is followed by
622 a `:', that option requires an argument. The options can be
623 separated from the argument by blanks.
624 Each time it is invoked, getopts places the option letter it
626 finds in the shell parameter name, prepended with a `+' when arg
627 begins with a `+'. The index of the next arg is stored in
628 OPTIND. The option argument, if any, is stored in OPTARG.
629 The first option to be examined may be changed by explicitly
631 assigning to OPTIND. OPTIND has an initial value of 1, and is
632 normally reset to 1 upon exit from a shell function. OPTARG is
633 not reset and retains its value from the most recent call to
634 getopts. If either of OPTIND or OPTARG is explicitly unset, it
635 remains unset, and the index or option argument is not stored.
636 The option itself is still stored in name in this case.
637 A leading `:' in optstring causes getopts to store the letter of
639 any invalid option in OPTARG, and to set name to `?' for an
640 unknown option and to `:' when a required argument is missing.
641 Otherwise, getopts sets name to `?' and prints an error message
642 when an option is invalid. The exit status is nonzero when
643 there are no more options.
644 hash [ -Ldfmrv ] [ name[=value] ] ...
646 hash can be used to directly modify the contents of the command
647 hash table, and the named directory hash table. Normally one
648 would modify these tables by modifying one's PATH (for the com‐
649 mand hash table) or by creating appropriate shell parameters
650 (for the named directory hash table). The choice of hash table
651 to work on is determined by the -d option; without the option
652 the command hash table is used, and with the option the named
653 directory hash table is used.
654 Given no arguments, and neither the -r or -f options, the
656 selected hash table will be listed in full.
657 The -r option causes the selected hash table to be emptied. It
659 will be subsequently rebuilt in the normal fashion. The -f
660 option causes the selected hash table to be fully rebuilt imme‐
661 diately. For the command hash table this hashes all the abso‐
662 lute directories in the PATH, and for the named directory hash
663 table this adds all users' home directories. These two options
664 cannot be used with any arguments.
665 The -m option causes the arguments to be taken as patterns
667 (which should be quoted) and the elements of the hash table
668 matching those patterns are printed. This is the only way to
669 display a limited selection of hash table elements.
670 For each name with a corresponding value, put `name' in the
672 selected hash table, associating it with the pathname `value'.
673 In the command hash table, this means that whenever `name' is
674 used as a command argument, the shell will try to execute the
675 file given by `value'. In the named directory hash table, this
676 means that `value' may be referred to as `~name'.
677 For each name with no corresponding value, attempt to add name
679 to the hash table, checking what the appropriate value is in the
680 normal manner for that hash table. If an appropriate value
681 can't be found, then the hash table will be unchanged.
682 The -v option causes hash table entries to be listed as they are
684 added by explicit specification. If has no effect if used with
685 -f.
686 If the -L flag is present, then each hash table entry is printed
688 in the form of a call to hash.
689 history
691 Same as fc -l.
692 integer [ {+|-}Hghilprtux ] [ -LRZ [ n ]] [ name[=value] ... ]
694 Equivalent to typeset -i, except that options irrelevant to
695 integers are not permitted.
696 jobs [ -dlprs ] [ job ... ]
698 jobs -Z string
699 Lists information about each given job, or all jobs if job is
700 omitted. The -l flag lists process IDs, and the -p flag lists
701 process groups. If the -r flag is specified only running jobs
702 will be listed and if the -s flag is given only stopped jobs are
703 shown. If the -d flag is given, the directory from which the
704 job was started (which may not be the current directory of the
705 job) will also be shown.
706 The -Z option replaces the shell's argument and environment
708 space with the given string, truncated if necessary to fit.
709 This will normally be visible in ps (ps(1)) listings. This fea‐
710 ture is typically used by daemons, to indicate their state.
711 kill [ -s signal_name | -n signal_number | -sig ] job ...
713 kill -l [ sig ... ]
714 Sends either SIGTERM or the specified signal to the given jobs
715 or processes. Signals are given by number or by names, with or
716 without the `SIG' prefix. If the signal being sent is not
717 `KILL' or `CONT', then the job will be sent a `CONT' signal if
718 it is stopped. The argument job can be the process ID of a job
719 not in the job list. In the second form, kill -l, if sig is not
720 specified the signal names are listed. Otherwise, for each sig
721 that is a name, the corresponding signal number is listed. For
722 each sig that is a signal number or a number representing the
723 exit status of a process which was terminated or stopped by a
724 signal the name of the signal is printed.
725 On some systems, alternative signal names are allowed for a few
727 signals. Typical examples are SIGCHLD and SIGCLD or SIGPOLL and
728 SIGIO, assuming they correspond to the same signal number. kill
729 -l will only list the preferred form, however kill -l alt will
730 show if the alternative form corresponds to a signal number.
731 For example, under Linux kill -l IO and kill -l POLL both output
732 29, hence kill -IO and kill -POLL have the same effect.
733 Many systems will allow process IDs to be negative to kill a
735 process group or zero to kill the current process group.
736 let arg ...
738 Evaluate each arg as an arithmetic expression. See the section
739 `Arithmetic Evaluation' in zshmisc(1) for a description of
740 arithmetic expressions. The exit status is 0 if the value of
741 the last expression is nonzero, 1 if it is zero, and 2 if an
742 error occurred.
743 limit [ -hs ] [ resource [ limit ] ] ...
745 Set or display resource limits. Unless the -s flag is given,
746 the limit applies only the children of the shell. If -s is
747 given without other arguments, the resource limits of the cur‐
748 rent shell is set to the previously set resource limits of the
749 children.
750 If limit is not specified, print the current limit placed on
752 resource, otherwise set the limit to the specified value. If
753 the -h flag is given, use hard limits instead of soft limits.
754 If no resource is given, print all limits.
755 When looping over multiple resources, the shell will abort imme‐
757 diately if it detects a badly formed argument. However, if it
758 fails to set a limit for some other reason it will continue try‐
759 ing to set the remaining limits.
760 resource can be one of:
762 addressspace
764 Maximum amount of address space used.
765 aiomemorylocked
766 Maximum amount of memory locked in RAM for AIO opera‐
767 tions.
768 aiooperations
769 Maximum number of AIO operations.
770 cachedthreads
771 Maximum number of cached threads.
772 coredumpsize
773 Maximum size of a core dump.
774 cputime
775 Maximum CPU seconds per process.
776 datasize
777 Maximum data size (including stack) for each process.
778 descriptors
779 Maximum value for a file descriptor.
780 filesize
781 Largest single file allowed.
782 maxproc
783 Maximum number of processes.
784 maxpthreads
785 Maximum number of threads per process.
786 memorylocked
787 Maximum amount of memory locked in RAM.
788 memoryuse
789 Maximum resident set size.
790 msgqueue
791 Maximum number of bytes in POSIX message queues.
792 resident
793 Maximum resident set size.
794 sigpending
795 Maximum number of pending signals.
796 sockbufsize
797 Maximum size of all socket buffers.
798 stacksize
799 Maximum stack size for each process.
800 vmemorysize
801 Maximum amount of virtual memory.
802 Which of these resource limits are available depends on the sys‐
804 tem. resource can be abbreviated to any unambiguous prefix. It
805 can also be an integer, which corresponds to the integer defined
806 for the resource by the operating system.
807 If argument corresponds to a number which is out of the range of
809 the resources configured into the shell, the shell will try to
810 read or write the limit anyway, and will report an error if this
811 fails. As the shell does not store such resources internally,
812 an attempt to set the limit will fail unless the -s option is
813 present.
814 limit is a number, with an optional scaling factor, as follows:
816 nh hours
818 nk kilobytes (default)
819 nm megabytes or minutes
820 [mm:]ss
821 minutes and seconds
822 The limit command is not made available by default when the
824 shell starts in a mode emulating another shell. It can be made
825 available with the command `zmodload -F zsh/rlimits b:limit'.
826 local [ {+|-}AEFHUahlprtux ] [ -LRZi [ n ]] [ name[=value] ] ...
828 Same as typeset, except that the options -g, and -f are not per‐
829 mitted. In this case the -x option does not force the use of
830 -g, i.e. exported variables will be local to functions.
831 log List all users currently logged in who are affected by the cur‐
833 rent setting of the watch parameter.
834 logout [ n ]
836 Same as exit, except that it only works in a login shell.
837 noglob simple command
839 See the section `Precommand Modifiers'.
840 popd [ [-q] {+|-}n ]
842 Remove an entry from the directory stack, and perform a cd to
843 the new top directory. With no argument, the current top entry
844 is removed. An argument of the form `+n' identifies a stack
845 entry by counting from the left of the list shown by the dirs
846 command, starting with zero. An argument of the form -n counts
847 from the right. If the PUSHD_MINUS option is set, the meanings
848 of `+' and `-' in this context are swapped.
849 If the -q (quiet) option is specified, the hook function chpwd
851 and the functions in the array $chpwd_functions are not called,
852 and the new directory stack is not printed. This is useful for
853 calls to popd that do not change the environment seen by an
854 interactive user.
855 print [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C cols ]
857 [ -R [ -en ]] [ arg ... ]
858 With the `-f' option the arguments are printed as described by
859 printf. With no flags or with the flag `-', the arguments are
860 printed on the standard output as described by echo, with the
861 following differences: the escape sequence `\M-x' metafies the
862 character x (sets the highest bit), `\C-x' produces a control
863 character (`\C-@' and `\C-?' give the characters NUL and
864 delete), and `\E' is a synonym for `\e'. Finally, if not in an
865 escape sequence, `\' escapes the following character and is not
866 printed.
867 -a Print arguments with the column incrementing first. Only
869 useful with the -c and -C options.
870 -b Recognize all the escape sequences defined for the bind‐
872 key command, see zshzle(1).
873 -c Print the arguments in columns. Unless -a is also given,
875 arguments are printed with the row incrementing first.
876 -C cols
878 Print the arguments in cols columns. Unless -a is also
879 given, arguments are printed with the row incrementing
880 first.
881 -D Treat the arguments as directory names, replacing pre‐
883 fixes with ~ expressions, as appropriate.
884 -i If given together with -o or -O, sorting is performed
886 case-independently.
887 -l Print the arguments separated by newlines instead of spa‐
889 ces.
890 -m Take the first argument as a pattern (should be quoted),
892 and remove it from the argument list together with subse‐
893 quent arguments that do not match this pattern.
894 -n Do not add a newline to the output.
896 -N Print the arguments separated and terminated by nulls.
898 -o Print the arguments sorted in ascending order.
900 -O Print the arguments sorted in descending order.
902 -p Print the arguments to the input of the coprocess.
904 -P Perform prompt expansion (see EXPANSION OF PROMPT
906 SEQUENCES in zshmisc(1)).
907 -r Ignore the escape conventions of echo.
909 -R Emulate the BSD echo command, which does not process
911 escape sequences unless the -e flag is given. The -n
912 flag suppresses the trailing newline. Only the -e and -n
913 flags are recognized after -R; all other arguments and
914 options are printed.
915 -s Place the results in the history list instead of on the
917 standard output. Each argument to the print command is
918 treated as a single word in the history, regardless of
919 its content.
920 -S Place the results in the history list instead of on the
922 standard output. In this case only a single argument is
923 allowed; it will be split into words as if it were a full
924 shell command line. The effect is similar to reading the
925 line from a history file with the HIST_LEX_WORDS option
926 active.
927 -u n Print the arguments to file descriptor n.
929 -z Push the arguments onto the editing buffer stack, sepa‐
931 rated by spaces.
932 If any of `-m', `-o' or `-O' are used in combination with `-f'
934 and there are no arguments (after the removal process in the
935 case of `-m') then nothing is printed.
936 printf format [ arg ... ]
938 Print the arguments according to the format specification. For‐
939 matting rules are the same as used in C. The same escape
940 sequences as for echo are recognised in the format. All C con‐
941 version specifications ending in one of csdiouxXeEfgGn are han‐
942 dled. In addition to this, `%b' can be used instead of `%s' to
943 cause escape sequences in the argument to be recognised and `%q'
944 can be used to quote the argument in such a way that allows it
945 to be reused as shell input. With the numeric format specifiers,
946 if the corresponding argument starts with a quote character, the
947 numeric value of the following character is used as the number
948 to print otherwise the argument is evaluated as an arithmetic
949 expression. See the section `Arithmetic Evaluation' in zsh‐
950 misc(1) for a description of arithmetic expressions. With `%n',
951 the corresponding argument is taken as an identifier which is
952 created as an integer parameter.
953 Normally, conversion specifications are applied to each argument
955 in order but they can explicitly specify the nth argument is to
956 be used by replacing `%' by `%n$' and `*' by `*n$'. It is rec‐
957 ommended that you do not mix references of this explicit style
958 with the normal style and the handling of such mixed styles may
959 be subject to future change.
960 If arguments remain unused after formatting, the format string
962 is reused until all arguments have been consumed. With the print
963 builtin, this can be suppressed by using the -r option. If more
964 arguments are required by the format than have been specified,
965 the behaviour is as if zero or an empty string had been speci‐
966 fied as the argument.
967 pushd [ -qsLP ] [ arg ]
969 pushd [ -qsLP ] old new
970 pushd [ -qsLP ] {+|-}n
971 Change the current directory, and push the old current directory
972 onto the directory stack. In the first form, change the current
973 directory to arg. If arg is not specified, change to the second
974 directory on the stack (that is, exchange the top two entries),
975 or change to $HOME if the PUSHD_TO_HOME option is set or if
976 there is only one entry on the stack. Otherwise, arg is inter‐
977 preted as it would be by cd. The meaning of old and new in the
978 second form is also the same as for cd.
979 The third form of pushd changes directory by rotating the direc‐
981 tory list. An argument of the form `+n' identifies a stack
982 entry by counting from the left of the list shown by the dirs
983 command, starting with zero. An argument of the form `-n'
984 counts from the right. If the PUSHD_MINUS option is set, the
985 meanings of `+' and `-' in this context are swapped.
986 If the -q (quiet) option is specified, the hook function chpwd
988 and the functions in the array $chpwd_functions are not called,
989 and the new directory stack is not printed. This is useful for
990 calls to pushd that do not change the environment seen by an
991 interactive user.
992 If the option -q is not specified and the shell option
994 PUSHD_SILENT is not set, the directory stack will be printed
995 after a pushd is performed.
996 The options -s, -L and -P have the same meanings as for the cd
998 builtin.
999 pushln [ arg ... ]
1001 Equivalent to print -nz.
1002 pwd [ -rLP ]
1004 Print the absolute pathname of the current working directory.
1005 If the -r or the -P flag is specified, or the CHASE_LINKS option
1006 is set and the -L flag is not given, the printed path will not
1007 contain symbolic links.
1008 r Same as fc -e -.
1010 read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d delim ]
1012 [ -u n ] [ name[?prompt] ] [ name ... ]
1013 Read one line and break it into fields using the characters in
1014 $IFS as separators, except as noted below. The first field is
1015 assigned to the first name, the second field to the second name,
1016 etc., with leftover fields assigned to the last name. If name
1017 is omitted then REPLY is used for scalars and reply for arrays.
1018 -r Raw mode: a `\' at the end of a line does not signify
1020 line continuation and backslashes in the line don't quote
1021 the following character and are not removed.
1022 -s Don't echo back characters if reading from the terminal.
1024 Currently does not work with the -q option.
1025 -q Read only one character from the terminal and set name to
1027 `y' if this character was `y' or `Y' and to `n' other‐
1028 wise. With this flag set the return status is zero only
1029 if the character was `y' or `Y'. This option may be used
1030 with a timeout; if the read times out, or encounters end
1031 of file, status 2 is returned. Input is read from the
1032 terminal unless one of -u or -p is present. This option
1033 may also be used within zle widgets.
1034 -k [ num ]
1036 Read only one (or num) characters. All are assigned to
1037 the first name, without word splitting. This flag is
1038 ignored when -q is present. Input is read from the ter‐
1039 minal unless one of -u or -p is present. This option may
1040 also be used within zle widgets.
1041 Note that despite the mnemonic `key' this option does
1043 read full characters, which may consist of multiple bytes
1044 if the option MULTIBYTE is set.
1045 -z Read one entry from the editor buffer stack and assign it
1047 to the first name, without word splitting. Text is
1048 pushed onto the stack with `print -z' or with push-line
1049 from the line editor (see zshzle(1)). This flag is
1050 ignored when the -k or -q flags are present.
1051 -e
1053 -E The input read is printed (echoed) to the standard out‐
1054 put. If the -e flag is used, no input is assigned to the
1055 parameters.
1056 -A The first name is taken as the name of an array and all
1058 words are assigned to it.
1059 -c
1061 -l These flags are allowed only if called inside a function
1062 used for completion (specified with the -K flag to com‐
1063 pctl). If the -c flag is given, the words of the current
1064 command are read. If the -l flag is given, the whole line
1065 is assigned as a scalar. If both flags are present, -l
1066 is used and -c is ignored.
1067 -n Together with -c, the number of the word the cursor is on
1069 is read. With -l, the index of the character the cursor
1070 is on is read. Note that the command name is word number
1071 1, not word 0, and that when the cursor is at the end of
1072 the line, its character index is the length of the line
1073 plus one.
1074 -u n Input is read from file descriptor n.
1076 -p Input is read from the coprocess.
1078 -d delim
1080 Input is terminated by the first character of delim
1081 instead of by newline.
1082 -t [ num ]
1084 Test if input is available before attempting to read. If
1085 num is present, it must begin with a digit and will be
1086 evaluated to give a number of seconds, which may be a
1087 floating point number; in this case the read times out if
1088 input is not available within this time. If num is not
1089 present, it is taken to be zero, so that read returns
1090 immediately if no input is available. If no input is
1091 available, return status 1 and do not set any variables.
1092 This option is not available when reading from the editor
1094 buffer with -z, when called from within completion with
1095 -c or -l, with -q which clears the input queue before
1096 reading, or within zle where other mechanisms should be
1097 used to test for input.
1098 Note that read does not attempt to alter the input pro‐
1100 cessing mode. The default mode is canonical input, in
1101 which an entire line is read at a time, so usually `read
1102 -t' will not read anything until an entire line has been
1103 typed. However, when reading from the terminal with -k
1104 input is processed one key at a time; in this case, only
1105 availability of the first character is tested, so that
1106 e.g. `read -t -k 2' can still block on the second charac‐
1107 ter. Use two instances of `read -t -k' if this is not
1108 what is wanted.
1109 If the first argument contains a `?', the remainder of this word
1111 is used as a prompt on standard error when the shell is interac‐
1112 tive.
1113 The value (exit status) of read is 1 when an end-of-file is
1115 encountered, or when -c or -l is present and the command is not
1116 called from a compctl function, or as described for -q. Other‐
1117 wise the value is 0.
1118 The behavior of some combinations of the -k, -p, -q, -u and -z
1120 flags is undefined. Presently -q cancels all the others, -p
1121 cancels -u, -k cancels -z, and otherwise -z cancels both -p and
1122 -u.
1123 The -c or -l flags cancel any and all of -kpquz.
1125 readonly
1127 Same as typeset -r.
1128 rehash Same as hash -r.
1130 return [ n ]
1132 Causes a shell function or `.' script to return to the invoking
1133 script with the return status specified by n. If n is omitted,
1134 the return status is that of the last command executed.
1135 If return was executed from a trap in a TRAPNAL function, the
1137 effect is different for zero and non-zero return status. With
1138 zero status (or after an implicit return at the end of the
1139 trap), the shell will return to whatever it was previously pro‐
1140 cessing; with a non-zero status, the shell will behave as inter‐
1141 rupted except that the return status of the trap is retained.
1142 Note that the numeric value of the signal which caused the trap
1143 is passed as the first argument, so the statement `return
1144 $((128+$1))' will return the same status as if the signal had
1145 not been trapped.
1146 sched See the section `The zsh/sched Module' in zshmodules(1).
1148 set [ {+|-}options | {+|-}o [ option_name ] ] ... [ {+|-}A [ name ] ] [
1150 arg ... ]
1151 Set the options for the shell and/or set the positional parame‐
1152 ters, or declare and set an array. If the -s option is given,
1153 it causes the specified arguments to be sorted before assigning
1154 them to the positional parameters (or to the array name if -A is
1155 used). With +s sort arguments in descending order. For the
1156 meaning of the other flags, see zshoptions(1). Flags may be
1157 specified by name using the -o option. If no option name is sup‐
1158 plied with -o, the current option states are printed: see the
1159 description of setopt below for more information on the format.
1160 With +o they are printed in a form that can be used as input to
1161 the shell.
1162 If the -A flag is specified, name is set to an array containing
1164 the given args; if no name is specified, all arrays are printed
1165 together with their values.
1166 If +A is used and name is an array, the given arguments will
1168 replace the initial elements of that array; if no name is speci‐
1169 fied, all arrays are printed without their values.
1170 The behaviour of arguments after -A name or +A name depends on
1172 whether the option KSH_ARRAYS is set. If it is not set, all
1173 arguments following name are treated as values for the array,
1174 regardless of their form. If the option is set, normal option
1175 processing continues at that point; only regular arguments are
1176 treated as values for the array. This means that
1177 set -A array -x -- foo
1179 sets array to `-x -- foo' if KSH_ARRAYS is not set, but sets the
1181 array to foo and turns on the option `-x' if it is set.
1182 If the -A flag is not present, but there are arguments beyond
1184 the options, the positional parameters are set. If the option
1185 list (if any) is terminated by `--', and there are no further
1186 arguments, the positional parameters will be unset.
1187 If no arguments and no `--' are given, then the names and values
1189 of all parameters are printed on the standard output. If the
1190 only argument is `+', the names of all parameters are printed.
1191 For historical reasons, `set -' is treated as `set +xv' and `set
1193 - args' as `set +xv -- args' when in any other emulation mode
1194 than zsh's native mode.
1195 setcap See the section `The zsh/cap Module' in zshmodules(1).
1197 setopt [ {+|-}options | {+|-}o option_name ] [ name ... ]
1199 Set the options for the shell. All options specified either
1200 with flags or by name are set.
1201 If no arguments are supplied, the names of all options currently
1203 set are printed. The form is chosen so as to minimize the dif‐
1204 ferences from the default options for the current emulation (the
1205 default emulation being native zsh, shown as <Z> in zshop‐
1206 tions(1)). Options that are on by default for the emulation are
1207 shown with the prefix no only if they are off, while other
1208 options are shown without the prefix no and only if they are on.
1209 In addition to options changed from the default state by the
1210 user, any options activated automatically by the shell (for
1211 example, SHIN_STDIN or INTERACTIVE) will be shown in the list.
1212 The format is further modified by the option KSH_OPTION_PRINT,
1213 however the rationale for choosing options with or without the
1214 no prefix remains the same in this case.
1215 If the -m flag is given the arguments are taken as patterns
1217 (which should be quoted to protect them from filename expan‐
1218 sion), and all options with names matching these patterns are
1219 set.
1220 Note that a bad option name does not cause execution of subse‐
1222 quent shell code to be aborted; this is behaviour is different
1223 from that of `set -o'. This is because set is regarded as a
1224 special builtin by the POSIX standard, but setopt is not.
1225 shift [ n ] [ name ... ]
1227 The positional parameters ${n+1} ... are renamed to $1 ...,
1228 where n is an arithmetic expression that defaults to 1. If any
1229 names are given then the arrays with these names are shifted
1230 instead of the positional parameters.
1231 source file [ arg ... ]
1233 Same as `.', except that the current directory is always
1234 searched and is always searched first, before directories in
1235 $path.
1236 stat See the section `The zsh/stat Module' in zshmodules(1).
1238 suspend [ -f ]
1240 Suspend the execution of the shell (send it a SIGTSTP) until it
1241 receives a SIGCONT. Unless the -f option is given, this will
1242 refuse to suspend a login shell.
1243 test [ arg ... ]
1245 [ [ arg ... ] ]
1246 Like the system version of test. Added for compatibility; use
1247 conditional expressions instead (see the section `Conditional
1248 Expressions'). The main differences between the conditional
1249 expression syntax and the test and [ builtins are: these com‐
1250 mands are not handled syntactically, so for example an empty
1251 variable expansion may cause an argument to be omitted; syntax
1252 errors cause status 2 to be returned instead of a shell error;
1253 and arithmetic operators expect integer arguments rather than
1254 arithmetic expressions.
1255 The command attempts to implement POSIX and its extensions where
1257 these are specified. Unfortunately there are intrinsic ambigui‐
1258 ties in the syntax; in particular there is no distinction
1259 between test operators and strings that resemble them. The
1260 standard attempts to resolve these for small numbers of argu‐
1261 ments (up to four); for five or more arguments compatibility
1262 cannot be relied on. Users are urged wherever possible to use
1263 the `[[' test syntax which does not have these ambiguities.
1264 times Print the accumulated user and system times for the shell and
1266 for processes run from the shell.
1267 trap [ arg ] [ sig ... ]
1269 arg is a series of commands (usually quoted to protect it from
1270 immediate evaluation by the shell) to be read and executed when
1271 the shell receives any of the signals specified by one or more
1272 sig args. Each sig can be given as a number, or as the name of
1273 a signal either with or without the string SIG in front (e.g. 1,
1274 HUP, and SIGHUP are all the same signal).
1275 If arg is `-', then the specified signals are reset to their
1277 defaults, or, if no sig args are present, all traps are reset.
1278 If arg is an empty string, then the specified signals are
1280 ignored by the shell (and by the commands it invokes).
1281 If arg is omitted but one or more sig args are provided (i.e.
1283 the first argument is a valid signal number or name), the effect
1284 is the same as if arg had been specified as `-'.
1285 The trap command with no arguments prints a list of commands
1287 associated with each signal.
1288 If sig is ZERR then arg will be executed after each command with
1290 a nonzero exit status. ERR is an alias for ZERR on systems that
1291 have no SIGERR signal (this is the usual case).
1292 If sig is DEBUG then arg will be executed before each command if
1294 the option DEBUG_BEFORE_CMD is set (as it is by default), else
1295 after each command. Here, a `command' is what is described as a
1296 `sublist' in the shell grammar, see the section SIMPLE COMMANDS
1297 & PIPELINES in zshmisc(1). If DEBUG_BEFORE_CMD is set various
1298 additional features are available. First, it is possible to
1299 skip the next command by setting the option ERR_EXIT; see the
1300 description of the ERR_EXIT option in zshoptions(1). Also, the
1301 shell parameter ZSH_DEBUG_CMD is set to the string corresponding
1302 to the command to be executed following the trap. Note that
1303 this string is reconstructed from the internal format and may
1304 not be formatted the same way as the original text. The parame‐
1305 ter is unset after the trap is executed.
1306 If sig is 0 or EXIT and the trap statement is executed inside
1308 the body of a function, then the command arg is executed after
1309 the function completes. The value of $? at the start of execu‐
1310 tion is the exit status of the shell or the return status of the
1311 function exiting. If sig is 0 or EXIT and the trap statement is
1312 not executed inside the body of a function, then the command arg
1313 is executed when the shell terminates; the trap runs before any
1314 zshexit hook functions.
1315 ZERR, DEBUG, and EXIT traps are not executed inside other traps.
1317 ZERR and DEBUG traps are kept within subshells, while other
1318 traps are reset.
1319 Note that traps defined with the trap builtin are slightly dif‐
1321 ferent from those defined as `TRAPNAL () { ... }', as the latter
1322 have their own function environment (line numbers, local vari‐
1323 ables, etc.) while the former use the environment of the command
1324 in which they were called. For example,
1325 trap 'print $LINENO' DEBUG
1327 will print the line number of a command executed after it has
1329 run, while
1330 TRAPDEBUG() { print $LINENO; }
1332 will always print the number zero.
1334 Alternative signal names are allowed as described under kill
1336 above. Defining a trap under either name causes any trap under
1337 an alternative name to be removed. However, it is recommended
1338 that for consistency users stick exclusively to one name or
1339 another.
1340 true [ arg ... ]
1342 Do nothing and return an exit status of 0.
1343 ttyctl -fu
1345 The -f option freezes the tty, and -u unfreezes it. When the
1346 tty is frozen, no changes made to the tty settings by external
1347 programs will be honored by the shell, except for changes in the
1348 size of the screen; the shell will simply reset the settings to
1349 their previous values as soon as each command exits or is sus‐
1350 pended. Thus, stty and similar programs have no effect when the
1351 tty is frozen. Without options it reports whether the terminal
1352 is frozen or not.
1353 type [ -wfpams ] name ...
1355 Equivalent to whence -v.
1356 typeset [ {+|-}AEFHUafghklprtuxmz ] [ -LRZi [ n ]] [ name[=value] ... ]
1358 typeset -T [ {+|-}Urux ] [ -LRZ [ n ]] SCALAR[=value] array [ sep ]
1359 Set or display attributes and values for shell parameters.
1360 A parameter is created for each name that does not already refer
1362 to one. When inside a function, a new parameter is created for
1363 every name (even those that already exist), and is unset again
1364 when the function completes. See `Local Parameters' in zsh‐
1365 param(1). The same rules apply to special shell parameters,
1366 which retain their special attributes when made local.
1367 For each name=value assignment, the parameter name is set to
1369 value. Note that arrays currently cannot be assigned in typeset
1370 expressions, only scalars and integers. Unless the option
1371 KSH_TYPESET is set, normal expansion rules apply to assignment
1372 arguments, so value may be split into separate words; if the
1373 option is set, assignments which can be recognised when expan‐
1374 sion is performed are treated as single words. For example the
1375 command typeset vbl=$(echo one two) is treated as having one
1376 argument if KSH_TYPESET is set, but otherwise is treated as hav‐
1377 ing the two arguments vbl=one and two.
1378 If the shell option TYPESET_SILENT is not set, for each remain‐
1380 ing name that refers to a parameter that is set, the name and
1381 value of the parameter are printed in the form of an assignment.
1382 Nothing is printed for newly-created parameters, or when any
1383 attribute flags listed below are given along with the name.
1384 Using `+' instead of minus to introduce an attribute turns it
1385 off.
1386 If the -p option is given, parameters and values are printed in
1388 the form of a typeset command and an assignment (which will be
1389 printed separately for arrays and associative arrays), regard‐
1390 less of other flags and options. Note that the -h flag on
1391 parameters is respected; no value will be shown for these param‐
1392 eters.
1393 If the -T option is given, two or three arguments must be
1395 present (an exception is that zero arguments are allowed to show
1396 the list of parameters created in this fashion). The first two
1397 are the name of a scalar and an array parameter (in that order)
1398 that will be tied together in the manner of $PATH and $path.
1399 The optional third argument is a single-character separator
1400 which will be used to join the elements of the array to form the
1401 scalar; if absent, a colon is used, as with $PATH. Only the
1402 first character of the separator is significant; any remaining
1403 characters are ignored. Only the scalar parameter may be
1404 assigned an initial value. Both the scalar and the array may
1405 otherwise be manipulated as normal. If one is unset, the other
1406 will automatically be unset too. There is no way of untying the
1407 variables without unsetting them, or converting the type of one
1408 of them with another typeset command; +T does not work, assign‐
1409 ing an array to SCALAR is an error, and assigning a scalar to
1410 array sets it to be a single-element array. Note that both
1411 `typeset -xT ...' and `export -T ...' work, but only the scalar
1412 will be marked for export. Setting the value using the scalar
1413 version causes a split on all separators (which cannot be
1414 quoted). It is possible to use the same two tied variables with
1415 a different separator character in which case the variables
1416 remain joined as before but the separator is changed. This flag
1417 has a different meaning when used with -f; see below.
1418 The -g (global) flag is treated specially: it means that any
1420 resulting parameter will not be restricted to local scope. Note
1421 that this does not necessarily mean that the parameter will be
1422 global, as the flag will apply to any existing parameter (even
1423 if unset) from an enclosing function. This flag does not affect
1424 the parameter after creation, hence it has no effect when list‐
1425 ing existing parameters, nor does the flag +g have any effect
1426 except in combination with -m (see below).
1427 If no name is present, the names and values of all parameters
1429 are printed. In this case the attribute flags restrict the dis‐
1430 play to only those parameters that have the specified
1431 attributes, and using `+' rather than `-' to introduce the flag
1432 suppresses printing of the values of parameters when there is no
1433 parameter name. Also, if the last option is the word `+', then
1434 names are printed but values are not.
1435 If the -m flag is given the name arguments are taken as patterns
1437 (which should be quoted). With no attribute flags, all parame‐
1438 ters (or functions with the -f flag) with matching names are
1439 printed (the shell option TYPESET_SILENT is not used in this
1440 case). Note that -m is ignored if no patterns are given. If
1441 the +g flag is combined with -m, a new local parameter is cre‐
1442 ated for every matching parameter that is not already local.
1443 Otherwise -m applies all other flags or assignments to the
1444 existing parameters. Except when assignments are made with
1445 name=value, using +m forces the matching parameters to be
1446 printed, even inside a function.
1447 If no attribute flags are given and either no -m flag is present
1449 or the +m form was used, each parameter name printed is preceded
1450 by a list of the attributes of that parameter (array, associa‐
1451 tion, exported, integer, readonly). If +m is used with
1452 attribute flags, and all those flags are introduced with +, the
1453 matching parameter names are printed but their values are not.
1454 Attribute flags that transform the final value (-L, -R, -Z, -l,
1456 u) are only applied to the expanded value at the point of a
1457 parameter expansion expression using `$'. They are not applied
1458 when a parameter is retrieved internally by the shell for any
1459 purpose.
1460 The following attribute flags may be specified:
1462 -A The names refer to associative array parameters; see
1464 `Array Parameters' in zshparam(1).
1465 -L Left justify and remove leading blanks from value. If n
1467 is nonzero, it defines the width of the field. If n is
1468 zero, the width is determined by the width of the value
1469 of the first assignment. In the case of numeric parame‐
1470 ters, the length of the complete value assigned to the
1471 parameter is used to determine the width, not the value
1472 that would be output.
1473 The width is the count of characters, which may be multi‐
1475 byte characters if the MULTIBYTE option is in effect.
1476 Note that the screen width of the character is not taken
1477 into account; if this is required, use padding with
1478 parameter expansion flags ${(ml...)...} as described in
1479 `Parameter Expansion Flags' in zshexpn(1).
1480 When the parameter is expanded, it is filled on the right
1482 with blanks or truncated if necessary to fit the field.
1483 Note truncation can lead to unexpected results with
1484 numeric parameters. Leading zeros are removed if the -Z
1485 flag is also set.
1486 -R Similar to -L, except that right justification is used;
1488 when the parameter is expanded, the field is left filled
1489 with blanks or truncated from the end. May not be com‐
1490 bined with the -Z flag.
1491 -U For arrays (but not for associative arrays), keep only
1493 the first occurrence of each duplicated value. This may
1494 also be set for colon-separated special parameters like
1495 PATH or FIGNORE, etc. This flag has a different meaning
1496 when used with -f; see below.
1497 -Z Specially handled if set along with the -L flag. Other‐
1499 wise, similar to -R, except that leading zeros are used
1500 for padding instead of blanks if the first non-blank
1501 character is a digit. Numeric parameters are specially
1502 handled: they are always eligible for padding with
1503 zeroes, and the zeroes are inserted at an appropriate
1504 place in the output.
1505 -a The names refer to array parameters. An array parameter
1507 may be created this way, but it may not be assigned to in
1508 the typeset statement. When displaying, both normal and
1509 associative arrays are shown.
1510 -f The names refer to functions rather than parameters. No
1512 assignments can be made, and the only other valid flags
1513 are -t, -T, -k, -u, -U and -z. The flag -t turns on exe‐
1514 cution tracing for this function; the flag -T does the
1515 same, but turns off tracing on any function called from
1516 the present one, unless that function also has the -t or
1517 -T flag. The -u and -U flags cause the function to be
1518 marked for autoloading; -U also causes alias expansion to
1519 be suppressed when the function is loaded. The fpath
1520 parameter will be searched to find the function defini‐
1521 tion when the function is first referenced; see the sec‐
1522 tion `Functions'. The -k and -z flags make the function
1523 be loaded using ksh-style or zsh-style autoloading
1524 respectively. If neither is given, the setting of the
1525 KSH_AUTOLOAD option determines how the function is
1526 loaded.
1527 -h Hide: only useful for special parameters (those marked
1529 `<S>' in the table in zshparam(1)), and for local parame‐
1530 ters with the same name as a special parameter, though
1531 harmless for others. A special parameter with this
1532 attribute will not retain its special effect when made
1533 local. Thus after `typeset -h PATH', a function contain‐
1534 ing `typeset PATH' will create an ordinary local parame‐
1535 ter without the usual behaviour of PATH. Alternatively,
1536 the local parameter may itself be given this attribute;
1537 hence inside a function `typeset -h PATH' creates an
1538 ordinary local parameter and the special PATH parameter
1539 is not altered in any way. It is also possible to create
1540 a local parameter using `typeset +h special', where the
1541 local copy of special will retain its special properties
1542 regardless of having the -h attribute. Global special
1543 parameters loaded from shell modules (currently those in
1544 zsh/mapfile and zsh/parameter) are automatically given
1545 the -h attribute to avoid name clashes.
1546 -H Hide value: specifies that typeset will not display the
1548 value of the parameter when listing parameters; the dis‐
1549 play for such parameters is always as if the `+' flag had
1550 been given. Use of the parameter is in other respects
1551 normal, and the option does not apply if the parameter is
1552 specified by name, or by pattern with the -m option.
1553 This is on by default for the parameters in the
1554 zsh/parameter and zsh/mapfile modules. Note, however,
1555 that unlike the -h flag this is also useful for non-spe‐
1556 cial parameters.
1557 -i Use an internal integer representation. If n is nonzero
1559 it defines the output arithmetic base, otherwise it is
1560 determined by the first assignment. Bases from 2 to 36
1561 inclusive are allowed.
1562 -E Use an internal double-precision floating point represen‐
1564 tation. On output the variable will be converted to sci‐
1565 entific notation. If n is nonzero it defines the number
1566 of significant figures to display; the default is ten.
1567 -F Use an internal double-precision floating point represen‐
1569 tation. On output the variable will be converted to
1570 fixed-point decimal notation. If n is nonzero it defines
1571 the number of digits to display after the decimal point;
1572 the default is ten.
1573 -l Convert the result to lower case whenever the parameter
1575 is expanded. The value is not converted when assigned.
1576 -r The given names are marked readonly. Note that if name
1578 is a special parameter, the readonly attribute can be
1579 turned on, but cannot then be turned off.
1580 -t Tags the named parameters. Tags have no special meaning
1582 to the shell. This flag has a different meaning when
1583 used with -f; see above.
1584 -u Convert the result to upper case whenever the parameter
1586 is expanded. The value is not converted when assigned.
1587 This flag has a different meaning when used with -f; see
1588 above.
1589 -x Mark for automatic export to the environment of subse‐
1591 quently executed commands. If the option GLOBAL_EXPORT
1592 is set, this implies the option -g, unless +g is also
1593 explicitly given; in other words the parameter is not
1594 made local to the enclosing function. This is for com‐
1595 patibility with previous versions of zsh.
1596 ulimit [ [ -SHacdfilmnpqrstvx | -N resource [ limit ] ... ]
1598 Set or display resource limits of the shell and the processes
1599 started by the shell. The value of limit can be a number in the
1600 unit specified below or one of the values `unlimited', which
1601 removes the limit on the resource, or `hard', which uses the
1602 current value of the hard limit on the resource.
1603 By default, only soft limits are manipulated. If the -H flag is
1605 given use hard limits instead of soft limits. If the -S flag is
1606 given together with the -H flag set both hard and soft limits.
1607 If no options are used, the file size limit (-f) is assumed.
1609 If limit is omitted the current value of the specified resources
1611 are printed. When more than one resource value is printed, the
1612 limit name and unit is printed before each value.
1613 When looping over multiple resources, the shell will abort imme‐
1615 diately if it detects a badly formed argument. However, if it
1616 fails to set a limit for some other reason it will continue try‐
1617 ing to set the remaining limits.
1618 Not all the following resources are supported on all systems.
1620 Running ulimit -a will show which are supported.
1621 -a Lists all of the current resource limits.
1623 -b Socket buffer size in bytes (N.B. not kilobytes)
1624 -c 512-byte blocks on the size of core dumps.
1625 -d Kilobytes on the size of the data segment.
1626 -f 512-byte blocks on the size of files written.
1627 -i The number of pending signals.
1628 -l Kilobytes on the size of locked-in memory.
1629 -m Kilobytes on the size of physical memory.
1630 -n open file descriptors.
1631 -q Bytes in POSIX message queues.
1632 -s Kilobytes on the size of the stack.
1633 -t CPU seconds to be used.
1634 -r The number of simultaneous threads available to the user.
1635 -u The number of processes available to the user.
1636 -v Kilobytes on the size of virtual memory. On some systems
1637 this refers to the limit called `address space'.
1638 -x The number of locks on files.
1639 A resource may also be specified by integer in the form `-N
1641 resource', where resource corresponds to the integer defined for
1642 the resource by the operating system. This may be used to set
1643 the limits for resources known to the shell which do not corre‐
1644 spond to option letters. Such limits will be shown by number in
1645 the output of `ulimit -a'.
1646 The number may alternatively be out of the range of limits com‐
1648 piled into the shell. The shell will try to read or write the
1649 limit anyway, and will report an error if this fails.
1650 umask [ -S ] [ mask ]
1652 The umask is set to mask. mask can be either an octal number or
1653 a symbolic value as described in chmod(1). If mask is omitted,
1654 the current value is printed. The -S option causes the mask to
1655 be printed as a symbolic value. Otherwise, the mask is printed
1656 as an octal number. Note that in the symbolic form the permis‐
1657 sions you specify are those which are to be allowed (not denied)
1658 to the users specified.
1659 unalias
1661 Same as unhash -a.
1662 unfunction
1664 Same as unhash -f.
1665 unhash [ -adfms ] name ...
1667 Remove the element named name from an internal hash table. The
1668 default is remove elements from the command hash table. The -a
1669 option causes unhash to remove regular or global aliases; note
1670 when removing a global aliases that the argument must be quoted
1671 to prevent it from being expanded before being passed to the
1672 command. The -s option causes unhash to remove suffix aliases.
1673 The -f option causes unhash to remove shell functions. The -d
1674 options causes unhash to remove named directories. If the -m
1675 flag is given the arguments are taken as patterns (should be
1676 quoted) and all elements of the corresponding hash table with
1677 matching names will be removed.
1678 unlimit [ -hs ] resource ...
1680 The resource limit for each resource is set to the hard limit.
1681 If the -h flag is given and the shell has appropriate privi‐
1682 leges, the hard resource limit for each resource is removed.
1683 The resources of the shell process are only changed if the -s
1684 flag is given.
1685 The unlimit command is not made available by default when the
1687 shell starts in a mode emulating another shell. It can be made
1688 available with the command `zmodload -F zsh/rlimits b:unlimit'.
1689 unset [ -fmv ] name ...
1691 Each named parameter is unset. Local parameters remain local
1692 even if unset; they appear unset within scope, but the previous
1693 value will still reappear when the scope ends.
1694 Individual elements of associative array parameters may be unset
1696 by using subscript syntax on name, which should be quoted (or
1697 the entire command prefixed with noglob) to protect the sub‐
1698 script from filename generation.
1699 If the -m flag is specified the arguments are taken as patterns
1701 (should be quoted) and all parameters with matching names are
1702 unset. Note that this cannot be used when unsetting associative
1703 array elements, as the subscript will be treated as part of the
1704 pattern.
1705 The -v flag specifies that name refers to parameters. This is
1707 the default behaviour.
1708 unset -f is equivalent to unfunction.
1710 unsetopt [ {+|-}options | {+|-}o option_name ] [ name ... ]
1712 Unset the options for the shell. All options specified either
1713 with flags or by name are unset. If no arguments are supplied,
1714 the names of all options currently unset are printed. If the -m
1715 flag is given the arguments are taken as patterns (which should
1716 be quoted to preserve them from being interpreted as glob pat‐
1717 terns), and all options with names matching these patterns are
1718 unset.
1719 vared See the section `Zle Builtins' in zshzle(1).
1721 wait [ job ... ]
1723 Wait for the specified jobs or processes. If job is not given
1724 then all currently active child processes are waited for. Each
1725 job can be either a job specification or the process ID of a job
1726 in the job table. The exit status from this command is that of
1727 the job waited for.
1728 whence [ -vcwfpams ] name ...
1730 For each name, indicate how it would be interpreted if used as a
1731 command name.
1732 -v Produce a more verbose report.
1734 -c Print the results in a csh-like format. This takes
1736 precedence over -v.
1737 -w For each name, print `name: word' where word is one of
1739 alias, builtin, command, function, hashed, reserved or
1740 none, according as name corresponds to an alias, a
1741 built-in command, an external command, a shell function,
1742 a command defined with the hash builtin, a reserved word,
1743 or is not recognised. This takes precedence over -v and
1744 -c.
1745 -f Causes the contents of a shell function to be displayed,
1747 which would otherwise not happen unless the -c flag were
1748 used.
1749 -p Do a path search for name even if it is an alias,
1751 reserved word, shell function or builtin.
1752 -a Do a search for all occurrences of name throughout the
1754 command path. Normally only the first occurrence is
1755 printed.
1756 -m The arguments are taken as patterns (should be quoted),
1758 and the information is displayed for each command match‐
1759 ing one of these patterns.
1760 -s If a pathname contains symlinks, print the symlink-free
1762 pathname as well.
1763 where [ -wpms ] name ...
1765 Equivalent to whence -ca.
1766 which [ -wpams ] name ...
1768 Equivalent to whence -c.
1769 zcompile [ -U ] [ -z | -k ] [ -R | -M ] file [ name ... ]
1771 zcompile -ca [ -m ] [ -R | -M ] file [ name ... ]
1772 zcompile -t file [ name ... ]
1773 This builtin command can be used to compile functions or
1774 scripts, storing the compiled form in a file, and to examine
1775 files containing the compiled form. This allows faster
1776 autoloading of functions and execution of scripts by avoiding
1777 parsing of the text when the files are read.
1778 The first form (without the -c, -a or -t options) creates a com‐
1780 piled file. If only the file argument is given, the output file
1781 has the name `file.zwc' and will be placed in the same directory
1782 as the file. The shell will load the compiled file instead of
1783 the normal function file when the function is autoloaded; see
1784 the section `Autoloading Functions' in zshmisc(1) for a descrip‐
1785 tion of how autoloaded functions are searched. The extension
1786 .zwc stands for `zsh word code'.
1787 If there is at least one name argument, all the named files are
1789 compiled into the output file given as the first argument. If
1790 file does not end in .zwc, this extension is automatically
1791 appended. Files containing multiple compiled functions are
1792 called `digest' files, and are intended to be used as elements
1793 of the FPATH/fpath special array.
1794 The second form, with the -c or -a options, writes the compiled
1796 definitions for all the named functions into file. For -c, the
1797 names must be functions currently defined in the shell, not
1798 those marked for autoloading. Undefined functions that are
1799 marked for autoloading may be written by using the -a option, in
1800 which case the fpath is searched and the contents of the defini‐
1801 tion files for those functions, if found, are compiled into
1802 file. If both -c and -a are given, names of both defined func‐
1803 tions and functions marked for autoloading may be given. In
1804 either case, the functions in files written with the -c or -a
1805 option will be autoloaded as if the KSH_AUTOLOAD option were
1806 unset.
1807 The reason for handling loaded and not-yet-loaded functions with
1809 different options is that some definition files for autoloading
1810 define multiple functions, including the function with the same
1811 name as the file, and, at the end, call that function. In such
1812 cases the output of `zcompile -c' does not include the addi‐
1813 tional functions defined in the file, and any other initializa‐
1814 tion code in the file is lost. Using `zcompile -a' captures all
1815 this extra information.
1816 If the -m option is combined with -c or -a, the names are used
1818 as patterns and all functions whose names match one of these
1819 patterns will be written. If no name is given, the definitions
1820 of all functions currently defined or marked as autoloaded will
1821 be written.
1822 The third form, with the -t option, examines an existing com‐
1824 piled file. Without further arguments, the names of the origi‐
1825 nal files compiled into it are listed. The first line of output
1826 shows the version of the shell which compiled the file and how
1827 the file will be used (i.e. by reading it directly or by mapping
1828 it into memory). With arguments, nothing is output and the
1829 return status is set to zero if definitions for all names were
1830 found in the compiled file, and non-zero if the definition for
1831 at least one name was not found.
1832 Other options:
1834 -U Aliases are not expanded when compiling the named files.
1836 -R When the compiled file is read, its contents are copied
1838 into the shell's memory, rather than memory-mapped (see
1839 -M). This happens automatically on systems that do not
1840 support memory mapping.
1841 When compiling scripts instead of autoloadable functions,
1843 it is often desirable to use this option; otherwise the
1844 whole file, including the code to define functions which
1845 have already been defined, will remain mapped, conse‐
1846 quently wasting memory.
1847 -M The compiled file is mapped into the shell's memory when
1849 read. This is done in such a way that multiple instances
1850 of the shell running on the same host will share this
1851 mapped file. If neither -R nor -M is given, the zcompile
1852 builtin decides what to do based on the size of the com‐
1853 piled file.
1854 -k
1856 -z These options are used when the compiled file contains
1857 functions which are to be autoloaded. If -z is given, the
1858 function will be autoloaded as if the KSH_AUTOLOAD option
1859 is not set, even if it is set at the time the compiled
1860 file is read, while if the -k is given, the function will
1861 be loaded as if KSH_AUTOLOAD is set. These options also
1862 take precedence over any -k or -z options specified to
1863 the autoload builtin. If neither of these options is
1864 given, the function will be loaded as determined by the
1865 setting of the KSH_AUTOLOAD option at the time the com‐
1866 piled file is read.
1867 These options may also appear as many times as necessary
1869 between the listed names to specify the loading style of
1870 all following functions, up to the next -k or -z.
1871 The created file always contains two versions of the com‐
1873 piled format, one for big-endian machines and one for
1874 small-endian machines. The upshot of this is that the
1875 compiled file is machine independent and if it is read or
1876 mapped, only one half of the file is actually used (and
1877 mapped).
1878 zformat
1880 See the section `The zsh/zutil Module' in zshmodules(1).
1881 zftp See the section `The zsh/zftp Module' in zshmodules(1).
1883 zle See the section `Zle Builtins' in zshzle(1).
1885 zmodload [ -dL ] [ ... ]
1887 zmodload -F [ -lLme -P param ] module [+-]feature...
1888 zmodload -e [ -A ] [ ... ]
1889 zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...
1890 zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...
1891 zmodload -A [ -L ] [ modalias[=module] ... ]
1892 zmodload -R modalias ...
1893 Performs operations relating to zsh's loadable modules. Loading
1894 of modules while the shell is running (`dynamical loading') is
1895 not available on all operating systems, or on all installations
1896 on a particular operating system, although the zmodload command
1897 itself is always available and can be used to manipulate modules
1898 built into versions of the shell executable without dynamical
1899 loading.
1900 Without arguments the names of all currently loaded binary mod‐
1902 ules are printed. The -L option causes this list to be in the
1903 form of a series of zmodload commands. Forms with arguments
1904 are:
1905 zmodload [ -i ] name ...
1907 zmodload -u [ -i ] name ...
1908 In the simplest case, zmodload loads a binary module.
1909 The module must be in a file with a name consisting of
1910 the specified name followed by a standard suffix, usually
1911 `.so' (`.sl' on HPUX). If the module to be loaded is
1912 already loaded the duplicate module is ignored. If zmod‐
1913 load detects an inconsistency, such as an invalid module
1914 name or circular dependency list, the current code block
1915 is aborted. Hence `zmodload module 2>/dev/null' is suf‐
1916 ficient to test whether a module is available. If it is
1917 available, the module is loaded if necessary, while if it
1918 is not available, non-zero status is silently returned.
1919 The option -i is accepted for compatibility but has no
1920 effect.
1921 The named module is searched for in the same way a com‐
1923 mand is, using $module_path instead of $path. However,
1924 the path search is performed even when the module name
1925 contains a `/', which it usually does. There is no way
1926 to prevent the path search.
1927 If the module supports features (see below), zmodload
1929 tries to enable all features when loading a module. If
1930 the module was successfully loaded but not all features
1931 could be enabled, zmodload returns status 2.
1932 With -u, zmodload unloads modules. The same name must be
1934 given that was given when the module was loaded, but it
1935 is not necessary for the module to exist in the file sys‐
1936 tem. The -i option suppresses the error if the module is
1937 already unloaded (or was never loaded).
1938 Each module has a boot and a cleanup function. The mod‐
1940 ule will not be loaded if its boot function fails. Simi‐
1941 larly a module can only be unloaded if its cleanup func‐
1942 tion runs successfully.
1943 zmodload -F [ -almLe -P param ] module [+-]feature...
1945 zmodload -F allows more selective control over the fea‐
1946 tures provided by modules. With no options apart from
1947 -F, the module named module is loaded, if it was not
1948 already loaded, and the list of features is set to the
1949 required state. If no features are specified, the module
1950 is loaded, if it was not already loaded, but the state of
1951 features is unchanged. Each feature may be preceded by a
1952 + to turn the feature on, or - to turn it off; the + is
1953 assumed if neither character is present. Any feature not
1954 explicitly mentioned is left in its current state; if the
1955 module was not previously loaded this means any such fea‐
1956 tures will remain disabled. The return status is zero if
1957 all features were set, 1 if the module failed to load,
1958 and 2 if some features could not be set (for example, a
1959 parameter couldn't be added because there was a different
1960 parameter of the same name) but the module was loaded.
1961 The standard features are builtins, conditions, parame‐
1963 ters and math functions; these are indicated by the pre‐
1964 fix `b:', `c:' (`C:' for an infix condition), `p:' and
1965 `f:', respectively, followed by the name that the corre‐
1966 sponding feature would have in the shell. For example,
1967 `b:strftime' indicates a builtin named strftime and
1968 p:EPOCHSECONDS indicates a parameter named EPOCHSECONDS.
1969 The module may provide other (`abstract') features of its
1970 own as indicated by its documentation; these have no pre‐
1971 fix.
1972 With -l or -L, features provided by the module are
1974 listed. With -l alone, a list of features together with
1975 their states is shown, one feature per line. With -L
1976 alone, a zmodload -F command that would cause enabled
1977 features of the module to be turned on is shown. With
1978 -lL, a zmodload -F command that would cause all the fea‐
1979 tures to be set to their current state is shown. If one
1980 of these combinations is given the option -P param then
1981 the parameter param is set to an array of features,
1982 either features together with their state or (if -L alone
1983 is given) enabled features.
1984 With the option -L the module name may be omitted; then a
1986 list of all enabled features for all modules providing
1987 features is printed in the form of zmodload -F commands.
1988 If -l is also given, the state of both enabled and dis‐
1989 abled features is output in that form.
1990 A set of features may be provided together with -l or -L
1992 and a module name; in that case only the state of those
1993 features is considered. Each feature may be preceded by
1994 + or - but the character has no effect. If no set of
1995 features is provided, all features are considered.
1996 With -e, the command first tests that the module is
1998 loaded; if it is not, status 1 is returned. If the mod‐
1999 ule is loaded, the list of features given as an argument
2000 is examined. Any feature given with no prefix is simply
2001 tested to see if the module provides it; any feature
2002 given with a prefix + or - is tested to see if is pro‐
2003 vided and in the given state. If the tests on all fea‐
2004 tures in the list succeed, status 0 is returned, else
2005 status 1.
2006 With -m, each entry in the given list of features is
2008 taken as a pattern to be matched against the list of fea‐
2009 tures provided by the module. An initial + or - must be
2010 given explicitly. This may not be combined with the -a
2011 option as autoloads must be specified explicitly.
2012 With -a, the given list of features is marked for
2014 autoload from the specified module, which may not yet be
2015 loaded. An optional + may appear before the feature
2016 name. If the feature is prefixed with -, any existing
2017 autoload is removed. The options -l and -L may be used
2018 to list autoloads. Autoloading is specific to individual
2019 features; when the module is loaded only the requested
2020 feature is enabled. Autoload requests are preserved if
2021 the module is subsequently unloaded until an explicit
2022 `zmodload -Fa module -feature' is issued. It is not an
2023 error to request an autoload for a feature of a module
2024 that is already loaded.
2025 When the module is loaded each autoload is checked
2027 against the features actually provided by the module; if
2028 the feature is not provided the autoload request is
2029 deleted. A warning message is output; if the module is
2030 being loaded to provide a different feature, and that
2031 autoload is successful, there is no effect on the status
2032 of the current command. If the module is already loaded
2033 at the time when zmodload -Fa is run, an error message is
2034 printed and status 1 returned.
2035 zmodload -Fa can be used with the -l, -L, -e and -P
2037 options for listing and testing the existence of
2038 autoloadable features. In this case -l is ignored if -L
2039 is specified. zmodload -FaL with no module name lists
2040 autoloads for all modules.
2041 Note that only standard features as described above can
2043 be autoloaded; other features require the module to be
2044 loaded before enabling.
2045 zmodload -d [ -L ] [ name ]
2047 zmodload -d name dep ...
2048 zmodload -ud name [ dep ... ]
2049 The -d option can be used to specify module dependencies.
2050 The modules named in the second and subsequent arguments
2051 will be loaded before the module named in the first argu‐
2052 ment.
2053 With -d and one argument, all dependencies for that mod‐
2055 ule are listed. With -d and no arguments, all module
2056 dependencies are listed. This listing is by default in a
2057 Makefile-like format. The -L option changes this format
2058 to a list of zmodload -d commands.
2059 If -d and -u are both used, dependencies are removed. If
2061 only one argument is given, all dependencies for that
2062 module are removed.
2063 zmodload -ab [ -L ]
2065 zmodload -ab [ -i ] name [ builtin ... ]
2066 zmodload -ub [ -i ] builtin ...
2067 The -ab option defines autoloaded builtins. It defines
2068 the specified builtins. When any of those builtins is
2069 called, the module specified in the first argument is
2070 loaded and all its features are enabled (for selective
2071 control of features use `zmodload -F -a' as described
2072 above). If only the name is given, one builtin is
2073 defined, with the same name as the module. -i suppresses
2074 the error if the builtin is already defined or
2075 autoloaded, but not if another builtin of the same name
2076 is already defined.
2077 With -ab and no arguments, all autoloaded builtins are
2079 listed, with the module name (if different) shown in
2080 parentheses after the builtin name. The -L option
2081 changes this format to a list of zmodload -a commands.
2082 If -b is used together with the -u option, it removes
2084 builtins previously defined with -ab. This is only pos‐
2085 sible if the builtin is not yet loaded. -i suppresses
2086 the error if the builtin is already removed (or never
2087 existed).
2088 Autoload requests are retained if the module is subse‐
2090 quently unloaded until an explicit `zmodload -ub builtin'
2091 is issued.
2092 zmodload -ac [ -IL ]
2094 zmodload -ac [ -iI ] name [ cond ... ]
2095 zmodload -uc [ -iI ] cond ...
2096 The -ac option is used to define autoloaded condition
2097 codes. The cond strings give the names of the conditions
2098 defined by the module. The optional -I option is used to
2099 define infix condition names. Without this option prefix
2100 condition names are defined.
2101 If given no condition names, all defined names are listed
2103 (as a series of zmodload commands if the -L option is
2104 given).
2105 The -uc option removes definitions for autoloaded condi‐
2107 tions.
2108 zmodload -ap [ -L ]
2110 zmodload -ap [ -i ] name [ parameter ... ]
2111 zmodload -up [ -i ] parameter ...
2112 The -p option is like the -b and -c options, but makes
2113 zmodload work on autoloaded parameters instead.
2114 zmodload -af [ -L ]
2116 zmodload -af [ -i ] name [ function ... ]
2117 zmodload -uf [ -i ] function ...
2118 The -f option is like the -b, -p, and -c options, but
2119 makes zmodload work on autoloaded math functions instead.
2120 zmodload -a [ -L ]
2122 zmodload -a [ -i ] name [ builtin ... ]
2123 zmodload -ua [ -i ] builtin ...
2124 Equivalent to -ab and -ub.
2125 zmodload -e [ -A ] [ string ... ]
2127 The -e option without arguments lists all loaded modules;
2128 if the -A option is also given, module aliases corre‐
2129 sponding to loaded modules are also shown. If arguments
2130 are provided, nothing is printed; the return status is
2131 set to zero if all strings given as arguments are names
2132 of loaded modules and to one if at least on string is not
2133 the name of a loaded module. This can be used to test
2134 for the availability of things implemented by modules.
2135 In this case, any aliases are automatically resolved and
2136 the -A flag is not used.
2137 zmodload -A [ -L ] [ modalias[=module] ... ]
2139 For each argument, if both modalias and module are given,
2140 define modalias to be an alias for the module module. If
2141 the module modalias is ever subsequently requested,
2142 either via a call to zmodload or implicitly, the shell
2143 will attempt to load module instead. If module is not
2144 given, show the definition of modalias. If no arguments
2145 are given, list all defined module aliases. When list‐
2146 ing, if the -L flag was also given, list the definition
2147 as a zmodload command to recreate the alias.
2148 The existence of aliases for modules is completely inde‐
2150 pendent of whether the name resolved is actually loaded
2151 as a module: while the alias exists, loading and unload‐
2152 ing the module under any alias has exactly the same
2153 effect as using the resolved name, and does not affect
2154 the connection between the alias and the resolved name
2155 which can be removed either by zmodload -R or by redefin‐
2156 ing the alias. Chains of aliases (i.e. where the first
2157 resolved name is itself an alias) are valid so long as
2158 these are not circular. As the aliases take the same
2159 format as module names, they may include path separators:
2160 in this case, there is no requirement for any part of the
2161 path named to exist as the alias will be resolved first.
2162 For example, `any/old/alias' is always a valid alias.
2163 Dependencies added to aliased modules are actually added
2165 to the resolved module; these remain if the alias is
2166 removed. It is valid to create an alias whose name is
2167 one of the standard shell modules and which resolves to a
2168 different module. However, if a module has dependencies,
2169 it will not be possible to use the module name as an
2170 alias as the module will already be marked as a loadable
2171 module in its own right.
2172 Apart from the above, aliases can be used in the zmodload
2174 command anywhere module names are required. However,
2175 aliases will not be shown in lists of loaded modules with
2176 a bare `zmodload'.
2177 zmodload -R modalias ...
2179 For each modalias argument that was previously defined as
2180 a module alias via zmodload -A, delete the alias. If any
2181 was not defined, an error is caused and the remainder of
2182 the line is ignored.
2183 Note that zsh makes no distinction between modules that were
2185 linked into the shell and modules that are loaded dynamically.
2186 In both cases this builtin command has to be used to make avail‐
2187 able the builtins and other things defined by modules (unless
2188 the module is autoloaded on these definitions). This is true
2189 even for systems that don't support dynamic loading of modules.
2190 zparseopts
2192 See the section `The zsh/zutil Module' in zshmodules(1).
2193 zprof See the section `The zsh/zprof Module' in zshmodules(1).
2195 zpty See the section `The zsh/zpty Module' in zshmodules(1).
2197 zregexparse
2199 See the section `The zsh/zutil Module' in zshmodules(1).
2200 zsocket
2202 See the section `The zsh/net/socket Module' in zshmodules(1).
2203 zstyle See the section `The zsh/zutil Module' in zshmodules(1).
2205 ztcp See the section `The zsh/net/tcp Module' in zshmodules(1).
2207zsh 5.0.2 December 21, 2012 ZSHBUILTINS(1)