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