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/deltochar
47 A ZLE function duplicating EMACS' zap-to-char.
48 zsh/example
50 An example of how to write a module.
51 zsh/files
53 Some basic file manipulation commands as builtins.
54 zsh/langinfo
56 Interface to locale information.
57 zsh/mapfile
59 Access to external files via a special associative array.
60 zsh/mathfunc
62 Standard scientific functions for use in mathematical evalua‐
63 tions.
64 zsh/newuser
66 Arrange for files for new users to be installed.
67 zsh/parameter
69 Access to internal hash tables via special associative arrays.
70 zsh/pcre
72 Interface to the PCRE library.
73 zsh/regex
75 Interface to the POSIX regex library.
76 zsh/sched
78 A builtin that provides a timed execution facility within the
79 shell.
80 zsh/net/socket
82 Manipulation of Unix domain sockets
83 zsh/stat
85 A builtin command interface to the stat system call.
86 zsh/system
88 A builtin interface to various low-level system features.
89 zsh/net/tcp
91 Manipulation of TCP sockets
92 zsh/termcap
94 Interface to the termcap database.
95 zsh/terminfo
97 Interface to the terminfo database.
98 zsh/zftp
100 A builtin FTP client.
101 zsh/zle
103 The Zsh Line Editor, including the bindkey and vared builtins.
104 zsh/zleparameter
106 Access to internals of the Zsh Line Editor via parameters.
107 zsh/zprof
109 A module allowing profiling for shell functions.
110 zsh/zpty
112 A builtin for starting a command in a pseudo-terminal.
113 zsh/zselect
115 Block and return when file descriptors are ready.
116 zsh/zutil
118 Some utility builtins, e.g. the one for supporting configuration
119 via styles.
120
122 The zsh/attr module is used for manipulating extended attributes. The
123 -h option causes all commands to operate on symbolic links instead of
124 their targets. The builtins in this module are:
125 zgetattr [ -h ] filename attribute [ parameter ]
127 Get the extended attribute attribute from the specified file‐
128 name. If the optional argument parameter is given, the attribute
129 is set on that parameter instead of being printed to stdout.
130 zsetattr [ -h ] filename attribute value
132 Set the extended attribute attribute on the specified filename
133 to value.
134 zdelattr [ -h ] filename attribute
136 Remove the extended attribute attribute from the specified file‐
137 name.
138 zlistattr [ -h ] filename [ parameter ]
140 List the extended attributes currently set on the specified
141 filename. If the optional argument parameter is given, the list
142 of attributes is set on that parameter instead of being printed
143 to stdout.
144 zgetattr and zlistattr allocate memory dynamically. If the attribute
146 or list of attributes grows between the allocation and the call to get
147 them, they return 2. On all other errors, 1 is returned. This allows
148 the calling function to check for this case and retry.
149
151 The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) capabil‐
152 ity sets. If the operating system does not support this interface, the
153 builtins defined by this module will do nothing. The builtins in this
154 module are:
155 cap [ capabilities ]
157 Change the shell's process capability sets to the specified
158 capabilities, otherwise display the shell's current capabili‐
159 ties.
160 getcap filename ...
162 This is a built-in implementation of the POSIX standard utility.
163 It displays the capability sets on each specified filename.
164 setcap capabilities filename ...
166 This is a built-in implementation of the POSIX standard utility.
167 It sets the capability sets on each specified filename to the
168 specified capabilities.
169
171 The zsh/clone module makes available one builtin command:
172 clone tty
174 Creates a forked instance of the current shell, attached to the
175 specified tty. In the new shell, the PID, PPID and TTY special
176 parameters are changed appropriately. $! is set to zero in the
177 new shell, and to the new shell's PID in the original shell.
178 The return status of the builtin is zero in both shells if suc‐
180 cessful, and non-zero on error.
181 The target of clone should be an unused terminal, such as an
183 unused virtual console or a virtual terminal created by
184 xterm -e sh -c 'trap : INT QUIT TSTP; tty; while :; do sleep
186 100000000; done'
187 Some words of explanation are warranted about this long xterm
189 command line: when doing clone on a pseudo-terminal, some other
190 session ("session" meant as a unix session group, or SID) is
191 already owning the terminal. Hence the cloned zsh cannot acquire
192 the pseudo-terminal as a controlling tty. That means two things:
193 the job control signals will go to the sh-started-by-xterm
195 process
196 group (that's why we disable INT QUIT and TSTP with trap;
197 otherwise
198 the while loop could get suspended or killed)
199 the cloned shell will have job control disabled, and the job
201 control keys (control-C, control-\ and control-Z) will not
202 work.
203 This does not apply when cloning to an unused vc.
205 Cloning to a used (and unprepared) terminal will result in two
207 processes reading simultaneously from the same terminal, with
208 input bytes going randomly to either process.
209 clone is mostly useful as a shell built-in replacement for
211 openvt.
212
214 The zsh/compctl module makes available two builtin commands. compctl,
215 is the old, deprecated way to control completions for ZLE. See zshcom‐
216 pctl(1). The other builtin command, compcall can be used in
217 user-defined completion widgets, see zshcompwid(1).
218
220 The zsh/complete module makes available several builtin commands which
221 can be used in user-defined completion widgets, see zshcompwid(1).
222
224 The zsh/complist module offers three extensions to completion listings:
225 the ability to highlight matches in such a list, the ability to scroll
226 through long lists and a different style of menu completion.
227 Colored completion listings
229 Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS is set and the
230 zsh/complist module is loaded or linked into the shell, completion
231 lists will be colored. Note, however, that complist will not automati‐
232 cally be loaded if it is not linked in: on systems with dynamic load‐
233 ing, `zmodload zsh/complist' is required.
234 The parameters ZLS_COLORS and ZLS_COLOURS describe how matches are
236 highlighted. To turn on highlighting an empty value suffices, in which
237 case all the default values given below will be used. The format of
238 the value of these parameters is the same as used by the GNU version of
239 the ls command: a colon-separated list of specifications of the form
240 `name=value'. The name may be one of the following strings, most of
241 which specify file types for which the value will be used. The strings
242 and their default values are:
243 no 0 for normal text (i.e. when displaying something other than a
245 matched file)
246 fi 0 for regular files
248 di 32 for directories
250 ln 36 for symbolic links. If this has the special value target, sym‐
252 bolic links are dereferenced and the target file used to deter‐
253 mine the display format.
254 pi 31 for named pipes (FIFOs)
256 so 33 for sockets
258 bd 44;37
260 for block devices
261 cd 44;37
263 for character devices
264 or none
266 for a symlink to nonexistent file (default is the value defined
267 for ln)
268 mi none
270 for a non-existent file (default is the value defined for fi);
271 this code is currently not used
272 su 37;41
274 for files with setuid bit set
275 sg 30;43
277 for files with setgid bit set
278 tw 30;42
280 for world writable directories with sticky bit set
281 ow 34;43
283 for world writable directories without sticky bit set
284 sa none
286 for files with an associated suffix alias; this is only tested
287 after specific suffixes, as described below
288 st 37;44
290 for directories with sticky bit set but not world writable
291 ex 35 for executable files
293 lc \e[ for the left code (see below)
295 rc m for the right code
297 tc 0 for the character indicating the file type printed after file‐
299 names if the LIST_TYPES option is set
300 sp 0 for the spaces printed after matches to align the next column
302 ec none
304 for the end code
305 Apart from these strings, the name may also be an asterisk (`*') fol‐
307 lowed by any string. The value given for such a string will be used for
308 all files whose name ends with the string. The name may also be an
309 equals sign (`=') followed by a pattern; the EXTENDED_GLOB option will
310 be turned on for evaluation of the pattern. The value given for this
311 pattern will be used for all matches (not just filenames) whose display
312 string are matched by the pattern. Definitions for the form with the
313 leading equal sign take precedence over the values defined for file
314 types, which in turn take precedence over the form with the leading
315 asterisk (file extensions).
316 The leading-equals form also allows different parts of the displayed
318 strings to be colored differently. For this, the pattern has to use
319 the `(#b)' globbing flag and pairs of parentheses surrounding the parts
320 of the strings that are to be colored differently. In this case the
321 value may consist of more than one color code separated by equal signs.
322 The first code will be used for all parts for which no explicit code is
323 specified and the following codes will be used for the parts matched by
324 the sub-patterns in parentheses. For example, the specification
325 `=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least
326 two characters long and will use the code `3' for the first character,
327 `7' for the last character and `0' for the rest.
328 All three forms of name may be preceded by a pattern in parentheses.
330 If this is given, the value will be used only for matches in groups
331 whose names are matched by the pattern given in the parentheses. For
332 example, `(g*)m*=43' highlights all matches beginning with `m' in
333 groups whose names begin with `g' using the color code `43'. In case
334 of the `lc', `rc', and `ec' codes, the group pattern is ignored.
335 Note also that all patterns are tried in the order in which they appear
337 in the parameter value until the first one matches which is then used.
338 When printing a match, the code prints the value of lc, the value for
340 the file-type or the last matching specification with a `*', the value
341 of rc, the string to display for the match itself, and then the value
342 of ec if that is defined or the values of lc, no, and rc if ec is not
343 defined.
344 The default values are ISO 6429 (ANSI) compliant and can be used on
346 vt100 compatible terminals such as xterms. On monochrome terminals the
347 default values will have no visible effect. The colors function from
348 the contribution can be used to get associative arrays containing the
349 codes for ANSI terminals (see the section `Other Functions' in zshcon‐
350 trib(1)). For example, after loading colors, one could use `$col‐
351 ors[red]' to get the code for foreground color red and `$col‐
352 ors[bg-green]' for the code for background color green.
353 If the completion system invoked by compinit is used, these parameters
355 should not be set directly because the system controls them itself.
356 Instead, the list-colors style should be used (see the section `Comple‐
357 tion System Configuration' in zshcompsys(1)).
358 Scrolling in completion listings
360 To enable scrolling through a completion list, the LISTPROMPT parameter
361 must be set. Its value will be used as the prompt; if it is the empty
362 string, a default prompt will be used. The value may contain escapes
363 of the form `%x'. It supports the escapes `%B', `%b', `%S', `%s',
364 `%U', `%u', `%F', `%f', `%K', `%k' and `%{...%}' used also in shell
365 prompts as well as three pairs of additional sequences: a `%l' or `%L'
366 is replaced by the number of the last line shown and the total number
367 of lines in the form `number/total'; a `%m' or `%M' is replaced with
368 the number of the last match shown and the total number of matches; and
369 `%p' or `%P' is replaced with `Top', `Bottom' or the position of the
370 first line shown in percent of the total number of lines, respectively.
371 In each of these cases the form with the uppercase letter will be
372 replaced with a string of fixed width, padded to the right with spaces,
373 while the lowercase form will not be padded.
374 If the parameter LISTPROMPT is set, the completion code will not ask if
376 the list should be shown. Instead it immediately starts displaying the
377 list, stopping after the first screenful, showing the prompt at the
378 bottom, waiting for a keypress after temporarily switching to the
379 listscroll keymap. Some of the zle functions have a special meaning
380 while scrolling lists:
381 send-break
383 stops listing discarding the key pressed
384 accept-line, down-history, down-line-or-history
386 down-line-or-search, vi-down-line-or-history
387 scrolls forward one line
388 complete-word, menu-complete, expand-or-complete
390 expand-or-complete-prefix, menu-complete-or-expand
391 scrolls forward one screenful
392 accept-search
394 stop listing but take no other action
395 Every other character stops listing and immediately processes the key
397 as usual. Any key that is not bound in the listscroll keymap or that
398 is bound to undefined-key is looked up in the keymap currently
399 selected.
400 As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not
402 be set directly when using the shell function based completion system.
403 Instead, the list-prompt style should be used.
404 Menu selection
406 The zsh/complist module also offers an alternative style of selecting
407 matches from a list, called menu selection, which can be used if the
408 shell is set up to return to the last prompt after showing a completion
409 list (see the ALWAYS_LAST_PROMPT option in zshoptions(1)).
410 Menu selection can be invoked directly by the widget menu-select
412 defined by this module. This is a standard ZLE widget that can be
413 bound to a key in the usual way as described in zshzle(1).
414 Alternatively, the parameter MENUSELECT can be set to an integer, which
416 gives the minimum number of matches that must be present before menu
417 selection is automatically turned on. This second method requires that
418 menu completion be started, either directly from a widget such as
419 menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU
420 being set. If MENUSELECT is set, but is 0, 1 or empty, menu selection
421 will always be started during an ambiguous menu completion.
422 When using the completion system based on shell functions, the MENUSE‐
424 LECT parameter should not be used (like the ZLS_COLORS and ZLS_COLOURS
425 parameters described above). Instead, the menu style should be used
426 with the select=... keyword.
427 After menu selection is started, the matches will be listed. If there
429 are more matches than fit on the screen, only the first screenful is
430 shown. The matches to insert into the command line can be selected
431 from this list. In the list one match is highlighted using the value
432 for ma from the ZLS_COLORS or ZLS_COLOURS parameter. The default value
433 for this is `7' which forces the selected match to be highlighted using
434 standout mode on a vt100-compatible terminal. If neither ZLS_COLORS
435 nor ZLS_COLOURS is set, the same terminal control sequence as for the
436 `%S' escape in prompts is used.
437 If there are more matches than fit on the screen and the parameter
439 MENUPROMPT is set, its value will be shown below the matches. It sup‐
440 ports the same escape sequences as LISTPROMPT, but the number of the
441 match or line shown will be that of the one where the mark is placed.
442 If its value is the empty string, a default prompt will be used.
443 The MENUSCROLL parameter can be used to specify how the list is
445 scrolled. If the parameter is unset, this is done line by line, if it
446 is set to `0' (zero), the list will scroll half the number of lines of
447 the screen. If the value is positive, it gives the number of lines to
448 scroll and if it is negative, the list will be scrolled the number of
449 lines of the screen minus the (absolute) value.
450 As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parameters, neither
452 MENUPROMPT nor MENUSCROLL should be set directly when using the shell
453 function based completion system. Instead, the select-prompt and
454 select-scroll styles should be used.
455 The completion code sometimes decides not to show all of the matches in
457 the list. These hidden matches are either matches for which the com‐
458 pletion function which added them explicitly requested that they not
459 appear in the list (using the -n option of the compadd builtin command)
460 or they are matches which duplicate a string already in the list
461 (because they differ only in things like prefixes or suffixes that are
462 not displayed). In the list used for menu selection, however, even
463 these matches are shown so that it is possible to select them. To
464 highlight such matches the hi and du capabilities in the ZLS_COLORS and
465 ZLS_COLOURS parameters are supported for hidden matches of the first
466 and second kind, respectively.
467 Selecting matches is done by moving the mark around using the zle move‐
469 ment functions. When not all matches can be shown on the screen at the
470 same time, the list will scroll up and down when crossing the top or
471 bottom line. The following zle functions have special meaning during
472 menu selection. Note that the following always perform the same task
473 within the menu selection map and cannot be replaced by user defined
474 widgets, nor can the set of functions be extended:
475 accept-line, accept-search
477 accept the current match and leave menu selection (but do not
478 cause the command line to be accepted)
479 send-break
481 leaves menu selection and restores the previous contents of the
482 command line
483 redisplay, clear-screen
485 execute their normal function without leaving menu selection
486 accept-and-hold, accept-and-menu-complete
488 accept the currently inserted match and continue selection
489 allowing to select the next match to insert into the line
490 accept-and-infer-next-history
492 accepts the current match and then tries completion with menu
493 selection again; in the case of files this allows one to select
494 a directory and immediately attempt to complete files in it; if
495 there are no matches, a message is shown and one can use undo to
496 go back to completion on the previous level, every other key
497 leaves menu selection (including the other zle functions which
498 are otherwise special during menu selection)
499 undo removes matches inserted during the menu selection by one of the
501 three functions before
502 down-history, down-line-or-history
504 vi-down-line-or-history, down-line-or-search
505 moves the mark one line down
506 up-history, up-line-or-history
508 vi-up-line-or-history, up-line-or-search
509 moves the mark one line up
510 forward-char, vi-forward-char
512 moves the mark one column right
513 backward-char, vi-backward-char
515 moves the mark one column left
516 forward-word, vi-forward-word
518 vi-forward-word-end, emacs-forward-word
519 moves the mark one screenful down
520 backward-word, vi-backward-word, emacs-backward-word
522 moves the mark one screenful up
523 vi-forward-blank-word, vi-forward-blank-word-end
525 moves the mark to the first line of the next group of matches
526 vi-backward-blank-word
528 moves the mark to the last line of the previous group of matches
529 beginning-of-history
531 moves the mark to the first line
532 end-of-history
534 moves the mark to the last line
535 beginning-of-buffer-or-history, beginning-of-line
537 beginning-of-line-hist, vi-beginning-of-line
538 moves the mark to the leftmost column
539 end-of-buffer-or-history, end-of-line
541 end-of-line-hist, vi-end-of-line
542 moves the mark to the rightmost column
543 complete-word, menu-complete, expand-or-complete
545 expand-or-complete-prefix, menu-expand-or-complete
546 moves the mark to the next match
547 reverse-menu-complete
549 moves the mark to the previous match
550 vi-insert
552 this toggles between normal and interactive mode; in interactive
553 mode the keys bound to self-insert and self-insert-unmeta insert
554 into the command line as in normal editing mode but without
555 leaving menu selection; after each character completion is tried
556 again and the list changes to contain only the new matches; the
557 completion widgets make the longest unambiguous string be
558 inserted in the command line and undo and backward-delete-char
559 go back to the previous set of matches
560 history-incremental-search-forward
562 history-incremental-search-backward
563 this starts incremental searches in the list of completions dis‐
564 played; in this mode, accept-line only leaves incremental
565 search, going back to the normal menu selection mode
566 All movement functions wrap around at the edges; any other zle function
568 not listed leaves menu selection and executes that function. It is
569 possible to make widgets in the above list do the same by using the
570 form of the widget with a `.' in front. For example, the widget
571 `.accept-line' has the effect of leaving menu selection and accepting
572 the entire command line.
573 During this selection the widget uses the keymap menuselect. Any key
575 that is not defined in this keymap or that is bound to undefined-key is
576 looked up in the keymap currently selected. This is used to ensure
577 that the most important keys used during selection (namely the cursor
578 keys, return, and TAB) have sensible defaults. However, keys in the
579 menuselect keymap can be modified directly using the bindkey builtin
580 command (see zshmodules(1)). For example, to make the return key leave
581 menu selection without accepting the match currently selected one could
582 call
583 bindkey -M menuselect '^M' send-break
585 after loading the zsh/complist module.
587
589 The zsh/computil module adds several builtin commands that are used by
590 some of the completion functions in the completion system based on
591 shell functions (see zshcompsys(1) ). Except for compquote these
592 builtin commands are very specialised and thus not very interesting
593 when writing your own completion functions. In summary, these builtin
594 commands are:
595 comparguments
597 This is used by the _arguments function to do the argument and
598 command line parsing. Like compdescribe it has an option -i to
599 do the parsing and initialize some internal state and various
600 options to access the state information to decide what should be
601 completed.
602 compdescribe
604 This is used by the _describe function to build the displays for
605 the matches and to get the strings to add as matches with their
606 options. On the first call one of the options -i or -I should
607 be supplied as the first argument. In the first case, display
608 strings without the descriptions will be generated, in the sec‐
609 ond case, the string used to separate the matches from their
610 descriptions must be given as the second argument and the
611 descriptions (if any) will be shown. All other arguments are
612 like the definition arguments to _describe itself.
613 Once compdescribe has been called with either the -i or the -I
615 option, it can be repeatedly called with the -g option and the
616 names of five arrays as its arguments. This will step through
617 the different sets of matches and store the options in the first
618 array, the strings with descriptions in the second, the matches
619 for these in the third, the strings without descriptions in the
620 fourth, and the matches for them in the fifth array. These are
621 then directly given to compadd to register the matches with the
622 completion code.
623 compfiles
625 Used by the _path_files function to optimize complex recursive
626 filename generation (globbing). It does three things. With the
627 -p and -P options it builds the glob patterns to use, including
628 the paths already handled and trying to optimize the patterns
629 with respect to the prefix and suffix from the line and the
630 match specification currently used. The -i option does the
631 directory tests for the ignore-parents style and the -r option
632 tests if a component for some of the matches are equal to the
633 string on the line and removes all other matches if that is
634 true.
635 compgroups
637 Used by the _tags function to implement the internals of the
638 group-order style. This only takes its arguments as names of
639 completion groups and creates the groups for it (all six types:
640 sorted and unsorted, both without removing duplicates, with
641 removing all duplicates and with removing consecutive dupli‐
642 cates).
643 compquote [ -p ] names ...
645 There may be reasons to write completion functions that have to
646 add the matches using the -Q option to compadd and perform quot‐
647 ing themselves. Instead of interpreting the first character of
648 the all_quotes key of the compstate special association and
649 using the q flag for parameter expansions, one can use this
650 builtin command. The arguments are the names of scalar or array
651 parameters and the values of these parameters are quoted as
652 needed for the innermost quoting level. If the -p option is
653 given, quoting is done as if there is some prefix before the
654 values of the parameters, so that a leading equal sign will not
655 be quoted.
656 The return status is non-zero in case of an error and zero oth‐
658 erwise.
659 comptags
661 comptry
662 These implement the internals of the tags mechanism.
663 compvalues
665 Like comparguments, but for the _values function.
666
668 The zsh/curses module makes available one builtin command and various
669 parameters.
670 Builtin
672 zcurses init
673 zcurses end
674 zcurses addwin targetwin nlines ncols begin_y begin_x [ parentwin ]
675 zcurses delwin targetwin
676 zcurses refresh [ targetwin ... ]
677 zcurses touch targetwin ...
678 zcurses move targetwin new_y new_x
679 zcurses clear targetwin [ redraw | eol | bot ]
680 zcurses position targetwin array
681 zcurses char targetwin character
682 zcurses string targetwin string
683 zcurses border targetwin border
684 zcurses attr targetwin [ {+/-}attribute | fg_col/bg_col ] [...]
685 zcurses bg targetwin [ {+/-}attribute | fg_col/bg_col | @char ] [...]
686 zcurses scroll targetwin [ on | off | {+/-}lines ]
687 zcurses input targetwin [ param [ kparam [ mparam ] ] ]
688 zcurses mouse [ delay num | {+/-}motion ]
689 zcurses timeout targetwin intval
690 zcurses querychar targetwin [ param ]
691 Manipulate curses windows. All uses of this command should be
692 bracketed by `zcurses init' to initialise use of curses, and
693 `zcurses end' to end it; omitting `zcurses end' can cause the
694 terminal to be in an unwanted state.
695 The subcommand addwin creates a window with nlines lines and
697 ncols columns. Its upper left corner will be placed at row
698 begin_y and column begin_x of the screen. targetwin is a string
699 and refers to the name of a window that is not currently
700 assigned. Note in particular the curses convention that verti‐
701 cal values appear before horizontal values.
702 If addwin is given an existing window as the final argument, the
704 new window is created as a subwindow of parentwin. This differs
705 from an ordinary new window in that the memory of the window
706 contents is shared with the parent's memory. Subwindows must be
707 deleted before their parent. Note that the coordinates of sub‐
708 windows are relative to the screen, not the parent, as with
709 other windows.
710 Use the subcommand delwin to delete a window created with
712 addwin. Note that end does not implicitly delete windows, and
713 that delwin does not erase the screen image of the window.
714 The window corresponding to the full visible screen is called
716 stdscr; it always exists after `zcurses init' and cannot be
717 delete with delwin.
718 The subcommand refresh will refresh window targetwin; this is
720 necessary to make any pending changes (such as characters you
721 have prepared for output with char) visible on the screen.
722 refresh without an argument causes the screen to be cleared and
723 redrawn. If multiple windows are given, the screen is updated
724 once at the end.
725 The subcommand touch marks the targetwins listed as changed.
727 This is necessary before refreshing windows if a window that was
728 in front of another window (which may be stdscr) is deleted.
729 The subcommand move moves the cursor position in targetwin to
731 new coordinates new_y and new_x. Note that the subcommand
732 string (but not the subcommand char) advances the cursor posi‐
733 tion over the characters added.
734 The subcommand clear erases the contents of targetwin. One (and
736 no more than one) of three options may be specified. With the
737 option redraw, in addition the next refresh of targetwin will
738 cause the screen to be cleared and repainted. With the option
739 eol, targetwin is only cleared to the end of the current cursor
740 line. With the option bot, targetwin is cleared to the end of
741 the window, i.e everything to the right and below the cursor is
742 cleared.
743 The subcommand position writes various positions associated with
745 targetwin into the array named array. These are, in order:
746 The y and x coordinates of the cursor relative to the top left
748 of targetwin
749 The y and x coordinates of the top left of targetwin on the
751 screen
752 The size of targetwin in y and x dimensions.
754 Outputting characters and strings are achieved by char and
756 string respectively.
757 To draw a border around window targetwin, use border. Note that
759 the border is not subsequently handled specially: in other
760 words, the border is simply a set of characters output at the
761 edge of the window. Hence it can be overwritten, can scroll off
762 the window, etc.
763 The subcommand attr will set targetwin's attributes or fore‐
765 ground/background color pair for any successive character out‐
766 put. Each attribute given on the line may be prepended by a +
767 to set or a - to unset that attribute; + is assumed if absent.
768 The attributes supported are blink, bold, dim, reverse, stand‐
769 out, and underline.
770 Each fg_col/bg_col attribute (to be read as `fg_col on bg_col')
772 sets the foreground and background color for character output.
773 The color default is sometimes available (in particular if the
774 library is ncurses), specifying the foreground or background
775 color with which the terminal started. The color pair
776 default/default is always available.
777 bg overrides the color and other attributes of all characters in
779 the window. Its usual use is to set the background initially,
780 but it will overwrite the attributes of any characters at the
781 time when it is called. In addition to the arguments allowed
782 with attr, an argument @char specifies a character to be shown
783 in otherwise blank areas of the window. Owing to limitations of
784 curses this cannot be a multibyte character (use of ASCII char‐
785 acters only is recommended). As the specified set of attributes
786 override the existing background, turning attributes off in the
787 arguments is not useful, though this does not cause an error.
788 The subcommand scroll can be used with on or off to enabled or
790 disable scrolling of a window when the cursor would otherwise
791 move below the window due to typing or output. It can also be
792 used with a positive or negative integer to scroll the window up
793 or down the given number of lines without changing the current
794 cursor position (which therefore appears to move in the opposite
795 direction relative to the window). In the second case, if
796 scrolling is off it is temporarily turned on to allow the window
797 to be scrolled.
798 The subcommand input reads a single character from the window
800 without echoing it back. If param is supplied the character is
801 assigned to the parameter param, else it is assigned to the
802 parameter REPLY.
803 If both param and kparam are supplied, the key is read in `key‐
805 pad' mode. In this mode special keys such as function keys and
806 arrow keys return the name of the key in the parameter kparam.
807 The key names are the macros defined in the curses.h or
808 ncurses.h with the prefix `KEY_' removed; see also the descrip‐
809 tion of the parameter zcurses_keycodes below. Other keys cause
810 a value to be set in param as before. On a successful return
811 only one of param or kparam contains a non-empty string; the
812 other is set to an empty string.
813 If mparam is also supplied, input attempts to handle mouse
815 input. This is only available with the ncurses library; mouse
816 handling can be detected by checking for the exit status of
817 `zcurses mouse' with no arguments. If a mouse button is clicked
818 (or double- or triple-clicked, or pressed or released with a
819 configurable delay from being clicked) then kparam is set to the
820 string MOUSE, and mparam is set to an array consisting of the
821 following elements:
822 - An identifier to discriminate different input devices;
823 this is only rarely useful.
824 - The x, y and z coordinates of the mouse click relative to
825 the full screen, as three elements in that order (i.e.
826 the y coordinate is, unusually, after the x coordinate).
827 The z coordinate is only available for a few unusual
828 input devices and is otherwise set to zero.
829 - Any events that occurred as separate items; usually there
830 will be just one. An event consists of PRESSED,
831 RELEASED, CLICKED, DOUBLE_CLICKED or TRIPLE_CLICKED fol‐
832 lowed immediately (in the same element) by the number of
833 the button.
834 - If the shift key was pressed, the string SHIFT.
835 - If the control key was pressed, the string CTRL.
836 - If the alt key was pressed, the string ALT.
837 Not all mouse events may be passed through to the terminal win‐
839 dow; most terminal emulators handle some mouse events them‐
840 selves. Note that the ncurses manual implies that using input
841 both with and without mouse handling may cause the mouse cursor
842 to appear and disappear.
843 The subcommand mouse can be used to configure the use of the
845 mouse. There is no window argument; mouse options are global.
846 `zcurses mouse' with no arguments returns status 0 if mouse han‐
847 dling is possible, else status 1. Otherwise, the possible argu‐
848 ments (which may be combined on the same command line) are as
849 follows. delay num sets the maximum delay in milliseconds
850 between press and release events to be considered as a click;
851 the value 0 disables click resolution, and the default is one
852 sixth of a second. motion proceeded by an optional `+' (the
853 default) or - turns on or off reporting of mouse motion in addi‐
854 tion to clicks, presses and releases, which are always reported.
855 However, it appears reports for mouse motion are not currently
856 implemented.
857 The subcommand timeout specifies a timeout value for input from
859 targetwin. If intval is negative, `zcurses input' waits indefi‐
860 nitely for a character to be typed; this is the default. If
861 intval is zero, `zcurses input' returns immediately; if there is
862 typeahead it is returned, else no input is done and status 1 is
863 returned. If intval is positive, `zcurses input' waits intval
864 milliseconds for input and if there is none at the end of that
865 period returns status 1.
866 The subcommand querychar queries the character at the current
868 cursor position. The return values are stored in the array
869 named param if supplied, else in the array reply. The first
870 value is the character (which may be a multibyte character if
871 the system supports them); the second is the color pair in the
872 usual fg_col/bg_col notation, or 0 if color is not supported.
873 Any attributes other than color that apply to the character, as
874 set with the subcommand attr, appear as additional elements.
875 Parameters
877 ZCURSES_COLORS
878 Readonly integer. The maximum number of colors the terminal
879 supports. This value is initialised by the curses library and
880 is not available until the first time zcurses init is run.
881 ZCURSES_COLOR_PAIRS
883 Readonly integer. The maximum number of color pairs
884 fg_col/bg_col that may be defined in `zcurses attr' commands;
885 note this limit applies to all color pairs that have been used
886 whether or not they are currently active. This value is ini‐
887 tialised by the curses library and is not available until the
888 first time zcurses init is run.
889 zcurses_attrs
891 Readonly array. The attributes supported by zsh/curses; avail‐
892 able as soon as the module is loaded.
893 zcurses_colors
895 Readonly array. The colors supported by zsh/curses; available
896 as soon as the module is loaded.
897 zcurses_keycodes
899 Readonly array. The values that may be returned in the second
900 parameter supplied to `zcurses input' in the order in which they
901 are defined internally by curses. Not all function keys are
902 listed, only F0; curses reserves space for F0 up to F63.
903 zcurses_windows
905 Readonly array. The current list of windows, i.e. all windows
906 that have been created with `zcurses addwin' and not removed
907 with `zcurses delwin'.
908
910 The zsh/datetime module makes available one builtin command:
911 strftime [ -s scalar ] format epochtime
913 strftime -r [ -q ] [ -s scalar ] format timestring
914 Output the date denoted by epochtime in the format specified.
915 With the option -r (reverse), use the format format to parse the
917 input string timestring and output the number of seconds since
918 the epoch at which the time occurred. If no timezone is parsed,
919 the current timezone is used; other parameters are set to zero
920 if not present. If timestring does not match format the command
921 returns status 1; it will additionally print an error message
922 unless the option -q (quiet) is given. If timestring matches
923 format but not all characters in timestring were used, the con‐
924 version succeeds; however, a warning is issued unless the option
925 -q is given. The matching is implemented by the system function
926 strptime; see strptime(3). This means that zsh format exten‐
927 sions are not available, however for reverse lookup they are not
928 required. If the function is not implemented, the command
929 returns status 2 and (unless -q is given) prints a message.
930 If -s scalar is given, assign the date string (or epoch time in
932 seconds if -r is given) to scalar instead of printing it.
933 The zsh/datetime module makes available several parameters; all are
935 readonly:
936 EPOCHREALTIME
938 A floating point value representing the number of seconds since
939 the epoch. The notional accuracy is to nanoseconds if the
940 clock_gettime call is available and to microseconds otherwise,
941 but in practice the range of double precision floating point and
942 shell scheduling latencies may be significant effects.
943 EPOCHSECONDS
945 An integer value representing the number of seconds since the
946 epoch.
947 epochtime
949 An array value containing the number of seconds since the epoch
950 in the first element and the remainder of the time since the
951 epoch in nanoseconds in the second element. To ensure the two
952 elements are consistent the array should be copied or otherwise
953 referenced as a single substitution before the values are used.
954 The following idiom may be used:
955 for secs nsecs in $epochtime; do
957 ...
958 done
959
961 The zsh/deltochar module makes available two ZLE functions:
962 delete-to-char
964 Read a character from the keyboard, and delete from the cursor
965 position up to and including the next (or, with repeat count n,
966 the nth) instance of that character. Negative repeat counts
967 mean delete backwards.
968 zap-to-char
970 This behaves like delete-to-char, except that the final occur‐
971 rence of the character itself is not deleted.
972
974 The zsh/example module makes available one builtin command:
975 example [ -flags ] [ args ... ]
977 Displays the flags and arguments it is invoked with.
978 The purpose of the module is to serve as an example of how to write a
980 module.
981
983 The zsh/files module makes available some common commands for file
984 manipulation as builtins; these commands are probably not needed for
985 many normal situations but can be useful in emergency recovery situa‐
986 tions with constrained resources. The commands do not implement all
987 features now required by relevant standards committees.
988 For all commands, a variant beginning zf_ is also available and loaded
990 automatically. Using the features capability of zmodload will let you
991 load only those names you want.
992 The commands loaded by default are:
994 chgrp [ -hRs ] group filename ...
996 Changes group of files specified. This is equivalent to chown
997 with a user-spec argument of `:group'.
998 chown [ -hRs ] user-spec filename ...
1000 Changes ownership and group of files specified.
1001 The user-spec can be in four forms:
1003 user change owner to user; do not change group
1005 user:: change owner to user; do not change group
1006 user: change owner to user; change group to user's primary
1007 group
1008 user:group
1009 change owner to user; change group to group
1010 :group do not change owner; change group to group
1011 In each case, the `:' may instead be a `.'. The rule is that if
1013 there is a `:' then the separator is `:', otherwise if there is
1014 a `.' then the separator is `.', otherwise there is no separa‐
1015 tor.
1016 Each of user and group may be either a username (or group name,
1018 as appropriate) or a decimal user ID (group ID). Interpretation
1019 as a name takes precedence, if there is an all-numeric username
1020 (or group name).
1021 If the target is a symbolic link, the -h option causes chown to
1023 set the ownership of the link instead of its target.
1024 The -R option causes chown to recursively descend into directo‐
1026 ries, changing the ownership of all files in the directory after
1027 changing the ownership of the directory itself.
1028 The -s option is a zsh extension to chown functionality. It
1030 enables paranoid behaviour, intended to avoid security problems
1031 involving a chown being tricked into affecting files other than
1032 the ones intended. It will refuse to follow symbolic links, so
1033 that (for example) ``chown luser /tmp/foo/passwd'' can't acci‐
1034 dentally chown /etc/passwd if /tmp/foo happens to be a link to
1035 /etc. It will also check where it is after leaving directories,
1036 so that a recursive chown of a deep directory tree can't end up
1037 recursively chowning /usr as a result of directories being moved
1038 up the tree.
1039 ln [ -dfhins ] filename dest
1041 ln [ -dfhins ] filename ... dir
1042 Creates hard (or, with -s, symbolic) links. In the first form,
1043 the specified destination is created, as a link to the specified
1044 filename. In the second form, each of the filenames is taken in
1045 turn, and linked to a pathname in the specified directory that
1046 has the same last pathname component.
1047 Normally, ln will not attempt to create hard links to directo‐
1049 ries. This check can be overridden using the -d option. Typi‐
1050 cally only the super-user can actually succeed in creating hard
1051 links to directories. This does not apply to symbolic links in
1052 any case.
1053 By default, existing files cannot be replaced by links. The -i
1055 option causes the user to be queried about replacing existing
1056 files. The -f option causes existing files to be silently
1057 deleted, without querying. -f takes precedence.
1058 The -h and -n options are identical and both exist for compati‐
1060 bility; either one indicates that if the target is a symlink
1061 then it should not be dereferenced. Typically this is used in
1062 combination with -sf so that if an existing link points to a
1063 directory then it will be removed, instead of followed. If this
1064 option is used with multiple filenames and the target is a sym‐
1065 bolic link pointing to a directory then the result is an error.
1066 mkdir [ -p ] [ -m mode ] dir ...
1068 Creates directories. With the -p option, non-existing parent
1069 directories are first created if necessary, and there will be no
1070 complaint if the directory already exists. The -m option can be
1071 used to specify (in octal) a set of file permissions for the
1072 created directories, otherwise mode 777 modified by the current
1073 umask (see umask(2)) is used.
1074 mv [ -fi ] filename dest
1076 mv [ -fi ] filename ... dir
1077 Moves files. In the first form, the specified filename is moved
1078 to the specified destination. In the second form, each of the
1079 filenames is taken in turn, and moved to a pathname in the spec‐
1080 ified directory that has the same last pathname component.
1081 By default, the user will be queried before replacing any file
1083 that the user cannot write to, but writable files will be
1084 silently removed. The -i option causes the user to be queried
1085 about replacing any existing files. The -f option causes any
1086 existing files to be silently deleted, without querying. -f
1087 takes precedence.
1088 Note that this mv will not move files across devices. Histori‐
1090 cal versions of mv, when actual renaming is impossible, fall
1091 back on copying and removing files; if this behaviour is
1092 desired, use cp and rm manually. This may change in a future
1093 version.
1094 rm [ -dfirs ] filename ...
1096 Removes files and directories specified.
1097 Normally, rm will not remove directories (except with the -r
1099 option). The -d option causes rm to try removing directories
1100 with unlink (see unlink(2)), the same method used for files.
1101 Typically only the super-user can actually succeed in unlinking
1102 directories in this way. -d takes precedence over -r.
1103 By default, the user will be queried before removing any file
1105 that the user cannot write to, but writable files will be
1106 silently removed. The -i option causes the user to be queried
1107 about removing any files. The -f option causes files to be
1108 silently deleted, without querying, and suppresses all error
1109 indications. -f takes precedence.
1110 The -r option causes rm to recursively descend into directories,
1112 deleting all files in the directory before removing the direc‐
1113 tory with the rmdir system call (see rmdir(2)).
1114 The -s option is a zsh extension to rm functionality. It
1116 enables paranoid behaviour, intended to avoid common security
1117 problems involving a root-run rm being tricked into removing
1118 files other than the ones intended. It will refuse to follow
1119 symbolic links, so that (for example) ``rm /tmp/foo/passwd''
1120 can't accidentally remove /etc/passwd if /tmp/foo happens to be
1121 a link to /etc. It will also check where it is after leaving
1122 directories, so that a recursive removal of a deep directory
1123 tree can't end up recursively removing /usr as a result of
1124 directories being moved up the tree.
1125 rmdir dir ...
1127 Removes empty directories specified.
1128 sync Calls the system call of the same name (see sync(2)), which
1130 flushes dirty buffers to disk. It might return before the I/O
1131 has actually been completed.
1132
1134 The zsh/langinfo module makes available one parameter:
1135 langinfo
1137 An associative array that maps langinfo elements to their val‐
1138 ues.
1139 Your implementation may support a number of the following keys:
1141 CODESET, D_T_FMT, D_FMT, T_FMT, RADIXCHAR, THOUSEP, YESEXPR,
1143 NOEXPR, CRNCYSTR, ABDAY_{1..7}, DAY_{1..7}, ABMON_{1..12},
1144 MON_{1..12}, T_FMT_AMPM, AM_STR, PM_STR, ERA, ERA_D_FMT,
1145 ERA_D_T_FMT, ERA_T_FMT, ALT_DIGITS
1146
1148 The zsh/mapfile module provides one special associative array parameter
1149 of the same name.
1150 mapfile
1152 This associative array takes as keys the names of files; the
1153 resulting value is the content of the file. The value is
1154 treated identically to any other text coming from a parameter.
1155 The value may also be assigned to, in which case the file in
1156 question is written (whether or not it originally existed); or
1157 an element may be unset, which will delete the file in question.
1158 For example, `vared mapfile[myfile]' works as expected, editing
1159 the file `myfile'.
1160 When the array is accessed as a whole, the keys are the names of
1162 files in the current directory, and the values are empty (to
1163 save a huge overhead in memory). Thus ${(k)mapfile} has the
1164 same affect as the glob operator *(D), since files beginning
1165 with a dot are not special. Care must be taken with expressions
1166 such as rm ${(k)mapfile}, which will delete every file in the
1167 current directory without the usual `rm *' test.
1168 The parameter mapfile may be made read-only; in that case, files
1170 referenced may not be written or deleted.
1171 A file may conveniently be read into an array as one line per
1173 element with the form `array=("${(f)mapfile[filename]}")'. The
1174 double quotes are necessary to prevent empty lines from being
1175 removed.
1176 Limitations
1178 Although reading and writing of the file in question is efficiently
1179 handled, zsh's internal memory management may be arbitrarily baroque;
1180 however, mapfile is usually very much more efficient than anything
1181 involving a loop. Note in particular that the whole contents of the
1182 file will always reside physically in memory when accessed (possibly
1183 multiple times, due to standard parameter substitution operations). In
1184 particular, this means handling of sufficiently long files (greater
1185 than the machine's swap space, or than the range of the pointer type)
1186 will be incorrect.
1187 No errors are printed or flagged for non-existent, unreadable, or
1189 unwritable files, as the parameter mechanism is too low in the shell
1190 execution hierarchy to make this convenient.
1191 It is unfortunate that the mechanism for loading modules does not yet
1193 allow the user to specify the name of the shell parameter to be given
1194 the special behaviour.
1195
1197 The zsh/mathfunc module provides standard mathematical functions for
1198 use when evaluating mathematical formulae. The syntax agrees with nor‐
1199 mal C and FORTRAN conventions, for example,
1200 (( f = sin(0.3) ))
1202 assigns the sine of 0.3 to the parameter f.
1204 Most functions take floating point arguments and return a floating
1206 point value. However, any necessary conversions from or to integer
1207 type will be performed automatically by the shell. Apart from atan
1208 with a second argument and the abs, int and float functions, all func‐
1209 tions behave as noted in the manual page for the corresponding C func‐
1210 tion, except that any arguments out of range for the function in ques‐
1211 tion will be detected by the shell and an error reported.
1212 The following functions take a single floating point argument: acos,
1214 acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp,
1215 expm1, fabs, floor, gamma, j0, j1, lgamma, log, log10, log1p, logb,
1216 sin, sinh, sqrt, tan, tanh, y0, y1. The atan function can optionally
1217 take a second argument, in which case it behaves like the C function
1218 atan2. The ilogb function takes a single floating point argument, but
1219 returns an integer.
1220 The function signgam takes no arguments, and returns an integer, which
1222 is the C variable of the same name, as described in gamma(3). Note
1223 that it is therefore only useful immediately after a call to gamma or
1224 lgamma. Note also that `signgam(RPAR' and `signgam' are distinct
1225 expressions.
1226 The following functions take two floating point arguments: copysign,
1228 fmod, hypot, nextafter.
1229 The following take an integer first argument and a floating point sec‐
1231 ond argument: jn, yn.
1232 The following take a floating point first argument and an integer sec‐
1234 ond argument: ldexp, scalb.
1235 The function abs does not convert the type of its single argument; it
1237 returns the absolute value of either a floating point number or an
1238 integer. The functions float and int convert their arguments into a
1239 floating point or integer value (by truncation) respectively.
1240 Note that the C pow function is available in ordinary math evaluation
1242 as the `**' operator and is not provided here.
1243 The function rand48 is available if your system's mathematical library
1245 has the function erand48(3). It returns a pseudo-random floating point
1246 number between 0 and 1. It takes a single string optional argument.
1247 If the argument is not present, the random number seed is initialised
1249 by three calls to the rand(3) function --- this produces the same ran‐
1250 dom numbers as the next three values of $RANDOM.
1251 If the argument is present, it gives the name of a scalar parameter
1253 where the current random number seed will be stored. On the first
1254 call, the value must contain at least twelve hexadecimal digits (the
1255 remainder of the string is ignored), or the seed will be initialised in
1256 the same manner as for a call to rand48 with no argument. Subsequent
1257 calls to rand48(param) will then maintain the seed in the parameter
1258 param as a string of twelve hexadecimal digits, with no base signifier.
1259 The random number sequences for different parameters are completely
1260 independent, and are also independent from that used by calls to rand48
1261 with no argument.
1262 For example, consider
1264 print $(( rand48(seed) ))
1266 print $(( rand48() ))
1267 print $(( rand48(seed) ))
1268 Assuming $seed does not exist, it will be initialised by the first
1270 call. In the second call, the default seed is initialised; note, how‐
1271 ever, that because of the properties of rand() there is a correlation
1272 between the seeds used for the two initialisations, so for more secure
1273 uses, you should generate your own 12-byte seed. The third call
1274 returns to the same sequence of random numbers used in the first call,
1275 unaffected by the intervening rand48().
1276
1278 The zsh/newuser module is loaded at boot if it is available, the RCS
1279 option is set, and the PRIVILEGED option is not set (all three are true
1280 by default). This takes place immediately after commands in the global
1281 zshenv file (typically /etc/zshenv), if any, have been executed. If
1282 the module is not available it is silently ignored by the shell; the
1283 module may safely be removed from $MODULE_PATH by the administrator if
1284 it is not required.
1285 On loading, the module tests if any of the start-up files .zshenv,
1287 .zprofile, .zshrc or .zlogin exist in the directory given by the envi‐
1288 ronment variable ZDOTDIR, or the user's home directory if that is not
1289 set. The test is not performed and the module halts processing if the
1290 shell was in an emulation mode (i.e. had been invoked as some other
1291 shell than zsh).
1292 If none of the start-up files were found, the module then looks for the
1294 file newuser first in a sitewide directory, usually the parent direc‐
1295 tory of the site-functions directory, and if that is not found the mod‐
1296 ule searches in a version-specific directory, usually the parent of the
1297 functions directory containing version-specific functions. (These
1298 directories can be configured when zsh is built using the
1299 --enable-site-scriptdir=dir and --enable-scriptdir=dir flags to config‐
1300 ure, respectively; the defaults are prefix/share/zsh and pre‐
1301 fix/share/zsh/$ZSH_VERSION where the default prefix is /usr/local.)
1302 If the file newuser is found, it is then sourced in the same manner as
1304 a start-up file. The file is expected to contain code to install
1305 start-up files for the user, however any valid shell code will be exe‐
1306 cuted.
1307 The zsh/newuser module is then unconditionally unloaded.
1309 Note that it is possible to achieve exactly the same effect as the
1311 zsh/newuser module by adding code to /etc/zshenv. The module exists
1312 simply to allow the shell to make arrangements for new users without
1313 the need for intervention by package maintainers and system administra‐
1314 tors.
1315 The script supplied with the module invokes the shell function
1317 zsh-newuser-install. This may be invoked directly by the user even if
1318 the zsh/newuser module is disabled. Note, however, that if the module
1319 is not installed the function will not be installed either. The func‐
1320 tion is documented in the section User Configuration Functions in zsh‐
1321 contrib(1).
1322
1324 The zsh/parameter module gives access to some of the internal hash
1325 tables used by the shell by defining some special parameters.
1326 options
1328 The keys for this associative array are the names of the options
1329 that can be set and unset using the setopt and unsetopt
1330 builtins. The value of each key is either the string on if the
1331 option is currently set, or the string off if the option is
1332 unset. Setting a key to one of these strings is like setting or
1333 unsetting the option, respectively. Unsetting a key in this
1334 array is like setting it to the value off.
1335 commands
1337 This array gives access to the command hash table. The keys are
1338 the names of external commands, the values are the pathnames of
1339 the files that would be executed when the command would be
1340 invoked. Setting a key in this array defines a new entry in this
1341 table in the same way as with the hash builtin. Unsetting a key
1342 as in `unset "commands[foo]"' removes the entry for the given
1343 key from the command hash table.
1344 functions
1346 This associative array maps names of enabled functions to their
1347 definitions. Setting a key in it is like defining a function
1348 with the name given by the key and the body given by the value.
1349 Unsetting a key removes the definition for the function named by
1350 the key.
1351 dis_functions
1353 Like functions but for disabled functions.
1354 builtins
1356 This associative array gives information about the builtin com‐
1357 mands currently enabled. The keys are the names of the builtin
1358 commands and the values are either `undefined' for builtin com‐
1359 mands that will automatically be loaded from a module if invoked
1360 or `defined' for builtin commands that are already loaded.
1361 dis_builtins
1363 Like builtins but for disabled builtin commands.
1364 reswords
1366 This array contains the enabled reserved words.
1367 dis_reswords
1369 Like reswords but for disabled reserved words.
1370 aliases
1372 This maps the names of the regular aliases currently enabled to
1373 their expansions.
1374 dis_aliases
1376 Like aliases but for disabled regular aliases.
1377 galiases
1379 Like aliases, but for global aliases.
1380 dis_galiases
1382 Like galiases but for disabled global aliases.
1383 saliases
1385 Like raliases, but for suffix aliases.
1386 dis_saliases
1388 Like saliases but for disabled suffix aliases.
1389 parameters
1391 The keys in this associative array are the names of the parame‐
1392 ters currently defined. The values are strings describing the
1393 type of the parameter, in the same format used by the t parame‐
1394 ter flag, see zshexpn(1) . Setting or unsetting keys in this
1395 array is not possible.
1396 modules
1398 An associative array giving information about modules. The keys
1399 are the names of the modules loaded, registered to be
1400 autoloaded, or aliased. The value says which state the named
1401 module is in and is one of the strings `loaded', `autoloaded',
1402 or `alias:name', where name is the name the module is aliased
1403 to.
1404 Setting or unsetting keys in this array is not possible.
1406 dirstack
1408 A normal array holding the elements of the directory stack. Note
1409 that the output of the dirs builtin command includes one more
1410 directory, the current working directory.
1411 history
1413 This associative array maps history event numbers to the full
1414 history lines.
1415 historywords
1417 A special array containing the words stored in the history.
1418 jobdirs
1420 This associative array maps job numbers to the directories from
1421 which the job was started (which may not be the current direc‐
1422 tory of the job).
1423 The keys of the associative arrays are usually valid job num‐
1425 bers, and these are the values output with, for example,
1426 ${(k)jobdirs}. Non-numeric job references may be used when
1427 looking up a value; for example, ${jobdirs[%+]} refers to the
1428 current job.
1429 jobtexts
1431 This associative array maps job numbers to the texts of the com‐
1432 mand lines that were used to start the jobs.
1433 Handling of the keys of the associative array is as described
1435 for jobdirs above.
1436 jobstates
1438 This associative array gives information about the states of the
1439 jobs currently known. The keys are the job numbers and the val‐
1440 ues are strings of the form `job-state:mark:pid=state...'. The
1441 job-state gives the state the whole job is currently in, one of
1442 `running', `suspended', or `done'. The mark is `+' for the cur‐
1443 rent job, `-' for the previous job and empty otherwise. This is
1444 followed by one `pid=state' for every process in the job. The
1445 pids are, of course, the process IDs and the state describes the
1446 state of that process.
1447 Handling of the keys of the associative array is as described
1449 for jobdirs above.
1450 nameddirs
1452 This associative array maps the names of named directories to
1453 the pathnames they stand for.
1454 userdirs
1456 This associative array maps user names to the pathnames of their
1457 home directories.
1458 usergroups
1460 This associative array maps names of system groups of which the
1461 current user is a member to the corresponding group identifiers.
1462 The contents are the same as the groups output by the id com‐
1463 mand.
1464 funcfiletrace
1466 This array contains the absolute line numbers and corresponding
1467 file names for the point where the current function, sourced
1468 file, or (if EVAL_LINENO is set) eval command was called. The
1469 array is of the same length as funcsourcetrace and functrace,
1470 but differs from funcsourcetrace in that the line and file are
1471 the point of call, not the point of definition, and differs from
1472 functrace in that all values are absolute line numbers in files,
1473 rather than relative to the start of a function, if any.
1474 funcsourcetrace
1476 This array contains the file names and line numbers of the
1477 points where the functions, sourced files, and (if EVAL_LINENO
1478 is set) eval commands currently being executed were defined.
1479 The line number is the line where the `function name' or `name
1480 ()' started. In the case of an autoloaded function the line
1481 number is reported as zero. The format of each element is file‐
1482 name:lineno. For functions autoloaded from a file in native zsh
1483 format, where only the body of the function occurs in the file,
1484 or for files that have been executed by the source or `.'
1485 builtins, the trace information is shown as filename:0, since
1486 the entire file is the definition.
1487 Most users will be interested in the information in the func‐
1489 filetrace array instead.
1490 funcstack
1492 This array contains the names of the functions, sourced files,
1493 and (if EVAL_LINENO is set) eval commands. currently being exe‐
1494 cuted. The first element is the name of the function using the
1495 parameter.
1496 functrace
1498 This array contains the names and line numbers of the callers
1499 corresponding to the functions currently being executed. The
1500 format of each element is name:lineno. Callers are also shown
1501 for sourced files; the caller is the point where the source or
1502 `.' command was executed.
1503
1505 The zsh/pcre module makes some commands available as builtins:
1506 pcre_compile [ -aimxs ] PCRE
1508 Compiles a perl-compatible regular expression.
1509 Option -a will force the pattern to be anchored. Option -i will
1511 compile a case-insensitive pattern. Option -m will compile a
1512 multi-line pattern; that is, ^ and $ will match newlines within
1513 the pattern. Option -x will compile an extended pattern,
1514 wherein whitespace and # comments are ignored. Option -s makes
1515 the dot metacharacter match all characters, including those that
1516 indicate newline.
1517 pcre_study
1519 Studies the previously-compiled PCRE which may result in faster
1520 matching.
1521 pcre_match [ -v var ] [ -a arr ] [ -n offset ] [ -b ] string
1523 Returns successfully if string matches the previously-compiled
1524 PCRE.
1525 Upon successful match, if the expression captures substrings
1527 within parentheses, pcre_match will set the array $match to
1528 those substrings, unless the -a option is given, in which case
1529 it will set the array arr. Similarly, the variable MATCH will
1530 be set to the entire matched portion of the string, unless the
1531 -v option is given, in which case the variable var will be set.
1532 No variables are altered if there is no successful match. A -n
1533 option starts searching for a match from the byte offset posi‐
1534 tion in string. If the -b option is given, the variable
1535 ZPCRE_OP will be set to an offset pair string, representing the
1536 byte offset positions of the entire matched portion within the
1537 string. For example, a ZPCRE_OP set to "32 45" indicates that
1538 the matched portion began on byte offset 32 and ended on byte
1539 offset 44. Here, byte offset position 45 is the position
1540 directly after the matched portion. Keep in mind that the byte
1541 position isn't necessarily the same as the character position
1542 when UTF-8 characters are involved. Consequently, the byte off‐
1543 set positions are only to be relied on in the context of using
1544 them for subsequent searches on string, using an offset position
1545 as an argument to the -n option. This is mostly used to imple‐
1546 ment the "find all non-overlapping matches" functionality.
1547 A simple example of "find all non-overlapping matches":
1549 string="The following zip codes: 78884 90210 99513"
1551 pcre_compile -m "\d{5}"
1552 accum=()
1553 pcre_match -b -- $string
1554 while [[ $? -eq 0 ]] do
1555 b=($=ZPCRE_OP)
1556 accum+=$MATCH
1557 pcre_match -b -n $b[2] -- $string
1558 done
1559 print -l $accum
1560 The zsh/pcre module makes available the following test condition:
1562 expr -pcre-match pcre
1563 Matches a string against a perl-compatible regular expression.
1564 For example,
1566 [[ "$text" -pcre-match ^d+$ ]] && print text variable contains
1568 only "d's".
1569
1571 The zsh/regex module makes available the following test condition:
1572 expr -regex-match regex
1573 Matches a string against a POSIX extended regular expression.
1574 On successful match, matched portion of the string will normally
1575 be placed in the MATCH variable. If there are any capturing
1576 parentheses within the regex, then the match array variable will
1577 contain those. If the match is not successful, then the vari‐
1578 ables will not be altered.
1579 For example,
1581 [[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
1583 print -l $MATCH X $match
1584 If the option REMATCH_PCRE is not set, then the =~ operator will
1586 automatically load this module as needed and will invoke the
1587 -regex-match operator.
1588 If BASH_REMATCH is set, then the array BASH_REMATCH will be set
1590 instead of MATCH and match.
1591
1593 The zsh/sched module makes available one builtin command and one param‐
1594 eter.
1595 sched [-o] [+]hh:mm[:ss] command ...
1597 sched [-o] [+]seconds command ...
1598 sched [ -item ]
1599 Make an entry in the scheduled list of commands to execute. The
1600 time may be specified in either absolute or relative time, and
1601 either as hours, minutes and (optionally) seconds separated by a
1602 colon, or seconds alone. An absolute number of seconds indi‐
1603 cates the time since the epoch (1970/01/01 00:00); this is use‐
1604 ful in combination with the features in the zsh/datetime module,
1605 see the zsh/datetime module entry in zshmodules(1).
1606 With no arguments, prints the list of scheduled commands. If
1608 the scheduled command has the -o flag set, this is shown at the
1609 start of the command.
1610 With the argument `-item', removes the given item from the list.
1612 The numbering of the list is continuous and entries are in time
1613 order, so the numbering can change when entries are added or
1614 deleted.
1615 Commands are executed either immediately before a prompt, or
1617 while the shell's line editor is waiting for input. In the lat‐
1618 ter case it is useful to be able to produce output that does not
1619 interfere with the line being edited. Providing the option -o
1620 causes the shell to clear the command line before the event and
1621 redraw it afterwards. This should be used with any scheduled
1622 event that produces visible output to the terminal; it is not
1623 needed, for example, with output that updates a terminal emula‐
1624 tor's title bar.
1625 The sched builtin is not made available by default when the
1627 shell starts in a mode emulating another shell. It can be made
1628 available with the command `zmodload -F zsh/sched b:sched'.
1629 zsh_scheduled_events
1631 A readonly array corresponding to the events scheduled by the
1632 sched builtin. The indices of the array correspond to the num‐
1633 bers shown when sched is run with no arguments (provided that
1634 the KSH_ARRAYS option is not set). The value of the array con‐
1635 sists of the scheduled time in seconds since the epoch (see the
1636 section `The zsh/datetime Module' for facilities for using this
1637 number), followed by a colon, followed by any options (which may
1638 be empty but will be preceded by a `-' otherwise), followed by a
1639 colon, followed by the command to be executed.
1640 The sched builtin should be used for manipulating the events.
1642 Note that this will have an immediate effect on the contents of
1643 the array, so that indices may become invalid.
1644
1646 The zsh/net/socket module makes available one builtin command:
1647 zsocket [ -altv ] [ -d fd ] [ args ]
1649 zsocket is implemented as a builtin to allow full use of shell
1650 command line editing, file I/O, and job control mechanisms.
1651 Outbound Connections
1653 zsocket [ -v ] [ -d fd ] filename
1654 Open a new Unix domain connection to filename. The shell param‐
1655 eter REPLY will be set to the file descriptor associated with
1656 that connection. Currently, only stream connections are sup‐
1657 ported.
1658 If -d is specified, its argument will be taken as the target
1660 file descriptor for the connection.
1661 In order to elicit more verbose output, use -v.
1663 Inbound Connections
1665 zsocket -l [ -v ] [ -d fd ] filename
1666 zsocket -l will open a socket listening on filename. The shell
1667 parameter REPLY will be set to the file descriptor associated
1668 with that listener.
1669 If -d is specified, its argument will be taken as the target
1671 file descriptor for the connection.
1672 In order to elicit more verbose output, use -v.
1674 zsocket -a [ -tv ] [ -d targetfd ] listenfd
1676 zsocket -a will accept an incoming connection to the socket
1677 associated with listenfd. The shell parameter REPLY will be set
1678 to the file descriptor associated with the inbound connection.
1679 If -d is specified, its argument will be taken as the target
1681 file descriptor for the connection.
1682 If -t is specified, zsocket will return if no incoming connec‐
1684 tion is pending. Otherwise it will wait for one.
1685 In order to elicit more verbose output, use -v.
1687
1689 The zsh/stat module makes available one builtin command under two pos‐
1690 sible names:
1691 zstat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ] [
1693 +element ] [ file ... ]
1694 stat ...
1695 The command acts as a front end to the stat system call (see
1696 stat(2)). The same command is provided with two names; as the
1697 name stat is often used by an external command it is recommended
1698 that only the zstat form of the command is used. This can be
1699 arranged by loading the module with the command `zmodload -F
1700 zsh/stat b:zstat'.
1701 If the stat call fails, the appropriate system error message
1703 printed and status 1 is returned. The fields of struct stat
1704 give information about the files provided as arguments to the
1705 command. In addition to those available from the stat call, an
1706 extra element `link' is provided. These elements are:
1707 device The number of the device on which the file resides.
1709 inode The unique number of the file on this device (`inode'
1711 number).
1712 mode The mode of the file; that is, the file's type and access
1714 permissions. With the -s option, this will be returned
1715 as a string corresponding to the first column in the dis‐
1716 play of the ls -l command.
1717 nlink The number of hard links to the file.
1719 uid The user ID of the owner of the file. With the -s
1721 option, this is displayed as a user name.
1722 gid The group ID of the file. With the -s option, this is
1724 displayed as a group name.
1725 rdev The raw device number. This is only useful for special
1727 devices.
1728 size The size of the file in bytes.
1730 atime
1732 mtime
1733 ctime The last access, modification and inode change times of
1734 the file, respectively, as the number of seconds since
1735 midnight GMT on 1st January, 1970. With the -s option,
1736 these are printed as strings for the local time zone; the
1737 format can be altered with the -F option, and with the -g
1738 option the times are in GMT.
1739 blksize
1741 The number of bytes in one allocation block on the device
1742 on which the file resides.
1743 block The number of disk blocks used by the file.
1745 link If the file is a link and the -L option is in effect,
1747 this contains the name of the file linked to, otherwise
1748 it is empty. Note that if this element is selected
1749 (``zstat +link'') then the -L option is automatically
1750 used.
1751 A particular element may be selected by including its name pre‐
1753 ceded by a `+' in the option list; only one element is allowed.
1754 The element may be shortened to any unique set of leading char‐
1755 acters. Otherwise, all elements will be shown for all files.
1756 Options:
1758 -A array
1760 Instead of displaying the results on standard output,
1761 assign them to an array, one struct stat element per
1762 array element for each file in order. In this case nei‐
1763 ther the name of the element nor the name of the files
1764 appears in array unless the -t or -n options were given,
1765 respectively. If -t is given, the element name appears
1766 as a prefix to the appropriate array element; if -n is
1767 given, the file name appears as a separate array element
1768 preceding all the others. Other formatting options are
1769 respected.
1770 -H hash
1772 Similar to -A, but instead assign the values to hash.
1773 The keys are the elements listed above. If the -n option
1774 is provided then the name of the file is included in the
1775 hash with key name.
1776 -f fd Use the file on file descriptor fd instead of named
1778 files; no list of file names is allowed in this case.
1779 -F fmt Supplies a strftime (see strftime(3)) string for the for‐
1781 matting of the time elements. The -s option is implied.
1782 -g Show the time elements in the GMT time zone. The -s
1784 option is implied.
1785 -l List the names of the type elements (to standard output
1787 or an array as appropriate) and return immediately;
1788 options other than -A and arguments are ignored.
1789 -L Perform an lstat (see lstat(2)) rather than a stat system
1791 call. In this case, if the file is a link, information
1792 about the link itself rather than the target file is
1793 returned. This option is required to make the link ele‐
1794 ment useful. It's important to note that this is the
1795 exact opposite from ls(1), etc.
1796 -n Always show the names of files. Usually these are only
1798 shown when output is to standard output and there is more
1799 than one file in the list.
1800 -N Never show the names of files.
1802 -o If a raw file mode is printed, show it in octal, which is
1804 more useful for human consumption than the default of
1805 decimal. A leading zero will be printed in this case.
1806 Note that this does not affect whether a raw or formatted
1807 file mode is shown, which is controlled by the -r and -s
1808 options, nor whether a mode is shown at all.
1809 -r Print raw data (the default format) alongside string data
1811 (the -s format); the string data appears in parentheses
1812 after the raw data.
1813 -s Print mode, uid, gid and the three time elements as
1815 strings instead of numbers. In each case the format is
1816 like that of ls -l.
1817 -t Always show the type names for the elements of struct
1819 stat. Usually these are only shown when output is to
1820 standard output and no individual element has been
1821 selected.
1822 -T Never show the type names of the struct stat elements.
1824
1826 The zsh/system module makes available various builtin commands and
1827 parameters.
1828 Builtins
1830 syserror [ -e errvar ] [ -p prefix ] [ errno | errname ]
1831 This command prints out the error message associated with errno,
1832 a system error number, followed by a newline to standard error.
1833 Instead of the error number, a name errname, for example ENOENT,
1835 may be used. The set of names is the same as the contents of
1836 the array errnos, see below.
1837 If the string prefix is given, it is printed in front of the
1839 error message, with no intervening space.
1840 If errvar is supplied, the entire message, without a newline, is
1842 assigned to the parameter names errvar and nothing is output.
1843 A return status of 0 indicates the message was successfully
1845 printed (although it may not be useful if the error number was
1846 out of the system's range), a return status of 1 indicates an
1847 error in the parameters, and a return status of 2 indicates the
1848 error name was not recognised (no message is printed for this).
1849 sysread [ -c countvar ] [ -i infd ] [ -o outfd ]
1851 [ -s bufsize ] [ -t timeout ] [ param ]
1852 Perform a single system read from file descriptor infd, or zero
1853 if that is not given. The result of the read is stored in param
1854 or REPLY if that is not given. If countvar is given, the number
1855 of bytes read is assigned to the parameter named by countvar.
1856 The maximum number of bytes read is bufsize or 8192 if that is
1858 not given, however the command returns as soon as any number of
1859 bytes was successfully read.
1860 If timeout is given, it specifies a timeout in seconds, which
1862 may be zero to poll the file descriptor. This is handled by the
1863 poll system call if available, otherwise the select system call
1864 if available.
1865 If outfd is given, an attempt is made to write all the bytes
1867 just read to the file descriptor outfd. If this fails, because
1868 of a system error other than EINTR or because of an internal zsh
1869 error during an interrupt, the bytes read but not written are
1870 stored in the parameter named by param if supplied (no default
1871 is used in this case), and the number of bytes read but not
1872 written is stored in the parameter named by countvar if that is
1873 supplied. If it was successful, countvar contains the full num‐
1874 ber of bytes transferred, as usual, and param is not set.
1875 The error EINTR (interrupted system call) is handled internally
1877 so that shell interrupts are transparent to the caller. Any
1878 other error causes a return.
1879 The possible return statuses are
1881 0 At least one byte of data was successfully read and, if
1882 appropriate, written.
1883 1 There was an error in the parameters to the command.
1885 This is the only error for which a message is printed to
1886 standard error.
1887 2 There was an error on the read, or on polling the input
1889 file descriptor for a timeout. The parameter ERRNO gives
1890 the error.
1891 3 Data were successfully read, but there was an error writ‐
1893 ing them to outfd. The parameter ERRNO gives the error.
1894 4 The attempt to read timed out. Note this does not set
1896 ERRNO as this is not a system error.
1897 5 No system error occurred, but zero bytes were read. This
1899 usually indicates end of file. The parameters are set
1900 according to the usual rules; no write to outfd is
1901 attempted.
1902 syswrite [ -c countvar ] [ -o outfd ] data
1904 The data (a single string of bytes) are written to the file
1905 descriptor outfd, or 1 if that is not given, using the write
1906 system call. Multiple write operations may be used if the first
1907 does not write all the data.
1908 If countvar is given, the number of byte written is stored in
1910 the parameter named by countvar; this may not be the full length
1911 of data if an error occurred.
1912 The error EINTR (interrupted system call) is handled internally
1914 by retrying; otherwise an error causes the command to return.
1915 For example, if the file descriptor is set to non-blocking out‐
1916 put, an error EAGAIN (on some systems, EWOULDBLOCK) may result
1917 in the command returning early.
1918 The return status may be 0 for success, 1 for an error in the
1920 parameters to the command, or 2 for an error on the write; no
1921 error message is printed in the last case, but the parameter
1922 ERRNO will reflect the error that occurred.
1923 zsystem flock [ -t timeout ] [ -f var ] [-er] file
1925 zsystem flock -u fd_expr
1926 The builtin zsystem's subcommand flock performs advisory file
1927 locking (via the fcntl(2) system call) over the entire contents
1928 of the given file. This form of locking requires the processes
1929 accessing the file to cooperate; its most obvious use is between
1930 two instances of the shell itself.
1931 In the first form the named file, which must already exist, is
1933 locked by opening a file descriptor to the file and applying a
1934 lock to the file descriptor. The lock terminates when the shell
1935 process that created the lock exits; it is therefore often con‐
1936 venient to create file locks within subshells, since the lock is
1937 automatically released when the subshell exits. Status 0 is
1938 returned if the lock succeeds, else status 1.
1939 In the second form the file descriptor given by the arithmetic
1941 expression fd_expr is closed, releasing a lock. The file
1942 descriptor can be queried by using the `-f var' form during the
1943 lock; on a successful lock, the shell variable var is set to the
1944 file descriptor used for locking. The lock will be released if
1945 the file descriptor is closed by any other means, for example
1946 using `exec {var}>&-'; however, the form described here performs
1947 a safety check that the file descriptor is in use for file lock‐
1948 ing.
1949 By default the shell waits indefinitely for the lock to succeed.
1951 The option -t timeout specifies a timeout for the lock in sec‐
1952 onds; currently this must be an integer. The shell will attempt
1953 to lock the file once a second during this period. If the
1954 attempt times out, status 2 is returned.
1955 If the option -e is given, the file descriptor for the lock is
1957 preserved when the shell uses exec to start a new process; oth‐
1958 erwise it is closed at that point and the lock released.
1959 If the option -r is given, the lock is only for reading, other‐
1961 wise it is for reading and writing. The file descriptor is
1962 opened accordingly.
1963 zsystem supports subcommand
1965 The builtin zsystem's subcommand supports tests whether a given
1966 subcommand is supported. It returns status 0 if so, else status
1967 1. It operates silently unless there was a syntax error (i.e.
1968 the wrong number of arguments), in which case status 255 is
1969 returned. Status 1 can indicate one of two things: subcommand
1970 is known but not supported by the current operating system, or
1971 subcommand is not known (possibly because this is an older ver‐
1972 sion of the shell before it was implemented).
1973 Parameters
1975 errnos A readonly array of the names of errors defined on the system.
1976 These are typically macros defined in C by including the system
1977 header file errno.h. The index of each name (assuming the
1978 option KSH_ARRAYS is unset) corresponds to the error number.
1979 Error numbers num before the last known error which have no name
1980 are given the name Enum in the array.
1981 Note that aliases for errors are not handled; only the canonical
1983 name is used.
1984 sysparams
1986 A readonly associative array. The keys are:
1987 pid Returns the process ID of the current process, even in sub‐
1988 shells. Compare $$, which returns the process ID of the main
1989 shell process.
1990 ppid Returns the process ID of the parent of the current process,
1992 even in subshells. Compare $PPID, which returns the process ID
1993 of the parent of the main shell process.
1994
1996 The zsh/net/tcp module makes available one builtin command:
1997 ztcp [ -acflLtv ] [ -d fd ] [ args ]
1999 ztcp is implemented as a builtin to allow full use of shell com‐
2000 mand line editing, file I/O, and job control mechanisms.
2001 If ztcp is run with no options, it will output the contents of
2003 its session table.
2004 If it is run with only the option -L, it will output the con‐
2006 tents of the session table in a format suitable for automatic
2007 parsing. The option is ignored if given with a command to open
2008 or close a session. The output consists of a set of lines, one
2009 per session, each containing the following elements separated by
2010 spaces:
2011 File descriptor
2013 The file descriptor in use for the connection. For nor‐
2014 mal inbound (I) and outbound (O) connections this may be
2015 read and written by the usual shell mechanisms. However,
2016 it should only be close with `ztcp -c'.
2017 Connection type
2019 A letter indicating how the session was created:
2020 Z A session created with the zftp command.
2022 L A connection opened for listening with `ztcp -l'.
2024 I An inbound connection accepted with `ztcp -a'.
2026 O An outbound connection created with `ztcp host
2028 ...'.
2029 The local host
2031 This is usually set to an all-zero IP address as the
2032 address of the localhost is irrelevant.
2033 The local port
2035 This is likely to be zero unless the connection is for
2036 listening.
2037 The remote host
2039 This is the fully qualified domain name of the peer, if
2040 available, else an IP address. It is an all-zero IP
2041 address for a session opened for listening.
2042 The remote port
2044 This is zero for a connection opened for listening.
2045 Outbound Connections
2047 ztcp [ -v ] [ -d fd ] host [ port ]
2048 Open a new TCP connection to host. If the port is omitted, it
2049 will default to port 23. The connection will be added to the
2050 session table and the shell parameter REPLY will be set to the
2051 file descriptor associated with that connection.
2052 If -d is specified, its argument will be taken as the target
2054 file descriptor for the connection.
2055 In order to elicit more verbose output, use -v.
2057 Inbound Connections
2059 ztcp -l [ -v ] [ -d fd ] port
2060 ztcp -l will open a socket listening on TCP port. The socket
2061 will be added to the session table and the shell parameter REPLY
2062 will be set to the file descriptor associated with that lis‐
2063 tener.
2064 If -d is specified, its argument will be taken as the target
2066 file descriptor for the connection.
2067 In order to elicit more verbose output, use -v.
2069 ztcp -a [ -tv ] [ -d targetfd ] listenfd
2071 ztcp -a will accept an incoming connection to the port associ‐
2072 ated with listenfd. The connection will be added to the session
2073 table and the shell parameter REPLY will be set to the file
2074 descriptor associated with the inbound connection.
2075 If -d is specified, its argument will be taken as the target
2077 file descriptor for the connection.
2078 If -t is specified, ztcp will return if no incoming connection
2080 is pending. Otherwise it will wait for one.
2081 In order to elicit more verbose output, use -v.
2083 Closing Connections
2085 ztcp -cf [ -v ] [ fd ]
2086 ztcp -c [ -v ] [ fd ]
2087 ztcp -c will close the socket associated with fd. The socket
2088 will be removed from the session table. If fd is not specified,
2089 ztcp will close everything in the session table.
2090 Normally, sockets registered by zftp (see zshmodules(1) ) cannot
2092 be closed this way. In order to force such a socket closed, use
2093 -f.
2094 In order to elicit more verbose output, use -v.
2096 Example
2098 Here is how to create a TCP connection between two instances of zsh.
2099 We need to pick an unassigned port; here we use the randomly chosen
2100 5123.
2101 On host1,
2103 zmodload zsh/net/tcp
2104 ztcp -l 5123
2105 listenfd=$REPLY
2106 ztcp -a $listenfd
2107 fd=$REPLY
2108 The second from last command blocks until there is an incoming connec‐
2109 tion.
2110 Now create a connection from host2 (which may, of course, be the same
2112 machine):
2113 zmodload zsh/net/tcp
2114 ztcp host1 5123
2115 fd=$REPLY
2116 Now on each host, $fd contains a file descriptor for talking to the
2118 other. For example, on host1:
2119 print This is a message >&$fd
2120 and on host2:
2121 read -r line <&$fd; print -r - $line
2122 prints `This is a message'.
2123 To tidy up, on host1:
2125 ztcp -c $listenfd
2126 ztcp -c $fd
2127 and on host2
2128 ztcp -c $fd
2129
2131 The zsh/termcap module makes available one builtin command:
2132 echotc cap [ arg ... ]
2134 Output the termcap value corresponding to the capability cap,
2135 with optional arguments.
2136 The zsh/termcap module makes available one parameter:
2138 termcap
2140 An associative array that maps termcap capability codes to their
2141 values.
2142
2144 The zsh/terminfo module makes available one builtin command:
2145 echoti cap [ arg ]
2147 Output the terminfo value corresponding to the capability cap,
2148 instantiated with arg if applicable.
2149 The zsh/terminfo module makes available one parameter:
2151 terminfo
2153 An associative array that maps terminfo capability names to
2154 their values.
2155
2157 The zsh/zftp module makes available one builtin command:
2158 zftp subcommand [ args ]
2160 The zsh/zftp module is a client for FTP (file transfer proto‐
2161 col). It is implemented as a builtin to allow full use of shell
2162 command line editing, file I/O, and job control mechanisms.
2163 Often, users will access it via shell functions providing a more
2164 powerful interface; a set is provided with the zsh distribution
2165 and is described in zshzftpsys(1). However, the zftp command is
2166 entirely usable in its own right.
2167 All commands consist of the command name zftp followed by the
2169 name of a subcommand. These are listed below. The return sta‐
2170 tus of each subcommand is supposed to reflect the success or
2171 failure of the remote operation. See a description of the vari‐
2172 able ZFTP_VERBOSE for more information on how responses from the
2173 server may be printed.
2174 Subcommands
2176 open host[:port] [ user [ password [ account ] ] ]
2177 Open a new FTP session to host, which may be the name of a
2178 TCP/IP connected host or an IP number in the standard dot nota‐
2179 tion. If the argument is in the form host:port, open a connec‐
2180 tion to TCP port port instead of the standard FTP port 21. This
2181 may be the name of a TCP service or a number: see the descrip‐
2182 tion of ZFTP_PORT below for more information.
2183 If IPv6 addresses in colon format are used, the host should be
2185 surrounded by quoted square brackets to distinguish it from the
2186 port, for example '[fe80::203:baff:fe02:8b56]'. For consistency
2187 this is allowed with all forms of host.
2188 Remaining arguments are passed to the login subcommand. Note
2190 that if no arguments beyond host are supplied, open will not
2191 automatically call login. If no arguments at all are supplied,
2192 open will use the parameters set by the params subcommand.
2193 After a successful open, the shell variables ZFTP_HOST,
2195 ZFTP_PORT, ZFTP_IP and ZFTP_SYSTEM are available; see `Vari‐
2196 ables' below.
2197 login [ name [ password [ account ] ] ]
2199 user [ name [ password [ account ] ] ]
2200 Login the user name with parameters password and account. Any
2201 of the parameters can be omitted, and will be read from standard
2202 input if needed (name is always needed). If standard input is a
2203 terminal, a prompt for each one will be printed on standard
2204 error and password will not be echoed. If any of the parameters
2205 are not used, a warning message is printed.
2206 After a successful login, the shell variables ZFTP_USER,
2208 ZFTP_ACCOUNT and ZFTP_PWD are available; see `Variables' below.
2209 This command may be re-issued when a user is already logged in,
2211 and the server will first be reinitialized for a new user.
2212 params [ host [ user [ password [ account ] ] ] ]
2214 params -
2215 Store the given parameters for a later open command with no
2216 arguments. Only those given on the command line will be remem‐
2217 bered. If no arguments are given, the parameters currently set
2218 are printed, although the password will appear as a line of
2219 stars; the return status is one if no parameters were set, zero
2220 otherwise.
2221 Any of the parameters may be specified as a `?', which may need
2223 to be quoted to protect it from shell expansion. In this case,
2224 the appropriate parameter will be read from stdin as with the
2225 login subcommand, including special handling of password. If
2226 the `?' is followed by a string, that is used as the prompt for
2227 reading the parameter instead of the default message (any neces‐
2228 sary punctuation and whitespace should be included at the end of
2229 the prompt). The first letter of the parameter (only) may be
2230 quoted with a `\'; hence an argument "\\$word" guarantees that
2231 the string from the shell parameter $word will be treated liter‐
2232 ally, whether or not it begins with a `?'.
2233 If instead a single `-' is given, the existing parameters, if
2235 any, are deleted. In that case, calling open with no arguments
2236 will cause an error.
2237 The list of parameters is not deleted after a close, however it
2239 will be deleted if the zsh/zftp module is unloaded.
2240 For example,
2242 zftp params ftp.elsewhere.xx juser '?Password for juser: '
2244 will store the host ftp.elsewhere.xx and the user juser and then
2246 prompt the user for the corresponding password with the given
2247 prompt.
2248 test Test the connection; if the server has reported that it has
2250 closed the connection (maybe due to a timeout), return status 2;
2251 if no connection was open anyway, return status 1; else return
2252 status 0. The test subcommand is silent, apart from messages
2253 printed by the $ZFTP_VERBOSE mechanism, or error messages if the
2254 connection closes. There is no network overhead for this test.
2255 The test is only supported on systems with either the select(2)
2257 or poll(2) system calls; otherwise the message `not supported on
2258 this system' is printed instead.
2259 The test subcommand will automatically be called at the start of
2261 any other subcommand for the current session when a connection
2262 is open.
2263 cd directory
2265 Change the remote directory to directory. Also alters the shell
2266 variable ZFTP_PWD.
2267 cdup Change the remote directory to the one higher in the directory
2269 tree. Note that cd .. will also work correctly on non-UNIX sys‐
2270 tems.
2271 dir [ args... ]
2273 Give a (verbose) listing of the remote directory. The args are
2274 passed directly to the server. The command's behaviour is imple‐
2275 mentation dependent, but a UNIX server will typically interpret
2276 args as arguments to the ls command and with no arguments return
2277 the result of `ls -l'. The directory is listed to standard out‐
2278 put.
2279 ls [ args ]
2281 Give a (short) listing of the remote directory. With no args,
2282 produces a raw list of the files in the directory, one per line.
2283 Otherwise, up to vagaries of the server implementation, behaves
2284 similar to dir.
2285 type [ type ]
2287 Change the type for the transfer to type, or print the current
2288 type if type is absent. The allowed values are `A' (ASCII), `I'
2289 (Image, i.e. binary), or `B' (a synonym for `I').
2290 The FTP default for a transfer is ASCII. However, if zftp finds
2292 that the remote host is a UNIX machine with 8-bit byes, it will
2293 automatically switch to using binary for file transfers upon
2294 open. This can subsequently be overridden.
2295 The transfer type is only passed to the remote host when a data
2297 connection is established; this command involves no network
2298 overhead.
2299 ascii The same as type A.
2301 binary The same as type I.
2303 mode [ S | B ]
2305 Set the mode type to stream (S) or block (B). Stream mode is
2306 the default; block mode is not widely supported.
2307 remote files...
2309 local [ files... ]
2310 Print the size and last modification time of the remote or local
2311 files. If there is more than one item on the list, the name of
2312 the file is printed first. The first number is the file size,
2313 the second is the last modification time of the file in the for‐
2314 mat CCYYMMDDhhmmSS consisting of year, month, date, hour, min‐
2315 utes and seconds in GMT. Note that this format, including the
2316 length, is guaranteed, so that time strings can be directly com‐
2317 pared via the [[ builtin's < and > operators, even if they are
2318 too long to be represented as integers.
2319 Not all servers support the commands for retrieving this infor‐
2321 mation. In that case, the remote command will print nothing and
2322 return status 2, compared with status 1 for a file not found.
2323 The local command (but not remote) may be used with no argu‐
2325 ments, in which case the information comes from examining file
2326 descriptor zero. This is the same file as seen by a put command
2327 with no further redirection.
2328 get file [...]
2330 Retrieve all files from the server, concatenating them and send‐
2331 ing them to standard output.
2332 put file [...]
2334 For each file, read a file from standard input and send that to
2335 the remote host with the given name.
2336 append file [...]
2338 As put, but if the remote file already exists, data is appended
2339 to it instead of overwriting it.
2340 getat file point
2342 putat file point
2343 appendat file point
2344 Versions of get, put and append which will start the transfer at
2345 the given point in the remote file. This is useful for append‐
2346 ing to an incomplete local file. However, note that this abil‐
2347 ity is not universally supported by servers (and is not quite
2348 the behaviour specified by the standard).
2349 delete file [...]
2351 Delete the list of files on the server.
2352 mkdir directory
2354 Create a new directory directory on the server.
2355 rmdir directory
2357 Delete the directory directory on the server.
2358 rename old-name new-name
2360 Rename file old-name to new-name on the server.
2361 site args...
2363 Send a host-specific command to the server. You will probably
2364 only need this if instructed by the server to use it.
2365 quote args...
2367 Send the raw FTP command sequence to the server. You should be
2368 familiar with the FTP command set as defined in RFC959 before
2369 doing this. Useful commands may include STAT and HELP. Note
2370 also the mechanism for returning messages as described for the
2371 variable ZFTP_VERBOSE below, in particular that all messages
2372 from the control connection are sent to standard error.
2373 close
2375 quit Close the current data connection. This unsets the shell param‐
2376 eters ZFTP_HOST, ZFTP_PORT, ZFTP_IP, ZFTP_SYSTEM, ZFTP_USER,
2377 ZFTP_ACCOUNT, ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE.
2378 session [ sessname ]
2380 Allows multiple FTP sessions to be used at once. The name of
2381 the session is an arbitrary string of characters; the default
2382 session is called `default'. If this command is called without
2383 an argument, it will list all the current sessions; with an
2384 argument, it will either switch to the existing session called
2385 sessname, or create a new session of that name.
2386 Each session remembers the status of the connection, the set of
2388 connection-specific shell parameters (the same set as are unset
2389 when a connection closes, as given in the description of close),
2390 and any user parameters specified with the params subcommand.
2391 Changing to a previous session restores those values; changing
2392 to a new session initialises them in the same way as if zftp had
2393 just been loaded. The name of the current session is given by
2394 the parameter ZFTP_SESSION.
2395 rmsession [ sessname ]
2397 Delete a session; if a name is not given, the current session is
2398 deleted. If the current session is deleted, the earliest exist‐
2399 ing session becomes the new current session, otherwise the cur‐
2400 rent session is not changed. If the session being deleted is
2401 the only one, a new session called `default' is created and
2402 becomes the current session; note that this is a new session
2403 even if the session being deleted is also called `default'. It
2404 is recommended that sessions not be deleted while background
2405 commands which use zftp are still active.
2406 Parameters
2408 The following shell parameters are used by zftp. Currently none of
2409 them are special.
2410 ZFTP_TMOUT
2412 Integer. The time in seconds to wait for a network operation to
2413 complete before returning an error. If this is not set when the
2414 module is loaded, it will be given the default value 60. A
2415 value of zero turns off timeouts. If a timeout occurs on the
2416 control connection it will be closed. Use a larger value if
2417 this occurs too frequently.
2418 ZFTP_IP
2420 Readonly. The IP address of the current connection in dot nota‐
2421 tion.
2422 ZFTP_HOST
2424 Readonly. The hostname of the current remote server. If the
2425 host was opened as an IP number, ZFTP_HOST contains that
2426 instead; this saves the overhead for a name lookup, as IP num‐
2427 bers are most commonly used when a nameserver is unavailable.
2428 ZFTP_PORT
2430 Readonly. The number of the remote TCP port to which the con‐
2431 nection is open (even if the port was originally specified as a
2432 named service). Usually this is the standard FTP port, 21.
2433 In the unlikely event that your system does not have the appro‐
2435 priate conversion functions, this appears in network byte order.
2436 If your system is little-endian, the port then consists of two
2437 swapped bytes and the standard port will be reported as 5376.
2438 In that case, numeric ports passed to zftp open will also need
2439 to be in this format.
2440 ZFTP_SYSTEM
2442 Readonly. The system type string returned by the server in
2443 response to an FTP SYST request. The most interesting case is a
2444 string beginning "UNIX Type: L8", which ensures maximum compati‐
2445 bility with a local UNIX host.
2446 ZFTP_TYPE
2448 Readonly. The type to be used for data transfers , either `A'
2449 or `I'. Use the type subcommand to change this.
2450 ZFTP_USER
2452 Readonly. The username currently logged in, if any.
2453 ZFTP_ACCOUNT
2455 Readonly. The account name of the current user, if any. Most
2456 servers do not require an account name.
2457 ZFTP_PWD
2459 Readonly. The current directory on the server.
2460 ZFTP_CODE
2462 Readonly. The three digit code of the last FTP reply from the
2463 server as a string. This can still be read after the connection
2464 is closed, and is not changed when the current session changes.
2465 ZFTP_REPLY
2467 Readonly. The last line of the last reply sent by the server.
2468 This can still be read after the connection is closed, and is
2469 not changed when the current session changes.
2470 ZFTP_SESSION
2472 Readonly. The name of the current FTP session; see the descrip‐
2473 tion of the session subcommand.
2474 ZFTP_PREFS
2476 A string of preferences for altering aspects of zftp's behav‐
2477 iour. Each preference is a single character. The following are
2478 defined:
2479 P Passive: attempt to make the remote server initiate data
2481 transfers. This is slightly more efficient than sendport
2482 mode. If the letter S occurs later in the string, zftp
2483 will use sendport mode if passive mode is not available.
2484 S Sendport: initiate transfers by the FTP PORT command.
2486 If this occurs before any P in the string, passive mode
2487 will never be attempted.
2488 D Dumb: use only the bare minimum of FTP commands. This
2490 prevents the variables ZFTP_SYSTEM and ZFTP_PWD from
2491 being set, and will mean all connections default to ASCII
2492 type. It may prevent ZFTP_SIZE from being set during a
2493 transfer if the server does not send it anyway (many
2494 servers do).
2495 If ZFTP_PREFS is not set when zftp is loaded, it will be set to
2497 a default of `PS', i.e. use passive mode if available, otherwise
2498 fall back to sendport mode.
2499 ZFTP_VERBOSE
2501 A string of digits between 0 and 5 inclusive, specifying which
2502 responses from the server should be printed. All responses go
2503 to standard error. If any of the numbers 1 to 5 appear in the
2504 string, raw responses from the server with reply codes beginning
2505 with that digit will be printed to standard error. The first
2506 digit of the three digit reply code is defined by RFC959 to cor‐
2507 respond to:
2508 1. A positive preliminary reply.
2510 2. A positive completion reply.
2512 3. A positive intermediate reply.
2514 4. A transient negative completion reply.
2516 5. A permanent negative completion reply.
2518 It should be noted that, for unknown reasons, the reply `Service
2520 not available', which forces termination of a connection, is
2521 classified as 421, i.e. `transient negative', an interesting
2522 interpretation of the word `transient'.
2523 The code 0 is special: it indicates that all but the last line
2525 of multiline replies read from the server will be printed to
2526 standard error in a processed format. By convention, servers
2527 use this mechanism for sending information for the user to read.
2528 The appropriate reply code, if it matches the same response,
2529 takes priority.
2530 If ZFTP_VERBOSE is not set when zftp is loaded, it will be set
2532 to the default value 450, i.e., messages destined for the user
2533 and all errors will be printed. A null string is valid and
2534 specifies that no messages should be printed.
2535 Functions
2537 zftp_chpwd
2538 If this function is set by the user, it is called every time the
2539 directory changes on the server, including when a user is logged
2540 in, or when a connection is closed. In the last case, $ZFTP_PWD
2541 will be unset; otherwise it will reflect the new directory.
2542 zftp_progress
2544 If this function is set by the user, it will be called during a
2545 get, put or append operation each time sufficient data has been
2546 received from the host. During a get, the data is sent to stan‐
2547 dard output, so it is vital that this function should write to
2548 standard error or directly to the terminal, not to standard out‐
2549 put.
2550 When it is called with a transfer in progress, the following
2552 additional shell parameters are set:
2553 ZFTP_FILE
2555 The name of the remote file being transferred from or to.
2556 ZFTP_TRANSFER
2558 A G for a get operation and a P for a put operation.
2559 ZFTP_SIZE
2561 The total size of the complete file being transferred:
2562 the same as the first value provided by the remote and
2563 local subcommands for a particular file. If the server
2564 cannot supply this value for a remote file being
2565 retrieved, it will not be set. If input is from a pipe
2566 the value may be incorrect and correspond simply to a
2567 full pipe buffer.
2568 ZFTP_COUNT
2570 The amount of data so far transferred; a number between
2571 zero and $ZFTP_SIZE, if that is set. This number is
2572 always available.
2573 The function is initially called with ZFTP_TRANSFER set appro‐
2575 priately and ZFTP_COUNT set to zero. After the transfer is fin‐
2576 ished, the function will be called one more time with
2577 ZFTP_TRANSFER set to GF or PF, in case it wishes to tidy up. It
2578 is otherwise never called twice with the same value of
2579 ZFTP_COUNT.
2580 Sometimes the progress meter may cause disruption. It is up to
2582 the user to decide whether the function should be defined and to
2583 use unfunction when necessary.
2584 Problems
2586 A connection may not be opened in the left hand side of a pipe as this
2587 occurs in a subshell and the file information is not updated in the
2588 main shell. In the case of type or mode changes or closing the connec‐
2589 tion in a subshell, the information is returned but variables are not
2590 updated until the next call to zftp. Other status changes in subshells
2591 will not be reflected by changes to the variables (but should be other‐
2592 wise harmless).
2593 Deleting sessions while a zftp command is active in the background can
2595 have unexpected effects, even if it does not use the session being
2596 deleted. This is because all shell subprocesses share information on
2597 the state of all connections, and deleting a session changes the order‐
2598 ing of that information.
2599 On some operating systems, the control connection is not valid after a
2601 fork(), so that operations in subshells, on the left hand side of a
2602 pipeline, or in the background are not possible, as they should be.
2603 This is presumably a bug in the operating system.
2604
2606 The zsh/zle module contains the Zsh Line Editor. See zshzle(1).
2607
2609 The zsh/zleparameter module defines two special parameters that can be
2610 used to access internal information of the Zsh Line Editor (see zsh‐
2611 zle(1)).
2612 keymaps
2614 This array contains the names of the keymaps currently defined.
2615 widgets
2617 This associative array contains one entry per widget defined.
2618 The name of the widget is the key and the value gives informa‐
2619 tion about the widget. It is either the string `builtin' for
2620 builtin widgets, a string of the form `user:name' for
2621 user-defined widgets, where name is the name of the shell func‐
2622 tion implementing the widget, or it is a string of the form
2623 `completion:type:name', for completion widgets. In the last case
2624 type is the name of the builtin widgets the completion widget
2625 imitates in its behavior and name is the name of the shell func‐
2626 tion implementing the completion widget.
2627
2629 When loaded, the zsh/zprof causes shell functions to be profiled. The
2630 profiling results can be obtained with the zprof builtin command made
2631 available by this module. There is no way to turn profiling off other
2632 than unloading the module.
2633 zprof [ -c ]
2635 Without the -c option, zprof lists profiling results to standard
2636 output. The format is comparable to that of commands like
2637 gprof.
2638 At the top there is a summary listing all functions that were
2640 called at least once. This summary is sorted in decreasing
2641 order of the amount of time spent in each. The lines contain
2642 the number of the function in order, which is used in other
2643 parts of the list in suffixes of the form `[num]', then the num‐
2644 ber of calls made to the function. The next three columns list
2645 the time in milliseconds spent in the function and its descen‐
2646 dants, the average time in milliseconds spent in the function
2647 and its descendants per call and the percentage of time spent in
2648 all shell functions used in this function and its descendants.
2649 The following three columns give the same information, but
2650 counting only the time spent in the function itself. The final
2651 column shows the name of the function.
2652 After the summary, detailed information about every function
2654 that was invoked is listed, sorted in decreasing order of the
2655 amount of time spent in each function and its descendants. Each
2656 of these entries consists of descriptions for the functions that
2657 called the function described, the function itself, and the
2658 functions that were called from it. The description for the
2659 function itself has the same format as in the summary (and shows
2660 the same information). The other lines don't show the number of
2661 the function at the beginning and have their function named
2662 indented to make it easier to distinguish the line showing the
2663 function described in the section from the surrounding lines.
2664 The information shown in this case is almost the same as in the
2666 summary, but only refers to the call hierarchy being displayed.
2667 For example, for a calling function the column showing the total
2668 running time lists the time spent in the described function and
2669 its descendants only for the times when it was called from that
2670 particular calling function. Likewise, for a called function,
2671 this columns lists the total time spent in the called function
2672 and its descendants only for the times when it was called from
2673 the function described.
2674 Also in this case, the column showing the number of calls to a
2676 function also shows a slash and then the total number of invoca‐
2677 tions made to the called function.
2678 As long as the zsh/zprof module is loaded, profiling will be
2680 done and multiple invocations of the zprof builtin command will
2681 show the times and numbers of calls since the module was loaded.
2682 With the -c option, the zprof builtin command will reset its
2683 internal counters and will not show the listing.
2684
2686 The zsh/zpty module offers one builtin:
2687 zpty [ -e ] [ -b ] name [ arg ... ]
2689 The arguments following name are concatenated with spaces
2690 between, then executed as a command, as if passed to the eval
2691 builtin. The command runs under a newly assigned pseudo-termi‐
2692 nal; this is useful for running commands non-interactively which
2693 expect an interactive environment. The name is not part of the
2694 command, but is used to refer to this command in later calls to
2695 zpty.
2696 With the -e option, the pseudo-terminal is set up so that input
2698 characters are echoed.
2699 With the -b option, input to and output from the pseudo-terminal
2701 are made non-blocking.
2702 zpty -d [ names ... ]
2704 The second form, with the -d option, is used to delete commands
2705 previously started, by supplying a list of their names. If no
2706 names are given, all commands are deleted. Deleting a command
2707 causes the HUP signal to be sent to the corresponding process.
2708 zpty -w [ -n ] name [ strings ... ]
2710 The -w option can be used to send the to command name the given
2711 strings as input (separated by spaces). If the -n option is not
2712 given, a newline is added at the end.
2713 If no strings are provided, the standard input is copied to the
2715 pseudo-terminal; this may stop before copying the full input if
2716 the pseudo-terminal is non-blocking.
2717 Note that the command under the pseudo-terminal sees this input
2719 as if it were typed, so beware when sending special tty driver
2720 characters such as word-erase, line-kill, and end-of-file.
2721 zpty -r [ -mt ] name [ param [ pattern ] ]
2723 The -r option can be used to read the output of the command
2724 name. With only a name argument, the output read is copied to
2725 the standard output. Unless the pseudo-terminal is non-block‐
2726 ing, copying continues until the command under the pseudo-termi‐
2727 nal exits; when non-blocking, only as much output as is immedi‐
2728 ately available is copied. The return status is zero if any
2729 output is copied.
2730 When also given a param argument, at most one line is read and
2732 stored in the parameter named param. Less than a full line may
2733 be read if the pseudo-terminal is non-blocking. The return sta‐
2734 tus is zero if at least one character is stored in param.
2735 If a pattern is given as well, output is read until the whole
2737 string read matches the pattern, even in the non-blocking case.
2738 The return status is zero if the string read matches the pat‐
2739 tern, or if the command has exited but at least one character
2740 could still be read. If the option -m is present, the return
2741 status is zero only if the pattern matches. As of this writing,
2742 a maximum of one megabyte of output can be consumed this way; if
2743 a full megabyte is read without matching the pattern, the return
2744 status is non-zero.
2745 In all cases, the return status is non-zero if nothing could be
2747 read, and is 2 if this is because the command has finished.
2748 If the -r option is combined with the -t option, zpty tests
2750 whether output is available before trying to read. If no output
2751 is available, zpty immediately returns the status 1. When used
2752 with a pattern, the behaviour on a failed poll is similar to
2753 when the command has exited: the return value is zero if at
2754 least one character could still be read even if the pattern
2755 failed to match.
2756 zpty -t name
2758 The -t option without the -r option can be used to test whether
2759 the command name is still running. It returns a zero status if
2760 the command is running and a non-zero value otherwise.
2761 zpty [ -L ]
2763 The last form, without any arguments, is used to list the com‐
2764 mands currently defined. If the -L option is given, this is
2765 done in the form of calls to the zpty builtin.
2766
2768 The zsh/zselect module makes available one builtin command:
2769 zselect [ -rwe -t timeout -a array ] [ fd ... ]
2771 The zselect builtin is a front-end to the `select' system call,
2772 which blocks until a file descriptor is ready for reading or
2773 writing, or has an error condition, with an optional timeout.
2774 If this is not available on your system, the command prints an
2775 error message and returns status 2 (normal errors return status
2776 1). For more information, see your systems documentation for
2777 select(3). Note there is no connection with the shell builtin
2778 of the same name.
2779 Arguments and options may be intermingled in any order.
2781 Non-option arguments are file descriptors, which must be decimal
2782 integers. By default, file descriptors are to be tested for
2783 reading, i.e. zselect will return when data is available to be
2784 read from the file descriptor, or more precisely, when a read
2785 operation from the file descriptor will not block. After a -r,
2786 -w and -e, the given file descriptors are to be tested for read‐
2787 ing, writing, or error conditions. These options and an arbi‐
2788 trary list of file descriptors may be given in any order.
2789 (The presence of an `error condition' is not well defined in the
2791 documentation for many implementations of the select system
2792 call. According to recent versions of the POSIX specification,
2793 it is really an exception condition, of which the only standard
2794 example is out-of-band data received on a socket. So zsh users
2795 are unlikely to find the -e option useful.)
2796 The option `-t timeout' specifies a timeout in hundredths of a
2798 second. This may be zero, in which case the file descriptors
2799 will simply be polled and zselect will return immediately. It
2800 is possible to call zselect with no file descriptors and a
2801 non-zero timeout for use as a finer-grained replacement for
2802 `sleep'; note, however, the return status is always 1 for a
2803 timeout.
2804 The option `-a array' indicates that array should be set to
2806 indicate the file descriptor(s) which are ready. If the option
2807 is not given, the array reply will be used for this purpose.
2808 The array will contain a string similar to the arguments for
2809 zselect. For example,
2810 zselect -t 0 -r 0 -w 1
2812 might return immediately with status 0 and $reply containing `-r
2814 0 -w 1' to show that both file descriptors are ready for the
2815 requested operations.
2816 The option `-A assoc' indicates that the associative array assoc
2818 should be set to indicate the file descriptor(s( which are
2819 ready. This option overrides the option -a, nor will reply be
2820 modified. The keys of assoc are the file descriptors, and the
2821 corresponding values are any of the characters `rwe' to indicate
2822 the condition.
2823 The command returns status 0 if some file descriptors are ready
2825 for reading. If the operation timed out, or a timeout of 0 was
2826 given and no file descriptors were ready, or there was an error,
2827 it returns status 1 and the array will not be set (nor modified
2828 in any way). If there was an error in the select operation the
2829 appropriate error message is printed.
2830
2832 The zsh/zutil module only adds some builtins:
2833 zstyle [ -L [ pattern [ style ] ] ]
2835 zstyle [ -e | - | -- ] pattern style strings ...
2836 zstyle -d [ pattern [ styles ... ] ]
2837 zstyle -g name [ pattern [ style ] ]
2838 zstyle -abs context style name [ sep ]
2839 zstyle -Tt context style [ strings ...]
2840 zstyle -m context style pattern
2841 This builtin command is used to define and lookup styles.
2842 Styles are pairs of names and values, where the values consist
2843 of any number of strings. They are stored together with pat‐
2844 terns and lookup is done by giving a string, called the `con‐
2845 text', which is compared to the patterns. The definition stored
2846 for the first matching pattern will be returned.
2847 For ordering of comparisons, patterns are searched from most
2849 specific to least specific, and patterns that are equally spe‐
2850 cific keep the order in which they were defined. A pattern is
2851 considered to be more specific than another if it contains more
2852 components (substrings separated by colons) or if the patterns
2853 for the components are more specific, where simple strings are
2854 considered to be more specific than patterns and complex pat‐
2855 terns are considered to be more specific than the pattern `*'.
2856 The first form (without arguments) lists the definitions.
2858 Styles are shown in alphabetic order and patterns are shown in
2859 the order zstyle will test them.
2860 If the -L option is given, listing is done in the form of calls
2862 to zstyle. The optional first argument is a pattern which will
2863 be matched against the string supplied as the pattern for the
2864 context; note that this means, for example, `zstyle -L ":comple‐
2865 tion:*"' will match any supplied pattern beginning `:comple‐
2866 tion:', not just ":completion:*": use ":completion:\*" to match
2867 that. The optional second argument limits the output to a spe‐
2868 cific style (not a pattern). -L is not compatible with any
2869 other options.
2870 The other forms are the following:
2872 zstyle [ - | -- | -e ] pattern style strings ...
2874 Defines the given style for the pattern with the strings
2875 as the value. If the -e option is given, the strings
2876 will be concatenated (separated by spaces) and the
2877 resulting string will be evaluated (in the same way as it
2878 is done by the eval builtin command) when the style is
2879 looked up. In this case the parameter `reply' must be
2880 assigned to set the strings returned after the evalua‐
2881 tion. Before evaluating the value, reply is unset, and
2882 if it is still unset after the evaluation, the style is
2883 treated as if it were not set.
2884 zstyle -d [ pattern [ styles ... ] ]
2886 Delete style definitions. Without arguments all defini‐
2887 tions are deleted, with a pattern all definitions for
2888 that pattern are deleted and if any styles are given,
2889 then only those styles are deleted for the pattern.
2890 zstyle -g name [ pattern [ style ] ]
2892 Retrieve a style definition. The name is used as the name
2893 of an array in which the results are stored. Without any
2894 further arguments, all patterns defined are returned.
2895 With a pattern the styles defined for that pattern are
2896 returned and with both a pattern and a style, the value
2897 strings of that combination is returned.
2898 The other forms can be used to look up or test patterns.
2900 zstyle -s context style name [ sep ]
2902 The parameter name is set to the value of the style
2903 interpreted as a string. If the value contains several
2904 strings they are concatenated with spaces (or with the
2905 sep string if that is given) between them.
2906 zstyle -b context style name
2908 The value is stored in name as a boolean, i.e. as the
2909 string `yes' if the value has only one string and that
2910 string is equal to one of `yes', `true', `on', or `1'. If
2911 the value is any other string or has more than one
2912 string, the parameter is set to `no'.
2913 zstyle -a context style name
2915 The value is stored in name as an array. If name is
2916 declared as an associative array, the first, third, etc.
2917 strings are used as the keys and the other strings are
2918 used as the values.
2919 zstyle -t context style [ strings ...]
2921 zstyle -T context style [ strings ...]
2922 Test the value of a style, i.e. the -t option only
2923 returns a status (sets $?). Without any strings the
2924 return status is zero if the style is defined for at
2925 least one matching pattern, has only one string in its
2926 value, and that is equal to one of `true', `yes', `on' or
2927 `1'. If any strings are given the status is zero if and
2928 only if at least one of the strings is equal to at least
2929 one of the strings in the value. If the style is defined
2930 but doesn't match, the return status is 1. If the style
2931 is not defined, the status is 2.
2932 The -T option tests the values of the style like -t, but
2934 it returns status zero (rather than 2) if the style is
2935 not defined for any matching pattern.
2936 zstyle -m context style pattern
2938 Match a value. Returns status zero if the pattern matches
2939 at least one of the strings in the value.
2940 zformat -f param format specs ...
2942 zformat -a array sep specs ...
2943 This builtin provides two different forms of formatting. The
2944 first form is selected with the -f option. In this case the for‐
2945 mat string will be modified by replacing sequences starting with
2946 a percent sign in it with strings from the specs. Each spec
2947 should be of the form `char:string' which will cause every
2948 appearance of the sequence `%char' in format to be replaced by
2949 the string. The `%' sequence may also contain optional minimum
2950 and maximum field width specifications between the `%' and the
2951 `char' in the form `%min.maxc', i.e. the minimum field width is
2952 given first and if the maximum field width is used, it has to be
2953 preceded by a dot. Specifying a minimum field width makes the
2954 result be padded with spaces to the right if the string is
2955 shorter than the requested width. Padding to the left can be
2956 achieved by giving a negative minimum field width. If a maximum
2957 field width is specified, the string will be truncated after
2958 that many characters. After all `%' sequences for the given
2959 specs have been processed, the resulting string is stored in the
2960 parameter param.
2961 The %-escapes also understand ternary expressions in the form
2963 used by prompts. The % is followed by a `(' and then an ordi‐
2964 nary format specifier character as described above. There may
2965 be a set of digits either before or after the `('; these specify
2966 a test number, which defaults to zero. Negative numbers are
2967 also allowed. An arbitrary delimiter character follows the for‐
2968 mat specifier, which is followed by a piece of `true' text, the
2969 delimiter character again, a piece of `false' text, and a clos‐
2970 ing parenthesis. The complete expression (without the digits)
2971 thus looks like `%(X.text1.text2)', except that the `.' charac‐
2972 ter is arbitrary. The value given for the format specifier in
2973 the char:string expressions is evaluated as a mathematical
2974 expression, and compared with the test number. If they are the
2975 same, text1 is output, else text2 is output. A parenthesis may
2976 be escaped in text2 as %). Either of text1 or text2 may contain
2977 nested %-escapes.
2978 For example:
2980 zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3
2982 outputs "The answer is 'yes'." to REPLY since the value for the
2984 format specifier c is 3, agreeing with the digit argument to the
2985 ternary expression.
2986 The second form, using the -a option, can be used for aligning
2988 strings. Here, the specs are of the form `left:right' where
2989 `left' and `right' are arbitrary strings. These strings are
2990 modified by replacing the colons by the sep string and padding
2991 the left strings with spaces to the right so that the sep
2992 strings in the result (and hence the right strings after them)
2993 are all aligned if the strings are printed below each other.
2994 All strings without a colon are left unchanged and all strings
2995 with an empty right string have the trailing colon removed. In
2996 both cases the lengths of the strings are not used to determine
2997 how the other strings are to be aligned. The resulting strings
2998 are stored in the array.
2999 zregexparse
3001 This implements some internals of the _regex_arguments function.
3002 zparseopts [ -D ] [ -K ] [ -M ] [ -E ] [ -a array ] [ -A assoc ] specs
3004 This builtin simplifies the parsing of options in positional
3005 parameters, i.e. the set of arguments given by $*. Each spec
3006 describes one option and must be of the form `opt[=array]'. If
3007 an option described by opt is found in the positional parameters
3008 it is copied into the array specified with the -a option; if the
3009 optional `=array' is given, it is instead copied into that
3010 array.
3011 Note that it is an error to give any spec without an `=array'
3013 unless one of the -a or -A options is used.
3014 Unless the -E option is given, parsing stops at the first string
3016 that isn't described by one of the specs. Even with -E, parsing
3017 always stops at a positional parameter equal to `-' or `--'.
3018 The opt description must be one of the following. Any of the
3020 special characters can appear in the option name provided it is
3021 preceded by a backslash.
3022 name
3024 name+ The name is the name of the option without the leading
3025 `-'. To specify a GNU-style long option, one of the
3026 usual two leading `-' must be included in name; for exam‐
3027 ple, a `--file' option is represented by a name of
3028 `-file'.
3029 If a `+' appears after name, the option is appended to
3031 array each time it is found in the positional parameters;
3032 without the `+' only the last occurrence of the option is
3033 preserved.
3034 If one of these forms is used, the option takes no argu‐
3036 ment, so parsing stops if the next positional parameter
3037 does not also begin with `-' (unless the -E option is
3038 used).
3039 name:
3041 name:-
3042 name:: If one or two colons are given, the option takes an argu‐
3043 ment; with one colon, the argument is mandatory and with
3044 two colons it is optional. The argument is appended to
3045 the array after the option itself.
3046 An optional argument is put into the same array element
3048 as the option name (note that this makes empty strings as
3049 arguments indistinguishable). A mandatory argument is
3050 added as a separate element unless the `:-' form is used,
3051 in which case the argument is put into the same element.
3052 A `+' as described above may appear between the name and
3054 the first colon.
3055 The options of zparseopts itself are:
3057 -a array
3059 As described above, this names the default array in which to
3060 store the recognised options.
3061 -A assoc
3063 If this is given, the options and their values are also put into
3064 an associative array with the option names as keys and the argu‐
3065 ments (if any) as the values.
3066 -D If this option is given, all options found are removed from the
3068 positional parameters of the calling shell or shell function, up
3069 to but not including any not described by the specs. This is
3070 similar to using the shift builtin.
3071 -K With this option, the arrays specified with the -a and -A
3073 options and with the `=array' forms are kept unchanged when none
3074 of the specs for them is used. This allows assignment of
3075 default values to them before calling zparseopts.
3076 -M This changes the assignment rules to implement a map among
3078 equivalent option names. If any spec uses the `=array' form,
3079 the string array is interpreted as the name of another spec,
3080 which is used to choose where to store the values. If no other
3081 spec is found, the values are stored as usual. This changes
3082 only the way the values are stored, not the way $* is parsed, so
3083 results may be unpredicable if the `name+' specifier is used
3084 inconsistently.
3085 -E This changes the parsing rules to not stop at the first string
3087 that isn't described by one of the specs. It can be used to
3088 test for or (if used together with -D) extract options and their
3089 arguments, ignoring all other options and arguments that may be
3090 in the positional parameters.
3091 For example,
3093 set -- -a -bx -c y -cz baz -cend
3095 zparseopts a=foo b:=bar c+:=bar
3096 will have the effect of
3098 foo=(-a)
3100 bar=(-b x -c y -c z)
3101 The arguments from `baz' on will not be used.
3103 As an example for the -E option, consider:
3105 set -- -a x -b y -c z arg1 arg2
3107 zparseopts -E -D b:=bar
3108 will have the effect of
3110 bar=(-b y)
3112 set -- -a x -c z arg1 arg2
3113 I.e., the option -b and its arguments are taken from the positional
3115 parameters and put into the array bar.
3116 The -M option can be used like this:
3118 set -- -a -bx -c y -cz baz -cend
3120 zparseopts -A bar -M a=foo b+: c:=b
3121 to have the effect of
3123 foo=(-a)
3125 bar=(-a '' -b xyz)
3126zsh 5.0.2 December 21, 2012 ZSHMODULES(1)