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