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/cap
16 Builtins for manipulating POSIX.1e (POSIX.6) capability (privi‐
17 lege) sets.
18 zsh/clone
20 A builtin that can clone a running shell onto another terminal.
21 zsh/compctl
23 The compctl builtin for controlling completion.
24 zsh/complete
26 The basic completion code.
27 zsh/complist
29 Completion listing extensions.
30 zsh/computil
32 A module with utility builtins needed for the shell function
33 based completion system.
34 zsh/datetime
36 Some date/time commands and parameters.
37 zsh/deltochar
39 A ZLE function duplicating EMACS' zap-to-char.
40 zsh/example
42 An example of how to write a module.
43 zsh/files
45 Some basic file manipulation commands as builtins.
46 zsh/mapfile
48 Access to external files via a special associative array.
49 zsh/mathfunc
51 Standard scientific functions for use in mathematical evalua‐
52 tions.
53 zsh/parameter
55 Access to internal hash tables via special associative arrays.
56 zsh/pcre
58 Interface to the PCRE library.
59 zsh/sched
61 A builtin that provides a timed execution facility within the
62 shell.
63 zsh/net/socket
65 Manipulation of Unix domain sockets
66 zsh/stat
68 A builtin command interface to the stat system call.
69 zsh/system
71 A builtin interface to various low-level system features.
72 zsh/net/tcp
74 Manipulation of TCP sockets
75 zsh/termcap
77 Interface to the termcap database.
78 zsh/terminfo
80 Interface to the terminfo database.
81 zsh/zftp
83 A builtin FTP client.
84 zsh/zle
86 The Zsh Line Editor, including the bindkey and vared builtins.
87 zsh/zleparameter
89 Access to internals of the Zsh Line Editor via parameters.
90 zsh/zprof
92 A module allowing profiling for shell functions.
93 zsh/zpty
95 A builtin for starting a command in a pseudo-terminal.
96 zsh/zselect
98 Block and return when file descriptors are ready.
99 zsh/zutil
101 Some utility builtins, e.g. the one for supporting configuration
102 via styles.
103
105 The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) capabil‐
106 ity sets. If the operating system does not support this interface, the
107 builtins defined by this module will do nothing. The builtins in this
108 module are:
109 cap [ capabilities ]
111 Change the shell's process capability sets to the specified
112 capabilities, otherwise display the shell's current capabili‐
113 ties.
114 getcap filename ...
116 This is a built-in implementation of the POSIX standard utility.
117 It displays the capability sets on each specified filename.
118 setcap capabilities filename ...
120 This is a built-in implementation of the POSIX standard utility.
121 It sets the capability sets on each specified filename to the
122 specified capabilities.
123
125 The zsh/clone module makes available one builtin command:
126 clone tty
128 Creates a forked instance of the current shell, attached to the
129 specified tty. In the new shell, the PID, PPID and TTY special
130 parameters are changed appropriately. $! is set to zero in the
131 new shell, and to the new shell's PID in the original shell.
132 The return value of the builtin is zero in both shells if suc‐
134 cessful, and non-zero on error.
135 The target of clone should be an unused terminal, such as an
137 unused virtual console or a virtual terminal created by
138 xterm -e sh -c 'trap : INT QUIT TSTP; tty; while :; do sleep
140 100000000; done'
141 Some words of explanation are warranted about this long xterm
143 command line: when doing clone on a pseudo-terminal, some other
144 session ("session" meant as a unix session group, or SID) is
145 already owning the terminal. Hence the cloned zsh cannot acquire
146 the pseudo-terminal as a controlling tty. That means two things:
147 the job control signals will go to the sh-started-by-xterm
149 process
150 group (that's why we disable INT QUIT and TSTP with trap;
151 otherwise
152 the while loop could get suspended or killed)
153 the cloned shell will have job control disabled, and the job
155 control keys (control-C, control-\ and control-Z) will not
156 work.
157 This does not apply when cloning to an unused vc.
159 Cloning to an used (and unprepared) terminal will result in two
161 processes reading simultaneously from the same terminal, with
162 input bytes going randomly to either process.
163 clone is mostly useful as a shell built-in replacement for
165 openvt.
166
168 The zsh/compctl module makes available two builtin commands. compctl,
169 is the old, deprecated way to control completions for ZLE. See zshcom‐
170 pctl(1). The other builtin command, compcall can be used in
171 user-defined completion widgets, see zshcompwid(1).
172
174 The zsh/complete module makes available several builtin commands which
175 can be used in user-defined completion widgets, see zshcompwid(1).
176
178 The zsh/complist module offers three extensions to completion listings:
179 the ability to highlight matches in such a list, the ability to scroll
180 through long lists and a different style of menu completion.
181 Colored completion listings
183 Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS is set and the
184 zsh/complist module is loaded or linked into the shell, completion
185 lists will be colored. Note, however, that complist will not automati‐
186 cally be loaded if it is not linked in: on systems with dynamic load‐
187 ing, `zmodload zsh/complist' is required.
188 The parameters ZLS_COLORS and ZLS_COLOURS describe how matches are
190 highlighted. To turn on highlighting an empty value suffices, in which
191 case all the default values given below will be used. The format of
192 the value of these parameters is the same as used by the GNU version of
193 the ls command: a colon-separated list of specifications of the form
194 `name=value'. The name may be one of the following strings, most of
195 which specify file types for which the value will be used. The strings
196 and their default values are:
197 no 0 for normal text (i.e. when displaying something other than a
199 matched file)
200 fi 0 for regular files
202 di 32 for directories
204 ln 36 for symbolic links
206 pi 31 for named pipes (FIFOs)
208 so 33 for sockets
210 bd 44;37
212 for block devices
213 cd 44;37
215 for character devices
216 ex 35 for executable files
218 mi none
220 for a non-existent file (default is the value defined for fi)
221 lc \e[ for the left code (see below)
223 rc m for the right code
225 tc 0 for the character indicating the file type printed after file‐
227 names if the LIST_TYPES option is set
228 sp 0 for the spaces printed after matches to align the next column
230 ec none
232 for the end code
233 Apart from these strings, the name may also be an asterisk (`*') fol‐
235 lowed by any string. The value given for such a string will be used for
236 all files whose name ends with the string. The name may also be an
237 equals sign (`=') followed by a pattern. The value given for this pat‐
238 tern will be used for all matches (not just filenames) whose display
239 string are matched by the pattern. Definitions for both of these take
240 precedence over the values defined for file types and the form with the
241 leading asterisk takes precedence over the form with the leading equal
242 sign.
243 The last form also allows different parts of the displayed strings to
245 be colored differently. For this, the pattern has to use the `(#b)'
246 globbing flag and pairs of parentheses surrounding the parts of the
247 strings that are to be colored differently. In this case the value may
248 consist of more than one color code separated by equal signs. The
249 first code will be used for all parts for which no explicit code is
250 specified and the following codes will be used for the parts matched by
251 the sub-patterns in parentheses. For example, the specification
252 `=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least
253 two characters long and will use the code `3' for the first character,
254 `7' for the last character and `0' for the rest.
255 All three forms of name may be preceded by a pattern in parentheses.
257 If this is given, the value will be used only for matches in groups
258 whose names are matched by the pattern given in the parentheses. For
259 example, `(g*)m*=43' highlights all matches beginning with `m' in
260 groups whose names begin with `g' using the color code `43'. In case
261 of the `lc', `rc', and `ec' codes, the group pattern is ignored.
262 Note also that all patterns are tried in the order in which they appear
264 in the parameter value until the first one matches which is then used.
265 When printing a match, the code prints the value of lc, the value for
267 the file-type or the last matching specification with a `*', the value
268 of rc, the string to display for the match itself, and then the value
269 of ec if that is defined or the values of lc, no, and rc if ec is not
270 defined.
271 The default values are ISO 6429 (ANSI) compliant and can be used on
273 vt100 compatible terminals such as xterms. On monochrome terminals the
274 default values will have no visible effect. The colors function from
275 the contribution can be used to get associative arrays containing the
276 codes for ANSI terminals (see the section `Other Functions' in zshcon‐
277 trib(1)). For example, after loading colors, one could use `$col‐
278 ors[red]' to get the code for foreground color red and `$col‐
279 ors[bg-green]' for the code for background color green.
280 If the completion system invoked by compinit is used, these parameters
282 should not be set directly because the system controls them itself.
283 Instead, the list-colors style should be used (see the section `Comple‐
284 tion System Configuration' in zshcompsys(1)).
285 Scrolling in completion listings
287 To enable scrolling through a completion list, the LISTPROMPT parameter
288 must be set. Its value will be used as the prompt; if it is the empty
289 string, a default prompt will be used. The value may contain escapes
290 of the form `%x'. It supports the escapes `%B', `%b', `%S', `%s',
291 `%U', `%u' and `%{...%}' used also in shell prompts as well as three
292 pairs of additional sequences: a `%l' or `%L' is replaced by the number
293 of the last line shown and the total number of lines in the form `num‐
294 ber/total'; a `%m' or `%M' is replaced with the number of the last
295 match shown and the total number of matches; and `%p' or `%P' is
296 replaced with `Top', `Bottom' or the position of the first line shown
297 in percent of the total number of lines, respectively. In each of
298 these cases the form with the uppercase letter will be replaced with a
299 string of fixed width, padded to the right with spaces, while the low‐
300 ercase form will not be padded.
301 If the parameter LISTPROMPT is set, the completion code will not ask if
303 the list should be shown. Instead it immediately starts displaying the
304 list, stopping after the first screenful, showing the prompt at the
305 bottom, waiting for a keypress after temporarily switching to the
306 listscroll keymap. Some of the zle functions have a special meaning
307 while scrolling lists:
308 send-break
310 stops listing discarding the key pressed
311 accept-line, down-history, down-line-or-history
313 down-line-or-search, vi-down-line-or-history
314 scrolls forward one line
315 complete-word, menu-complete, expand-or-complete
317 expand-or-complete-prefix, menu-complete-or-expand
318 scrolls forward one screenful
319 Every other character stops listing and immediately processes the key
321 as usual. Any key that is not bound in the listscroll keymap or that
322 is bound to undefined-key is looked up in the keymap currently
323 selected.
324 As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not
326 be set directly when using the shell function based completion system.
327 Instead, the list-prompt style should be used.
328 Menu selection
330 The zsh/complist module also offers an alternative style of selecting
331 matches from a list, called menu selection, which can be used if the
332 shell is set up to return to the last prompt after showing a completion
333 list (see the ALWAYS_LAST_PROMPT option in zshoptions(1)). It can be
334 invoked directly by the widget menu-select defined by the module.
335 Alternatively, the parameter MENUSELECT can be set to an integer, which
336 gives the minimum number of matches that must be present before menu
337 selection is automatically turned on. This second method requires that
338 menu completion be started, either directly from a widget such as
339 menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU
340 being set. If MENUSELECT is set, but is 0, 1 or empty, menu selection
341 will always be started during an ambiguous menu completion.
342 When using the completion system based on shell functions, the MENUSE‐
344 LECT parameter should not be used (like the ZLS_COLORS and ZLS_COLOURS
345 parameters described above). Instead, the menu style should be used
346 with the select=... keyword.
347 After menu selection is started, the matches will be listed. If there
349 are more matches than fit on the screen, only the first screenful is
350 shown. The matches to insert into the command line can be selected
351 from this list. In the list one match is highlighted using the value
352 for ma from the ZLS_COLORS or ZLS_COLOURS parameter. The default value
353 for this is `7' which forces the selected match to be highlighted using
354 standout mode on a vt100-compatible terminal. If neither ZLS_COLORS
355 nor ZLS_COLOURS is set, the same terminal control sequence as for the
356 `%S' escape in prompts is used.
357 If there are more matches than fit on the screen and the parameter
359 MENUPROMPT is set, its value will be shown below the matches. It sup‐
360 ports the same escape sequences as LISTPROMPT, but the number of the
361 match or line shown will be that of the one where the mark is placed.
362 If its value is the empty string, a default prompt will be used.
363 The MENUSCROLL parameter can be used to specify how the list is
365 scrolled. If the parameter is unset, this is done line by line, if it
366 is set to `0' (zero), the list will scroll half the number of lines of
367 the screen. If the value is positive, it gives the number of lines to
368 scroll and if it is negative, the list will be scrolled the number of
369 lines of the screen minus the (absolute) value.
370 As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parameters, neither
372 MENUPROMPT nor MENUSCROLL should be set directly when using the shell
373 function based completion system. Instead, the select-prompt and
374 select-scroll styles should be used.
375 The completion code sometimes decides not to show all of the matches in
377 the list. These hidden matches are either matches for which the com‐
378 pletion function which added them explicitly requested that they not
379 appear in the list (using the -n option of the compadd builtin command)
380 or they are matches which duplicate a string already in the list
381 (because they differ only in things like prefixes or suffixes that are
382 not displayed). In the list used for menu selection, however, even
383 these matches are shown so that it is possible to select them. To
384 highlight such matches the hi and du capabilities in the ZLS_COLORS and
385 ZLS_COLOURS parameters are supported for hidden matches of the first
386 and second kind, respectively.
387 Selecting matches is done by moving the mark around using the zle move‐
389 ment functions. When not all matches can be shown on the screen at the
390 same time, the list will scroll up and down when crossing the top or
391 bottom line. The following zle functions have special meaning during
392 menu selection:
393 accept-line
395 accepts the current match and leaves menu selection
396 send-break
398 leaves menu selection and restores the previous contents of the
399 command line
400 redisplay, clear-screen
402 execute their normal function without leaving menu selection
403 accept-and-hold, accept-and-menu-complete
405 accept the currently inserted match and continue selection
406 allowing to select the next match to insert into the line
407 accept-and-infer-next-history
409 accepts the current match and then tries completion with menu
410 selection again; in the case of files this allows one to select
411 a directory and immediately attempt to complete files in it; if
412 there are no matches, a message is shown and one can use undo to
413 go back to completion on the previous level, every other key
414 leaves menu selection (including the other zle functions which
415 are otherwise special during menu selection)
416 undo removes matches inserted during the menu selection by one of the
418 three functions before
419 down-history, down-line-or-history
421 vi-down-line-or-history, down-line-or-search
422 moves the mark one line down
423 up-history, up-line-or-history
425 vi-up-line-or-history, up-line-or-search
426 moves the mark one line up
427 forward-char, vi-forward-char
429 moves the mark one column right
430 backward-char, vi-backward-char
432 moves the mark one column left
433 forward-word, vi-forward-word
435 vi-forward-word-end, emacs-forward-word
436 moves the mark one screenful down
437 backward-word, vi-backward-word, emacs-backward-word
439 moves the mark one screenful up
440 vi-forward-blank-word, vi-forward-blank-word-end
442 moves the mark to the first line of the next group of matches
443 vi-backward-blank-word
445 moves the mark to the last line of the previous group of matches
446 beginning-of-history
448 moves the mark to the first line
449 end-of-history
451 moves the mark to the last line
452 beginning-of-buffer-or-history, beginning-of-line
454 beginning-of-line-hist, vi-beginning-of-line
455 moves the mark to the leftmost column
456 end-of-buffer-or-history, end-of-line
458 end-of-line-hist, vi-end-of-line
459 moves the mark to the rightmost column
460 complete-word, menu-complete, expand-or-complete
462 expand-or-complete-prefix, menu-expand-or-complete
463 moves the mark to the next match
464 reverse-menu-complete
466 moves the mark to the previous match
467 vi-insert
469 this toggles between normal and interactive mode; in interactive
470 mode the keys bound to self-insert and self-insert-unmeta insert
471 into the command line as in normal editing mode but without
472 leaving menu selection; after each character completion is tried
473 again and the list changes to contain only the new matches; the
474 completion widgets make the longest unambiguous string be
475 inserted in the command line and undo and backward-delete-char
476 go back to the previous set of matches
477 history-incremental-search-forward,
479 history-incremental-search-backward this starts incremental
480 searches in the list of completions displayed; in this mode,
481 accept-line only leaves incremental search, going back to the
482 normal menu selection mode
483 All movement functions wrap around at the edges; any other zle function
485 not listed leaves menu selection and executes that function. It is
486 possible to make widgets in the above list do the same by using the
487 form of the widget with a `.' in front. For example, the widget
488 `.accept-line' has the effect of leaving menu selection and accepting
489 the entire command line.
490 During this selection the widget uses the keymap menuselect. Any key
492 that is not defined in this keymap or that is bound to undefined-key is
493 looked up in the keymap currently selected. This is used to ensure
494 that the most important keys used during selection (namely the cursor
495 keys, return, and TAB) have sensible defaults. However, keys in the
496 menuselect keymap can be modified directly using the bindkey builtin
497 command (see zshmodules(1)). For example, to make the return key leave
498 menu selection without accepting the match currently selected one could
499 call
500 bindkey -M menuselect '^M' send-break
502 after loading the zsh/complist module.
504
506 The zsh/computil module adds several builtin commands that are used by
507 some of the completion functions in the completion system based on
508 shell functions (see zshcompsys(1) ). Except for compquote these
509 builtin commands are very specialised and thus not very interesting
510 when writing your own completion functions. In summary, these builtin
511 commands are:
512 comparguments
514 This is used by the _arguments function to do the argument and
515 command line parsing. Like compdescribe it has an option -i to
516 do the parsing and initialize some internal state and various
517 options to access the state information to decide what should be
518 completed.
519 compdescribe
521 This is used by the _describe function to build the displays for
522 the matches and to get the strings to add as matches with their
523 options. On the first call one of the options -i or -I should
524 be supplied as the first argument. In the first case, display
525 strings without the descriptions will be generated, in the sec‐
526 ond case, the string used to separate the matches from their
527 descriptions must be given as the second argument and the
528 descriptions (if any) will be shown. All other arguments are
529 like the definition arguments to _describe itself.
530 Once compdescribe has been called with either the -i or the -I
532 option, it can be repeatedly called with the -g option and the
533 names of five arrays as its arguments. This will step through
534 the different sets of matches and store the options in the first
535 array, the strings with descriptions in the second, the matches
536 for these in the third, the strings without descriptions in the
537 fourth, and the matches for them in the fifth array. These are
538 then directly given to compadd to register the matches with the
539 completion code.
540 compfiles
542 Used by the _path_files function to optimize complex recursive
543 filename generation (globbing). It does three things. With the
544 -p and -P options it builds the glob patterns to use, including
545 the paths already handled and trying to optimize the patterns
546 with respect to the prefix and suffix from the line and the
547 match specification currently used. The -i option does the
548 directory tests for the ignore-parents style and the -r option
549 tests if a component for some of the matches are equal to the
550 string on the line and removes all other matches if that is
551 true.
552 compgroups
554 Used by the _tags function to implement the internals of the
555 group-order style. This only takes its arguments as names of
556 completion groups and creates the groups for it (all six types:
557 sorted and unsorted, both without removing duplicates, with
558 removing all duplicates and with removing consecutive dupli‐
559 cates).
560 compquote [ -p ] names ...
562 There may be reasons to write completion functions that have to
563 add the matches using the -Q option to compadd and perform quot‐
564 ing themselves. Instead of interpreting the first character of
565 the all_quotes key of the compstate special association and
566 using the q flag for parameter expansions, one can use this
567 builtin command. The arguments are the names of scalar or array
568 parameters and the values of these parameters are quoted as
569 needed for the innermost quoting level. If the -p option is
570 given, quoting is done as if there is some prefix before the
571 values of the parameters, so that a leading equal sign will not
572 be quoted.
573 The return value is non-zero in case of an error and zero other‐
575 wise.
576 comptags
578 comptry
579 These implement the internals of the tags mechanism.
580 compvalues
582 Like comparguments, but for the _values function.
583
585 The zsh/datetime module makes available one builtin command:
586 strftime [ -s scalar ] format epochtime
588 Output the date denoted by epochtime in the format specified.
589 If -s scalar is given, assign the date to scalar instead of
591 printing it.
592 The zsh/datetime module makes available one parameter:
594 EPOCHSECONDS
596 An integer value representing the number of seconds since the
597 epoch.
598
600 The zsh/deltochar module makes available two ZLE functions:
601 delete-to-char
603 Read a character from the keyboard, and delete from the cursor
604 position up to and including the next (or, with repeat count n,
605 the nth) instance of that character. Negative repeat counts
606 mean delete backwards.
607 zap-to-char
609 This behaves like delete-to-char, except that the final occur‐
610 rence of the character itself is not deleted.
611
613 The zsh/example module makes available one builtin command:
614 example [ -flags ] [ args ... ]
616 Displays the flags and arguments it is invoked with.
617 The purpose of the module is to serve as an example of how to write a
619 module.
620
622 The zsh/files module makes some standard commands available as
623 builtins:
624 chgrp [ -Rs ] group filename ...
626 Changes group of files specified. This is equivalent to chown
627 with a user-spec argument of `:group'.
628 chown [ -Rs ] user-spec filename ...
630 Changes ownership and group of files specified.
631 The user-spec can be in four forms:
633 user change owner to user; do not change group
635 user:: change owner to user; do not change group
636 user: change owner to user; change group to user's primary
637 group
638 user:group
639 change owner to user; change group to group
640 :group do not change owner; change group to group
641 In each case, the `:' may instead be a `.'. The rule is that if
643 there is a `:' then the separator is `:', otherwise if there is
644 a `.' then the separator is `.', otherwise there is no separa‐
645 tor.
646 Each of user and group may be either a username (or group name,
648 as appropriate) or a decimal user ID (group ID). Interpretation
649 as a name takes precedence, if there is an all-numeric username
650 (or group name).
651 The -R option causes chown to recursively descend into directo‐
653 ries, changing the ownership of all files in the directory after
654 changing the ownership of the directory itself.
655 The -s option is a zsh extension to chown functionality. It
657 enables paranoid behaviour, intended to avoid security problems
658 involving a chown being tricked into affecting files other than
659 the ones intended. It will refuse to follow symbolic links, so
660 that (for example) ``chown luser /tmp/foo/passwd'' can't acci‐
661 dentally chown /etc/passwd if /tmp/foo happens to be a link to
662 /etc. It will also check where it is after leaving directories,
663 so that a recursive chown of a deep directory tree can't end up
664 recursively chowning /usr as a result of directories being moved
665 up the tree.
666 ln [ -dfis ] filename dest
668 ln [ -dfis ] filename ... dir
669 Creates hard (or, with -s, symbolic) links. In the first form,
670 the specified destination is created, as a link to the specified
671 filename. In the second form, each of the filenames is taken in
672 turn, and linked to a pathname in the specified directory that
673 has the same last pathname component.
674 Normally, ln will not attempt to create hard links to directo‐
676 ries. This check can be overridden using the -d option. Typi‐
677 cally only the super-user can actually succeed in creating hard
678 links to directories. This does not apply to symbolic links in
679 any case.
680 By default, existing files cannot be replaced by links. The -i
682 option causes the user to be queried about replacing existing
683 files. The -f option causes existing files to be silently
684 deleted, without querying. -f takes precedence.
685 mkdir [ -p ] [ -m mode ] dir ...
687 Creates directories. With the -p option, non-existing parent
688 directories are first created if necessary, and there will be no
689 complaint if the directory already exists. The -m option can be
690 used to specify (in octal) a set of file permissions for the
691 created directories, otherwise mode 777 modified by the current
692 umask (see umask(2)) is used.
693 mv [ -fi ] filename dest
695 mv [ -fi ] filename ... dir
696 Moves files. In the first form, the specified filename is moved
697 to the specified destination. In the second form, each of the
698 filenames is taken in turn, and moved to a pathname in the spec‐
699 ified directory that has the same last pathname component.
700 By default, the user will be queried before replacing any file
702 that the user cannot write to, but writable files will be
703 silently removed. The -i option causes the user to be queried
704 about replacing any existing files. The -f option causes any
705 existing files to be silently deleted, without querying. -f
706 takes precedence.
707 Note that this mv will not move files across devices. Histori‐
709 cal versions of mv, when actual renaming is impossible, fall
710 back on copying and removing files; if this behaviour is
711 desired, use cp and rm manually. This may change in a future
712 version.
713 rm [ -dfirs ] filename ...
715 Removes files and directories specified.
716 Normally, rm will not remove directories (except with the -r
718 option). The -d option causes rm to try removing directories
719 with unlink (see unlink(2)), the same method used for files.
720 Typically only the super-user can actually succeed in unlinking
721 directories in this way. -d takes precedence over -r.
722 By default, the user will be queried before removing any file
724 that the user cannot write to, but writable files will be
725 silently removed. The -i option causes the user to be queried
726 about removing any files. The -f option causes files to be
727 silently deleted, without querying, and suppresses all error
728 indications. -f takes precedence.
729 The -r option causes rm to recursively descend into directories,
731 deleting all files in the directory before removing the direc‐
732 tory with the rmdir system call (see rmdir(2)).
733 The -s option is a zsh extension to rm functionality. It
735 enables paranoid behaviour, intended to avoid common security
736 problems involving a root-run rm being tricked into removing
737 files other than the ones intended. It will refuse to follow
738 symbolic links, so that (for example) ``rm /tmp/foo/passwd''
739 can't accidentally remove /etc/passwd if /tmp/foo happens to be
740 a link to /etc. It will also check where it is after leaving
741 directories, so that a recursive removal of a deep directory
742 tree can't end up recursively removing /usr as a result of
743 directories being moved up the tree.
744 rmdir dir ...
746 Removes empty directories specified.
747 sync Calls the system call of the same name (see sync(2)), which
749 flushes dirty buffers to disk. It might return before the I/O
750 has actually been completed.
751
753 The zsh/mapfile module provides one special associative array parameter
754 of the same name.
755 mapfile
757 This associative array takes as keys the names of files; the
758 resulting value is the content of the file. The value is
759 treated identically to any other text coming from a parameter.
760 The value may also be assigned to, in which case the file in
761 question is written (whether or not it originally existed); or
762 an element may be unset, which will delete the file in question.
763 For example, `vared mapfile[myfile]' works as expected, editing
764 the file `myfile'.
765 When the array is accessed as a whole, the keys are the names of
767 files in the current directory, and the values are empty (to
768 save a huge overhead in memory). Thus ${(k)mapfile} has the
769 same affect as the glob operator *(D), since files beginning
770 with a dot are not special. Care must be taken with expressions
771 such as rm ${(k)mapfile}, which will delete every file in the
772 current directory without the usual `rm *' test.
773 The parameter mapfile may be made read-only; in that case, files
775 referenced may not be written or deleted.
776 Limitations
778 Although reading and writing of the file in question is efficiently
779 handled, zsh's internal memory management may be arbitrarily baroque.
780 Thus it should not automatically be assumed that use of mapfile repre‐
781 sents a gain in efficiency over use of other mechanisms. Note in par‐
782 ticular that the whole contents of the file will always reside physi‐
783 cally in memory when accessed (possibly multiple times, due to standard
784 parameter substitution operations). In particular, this means handling
785 of sufficiently long files (greater than the machine's swap space, or
786 than the range of the pointer type) will be incorrect.
787 No errors are printed or flagged for non-existent, unreadable, or
789 unwritable files, as the parameter mechanism is too low in the shell
790 execution hierarchy to make this convenient.
791 It is unfortunate that the mechanism for loading modules does not yet
793 allow the user to specify the name of the shell parameter to be given
794 the special behaviour.
795
797 The zsh/mathfunc module provides standard mathematical functions for
798 use when evaluating mathematical formulae. The syntax agrees with nor‐
799 mal C and FORTRAN conventions, for example,
800 (( f = sin(0.3) ))
802 assigns the sine of 0.3 to the parameter f.
804 Most functions take floating point arguments and return a floating
806 point value. However, any necessary conversions from or to integer
807 type will be performed automatically by the shell. Apart from atan
808 with a second argument and the abs, int and float functions, all func‐
809 tions behave as noted in the manual page for the corresponding C func‐
810 tion, except that any arguments out of range for the function in ques‐
811 tion will be detected by the shell and an error reported.
812 The following functions take a single floating point argument: acos,
814 acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp,
815 expm1, fabs, floor, gamma, j0, j1, lgamma, log, log10, log1p, logb,
816 sin, sinh, sqrt, tan, tanh, y0, y1. The atan function can optionally
817 take a second argument, in which case it behaves like the C function
818 atan2. The ilogb function takes a single floating point argument, but
819 returns an integer.
820 The function signgam takes no arguments, and returns an integer, which
822 is the C variable of the same name, as described in gamma(3). Note
823 that it is therefore only useful immediately after a call to gamma or
824 lgamma. Note also that `signgam()' and `signgam' are distinct expres‐
825 sions.
826 The following functions take two floating point arguments: copysign,
828 fmod, hypot, nextafter.
829 The following take an integer first argument and a floating point sec‐
831 ond argument: jn, yn.
832 The following take a floating point first argument and an integer sec‐
834 ond argument: ldexp, scalb.
835 The function abs does not convert the type of its single argument; it
837 returns the absolute value of either a floating point number or an
838 integer. The functions float and int convert their arguments into a
839 floating point or integer value (by truncation) respectively.
840 Note that the C pow function is available in ordinary math evaluation
842 as the `**' operator and is not provided here.
843 The function rand48 is available if your system's mathematical library
845 has the function erand48(3). It returns a pseudo-random floating point
846 number between 0 and 1. It takes a single string optional argument.
847 If the argument is not present, the random number seed is initialised
849 by three calls to the rand(3) function --- this produces the same ran‐
850 dom numbers as the next three values of $RANDOM.
851 If the argument is present, it gives the name of a scalar parameter
853 where the current random number seed will be stored. On the first
854 call, the value must contain at least twelve hexadecimal digits (the
855 remainder of the string is ignored), or the seed will be initialised in
856 the same manner as for a call to rand48 with no argument. Subsequent
857 calls to rand48(param) will then maintain the seed in the parameter
858 param as a string of twelve hexadecimal digits, with no base signifier.
859 The random number sequences for different parameters are completely
860 independent, and are also independent from that used by calls to rand48
861 with no argument.
862 For example, consider
864 print $(( rand48(seed) ))
866 print $(( rand48() ))
867 print $(( rand48(seed) ))
868 Assuming $seed does not exist, it will be initialised by the first
870 call. In the second call, the default seed is initialised; note, how‐
871 ever, that because of the properties of rand() there is a correlation
872 between the seeds used for the two initialisations, so for more secure
873 uses, you should generate your own 12-byte seed. The third call
874 returns to the same sequence of random numbers used in the first call,
875 unaffected by the intervening rand48().
876
878 The zsh/parameter module gives access to some of the internal hash
879 tables used by the shell by defining some special parameters.
880 options
882 The keys for this associative array are the names of the options
883 that can be set and unset using the setopt and unsetopt
884 builtins. The value of each key is either the string on if the
885 option is currently set, or the string off if the option is
886 unset. Setting a key to one of these strings is like setting or
887 unsetting the option, respectively. Unsetting a key in this
888 array is like setting it to the value off.
889 commands
891 This array gives access to the command hash table. The keys are
892 the names of external commands, the values are the pathnames of
893 the files that would be executed when the command would be
894 invoked. Setting a key in this array defines a new entry in this
895 table in the same way as with the hash builtin. Unsetting a key
896 as in `unset "commands[foo]"' removes the entry for the given
897 key from the command hash table.
898 functions
900 This associative array maps names of enabled functions to their
901 definitions. Setting a key in it is like defining a function
902 with the name given by the key and the body given by the value.
903 Unsetting a key removes the definition for the function named by
904 the key.
905 dis_functions
907 Like functions but for disabled functions.
908 builtins
910 This associative array gives information about the builtin com‐
911 mands currently enabled. The keys are the names of the builtin
912 commands and the values are either `undefined' for builtin com‐
913 mands that will automatically be loaded from a module if invoked
914 or `defined' for builtin commands that are already loaded.
915 dis_builtins
917 Like builtins but for disabled builtin commands.
918 reswords
920 This array contains the enabled reserved words.
921 dis_reswords
923 Like reswords but for disabled reserved words.
924 aliases
926 This maps the names of the regular aliases currently enabled to
927 their expansions.
928 dis_aliases
930 Like aliases but for disabled regular aliases.
931 galiases
933 Like aliases, but for global aliases.
934 dis_galiases
936 Like galiases but for disabled global aliases.
937 saliases
939 Like raliases, but for suffix aliases.
940 dis_saliases
942 Like saliases but for disabled suffix aliases.
943 parameters
945 The keys in this associative array are the names of the parame‐
946 ters currently defined. The values are strings describing the
947 type of the parameter, in the same format used by the t parame‐
948 ter flag, see zshexpn(1) . Setting or unsetting keys in this
949 array is not possible.
950 modules
952 An associative array giving information about modules. The keys
953 are the names of the modules loaded, registered to be
954 autoloaded, or aliased. The value says which state the named
955 module is in and is one of the strings `loaded', `autoloaded',
956 or `alias:name', where name is the name the module is aliased
957 to.
958 Setting or unsetting keys in this array is not possible.
960 dirstack
962 A normal array holding the elements of the directory stack. Note
963 that the output of the dirs builtin command includes one more
964 directory, the current working directory.
965 history
967 This associative array maps history event numbers to the full
968 history lines.
969 historywords
971 A special array containing the words stored in the history.
972 jobdirs
974 This associative array maps job numbers to the directories from
975 which the job was started (which may not be the current direc‐
976 tory of the job).
977 jobtexts
979 This associative array maps job numbers to the texts of the com‐
980 mand lines that were used to start the jobs.
981 jobstates
983 This associative array gives information about the states of the
984 jobs currently known. The keys are the job numbers and the val‐
985 ues are strings of the form `job-state:mark:pid=state...'. The
986 job-state gives the state the whole job is currently in, one of
987 `running', `suspended', or `done'. The mark is `+' for the cur‐
988 rent job, `-' for the previous job and empty otherwise. This is
989 followed by one `pid=state' for every process in the job. The
990 pids are, of course, the process IDs and the state describes the
991 state of that process.
992 nameddirs
994 This associative array maps the names of named directories to
995 the pathnames they stand for.
996 userdirs
998 This associative array maps user names to the pathnames of their
999 home directories.
1000 funcstack
1002 This array contains the names of the functions currently being
1003 executed. The first element is the name of the function using
1004 the parameter.
1005
1007 The zsh/pcre module makes some commands available as builtins:
1008 pcre_compile [ -aimx ] PCRE
1010 Compiles a perl-compatible regular expression.
1011 Option -a will force the pattern to be anchored. Option -i will
1013 compile a case-insensitive pattern. Option -m will compile a
1014 multi-line pattern; that is, ^ and $ will match newlines within
1015 the pattern. Option -x will compile an extended pattern,
1016 wherein whitespace and # comments are ignored.
1017 pcre_study
1019 Studies the previously-compiled PCRE which may result in faster
1020 matching.
1021 pcre_match [ -a arr ] string
1023 Returns successfully if string matches the previously-compiled
1024 PCRE.
1025 If the expression captures substrings within parentheses,
1027 pcre_match will set the array $match to those substrings, unless
1028 the -a option is given, in which case it will set the array arr.
1029 The zsh/pcre module makes available the following test condition:
1031 expr -pcre-match pcre
1032 Matches a string against a perl-compatible regular expression.
1033 For example,
1035 [[ "$text" -pcre-match ^d+$ ]] && print text variable contains
1037 only "d's".
1038
1040 The zsh/sched module makes available one builtin command:
1041 sched [+]hh:mm command ...
1043 sched [ -item ]
1044 Make an entry in the scheduled list of commands to execute. The
1045 time may be specified in either absolute or relative time. With
1046 no arguments, prints the list of scheduled commands. With the
1047 argument `-item', removes the given item from the list.
1048
1050 The zsh/net/socket module makes available one builtin command:
1051 zsocket [ -altv ] [ -d fd ] [ args ]
1053 zsocket is implemented as a builtin to allow full use of shell
1054 command line editing, file I/O, and job control mechanisms.
1055 Outbound Connections
1057 zsocket [ -v ] [ -d fd ] filename
1058 Open a new Unix domain connection to filename. The shell param‐
1059 eter REPLY will be set to the file descriptor associated with
1060 that connection. Currently, only stream connections are sup‐
1061 ported.
1062 If -d is specified, its argument will be taken as the target
1064 file descriptor for the connection.
1065 In order to elicit more verbose output, use -v.
1067 Inbound Connections
1069 zsocket -l [ -v ] [ -d fd ] filename
1070 zsocket -l will open a socket listening on filename. The shell
1071 parameter REPLY will be set to the file descriptor associated
1072 with that listener.
1073 If -d is specified, its argument will be taken as the target
1075 file descriptor for the connection.
1076 In order to elicit more verbose output, use -v.
1078 zsocket -a [ -tv ] [ -d targetfd ] listenfd
1080 zsocket -a will accept an incoming connection to the socket
1081 associated with listenfd. The shell parameter REPLY will be set
1082 to the file descriptor associated with the inbound connection.
1083 If -d is specified, its argument will be taken as the target
1085 file descriptor for the connection.
1086 If -t is specified, zsocket will return if no incoming connec‐
1088 tion is pending. Otherwise it will wait for one.
1089 In order to elicit more verbose output, use -v.
1091
1093 The zsh/stat module makes available one builtin command:
1094 stat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ] [
1096 +element ] [ file ... ]
1097 The command acts as a front end to the stat system call (see
1098 stat(2)). If the stat call fails, the appropriate system error
1099 message printed and status 1 is returned. The fields of struct
1100 stat give information about the files provided as arguments to
1101 the command. In addition to those available from the stat call,
1102 an extra element `link' is provided. These elements are:
1103 device The number of the device on which the file resides.
1105 inode The unique number of the file on this device (`inode'
1107 number).
1108 mode The mode of the file; that is, the file's type and access
1110 permissions. With the -s option, this will be returned
1111 as a string corresponding to the first column in the dis‐
1112 play of the ls -l command.
1113 nlink The number of hard links to the file.
1115 uid The user ID of the owner of the file. With the -s
1117 option, this is displayed as a user name.
1118 gid The group ID of the file. With the -s option, this is
1120 displayed as a group name.
1121 rdev The raw device number. This is only useful for special
1123 devices.
1124 size The size of the file in bytes.
1126 atime
1128 mtime
1129 ctime The last access, modification and inode change times of
1130 the file, respectively, as the number of seconds since
1131 midnight GMT on 1st January, 1970. With the -s option,
1132 these are printed as strings for the local time zone; the
1133 format can be altered with the -F option, and with the -g
1134 option the times are in GMT.
1135 blksize
1137 The number of bytes in one allocation block on the device
1138 on which the file resides.
1139 block The number of disk blocks used by the file.
1141 link If the file is a link and the -L option is in effect,
1143 this contains the name of the file linked to, otherwise
1144 it is empty. Note that if this element is selected
1145 (``stat +link'') then the -L option is automatically
1146 used.
1147 A particular element may be selected by including its name pre‐
1149 ceded by a `+' in the option list; only one element is allowed.
1150 The element may be shortened to any unique set of leading char‐
1151 acters. Otherwise, all elements will be shown for all files.
1152 Options:
1154 -A array
1156 Instead of displaying the results on standard output,
1157 assign them to an array, one struct stat element per
1158 array element for each file in order. In this case nei‐
1159 ther the name of the element nor the name of the files
1160 appears in array unless the -t or -n options were given,
1161 respectively. If -t is given, the element name appears
1162 as a prefix to the appropriate array element; if -n is
1163 given, the file name appears as a separate array element
1164 preceding all the others. Other formatting options are
1165 respected.
1166 -H hash
1168 Similar to -A, but instead assign the values to hash.
1169 The keys are the elements listed above. If the -n option
1170 is provided then the name of the file is included in the
1171 hash with key name.
1172 -f fd Use the file on file descriptor fd instead of named
1174 files; no list of file names is allowed in this case.
1175 -F fmt Supplies a strftime (see strftime(3)) string for the for‐
1177 matting of the time elements. The -s option is implied.
1178 -g Show the time elements in the GMT time zone. The -s
1180 option is implied.
1181 -l List the names of the type elements (to standard output
1183 or an array as appropriate) and return immediately;
1184 options other than -A and arguments are ignored.
1185 -L Perform an lstat (see lstat(2)) rather than a stat system
1187 call. In this case, if the file is a link, information
1188 about the link itself rather than the target file is
1189 returned. This option is required to make the link ele‐
1190 ment useful.
1191 -n Always show the names of files. Usually these are only
1193 shown when output is to standard output and there is more
1194 than one file in the list.
1195 -N Never show the names of files.
1197 -o If a raw file mode is printed, show it in octal, which is
1199 more useful for human consumption than the default of
1200 decimal. A leading zero will be printed in this case.
1201 Note that this does not affect whether a raw or formatted
1202 file mode is shown, which is controlled by the -r and -s
1203 options, nor whether a mode is shown at all.
1204 -r Print raw data (the default format) alongside string data
1206 (the -s format); the string data appears in parentheses
1207 after the raw data.
1208 -s Print mode, uid, gid and the three time elements as
1210 strings instead of numbers. In each case the format is
1211 like that of ls -l.
1212 -t Always show the type names for the elements of struct
1214 stat. Usually these are only shown when output is to
1215 standard output and no individual element has been
1216 selected.
1217 -T Never show the type names of the struct stat elements.
1219
1221 The zsh/system module makes available three builtin commands and a
1222 parameter.
1223
1225 syserror [ -e errvar ] [ -p prefix ] [ errno | errname ]
1226 This command prints out the error message associated with errno,
1227 a system error number, followed by a newline to standard error.
1228 Instead of the error number, a name errname, for example ENOENT,
1230 may be used. The set of names is the same as the contents of
1231 the array errnos, see below.
1232 If the string prefix is given, it is printed in front of the
1234 error message, with no intervening space.
1235 If errvar is supplied, the entire message, without a newline, is
1237 assigned to the parameter names errvar and nothing is output.
1238 A return value of 0 indicates the message was successfully
1240 printed (although it may not be useful if the error number was
1241 out of the system's range), a return value of 1 indicates an
1242 error in the parameters, and a return value of 2 indicates the
1243 error name was not recognised (no message is printed for this).
1244 sysread [ -c countvar ] [ -i infd ] [ -o outfd ]
1246 [ -s bufsize ] [ -t timeout ] [ param ]
1247 Perform a single system read from file descriptor infd, or zero
1248 if that is not given. The result of the read is stored in param
1249 or REPLY if that is not given. If countvar is given, the number
1250 of bytes read is assigned to the parameter named by countvar.
1251 The maximum number of bytes read is bufsize or 8192 if that is
1253 not given, however the command returns as soon as any number of
1254 bytes was successfully read.
1255 If timeout is given, it specifies a timeout in seconds, which
1257 may be zero to poll the file descriptor. This is handled by the
1258 poll system call if available, otherwise the select system call
1259 if available.
1260 If outfd is given, an attempt is made to write all the bytes
1262 just read to the file descriptor outfd. If this fails, because
1263 of a system error other than EINTR or because of an internal zsh
1264 error during an interrupt, the bytes read but not written are
1265 stored in the parameter named by param if supplied (no default
1266 is used in this case), and the number of bytes read but not
1267 written is stored in the parameter named by countvar if that is
1268 supplied. If it was successful, countvar contains the full num‐
1269 ber of bytes transferred, as usual, and param is not set.
1270 The error EINTR (interrupted system call) is handled internally
1272 so that shell interrupts are transparent to the caller. Any
1273 other error causes a return.
1274 The possible return values are
1276 0 At least one byte of data was successfully read and, if
1277 appropriate, written.
1278 1 There was an error in the parameters to the command.
1280 This is the only error for which a message is printed to
1281 standard error.
1282 2 There was an error on the read, or on polling the input
1284 file descriptor for a timeout. The parameter ERRNO gives
1285 the error.
1286 3 Data were successfully read, but there was an error writ‐
1288 ing them to outfd. The parameter ERRNO gives the error.
1289 4 The attempt to read timed out. Note this does not set
1291 ERRNO as this is not a system error.
1292 5 No system error occurred, but zero bytes were read. This
1294 usually indicates end of file. The parameters are set
1295 according to the usual rules; no write to outfd is
1296 attempted.
1297 syswrite [ -c countvar ] [ -o outfd ] data
1299 The data (a single string of bytes) are written to the file
1300 descriptor outfd, or 1 if that is not given, using the write
1301 system call. Multiple write operations may be used if the first
1302 does not write all the data.
1303 If countvar is given, the number of byte written is stored in
1305 the parameter named by countvar; this may not be the full length
1306 of data if an error occurred.
1307 The error EINTR (interrupted system call) is handled internally
1309 by retrying; otherwise an error causes the command to return.
1310 For example, if the file descriptor is set to non-blocking out‐
1311 put, an error EAGAIN (on some systems, EWOULDBLOCK) may result
1312 in the command returning early.
1313 The return status may be 0 for success, 1 for an error in the
1315 parameters to the command, or 2 for an error on the write; no
1316 error message is printed in the last case, but the parameter
1317 ERRNO will reflect the error that occurred.
1318
1320 errnos A readonly array of the names of errors defined on the system.
1321 These are typically macros defined in C by including the system
1322 header file errno.h. The index of each name (assuming the
1323 option KSH_ARRAYS is unset) corresponds to the error number.
1324 Error numbers num before the last known error which have no name
1325 are given the name Enum in the array.
1326 Note that aliases for errors are not handled; only the canonical
1328 name is used.
1329
1331 The zsh/net/tcp module makes available one builtin command:
1332 ztcp [ -acflLtv ] [ -d fd ] [ args ]
1334 ztcp is implemented as a builtin to allow full use of shell com‐
1335 mand line editing, file I/O, and job control mechanisms.
1336 If ztcp is run with no options, it will output the contents of
1338 its session table.
1339 If it is run with only the option -L, it will output the con‐
1341 tents of the session table in a format suitable for automatic
1342 parsing. The option is ignored if given with a command to open
1343 or close a session. The output consists of a set of lines, one
1344 per session, each containing the following elements separated by
1345 spaces:
1346 File descriptor
1348 The file descriptor in use for the connection. For nor‐
1349 mal inbound (I) and outbound (O) connections this may be
1350 read and written by the usual shell mechanisms. However,
1351 it should only be close with `ztcp -c'.
1352 Connection type
1354 A letter indicating how the session was created:
1355 Z A session created with the zftp command.
1357 L A connection opened for listening with `ztcp -l'.
1359 I An inbound connection accepted with `ztcp -a'.
1361 O An outbound connection created with `ztcp host
1363 ...'.
1364 The local host
1366 This is usually set to an all-zero IP address as the
1367 address of the localhost is irrelevant.
1368 The local port
1370 This is likely to be zero unless the connection is for
1371 listening.
1372 The remote host
1374 This is the fully qualified domain name of the peer, if
1375 available, else an IP address. It is an all-zero IP
1376 address for a session opened for listening.
1377 The remote port
1379 This is zero for a connection opened for listening.
1380 Outbound Connections
1382 ztcp [ -v ] [ -d fd ] host [ port ]
1383 Open a new TCP connection to host. If the port is omitted, it
1384 will default to port 23. The connection will be added to the
1385 session table and the shell parameter REPLY will be set to the
1386 file descriptor associated with that connection.
1387 If -d is specified, its argument will be taken as the target
1389 file descriptor for the connection.
1390 In order to elicit more verbose output, use -v.
1392 Inbound Connections
1394 ztcp -l [ -v ] [ -d fd ] port
1395 ztcp -l will open a socket listening on TCP port. The socket
1396 will be added to the session table and the shell parameter REPLY
1397 will be set to the file descriptor associated with that lis‐
1398 tener.
1399 If -d is specified, its argument will be taken as the target
1401 file descriptor for the connection.
1402 In order to elicit more verbose output, use -v.
1404 ztcp -a [ -tv ] [ -d targetfd ] listenfd
1406 ztcp -a will accept an incoming connection to the port associ‐
1407 ated with listenfd. The connection will be added to the session
1408 table and the shell parameter REPLY will be set to the file
1409 descriptor associated with the inbound connection.
1410 If -d is specified, its argument will be taken as the target
1412 file descriptor for the connection.
1413 If -t is specified, ztcp will return if no incoming connection
1415 is pending. Otherwise it will wait for one.
1416 In order to elicit more verbose output, use -v.
1418 Closing Connections
1420 ztcp -cf [ -v ] [ fd ]
1421 ztcp -c [ -v ] [ fd ]
1422 ztcp -c will close the socket associated with fd. The socket
1423 will be removed from the session table. If fd is not specified,
1424 ztcp will close everything in the session table.
1425 Normally, sockets registered by zftp (see zshmodules(1) ) cannot
1427 be closed this way. In order to force such a socket closed, use
1428 -f.
1429 In order to elicit more verbose output, use -v.
1431 Example
1433 Here is how to create a TCP connection between two instances of zsh.
1434 We need to pick an unassigned port; here we use the randomly chosen
1435 5123.
1436 On host1,
1438 zmodload zsh/net/tcp
1439 ztcp -l 5123
1440 listenfd=$REPLY
1441 ztcp -a $listenfd
1442 fd=$REPLY
1443 The second from last command blocks until there is an incoming connec‐
1444 tion.
1445 Now create a connection from host2 (which may, of course, be the same
1447 machine):
1448 zmodload zsh/net/tcp
1449 ztcp host1 5123
1450 fd=$REPLY
1451 Now on each host, $fd contains a file descriptor for talking to the
1453 other. For example, on host1:
1454 print This is a message >&$fd
1455 and on host2:
1456 read -r line <&$fd; print -r - $line
1457 prints `This is a message'.
1458 To tidy up, on host1:
1460 ztcp -c $listenfd
1461 ztcp -c $fd
1462 and on host2
1463 ztcp -c $fd
1464
1466 The zsh/termcap module makes available one builtin command:
1467 echotc cap [ arg ... ]
1469 Output the termcap value corresponding to the capability cap,
1470 with optional arguments.
1471 The zsh/termcap module makes available one parameter:
1473 termcap
1475 An associative array that maps termcap capability codes to their
1476 values.
1477
1479 The zsh/terminfo module makes available one builtin command:
1480 echoti cap [ arg ]
1482 Output the terminfo value corresponding to the capability cap,
1483 instantiated with arg if applicable.
1484 The zsh/terminfo module makes available one parameter:
1486 terminfo
1488 An associative array that maps terminfo capability names to
1489 their values.
1490
1492 The zsh/zftp module makes available one builtin command:
1493 zftp subcommand [ args ]
1495 The zsh/zftp module is a client for FTP (file transfer proto‐
1496 col). It is implemented as a builtin to allow full use of shell
1497 command line editing, file I/O, and job control mechanisms.
1498 Often, users will access it via shell functions providing a more
1499 powerful interface; a set is provided with the zsh distribution
1500 and is described in zshzftpsys(1). However, the zftp command is
1501 entirely usable in its own right.
1502 All commands consist of the command name zftp followed by the
1504 name of a subcommand. These are listed below. The return sta‐
1505 tus of each subcommand is supposed to reflect the success or
1506 failure of the remote operation. See a description of the vari‐
1507 able ZFTP_VERBOSE for more information on how responses from the
1508 server may be printed.
1509 Subcommands
1511 open host[:port] [ user [ password [ account ] ] ]
1512 Open a new FTP session to host, which may be the name of a
1513 TCP/IP connected host or an IP number in the standard dot nota‐
1514 tion. If the argument is in the form host:port, open a connec‐
1515 tion to TCP port port instead of the standard FTP port 21. This
1516 may be the name of a TCP service or a number: see the descrip‐
1517 tion of ZFTP_PORT below for more information.
1518 If IPv6 addresses in colon format are used, the host should be
1520 surrounded by quoted square brackets to distinguish it from the
1521 port, for example '[fe80::203:baff:fe02:8b56]'. For consistency
1522 this is allowed with all forms of host.
1523 Remaining arguments are passed to the login subcommand. Note
1525 that if no arguments beyond host are supplied, open will not
1526 automatically call login. If no arguments at all are supplied,
1527 open will use the parameters set by the params subcommand.
1528 After a successful open, the shell variables ZFTP_HOST,
1530 ZFTP_PORT, ZFTP_IP and ZFTP_SYSTEM are available; see `Vari‐
1531 ables' below.
1532 login [ name [ password [ account ] ] ]
1534 user [ name [ password [ account ] ] ]
1535 Login the user name with parameters password and account. Any
1536 of the parameters can be omitted, and will be read from standard
1537 input if needed (name is always needed). If standard input is a
1538 terminal, a prompt for each one will be printed on standard
1539 error and password will not be echoed. If any of the parameters
1540 are not used, a warning message is printed.
1541 After a successful login, the shell variables ZFTP_USER,
1543 ZFTP_ACCOUNT and ZFTP_PWD are available; see `Variables' below.
1544 This command may be re-issued when a user is already logged in,
1546 and the server will first be reinitialized for a new user.
1547 params [ host [ user [ password [ account ] ] ] ]
1549 params -
1550 Store the given parameters for a later open command with no
1551 arguments. Only those given on the command line will be remem‐
1552 bered. If no arguments are given, the parameters currently set
1553 are printed, although the password will appear as a line of
1554 stars; the return value is one if no parameters were set, zero
1555 otherwise.
1556 Any of the parameters may be specified as a `?', which may need
1558 to be quoted to protect it from shell expansion. In this case,
1559 the appropriate parameter will be read from stdin as with the
1560 login subcommand, including special handling of password. If
1561 the `?' is followed by a string, that is used as the prompt for
1562 reading the parameter instead of the default message (any neces‐
1563 sary punctuation and whitespace should be included at the end of
1564 the prompt). The first letter of the parameter (only) may be
1565 quoted with a `\'; hence an argument "\\$word" guarantees that
1566 the string from the shell parameter $word will be treated liter‐
1567 ally, whether or not it begins with a `?'.
1568 If instead a single `-' is given, the existing parameters, if
1570 any, are deleted. In that case, calling open with no arguments
1571 will cause an error.
1572 The list of parameters is not deleted after a close, however it
1574 will be deleted if the zsh/zftp module is unloaded.
1575 For example,
1577 zftp params ftp.elsewhere.xx juser '?Password for juser: '
1579 will store the host ftp.elsewhere.xx and the user juser and then
1581 prompt the user for the corresponding password with the given
1582 prompt.
1583 test Test the connection; if the server has reported that it has
1585 closed the connection (maybe due to a timeout), return status 2;
1586 if no connection was open anyway, return status 1; else return
1587 status 0. The test subcommand is silent, apart from messages
1588 printed by the $ZFTP_VERBOSE mechanism, or error messages if the
1589 connection closes. There is no network overhead for this test.
1590 The test is only supported on systems with either the select(2)
1592 or poll(2) system calls; otherwise the message `not supported on
1593 this system' is printed instead.
1594 The test subcommand will automatically be called at the start of
1596 any other subcommand for the current session when a connection
1597 is open.
1598 cd directory
1600 Change the remote directory to directory. Also alters the shell
1601 variable ZFTP_PWD.
1602 cdup Change the remote directory to the one higher in the directory
1604 tree. Note that cd .. will also work correctly on non-UNIX sys‐
1605 tems.
1606 dir [ args... ]
1608 Give a (verbose) listing of the remote directory. The args are
1609 passed directly to the server. The command's behaviour is imple‐
1610 mentation dependent, but a UNIX server will typically interpret
1611 args as arguments to the ls command and with no arguments return
1612 the result of `ls -l'. The directory is listed to standard out‐
1613 put.
1614 ls [ args ]
1616 Give a (short) listing of the remote directory. With no args,
1617 produces a raw list of the files in the directory, one per line.
1618 Otherwise, up to vagaries of the server implementation, behaves
1619 similar to dir.
1620 type [ type ]
1622 Change the type for the transfer to type, or print the current
1623 type if type is absent. The allowed values are `A' (ASCII), `I'
1624 (Image, i.e. binary), or `B' (a synonym for `I').
1625 The FTP default for a transfer is ASCII. However, if zftp finds
1627 that the remote host is a UNIX machine with 8-bit byes, it will
1628 automatically switch to using binary for file transfers upon
1629 open. This can subsequently be overridden.
1630 The transfer type is only passed to the remote host when a data
1632 connection is established; this command involves no network
1633 overhead.
1634 ascii The same as type A.
1636 binary The same as type I.
1638 mode [ S | B ]
1640 Set the mode type to stream (S) or block (B). Stream mode is
1641 the default; block mode is not widely supported.
1642 remote files...
1644 local [ files... ]
1645 Print the size and last modification time of the remote or local
1646 files. If there is more than one item on the list, the name of
1647 the file is printed first. The first number is the file size,
1648 the second is the last modification time of the file in the for‐
1649 mat CCYYMMDDhhmmSS consisting of year, month, date, hour, min‐
1650 utes and seconds in GMT. Note that this format, including the
1651 length, is guaranteed, so that time strings can be directly com‐
1652 pared via the [[ builtin's < and > operators, even if they are
1653 too long to be represented as integers.
1654 Not all servers support the commands for retrieving this infor‐
1656 mation. In that case, the remote command will print nothing and
1657 return status 2, compared with status 1 for a file not found.
1658 The local command (but not remote) may be used with no argu‐
1660 ments, in which case the information comes from examining file
1661 descriptor zero. This is the same file as seen by a put command
1662 with no further redirection.
1663 get file [...]
1665 Retrieve all files from the server, concatenating them and send‐
1666 ing them to standard output.
1667 put file [...]
1669 For each file, read a file from standard input and send that to
1670 the remote host with the given name.
1671 append file [...]
1673 As put, but if the remote file already exists, data is appended
1674 to it instead of overwriting it.
1675 getat file point
1677 putat file point
1678 appendat file point
1679 Versions of get, put and append which will start the transfer at
1680 the given point in the remote file. This is useful for append‐
1681 ing to an incomplete local file. However, note that this abil‐
1682 ity is not universally supported by servers (and is not quite
1683 the behaviour specified by the standard).
1684 delete file [...]
1686 Delete the list of files on the server.
1687 mkdir directory
1689 Create a new directory directory on the server.
1690 rmdir directory
1692 Delete the directory directory on the server.
1693 rename old-name new-name
1695 Rename file old-name to new-name on the server.
1696 site args...
1698 Send a host-specific command to the server. You will probably
1699 only need this if instructed by the server to use it.
1700 quote args...
1702 Send the raw FTP command sequence to the server. You should be
1703 familiar with the FTP command set as defined in RFC959 before
1704 doing this. Useful commands may include STAT and HELP. Note
1705 also the mechanism for returning messages as described for the
1706 variable ZFTP_VERBOSE below, in particular that all messages
1707 from the control connection are sent to standard error.
1708 close
1710 quit Close the current data connection. This unsets the shell param‐
1711 eters ZFTP_HOST, ZFTP_PORT, ZFTP_IP, ZFTP_SYSTEM, ZFTP_USER,
1712 ZFTP_ACCOUNT, ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE.
1713 session [ sessname ]
1715 Allows multiple FTP sessions to be used at once. The name of
1716 the session is an arbitrary string of characters; the default
1717 session is called `default'. If this command is called without
1718 an argument, it will list all the current sessions; with an
1719 argument, it will either switch to the existing session called
1720 sessname, or create a new session of that name.
1721 Each session remembers the status of the connection, the set of
1723 connection-specific shell parameters (the same set as are unset
1724 when a connection closes, as given in the description of close),
1725 and any user parameters specified with the params subcommand.
1726 Changing to a previous session restores those values; changing
1727 to a new session initialises them in the same way as if zftp had
1728 just been loaded. The name of the current session is given by
1729 the parameter ZFTP_SESSION.
1730 rmsession [ sessname ]
1732 Delete a session; if a name is not given, the current session is
1733 deleted. If the current session is deleted, the earliest exist‐
1734 ing session becomes the new current session, otherwise the cur‐
1735 rent session is not changed. If the session being deleted is
1736 the only one, a new session called `default' is created and
1737 becomes the current session; note that this is a new session
1738 even if the session being deleted is also called `default'. It
1739 is recommended that sessions not be deleted while background
1740 commands which use zftp are still active.
1741 Parameters
1743 The following shell parameters are used by zftp. Currently none of
1744 them are special.
1745 ZFTP_TMOUT
1747 Integer. The time in seconds to wait for a network operation to
1748 complete before returning an error. If this is not set when the
1749 module is loaded, it will be given the default value 60. A
1750 value of zero turns off timeouts. If a timeout occurs on the
1751 control connection it will be closed. Use a larger value if
1752 this occurs too frequently.
1753 ZFTP_IP
1755 Readonly. The IP address of the current connection in dot nota‐
1756 tion.
1757 ZFTP_HOST
1759 Readonly. The hostname of the current remote server. If the
1760 host was opened as an IP number, ZFTP_HOST contains that
1761 instead; this saves the overhead for a name lookup, as IP num‐
1762 bers are most commonly used when a nameserver is unavailable.
1763 ZFTP_PORT
1765 Readonly. The number of the remote TCP port to which the con‐
1766 nection is open (even if the port was originally specified as a
1767 named service). Usually this is the standard FTP port, 21.
1768 In the unlikely event that your system does not have the appro‐
1770 priate conversion functions, this appears in network byte order.
1771 If your system is little-endian, the port then consists of two
1772 swapped bytes and the standard port will be reported as 5376.
1773 In that case, numeric ports passed to zftp open will also need
1774 to be in this format.
1775 ZFTP_SYSTEM
1777 Readonly. The system type string returned by the server in
1778 response to an FTP SYST request. The most interesting case is a
1779 string beginning "UNIX Type: L8", which ensures maximum compati‐
1780 bility with a local UNIX host.
1781 ZFTP_TYPE
1783 Readonly. The type to be used for data transfers , either `A'
1784 or `I'. Use the type subcommand to change this.
1785 ZFTP_USER
1787 Readonly. The username currently logged in, if any.
1788 ZFTP_ACCOUNT
1790 Readonly. The account name of the current user, if any. Most
1791 servers do not require an account name.
1792 ZFTP_PWD
1794 Readonly. The current directory on the server.
1795 ZFTP_CODE
1797 Readonly. The three digit code of the last FTP reply from the
1798 server as a string. This can still be read after the connection
1799 is closed, and is not changed when the current session changes.
1800 ZFTP_REPLY
1802 Readonly. The last line of the last reply sent by the server.
1803 This can still be read after the connection is closed, and is
1804 not changed when the current session changes.
1805 ZFTP_SESSION
1807 Readonly. The name of the current FTP session; see the descrip‐
1808 tion of the session subcommand.
1809 ZFTP_PREFS
1811 A string of preferences for altering aspects of zftp's behav‐
1812 iour. Each preference is a single character. The following are
1813 defined:
1814 P Passive: attempt to make the remote server initiate data
1816 transfers. This is slightly more efficient than sendport
1817 mode. If the letter S occurs later in the string, zftp
1818 will use sendport mode if passive mode is not available.
1819 S Sendport: initiate transfers by the FTP PORT command.
1821 If this occurs before any P in the string, passive mode
1822 will never be attempted.
1823 D Dumb: use only the bare minimum of FTP commands. This
1825 prevents the variables ZFTP_SYSTEM and ZFTP_PWD from
1826 being set, and will mean all connections default to ASCII
1827 type. It may prevent ZFTP_SIZE from being set during a
1828 transfer if the server does not send it anyway (many
1829 servers do).
1830 If ZFTP_PREFS is not set when zftp is loaded, it will be set to
1832 a default of `PS', i.e. use passive mode if available, otherwise
1833 fall back to sendport mode.
1834 ZFTP_VERBOSE
1836 A string of digits between 0 and 5 inclusive, specifying which
1837 responses from the server should be printed. All responses go
1838 to standard error. If any of the numbers 1 to 5 appear in the
1839 string, raw responses from the server with reply codes beginning
1840 with that digit will be printed to standard error. The first
1841 digit of the three digit reply code is defined by RFC959 to cor‐
1842 respond to:
1843 1. A positive preliminary reply.
1845 2. A positive completion reply.
1847 3. A positive intermediate reply.
1849 4. A transient negative completion reply.
1851 5. A permanent negative completion reply.
1853 It should be noted that, for unknown reasons, the reply `Service
1855 not available', which forces termination of a connection, is
1856 classified as 421, i.e. `transient negative', an interesting
1857 interpretation of the word `transient'.
1858 The code 0 is special: it indicates that all but the last line
1860 of multiline replies read from the server will be printed to
1861 standard error in a processed format. By convention, servers
1862 use this mechanism for sending information for the user to read.
1863 The appropriate reply code, if it matches the same response,
1864 takes priority.
1865 If ZFTP_VERBOSE is not set when zftp is loaded, it will be set
1867 to the default value 450, i.e., messages destined for the user
1868 and all errors will be printed. A null string is valid and
1869 specifies that no messages should be printed.
1870 Functions
1872 zftp_chpwd
1873 If this function is set by the user, it is called every time the
1874 directory changes on the server, including when a user is logged
1875 in, or when a connection is closed. In the last case, $ZFTP_PWD
1876 will be unset; otherwise it will reflect the new directory.
1877 zftp_progress
1879 If this function is set by the user, it will be called during a
1880 get, put or append operation each time sufficient data has been
1881 received from the host. During a get, the data is sent to stan‐
1882 dard output, so it is vital that this function should write to
1883 standard error or directly to the terminal, not to standard out‐
1884 put.
1885 When it is called with a transfer in progress, the following
1887 additional shell parameters are set:
1888 ZFTP_FILE
1890 The name of the remote file being transferred from or to.
1891 ZFTP_TRANSFER
1893 A G for a get operation and a P for a put operation.
1894 ZFTP_SIZE
1896 The total size of the complete file being transferred:
1897 the same as the first value provided by the remote and
1898 local subcommands for a particular file. If the server
1899 cannot supply this value for a remote file being
1900 retrieved, it will not be set. If input is from a pipe
1901 the value may be incorrect and correspond simply to a
1902 full pipe buffer.
1903 ZFTP_COUNT
1905 The amount of data so far transferred; a number between
1906 zero and $ZFTP_SIZE, if that is set. This number is
1907 always available.
1908 The function is initially called with ZFTP_TRANSFER set appro‐
1910 priately and ZFTP_COUNT set to zero. After the transfer is fin‐
1911 ished, the function will be called one more time with
1912 ZFTP_TRANSFER set to GF or PF, in case it wishes to tidy up. It
1913 is otherwise never called twice with the same value of
1914 ZFTP_COUNT.
1915 Sometimes the progress meter may cause disruption. It is up to
1917 the user to decide whether the function should be defined and to
1918 use unfunction when necessary.
1919 Problems
1921 A connection may not be opened in the left hand side of a pipe as this
1922 occurs in a subshell and the file information is not updated in the
1923 main shell. In the case of type or mode changes or closing the connec‐
1924 tion in a subshell, the information is returned but variables are not
1925 updated until the next call to zftp. Other status changes in subshells
1926 will not be reflected by changes to the variables (but should be other‐
1927 wise harmless).
1928 Deleting sessions while a zftp command is active in the background can
1930 have unexpected effects, even if it does not use the session being
1931 deleted. This is because all shell subprocesses share information on
1932 the state of all connections, and deleting a session changes the order‐
1933 ing of that information.
1934 On some operating systems, the control connection is not valid after a
1936 fork(), so that operations in subshells, on the left hand side of a
1937 pipeline, or in the background are not possible, as they should be.
1938 This is presumably a bug in the operating system.
1939
1941 The zsh/zle module contains the Zsh Line Editor. See zshzle(1).
1942
1944 The zsh/zleparameter module defines two special parameters that can be
1945 used to access internal information of the Zsh Line Editor (see zsh‐
1946 zle(1)).
1947 keymaps
1949 This array contains the names of the keymaps currently defined.
1950 widgets
1952 This associative array contains one entry per widget defined.
1953 The name of the widget is the key and the value gives informa‐
1954 tion about the widget. It is either the string `builtin' for
1955 builtin widgets, a string of the form `user:name' for
1956 user-defined widgets, where name is the name of the shell func‐
1957 tion implementing the widget, or it is a string of the form
1958 `completion:type:name', for completion widgets. In the last case
1959 type is the name of the builtin widgets the completion widget
1960 imitates in its behavior and name is the name of the shell func‐
1961 tion implementing the completion widget.
1962
1964 When loaded, the zsh/zprof causes shell functions to be profiled. The
1965 profiling results can be obtained with the zprof builtin command made
1966 available by this module. There is no way to turn profiling off other
1967 than unloading the module.
1968 zprof [ -c ]
1970 Without the -c option, zprof lists profiling results to standard
1971 output. The format is comparable to that of commands like
1972 gprof.
1973 At the top there is a summary listing all functions that were
1975 called at least once. This summary is sorted in decreasing
1976 order of the amount of time spent in each. The lines contain
1977 the number of the function in order, which is used in other
1978 parts of the list in suffixes of the form `[num]'.RE, then the
1979 number of calls made to the function. The next three columns
1980 list the time in milliseconds spent in the function and its
1981 descendents, the average time in milliseconds spent in the func‐
1982 tion and its descendents per call and the percentage of time
1983 spent in all shell functions used in this function and its
1984 descendents. The following three columns give the same informa‐
1985 tion, but counting only the time spent in the function itself.
1986 The final column shows the name of the function.
1987 After the summary, detailed information about every function
1989 that was invoked is listed, sorted in decreasing order of the
1990 amount of time spent in each function and its descendents. Each
1991 of these entries consists of descriptions for the functions that
1992 called the function described, the function itself, and the
1993 functions that were called from it. The description for the
1994 function itself has the same format as in the summary (and shows
1995 the same information). The other lines don't show the number of
1996 the function at the beginning and have their function named
1997 indented to make it easier to distinguish the line showing the
1998 function described in the section from the surrounding lines.
1999 The information shown in this case is almost the same as in the
2001 summary, but only refers to the call hierarchy being displayed.
2002 For example, for a calling function the column showing the total
2003 running time lists the time spent in the described function and
2004 its descendents only for the times when it was called from that
2005 particular calling function. Likewise, for a called function,
2006 this columns lists the total time spent in the called function
2007 and its descendents only for the times when it was called from
2008 the function described.
2009 Also in this case, the column showing the number of calls to a
2011 function also shows a slash and then the total number of invoca‐
2012 tions made to the called function.
2013 As long as the zsh/zprof module is loaded, profiling will be
2015 done and multiple invocations of the zprof builtin command will
2016 show the times and numbers of calls since the module was loaded.
2017 With the -c option, the zprof builtin command will reset its
2018 internal counters and will not show the listing. )
2019
2021 The zsh/zpty module offers one builtin:
2022 zpty [ -e ] [ -b ] name [ arg ... ]
2024 The arguments following name are concatenated with spaces
2025 between, then executed as a command, as if passed to the eval
2026 builtin. The command runs under a newly assigned pseudo-termi‐
2027 nal; this is useful for running commands non-interactively which
2028 expect an interactive environment. The name is not part of the
2029 command, but is used to refer to this command in later calls to
2030 zpty.
2031 With the -e option, the pseudo-terminal is set up so that input
2033 characters are echoed.
2034 With the -b option, input to and output from the pseudo-terminal
2036 are made non-blocking.
2037 zpty -d [ names ... ]
2039 The second form, with the -d option, is used to delete commands
2040 previously started, by supplying a list of their names. If no
2041 names are given, all commands are deleted. Deleting a command
2042 causes the HUP signal to be sent to the corresponding process.
2043 zpty -w [ -n ] name [ strings ... ]
2045 The -w option can be used to send the to command name the given
2046 strings as input (separated by spaces). If the -n option is not
2047 given, a newline is added at the end.
2048 If no strings are provided, the standard input is copied to the
2050 pseudo-terminal; this may stop before copying the full input if
2051 the pseudo-terminal is non-blocking.
2052 Note that the command under the pseudo-terminal sees this input
2054 as if it were typed, so beware when sending special tty driver
2055 characters such as word-erase, line-kill, and end-of-file.
2056 zpty -r [ -t ] name [ param [ pattern ] ]
2058 The -r option can be used to read the output of the command
2059 name. With only a name argument, the output read is copied to
2060 the standard output. Unless the pseudo-terminal is non-block‐
2061 ing, copying continues until the command under the pseudo-termi‐
2062 nal exits; when non-blocking, only as much output as is immedi‐
2063 ately available is copied. The return value is zero if any out‐
2064 put is copied.
2065 When also given a param argument, at most one line is read and
2067 stored in the parameter named param. Less than a full line may
2068 be read if the pseudo-terminal is non-blocking. The return
2069 value is zero if at least one character is stored in param.
2070 If a pattern is given as well, output is read until the whole
2072 string read matches the pattern, even in the non-blocking case.
2073 The return value is zero if the string read matches the pattern,
2074 or if the command has exited but at least one character could
2075 still be read. As of this writing, a maximum of one megabyte of
2076 output can be consumed this way; if a full megabyte is read
2077 without matching the pattern, the return value is non-zero.
2078 In all cases, the return value is non-zero if nothing could be
2080 read, and is 2 if this is because the command has finished.
2081 If the -r option is combined with the -t option, zpty tests
2083 whether output is available before trying to read. If no output
2084 is available, zpty immediately returns the value 1.
2085 zpty -t name
2087 The -t option without the -r option can be used to test whether
2088 the command name is still running. It returns a zero value if
2089 the command is running and a non-zero value otherwise.
2090 zpty [ -L ]
2092 The last form, without any arguments, is used to list the com‐
2093 mands currently defined. If the -L option is given, this is
2094 done in the form of calls to the zpty builtin.
2095
2097 The zsh/zselect module makes available one builtin command:
2098 zselect [ -rwe -t timeout -a array ] [ fd ... ]
2100 The zselect builtin is a front-end to the `select' system call,
2101 which blocks until a file descriptor is ready for reading or
2102 writing, or has an error condition, with an optional timeout.
2103 If this is not available on your system, the command prints an
2104 error message and returns status 2 (normal errors return status
2105 1). For more information, see your systems documentation for
2106 select(3). Note there is no connection with the shell builtin
2107 of the same name.
2108 Arguments and options may be intermingled in any order.
2110 Non-option arguments are file descriptors, which must be decimal
2111 integers. By default, file descriptors are to be tested for
2112 reading, i.e. zselect will return when data is available to be
2113 read from the file descriptor, or more precisely, when a read
2114 operation from the file descriptor will not block. After a -r,
2115 -w and -e, the given file descriptors are to be tested for read‐
2116 ing, writing, or error conditions. These options and an arbi‐
2117 trary list of file descriptors may be given in any order.
2118 (The presence of an `error condition' is not well defined in the
2120 documentation for many implementations of the select system
2121 call. According to recent versions of the POSIX specification,
2122 it is really an exception condition, of which the only standard
2123 example is out-of-band data received on a socket. So zsh users
2124 are unlikely to find the -e option useful.)
2125 The option `-t timeout' specifies a timeout in hundredths of a
2127 second. This may be zero, in which case the file descriptors
2128 will simply be polled and zselect will return immediately. It
2129 is possible to call zselect with no file descriptors and a
2130 non-zero timeout for use as a finer-grained replacement for
2131 `sleep'; not, however, the return status is always 1 for a time‐
2132 out.
2133 The option `-a array' indicates that array should be set to
2135 indicate the file descriptor(s) which are ready. If the option
2136 is not given, the array reply will be used for this purpose.
2137 The array will contain a string similar to the arguments for
2138 zselect. For example,
2139 zselect -t 0 -r 0 -w 1
2141 might return immediately with status 0 and $reply containing `-r
2143 0 -w 1' to show that both file descriptors are ready for the
2144 requested operations.
2145 The option `-A assoc' indicates that the associative array assoc
2147 should be set to indicate the file descriptor(s) which are
2148 ready. This option overrides the option -a, nor will reply be
2149 modified. The keys of assoc are the file descriptors, and the
2150 corresponding values are any of the characters `rwe' to indicate
2151 the condition.
2152 The command returns 0 if some file descriptors are ready for
2154 reading. If the operation timed out, or a timeout of 0 was
2155 given and no file descriptors were ready, or there was an error,
2156 it returns status 1 and the array will not be set (nor modified
2157 in any way). If there was an error in the select operation the
2158 appropriate error message is printed.
2159
2161 The zsh/zutil module only adds some builtins:
2162 zstyle [ -L ]
2164 zstyle [ -e | - | -- ] pattern style strings ...
2165 zstyle -d [ pattern [ styles ... ] ]
2166 zstyle -g name [ pattern [ style ] ]
2167 zstyle -abs context style name [ sep ]
2168 zstyle -Tt context style [ strings ...]
2169 zstyle -m context style pattern
2170 This builtin command is used to define and lookup styles.
2171 Styles are pairs of names and values, where the values consist
2172 of any number of strings. They are stored together with pat‐
2173 terns and lookup is done by giving a string, called the `con‐
2174 text', which is compared to the patterns. The definition stored
2175 for the first matching pattern will be returned.
2176 For ordering of comparisons, patterns are searched from most
2178 specific to least specific, and patterns that are equally spe‐
2179 cific keep the order in which they were defined. A pattern is
2180 considered to be more specific than another if it contains more
2181 components (substrings separated by colons) or if the patterns
2182 for the components are more specific, where simple strings are
2183 considered to be more specific than patterns and complex pat‐
2184 terns are considered to be more specific than the pattern `*'.
2185 The first form (without arguments) lists the definitions in the
2187 order zstyle will test them. If the -L option is given, listing
2188 is done in the form of calls to zstyle. Forms with arguments:
2189 zstyle [ - | -- | -e ] pattern style strings ...
2191 Defines the given style for the pattern with the strings
2192 as the value. If the -e option is given, the strings
2193 will be concatenated (separated by spaces) and the
2194 resulting string will be evaluated (in the same way as it
2195 is done by the eval builtin command) when the style is
2196 looked up. In this case the parameter `reply' must be
2197 assigned to set the strings returned after the evalua‐
2198 tion. Before evaluating the value, reply is unset, and
2199 if it is still unset after the evaluation, the style is
2200 treated as if it were not set.
2201 zstyle -d [ pattern [ styles ... ] ]
2203 Delete style definitions. Without arguments all defini‐
2204 tions are deleted, with a pattern all definitions for
2205 that pattern are deleted and if any styles are given,
2206 then only those styles are deleted for the pattern.
2207 zstyle -g name [ pattern [ style ] ]
2209 Retrieve a style definition. The name is used as the name
2210 of an array in which the results are stored. Without any
2211 further arguments, all patterns defined are returned.
2212 With a pattern the styles defined for that pattern are
2213 returned and with both a pattern and a style, the value
2214 strings of that combination is returned.
2215 The other forms can be used to look up or test patterns.
2217 zstyle -s context style name [ sep ]
2219 The parameter name is set to the value of the style
2220 interpreted as a string. If the value contains several
2221 strings they are concatenated with spaces (or with the
2222 sep string if that is given) between them.
2223 zstyle -b context style name
2225 The value is stored in name as a boolean, i.e. as the
2226 string `yes' if the value has only one string and that
2227 string is equal to one of `yes', `true', `on', or `1'. If
2228 the value is any other string or has more than one
2229 string, the parameter is set to `no'.
2230 zstyle -a context style name
2232 The value is stored in name as an array. If name is
2233 declared as an associative array, the first, third, etc.
2234 strings are used as the keys and the other strings are
2235 used as the values.
2236 zstyle -t context style [ strings ...]
2238 zstyle -T context style [ strings ...]
2239 Test the value of a style, i.e. the -t option only
2240 returns a status (sets $?). Without any strings the
2241 return status is zero if the style is defined for at
2242 least one matching pattern, has only one string in its
2243 value, and that is equal to one of `true', `yes', `on' or
2244 `1'. If any strings are given the status is zero if and
2245 only if at least one of the strings is equal to at least
2246 one of the strings in the value. If the style is not
2247 defined, the status is 2.
2248 The -T option tests the values of the style like -t, but
2250 it returns zero (rather than 2) if the style is not
2251 defined for any matching pattern.
2252 zstyle -m context style pattern
2254 Match a value. Returns status zero if the pattern matches
2255 at least one of the strings in the value.
2256 zformat -f param format specs ...
2258 zformat -a array sep specs ...
2259 This builtin provides two different forms of formatting. The
2260 first form is selected with the -f option. In this case the for‐
2261 mat string will be modified by replacing sequences starting with
2262 a percent sign in it with strings from the specs. Each spec
2263 should be of the form `char:string' which will cause every
2264 appearance of the sequence `%char' in format to be replaced by
2265 the string. The `%' sequence may also contain optional minimum
2266 and maximum field width specifications between the `%' and the
2267 `char' in the form `%min.maxc', i.e. the minimum field width is
2268 given first and if the maximum field width is used, it has to be
2269 preceded by a dot. Specifying a minimum field width makes the
2270 result be padded with spaces to the right if the string is
2271 shorter than the requested width. Padding to the left can be
2272 achieved by giving a negative minimum field width. If a maximum
2273 field width is specified, the string will be truncated after
2274 that many characters. After all `%' sequences for the given
2275 specs have been processed, the resulting string is stored in the
2276 parameter param.
2277 The %-escapes also understand ternary expressions in the form
2279 used by prompts. The % is followed by a `(' and then an ordi‐
2280 nary format specifier character as described above. There may
2281 be a set of digits either before or after the `('; these specify
2282 a test number, which defaults to zero. Negative numbers are
2283 also allowed. An arbitrary delimiter character follows the for‐
2284 mat specifier, which is followed by a piece of `true' text, the
2285 delimiter character again, a piece of `false' text, and a clos‐
2286 ing parenthesis. The complete expression (without the digits)
2287 thus looks like `%(X.text1.text2)', except that the `.' charac‐
2288 ter is arbitrary. The value given for the format specifier in
2289 the char:string expressions is evaluated as a mathematical
2290 expression, and compared with the test number. If they are the
2291 same, text1 is output, else text2 is output. A parenthesis may
2292 be escaped in text2 as %). Either of text1 or text2 may contain
2293 nested %-escapes.
2294 For example:
2296 zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3
2298 outputs "The answer is 'yes'." to REPLY since the value for the
2300 format specifier c is 3, agreeing with the digit argument to the
2301 ternary expression.
2302 The second form, using the -a option, can be used for aligning
2304 strings. Here, the specs are of the form `left:right' where
2305 `left' and `right' are arbitrary strings. These strings are
2306 modified by replacing the colons by the sep string and padding
2307 the left strings with spaces to the right so that the sep
2308 strings in the result (and hence the right strings after them)
2309 are all aligned if the strings are printed below each other.
2310 All strings without a colon are left unchanged and all strings
2311 with an empty right string have the trailing colon removed. In
2312 both cases the lengths of the strings are not used to determine
2313 how the other strings are to be aligned. The resulting strings
2314 are stored in the array.
2315 zregexparse
2317 This implements some internals of the _regex_arguments function.
2318 zparseopts [ -D ] [ -K ] [ -E ] [ -a array ] [ -A assoc ] specs
2320 This builtin simplifies the parsing of options in positional
2321 parameters, i.e. the set of arguments given by $*. Each spec
2322 describes one option and must be of the form `opt[=array]'. If
2323 an option described by opt is found in the positional parameters
2324 it is copied into the array specified with the -a option; if the
2325 optional `=array' is given, it is instead copied into that
2326 array.
2327 Note that it is an error to give any spec without an `=array'
2329 unless one of the -a or -A options is used.
2330 Unless the -E option is given, parsing stops at the first string
2332 that isn't described by one of the specs. Even with -E, parsing
2333 always stops at a positional parameter equal to `-' or `--'.
2334 The opt description must be one of the following. Any of the
2336 special characters can appear in the option name provided it is
2337 preceded by a backslash.
2338 name
2340 name+ The name is the name of the option without the leading
2341 `-'. To specify a GNU-style long option, one of the
2342 usual two leading `-' must be included in name; for exam‐
2343 ple, a `--file' option is represented by a name of
2344 `-file'.
2345 If a `+' appears after name, the option is appended to
2347 array each time it is found in the positional parameters;
2348 without the `+' only the last occurrence of the option is
2349 preserved.
2350 If one of these forms is used, the option takes no argu‐
2352 ment, so parsing stops if the next positional parameter
2353 does not also begin with `-' (unless the -E option is
2354 used).
2355 name:
2357 name:-
2358 name:: If one or two colons are given, the option takes an argu‐
2359 ment; with one colon, the argument is mandatory and with
2360 two colons it is optional. The argument is appended to
2361 the array after the option itself.
2362 An optional argument is put into the same array element
2364 as the option name (note that this makes empty strings as
2365 arguments indistinguishable). A mandatory argument is
2366 added as a separate element unless the `:-' form is used,
2367 in which case the argument is put into the same element.
2368 A `+' as described above may appear between the name and
2370 the first colon.
2371 The options of zparseopts itself are:
2373 -a array
2375 As described above, this names the default array in which to
2376 store the recognised options.
2377 -A assoc
2379 If this is given, the options and their values are also put into
2380 an associative array with the option names as keys and the argu‐
2381 ments (if any) as the values.
2382 -D If this option is given, all options found are removed from the
2384 positional parameters of the calling shell or shell function, up
2385 to but not including any not described by the specs. This is
2386 similar to using the shift builtin.
2387 -K With this option, the arrays specified with the -a and -A
2389 options and with the `=array' forms are kept unchanged when none
2390 of the specs for them is used. This allows assignment of
2391 default values to them before calling zparseopts.
2392 -E This changes the parsing rules to not stop at the first string
2394 that isn't described by one of the specs. It can be used to
2395 test for or (if used together with -D) extract options and their
2396 arguments, ignoring all other options and arguments that may be
2397 in the positional parameters.
2398 For example,
2400 set -- -a -bx -c y -cz baz -cend
2402 zparseopts a=foo b:=bar c+:=bar
2403 will have the effect of
2405 foo=(-a)
2407 bar=(-b x -c y -c z)
2408 The arguments from `baz' on will not be used.
2410 As an example for the -E option, consider:
2412 set -- -a x -b y -c z arg1 arg2
2414 zparseopts -E -D b:=bar
2415 will have the effect of
2417 bar=(-b y)
2419 set -- -a x -c z arg1 arg2
2420 I.e., the option -b and its arguments are taken from the positional
2422 parameters and put into the array bar.
2423zsh 4.2.6 November 28, 2005 ZSHMODULES(1)