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