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