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