1ZSHMODULES(1) General Commands Manual ZSHMODULES(1)
2
6 zshmodules - zsh loadable modules
7
9 Some optional parts of zsh are in modules, separate from the core of
10 the shell. Each of these modules may be linked in to the shell at
11 build time, or can be dynamically linked while the shell is running if
12 the installation supports this feature. Modules are linked at runtime
13 with the zmodload command, see zshbuiltins(1).
14 The modules that are bundled with the zsh distribution are:
16 zsh/attr
18 Builtins for manipulating extended attributes (xattr).
19 zsh/cap
21 Builtins for manipulating POSIX.1e (POSIX.6) capability (privi‐
22 lege) sets.
23 zsh/clone
25 A builtin that can clone a running shell onto another terminal.
26 zsh/compctl
28 The compctl builtin for controlling completion.
29 zsh/complete
31 The basic completion code.
32 zsh/complist
34 Completion listing extensions.
35 zsh/computil
37 A module with utility builtins needed for the shell function
38 based completion system.
39 zsh/curses
41 curses windowing commands
42 zsh/datetime
44 Some date/time commands and parameters.
45 zsh/db/gdbm
47 Builtins for managing associative array parameters tied to GDBM
48 databases.
49 zsh/deltochar
51 A ZLE function duplicating EMACS' zap-to-char.
52 zsh/example
54 An example of how to write a module.
55 zsh/files
57 Some basic file manipulation commands as builtins.
58 zsh/langinfo
60 Interface to locale information.
61 zsh/mapfile
63 Access to external files via a special associative array.
64 zsh/mathfunc
66 Standard scientific functions for use in mathematical evalua‐
67 tions.
68 zsh/nearcolor
70 Map colours to the nearest colour in the available palette.
71 zsh/newuser
73 Arrange for files for new users to be installed.
74 zsh/parameter
76 Access to internal hash tables via special associative arrays.
77 zsh/pcre
79 Interface to the PCRE library.
80 zsh/param/private
82 Builtins for managing private-scoped parameters in function con‐
83 text.
84 zsh/regex
86 Interface to the POSIX regex library.
87 zsh/sched
89 A builtin that provides a timed execution facility within the
90 shell.
91 zsh/net/socket
93 Manipulation of Unix domain sockets
94 zsh/stat
96 A builtin command interface to the stat system call.
97 zsh/system
99 A builtin interface to various low-level system features.
100 zsh/net/tcp
102 Manipulation of TCP sockets
103 zsh/termcap
105 Interface to the termcap database.
106 zsh/terminfo
108 Interface to the terminfo database.
109 zsh/watch
111 Reporting of login and logout events.
112 zsh/zftp
114 A builtin FTP client.
115 zsh/zle
117 The Zsh Line Editor, including the bindkey and vared builtins.
118 zsh/zleparameter
120 Access to internals of the Zsh Line Editor via parameters.
121 zsh/zprof
123 A module allowing profiling for shell functions.
124 zsh/zpty
126 A builtin for starting a command in a pseudo-terminal.
127 zsh/zselect
129 Block and return when file descriptors are ready.
130 zsh/zutil
132 Some utility builtins, e.g. the one for supporting configuration
133 via styles.
134
136 The zsh/attr module is used for manipulating extended attributes. The
137 -h option causes all commands to operate on symbolic links instead of
138 their targets. The builtins in this module are:
139 zgetattr [ -h ] filename attribute [ parameter ]
141 Get the extended attribute attribute from the specified file‐
142 name. If the optional argument parameter is given, the attribute
143 is set on that parameter instead of being printed to stdout.
144 zsetattr [ -h ] filename attribute value
146 Set the extended attribute attribute on the specified filename
147 to value.
148 zdelattr [ -h ] filename attribute
150 Remove the extended attribute attribute from the specified file‐
151 name.
152 zlistattr [ -h ] filename [ parameter ]
154 List the extended attributes currently set on the specified
155 filename. If the optional argument parameter is given, the list
156 of attributes is set on that parameter instead of being printed
157 to stdout.
158 zgetattr and zlistattr allocate memory dynamically. If the attribute
160 or list of attributes grows between the allocation and the call to get
161 them, they return 2. On all other errors, 1 is returned. This allows
162 the calling function to check for this case and retry.
163
165 The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) capabil‐
166 ity sets. If the operating system does not support this interface, the
167 builtins defined by this module will do nothing. The builtins in this
168 module are:
169 cap [ capabilities ]
171 Change the shell's process capability sets to the specified ca‐
172 pabilities, otherwise display the shell's current capabilities.
173 getcap filename ...
175 This is a built-in implementation of the POSIX standard utility.
176 It displays the capability sets on each specified filename.
177 setcap capabilities filename ...
179 This is a built-in implementation of the POSIX standard utility.
180 It sets the capability sets on each specified filename to the
181 specified capabilities.
182
184 The zsh/clone module makes available one builtin command:
185 clone tty
187 Creates a forked instance of the current shell, attached to the
188 specified tty. In the new shell, the PID, PPID and TTY special
189 parameters are changed appropriately. $! is set to zero in the
190 new shell, and to the new shell's PID in the original shell.
191 The return status of the builtin is zero in both shells if suc‐
193 cessful, and non-zero on error.
194 The target of clone should be an unused terminal, such as an un‐
196 used virtual console or a virtual terminal created by
197 xterm -e sh -c 'trap : INT QUIT TSTP; tty;
199 while :; do sleep 100000000; done'
200 Some words of explanation are warranted about this long xterm
202 command line: when doing clone on a pseudo-terminal, some other
203 session ("session" meant as a unix session group, or SID) is al‐
204 ready owning the terminal. Hence the cloned zsh cannot acquire
205 the pseudo-terminal as a controlling tty. That means two things:
206 • the job control signals will go to the
208 sh-started-by-xterm process group (that's why we disable
209 INT QUIT and TSTP with trap; otherwise the while loop
210 could get suspended or killed)
211 • the cloned shell will have job control disabled, and the
213 job control keys (control-C, control-\ and control-Z)
214 will not work.
215 This does not apply when cloning to an unused vc.
217 Cloning to a used (and unprepared) terminal will result in two
219 processes reading simultaneously from the same terminal, with
220 input bytes going randomly to either process.
221 clone is mostly useful as a shell built-in replacement for
223 openvt.
224
226 The zsh/compctl module makes available two builtin commands. compctl,
227 is the old, deprecated way to control completions for ZLE. See zshcom‐
228 pctl(1). The other builtin command, compcall can be used in user-de‐
229 fined completion widgets, see zshcompwid(1).
230
232 The zsh/complete module makes available several builtin commands which
233 can be used in user-defined completion widgets, see zshcompwid(1).
234
236 The zsh/complist module offers three extensions to completion listings:
237 the ability to highlight matches in such a list, the ability to scroll
238 through long lists and a different style of menu completion.
239 Colored completion listings
241 Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS is set and the
242 zsh/complist module is loaded or linked into the shell, completion
243 lists will be colored. Note, however, that complist will not automati‐
244 cally be loaded if it is not linked in: on systems with dynamic load‐
245 ing, `zmodload zsh/complist' is required.
246 The parameters ZLS_COLORS and ZLS_COLOURS describe how matches are
248 highlighted. To turn on highlighting an empty value suffices, in which
249 case all the default values given below will be used. The format of
250 the value of these parameters is the same as used by the GNU version of
251 the ls command: a colon-separated list of specifications of the form
252 `name=value'. The name may be one of the following strings, most of
253 which specify file types for which the value will be used. The strings
254 and their default values are:
255 no 0 for normal text (i.e. when displaying something other than a
257 matched file)
258 fi 0 for regular files
260 di 32 for directories
262 ln 36 for symbolic links. If this has the special value target, sym‐
264 bolic links are dereferenced and the target file used to deter‐
265 mine the display format.
266 pi 31 for named pipes (FIFOs)
268 so 33 for sockets
270 bd 44;37
272 for block devices
273 cd 44;37
275 for character devices
276 or none
278 for a symlink to nonexistent file (default is the value defined
279 for ln)
280 mi none
282 for a non-existent file (default is the value defined for fi);
283 this code is currently not used
284 su 37;41
286 for files with setuid bit set
287 sg 30;43
289 for files with setgid bit set
290 tw 30;42
292 for world writable directories with sticky bit set
293 ow 34;43
295 for world writable directories without sticky bit set
296 sa none
298 for files with an associated suffix alias; this is only tested
299 after specific suffixes, as described below
300 st 37;44
302 for directories with sticky bit set but not world writable
303 ex 35 for executable files
305 lc \e[ for the left code (see below)
307 rc m for the right code
309 tc 0 for the character indicating the file type printed after file‐
311 names if the LIST_TYPES option is set
312 sp 0 for the spaces printed after matches to align the next column
314 ec none
316 for the end code
317 Apart from these strings, the name may also be an asterisk (`*') fol‐
319 lowed by any string. The value given for such a string will be used for
320 all files whose name ends with the string. The name may also be an
321 equals sign (`=') followed by a pattern; the EXTENDED_GLOB option will
322 be turned on for evaluation of the pattern. The value given for this
323 pattern will be used for all matches (not just filenames) whose display
324 string are matched by the pattern. Definitions for the form with the
325 leading equal sign take precedence over the values defined for file
326 types, which in turn take precedence over the form with the leading as‐
327 terisk (file extensions).
328 The leading-equals form also allows different parts of the displayed
330 strings to be colored differently. For this, the pattern has to use
331 the `(#b)' globbing flag and pairs of parentheses surrounding the parts
332 of the strings that are to be colored differently. In this case the
333 value may consist of more than one color code separated by equal signs.
334 The first code will be used for all parts for which no explicit code is
335 specified and the following codes will be used for the parts matched by
336 the sub-patterns in parentheses. For example, the specification
337 `=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least
338 two characters long and will use the code `3' for the first character,
339 `7' for the last character and `0' for the rest.
340 All three forms of name may be preceded by a pattern in parentheses.
342 If this is given, the value will be used only for matches in groups
343 whose names are matched by the pattern given in the parentheses. For
344 example, `(g*)m*=43' highlights all matches beginning with `m' in
345 groups whose names begin with `g' using the color code `43'. In case
346 of the `lc', `rc', and `ec' codes, the group pattern is ignored.
347 Note also that all patterns are tried in the order in which they appear
349 in the parameter value until the first one matches which is then used.
350 Patterns may be matched against completions, descriptions (possibly
351 with spaces appended for padding), or lines consisting of a completion
352 followed by a description. For consistent coloring it may be necessary
353 to use more than one pattern or a pattern with backreferences.
354 When printing a match, the code prints the value of lc, the value for
356 the file-type or the last matching specification with a `*', the value
357 of rc, the string to display for the match itself, and then the value
358 of ec if that is defined or the values of lc, no, and rc if ec is not
359 defined.
360 The default values are ISO 6429 (ANSI) compliant and can be used on
362 vt100 compatible terminals such as xterms. On monochrome terminals the
363 default values will have no visible effect. The colors function from
364 the contribution can be used to get associative arrays containing the
365 codes for ANSI terminals (see the section `Other Functions' in zshcon‐
366 trib(1)). For example, after loading colors, one could use
367 `$color[red]' to get the code for foreground color red and
368 `$color[bg-green]' for the code for background color green.
369 If the completion system invoked by compinit is used, these parameters
371 should not be set directly because the system controls them itself.
372 Instead, the list-colors style should be used (see the section `Comple‐
373 tion System Configuration' in zshcompsys(1)).
374 Scrolling in completion listings
376 To enable scrolling through a completion list, the LISTPROMPT parameter
377 must be set. Its value will be used as the prompt; if it is the empty
378 string, a default prompt will be used. The value may contain escapes
379 of the form `%x'. It supports the escapes `%B', `%b', `%S', `%s',
380 `%U', `%u', `%F', `%f', `%K', `%k' and `%{...%}' used also in shell
381 prompts as well as three pairs of additional sequences: a `%l' or `%L'
382 is replaced by the number of the last line shown and the total number
383 of lines in the form `number/total'; a `%m' or `%M' is replaced with
384 the number of the last match shown and the total number of matches; and
385 `%p' or `%P' is replaced with `Top', `Bottom' or the position of the
386 first line shown in percent of the total number of lines, respectively.
387 In each of these cases the form with the uppercase letter will be re‐
388 placed with a string of fixed width, padded to the right with spaces,
389 while the lowercase form will not be padded.
390 If the parameter LISTPROMPT is set, the completion code will not ask if
392 the list should be shown. Instead it immediately starts displaying the
393 list, stopping after the first screenful, showing the prompt at the
394 bottom, waiting for a keypress after temporarily switching to the
395 listscroll keymap. Some of the zle functions have a special meaning
396 while scrolling lists:
397 send-break
399 stops listing discarding the key pressed
400 accept-line, down-history, down-line-or-history
402 down-line-or-search, vi-down-line-or-history
403 scrolls forward one line
404 complete-word, menu-complete, expand-or-complete
406 expand-or-complete-prefix, menu-complete-or-expand
407 scrolls forward one screenful
408 accept-search
410 stop listing but take no other action
411 Every other character stops listing and immediately processes the key
413 as usual. Any key that is not bound in the listscroll keymap or that
414 is bound to undefined-key is looked up in the keymap currently se‐
415 lected.
416 As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not
418 be set directly when using the shell function based completion system.
419 Instead, the list-prompt style should be used.
420 Menu selection
422 The zsh/complist module also offers an alternative style of selecting
423 matches from a list, called menu selection, which can be used if the
424 shell is set up to return to the last prompt after showing a completion
425 list (see the ALWAYS_LAST_PROMPT option in zshoptions(1)).
426 Menu selection can be invoked directly by the widget menu-select de‐
428 fined by this module. This is a standard ZLE widget that can be bound
429 to a key in the usual way as described in zshzle(1).
430 Alternatively, the parameter MENUSELECT can be set to an integer, which
432 gives the minimum number of matches that must be present before menu
433 selection is automatically turned on. This second method requires that
434 menu completion be started, either directly from a widget such as
435 menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU
436 being set. If MENUSELECT is set, but is 0, 1 or empty, menu selection
437 will always be started during an ambiguous menu completion.
438 When using the completion system based on shell functions, the MENUSE‐
440 LECT parameter should not be used (like the ZLS_COLORS and ZLS_COLOURS
441 parameters described above). Instead, the menu style should be used
442 with the select=... keyword.
443 After menu selection is started, the matches will be listed. If there
445 are more matches than fit on the screen, only the first screenful is
446 shown. The matches to insert into the command line can be selected
447 from this list. In the list one match is highlighted using the value
448 for ma from the ZLS_COLORS or ZLS_COLOURS parameter. The default value
449 for this is `7' which forces the selected match to be highlighted using
450 standout mode on a vt100-compatible terminal. If neither ZLS_COLORS
451 nor ZLS_COLOURS is set, the same terminal control sequence as for the
452 `%S' escape in prompts is used.
453 If there are more matches than fit on the screen and the parameter
455 MENUPROMPT is set, its value will be shown below the matches. It sup‐
456 ports the same escape sequences as LISTPROMPT, but the number of the
457 match or line shown will be that of the one where the mark is placed.
458 If its value is the empty string, a default prompt will be used.
459 The MENUSCROLL parameter can be used to specify how the list is
461 scrolled. If the parameter is unset, this is done line by line, if it
462 is set to `0' (zero), the list will scroll half the number of lines of
463 the screen. If the value is positive, it gives the number of lines to
464 scroll and if it is negative, the list will be scrolled the number of
465 lines of the screen minus the (absolute) value.
466 As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parameters, neither
468 MENUPROMPT nor MENUSCROLL should be set directly when using the shell
469 function based completion system. Instead, the select-prompt and se‐
470 lect-scroll styles should be used.
471 The completion code sometimes decides not to show all of the matches in
473 the list. These hidden matches are either matches for which the com‐
474 pletion function which added them explicitly requested that they not
475 appear in the list (using the -n option of the compadd builtin command)
476 or they are matches which duplicate a string already in the list (be‐
477 cause they differ only in things like prefixes or suffixes that are not
478 displayed). In the list used for menu selection, however, even these
479 matches are shown so that it is possible to select them. To highlight
480 such matches the hi and du capabilities in the ZLS_COLORS and
481 ZLS_COLOURS parameters are supported for hidden matches of the first
482 and second kind, respectively.
483 Selecting matches is done by moving the mark around using the zle move‐
485 ment functions. When not all matches can be shown on the screen at the
486 same time, the list will scroll up and down when crossing the top or
487 bottom line. The following zle functions have special meaning during
488 menu selection. Note that the following always perform the same task
489 within the menu selection map and cannot be replaced by user defined
490 widgets, nor can the set of functions be extended:
491 accept-line, accept-search
493 accept the current match and leave menu selection (but do not
494 cause the command line to be accepted)
495 send-break
497 leaves menu selection and restores the previous contents of the
498 command line
499 redisplay, clear-screen
501 execute their normal function without leaving menu selection
502 accept-and-hold, accept-and-menu-complete
504 accept the currently inserted match and continue selection al‐
505 lowing to select the next match to insert into the line
506 accept-and-infer-next-history
508 accepts the current match and then tries completion with menu
509 selection again; in the case of files this allows one to select
510 a directory and immediately attempt to complete files in it; if
511 there are no matches, a message is shown and one can use undo to
512 go back to completion on the previous level, every other key
513 leaves menu selection (including the other zle functions which
514 are otherwise special during menu selection)
515 undo removes matches inserted during the menu selection by one of the
517 three functions before
518 down-history, down-line-or-history
520 vi-down-line-or-history, down-line-or-search
521 moves the mark one line down
522 up-history, up-line-or-history
524 vi-up-line-or-history, up-line-or-search
525 moves the mark one line up
526 forward-char, vi-forward-char
528 moves the mark one column right
529 backward-char, vi-backward-char
531 moves the mark one column left
532 forward-word, vi-forward-word
534 vi-forward-word-end, emacs-forward-word
535 moves the mark one screenful down
536 backward-word, vi-backward-word, emacs-backward-word
538 moves the mark one screenful up
539 vi-forward-blank-word, vi-forward-blank-word-end
541 moves the mark to the first line of the next group of matches
542 vi-backward-blank-word
544 moves the mark to the last line of the previous group of matches
545 beginning-of-history
547 moves the mark to the first line
548 end-of-history
550 moves the mark to the last line
551 beginning-of-buffer-or-history, beginning-of-line
553 beginning-of-line-hist, vi-beginning-of-line
554 moves the mark to the leftmost column
555 end-of-buffer-or-history, end-of-line
557 end-of-line-hist, vi-end-of-line
558 moves the mark to the rightmost column
559 complete-word, menu-complete, expand-or-complete
561 expand-or-complete-prefix, menu-expand-or-complete
562 moves the mark to the next match
563 reverse-menu-complete
565 moves the mark to the previous match
566 vi-insert
568 this toggles between normal and interactive mode; in interactive
569 mode the keys bound to self-insert and self-insert-unmeta insert
570 into the command line as in normal editing mode but without
571 leaving menu selection; after each character completion is tried
572 again and the list changes to contain only the new matches; the
573 completion widgets make the longest unambiguous string be in‐
574 serted in the command line and undo and backward-delete-char go
575 back to the previous set of matches
576 history-incremental-search-forward
578 history-incremental-search-backward
579 this starts incremental searches in the list of completions dis‐
580 played; in this mode, accept-line only leaves incremental
581 search, going back to the normal menu selection mode
582 All movement functions wrap around at the edges; any other zle function
584 not listed leaves menu selection and executes that function. It is
585 possible to make widgets in the above list do the same by using the
586 form of the widget with a `.' in front. For example, the widget `.ac‐
587 cept-line' has the effect of leaving menu selection and accepting the
588 entire command line.
589 During this selection the widget uses the keymap menuselect. Any key
591 that is not defined in this keymap or that is bound to undefined-key is
592 looked up in the keymap currently selected. This is used to ensure
593 that the most important keys used during selection (namely the cursor
594 keys, return, and TAB) have sensible defaults. However, keys in the
595 menuselect keymap can be modified directly using the bindkey builtin
596 command (see zshmodules(1)). For example, to make the return key leave
597 menu selection without accepting the match currently selected one could
598 call
599 bindkey -M menuselect '^M' send-break
601 after loading the zsh/complist module.
603
605 The zsh/computil module adds several builtin commands that are used by
606 some of the completion functions in the completion system based on
607 shell functions (see zshcompsys(1) ). Except for compquote these
608 builtin commands are very specialised and thus not very interesting
609 when writing your own completion functions. In summary, these builtin
610 commands are:
611 comparguments
613 This is used by the _arguments function to do the argument and
614 command line parsing. Like compdescribe it has an option -i to
615 do the parsing and initialize some internal state and various
616 options to access the state information to decide what should be
617 completed.
618 compdescribe
620 This is used by the _describe function to build the displays for
621 the matches and to get the strings to add as matches with their
622 options. On the first call one of the options -i or -I should
623 be supplied as the first argument. In the first case, display
624 strings without the descriptions will be generated, in the sec‐
625 ond case, the string used to separate the matches from their de‐
626 scriptions must be given as the second argument and the descrip‐
627 tions (if any) will be shown. All other arguments are like the
628 definition arguments to _describe itself.
629 Once compdescribe has been called with either the -i or the -I
631 option, it can be repeatedly called with the -g option and the
632 names of four parameters as its arguments. This will step
633 through the different sets of matches and store the value of
634 compstate[list] in the first scalar, the options for compadd in
635 the second array, the matches in the third array, and the
636 strings to be displayed in the completion listing in the fourth
637 array. The arrays may then be directly given to compadd to reg‐
638 ister the matches with the completion code.
639 compfiles
641 Used by the _path_files function to optimize complex recursive
642 filename generation (globbing). It does three things. With the
643 -p and -P options it builds the glob patterns to use, including
644 the paths already handled and trying to optimize the patterns
645 with respect to the prefix and suffix from the line and the
646 match specification currently used. The -i option does the di‐
647 rectory tests for the ignore-parents style and the -r option
648 tests if a component for some of the matches are equal to the
649 string on the line and removes all other matches if that is
650 true.
651 compgroups
653 Used by the _tags function to implement the internals of the
654 group-order style. This only takes its arguments as names of
655 completion groups and creates the groups for it (all six types:
656 sorted and unsorted, both without removing duplicates, with re‐
657 moving all duplicates and with removing consecutive duplicates).
658 compquote [ -p ] names ...
660 There may be reasons to write completion functions that have to
661 add the matches using the -Q option to compadd and perform quot‐
662 ing themselves. Instead of interpreting the first character of
663 the all_quotes key of the compstate special association and us‐
664 ing the q flag for parameter expansions, one can use this
665 builtin command. The arguments are the names of scalar or array
666 parameters and the values of these parameters are quoted as
667 needed for the innermost quoting level. If the -p option is
668 given, quoting is done as if there is some prefix before the
669 values of the parameters, so that a leading equal sign will not
670 be quoted.
671 The return status is non-zero in case of an error and zero oth‐
673 erwise.
674 comptags
676 comptry
677 These implement the internals of the tags mechanism.
678 compvalues
680 Like comparguments, but for the _values function.
681
683 The zsh/curses module makes available one builtin command and various
684 parameters.
685 Builtin
687 zcurses init
688 zcurses end
689 zcurses addwin targetwin nlines ncols begin_y begin_x [ parentwin ]
690 zcurses delwin targetwin
691 zcurses refresh [ targetwin ... ]
692 zcurses touch targetwin ...
693 zcurses move targetwin new_y new_x
694 zcurses clear targetwin [ redraw | eol | bot ]
695 zcurses position targetwin array
696 zcurses char targetwin character
697 zcurses string targetwin string
698 zcurses border targetwin border
699 zcurses attr targetwin [ [+|-]attribute | fg_col/bg_col ] [...]
700 zcurses bg targetwin [ [+|-]attribute | fg_col/bg_col | @char ] [...]
701 zcurses scroll targetwin [ on | off | [+|-]lines ]
702 zcurses input targetwin [ param [ kparam [ mparam ] ] ]
703 zcurses mouse [ delay num | [+|-]motion ]
704 zcurses timeout targetwin intval
705 zcurses querychar targetwin [ param ]
706 zcurses resize height width [ endwin | nosave | endwin_nosave ]
707 Manipulate curses windows. All uses of this command should be
708 bracketed by `zcurses init' to initialise use of curses, and
709 `zcurses end' to end it; omitting `zcurses end' can cause the
710 terminal to be in an unwanted state.
711 The subcommand addwin creates a window with nlines lines and
713 ncols columns. Its upper left corner will be placed at row be‐
714 gin_y and column begin_x of the screen. targetwin is a string
715 and refers to the name of a window that is not currently as‐
716 signed. Note in particular the curses convention that vertical
717 values appear before horizontal values.
718 If addwin is given an existing window as the final argument, the
720 new window is created as a subwindow of parentwin. This differs
721 from an ordinary new window in that the memory of the window
722 contents is shared with the parent's memory. Subwindows must be
723 deleted before their parent. Note that the coordinates of sub‐
724 windows are relative to the screen, not the parent, as with
725 other windows.
726 Use the subcommand delwin to delete a window created with ad‐
728 dwin. Note that end does not implicitly delete windows, and
729 that delwin does not erase the screen image of the window.
730 The window corresponding to the full visible screen is called
732 stdscr; it always exists after `zcurses init' and cannot be
733 delete with delwin.
734 The subcommand refresh will refresh window targetwin; this is
736 necessary to make any pending changes (such as characters you
737 have prepared for output with char) visible on the screen. re‐
738 fresh without an argument causes the screen to be cleared and
739 redrawn. If multiple windows are given, the screen is updated
740 once at the end.
741 The subcommand touch marks the targetwins listed as changed.
743 This is necessary before refreshing windows if a window that was
744 in front of another window (which may be stdscr) is deleted.
745 The subcommand move moves the cursor position in targetwin to
747 new coordinates new_y and new_x. Note that the subcommand
748 string (but not the subcommand char) advances the cursor posi‐
749 tion over the characters added.
750 The subcommand clear erases the contents of targetwin. One (and
752 no more than one) of three options may be specified. With the
753 option redraw, in addition the next refresh of targetwin will
754 cause the screen to be cleared and repainted. With the option
755 eol, targetwin is only cleared to the end of the current cursor
756 line. With the option bot, targetwin is cleared to the end of
757 the window, i.e everything to the right and below the cursor is
758 cleared.
759 The subcommand position writes various positions associated with
761 targetwin into the array named array. These are, in order:
762 - The y and x coordinates of the cursor relative to the top
763 left of targetwin
764 - The y and x coordinates of the top left of targetwin on
765 the screen
766 - The size of targetwin in y and x dimensions.
767 Outputting characters and strings are achieved by char and
769 string respectively.
770 To draw a border around window targetwin, use border. Note that
772 the border is not subsequently handled specially: in other
773 words, the border is simply a set of characters output at the
774 edge of the window. Hence it can be overwritten, can scroll off
775 the window, etc.
776 The subcommand attr will set targetwin's attributes or fore‐
778 ground/background color pair for any successive character out‐
779 put. Each attribute given on the line may be prepended by a +
780 to set or a - to unset that attribute; + is assumed if absent.
781 The attributes supported are blink, bold, dim, reverse, stand‐
782 out, and underline.
783 Each fg_col/bg_col attribute (to be read as `fg_col on bg_col')
785 sets the foreground and background color for character output.
786 The color default is sometimes available (in particular if the
787 library is ncurses), specifying the foreground or background
788 color with which the terminal started. The color pair de‐
789 fault/default is always available. To use more than the 8 named
790 colors (red, green, etc.) construct the fg_col/bg_col pairs
791 where fg_col and bg_col are decimal integers, e.g 128/200. The
792 maximum color value is 254 if the terminal supports 256 colors.
793 bg overrides the color and other attributes of all characters in
795 the window. Its usual use is to set the background initially,
796 but it will overwrite the attributes of any characters at the
797 time when it is called. In addition to the arguments allowed
798 with attr, an argument @char specifies a character to be shown
799 in otherwise blank areas of the window. Owing to limitations of
800 curses this cannot be a multibyte character (use of ASCII char‐
801 acters only is recommended). As the specified set of attributes
802 override the existing background, turning attributes off in the
803 arguments is not useful, though this does not cause an error.
804 The subcommand scroll can be used with on or off to enabled or
806 disable scrolling of a window when the cursor would otherwise
807 move below the window due to typing or output. It can also be
808 used with a positive or negative integer to scroll the window up
809 or down the given number of lines without changing the current
810 cursor position (which therefore appears to move in the opposite
811 direction relative to the window). In the second case, if
812 scrolling is off it is temporarily turned on to allow the window
813 to be scrolled.
814 The subcommand input reads a single character from the window
816 without echoing it back. If param is supplied the character is
817 assigned to the parameter param, else it is assigned to the pa‐
818 rameter REPLY.
819 If both param and kparam are supplied, the key is read in `key‐
821 pad' mode. In this mode special keys such as function keys and
822 arrow keys return the name of the key in the parameter kparam.
823 The key names are the macros defined in the curses.h or
824 ncurses.h with the prefix `KEY_' removed; see also the descrip‐
825 tion of the parameter zcurses_keycodes below. Other keys cause
826 a value to be set in param as before. On a successful return
827 only one of param or kparam contains a non-empty string; the
828 other is set to an empty string.
829 If mparam is also supplied, input attempts to handle mouse in‐
831 put. This is only available with the ncurses library; mouse
832 handling can be detected by checking for the exit status of
833 `zcurses mouse' with no arguments. If a mouse button is clicked
834 (or double- or triple-clicked, or pressed or released with a
835 configurable delay from being clicked) then kparam is set to the
836 string MOUSE, and mparam is set to an array consisting of the
837 following elements:
838 - An identifier to discriminate different input devices;
839 this is only rarely useful.
840 - The x, y and z coordinates of the mouse click relative to
841 the full screen, as three elements in that order (i.e.
842 the y coordinate is, unusually, after the x coordinate).
843 The z coordinate is only available for a few unusual in‐
844 put devices and is otherwise set to zero.
845 - Any events that occurred as separate items; usually there
846 will be just one. An event consists of PRESSED, RE‐
847 LEASED, CLICKED, DOUBLE_CLICKED or TRIPLE_CLICKED fol‐
848 lowed immediately (in the same element) by the number of
849 the button.
850 - If the shift key was pressed, the string SHIFT.
851 - If the control key was pressed, the string CTRL.
852 - If the alt key was pressed, the string ALT.
853 Not all mouse events may be passed through to the terminal win‐
855 dow; most terminal emulators handle some mouse events them‐
856 selves. Note that the ncurses manual implies that using input
857 both with and without mouse handling may cause the mouse cursor
858 to appear and disappear.
859 The subcommand mouse can be used to configure the use of the
861 mouse. There is no window argument; mouse options are global.
862 `zcurses mouse' with no arguments returns status 0 if mouse han‐
863 dling is possible, else status 1. Otherwise, the possible argu‐
864 ments (which may be combined on the same command line) are as
865 follows. delay num sets the maximum delay in milliseconds be‐
866 tween press and release events to be considered as a click; the
867 value 0 disables click resolution, and the default is one sixth
868 of a second. motion proceeded by an optional `+' (the default)
869 or - turns on or off reporting of mouse motion in addition to
870 clicks, presses and releases, which are always reported. How‐
871 ever, it appears reports for mouse motion are not currently im‐
872 plemented.
873 The subcommand timeout specifies a timeout value for input from
875 targetwin. If intval is negative, `zcurses input' waits indefi‐
876 nitely for a character to be typed; this is the default. If
877 intval is zero, `zcurses input' returns immediately; if there is
878 typeahead it is returned, else no input is done and status 1 is
879 returned. If intval is positive, `zcurses input' waits intval
880 milliseconds for input and if there is none at the end of that
881 period returns status 1.
882 The subcommand querychar queries the character at the current
884 cursor position. The return values are stored in the array
885 named param if supplied, else in the array reply. The first
886 value is the character (which may be a multibyte character if
887 the system supports them); the second is the color pair in the
888 usual fg_col/bg_col notation, or 0 if color is not supported.
889 Any attributes other than color that apply to the character, as
890 set with the subcommand attr, appear as additional elements.
891 The subcommand resize resizes stdscr and all windows to given
893 dimensions (windows that stick out from the new dimensions are
894 resized down). The underlying curses extension (resize_term
895 call) can be unavailable. To verify, zeroes can be used for
896 height and width. If the result of the subcommand is 0, re‐
897 size_term is available (2 otherwise). Tests show that resizing
898 can be normally accomplished by calling zcurses end and zcurses
899 refresh. The resize subcommand is provided for versatility. Mul‐
900 tiple system configurations have been checked and zcurses end
901 and zcurses refresh are still needed for correct terminal state
902 after resize. To invoke them with resize, use endwin argument.
903 Using nosave argument will cause new terminal state to not be
904 saved internally by zcurses. This is also provided for versatil‐
905 ity and should normally be not needed.
906 Parameters
908 ZCURSES_COLORS
909 Readonly integer. The maximum number of colors the terminal
910 supports. This value is initialised by the curses library and
911 is not available until the first time zcurses init is run.
912 ZCURSES_COLOR_PAIRS
914 Readonly integer. The maximum number of color pairs
915 fg_col/bg_col that may be defined in `zcurses attr' commands;
916 note this limit applies to all color pairs that have been used
917 whether or not they are currently active. This value is ini‐
918 tialised by the curses library and is not available until the
919 first time zcurses init is run.
920 zcurses_attrs
922 Readonly array. The attributes supported by zsh/curses; avail‐
923 able as soon as the module is loaded.
924 zcurses_colors
926 Readonly array. The colors supported by zsh/curses; available
927 as soon as the module is loaded.
928 zcurses_keycodes
930 Readonly array. The values that may be returned in the second
931 parameter supplied to `zcurses input' in the order in which they
932 are defined internally by curses. Not all function keys are
933 listed, only F0; curses reserves space for F0 up to F63.
934 zcurses_windows
936 Readonly array. The current list of windows, i.e. all windows
937 that have been created with `zcurses addwin' and not removed
938 with `zcurses delwin'.
939
941 The zsh/datetime module makes available one builtin command:
942 strftime [ -s scalar | -n ] format [ epochtime [ nanoseconds ] ]
944 strftime -r [ -q ] [ -s scalar | -n ] format timestring
945 Output the date in the format specified. With no epochtime, the
946 current system date/time is used; optionally, epochtime may be
947 used to specify the number of seconds since the epoch, and
948 nanoseconds may additionally be used to specify the number of
949 nanoseconds past the second (otherwise that number is assumed to
950 be 0). See strftime(3) for details. The zsh extensions de‐
951 scribed in the section EXPANSION OF PROMPT SEQUENCES in zsh‐
952 misc(1) are also available.
953 -n Suppress printing a newline after the formatted string.
955 -q Run quietly; suppress printing of all error messages de‐
957 scribed below. Errors for invalid epochtime values are
958 always printed.
959 -r With the option -r (reverse), use format to parse the in‐
961 put string timestring and output the number of seconds
962 since the epoch at which the time occurred. The parsing
963 is implemented by the system function strptime; see strp‐
964 time(3). This means that zsh format extensions are not
965 available, but for reverse lookup they are not required.
966 In most implementations of strftime any timezone in the
968 timestring is ignored and the local timezone declared by
969 the TZ environment variable is used; other parameters are
970 set to zero if not present.
971 If timestring does not match format the command returns
973 status 1 and prints an error message. If timestring
974 matches format but not all characters in timestring were
975 used, the conversion succeeds but also prints an error
976 message.
977 If either of the system functions strptime or mktime is
979 not available, status 2 is returned and an error message
980 is printed.
981 -s scalar
983 Assign the date string (or epoch time in seconds if -r is
984 given) to scalar instead of printing it.
985 Note that depending on the system's declared integral time type,
987 strftime may produce incorrect results for epoch times greater
988 than 2147483647 which corresponds to 2038-01-19 03:14:07 +0000.
989 The zsh/datetime module makes available several parameters; all are
991 readonly:
992 EPOCHREALTIME
994 A floating point value representing the number of seconds since
995 the epoch. The notional accuracy is to nanoseconds if the
996 clock_gettime call is available and to microseconds otherwise,
997 but in practice the range of double precision floating point and
998 shell scheduling latencies may be significant effects.
999 EPOCHSECONDS
1001 An integer value representing the number of seconds since the
1002 epoch.
1003 epochtime
1005 An array value containing the number of seconds since the epoch
1006 in the first element and the remainder of the time since the
1007 epoch in nanoseconds in the second element. To ensure the two
1008 elements are consistent the array should be copied or otherwise
1009 referenced as a single substitution before the values are used.
1010 The following idiom may be used:
1011 for secs nsecs in $epochtime; do
1013 ...
1014 done
1015
1017 The zsh/db/gdbm module is used to create "tied" associative arrays that
1018 interface to database files. If the GDBM interface is not available,
1019 the builtins defined by this module will report an error. This module
1020 is also intended as a prototype for creating additional database inter‐
1021 faces, so the ztie builtin may move to a more generic module in the fu‐
1022 ture.
1023 The builtins in this module are:
1025 ztie -d db/gdbm -f filename [ -r ] arrayname
1027 Open the GDBM database identified by filename and, if success‐
1028 ful, create the associative array arrayname linked to the file.
1029 To create a local tied array, the parameter must first be de‐
1030 clared, so commands similar to the following would be executed
1031 inside a function scope:
1032 local -A sampledb
1034 ztie -d db/gdbm -f sample.gdbm sampledb
1035 The -r option opens the database file for reading only, creating
1037 a parameter with the readonly attribute. Without this option,
1038 using `ztie' on a file for which the user does not have write
1039 permission is an error. If writable, the database is opened
1040 synchronously so fields changed in arrayname are immediately
1041 written to filename.
1042 Changes to the file modes filename after it has been opened do
1044 not alter the state of arrayname, but `typeset -r arrayname'
1045 works as expected.
1046 zuntie [ -u ] arrayname ...
1048 Close the GDBM database associated with each arrayname and then
1049 unset the parameter. The -u option forces an unset of parame‐
1050 ters made readonly with `ztie -r'.
1051 This happens automatically if the parameter is explicitly unset
1053 or its local scope (function) ends. Note that a readonly param‐
1054 eter may not be explicitly unset, so the only way to unset a
1055 global parameter created with `ztie -r' is to use `zuntie -u'.
1056 zgdbmpath parametername
1058 Put path to database file assigned to parametername into REPLY
1059 scalar.
1060 zgdbm_tied
1062 Array holding names of all tied parameters.
1063 The fields of an associative array tied to GDBM are neither cached nor
1065 otherwise stored in memory, they are read from or written to the data‐
1066 base on each reference. Thus, for example, the values in a readonly
1067 array may be changed by a second writer of the same database file.
1068
1070 The zsh/deltochar module makes available two ZLE functions:
1071 delete-to-char
1073 Read a character from the keyboard, and delete from the cursor
1074 position up to and including the next (or, with repeat count n,
1075 the nth) instance of that character. Negative repeat counts
1076 mean delete backwards.
1077 zap-to-char
1079 This behaves like delete-to-char, except that the final occur‐
1080 rence of the character itself is not deleted.
1081
1083 The zsh/example module makes available one builtin command:
1084 example [ -flags ] [ args ... ]
1086 Displays the flags and arguments it is invoked with.
1087 The purpose of the module is to serve as an example of how to write a
1089 module.
1090
1092 The zsh/files module makes available some common commands for file ma‐
1093 nipulation as builtins; these commands are probably not needed for many
1094 normal situations but can be useful in emergency recovery situations
1095 with constrained resources. The commands do not implement all features
1096 now required by relevant standards committees.
1097 For all commands, a variant beginning zf_ is also available and loaded
1099 automatically. Using the features capability of zmodload will let you
1100 load only those names you want. Note that it's possible to load only
1101 the builtins with zsh-specific names using the following command:
1102 zmodload -m -F zsh/files b:zf_\*
1104 The commands loaded by default are:
1106 chgrp [ -hRs ] group filename ...
1108 Changes group of files specified. This is equivalent to chown
1109 with a user-spec argument of `:group'.
1110 chmod [ -Rs ] mode filename ...
1112 Changes mode of files specified.
1113 The specified mode must be in octal.
1115 The -R option causes chmod to recursively descend into directo‐
1117 ries, changing the mode of all files in the directory after
1118 changing the mode of the directory itself.
1119 The -s option is a zsh extension to chmod functionality. It en‐
1121 ables paranoid behaviour, intended to avoid security problems
1122 involving a chmod being tricked into affecting files other than
1123 the ones intended. It will refuse to follow symbolic links, so
1124 that (for example) ``chmod 600 /tmp/foo/passwd'' can't acciden‐
1125 tally chmod /etc/passwd if /tmp/foo happens to be a link to
1126 /etc. It will also check where it is after leaving directories,
1127 so that a recursive chmod of a deep directory tree can't end up
1128 recursively chmoding /usr as a result of directories being moved
1129 up the tree.
1130 chown [ -hRs ] user-spec filename ...
1132 Changes ownership and group of files specified.
1133 The user-spec can be in four forms:
1135 user change owner to user; do not change group
1137 user:: change owner to user; do not change group
1138 user: change owner to user; change group to user's primary
1139 group
1140 user:group
1141 change owner to user; change group to group
1142 :group do not change owner; change group to group
1143 In each case, the `:' may instead be a `.'. The rule is that if
1145 there is a `:' then the separator is `:', otherwise if there is
1146 a `.' then the separator is `.', otherwise there is no separa‐
1147 tor.
1148 Each of user and group may be either a username (or group name,
1150 as appropriate) or a decimal user ID (group ID). Interpretation
1151 as a name takes precedence, if there is an all-numeric username
1152 (or group name).
1153 If the target is a symbolic link, the -h option causes chown to
1155 set the ownership of the link instead of its target.
1156 The -R option causes chown to recursively descend into directo‐
1158 ries, changing the ownership of all files in the directory after
1159 changing the ownership of the directory itself.
1160 The -s option is a zsh extension to chown functionality. It en‐
1162 ables paranoid behaviour, intended to avoid security problems
1163 involving a chown being tricked into affecting files other than
1164 the ones intended. It will refuse to follow symbolic links, so
1165 that (for example) ``chown luser /tmp/foo/passwd'' can't acci‐
1166 dentally chown /etc/passwd if /tmp/foo happens to be a link to
1167 /etc. It will also check where it is after leaving directories,
1168 so that a recursive chown of a deep directory tree can't end up
1169 recursively chowning /usr as a result of directories being moved
1170 up the tree.
1171 ln [ -dfhins ] filename dest
1173 ln [ -dfhins ] filename ... dir
1174 Creates hard (or, with -s, symbolic) links. In the first form,
1175 the specified destination is created, as a link to the specified
1176 filename. In the second form, each of the filenames is taken in
1177 turn, and linked to a pathname in the specified directory that
1178 has the same last pathname component.
1179 Normally, ln will not attempt to create hard links to directo‐
1181 ries. This check can be overridden using the -d option. Typi‐
1182 cally only the super-user can actually succeed in creating hard
1183 links to directories. This does not apply to symbolic links in
1184 any case.
1185 By default, existing files cannot be replaced by links. The -i
1187 option causes the user to be queried about replacing existing
1188 files. The -f option causes existing files to be silently
1189 deleted, without querying. -f takes precedence.
1190 The -h and -n options are identical and both exist for compati‐
1192 bility; either one indicates that if the target is a symlink
1193 then it should not be dereferenced. Typically this is used in
1194 combination with -sf so that if an existing link points to a di‐
1195 rectory then it will be removed, instead of followed. If this
1196 option is used with multiple filenames and the target is a sym‐
1197 bolic link pointing to a directory then the result is an error.
1198 mkdir [ -p ] [ -m mode ] dir ...
1200 Creates directories. With the -p option, non-existing parent
1201 directories are first created if necessary, and there will be no
1202 complaint if the directory already exists. The -m option can be
1203 used to specify (in octal) a set of file permissions for the
1204 created directories, otherwise mode 777 modified by the current
1205 umask (see umask(2)) is used.
1206 mv [ -fi ] filename dest
1208 mv [ -fi ] filename ... dir
1209 Moves files. In the first form, the specified filename is moved
1210 to the specified destination. In the second form, each of the
1211 filenames is taken in turn, and moved to a pathname in the spec‐
1212 ified directory that has the same last pathname component.
1213 By default, the user will be queried before replacing any file
1215 that the user cannot write to, but writable files will be
1216 silently removed. The -i option causes the user to be queried
1217 about replacing any existing files. The -f option causes any
1218 existing files to be silently deleted, without querying. -f
1219 takes precedence.
1220 Note that this mv will not move files across devices. Histori‐
1222 cal versions of mv, when actual renaming is impossible, fall
1223 back on copying and removing files; if this behaviour is de‐
1224 sired, use cp and rm manually. This may change in a future ver‐
1225 sion.
1226 rm [ -dfiRrs ] filename ...
1228 Removes files and directories specified.
1229 Normally, rm will not remove directories (except with the -R or
1231 -r options). The -d option causes rm to try removing directo‐
1232 ries with unlink (see unlink(2)), the same method used for
1233 files. Typically only the super-user can actually succeed in
1234 unlinking directories in this way. -d takes precedence over -R
1235 and -r.
1236 By default, the user will be queried before removing any file
1238 that the user cannot write to, but writable files will be
1239 silently removed. The -i option causes the user to be queried
1240 about removing any files. The -f option causes files to be
1241 silently deleted, without querying, and suppresses all error in‐
1242 dications. -f takes precedence.
1243 The -R and -r options cause rm to recursively descend into di‐
1245 rectories, deleting all files in the directory before removing
1246 the directory with the rmdir system call (see rmdir(2)).
1247 The -s option is a zsh extension to rm functionality. It en‐
1249 ables paranoid behaviour, intended to avoid common security
1250 problems involving a root-run rm being tricked into removing
1251 files other than the ones intended. It will refuse to follow
1252 symbolic links, so that (for example) ``rm /tmp/foo/passwd''
1253 can't accidentally remove /etc/passwd if /tmp/foo happens to be
1254 a link to /etc. It will also check where it is after leaving
1255 directories, so that a recursive removal of a deep directory
1256 tree can't end up recursively removing /usr as a result of di‐
1257 rectories being moved up the tree.
1258 rmdir dir ...
1260 Removes empty directories specified.
1261 sync Calls the system call of the same name (see sync(2)), which
1263 flushes dirty buffers to disk. It might return before the I/O
1264 has actually been completed.
1265
1267 The zsh/langinfo module makes available one parameter:
1268 langinfo
1270 An associative array that maps langinfo elements to their val‐
1271 ues.
1272 Your implementation may support a number of the following keys:
1274 CODESET, D_T_FMT, D_FMT, T_FMT, RADIXCHAR, THOUSEP, YESEXPR, NO‐
1276 EXPR, CRNCYSTR, ABDAY_{1..7}, DAY_{1..7}, ABMON_{1..12},
1277 MON_{1..12}, T_FMT_AMPM, AM_STR, PM_STR, ERA, ERA_D_FMT,
1278 ERA_D_T_FMT, ERA_T_FMT, ALT_DIGITS
1279
1281 The zsh/mapfile module provides one special associative array parameter
1282 of the same name.
1283 mapfile
1285 This associative array takes as keys the names of files; the re‐
1286 sulting value is the content of the file. The value is treated
1287 identically to any other text coming from a parameter. The
1288 value may also be assigned to, in which case the file in ques‐
1289 tion is written (whether or not it originally existed); or an
1290 element may be unset, which will delete the file in question.
1291 For example, `vared 'mapfile[myfile]'' works as expected, edit‐
1292 ing the file `myfile'.
1293 When the array is accessed as a whole, the keys are the names of
1295 files in the current directory, and the values are empty (to
1296 save a huge overhead in memory). Thus ${(k)mapfile} has the
1297 same effect as the glob operator *(D), since files beginning
1298 with a dot are not special. Care must be taken with expressions
1299 such as rm ${(k)mapfile}, which will delete every file in the
1300 current directory without the usual `rm *' test.
1301 The parameter mapfile may be made read-only; in that case, files
1303 referenced may not be written or deleted.
1304 A file may conveniently be read into an array as one line per
1306 element with the form `array=("${(f@)mapfile[filename]}")'. The
1307 double quotes and the `@' are necessary to prevent empty lines
1308 from being removed. Note that if the file ends with a newline,
1309 the shell will split on the final newline, generating an addi‐
1310 tional empty field; this can be suppressed by using `ar‐
1311 ray=("${(f@)${mapfile[filename]%$'\n'}}")'.
1312 Limitations
1314 Although reading and writing of the file in question is efficiently
1315 handled, zsh's internal memory management may be arbitrarily baroque;
1316 however, mapfile is usually very much more efficient than anything in‐
1317 volving a loop. Note in particular that the whole contents of the file
1318 will always reside physically in memory when accessed (possibly multi‐
1319 ple times, due to standard parameter substitution operations). In par‐
1320 ticular, this means handling of sufficiently long files (greater than
1321 the machine's swap space, or than the range of the pointer type) will
1322 be incorrect.
1323 No errors are printed or flagged for non-existent, unreadable, or un‐
1325 writable files, as the parameter mechanism is too low in the shell exe‐
1326 cution hierarchy to make this convenient.
1327 It is unfortunate that the mechanism for loading modules does not yet
1329 allow the user to specify the name of the shell parameter to be given
1330 the special behaviour.
1331
1333 The zsh/mathfunc module provides standard mathematical functions for
1334 use when evaluating mathematical formulae. The syntax agrees with nor‐
1335 mal C and FORTRAN conventions, for example,
1336 (( f = sin(0.3) ))
1338 assigns the sine of 0.3 to the parameter f.
1340 Most functions take floating point arguments and return a floating
1342 point value. However, any necessary conversions from or to integer
1343 type will be performed automatically by the shell. Apart from atan
1344 with a second argument and the abs, int and float functions, all func‐
1345 tions behave as noted in the manual page for the corresponding C func‐
1346 tion, except that any arguments out of range for the function in ques‐
1347 tion will be detected by the shell and an error reported.
1348 The following functions take a single floating point argument: acos,
1350 acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp,
1351 expm1, fabs, floor, gamma, j0, j1, lgamma, log, log10, log1p, log2,
1352 logb, sin, sinh, sqrt, tan, tanh, y0, y1. The atan function can op‐
1353 tionally take a second argument, in which case it behaves like the C
1354 function atan2. The ilogb function takes a single floating point argu‐
1355 ment, but returns an integer.
1356 The function signgam takes no arguments, and returns an integer, which
1358 is the C variable of the same name, as described in gamma(3). Note
1359 that it is therefore only useful immediately after a call to gamma or
1360 lgamma. Note also that `signgam()' and `signgam' are distinct expres‐
1361 sions.
1362 The functions min, max, and sum are defined not in this module but in
1364 the zmathfunc autoloadable function, described in the section `Mathe‐
1365 matical Functions' in zshcontrib(1).
1366 The following functions take two floating point arguments: copysign,
1368 fmod, hypot, nextafter.
1369 The following take an integer first argument and a floating point sec‐
1371 ond argument: jn, yn.
1372 The following take a floating point first argument and an integer sec‐
1374 ond argument: ldexp, scalb.
1375 The function abs does not convert the type of its single argument; it
1377 returns the absolute value of either a floating point number or an in‐
1378 teger. The functions float and int convert their arguments into a
1379 floating point or integer value (by truncation) respectively.
1380 Note that the C pow function is available in ordinary math evaluation
1382 as the `**' operator and is not provided here.
1383 The function rand48 is available if your system's mathematical library
1385 has the function erand48(3). It returns a pseudo-random floating point
1386 number between 0 and 1. It takes a single string optional argument.
1387 If the argument is not present, the random number seed is initialised
1389 by three calls to the rand(3) function --- this produces the same ran‐
1390 dom numbers as the next three values of $RANDOM.
1391 If the argument is present, it gives the name of a scalar parameter
1393 where the current random number seed will be stored. On the first
1394 call, the value must contain at least twelve hexadecimal digits (the
1395 remainder of the string is ignored), or the seed will be initialised in
1396 the same manner as for a call to rand48 with no argument. Subsequent
1397 calls to rand48(param) will then maintain the seed in the parameter
1398 param as a string of twelve hexadecimal digits, with no base signifier.
1399 The random number sequences for different parameters are completely in‐
1400 dependent, and are also independent from that used by calls to rand48
1401 with no argument.
1402 For example, consider
1404 print $(( rand48(seed) ))
1406 print $(( rand48() ))
1407 print $(( rand48(seed) ))
1408 Assuming $seed does not exist, it will be initialised by the first
1410 call. In the second call, the default seed is initialised; note, how‐
1411 ever, that because of the properties of rand() there is a correlation
1412 between the seeds used for the two initialisations, so for more secure
1413 uses, you should generate your own 12-byte seed. The third call re‐
1414 turns to the same sequence of random numbers used in the first call,
1415 unaffected by the intervening rand48().
1416
1418 The zsh/nearcolor module replaces colours specified as hex triplets
1419 with the nearest colour in the 88 or 256 colour palettes that are
1420 widely used by terminal emulators. By default, 24-bit true colour es‐
1421 cape codes are generated when colours are specified using hex triplets.
1422 These are not supported by all terminals. The purpose of this module
1423 is to make it easier to define colour preferences in a form that can
1424 work across a range of terminal emulators.
1425 Aside from the default colour, the ANSI standard for terminal escape
1427 codes provides for eight colours. The bright attribute brings this to
1428 sixteen. These basic colours are commonly used in terminal applications
1429 due to being widely supported. Expanded 88 and 256 colour palettes are
1430 also common and, while the first sixteen colours vary somewhat between
1431 terminals and configurations, these add a generally consistent and pre‐
1432 dictable set of colours.
1433 In order to use the zsh/nearcolor module, it only needs to be loaded.
1435 Thereafter, whenever a colour is specified using a hex triplet, it will
1436 be compared against each of the available colours and the closest will
1437 be selected. The first sixteen colours are never matched in this
1438 process due to being unpredictable.
1439 It isn't possible to reliably detect support for true colour in the
1441 terminal emulator. It is therefore recommended to be selective in load‐
1442 ing the zsh/nearcolor module. For example, the following checks the
1443 COLORTERM environment variable:
1444 [[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor
1446 Note that some terminals accept the true color escape codes but map
1448 them internally to a more limited palette in a similar manner to the
1449 zsh/nearcolor module.
1450
1452 The zsh/newuser module is loaded at boot if it is available, the RCS
1453 option is set, and the PRIVILEGED option is not set (all three are true
1454 by default). This takes place immediately after commands in the global
1455 zshenv file (typically /etc/zshenv), if any, have been executed. If
1456 the module is not available it is silently ignored by the shell; the
1457 module may safely be removed from $MODULE_PATH by the administrator if
1458 it is not required.
1459 On loading, the module tests if any of the start-up files .zshenv,
1461 .zprofile, .zshrc or .zlogin exist in the directory given by the envi‐
1462 ronment variable ZDOTDIR, or the user's home directory if that is not
1463 set. The test is not performed and the module halts processing if the
1464 shell was in an emulation mode (i.e. had been invoked as some other
1465 shell than zsh).
1466 If none of the start-up files were found, the module then looks for the
1468 file newuser first in a sitewide directory, usually the parent direc‐
1469 tory of the site-functions directory, and if that is not found the mod‐
1470 ule searches in a version-specific directory, usually the parent of the
1471 functions directory containing version-specific functions. (These di‐
1472 rectories can be configured when zsh is built using the --en‐
1473 able-site-scriptdir=dir and --enable-scriptdir=dir flags to configure,
1474 respectively; the defaults are prefix/share/zsh and pre‐
1475 fix/share/zsh/$ZSH_VERSION where the default prefix is /usr/local.)
1476 If the file newuser is found, it is then sourced in the same manner as
1478 a start-up file. The file is expected to contain code to install
1479 start-up files for the user, however any valid shell code will be exe‐
1480 cuted.
1481 The zsh/newuser module is then unconditionally unloaded.
1483 Note that it is possible to achieve exactly the same effect as the
1485 zsh/newuser module by adding code to /etc/zshenv. The module exists
1486 simply to allow the shell to make arrangements for new users without
1487 the need for intervention by package maintainers and system administra‐
1488 tors.
1489 The script supplied with the module invokes the shell function
1491 zsh-newuser-install. This may be invoked directly by the user even if
1492 the zsh/newuser module is disabled. Note, however, that if the module
1493 is not installed the function will not be installed either. The func‐
1494 tion is documented in the section `User Configuration Functions' in
1495 zshcontrib(1).
1496
1498 The zsh/parameter module gives access to some of the internal hash ta‐
1499 bles used by the shell by defining some special parameters.
1500 options
1502 The keys for this associative array are the names of the options
1503 that can be set and unset using the setopt and unsetopt
1504 builtins. The value of each key is either the string on if the
1505 option is currently set, or the string off if the option is un‐
1506 set. Setting a key to one of these strings is like setting or
1507 unsetting the option, respectively. Unsetting a key in this ar‐
1508 ray is like setting it to the value off.
1509 commands
1511 This array gives access to the command hash table. The keys are
1512 the names of external commands, the values are the pathnames of
1513 the files that would be executed when the command would be in‐
1514 voked. Setting a key in this array defines a new entry in this
1515 table in the same way as with the hash builtin. Unsetting a key
1516 as in `unset "commands[foo]"' removes the entry for the given
1517 key from the command hash table.
1518 functions
1520 This associative array maps names of enabled functions to their
1521 definitions. Setting a key in it is like defining a function
1522 with the name given by the key and the body given by the value.
1523 Unsetting a key removes the definition for the function named by
1524 the key.
1525 dis_functions
1527 Like functions but for disabled functions.
1528 functions_source
1530 This readonly associative array maps names of enabled functions
1531 to the name of the file containing the source of the function.
1532 For an autoloaded function that has already been loaded, or
1534 marked for autoload with an absolute path, or that has had its
1535 path resolved with `functions -r', this is the file found for
1536 autoloading, resolved to an absolute path.
1537 For a function defined within the body of a script or sourced
1539 file, this is the name of that file. In this case, this is the
1540 exact path originally used to that file, which may be a relative
1541 path.
1542 For any other function, including any defined at an interactive
1544 prompt or an autoload function whose path has not yet been re‐
1545 solved, this is the empty string. However, the hash element is
1546 reported as defined just so long as the function is present:
1547 the keys to this hash are the same as those to $functions.
1548 dis_functions_source
1550 Like functions_source but for disabled functions.
1551 builtins
1553 This associative array gives information about the builtin com‐
1554 mands currently enabled. The keys are the names of the builtin
1555 commands and the values are either `undefined' for builtin com‐
1556 mands that will automatically be loaded from a module if invoked
1557 or `defined' for builtin commands that are already loaded.
1558 dis_builtins
1560 Like builtins but for disabled builtin commands.
1561 reswords
1563 This array contains the enabled reserved words.
1564 dis_reswords
1566 Like reswords but for disabled reserved words.
1567 patchars
1569 This array contains the enabled pattern characters.
1570 dis_patchars
1572 Like patchars but for disabled pattern characters.
1573 aliases
1575 This maps the names of the regular aliases currently enabled to
1576 their expansions.
1577 dis_aliases
1579 Like aliases but for disabled regular aliases.
1580 galiases
1582 Like aliases, but for global aliases.
1583 dis_galiases
1585 Like galiases but for disabled global aliases.
1586 saliases
1588 Like raliases, but for suffix aliases.
1589 dis_saliases
1591 Like saliases but for disabled suffix aliases.
1592 parameters
1594 The keys in this associative array are the names of the parame‐
1595 ters currently defined. The values are strings describing the
1596 type of the parameter, in the same format used by the t parame‐
1597 ter flag, see zshexpn(1) . Setting or unsetting keys in this
1598 array is not possible.
1599 modules
1601 An associative array giving information about modules. The keys
1602 are the names of the modules loaded, registered to be au‐
1603 toloaded, or aliased. The value says which state the named mod‐
1604 ule is in and is one of the strings `loaded', `autoloaded', or
1605 `alias:name', where name is the name the module is aliased to.
1606 Setting or unsetting keys in this array is not possible.
1608 dirstack
1610 A normal array holding the elements of the directory stack. Note
1611 that the output of the dirs builtin command includes one more
1612 directory, the current working directory.
1613 history
1615 This associative array maps history event numbers to the full
1616 history lines. Although it is presented as an associative ar‐
1617 ray, the array of all values (${history[@]}) is guaranteed to be
1618 returned in order from most recent to oldest history event, that
1619 is, by decreasing history event number.
1620 historywords
1622 A special array containing the words stored in the history.
1623 These also appear in most to least recent order.
1624 jobdirs
1626 This associative array maps job numbers to the directories from
1627 which the job was started (which may not be the current direc‐
1628 tory of the job).
1629 The keys of the associative arrays are usually valid job num‐
1631 bers, and these are the values output with, for example,
1632 ${(k)jobdirs}. Non-numeric job references may be used when
1633 looking up a value; for example, ${jobdirs[%+]} refers to the
1634 current job.
1635 See the jobs builtin for how job information is provided in a
1637 subshell.
1638 jobtexts
1640 This associative array maps job numbers to the texts of the com‐
1641 mand lines that were used to start the jobs.
1642 Handling of the keys of the associative array is as described
1644 for jobdirs above.
1645 See the jobs builtin for how job information is provided in a
1647 subshell.
1648 jobstates
1650 This associative array gives information about the states of the
1651 jobs currently known. The keys are the job numbers and the val‐
1652 ues are strings of the form `job-state:mark:pid=state...'. The
1653 job-state gives the state the whole job is currently in, one of
1654 `running', `suspended', or `done'. The mark is `+' for the cur‐
1655 rent job, `-' for the previous job and empty otherwise. This is
1656 followed by one `:pid=state' for every process in the job. The
1657 pids are, of course, the process IDs and the state describes the
1658 state of that process.
1659 Handling of the keys of the associative array is as described
1661 for jobdirs above.
1662 See the jobs builtin for how job information is provided in a
1664 subshell.
1665 nameddirs
1667 This associative array maps the names of named directories to
1668 the pathnames they stand for.
1669 userdirs
1671 This associative array maps user names to the pathnames of their
1672 home directories.
1673 usergroups
1675 This associative array maps names of system groups of which the
1676 current user is a member to the corresponding group identifiers.
1677 The contents are the same as the groups output by the id com‐
1678 mand.
1679 funcfiletrace
1681 This array contains the absolute line numbers and corresponding
1682 file names for the point where the current function, sourced
1683 file, or (if EVAL_LINENO is set) eval command was called. The
1684 array is of the same length as funcsourcetrace and functrace,
1685 but differs from funcsourcetrace in that the line and file are
1686 the point of call, not the point of definition, and differs from
1687 functrace in that all values are absolute line numbers in files,
1688 rather than relative to the start of a function, if any.
1689 funcsourcetrace
1691 This array contains the file names and line numbers of the
1692 points where the functions, sourced files, and (if EVAL_LINENO
1693 is set) eval commands currently being executed were defined.
1694 The line number is the line where the `function name' or `name
1695 ()' started. In the case of an autoloaded function the line
1696 number is reported as zero. The format of each element is file‐
1697 name:lineno.
1698 For functions autoloaded from a file in native zsh format, where
1700 only the body of the function occurs in the file, or for files
1701 that have been executed by the source or `.' builtins, the trace
1702 information is shown as filename:0, since the entire file is the
1703 definition. The source file name is resolved to an absolute
1704 path when the function is loaded or the path to it otherwise re‐
1705 solved.
1706 Most users will be interested in the information in the func‐
1708 filetrace array instead.
1709 funcstack
1711 This array contains the names of the functions, sourced files,
1712 and (if EVAL_LINENO is set) eval commands. currently being exe‐
1713 cuted. The first element is the name of the function using the
1714 parameter.
1715 The standard shell array zsh_eval_context can be used to deter‐
1717 mine the type of shell construct being executed at each depth:
1718 note, however, that is in the opposite order, with the most re‐
1719 cent item last, and it is more detailed, for example including
1720 an entry for toplevel, the main shell code being executed either
1721 interactively or from a script, which is not present in $func‐
1722 stack.
1723 functrace
1725 This array contains the names and line numbers of the callers
1726 corresponding to the functions currently being executed. The
1727 format of each element is name:lineno. Callers are also shown
1728 for sourced files; the caller is the point where the source or
1729 `.' command was executed.
1730
1732 The zsh/pcre module makes some commands available as builtins:
1733 pcre_compile [ -aimxs ] PCRE
1735 Compiles a perl-compatible regular expression.
1736 Option -a will force the pattern to be anchored. Option -i will
1738 compile a case-insensitive pattern. Option -m will compile a
1739 multi-line pattern; that is, ^ and $ will match newlines within
1740 the pattern. Option -x will compile an extended pattern,
1741 wherein whitespace and # comments are ignored. Option -s makes
1742 the dot metacharacter match all characters, including those that
1743 indicate newline.
1744 pcre_study
1746 Studies the previously-compiled PCRE which may result in faster
1747 matching.
1748 pcre_match [ -v var ] [ -a arr ] [ -n offset ] [ -b ] string
1750 Returns successfully if string matches the previously-compiled
1751 PCRE.
1752 Upon successful match, if the expression captures substrings
1754 within parentheses, pcre_match will set the array match to those
1755 substrings, unless the -a option is given, in which case it will
1756 set the array arr. Similarly, the variable MATCH will be set to
1757 the entire matched portion of the string, unless the -v option
1758 is given, in which case the variable var will be set. No vari‐
1759 ables are altered if there is no successful match. A -n option
1760 starts searching for a match from the byte offset position in
1761 string. If the -b option is given, the variable ZPCRE_OP will
1762 be set to an offset pair string, representing the byte offset
1763 positions of the entire matched portion within the string. For
1764 example, a ZPCRE_OP set to "32 45" indicates that the matched
1765 portion began on byte offset 32 and ended on byte offset 44.
1766 Here, byte offset position 45 is the position directly after the
1767 matched portion. Keep in mind that the byte position isn't nec‐
1768 essarily the same as the character position when UTF-8 charac‐
1769 ters are involved. Consequently, the byte offset positions are
1770 only to be relied on in the context of using them for subsequent
1771 searches on string, using an offset position as an argument to
1772 the -n option. This is mostly used to implement the "find all
1773 non-overlapping matches" functionality.
1774 A simple example of "find all non-overlapping matches":
1776 string="The following zip codes: 78884 90210 99513"
1778 pcre_compile -m "\d{5}"
1779 accum=()
1780 pcre_match -b -- $string
1781 while [[ $? -eq 0 ]] do
1782 b=($=ZPCRE_OP)
1783 accum+=$MATCH
1784 pcre_match -b -n $b[2] -- $string
1785 done
1786 print -l $accum
1787 The zsh/pcre module makes available the following test condition:
1789 expr -pcre-match pcre
1791 Matches a string against a perl-compatible regular expression.
1792 For example,
1794 [[ "$text" -pcre-match ^d+$ ]] &&
1796 print text variable contains only "d's".
1797 If the REMATCH_PCRE option is set, the =~ operator is equivalent
1799 to -pcre-match, and the NO_CASE_MATCH option may be used. Note
1800 that NO_CASE_MATCH never applies to the pcre_match builtin, in‐
1801 stead use the -i switch of pcre_compile.
1802
1804 The zsh/param/private module is used to create parameters whose scope
1805 is limited to the current function body, and not to other functions
1806 called by the current function.
1807 This module provides a single autoloaded builtin:
1809 private [ {+|-}AHUahlmrtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ]
1811 The private builtin accepts all the same options and arguments
1812 as local (zshbuiltins(1)) except for the `-T' option. Tied pa‐
1813 rameters may not be made private.
1814 The `-p' option is presently a no-op because the state of pri‐
1816 vate parameters cannot reliably be reloaded. This also applies
1817 to printing private parameters with `typeset -p'.
1818 If used at the top level (outside a function scope), private
1820 creates a normal parameter in the same manner as declare or
1821 typeset. A warning about this is printed if WARN_CREATE_GLOBAL
1822 is set (zshoptions(1)). Used inside a function scope, private
1823 creates a local parameter similar to one declared with local,
1824 except having special properties noted below.
1825 Special parameters which expose or manipulate internal shell
1827 state, such as ARGC, argv, COLUMNS, LINES, UID, EUID, IFS,
1828 PROMPT, RANDOM, SECONDS, etc., cannot be made private unless the
1829 `-h' option is used to hide the special meaning of the parame‐
1830 ter. This may change in the future.
1831 As with other typeset equivalents, private is both a builtin and a re‐
1833 served word, so arrays may be assigned with parenthesized word list
1834 name=(value...) syntax. However, the reserved word `private' is not
1835 available until zsh/param/private is loaded, so care must be taken with
1836 order of execution and parsing for function definitions which use pri‐
1837 vate. To compensate for this, the module also adds the option `-P' to
1838 the `local' builtin to declare private parameters.
1839 For example, this construction fails if zsh/param/private has not yet
1841 been loaded when `bad_declaration' is defined:
1842 bad_declaration() {
1843 zmodload zsh/param/private
1844 private array=( one two three )
1845 }
1846 This construction works because local is already a keyword, and the
1848 module is loaded before the statement is executed:
1849 good_declaration() {
1850 zmodload zsh/param/private
1851 local -P array=( one two three )
1852 }
1853 The following is usable in scripts but may have trouble with autoload:
1855 zmodload zsh/param/private
1856 iffy_declaration() {
1857 private array=( one two three )
1858 }
1859 The private builtin may always be used with scalar assignments and for
1861 declarations without assignments.
1862 Parameters declared with private have the following properties:
1864 • Within the function body where it is declared, the parameter be‐
1866 haves as a local, except as noted above for tied or special pa‐
1867 rameters.
1868 • The type of a parameter declared private cannot be changed in
1870 the scope where it was declared, even if the parameter is unset.
1871 Thus an array cannot be assigned to a private scalar, etc.
1872 • Within any other function called by the declaring function, the
1874 private parameter does NOT hide other parameters of the same
1875 name, so for example a global parameter of the same name is vis‐
1876 ible and may be assigned or unset. This includes calls to
1877 anonymous functions, although that may also change in the fu‐
1878 ture. However, the private name may not be created outside the
1879 local scope when it was not previously declared.
1880 • An exported private remains in the environment of inner scopes
1882 but appears unset for the current shell in those scopes. Gener‐
1883 ally, exporting private parameters should be avoided.
1884 Note that this differs from the static scope defined by compiled lan‐
1886 guages derived from C, in that the a new call to the same function cre‐
1887 ates a new scope, i.e., the parameter is still associated with the call
1888 stack rather than with the function definition. It differs from ksh
1889 `typeset -S' because the syntax used to define the function has no
1890 bearing on whether the parameter scope is respected.
1891
1893 The zsh/regex module makes available the following test condition:
1894 expr -regex-match regex
1896 Matches a string against a POSIX extended regular expression.
1897 On successful match, matched portion of the string will normally
1898 be placed in the MATCH variable. If there are any capturing
1899 parentheses within the regex, then the match array variable will
1900 contain those. If the match is not successful, then the vari‐
1901 ables will not be altered.
1902 For example,
1904 [[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
1906 print -l $MATCH X $match
1907 If the option REMATCH_PCRE is not set, then the =~ operator will
1909 automatically load this module as needed and will invoke the
1910 -regex-match operator.
1911 If BASH_REMATCH is set, then the array BASH_REMATCH will be set
1913 instead of MATCH and match.
1914 Note that the zsh/regex module logic relies on the host system.
1916 The same expr and regex pair could produce different results on
1917 different platforms if a regex with non-standard syntax is
1918 given.
1919 For example, no syntax for matching a word boundary is defined
1921 in the POSIX extended regular expression standard. GNU libc and
1922 BSD libc both provide such syntaxes as extensions (\b and
1923 [[:<:]]/[[:>:]] respectively), but neither of these syntaxes is
1924 supported by both of these implementations.
1925 Refer to the regcomp(3) and re_format(7) manual pages on your
1927 system for locally-supported syntax.
1928
1930 The zsh/sched module makes available one builtin command and one param‐
1931 eter.
1932 sched [-o] [+]hh:mm[:ss] command ...
1934 sched [-o] [+]seconds command ...
1935 sched [ -item ]
1936 Make an entry in the scheduled list of commands to execute. The
1937 time may be specified in either absolute or relative time, and
1938 either as hours, minutes and (optionally) seconds separated by a
1939 colon, or seconds alone. An absolute number of seconds indi‐
1940 cates the time since the epoch (1970/01/01 00:00); this is use‐
1941 ful in combination with the features in the zsh/datetime module,
1942 see the zsh/datetime module entry in zshmodules(1).
1943 With no arguments, prints the list of scheduled commands. If
1945 the scheduled command has the -o flag set, this is shown at the
1946 start of the command.
1947 With the argument `-item', removes the given item from the list.
1949 The numbering of the list is continuous and entries are in time
1950 order, so the numbering can change when entries are added or
1951 deleted.
1952 Commands are executed either immediately before a prompt, or
1954 while the shell's line editor is waiting for input. In the lat‐
1955 ter case it is useful to be able to produce output that does not
1956 interfere with the line being edited. Providing the option -o
1957 causes the shell to clear the command line before the event and
1958 redraw it afterwards. This should be used with any scheduled
1959 event that produces visible output to the terminal; it is not
1960 needed, for example, with output that updates a terminal emula‐
1961 tor's title bar.
1962 To effect changes to the editor buffer when an event executes,
1964 use the `zle' command with no arguments to test whether the edi‐
1965 tor is active, and if it is, then use `zle widget' to access the
1966 editor via the named widget.
1967 The sched builtin is not made available by default when the
1969 shell starts in a mode emulating another shell. It can be made
1970 available with the command `zmodload -F zsh/sched b:sched'.
1971 zsh_scheduled_events
1973 A readonly array corresponding to the events scheduled by the
1974 sched builtin. The indices of the array correspond to the num‐
1975 bers shown when sched is run with no arguments (provided that
1976 the KSH_ARRAYS option is not set). The value of the array con‐
1977 sists of the scheduled time in seconds since the epoch (see the
1978 section `The zsh/datetime Module' for facilities for using this
1979 number), followed by a colon, followed by any options (which may
1980 be empty but will be preceded by a `-' otherwise), followed by a
1981 colon, followed by the command to be executed.
1982 The sched builtin should be used for manipulating the events.
1984 Note that this will have an immediate effect on the contents of
1985 the array, so that indices may become invalid.
1986
1988 The zsh/net/socket module makes available one builtin command:
1989 zsocket [ -altv ] [ -d fd ] [ args ]
1991 zsocket is implemented as a builtin to allow full use of shell
1992 command line editing, file I/O, and job control mechanisms.
1993 Outbound Connections
1995 zsocket [ -v ] [ -d fd ] filename
1996 Open a new Unix domain connection to filename. The shell param‐
1997 eter REPLY will be set to the file descriptor associated with
1998 that connection. Currently, only stream connections are sup‐
1999 ported.
2000 If -d is specified, its argument will be taken as the target
2002 file descriptor for the connection.
2003 In order to elicit more verbose output, use -v.
2005 File descriptors can be closed with normal shell syntax when no
2007 longer needed, for example:
2008 exec {REPLY}>&-
2010 Inbound Connections
2012 zsocket -l [ -v ] [ -d fd ] filename
2013 zsocket -l will open a socket listening on filename. The shell
2014 parameter REPLY will be set to the file descriptor associated
2015 with that listener. The file descriptor remains open in sub‐
2016 shells and forked external executables.
2017 If -d is specified, its argument will be taken as the target
2019 file descriptor for the connection.
2020 In order to elicit more verbose output, use -v.
2022 zsocket -a [ -tv ] [ -d targetfd ] listenfd
2024 zsocket -a will accept an incoming connection to the socket as‐
2025 sociated with listenfd. The shell parameter REPLY will be set
2026 to the file descriptor associated with the inbound connection.
2027 The file descriptor remains open in subshells and forked exter‐
2028 nal executables.
2029 If -d is specified, its argument will be taken as the target
2031 file descriptor for the connection.
2032 If -t is specified, zsocket will return if no incoming connec‐
2034 tion is pending. Otherwise it will wait for one.
2035 In order to elicit more verbose output, use -v.
2037
2039 The zsh/stat module makes available one builtin command under two pos‐
2040 sible names:
2041 zstat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ]
2043 [ +element ] [ file ... ]
2044 stat ...
2045 The command acts as a front end to the stat system call (see
2046 stat(2)). The same command is provided with two names; as the
2047 name stat is often used by an external command it is recommended
2048 that only the zstat form of the command is used. This can be
2049 arranged by loading the module with the command `zmodload -F
2050 zsh/stat b:zstat'.
2051 If the stat call fails, the appropriate system error message
2053 printed and status 1 is returned. The fields of struct stat
2054 give information about the files provided as arguments to the
2055 command. In addition to those available from the stat call, an
2056 extra element `link' is provided. These elements are:
2057 device The number of the device on which the file resides.
2059 inode The unique number of the file on this device (`inode'
2061 number).
2062 mode The mode of the file; that is, the file's type and access
2064 permissions. With the -s option, this will be returned
2065 as a string corresponding to the first column in the dis‐
2066 play of the ls -l command.
2067 nlink The number of hard links to the file.
2069 uid The user ID of the owner of the file. With the -s op‐
2071 tion, this is displayed as a user name.
2072 gid The group ID of the file. With the -s option, this is
2074 displayed as a group name.
2075 rdev The raw device number. This is only useful for special
2077 devices.
2078 size The size of the file in bytes.
2080 atime
2082 mtime
2083 ctime The last access, modification and inode change times of
2084 the file, respectively, as the number of seconds since
2085 midnight GMT on 1st January, 1970. With the -s option,
2086 these are printed as strings for the local time zone; the
2087 format can be altered with the -F option, and with the -g
2088 option the times are in GMT.
2089 blksize
2091 The number of bytes in one allocation block on the device
2092 on which the file resides.
2093 block The number of disk blocks used by the file.
2095 link If the file is a link and the -L option is in effect,
2097 this contains the name of the file linked to, otherwise
2098 it is empty. Note that if this element is selected
2099 (``zstat +link'') then the -L option is automatically
2100 used.
2101 A particular element may be selected by including its name pre‐
2103 ceded by a `+' in the option list; only one element is allowed.
2104 The element may be shortened to any unique set of leading char‐
2105 acters. Otherwise, all elements will be shown for all files.
2106 Options:
2108 -A array
2110 Instead of displaying the results on standard output, as‐
2111 sign them to an array, one struct stat element per array
2112 element for each file in order. In this case neither the
2113 name of the element nor the name of the files appears in
2114 array unless the -t or -n options were given, respec‐
2115 tively. If -t is given, the element name appears as a
2116 prefix to the appropriate array element; if -n is given,
2117 the file name appears as a separate array element preced‐
2118 ing all the others. Other formatting options are re‐
2119 spected.
2120 -H hash
2122 Similar to -A, but instead assign the values to hash.
2123 The keys are the elements listed above. If the -n option
2124 is provided then the name of the file is included in the
2125 hash with key name.
2126 -f fd Use the file on file descriptor fd instead of named
2128 files; no list of file names is allowed in this case.
2129 -F fmt Supplies a strftime (see strftime(3)) string for the for‐
2131 matting of the time elements. The format string supports
2132 all of the zsh extensions described in the section EXPAN‐
2133 SION OF PROMPT SEQUENCES in zshmisc(1). In particular,
2134 -F %s.%N can be used to show timestamps with nanosecond
2135 precision if supported by the system. The -s option is
2136 implied.
2137 -g Show the time elements in the GMT time zone. The -s op‐
2139 tion is implied.
2140 -l List the names of the type elements (to standard output
2142 or an array as appropriate) and return immediately; argu‐
2143 ments, and options other than -A, are ignored.
2144 -L Perform an lstat (see lstat(2)) rather than a stat system
2146 call. In this case, if the file is a link, information
2147 about the link itself rather than the target file is re‐
2148 turned. This option is required to make the link element
2149 useful. It's important to note that this is the exact
2150 opposite from ls(1), etc.
2151 -n Always show the names of files. Usually these are only
2153 shown when output is to standard output and there is more
2154 than one file in the list.
2155 -N Never show the names of files.
2157 -o If a raw file mode is printed, show it in octal, which is
2159 more useful for human consumption than the default of
2160 decimal. A leading zero will be printed in this case.
2161 Note that this does not affect whether a raw or formatted
2162 file mode is shown, which is controlled by the -r and -s
2163 options, nor whether a mode is shown at all.
2164 -r Print raw data (the default format) alongside string data
2166 (the -s format); the string data appears in parentheses
2167 after the raw data.
2168 -s Print mode, uid, gid and the three time elements as
2170 strings instead of numbers. In each case the format is
2171 like that of ls -l.
2172 -t Always show the type names for the elements of struct
2174 stat. Usually these are only shown when output is to
2175 standard output and no individual element has been se‐
2176 lected.
2177 -T Never show the type names of the struct stat elements.
2179
2181 The zsh/system module makes available various builtin commands and pa‐
2182 rameters.
2183 Builtins
2185 syserror [ -e errvar ] [ -p prefix ] [ errno | errname ]
2186 This command prints out the error message associated with errno,
2187 a system error number, followed by a newline to standard error.
2188 Instead of the error number, a name errname, for example ENOENT,
2190 may be used. The set of names is the same as the contents of
2191 the array errnos, see below.
2192 If the string prefix is given, it is printed in front of the er‐
2194 ror message, with no intervening space.
2195 If errvar is supplied, the entire message, without a newline, is
2197 assigned to the parameter names errvar and nothing is output.
2198 A return status of 0 indicates the message was successfully
2200 printed (although it may not be useful if the error number was
2201 out of the system's range), a return status of 1 indicates an
2202 error in the parameters, and a return status of 2 indicates the
2203 error name was not recognised (no message is printed for this).
2204 sysopen [ -arw ] [ -m permissions ] [ -o options ]
2207 -u fd file
2208 This command opens a file. The -r, -w and -a flags indicate
2209 whether the file should be opened for reading, writing and ap‐
2210 pending, respectively. The -m option allows the initial permis‐
2211 sions to use when creating a file to be specified in octal form.
2212 The file descriptor is specified with -u. Either an explicit
2213 file descriptor in the range 0 to 9 can be specified or a vari‐
2214 able name can be given to which the file descriptor number will
2215 be assigned.
2216 The -o option allows various system specific options to be spec‐
2218 ified as a comma-separated list. The following is a list of pos‐
2219 sible options. Note that, depending on the system, some may not
2220 be available.
2221 cloexec
2222 mark file to be closed when other programs are executed
2223 (else the file descriptor remains open in subshells and
2224 forked external executables)
2225 create
2227 creat create file if it does not exist
2228 excl create file, error if it already exists
2230 noatime
2232 suppress updating of the file atime
2233 nofollow
2235 fail if file is a symbolic link
2236 nonblock
2238 the file is opened in nonblocking mode
2239 sync request that writes wait until data has been physically
2241 written
2242 truncate
2244 trunc truncate file to size 0
2245 To close the file, use one of the following:
2247 exec {fd}<&-
2249 exec {fd}>&-
2250 sysread [ -c countvar ] [ -i infd ] [ -o outfd ]
2253 [ -s bufsize ] [ -t timeout ] [ param ]
2254 Perform a single system read from file descriptor infd, or zero
2255 if that is not given. The result of the read is stored in param
2256 or REPLY if that is not given. If countvar is given, the number
2257 of bytes read is assigned to the parameter named by countvar.
2258 The maximum number of bytes read is bufsize or 8192 if that is
2260 not given, however the command returns as soon as any number of
2261 bytes was successfully read.
2262 If timeout is given, it specifies a timeout in seconds, which
2264 may be zero to poll the file descriptor. This is handled by the
2265 poll system call if available, otherwise the select system call
2266 if available.
2267 If outfd is given, an attempt is made to write all the bytes
2269 just read to the file descriptor outfd. If this fails, because
2270 of a system error other than EINTR or because of an internal zsh
2271 error during an interrupt, the bytes read but not written are
2272 stored in the parameter named by param if supplied (no default
2273 is used in this case), and the number of bytes read but not
2274 written is stored in the parameter named by countvar if that is
2275 supplied. If it was successful, countvar contains the full num‐
2276 ber of bytes transferred, as usual, and param is not set.
2277 The error EINTR (interrupted system call) is handled internally
2279 so that shell interrupts are transparent to the caller. Any
2280 other error causes a return.
2281 The possible return statuses are
2283 0 At least one byte of data was successfully read and, if
2284 appropriate, written.
2285 1 There was an error in the parameters to the command.
2287 This is the only error for which a message is printed to
2288 standard error.
2289 2 There was an error on the read, or on polling the input
2291 file descriptor for a timeout. The parameter ERRNO gives
2292 the error.
2293 3 Data were successfully read, but there was an error writ‐
2295 ing them to outfd. The parameter ERRNO gives the error.
2296 4 The attempt to read timed out. Note this does not set
2298 ERRNO as this is not a system error.
2299 5 No system error occurred, but zero bytes were read. This
2301 usually indicates end of file. The parameters are set
2302 according to the usual rules; no write to outfd is at‐
2303 tempted.
2304 sysseek [ -u fd ] [ -w start|end|current ] offset
2306 The current file position at which future reads and writes will
2307 take place is adjusted to the specified byte offset. The offset
2308 is evaluated as a math expression. The -u option allows the file
2309 descriptor to be specified. By default the offset is specified
2310 relative to the start or the file but, with the -w option, it is
2311 possible to specify that the offset should be relative to the
2312 current position or the end of the file.
2313 syswrite [ -c countvar ] [ -o outfd ] data
2315 The data (a single string of bytes) are written to the file de‐
2316 scriptor outfd, or 1 if that is not given, using the write sys‐
2317 tem call. Multiple write operations may be used if the first
2318 does not write all the data.
2319 If countvar is given, the number of byte written is stored in
2321 the parameter named by countvar; this may not be the full length
2322 of data if an error occurred.
2323 The error EINTR (interrupted system call) is handled internally
2325 by retrying; otherwise an error causes the command to return.
2326 For example, if the file descriptor is set to non-blocking out‐
2327 put, an error EAGAIN (on some systems, EWOULDBLOCK) may result
2328 in the command returning early.
2329 The return status may be 0 for success, 1 for an error in the
2331 parameters to the command, or 2 for an error on the write; no
2332 error message is printed in the last case, but the parameter ER‐
2333 RNO will reflect the error that occurred.
2334 zsystem flock [ -t timeout ] [ -i interval ] [ -f var ] [-er] file
2336 zsystem flock -u fd_expr
2337 The builtin zsystem's subcommand flock performs advisory file
2338 locking (via the fcntl(2) system call) over the entire contents
2339 of the given file. This form of locking requires the processes
2340 accessing the file to cooperate; its most obvious use is between
2341 two instances of the shell itself.
2342 In the first form the named file, which must already exist, is
2344 locked by opening a file descriptor to the file and applying a
2345 lock to the file descriptor. The lock terminates when the shell
2346 process that created the lock exits; it is therefore often con‐
2347 venient to create file locks within subshells, since the lock is
2348 automatically released when the subshell exits. Note that use
2349 of the print builtin with the -u option will, as a side effect,
2350 release the lock, as will redirection to the file in the shell
2351 holding the lock. To work around this use a subshell, e.g.
2352 `(print message) >> file'. Status 0 is returned if the lock
2353 succeeds, else status 1.
2354 In the second form the file descriptor given by the arithmetic
2356 expression fd_expr is closed, releasing a lock. The file de‐
2357 scriptor can be queried by using the `-f var' form during the
2358 lock; on a successful lock, the shell variable var is set to the
2359 file descriptor used for locking. The lock will be released if
2360 the file descriptor is closed by any other means, for example
2361 using `exec {var}>&-'; however, the form described here performs
2362 a safety check that the file descriptor is in use for file lock‐
2363 ing.
2364 By default the shell waits indefinitely for the lock to succeed.
2366 The option -t timeout specifies a timeout for the lock in sec‐
2367 onds; fractional seconds are allowed. During this period, the
2368 shell will attempt to lock the file every interval seconds if
2369 the -i interval option is given, otherwise once a second. (This
2370 interval is shortened before the last attempt if needed, so that
2371 the shell waits only until the timeout and not longer.) If the
2372 attempt times out, status 2 is returned.
2373 (Note: timeout is limited to 2^30-1 seconds (about 34 years),
2375 and interval to 0.999 * LONG_MAX microseconds (only about 35
2376 minutes on 32-bit systems).)
2377 If the option -e is given, the file descriptor for the lock is
2379 preserved when the shell uses exec to start a new process; oth‐
2380 erwise it is closed at that point and the lock released.
2381 If the option -r is given, the lock is only for reading, other‐
2383 wise it is for reading and writing. The file descriptor is
2384 opened accordingly.
2385 zsystem supports subcommand
2387 The builtin zsystem's subcommand supports tests whether a given
2388 subcommand is supported. It returns status 0 if so, else status
2389 1. It operates silently unless there was a syntax error (i.e.
2390 the wrong number of arguments), in which case status 255 is re‐
2391 turned. Status 1 can indicate one of two things: subcommand is
2392 known but not supported by the current operating system, or sub‐
2393 command is not known (possibly because this is an older version
2394 of the shell before it was implemented).
2395 Math Functions
2397 systell(fd)
2398 The systell math function returns the current file position for
2399 the file descriptor passed as an argument.
2400 Parameters
2402 errnos A readonly array of the names of errors defined on the system.
2403 These are typically macros defined in C by including the system
2404 header file errno.h. The index of each name (assuming the op‐
2405 tion KSH_ARRAYS is unset) corresponds to the error number. Er‐
2406 ror numbers num before the last known error which have no name
2407 are given the name Enum in the array.
2408 Note that aliases for errors are not handled; only the canonical
2410 name is used.
2411 sysparams
2413 A readonly associative array. The keys are:
2414 pid Returns the process ID of the current process, even in
2416 subshells. Compare $$, which returns the process ID of
2417 the main shell process.
2418 ppid Returns the current process ID of the parent of the cur‐
2420 rent process, even in subshells. Compare $PPID, which
2421 returns the process ID of the initial parent of the main
2422 shell process.
2423 procsubstpid
2425 Returns the process ID of the last process started for
2426 process substitution, i.e. the <(...) and >(...) expan‐
2427 sions.
2428
2430 The zsh/net/tcp module makes available one builtin command:
2431 ztcp [ -acflLtv ] [ -d fd ] [ args ]
2433 ztcp is implemented as a builtin to allow full use of shell com‐
2434 mand line editing, file I/O, and job control mechanisms.
2435 If ztcp is run with no options, it will output the contents of
2437 its session table.
2438 If it is run with only the option -L, it will output the con‐
2440 tents of the session table in a format suitable for automatic
2441 parsing. The option is ignored if given with a command to open
2442 or close a session. The output consists of a set of lines, one
2443 per session, each containing the following elements separated by
2444 spaces:
2445 File descriptor
2447 The file descriptor in use for the connection. For nor‐
2448 mal inbound (I) and outbound (O) connections this may be
2449 read and written by the usual shell mechanisms. However,
2450 it should only be close with `ztcp -c'.
2451 Connection type
2453 A letter indicating how the session was created:
2454 Z A session created with the zftp command.
2456 L A connection opened for listening with `ztcp -l'.
2458 I An inbound connection accepted with `ztcp -a'.
2460 O An outbound connection created with `ztcp host
2462 ...'.
2463 The local host
2465 This is usually set to an all-zero IP address as the ad‐
2466 dress of the localhost is irrelevant.
2467 The local port
2469 This is likely to be zero unless the connection is for
2470 listening.
2471 The remote host
2473 This is the fully qualified domain name of the peer, if
2474 available, else an IP address. It is an all-zero IP ad‐
2475 dress for a session opened for listening.
2476 The remote port
2478 This is zero for a connection opened for listening.
2479 Outbound Connections
2481 ztcp [ -v ] [ -d fd ] host [ port ]
2482 Open a new TCP connection to host. If the port is omitted, it
2483 will default to port 23. The connection will be added to the
2484 session table and the shell parameter REPLY will be set to the
2485 file descriptor associated with that connection.
2486 If -d is specified, its argument will be taken as the target
2488 file descriptor for the connection.
2489 In order to elicit more verbose output, use -v.
2491 Inbound Connections
2493 ztcp -l [ -v ] [ -d fd ] port
2494 ztcp -l will open a socket listening on TCP port. The socket
2495 will be added to the session table and the shell parameter REPLY
2496 will be set to the file descriptor associated with that lis‐
2497 tener.
2498 If -d is specified, its argument will be taken as the target
2500 file descriptor for the connection.
2501 In order to elicit more verbose output, use -v.
2503 ztcp -a [ -tv ] [ -d targetfd ] listenfd
2505 ztcp -a will accept an incoming connection to the port associ‐
2506 ated with listenfd. The connection will be added to the session
2507 table and the shell parameter REPLY will be set to the file de‐
2508 scriptor associated with the inbound connection.
2509 If -d is specified, its argument will be taken as the target
2511 file descriptor for the connection.
2512 If -t is specified, ztcp will return if no incoming connection
2514 is pending. Otherwise it will wait for one.
2515 In order to elicit more verbose output, use -v.
2517 Closing Connections
2519 ztcp -cf [ -v ] [ fd ]
2520 ztcp -c [ -v ] [ fd ]
2521 ztcp -c will close the socket associated with fd. The socket
2522 will be removed from the session table. If fd is not specified,
2523 ztcp will close everything in the session table.
2524 Normally, sockets registered by zftp (see zshmodules(1) ) cannot
2526 be closed this way. In order to force such a socket closed, use
2527 -f.
2528 In order to elicit more verbose output, use -v.
2530 Example
2532 Here is how to create a TCP connection between two instances of zsh.
2533 We need to pick an unassigned port; here we use the randomly chosen
2534 5123.
2535 On host1,
2537 zmodload zsh/net/tcp
2538 ztcp -l 5123
2539 listenfd=$REPLY
2540 ztcp -a $listenfd
2541 fd=$REPLY
2542 The second from last command blocks until there is an incoming connec‐
2543 tion.
2544 Now create a connection from host2 (which may, of course, be the same
2546 machine):
2547 zmodload zsh/net/tcp
2548 ztcp host1 5123
2549 fd=$REPLY
2550 Now on each host, $fd contains a file descriptor for talking to the
2552 other. For example, on host1:
2553 print This is a message >&$fd
2554 and on host2:
2555 read -r line <&$fd; print -r - $line
2556 prints `This is a message'.
2557 To tidy up, on host1:
2559 ztcp -c $listenfd
2560 ztcp -c $fd
2561 and on host2
2562 ztcp -c $fd
2563
2565 The zsh/termcap module makes available one builtin command:
2566 echotc cap [ arg ... ]
2568 Output the termcap value corresponding to the capability cap,
2569 with optional arguments.
2570 The zsh/termcap module makes available one parameter:
2572 termcap
2574 An associative array that maps termcap capability codes to their
2575 values.
2576
2578 The zsh/terminfo module makes available one builtin command:
2579 echoti cap [ arg ]
2581 Output the terminfo value corresponding to the capability cap,
2582 instantiated with arg if applicable.
2583 The zsh/terminfo module makes available one parameter:
2585 terminfo
2587 An associative array that maps terminfo capability names to
2588 their values.
2589
2591 The zsh/watch module can be used to report when specific users log in
2592 or out. This is controlled via the following parameters.
2593 LOGCHECK
2595 The interval in seconds between checks for login/logout activity
2596 using the watch parameter.
2597 watch <S> <Z> (WATCH <S>)
2599 An array (colon-separated list) of login/logout events to re‐
2600 port.
2601 If it contains the single word `all', then all login/logout
2603 events are reported. If it contains the single word `notme',
2604 then all events are reported as with `all' except $USERNAME.
2605 An entry in this list may consist of a username, an `@' followed
2607 by a remote hostname, and a `%' followed by a line (tty). Any
2608 of these may be a pattern (be sure to quote this during the as‐
2609 signment to watch so that it does not immediately perform file
2610 generation); the setting of the EXTENDED_GLOB option is re‐
2611 spected. Any or all of these components may be present in an
2612 entry; if a login/logout event matches all of them, it is re‐
2613 ported.
2614 For example, with the EXTENDED_GLOB option set, the following:
2616 watch=('^(pws|barts)')
2618 causes reports for activity associated with any user other than
2620 pws or barts.
2621 WATCHFMT
2623 The format of login/logout reports if the watch parameter is
2624 set. Default is `%n has %a %l from %m'. Recognizes the follow‐
2625 ing escape sequences:
2626 %n The name of the user that logged in/out.
2628 %a The observed action, i.e. "logged on" or "logged off".
2630 %l The line (tty) the user is logged in on.
2632 %M The full hostname of the remote host.
2634 %m The hostname up to the first `.'. If only the IP address
2636 is available or the utmp field contains the name of an
2637 X-windows display, the whole name is printed.
2638 NOTE: The `%m' and `%M' escapes will work only if there
2640 is a host name field in the utmp on your machine. Other‐
2641 wise they are treated as ordinary strings.
2642 %F{color} (%f)
2644 Start (stop) using a different foreground color.
2645 %K{color} (%k)
2647 Start (stop) using a different background color.
2648 %S (%s)
2650 Start (stop) standout mode.
2651 %U (%u)
2653 Start (stop) underline mode.
2654 %B (%b)
2656 Start (stop) boldface mode.
2657 %t
2659 %@ The time, in 12-hour, am/pm format.
2660 %T The time, in 24-hour format.
2662 %w The date in `day-dd' format.
2664 %W The date in `mm/dd/yy' format.
2666 %D The date in `yy-mm-dd' format.
2668 %D{string}
2670 The date formatted as string using the strftime function,
2671 with zsh extensions as described by EXPANSION OF PROMPT
2672 SEQUENCES in zshmisc(1).
2673 %(x:true-text:false-text)
2675 Specifies a ternary expression. The character following
2676 the x is arbitrary; the same character is used to sepa‐
2677 rate the text for the "true" result from that for the
2678 "false" result. Both the separator and the right paren‐
2679 thesis may be escaped with a backslash. Ternary expres‐
2680 sions may be nested.
2681 The test character x may be any one of `l', `n', `m' or
2683 `M', which indicate a `true' result if the corresponding
2684 escape sequence would return a non-empty value; or it may
2685 be `a', which indicates a `true' result if the watched
2686 user has logged in, or `false' if he has logged out.
2687 Other characters evaluate to neither true nor false; the
2688 entire expression is omitted in this case.
2689 If the result is `true', then the true-text is formatted
2691 according to the rules above and printed, and the
2692 false-text is skipped. If `false', the true-text is
2693 skipped and the false-text is formatted and printed. Ei‐
2694 ther or both of the branches may be empty, but both sepa‐
2695 rators must be present in any case.
2696 Furthermore, the zsh/watch module makes available one builtin command:
2698 log List all users currently logged in who are affected by the cur‐
2700 rent setting of the watch parameter.
2701
2703 The zsh/zftp module makes available one builtin command:
2704 zftp subcommand [ args ]
2706 The zsh/zftp module is a client for FTP (file transfer proto‐
2707 col). It is implemented as a builtin to allow full use of shell
2708 command line editing, file I/O, and job control mechanisms. Of‐
2709 ten, users will access it via shell functions providing a more
2710 powerful interface; a set is provided with the zsh distribution
2711 and is described in zshzftpsys(1). However, the zftp command is
2712 entirely usable in its own right.
2713 All commands consist of the command name zftp followed by the
2715 name of a subcommand. These are listed below. The return sta‐
2716 tus of each subcommand is supposed to reflect the success or
2717 failure of the remote operation. See a description of the vari‐
2718 able ZFTP_VERBOSE for more information on how responses from the
2719 server may be printed.
2720 Subcommands
2722 open host[:port] [ user [ password [ account ] ] ]
2723 Open a new FTP session to host, which may be the name of a
2724 TCP/IP connected host or an IP number in the standard dot nota‐
2725 tion. If the argument is in the form host:port, open a connec‐
2726 tion to TCP port port instead of the standard FTP port 21. This
2727 may be the name of a TCP service or a number: see the descrip‐
2728 tion of ZFTP_PORT below for more information.
2729 If IPv6 addresses in colon format are used, the host should be
2731 surrounded by quoted square brackets to distinguish it from the
2732 port, for example '[fe80::203:baff:fe02:8b56]'. For consistency
2733 this is allowed with all forms of host.
2734 Remaining arguments are passed to the login subcommand. Note
2736 that if no arguments beyond host are supplied, open will not au‐
2737 tomatically call login. If no arguments at all are supplied,
2738 open will use the parameters set by the params subcommand.
2739 After a successful open, the shell variables ZFTP_HOST,
2741 ZFTP_PORT, ZFTP_IP and ZFTP_SYSTEM are available; see `Vari‐
2742 ables' below.
2743 login [ name [ password [ account ] ] ]
2745 user [ name [ password [ account ] ] ]
2746 Login the user name with parameters password and account. Any
2747 of the parameters can be omitted, and will be read from standard
2748 input if needed (name is always needed). If standard input is a
2749 terminal, a prompt for each one will be printed on standard er‐
2750 ror and password will not be echoed. If any of the parameters
2751 are not used, a warning message is printed.
2752 After a successful login, the shell variables ZFTP_USER,
2754 ZFTP_ACCOUNT and ZFTP_PWD are available; see `Variables' below.
2755 This command may be re-issued when a user is already logged in,
2757 and the server will first be reinitialized for a new user.
2758 params [ host [ user [ password [ account ] ] ] ]
2760 params -
2761 Store the given parameters for a later open command with no ar‐
2762 guments. Only those given on the command line will be remem‐
2763 bered. If no arguments are given, the parameters currently set
2764 are printed, although the password will appear as a line of
2765 stars; the return status is one if no parameters were set, zero
2766 otherwise.
2767 Any of the parameters may be specified as a `?', which may need
2769 to be quoted to protect it from shell expansion. In this case,
2770 the appropriate parameter will be read from stdin as with the
2771 login subcommand, including special handling of password. If
2772 the `?' is followed by a string, that is used as the prompt for
2773 reading the parameter instead of the default message (any neces‐
2774 sary punctuation and whitespace should be included at the end of
2775 the prompt). The first letter of the parameter (only) may be
2776 quoted with a `\'; hence an argument "\\$word" guarantees that
2777 the string from the shell parameter $word will be treated liter‐
2778 ally, whether or not it begins with a `?'.
2779 If instead a single `-' is given, the existing parameters, if
2781 any, are deleted. In that case, calling open with no arguments
2782 will cause an error.
2783 The list of parameters is not deleted after a close, however it
2785 will be deleted if the zsh/zftp module is unloaded.
2786 For example,
2788 zftp params ftp.elsewhere.xx juser '?Password for juser: '
2790 will store the host ftp.elsewhere.xx and the user juser and then
2792 prompt the user for the corresponding password with the given
2793 prompt.
2794 test Test the connection; if the server has reported that it has
2796 closed the connection (maybe due to a timeout), return status 2;
2797 if no connection was open anyway, return status 1; else return
2798 status 0. The test subcommand is silent, apart from messages
2799 printed by the $ZFTP_VERBOSE mechanism, or error messages if the
2800 connection closes. There is no network overhead for this test.
2801 The test is only supported on systems with either the select(2)
2803 or poll(2) system calls; otherwise the message `not supported on
2804 this system' is printed instead.
2805 The test subcommand will automatically be called at the start of
2807 any other subcommand for the current session when a connection
2808 is open.
2809 cd directory
2811 Change the remote directory to directory. Also alters the shell
2812 variable ZFTP_PWD.
2813 cdup Change the remote directory to the one higher in the directory
2815 tree. Note that cd .. will also work correctly on non-UNIX sys‐
2816 tems.
2817 dir [ arg ... ]
2819 Give a (verbose) listing of the remote directory. The args are
2820 passed directly to the server. The command's behaviour is imple‐
2821 mentation dependent, but a UNIX server will typically interpret
2822 args as arguments to the ls command and with no arguments return
2823 the result of `ls -l'. The directory is listed to standard out‐
2824 put.
2825 ls [ arg ... ]
2827 Give a (short) listing of the remote directory. With no arg,
2828 produces a raw list of the files in the directory, one per line.
2829 Otherwise, up to vagaries of the server implementation, behaves
2830 similar to dir.
2831 type [ type ]
2833 Change the type for the transfer to type, or print the current
2834 type if type is absent. The allowed values are `A' (ASCII), `I'
2835 (Image, i.e. binary), or `B' (a synonym for `I').
2836 The FTP default for a transfer is ASCII. However, if zftp finds
2838 that the remote host is a UNIX machine with 8-bit byes, it will
2839 automatically switch to using binary for file transfers upon
2840 open. This can subsequently be overridden.
2841 The transfer type is only passed to the remote host when a data
2843 connection is established; this command involves no network
2844 overhead.
2845 ascii The same as type A.
2847 binary The same as type I.
2849 mode [ S | B ]
2851 Set the mode type to stream (S) or block (B). Stream mode is
2852 the default; block mode is not widely supported.
2853 remote file ...
2855 local [ file ... ]
2856 Print the size and last modification time of the remote or local
2857 files. If there is more than one item on the list, the name of
2858 the file is printed first. The first number is the file size,
2859 the second is the last modification time of the file in the for‐
2860 mat CCYYMMDDhhmmSS consisting of year, month, date, hour, min‐
2861 utes and seconds in GMT. Note that this format, including the
2862 length, is guaranteed, so that time strings can be directly com‐
2863 pared via the [[ builtin's < and > operators, even if they are
2864 too long to be represented as integers.
2865 Not all servers support the commands for retrieving this infor‐
2867 mation. In that case, the remote command will print nothing and
2868 return status 2, compared with status 1 for a file not found.
2869 The local command (but not remote) may be used with no argu‐
2871 ments, in which case the information comes from examining file
2872 descriptor zero. This is the same file as seen by a put command
2873 with no further redirection.
2874 get file ...
2876 Retrieve all files from the server, concatenating them and send‐
2877 ing them to standard output.
2878 put file ...
2880 For each file, read a file from standard input and send that to
2881 the remote host with the given name.
2882 append file ...
2884 As put, but if the remote file already exists, data is appended
2885 to it instead of overwriting it.
2886 getat file point
2888 putat file point
2889 appendat file point
2890 Versions of get, put and append which will start the transfer at
2891 the given point in the remote file. This is useful for append‐
2892 ing to an incomplete local file. However, note that this abil‐
2893 ity is not universally supported by servers (and is not quite
2894 the behaviour specified by the standard).
2895 delete file ...
2897 Delete the list of files on the server.
2898 mkdir directory
2900 Create a new directory directory on the server.
2901 rmdir directory
2903 Delete the directory directory on the server.
2904 rename old-name new-name
2906 Rename file old-name to new-name on the server.
2907 site arg ...
2909 Send a host-specific command to the server. You will probably
2910 only need this if instructed by the server to use it.
2911 quote arg ...
2913 Send the raw FTP command sequence to the server. You should be
2914 familiar with the FTP command set as defined in RFC959 before
2915 doing this. Useful commands may include STAT and HELP. Note
2916 also the mechanism for returning messages as described for the
2917 variable ZFTP_VERBOSE below, in particular that all messages
2918 from the control connection are sent to standard error.
2919 close
2921 quit Close the current data connection. This unsets the shell param‐
2922 eters ZFTP_HOST, ZFTP_PORT, ZFTP_IP, ZFTP_SYSTEM, ZFTP_USER,
2923 ZFTP_ACCOUNT, ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE.
2924 session [ sessname ]
2926 Allows multiple FTP sessions to be used at once. The name of
2927 the session is an arbitrary string of characters; the default
2928 session is called `default'. If this command is called without
2929 an argument, it will list all the current sessions; with an ar‐
2930 gument, it will either switch to the existing session called
2931 sessname, or create a new session of that name.
2932 Each session remembers the status of the connection, the set of
2934 connection-specific shell parameters (the same set as are unset
2935 when a connection closes, as given in the description of close),
2936 and any user parameters specified with the params subcommand.
2937 Changing to a previous session restores those values; changing
2938 to a new session initialises them in the same way as if zftp had
2939 just been loaded. The name of the current session is given by
2940 the parameter ZFTP_SESSION.
2941 rmsession [ sessname ]
2943 Delete a session; if a name is not given, the current session is
2944 deleted. If the current session is deleted, the earliest exist‐
2945 ing session becomes the new current session, otherwise the cur‐
2946 rent session is not changed. If the session being deleted is
2947 the only one, a new session called `default' is created and be‐
2948 comes the current session; note that this is a new session even
2949 if the session being deleted is also called `default'. It is
2950 recommended that sessions not be deleted while background com‐
2951 mands which use zftp are still active.
2952 Parameters
2954 The following shell parameters are used by zftp. Currently none of
2955 them are special.
2956 ZFTP_TMOUT
2958 Integer. The time in seconds to wait for a network operation to
2959 complete before returning an error. If this is not set when the
2960 module is loaded, it will be given the default value 60. A
2961 value of zero turns off timeouts. If a timeout occurs on the
2962 control connection it will be closed. Use a larger value if
2963 this occurs too frequently.
2964 ZFTP_IP
2966 Readonly. The IP address of the current connection in dot nota‐
2967 tion.
2968 ZFTP_HOST
2970 Readonly. The hostname of the current remote server. If the
2971 host was opened as an IP number, ZFTP_HOST contains that in‐
2972 stead; this saves the overhead for a name lookup, as IP numbers
2973 are most commonly used when a nameserver is unavailable.
2974 ZFTP_PORT
2976 Readonly. The number of the remote TCP port to which the con‐
2977 nection is open (even if the port was originally specified as a
2978 named service). Usually this is the standard FTP port, 21.
2979 In the unlikely event that your system does not have the appro‐
2981 priate conversion functions, this appears in network byte order.
2982 If your system is little-endian, the port then consists of two
2983 swapped bytes and the standard port will be reported as 5376.
2984 In that case, numeric ports passed to zftp open will also need
2985 to be in this format.
2986 ZFTP_SYSTEM
2988 Readonly. The system type string returned by the server in re‐
2989 sponse to an FTP SYST request. The most interesting case is a
2990 string beginning "UNIX Type: L8", which ensures maximum compati‐
2991 bility with a local UNIX host.
2992 ZFTP_TYPE
2994 Readonly. The type to be used for data transfers , either `A'
2995 or `I'. Use the type subcommand to change this.
2996 ZFTP_USER
2998 Readonly. The username currently logged in, if any.
2999 ZFTP_ACCOUNT
3001 Readonly. The account name of the current user, if any. Most
3002 servers do not require an account name.
3003 ZFTP_PWD
3005 Readonly. The current directory on the server.
3006 ZFTP_CODE
3008 Readonly. The three digit code of the last FTP reply from the
3009 server as a string. This can still be read after the connection
3010 is closed, and is not changed when the current session changes.
3011 ZFTP_REPLY
3013 Readonly. The last line of the last reply sent by the server.
3014 This can still be read after the connection is closed, and is
3015 not changed when the current session changes.
3016 ZFTP_SESSION
3018 Readonly. The name of the current FTP session; see the descrip‐
3019 tion of the session subcommand.
3020 ZFTP_PREFS
3022 A string of preferences for altering aspects of zftp's behav‐
3023 iour. Each preference is a single character. The following are
3024 defined:
3025 P Passive: attempt to make the remote server initiate data
3027 transfers. This is slightly more efficient than sendport
3028 mode. If the letter S occurs later in the string, zftp
3029 will use sendport mode if passive mode is not available.
3030 S Sendport: initiate transfers by the FTP PORT command.
3032 If this occurs before any P in the string, passive mode
3033 will never be attempted.
3034 D Dumb: use only the bare minimum of FTP commands. This
3036 prevents the variables ZFTP_SYSTEM and ZFTP_PWD from be‐
3037 ing set, and will mean all connections default to ASCII
3038 type. It may prevent ZFTP_SIZE from being set during a
3039 transfer if the server does not send it anyway (many
3040 servers do).
3041 If ZFTP_PREFS is not set when zftp is loaded, it will be set to
3043 a default of `PS', i.e. use passive mode if available, otherwise
3044 fall back to sendport mode.
3045 ZFTP_VERBOSE
3047 A string of digits between 0 and 5 inclusive, specifying which
3048 responses from the server should be printed. All responses go
3049 to standard error. If any of the numbers 1 to 5 appear in the
3050 string, raw responses from the server with reply codes beginning
3051 with that digit will be printed to standard error. The first
3052 digit of the three digit reply code is defined by RFC959 to cor‐
3053 respond to:
3054 1. A positive preliminary reply.
3056 2. A positive completion reply.
3058 3. A positive intermediate reply.
3060 4. A transient negative completion reply.
3062 5. A permanent negative completion reply.
3064 It should be noted that, for unknown reasons, the reply `Service
3066 not available', which forces termination of a connection, is
3067 classified as 421, i.e. `transient negative', an interesting in‐
3068 terpretation of the word `transient'.
3069 The code 0 is special: it indicates that all but the last line
3071 of multiline replies read from the server will be printed to
3072 standard error in a processed format. By convention, servers
3073 use this mechanism for sending information for the user to read.
3074 The appropriate reply code, if it matches the same response,
3075 takes priority.
3076 If ZFTP_VERBOSE is not set when zftp is loaded, it will be set
3078 to the default value 450, i.e., messages destined for the user
3079 and all errors will be printed. A null string is valid and
3080 specifies that no messages should be printed.
3081 Functions
3083 zftp_chpwd
3084 If this function is set by the user, it is called every time the
3085 directory changes on the server, including when a user is logged
3086 in, or when a connection is closed. In the last case, $ZFTP_PWD
3087 will be unset; otherwise it will reflect the new directory.
3088 zftp_progress
3090 If this function is set by the user, it will be called during a
3091 get, put or append operation each time sufficient data has been
3092 received from the host. During a get, the data is sent to stan‐
3093 dard output, so it is vital that this function should write to
3094 standard error or directly to the terminal, not to standard out‐
3095 put.
3096 When it is called with a transfer in progress, the following ad‐
3098 ditional shell parameters are set:
3099 ZFTP_FILE
3101 The name of the remote file being transferred from or to.
3102 ZFTP_TRANSFER
3104 A G for a get operation and a P for a put operation.
3105 ZFTP_SIZE
3107 The total size of the complete file being transferred:
3108 the same as the first value provided by the remote and
3109 local subcommands for a particular file. If the server
3110 cannot supply this value for a remote file being re‐
3111 trieved, it will not be set. If input is from a pipe the
3112 value may be incorrect and correspond simply to a full
3113 pipe buffer.
3114 ZFTP_COUNT
3116 The amount of data so far transferred; a number between
3117 zero and $ZFTP_SIZE, if that is set. This number is al‐
3118 ways available.
3119 The function is initially called with ZFTP_TRANSFER set appro‐
3121 priately and ZFTP_COUNT set to zero. After the transfer is fin‐
3122 ished, the function will be called one more time with
3123 ZFTP_TRANSFER set to GF or PF, in case it wishes to tidy up. It
3124 is otherwise never called twice with the same value of
3125 ZFTP_COUNT.
3126 Sometimes the progress meter may cause disruption. It is up to
3128 the user to decide whether the function should be defined and to
3129 use unfunction when necessary.
3130 Problems
3132 A connection may not be opened in the left hand side of a pipe as this
3133 occurs in a subshell and the file information is not updated in the
3134 main shell. In the case of type or mode changes or closing the connec‐
3135 tion in a subshell, the information is returned but variables are not
3136 updated until the next call to zftp. Other status changes in subshells
3137 will not be reflected by changes to the variables (but should be other‐
3138 wise harmless).
3139 Deleting sessions while a zftp command is active in the background can
3141 have unexpected effects, even if it does not use the session being
3142 deleted. This is because all shell subprocesses share information on
3143 the state of all connections, and deleting a session changes the order‐
3144 ing of that information.
3145 On some operating systems, the control connection is not valid after a
3147 fork(), so that operations in subshells, on the left hand side of a
3148 pipeline, or in the background are not possible, as they should be.
3149 This is presumably a bug in the operating system.
3150
3152 The zsh/zle module contains the Zsh Line Editor. See zshzle(1).
3153
3155 The zsh/zleparameter module defines two special parameters that can be
3156 used to access internal information of the Zsh Line Editor (see zsh‐
3157 zle(1)).
3158 keymaps
3160 This array contains the names of the keymaps currently defined.
3161 widgets
3163 This associative array contains one entry per widget. The name
3164 of the widget is the key and the value gives information about
3165 the widget. It is either
3166 the string `builtin' for builtin widgets,
3167 a string of the form `user:name' for user-defined widgets,
3168 where name is the name of the shell function implementing
3169 the widget,
3170 a string of the form `completion:type:name'
3171 for completion widgets,
3172 or a null value if the widget is not yet fully defined. In
3173 the penultimate case, type is the name of the builtin widget the
3174 completion widget imitates in its behavior and name is the name
3175 of the shell function implementing the completion widget.
3176
3178 When loaded, the zsh/zprof causes shell functions to be profiled. The
3179 profiling results can be obtained with the zprof builtin command made
3180 available by this module. There is no way to turn profiling off other
3181 than unloading the module.
3182 zprof [ -c ]
3184 Without the -c option, zprof lists profiling results to standard
3185 output. The format is comparable to that of commands like
3186 gprof.
3187 At the top there is a summary listing all functions that were
3189 called at least once. This summary is sorted in decreasing or‐
3190 der of the amount of time spent in each. The lines contain the
3191 number of the function in order, which is used in other parts of
3192 the list in suffixes of the form `[num]', then the number of
3193 calls made to the function. The next three columns list the
3194 time in milliseconds spent in the function and its descendants,
3195 the average time in milliseconds spent in the function and its
3196 descendants per call and the percentage of time spent in all
3197 shell functions used in this function and its descendants. The
3198 following three columns give the same information, but counting
3199 only the time spent in the function itself. The final column
3200 shows the name of the function.
3201 After the summary, detailed information about every function
3203 that was invoked is listed, sorted in decreasing order of the
3204 amount of time spent in each function and its descendants. Each
3205 of these entries consists of descriptions for the functions that
3206 called the function described, the function itself, and the
3207 functions that were called from it. The description for the
3208 function itself has the same format as in the summary (and shows
3209 the same information). The other lines don't show the number of
3210 the function at the beginning and have their function named in‐
3211 dented to make it easier to distinguish the line showing the
3212 function described in the section from the surrounding lines.
3213 The information shown in this case is almost the same as in the
3215 summary, but only refers to the call hierarchy being displayed.
3216 For example, for a calling function the column showing the total
3217 running time lists the time spent in the described function and
3218 its descendants only for the times when it was called from that
3219 particular calling function. Likewise, for a called function,
3220 this columns lists the total time spent in the called function
3221 and its descendants only for the times when it was called from
3222 the function described.
3223 Also in this case, the column showing the number of calls to a
3225 function also shows a slash and then the total number of invoca‐
3226 tions made to the called function.
3227 As long as the zsh/zprof module is loaded, profiling will be
3229 done and multiple invocations of the zprof builtin command will
3230 show the times and numbers of calls since the module was loaded.
3231 With the -c option, the zprof builtin command will reset its in‐
3232 ternal counters and will not show the listing.
3233
3235 The zsh/zpty module offers one builtin:
3236 zpty [ -e ] [ -b ] name [ arg ... ]
3238 The arguments following name are concatenated with spaces be‐
3239 tween, then executed as a command, as if passed to the eval
3240 builtin. The command runs under a newly assigned pseudo-termi‐
3241 nal; this is useful for running commands non-interactively which
3242 expect an interactive environment. The name is not part of the
3243 command, but is used to refer to this command in later calls to
3244 zpty.
3245 With the -e option, the pseudo-terminal is set up so that input
3247 characters are echoed.
3248 With the -b option, input to and output from the pseudo-terminal
3250 are made non-blocking.
3251 The shell parameter REPLY is set to the file descriptor assigned
3253 to the master side of the pseudo-terminal. This allows the ter‐
3254 minal to be monitored with ZLE descriptor handlers (see zsh‐
3255 zle(1)) or manipulated with sysread and syswrite (see THE
3256 ZSH/SYSTEM MODULE in zshmodules(1)). Warning: Use of sysread
3257 and syswrite is not recommended; use zpty -r and zpty -w unless
3258 you know exactly what you are doing.
3259 zpty -d [ name ... ]
3261 The second form, with the -d option, is used to delete commands
3262 previously started, by supplying a list of their names. If no
3263 name is given, all commands are deleted. Deleting a command
3264 causes the HUP signal to be sent to the corresponding process.
3265 zpty -w [ -n ] name [ string ... ]
3267 The -w option can be used to send the to command name the given
3268 strings as input (separated by spaces). If the -n option is not
3269 given, a newline is added at the end.
3270 If no string is provided, the standard input is copied to the
3272 pseudo-terminal; this may stop before copying the full input if
3273 the pseudo-terminal is non-blocking. The exact input is always
3274 copied: the -n option is not applied.
3275 Note that the command under the pseudo-terminal sees this input
3277 as if it were typed, so beware when sending special tty driver
3278 characters such as word-erase, line-kill, and end-of-file.
3279 zpty -r [ -mt ] name [ param [ pattern ] ]
3281 The -r option can be used to read the output of the command
3282 name. With only a name argument, the output read is copied to
3283 the standard output. Unless the pseudo-terminal is non-block‐
3284 ing, copying continues until the command under the pseudo-termi‐
3285 nal exits; when non-blocking, only as much output as is immedi‐
3286 ately available is copied. The return status is zero if any
3287 output is copied.
3288 When also given a param argument, at most one line is read and
3290 stored in the parameter named param. Less than a full line may
3291 be read if the pseudo-terminal is non-blocking. The return sta‐
3292 tus is zero if at least one character is stored in param.
3293 If a pattern is given as well, output is read until the whole
3295 string read matches the pattern, even in the non-blocking case.
3296 The return status is zero if the string read matches the pat‐
3297 tern, or if the command has exited but at least one character
3298 could still be read. If the option -m is present, the return
3299 status is zero only if the pattern matches. As of this writing,
3300 a maximum of one megabyte of output can be consumed this way; if
3301 a full megabyte is read without matching the pattern, the return
3302 status is non-zero.
3303 In all cases, the return status is non-zero if nothing could be
3305 read, and is 2 if this is because the command has finished.
3306 If the -r option is combined with the -t option, zpty tests
3308 whether output is available before trying to read. If no output
3309 is available, zpty immediately returns the status 1. When used
3310 with a pattern, the behaviour on a failed poll is similar to
3311 when the command has exited: the return value is zero if at
3312 least one character could still be read even if the pattern
3313 failed to match.
3314 zpty -t name
3316 The -t option without the -r option can be used to test whether
3317 the command name is still running. It returns a zero status if
3318 the command is running and a non-zero value otherwise.
3319 zpty [ -L ]
3321 The last form, without any arguments, is used to list the com‐
3322 mands currently defined. If the -L option is given, this is
3323 done in the form of calls to the zpty builtin.
3324
3326 The zsh/zselect module makes available one builtin command:
3327 zselect [ -rwe ] [ -t timeout ] [ -a array ] [ -A assoc ] [ fd ... ]
3329 The zselect builtin is a front-end to the `select' system call,
3330 which blocks until a file descriptor is ready for reading or
3331 writing, or has an error condition, with an optional timeout.
3332 If this is not available on your system, the command prints an
3333 error message and returns status 2 (normal errors return status
3334 1). For more information, see your system's documentation for
3335 select(3). Note there is no connection with the shell builtin
3336 of the same name.
3337 Arguments and options may be intermingled in any order. Non-op‐
3339 tion arguments are file descriptors, which must be decimal inte‐
3340 gers. By default, file descriptors are to be tested for read‐
3341 ing, i.e. zselect will return when data is available to be read
3342 from the file descriptor, or more precisely, when a read opera‐
3343 tion from the file descriptor will not block. After a -r, -w
3344 and -e, the given file descriptors are to be tested for reading,
3345 writing, or error conditions. These options and an arbitrary
3346 list of file descriptors may be given in any order.
3347 (The presence of an `error condition' is not well defined in the
3349 documentation for many implementations of the select system
3350 call. According to recent versions of the POSIX specification,
3351 it is really an exception condition, of which the only standard
3352 example is out-of-band data received on a socket. So zsh users
3353 are unlikely to find the -e option useful.)
3354 The option `-t timeout' specifies a timeout in hundredths of a
3356 second. This may be zero, in which case the file descriptors
3357 will simply be polled and zselect will return immediately. It
3358 is possible to call zselect with no file descriptors and a
3359 non-zero timeout for use as a finer-grained replacement for
3360 `sleep'; note, however, the return status is always 1 for a
3361 timeout.
3362 The option `-a array' indicates that array should be set to in‐
3364 dicate the file descriptor(s) which are ready. If the option is
3365 not given, the array reply will be used for this purpose. The
3366 array will contain a string similar to the arguments for zse‐
3367 lect. For example,
3368 zselect -t 0 -r 0 -w 1
3370 might return immediately with status 0 and $reply containing `-r
3372 0 -w 1' to show that both file descriptors are ready for the re‐
3373 quested operations.
3374 The option `-A assoc' indicates that the associative array assoc
3376 should be set to indicate the file descriptor(s) which are
3377 ready. This option overrides the option -a, nor will reply be
3378 modified. The keys of assoc are the file descriptors, and the
3379 corresponding values are any of the characters `rwe' to indicate
3380 the condition.
3381 The command returns status 0 if some file descriptors are ready
3383 for reading. If the operation timed out, or a timeout of 0 was
3384 given and no file descriptors were ready, or there was an error,
3385 it returns status 1 and the array will not be set (nor modified
3386 in any way). If there was an error in the select operation the
3387 appropriate error message is printed.
3388
3390 The zsh/zutil module only adds some builtins:
3391 zstyle [ -L [ metapattern [ style ] ] ]
3393 zstyle [ -e | - | -- ] pattern style string ...
3394 zstyle -d [ pattern [ style ... ] ]
3395 zstyle -g name [ pattern [ style ] ]
3396 zstyle -{a|b|s} context style name [ sep ]
3397 zstyle -{T|t} context style [ string ... ]
3398 zstyle -m context style pattern
3399 This builtin command is used to define and lookup styles.
3400 Styles are pairs of names and values, where the values consist
3401 of any number of strings. They are stored together with pat‐
3402 terns and lookup is done by giving a string, called the `con‐
3403 text', which is matched against the patterns. The definition
3404 stored for the most specific pattern that matches will be re‐
3405 turned.
3406 A pattern is considered to be more specific than another if it
3408 contains more components (substrings separated by colons) or if
3409 the patterns for the components are more specific, where simple
3410 strings are considered to be more specific than patterns and
3411 complex patterns are considered to be more specific than the
3412 pattern `*'. A `*' in the pattern will match zero or more char‐
3413 acters in the context; colons are not treated specially in this
3414 regard. If two patterns are equally specific, the tie is broken
3415 in favour of the pattern that was defined first.
3416 Example
3418 For example, a fictional `weather' plugin might state in its
3420 documentation that it looks up the preferred-precipitation style
3421 under the `:weather:continent:day-of-the-week:phase-of-the-moon'
3422 context. According to this, you might set the following in your
3423 zshrc:
3424 zstyle ':weather:europe:*' preferred-precipitation rain
3426 zstyle ':weather:*:Sunday:*' preferred-precipitation snow
3427 Then the plugin would run under the hood a command such as
3429 zstyle -s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred-precipitation REPLY
3431 in order to retrieve your preference into the scalar variable
3433 $REPLY. On Sundays $REPLY would be set to `snow'; in Europe it
3434 would be set to `rain'; and on Sundays in Europe it would be set
3435 to `snow' again, because the patterns `:weather:europe:*' and
3436 `:weather:*:Sunday:*' both match the context argument to zstyle
3437 -s, are equally specific, and the latter is more specific (be‐
3438 cause it has more colon-separated components).
3439 Usage
3441 The forms that operate on patterns are the following.
3443 zstyle [ -L [ metapattern [ style ] ] ]
3445 Without arguments, lists style definitions. Styles are
3446 shown in alphabetic order and patterns are shown in the
3447 order zstyle will test them.
3448 If the -L option is given, listing is done in the form of
3450 calls to zstyle. The optional first argument, metapat‐
3451 tern, is a pattern which will be matched against the
3452 string supplied as pattern when the style was defined.
3453 Note: this means, for example, `zstyle -L ":comple‐
3454 tion:*"' will match any supplied pattern beginning `:com‐
3455 pletion:', not just ":completion:*": use ':comple‐
3456 tion:\*' to match that. The optional second argument
3457 limits the output to a specific style (not a pattern).
3458 -L is not compatible with any other options.
3459 zstyle [ - | -- | -e ] pattern style string ...
3461 Defines the given style for the pattern with the strings
3462 as the value. If the -e option is given, the strings
3463 will be concatenated (separated by spaces) and the re‐
3464 sulting string will be evaluated (in the same way as it
3465 is done by the eval builtin command) when the style is
3466 looked up. In this case the parameter `reply' must be
3467 assigned to set the strings returned after the evalua‐
3468 tion. Before evaluating the value, reply is unset, and
3469 if it is still unset after the evaluation, the style is
3470 treated as if it were not set.
3471 zstyle -d [ pattern [ style ... ] ]
3473 Delete style definitions. Without arguments all defini‐
3474 tions are deleted, with a pattern all definitions for
3475 that pattern are deleted and if any styles are given,
3476 then only those styles are deleted for the pattern.
3477 zstyle -g name [ pattern [ style ] ]
3479 Retrieve a style definition. The name is used as the name
3480 of an array in which the results are stored. Without any
3481 further arguments, all patterns defined are returned.
3482 With a pattern the styles defined for that pattern are
3483 returned and with both a pattern and a style, the value
3484 strings of that combination is returned.
3485 The other forms can be used to look up or test styles for a
3487 given context.
3488 zstyle -s context style name [ sep ]
3490 The parameter name is set to the value of the style in‐
3491 terpreted as a string. If the value contains several
3492 strings they are concatenated with spaces (or with the
3493 sep string if that is given) between them.
3494 Return 0 if the style is set, 1 otherwise.
3496 zstyle -b context style name
3498 The value is stored in name as a boolean, i.e. as the
3499 string `yes' if the value has only one string and that
3500 string is equal to one of `yes', `true', `on', or `1'. If
3501 the value is any other string or has more than one
3502 string, the parameter is set to `no'.
3503 Return 0 if name is set to `yes', 1 otherwise.
3505 zstyle -a context style name
3507 The value is stored in name as an array. If name is de‐
3508 clared as an associative array, the first, third, etc.
3509 strings are used as the keys and the other strings are
3510 used as the values.
3511 Return 0 if the style is set, 1 otherwise.
3513 zstyle -t context style [ string ... ]
3515 zstyle -T context style [ string ... ]
3516 Test the value of a style, i.e. the -t option only re‐
3517 turns a status (sets $?). Without any string the return
3518 status is zero if the style is defined for at least one
3519 matching pattern, has only one string in its value, and
3520 that is equal to one of `true', `yes', `on' or `1'. If
3521 any strings are given the status is zero if and only if
3522 at least one of the strings is equal to at least one of
3523 the strings in the value. If the style is defined but
3524 doesn't match, the return status is 1. If the style is
3525 not defined, the status is 2.
3526 The -T option tests the values of the style like -t, but
3528 it returns status zero (rather than 2) if the style is
3529 not defined for any matching pattern.
3530 zstyle -m context style pattern
3532 Match a value. Returns status zero if the pattern matches
3533 at least one of the strings in the value.
3534 zformat -f param format spec ...
3536 zformat -F param format spec ...
3537 zformat -a array sep spec ...
3538 This builtin provides different forms of formatting. The first
3539 form is selected with the -f option. In this case the format
3540 string will be modified by replacing sequences starting with a
3541 percent sign in it with strings from the specs. Each spec
3542 should be of the form `char:string' which will cause every ap‐
3543 pearance of the sequence `%char' in format to be replaced by the
3544 string. The `%' sequence may also contain optional minimum and
3545 maximum field width specifications between the `%' and the
3546 `char' in the form `%min.maxc', i.e. the minimum field width is
3547 given first and if the maximum field width is used, it has to be
3548 preceded by a dot. Specifying a minimum field width makes the
3549 result be padded with spaces to the right if the string is
3550 shorter than the requested width. Padding to the left can be
3551 achieved by giving a negative minimum field width. If a maximum
3552 field width is specified, the string will be truncated after
3553 that many characters. After all `%' sequences for the given
3554 specs have been processed, the resulting string is stored in the
3555 parameter param.
3556 The %-escapes also understand ternary expressions in the form
3558 used by prompts. The % is followed by a `(' and then an ordi‐
3559 nary format specifier character as described above. There may
3560 be a set of digits either before or after the `('; these specify
3561 a test number, which defaults to zero. Negative numbers are
3562 also allowed. An arbitrary delimiter character follows the for‐
3563 mat specifier, which is followed by a piece of `true' text, the
3564 delimiter character again, a piece of `false' text, and a clos‐
3565 ing parenthesis. The complete expression (without the digits)
3566 thus looks like `%(X.text1.text2)', except that the `.' charac‐
3567 ter is arbitrary. The value given for the format specifier in
3568 the char:string expressions is evaluated as a mathematical ex‐
3569 pression, and compared with the test number. If they are the
3570 same, text1 is output, else text2 is output. A parenthesis may
3571 be escaped in text2 as %). Either of text1 or text2 may contain
3572 nested %-escapes.
3573 For example:
3575 zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3
3577 outputs "The answer is 'yes'." to REPLY since the value for the
3579 format specifier c is 3, agreeing with the digit argument to the
3580 ternary expression.
3581 With -F instead of -f, ternary expressions choose between the
3583 `true' or `false' text on the basis of whether the format speci‐
3584 fier is present and non-empty. A test number indicates a mini‐
3585 mum width for the value given in the format specifier. Negative
3586 numbers reverse this, so the test is for whether the value ex‐
3587 ceeds a maximum width.
3588 The form, using the -a option, can be used for aligning strings.
3590 Here, the specs are of the form `left:right' where `left' and
3591 `right' are arbitrary strings. These strings are modified by
3592 replacing the colons by the sep string and padding the left
3593 strings with spaces to the right so that the sep strings in the
3594 result (and hence the right strings after them) are all aligned
3595 if the strings are printed below each other. All strings with‐
3596 out a colon are left unchanged and all strings with an empty
3597 right string have the trailing colon removed. In both cases the
3598 lengths of the strings are not used to determine how the other
3599 strings are to be aligned. A colon in the left string can be
3600 escaped with a backslash. The resulting strings are stored in
3601 the array.
3602 zregexparse
3604 This implements some internals of the _regex_arguments function.
3605 zparseopts [ -D -E -F -K -M ] [ -a array ] [ -A assoc ] [ - ] spec ...
3607 This builtin simplifies the parsing of options in positional pa‐
3608 rameters, i.e. the set of arguments given by $*. Each spec de‐
3609 scribes one option and must be of the form `opt[=array]'. If an
3610 option described by opt is found in the positional parameters it
3611 is copied into the array specified with the -a option; if the
3612 optional `=array' is given, it is instead copied into that ar‐
3613 ray, which should be declared as a normal array and never as an
3614 associative array.
3615 Note that it is an error to give any spec without an `=array'
3617 unless one of the -a or -A options is used.
3618 Unless the -E option is given, parsing stops at the first string
3620 that isn't described by one of the specs. Even with -E, parsing
3621 always stops at a positional parameter equal to `-' or `--'. See
3622 also -F.
3623 The opt description must be one of the following. Any of the
3625 special characters can appear in the option name provided it is
3626 preceded by a backslash.
3627 name
3629 name+ The name is the name of the option without the leading
3630 `-'. To specify a GNU-style long option, one of the
3631 usual two leading `-' must be included in name; for exam‐
3632 ple, a `--file' option is represented by a name of
3633 `-file'.
3634 If a `+' appears after name, the option is appended to
3636 array each time it is found in the positional parameters;
3637 without the `+' only the last occurrence of the option is
3638 preserved.
3639 If one of these forms is used, the option takes no argu‐
3641 ment, so parsing stops if the next positional parameter
3642 does not also begin with `-' (unless the -E option is
3643 used).
3644 name:
3646 name:-
3647 name:: If one or two colons are given, the option takes an argu‐
3648 ment; with one colon, the argument is mandatory and with
3649 two colons it is optional. The argument is appended to
3650 the array after the option itself.
3651 An optional argument is put into the same array element
3653 as the option name (note that this makes empty strings as
3654 arguments indistinguishable). A mandatory argument is
3655 added as a separate element unless the `:-' form is used,
3656 in which case the argument is put into the same element.
3657 A `+' as described above may appear between the name and
3659 the first colon.
3660 In all cases, option-arguments must appear either immediately
3662 following the option in the same positional parameter or in the
3663 next one. Even an optional argument may appear in the next pa‐
3664 rameter, unless it begins with a `-'. There is no special han‐
3665 dling of `=' as with GNU-style argument parsers; given the spec
3666 `-foo:', the positional parameter `--foo=bar' is parsed as
3667 `--foo' with an argument of `=bar'.
3668 When the names of two options that take no arguments overlap,
3670 the longest one wins, so that parsing for the specs `-foo -foo‐
3671 bar' (for example) is unambiguous. However, due to the aforemen‐
3672 tioned handling of option-arguments, ambiguities may arise when
3673 at least one overlapping spec takes an argument, as in `-foo:
3674 -foobar'. In that case, the last matching spec wins.
3675 The options of zparseopts itself cannot be stacked because, for
3677 example, the stack `-DEK' is indistinguishable from a spec for
3678 the GNU-style long option `--DEK'. The options of zparseopts
3679 itself are:
3680 -a array
3682 As described above, this names the default array in which
3683 to store the recognised options.
3684 -A assoc
3686 If this is given, the options and their values are also
3687 put into an associative array with the option names as
3688 keys and the arguments (if any) as the values.
3689 -D If this option is given, all options found are removed
3691 from the positional parameters of the calling shell or
3692 shell function, up to but not including any not described
3693 by the specs. If the first such parameter is `-' or
3694 `--', it is removed as well. This is similar to using
3695 the shift builtin.
3696 -E This changes the parsing rules to not stop at the first
3698 string that isn't described by one of the specs. It can
3699 be used to test for or (if used together with -D) extract
3700 options and their arguments, ignoring all other options
3701 and arguments that may be in the positional parameters.
3702 As indicated above, parsing still stops at the first `-'
3703 or `--' not described by a spec, but it is not removed
3704 when used with -D.
3705 -F If this option is given, zparseopts immediately stops at
3707 the first option-like parameter not described by one of
3708 the specs, prints an error message, and returns status 1.
3709 Removal (-D) and extraction (-E) are not performed, and
3710 option arrays are not updated. This provides basic vali‐
3711 dation for the given options.
3712 Note that the appearance in the positional parameters of
3714 an option without its required argument always aborts
3715 parsing and returns an error as described above regard‐
3716 less of whether this option is used.
3717 -K With this option, the arrays specified with the -a option
3719 and with the `=array' forms are kept unchanged when none
3720 of the specs for them is used. Otherwise the entire ar‐
3721 ray is replaced when any of the specs is used. Individ‐
3722 ual elements of associative arrays specified with the -A
3723 option are preserved by -K. This allows assignment of
3724 default values to arrays before calling zparseopts.
3725 -M This changes the assignment rules to implement a map
3727 among equivalent option names. If any spec uses the
3728 `=array' form, the string array is interpreted as the
3729 name of another spec, which is used to choose where to
3730 store the values. If no other spec is found, the values
3731 are stored as usual. This changes only the way the val‐
3732 ues are stored, not the way $* is parsed, so results may
3733 be unpredictable if the `name+' specifier is used incon‐
3734 sistently.
3735 For example,
3737 set -- -a -bx -c y -cz baz -cend
3739 zparseopts a=foo b:=bar c+:=bar
3740 will have the effect of
3742 foo=(-a)
3744 bar=(-b x -c y -c z)
3745 The arguments from `baz' on will not be used.
3747 As an example for the -E option, consider:
3749 set -- -a x -b y -c z arg1 arg2
3751 zparseopts -E -D b:=bar
3752 will have the effect of
3754 bar=(-b y)
3756 set -- -a x -c z arg1 arg2
3757 I.e., the option -b and its arguments are taken from the posi‐
3759 tional parameters and put into the array bar.
3760 The -M option can be used like this:
3762 set -- -a -bx -c y -cz baz -cend
3764 zparseopts -A bar -M a=foo b+: c:=b
3765 to have the effect of
3767 foo=(-a)
3769 bar=(-a '' -b xyz)
3770zsh 5.9 May 14, 2022 ZSHMODULES(1)