zshmodules - zsh loadable modules
DESCRIPTION
Some optional parts of zsh are in modules, separate from
the core of the shell. Each of these modules may be
linked in to the shell at build time, or can be dynami
cally linked while the shell is running if the installa
tion supports this feature. The modules that are bundled
with the zsh distribution are:
zsh/cap
Builtins for manipulating POSIX.1e (POSIX.6) capa
bility (privilege) sets.
zsh/clone
A builtin that can clone a running shell onto
another terminal.
zsh/compctl
The compctl builtin for controlling completion.
zsh/complete
The basic completion code.
zsh/complist
Completion listing extensions.
zsh/computil
A module with utility builtins needed for the shell
function based completion system.
zsh/deltochar
A ZLE function duplicating EMACS' zap-to-char.
zsh/example
An example of how to write a module.
zsh/files
Some basic file manipulation commands as builtins.
zsh/mapfile
Access to external files via a special associative
array.
zsh/mathfunc
Standard scientific functions for use in mathemati
cal evaluations.
zsh/parameter
Access to internal hash tables via special associa
tive arrays.
A builtin that provides a timed execution facility
within the shell.
zsh/stat
A builtin command interface to the stat system
call.
zsh/termcap
Interface to the termcap database.
zsh/terminfo
Interface to the terminfo database.
zsh/zftp
A builtin FTP client.
zsh/zle
The Zsh Line Editor, including the bindkey and
vared builtins.
zsh/zleparameter
Access to internals of the Zsh Line Editor via
parameters.
zsh/zprof
A module allowing profiling for shell functions.
zsh/zpty
A builtin for starting a command in a pseudo-termi
nal.
zsh/zutil
Some utility builtins, e.g. the one for supporting
configuration via styles.
THE ZSH/CAP MODULE
The zsh/cap module is used for manipulating POSIX.1e
(POSIX.6) capability sets. If the operating system does
not support this interface, the builtins defined by this
module will do nothing. The builtins in this module are:
cap [ capabilities ]
Change the shell's process capability sets to the
specified capabilities, otherwise display the
shell's current capabilities.
getcap filename ...
This is a built-in implementation of the POSIX
standard utility. It displays the capability sets
on each specified filename.
setcap capabilities filename ...
This is a built-in implementation of the POSIX
each specified filename to the specified capabili
ties.
THE ZSH/CLONE MODULE
The zsh/clone module makes available one builtin command:
clone tty
Creates a forked instance of the current shell,
attached to the specified tty. In the new shell,
the PID, PPID and TTY special parameters are
changed appropriately. $! is set to zero in the
new shell, and to the new shell's PID in the origi
nal shell.
The return value of the builtin is zero in both
shells if successful, and non-zero on error.
THE ZSH/COMPCTL MODULE
The zsh/compctl module makes available two builtin com
mands. compctl, is the old, deprecated way to control com
pletions for ZLE. See zshcompctl(1). The other builtin
command, compcall can be used in user-defined completion
widgets, see zshcompwid(1).
THE ZSH/COMPLETE MODULE
The zsh/complete module makes available several builtin
commands which can be used in user-defined completion wid
gets, see zshcompwid(1).
THE ZSH/COMPLIST MODULE
The zsh/complist module offers three extensions to comple
tion listings: the ability to highlight matches in such a
list, the ability to scroll through long lists and a dif
ferent style of menu completion.
Colored completion listings
Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS
is set and the zsh/complist module is loaded or linked
into the shell, completion lists will be colored. Note,
however, that complist will not automatically be loaded if
it is not linked in: on systems with dynamic loading,
`zmodload zsh/complist' is required.
The parameters ZLS_COLORS and ZLS_COLOURS describe how
matches are highlighted. To turn on highlighting an empty
value suffices, in which case all the default values given
below will be used. The format of the value of these
parameters is the same as used by the GNU version of the
ls command: a colon-separated list of specifications of
the form `name=value'. The name may be one of the follow
ing strings, most of which specify file types for which
the value will be used. The strings and their default
no 0 for normal text (i.e. when displaying something
other than a matched file)
fi 0 for regular files
di 32 for directories
ln 36 for symbolic links
pi 31 for named pipes (FIFOs)
so 33 for sockets
bd 44;37
for block devices
cd 44;37
for character devices
ex 35 for executable files
mi none
for a non-existent file (default is the value
defined for fi)
lc \e[ for the left code (see below)
rc m for the right code
tc 0 for the character indicating the file type printed
after filenames if the LIST_TYPES option is set
sp 0 for the spaces printed after matches to align the
next column
ec none
for the end code
Apart from these strings, the name may also be an asterisk
(`*') followed by any string. The value given for such a
string will be used for all files whose name ends with the
string. The name may also be an equals sign (`=') fol
lowed by a pattern. The value given for this pattern will
be used for all matches (not just filenames) whose display
string are matched by the pattern. Definitions for both
of these take precedence over the values defined for file
types and the form with the leading asterisk takes prece
dence over the form with the leading equal sign.
The last form also allows different parts of the displayed
strings to be colored differently. For this, the pattern
has to use the `(#b)' globbing flag and pairs of
to be colored differently. In this case the value may
consist of more than one color code separated by equal
signs. The first code will be used for all parts for
which no explicit code is specified and the following
codes will be used for the parts matched by the sub-pat
terns in parentheses. For example, the specification
`=(#b)(?)*(?)=0=3=7' will be used for all matches which
are at least two characters long and will use the code `3'
for the first character, `7' for the last character and
`0' for the rest.
All three forms of name may be preceded by a pattern in
parentheses. If this is given, the value will be used
only for matches in groups whose names are matched by the
pattern given in the parentheses. For example,
`(g*)m*=43' highlights all matches beginning with `m' in
groups whose names begin with `g' using the color code
`43'. In case of the `lc', `rc', and `ec' codes, the
group pattern is ignored.
Note also that all patterns are tried in the order in
which they appear in the parameter value until the first
one matches which is then used.
When printing a match, the code prints the value of lc,
the value for the file-type or the last matching specifi
cation with a `*', the value of rc, the string to display
for the match itself, and then the value of ec if that is
defined or the values of lc, no, and rc if ec is not
defined.
The default values are ISO 6429 (ANSI) compliant and can
be used on vt100 compatible terminals such as xterms. On
monochrome terminals the default values will have no visi
ble effect. The colors function from the contribution can
be used to get associative arrays containing the codes for
ANSI terminals (see the section `Other Functions' in zsh
contrib(1)). For example, after loading colors, one could
use `$colors[red]' to get the code for foreground color
red and `$colors[bg-green]' for the code for background
color green.
If the completion system invoked by compinit is used,
these parameters should not be set directly because the
system controls them itself. Instead, the list-colors
style should be used (see the section `Completion System
Configuration' in zshcompsys(1)).
Scrolling in completion listings
To enable scrolling through a completion list, the LIST
PROMPT parameter must be set. Its value will be used as
the prompt; if it is the empty string, a default prompt
`%x'. It supports the escapes `%B', `%b', `%S', `%s',
`%U', `%u' and `%{...%}' used also in shell prompts as
well as three pairs of additional sequences: a `%l' or
`%L' is replaced by the number of the last line shown and
the total number of lines in the form `number/total'; a
`%m' or `%M' is replaced with the number of the last match
shown and the total number of matches; and `%p' or `%P' is
replaced with `Top', `Bottom' or the position of the first
line shown in percent of the total number of lines,
respectively. In each of these cases the form with the
uppercase letter will be replaced with a string of fixed
width, padded to the right with spaces, while the lower
case form will not be padded.
If the parameter LISTPROMPT is set, the completion code
will not ask if the list should be shown. Instead it
immediately starts displaying the list, stopping after the
first screenful, showing the prompt at the bottom, waiting
for a keypress after temporarily switching to the
listscroll keymap. Some of the zle functions have a spe
cial meaning while scrolling lists:
send-break
stops listing discarding the key pressed
accept-line, down-history, down-line-or-history
down-line-or-search, vi-down-line-or-history
scrolls forward one line
complete-word, menu-complete, expand-or-complete
expand-or-complete-prefix, menu-complete-or-expand
scrolls forward one screenful
Every other character stops listing and immediately pro
cesses the key as usual. Any key that is not bound in the
listscroll keymap or that is bound to undefined-key is
looked up in the keymap currently selected.
As for the ZLS_COLORS and ZLS_COLOURS parameters, LIST
PROMPT should not be set directly when using the shell
function based completion system. Instead, the
list-prompt style should be used.
Menu selection
The zsh/complist module also offers an alternative style
of selecting matches from a list, called menu selection,
which can be used if the shell is set up to return to the
last prompt after showing a completion list (see the
ALWAYS_LAST_PROMPT option in zshoptions(1)). It can be
invoked directly by the widget menu-select defined by the
module. Alternatively, the parameter MENUSELECT can be
set to an integer, which gives the minimum number of
automatically turned on. This second method requires that
menu completion be started, either directly from a widget
such as menu-complete, or due to one of the options
MENU_COMPLETE or AUTO_MENU being set. If MENUSELECT is
set, but is 0, 1 or empty, menu selection will always be
started during an ambiguous menu completion.
When using the completion system based on shell functions,
the MENUSELECT parameter should not be used (like the
ZLS_COLORS and ZLS_COLOURS parameters described above).
Instead, the menu style should be used with the select=...
keyword.
After menu selection is started, the matches will be
listed. If there are more matches than fit on the screen,
only the first screenful is shown. The matches to insert
into the command line can be selected from this list. In
the list one match is highlighted using the value for ma
from the ZLS_COLORS or ZLS_COLOURS parameter. The default
value for this is `7' which forces the selected match to
be highlighted using standout mode on a vt100-compatible
terminal. If neither ZLS_COLORS nor ZLS_COLOURS is set,
the same terminal control sequence as for the `%S' escape
in prompts is used.
If there are more matches than fit on the screen and the
parameter MENUPROMPT is set, its value will be shown below
the matches. It supports the same escape sequences as
LISTPROMPT, but the number of the match or line shown will
be that of the one where the mark is placed. If its value
is the empty string, a default prompt will be used.
The MENUSCROLL parameter can be used to specify how the
list is scrolled. If the parameter is unset, this is done
line by line, if it is set to `0' (zero), the list will
scroll half the number of lines of the screen. If the
value is positive, it gives the number of lines to scroll
and if it is negative, the list will be scrolled the num
ber of lines of the screen minus the (absolute) value.
As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parame
ters, neither MENUPROMPT nor MENUSCROLL should be set
directly when using the shell function based completion
system. Instead, the select-prompt and select-scroll
styles should be used.
The completion code sometimes decides not to show all of
the matches in the list. These hidden matches are either
matches for which the completion function which added them
explicitly requested that they not appear in the list
(using the -n option of the compadd builtin command) or
they are matches which duplicate a string already in the
list (because they differ only in things like prefixes or
menu selection, however, even these matches are shown so
that it is possible to select them. To highlight such
matches the hi and du capabilities in the ZLS_COLORS and
ZLS_COLOURS parameters are supported for hidden matches of
the first and second kind, respectively.
Selecting matches is done by moving the mark around using
the zle movement functions. When not all matches can be
shown on the screen at the same time, the list will scroll
up and down when crossing the top or bottom line. The
following zle functions have special meaning during menu
selection:
accept-line
accepts the current match and leaves menu selection
send-break
leaves menu selection and restores the previous
contents of the command line
redisplay, clear-screen
execute their normal function without leaving menu
selection
accept-and-hold, accept-and-menu-complete
accept the currently inserted match and continue
selection allowing to select the next match to
insert into the line
accept-and-infer-next-history
accepts the current match and then tries completion
with menu selection again; in the case of files
this allows one to select a directory and immedi
ately attempt to complete files in it; if there
are no matches, a message is shown and one can use
undo to go back to completion on the previous
level, every other key leaves menu selection
(including the other zle functions which are other
wise special during menu selection)
undo removes matches inserted during the menu selection
by one of the three functions before
down-history, down-line-or-history
vi-down-line-or-history, down-line-or-search
moves the mark one line down
up-history, up-line-or-history
vi-up-line-or-history, up-line-or-search
moves the mark one line up
forward-char, vi-forward-char
moves the mark one column right
moves the mark one column left
forward-word, vi-forward-word
vi-forward-word-end, emacs-forward-word
moves the mark one screenful down
backward-word, vi-backward-word, emacs-backward-word
moves the mark one screenful up
vi-forward-blank-word, vi-forward-blank-word-end
moves the mark to the first line of the next group
of matches
vi-backward-blank-word
moves the mark to the last line of the previous
group of matches
beginning-of-history
moves the mark to the first line
end-of-history
moves the mark to the last line
beginning-of-buffer-or-history, beginning-of-line
beginning-of-line-hist, vi-beginning-of-line
moves the mark to the leftmost column
end-of-buffer-or-history, end-of-line
end-of-line-hist, vi-end-of-line
moves the mark to the rightmost column
complete-word, menu-complete, expand-or-complete
expand-or-complete-prefix, menu-expand-or-complete
moves the mark to the next match
reverse-menu-complete
moves the mark to the previous match
All movement functions wrap around at the edges; any other
zle function not listed leaves menu selection and executes
that function. It is possible to make widgets in the
above list do the same by using the form of the widget
with a `.' in front. For example, the widget
`.accept-line' has the effect of leaving menu selection
and accepting the entire command line.
During this selection the widget uses the keymap menuse
lect. Any key that is not defined in this keymap or that
is bound to undefined-key is looked up in the keymap cur
rently selected. This is used to ensure that the most
important keys used during selection (namely the cursor
keys, return, and TAB) have sensible defaults. However,
keys in the menuselect keymap can be modified directly
example, to make the return key leave menu selection with
out accepting the match currently selected one could call
bindkey -M menuselect '^M' send-break
after loading the zsh/complist module.
THE ZSH/COMPUTIL MODULE
The zsh/computil module adds several builtin commands that
are used by some of the completion functions in the com
pletion system based on shell functions (see zshcompsys(1)
). Except for compquote these builtin commands are very
specialised and thus not very interesting when writing
your own completion functions. In summary, these builtin
commands are:
comparguments
This is used by the _arguments function to do the
argument and command line parsing. Like compde
scribe it has an option -i to do the parsing and
initialize some internal state and various options
to access the state information to decide what
should be completed.
compdescribe
This is used by the _describe function to build the
displays for the matches and to get the strings to
add as matches with their options. On the first
call one of the options -i or -I should be supplied
as the first argument. In the first case, display
strings without the descriptions will be generated,
in the second case, the string used to separate the
matches from their descriptions must be given as
the second argument and the descriptions (if any)
will be shown. All other arguments are like the
definition arguments to _describe itself.
Once compdescribe has been called with either the
-i or the -I option, it can be repeatedly called
with the -g option and the names of five arrays as
its arguments. This will step through the differ
ent sets of matches and store the options in the
first array, the strings with descriptions in the
second, the matches for these in the third, the
strings without descriptions in the fourth, and the
matches for them in the fifth array. These are
then directly given to compadd to register the
matches with the completion code.
compfiles
Used by the _path_files function to optimize com
plex recursive filename generation (globbing). It
does three things. With the -p and -P options it
paths already handled and trying to optimize the
patterns with respect to the prefix and suffix from
the line and the match specification currently
used. The -i option does the directory tests for
the ignore-parents style and the -r option tests if
a component for some of the matches are equal to
the string on the line and removes all other
matches if that is true.
compgroups
Used by the _tags function to implement the inter
nals of the group-order style. This only takes its
arguments as names of completion groups and creates
the groups for it (all six types: sorted and
unsorted, both without removing duplicates, with
removing all duplicates and with removing consecu
tive duplicates).
compquote [ -p ] names ...
There may be reasons to write completion functions
that have to add the matches using the -Q option to
compadd and perform quoting themselves. Instead of
interpreting the first character of the all_quotes
key of the compstate special association and using
the q flag for parameter expansions, one can use
this builtin command. The arguments are the names
of scalar or array parameters and the values of
these parameters are quoted as needed for the
innermost quoting level. If the -p option is
given, quoting is done as if there is some prefix
before the values of the parameters, so that a
leading equal sign will not be quoted.
The return value is non-zero in case of an error
and zero otherwise.
comptags
comptry
These implement the internals of the tags mecha
nism.
compvalues
Like comparguments, but for the _values function.
THE ZSH/DELTOCHAR MODULE
The zsh/deltochar module makes available two ZLE func
tions:
delete-to-char
Read a character from the keyboard, and delete from
the cursor position up to and including the next
(or, with repeat count n, the nth) instance of that
character. Negative repeat counts mean delete
zap-to-char
This behaves like delete-to-char, except that the
final occurrence of the character itself is not
deleted.
THE ZSH/EXAMPLE MODULE
The zsh/example module makes available one builtin com
mand:
example [ -flags ] [ args ... ]
Displays the flags and arguments it is invoked
with.
The purpose of the module is to serve as an example of how
to write a module.
THE ZSH/FILES MODULE
The zsh/files module makes some standard commands avail
able as builtins:
chgrp [ -Rs ] group filename ...
Changes group of files specified. This is equiva
lent to chown with a user-spec argument of
`:group'.
chown [ -Rs ] user-spec filename ...
Changes ownership and group of files specified.
The user-spec can be in four forms:
user change owner to user; do not change group
user:: change owner to user; do not change group
user: change owner to user; change group to user's
primary group
user:group
change owner to user; change group to group
:group do not change owner; change group to group
In each case, the `:' may instead be a `.'. The
rule is that if there is a `:' then the separator
is `:', otherwise if there is a `.' then the sepa
rator is `.', otherwise there is no separator.
Each of user and group may be either a username (or
group name, as appropriate) or a decimal user ID
(group ID). Interpretation as a name takes prece
dence, if there is an all-numeric username (or
group name).
The -R option causes chown to recursively descend
into directories, changing the ownership of all
files in the directory after changing the ownership
The -s option is a zsh extension to chown function
ality. It enables paranoid behaviour, intended to
avoid security problems involving a chown being
tricked into affecting files other than the ones
intended. It will refuse to follow symbolic links,
so that (for example) ``chown luser
/tmp/foo/passwd'' can't accidentally chown
/etc/passwd if /tmp/foo happens to be a link to
/etc. It will also check where it is after leaving
directories, so that a recursive chown of a deep
directory tree can't end up recursively chowning
/usr as a result of directories being moved up the
tree.
ln [ -dfis ] filename dest
ln [ -dfis ] filename ... dir
Creates hard (or, with -s, symbolic) links. In the
first form, the specified destination is created,
as a link to the specified filename. In the second
form, each of the filenames is taken in turn, and
linked to a pathname in the specified directory
that has the same last pathname component.
Normally, ln will not attempt to create hard links
to directories. This check can be overridden using
the -d option. Typically only the super-user can
actually succeed in creating hard links to directo
ries. This does not apply to symbolic links in any
case.
By default, existing files cannot be replaced by
links. The -i option causes the user to be queried
about replacing existing files. The -f option
causes existing files to be silently deleted, with
out querying. -f takes precedence.
mkdir [ -p ] [ -m mode ] dir ...
Creates directories. With the -p option,
non-existing parent directories are first created
if necessary, and there will be no complaint if the
directory already exists. The -m option can be
used to specify (in octal) a set of file permis
sions for the created directories, otherwise mode
777 modified by the current umask (see umask(2)) is
used.
mv [ -fi ] filename dest
mv [ -fi ] filename ... dir
Moves files. In the first form, the specified
filename is moved to the specified destination. In
the second form, each of the filenames is taken in
turn, and moved to a pathname in the specified
nent.
By default, the user will be queried before replac
ing any file that the user cannot write to, but
writable files will be silently removed. The -i
option causes the user to be queried about replac
ing any existing files. The -f option causes any
existing files to be silently deleted, without
querying. -f takes precedence.
Note that this mv will not move files across
devices. Historical versions of mv, when actual
renaming is impossible, fall back on copying and
removing files; if this behaviour is desired, use
cp and rm manually. This may change in a future
version.
rm [ -dfirs ] filename ...
Removes files and directories specified.
Normally, rm will not remove directories (except
with the -r option). The -d option causes rm to
try removing directories with unlink (see
unlink(2)), the same method used for files. Typi
cally only the super-user can actually succeed in
unlinking directories in this way. -d takes prece
dence over -r.
By default, the user will be queried before remov
ing any file that the user cannot write to, but
writable files will be silently removed. The -i
option causes the user to be queried about removing
any files. The -f option causes files to be
silently deleted, without querying, and suppresses
all error indications. -f takes precedence.
The -r option causes rm to recursively descend into
directories, deleting all files in the directory
before removing the directory with the rmdir system
call (see rmdir(2)).
The -s option is a zsh extension to rm functional
ity. It enables paranoid behaviour, intended to
avoid common security problems involving a root-run
rm being tricked into removing files other than the
ones intended. It will refuse to follow symbolic
links, so that (for example) ``rm /tmp/foo/passwd''
can't accidentally remove /etc/passwd if /tmp/foo
happens to be a link to /etc. It will also check
where it is after leaving directories, so that a
recursive removal of a deep directory tree can't
end up recursively removing /usr as a result of
directories being moved up the tree.
Removes empty directories specified.
sync Calls the system call of the same name (see
sync(2)), which flushes dirty buffers to disk. It
might return before the I/O has actually been com
pleted.
THE ZSH/MAPFILE MODULE
The zsh/mapfile module provides one special associative
array parameter of the same name.
mapfile
This associative array takes as keys the names of
files; the resulting value is the content of the
file. The value is treated identically to any
other text coming from a parameter. The value may
also be assigned to, in which case the file in
question is written (whether or not it originally
existed); or an element may be unset, which will
delete the file in question. For example, `vared
mapfile[myfile]' works as expected, editing the
file `myfile'.
When the array is accessed as a whole, the keys are
the names of files in the current directory, and
the values are empty (to save a huge overhead in
memory). Thus ${(k)mapfile} has the same affect as
the glob operator *(D), since files beginning with
a dot are not special. Care must be taken with
expressions such as rm ${(k)mapfile}, which will
delete every file in the current directory without
the usual `rm *' test.
The parameter mapfile may be made read-only; in
that case, files referenced may not be written or
deleted.
Limitations
Although reading and writing of the file in question is
efficiently handled, zsh's internal memory management may
be arbitrarily baroque. Thus it should not automatically
be assumed that use of mapfile represents a gain in effi
ciency over use of other mechanisms. Note in particular
that the whole contents of the file will always reside
physically in memory when accessed (possibly multiple
times, due to standard parameter substitution operations).
In particular, this means handling of sufficiently long
files (greater than the machine's swap space, or than the
range of the pointer type) will be incorrect.
No errors are printed or flagged for non-existent, unread
able, or unwritable files, as the parameter mechanism is
venient.
It is unfortunate that the mechanism for loading modules
does not yet allow the user to specify the name of the
shell parameter to be given the special behaviour.
THE ZSH/MATHFUNC MODULE
The zsh/mathfunc module provides standard mathematical
functions for use when evaluating mathematical formulae.
The syntax agrees with normal C and FORTRAN conventions,
for example,
(( f = sin(0.3) ))
assigns the sine of 0.3 to the parameter f.
Most functions take floating point arguments and return a
floating point value. However, any necessary conversions
from or to integer type will be performed automatically by
the shell. Apart from atan with a second argument and the
abs, int and float functions, all functions behave as
noted in the manual page for the corresponding C function,
except that any arguments out of range for the function in
question will be detected by the shell and an error
reported.
The following functions take a single floating point argu
ment: acos, acosh, asin, asinh, atan, atanh, cbrt, ceil,
cos, cosh, erf, erfc, exp, expm1, fabs, floor, gamma, j0,
j1, lgamma, log, log10, log1p, logb, sin, sinh, sqrt, tan,
tanh, y0, y1. The atan function can optionally take a
second argument, in which case it behaves like the C func
tion atan2. The ilogb function takes a single floating
point argument, but returns an integer.
The function signgam takes no arguments, and returns an
integer, which is the C variable of the same name, as
described in gamma(3). Note that it is therefore only
useful immediately after a call to gamma or lgamma. Note
also that `signgam()' and `signgam' are distinct expres
sions.
The following functions take two floating point arguments:
copysign, fmod, hypot, nextafter.
The following take an integer first argument and a float
ing point second argument: jn, yn.
The following take a floating point first argument and an
integer second argument: ldexp, scalb.
The function abs does not convert the type of its single
argument; it returns the absolute value of either a
and int convert their arguments into a floating point or
integer value (by truncation) respectively.
Note that the C pow function is available in ordinary math
evaluation as the `**' operator and is not provided here.
THE ZSH/PARAMETER MODULE
The zsh/parameter module gives access to some of the
internal hash tables used by the shell by defining some
special parameters.
options
The keys for this associative array are the names
of the options that can be set and unset using the
setopt and unsetopt builtins. The value of each key
is either the string on if the option is currently
set, or the string off if the option is unset.
Setting a key to one of these strings is like set
ting or unsetting the option, respectively. Unset
ting a key in this array is like setting it to the
value off.
commands
This array gives access to the command hash table.
The keys are the names of external commands, the
values are the pathnames of the files that would be
executed when the command would be invoked. Setting
a key in this array defines a new entry in this
table in the same way as with the hash builtin.
Unsetting a key as in `unset "commands[foo]"'
removes the entry for the given key from the com
mand hash table.
functions
This associative array maps names of enabled func
tions to their definitions. Setting a key in it is
like defining a function with the name given by the
key and the body given by the value. Unsetting a
key removes the definition for the function named
by the key.
dis_functions
Like functions but for disabled functions.
builtins
This associative array gives information about the
builtin commands currently enabled. The keys are
the names of the builtin commands and the values
are either `undefined' for builtin commands that
will automatically be loaded from a module if
invoked or `defined' for builtin commands that are
already loaded.
Like builtins but for disabled builtin commands.
reswords
This array contains the enabled reserved words.
dis_reswords
Like reswords but for disabled reserved words.
aliases
This maps the names of the regular aliases cur
rently enabled to their expansions.
dis_aliases
Like raliases but for disabled regular aliases.
galiases
Like raliases, but for global aliases.
dis_galiases
Like galiases but for disabled global aliases.
parameters
The keys in this associative array are the names of
the parameters currently defined. The values are
strings describing the type of the parameter, in
the same format used by the t parameter flag, see
zshexpn(1) . Setting or unsetting keys in this
array is not possible.
modules
An associative array giving information about mod
ules. The keys are the names of the modules loaded,
registered to be autoloaded, or aliased. The value
says which state the named module is in and is one
of the strings `loaded', `autoloaded', or
`alias:name', where name is the name the module is
aliased to.
Setting or unsetting keys in this array is not pos
sible.
dirstack
A normal array holding the elements of the direc
tory stack. Note that the output of the dirs
builtin command includes one more directory, the
current working directory.
history
This associative array maps history event numbers
to the full history lines.
historywords
A special array containing the words stored in the
jobdirs
This associative array maps job numbers to the
directories from which the job was started (which
may not be the current directory of the job).
jobtexts
This associative array maps job numbers to the
texts of the command lines that were used to start
the jobs.
jobstates
This associative array gives information about the
states of the jobs currently known. The keys are
the job numbers and the values are strings of the
form `job-state:mark:pid=state...'. The job-state
gives the state the whole job is currently in, one
of `running', `suspended', or `done'. The mark is
`+' for the current job, `-' for the previous job
and empty otherwise. This is followed by one
`pid=state' for every process in the job. The pids
are, of course, the process IDs and the state
describes the state of that process.
nameddirs
This associative array maps the names of named
directories to the pathnames they stand for.
userdirs
This associative array maps user names to the path
names of their home directories.
funcstack
This array contains the names of the functions cur
rently being executed. The first element is the
name of the function using the parameter.
THE ZSH/SCHED MODULE
The zsh/sched module makes available one builtin command:
sched [+]hh:mm command ...
sched [ -item ]
Make an entry in the scheduled list of commands to
execute. The time may be specified in either abso
lute or relative time. With no arguments, prints
the list of scheduled commands. With the argument
`-item', removes the given item from the list.
THE ZSH/STAT MODULE
The zsh/stat module makes available one builtin command:
stat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [
-F fmt ] [ +element ] [ file ... ]
call (see stat(2)). If the stat call fails, the
appropriate system error message printed and status
1 is returned. The fields of struct stat give
information about the files provided as arguments
to the command. In addition to those available
from the stat call, an extra element `link' is pro
vided. These elements are:
device The number of the device on which the file
resides.
inode The unique number of the file on this device
(`inode' number).
mode The mode of the file; that is, the file's
type and access permissions. With the -s
option, this will be returned as a string
corresponding to the first column in the
display of the ls -l command.
nlink The number of hard links to the file.
uid The user ID of the owner of the file. With
the -s option, this is displayed as a user
name.
gid The group ID of the file. With the -s
option, this is displayed as a group name.
rdev The raw device number. This is only useful
for special devices.
size The size of the file in bytes.
atime
mtime
ctime The last access, modification and inode
change times of the file, respectively, as
the number of seconds since midnight GMT on
1st January, 1970. With the -s option,
these are printed as strings for the local
time zone; the format can be altered with
the -F option, and with the -g option the
times are in GMT.
blksize
The number of bytes in one allocation block
on the device on which the file resides.
block The number of disk blocks used by the file.
link If the file is a link and the -L option is
in effect, this contains the name of the
that if this element is selected (``stat
+link'') then the -L option is automatically
used.
A particular element may be selected by including
its name preceded by a `+' in the option list; only
one element is allowed. The element may be short
ened to any unique set of leading characters. Oth
erwise, all elements will be shown for all files.
Options:
-A array
Instead of displaying the results on stan
dard output, assign them to an array, one
struct stat element per array element for
each file in order. In this case neither
the name of the element nor the name of the
files appears in array unless the -t or -n
options were given, respectively. If -t is
given, the element name appears as a prefix
to the appropriate array element; if -n is
given, the file name appears as a separate
array element preceding all the others.
Other formatting options are respected.
-H hash
Similar to -A, but instead assign the values
to hash. The keys are the elements listed
above. If the -n option is provided then
the name of the file is included in the hash
with key name.
-f fd Use the file on file descriptor fd instead
of named files; no list of file names is
allowed in this case.
-F fmt Supplies a strftime (see strftime(3)) string
for the formatting of the time elements.
The -s option is implied.
-g Show the time elements in the GMT time zone.
The -s option is implied.
-l List the names of the type elements (to
standard output or an array as appropriate)
and return immediately; options other than
-A and arguments are ignored.
-L Perform an lstat (see lstat(2)) rather than
a stat system call. In this case, if the
file is a link, information about the link
itself rather than the target file is
the link element useful.
-n Always show the names of files. Usually
these are only shown when output is to stan
dard output and there is more than one file
in the list.
-N Never show the names of files.
-o If a raw file mode is printed, show it in
octal, which is more useful for human con
sumption than the default of decimal. A
leading zero will be printed in this case.
Note that this does not affect whether a raw
or formatted file mode is shown, which is
controlled by the -r and -s options, nor
whether a mode is shown at all.
-r Print raw data (the default format) along
side string data (the -s format); the string
data appears in parentheses after the raw
data.
-s Print mode, uid, gid and the three time ele
ments as strings instead of numbers. In
each case the format is like that of ls -l.
-t Always show the type names for the elements
of struct stat. Usually these are only
shown when output is to standard output and
no individual element has been selected.
-T Never show the type names of the struct stat
elements.
THE ZSH/TERMCAP MODULE
The zsh/termcap module makes available one builtin com
mand:
echotc cap [ arg ... ]
Output the termcap value corresponding to the capa
bility cap, with optional arguments.
The zsh/termcap module makes available one parameter:
termcap
An associative array that maps termcap capability
codes to their values.
THE ZSH/TERMINFO MODULE
The zsh/terminfo module makes available one builtin com
mand:
Output the terminfo value corresponding to the
capability cap.
The zsh/terminfo module makes available one parameter:
terminfo
An associative array that maps terminfo capability
names to their values.
THE ZSH/ZFTP MODULE
The zsh/zftp module makes available one builtin command:
zftp subcommand [ args ]
The zsh/zftp module is a client for FTP (file
transfer protocol). It is implemented as a builtin
to allow full use of shell command line editing,
file I/O, and job control mechanisms. Often, users
will access it via shell functions providing a more
powerful interface; a set is provided with the zsh
distribution and is described in zshzftpsys(1).
However, the zftp command is entirely usable in its
own right.
All commands consist of the command name zftp fol
lowed by the name of a subcommand. These are
listed below. The return status of each subcommand
is supposed to reflect the success or failure of
the remote operation. See a description of the
variable ZFTP_VERBOSE for more information on how
responses from the server may be printed.
Subcommands
open host [ user [ password [ account ] ] ]
Open a new FTP session to host, which may be the
name of a TCP/IP connected host or an IP number in
the standard dot notation. Remaining arguments are
passed to the login subcommand. Note that if no
arguments beyond host are supplied, open will not
automatically call login. If no arguments at all
are supplied, open will use the parameters set by
the params subcommand.
After a successful open, the shell variables
ZFTP_HOST, ZFTP_IP and ZFTP_SYSTEM are available;
see `Variables' below.
login [ name [ password [ account ] ] ]
user [ name [ password [ account ] ] ]
Login the user name with parameters password and
account. Any of the parameters can be omitted, and
will be read from standard input if needed (name is
always needed). If standard input is a terminal, a
error and password will not be echoed. If any of
the parameters are not used, a warning message is
printed.
After a successful login, the shell variables
ZFTP_USER, ZFTP_ACCOUNT and ZFTP_PWD are available;
see `Variables' below.
This command may be re-issued when a user is
already logged in, and the server will first be
reinitialized for a new user.
params [ host [ user [ password [ account ] ] ] ]
params -
Store the given parameters for a later open command
with no arguments. Only those given on the command
line will be remembered. If no arguments are
given, the parameters currently set are printed,
although the password will appear as a line of
stars; the return value is one if no parameters
were set, zero otherwise.
Any of the parameters may be specified as a `?',
which may need to be quoted to protect it from
shell expansion. In this case, the appropriate
parameter will be read from stdin as with the login
subcommand, including special handling of password.
If the `?' is followed by a string, that is used as
the prompt for reading the parameter instead of the
default message (any necessary punctuation and
whitespace should be included at the end of the
prompt). The first letter of the parameter (only)
may be quoted with a `\'; hence an argument
"\\$word" guarantees that the string from the shell
parameter $word will be treated literally, whether
or not it begins with a `?'.
If instead a single `-' is given, the existing
parameters, if any, are deleted. In that case,
calling open with no arguments will cause an error.
The list of parameters is not deleted after a
close, however it will be deleted if the zsh/zftp
module is unloaded.
For example,
zftp params ftp.elsewhere.xx juser '?Password for juser: '
will store the host ftp.elsewhere.xx and the user
juser and then prompt the user for the correspond
ing password with the given prompt.
that it has closed the connection (maybe due to a
timeout), return status 2; if no connection was
open anyway, return status 1; else return status 0.
The test subcommand is silent, apart from messages
printed by the $ZFTP_VERBOSE mechanism, or error
messages if the connection closes. There is no
network overhead for this test.
The test is only supported on systems with either
the select(2) or poll(2) system calls; otherwise
the message `not supported on this system' is
printed instead.
The test subcommand will automatically be called at
the start of any other subcommand for the current
session when a connection is open.
cd directory
Change the remote directory to directory. Also
alters the shell variable ZFTP_PWD.
cdup Change the remote directory to the one higher in
the directory tree. Note that cd .. will also work
correctly on non-UNIX systems.
dir [ args... ]
Give a (verbose) listing of the remote directory.
The args are passed directly to the server. The
command's behaviour is implementation dependent,
but a UNIX server will typically interpret args as
arguments to the ls command and with no arguments
return the result of `ls -l'. The directory is
listed to standard output.
ls [ args ]
Give a (short) listing of the remote directory.
With no args, produces a raw list of the files in
the directory, one per line. Otherwise, up to
vagaries of the server implementation, behaves sim
ilar to dir.
type [ type ]
Change the type for the transfer to type, or print
the current type if type is absent. The allowed
values are `A' (ASCII), `I' (Image, i.e. binary),
or `B' (a synonym for `I').
The FTP default for a transfer is ASCII. However,
if zftp finds that the remote host is a UNIX
machine with 8-bit byes, it will automatically
switch to using binary for file transfers upon
open. This can subsequently be overridden.
when a data connection is established; this command
involves no network overhead.
ascii The same as type A.
binary The same as type I.
mode [ S | B ]
Set the mode type to stream (S) or block (B).
Stream mode is the default; block mode is not
widely supported.
remote files...
local [ files... ]
Print the size and last modification time of the
remote or local files. If there is more than one
item on the list, the name of the file is printed
first. The first number is the file size, the sec
ond is the last modification time of the file in
the format CCYYMMDDhhmmSS consisting of year,
month, date, hour, minutes and seconds in GMT.
Note that this format, including the length, is
guaranteed, so that time strings can be directly
compared via the [[ builtin's < and > operators,
even if they are too long to be represented as
integers.
Not all servers support the commands for retrieving
this information. In that case, the remote command
will print nothing and return status 2, compared
with status 1 for a file not found.
The local command (but not remote) may be used with
no arguments, in which case the information comes
from examining file descriptor zero. This is the
same file as seen by a put command with no further
redirection.
get file [...]
Retrieve all files from the server, concatenating
them and sending them to standard output.
put file [...]
For each file, read a file from standard input and
send that to the remote host with the given name.
append file [...]
As put, but if the remote file already exists, data
is appended to it instead of overwriting it.
getat file point
putat file point
Versions of get, put and append which will start
the transfer at the given point in the remote file.
This is useful for appending to an incomplete local
file. However, note that this ability is not uni
versally supported by servers (and is not quite the
behaviour specified by the standard).
delete file [...]
Delete the list of files on the server.
mkdir directory
Create a new directory directory on the server.
rmdir directory
Delete the directory directory on the server.
rename old-name new-name
Rename file old-name to new-name on the server.
site args...
Send a host-specific command to the server. You
will probably only need this if instructed by the
server to use it.
quote args...
Send the raw FTP command sequence to the server.
You should be familiar with the FTP command set as
defined in RFC959 before doing this. Useful com
mands may include STAT and HELP. Note also the
mechanism for returning messages as described for
the variable ZFTP_VERBOSE below, in particular that
all messages from the control connection are sent
to standard error.
close
quit Close the current data connection. This unsets the
shell parameters ZFTP_HOST, ZFTP_IP, ZFTP_SYSTEM,
ZFTP_USER, ZFTP_ACCOUNT, ZFTP_PWD, ZFTP_TYPE and
ZFTP_MODE.
session [ sessname ]
Allows multiple FTP sessions to be used at once.
The name of the session is an arbitrary string of
characters; the default session is called
`default'. If this command is called without an
argument, it will list all the current sessions;
with an argument, it will either switch to the
existing session called sessname, or create a new
session of that name.
Each session remembers the status of the connec
tion, the set of connection-specific shell parame
ters (the same set as are unset when a connection
any user parameters specified with the params sub
command. Changing to a previous session restores
those values; changing to a new session initialises
them in the same way as if zftp had just been
loaded. The name of the current session is given
by the parameter ZFTP_SESSION.
rmsession [ sessname ]
Delete a session; if a name is not given, the cur
rent session is deleted. If the current session is
deleted, the earliest existing session becomes the
new current session, otherwise the current session
is not changed. If the session being deleted is
the only one, a new session called `default' is
created and becomes the current session; note that
this is a new session even if the session being
deleted is also called `default'. It is recommended
that sessions not be deleted while background com
mands which use zftp are still active.
Parameters
The following shell parameters are used by zftp. Cur
rently none of them are special.
ZFTP_TMOUT
Integer. The time in seconds to wait for a network
operation to complete before returning an error.
If this is not set when the module is loaded, it
will be given the default value 60. A value of
zero turns off timeouts. If a timeout occurs on
the control connection it will be closed. Use a
larger value if this occurs too frequently.
ZFTP_IP
Readonly. The IP address of the current connection
in dot notation.
ZFTP_HOST
Readonly. The hostname of the current remote
server. If the host was opened as an IP number,
ZFTP_HOST contains that instead; this saves the
overhead for a name lookup, as IP numbers are most
commonly used when a nameserver is unavailable.
ZFTP_SYSTEM
Readonly. The system type string returned by the
server in response to an FTP SYST request. The
most interesting case is a string beginning "UNIX
Type: L8", which ensures maximum compatibility with
a local UNIX host.
Readonly. The type to be used for data transfers ,
either `A' or `I'. Use the type subcommand to
change this.
ZFTP_USER
Readonly. The username currently logged in, if
any.
ZFTP_ACCOUNT
Readonly. The account name of the current user, if
any. Most servers do not require an account name.
ZFTP_PWD
Readonly. The current directory on the server.
ZFTP_CODE
Readonly. The three digit code of the last FTP
reply from the server as a string. This can still
be read after the connection is closed, and is not
changed when the current session changes.
ZFTP_REPLY
Readonly. The last line of the last reply sent by
the server. This can still be read after the con
nection is closed, and is not changed when the cur
rent session changes.
ZFTP_SESSION
Readonly. The name of the current FTP session; see
the description of the session subcommand.
ZFTP_PREFS
A string of preferences for altering aspects of
zftp's behaviour. Each preference is a single
character. The following are defined:
P Passive: attempt to make the remote server
initiate data transfers. This is slightly
more efficient than sendport mode. If the
letter S occurs later in the string, zftp
will use sendport mode if passive mode is
not available.
S Sendport: initiate transfers by the FTP
PORT command. If this occurs before any P
in the string, passive mode will never be
attempted.
D Dumb: use only the bare minimum of FTP com
mands. This prevents the variables
ZFTP_SYSTEM and ZFTP_PWD from being set, and
will mean all connections default to ASCII
type. It may prevent ZFTP_SIZE from being
send it anyway (many servers do).
If ZFTP_PREFS is not set when zftp is loaded, it
will be set to a default of `PS', i.e. use passive
mode if available, otherwise fall back to sendport
mode.
ZFTP_VERBOSE
A string of digits between 0 and 5 inclusive, spec
ifying which responses from the server should be
printed. All responses go to standard error. If
any of the numbers 1 to 5 appear in the string, raw
responses from the server with reply codes begin
ning with that digit will be printed to standard
error. The first digit of the three digit reply
code is defined by RFC959 to correspond to:
1. A positive preliminary reply.
2. A positive completion reply.
3. A positive intermediate reply.
4. A transient negative completion reply.
5. A permanent negative completion reply.
It should be noted that, for unknown reasons, the
reply `Service not available', which forces termi
nation of a connection, is classified as 421, i.e.
`transient negative', an interesting interpretation
of the word `transient'.
The code 0 is special: it indicates that all but
the last line of multiline replies read from the
server will be printed to standard error in a pro
cessed format. By convention, servers use this
mechanism for sending information for the user to
read. The appropriate reply code, if it matches
the same response, takes priority.
If ZFTP_VERBOSE is not set when zftp is loaded, it
will be set to the default value 450, i.e., mes
sages destined for the user and all errors will be
printed. A null string is valid and specifies that
no messages should be printed.
Functions
zftp_chpwd
If this function is set by the user, it is called
every time the directory changes on the server,
including when a user is logged in, or when a
will be unset; otherwise it will reflect the new
directory.
zftp_progress
If this function is set by the user, it will be
called during a get, put or append operation each
time sufficient data has been received from the
host. During a get, the data is sent to standard
output, so it is vital that this function should
write to standard error or directly to the termi
nal, not to standard output.
When it is called with a transfer in progress, the
following additional shell parameters are set:
ZFTP_FILE
The name of the remote file being trans
ferred from or to.
ZFTP_TRANSFER
A G for a get operation and a P for a put
operation.
ZFTP_SIZE
The total size of the complete file being
transferred: the same as the first value
provided by the remote and local subcommands
for a particular file. If the server cannot
supply this value for a remote file being
retrieved, it will not be set. If input is
from a pipe the value may be incorrect and
correspond simply to a full pipe buffer.
ZFTP_COUNT
The amount of data so far transferred; a
number between zero and $ZFTP_SIZE, if that
is set. This number is always available.
The function is initially called with ZFTP_TRANSFER
set appropriately and ZFTP_COUNT set to zero.
After the transfer is finished, the function will
be called one more time with ZFTP_TRANSFER set to
GF or PF, in case it wishes to tidy up. It is oth
erwise never called twice with the same value of
ZFTP_COUNT.
Sometimes the progress meter may cause disruption.
It is up to the user to decide whether the function
should be defined and to use unfunction when neces
sary.
A connection may not be opened in the left hand side of a
pipe as this occurs in a subshell and the file information
is not updated in the main shell. In the case of type or
mode changes or closing the connection in a subshell, the
information is returned but variables are not updated
until the next call to zftp. Other status changes in sub
shells will not be reflected by changes to the variables
(but should be otherwise harmless).
Deleting sessions while a zftp command is active in the
background can have unexpected effects, even if it does
not use the session being deleted. This is because all
shell subprocesses share information on the state of all
connections, and deleting a session changes the ordering
of that information.
On some operating systems, the control connection is not
valid after a fork(), so that operations in subshells, on
the left hand side of a pipeline, or in the background are
not possible, as they should be. This is presumably a bug
in the operating system.
THE ZSH/ZLE MODULE
The zsh/zle module contains the Zsh Line Editor. See zsh
zle(1).
THE ZSH/ZLEPARAMETER MODULE
The zsh/zleparameter module defines two special parameters
that can be used to access internal information of the Zsh
Line Editor (see zshzle(1)).
keymaps
This array contains the names of the keymaps cur
rently defined.
widgets
This associative array contains one entry per wid
get defined. The name of the widget is the key and
the value gives information about the widget. It is
either the string `builtin' for builtin widgets, a
string of the form `user:name' for user-defined
widgets, where name is the name of the shell func
tion implementing the widget, or it is a string of
the form `completion:type:name', for completion
widgets. In the last case type is the name of the
builtin widgets the completion widget imitates in
its behavior and name is the name of the shell
function implementing the completion widget.
THE ZSH/ZPROF MODULE
When loaded, the zsh/zprof causes shell functions to be
profiled. The profiling results can be obtained with the
zprof builtin command made available by this module.
the module.
zprof [ -c ]
Without the -c option, zprof lists profiling
results to standard output. The format is compara
ble to that of commands like gprof.
At the top there is a summary listing all functions
that were called at least once. This summary is
sorted in decreasing order of the amount of time
spent in each. The lines contain the number of the
function in order, which is used in other parts of
the list in suffixes of the form `[num]'.RE, then
the number of calls made to the function. The next
three columns list the time in milliseconds spent
in the function and its descendents, the average
time in milliseconds spent in the function and its
descendents per call and the percentage of time
spent in all shell functions used in this function
and its descendents. The following three columns
give the same information, but counting only the
time spent in the function itself. The final col
umn shows the name of the function.
After the summary, detailed information about every
function that was invoked is listed, sorted in
decreasing order of the amount of time spent in
each function and its descendents. Each of these
entries consists of descriptions for the functions
that called the function described, the function
itself, and the functions that were called from it.
The description for the function itself has the
same format as in the summary (and shows the same
information). The other lines don't show the num
ber of the function at the beginning and have their
function named indented to make it easier to dis
tinguish the line showing the function described in
the section from the surrounding lines.
The information shown in this case is almost the
same as in the summary, but only refers to the call
hierarchy being displayed. For example, for a
calling function the column showing the total run
ning time lists the time spent in the described
function and its descendents only for the times
when it was called from that particular calling
function. Likewise, for a called function, this
columns lists the total time spent in the called
function and its descendents only for the times
when it was called from the function described.
Also in this case, the column showing the number of
calls to a function also shows a slash and then the
function.
As long as the zsh/zprof module is loaded, profil
ing will be done and multiple invocations of the
zprof builtin command will show the times and num
bers of calls since the module was loaded. With
the -c option, the zprof builtin command will reset
its internal counters and will not show the list
ing. )
THE ZSH/ZPTY MODULE
The zsh/zpty module offers one builtin:
zpty [ -e ] [ -b ] name [ arg ... ]
The arguments following name are concatenated with
spaces between, then executed as a command, as if
passed to the eval builtin. The command runs under
a newly assigned pseudo-terminal; this is useful
for running commands non-interactively which expect
an interactive environment. The name is not part
of the command, but is used to refer to this com
mand in later calls to zpty.
With the -e option, the pseudo-terminal is set up
so that input characters are echoed.
With the -b option, input to and output from the
pseudo-terminal are made non-blocking.
zpty -d [ names ... ]
The second form, with the -d option, is used to
delete commands previously started, by supplying a
list of their names. If no names are given, all
commands are deleted. Deleting a command causes
the HUP signal to be sent to the corresponding pro
cess.
zpty -w [ -n ] name [ strings ... ]
The -w option can be used to send the to command
name the given strings as input (separated by
spaces). If the -n option is not given, a newline
is added at the end.
If no strings are provided, the standard input is
copied to the pseudo-terminal; this may stop before
copying the full input if the pseudo-terminal is
non-blocking.
Note that the command under the pseudo-terminal
sees this input as if it were typed, so beware when
sending special tty driver characters such as
word-erase, line-kill, and end-of-file.
The -r option can be used to read the output of the
command name. With only a name argument, the out
put read is copied to the standard output. Unless
the pseudo-terminal is non-blocking, copying con
tinues until the command under the pseudo-terminal
exits; when non-blocking, only as much output as is
immediately available is copied. The return value
is zero if any output is copied.
When also given a param argument, at most one line
is read and stored in the parameter named param.
Less than a full line may be read if the
pseudo-terminal is non-blocking. The return value
is zero if at least one character is stored in
param.
If a pattern is given as well, output is read until
the whole string read matches the pattern, even in
the non-blocking case. The return value is zero if
the string read matches the pattern, or if the com
mand has exited but at least one character could
still be read. As of this writing, a maximum of
one megabyte of output can be consumed this way; if
a full megabyte is read without matching the pat
tern, the return value is non-zero.
In all cases, the return value is non-zero if noth
ing could be read, and is 2 if this is because the
command has finished.
If the -r option is combined with the -t option,
zpty tests whether output is available before try
ing to read. If no output is available, zpty imme
diately returns the value 1.
zpty -t name
The -t option without the -r option can be used to
test whether the command name is still running. It
returns a zero value if the command is running and
a non-zero value otherwise.
zpty [ -L ]
The last form, without any arguments, is used to
list the commands currently defined. If the -L
option is given, this is done in the form of calls
to the zpty builtin.
THE ZSH/ZUTIL MODULE
The zsh/zutil module only adds some builtins:
zstyle [ -L ]
zstyle [ -e | - | -- ] pattern style strings ...
zstyle -g name [ pattern [ style ] ]
zstyle -abs context style name [ sep ]
zstyle -Tt context style [ strings ...]
zstyle -m context style pattern
This builtin command is used to define and lookup
styles. Styles are pairs of names and values,
where the values consist of any number of strings.
They are stored together with patterns and lookup
is done by giving a string, called the `context',
which is compared to the patterns. The definition
stored for the first matching pattern will be
returned.
For ordering of comparisons, patterns are searched
from most specific to least specific, and patterns
that are equally specific keep the order in which
they were defined. A pattern is considered to be
more specific than another if it contains more com
ponents (substrings separated by colons) or if the
patterns for the components are more specific,
where simple strings are considered to be more spe
cific than patterns and complex patterns are con
sidered to be more specific than the pattern `*'.
The first form (without arguments) lists the defi
nitions in the order zstyle will test them. If the
-L option is given, listing is done in the form of
calls to zstyle. Forms with arguments:
zstyle [ - | -- | -e ] pattern style strings ...
Defines the given style for the pattern with
the strings as the value. If the -e option
is given, the strings will be concatenated
(separated by spaces) and the resulting
string will be evaluated (in the same way as
it is done by the eval builtin command) when
the style is looked up. In this case the
parameter `reply' must be assigned to set
the strings returned after the evaluation.
Before evaluating the value, reply is unset,
and if it is still unset after the evalua
tion, the style is treated as if it were not
set.
zstyle -d [ pattern [ styles ... ] ]
Delete style definitions. Without arguments
all definitions are deleted, with a pattern
all definitions for that pattern are deleted
and if any styles are given, then only those
styles are deleted for the pattern.
zstyle -g name [ pattern [ style ] ]
Retrieve a style definition. The name is
results are stored. Without any further
arguments, all patterns defined are
returned. With a pattern the styles defined
for that pattern are returned and with both
a pattern and a style, the value strings of
that combination is returned.
The other forms can be used to look up or test pat
terns.
zstyle -s context style name [ sep ]
The parameter name is set to the value of
the style interpreted as a string. If the
value contains several strings they are con
catenated with spaces (or with the sep
string if that is given) between them.
zstyle -b context style name
The value is stored in name as a boolean,
i.e. as the string `yes' if the value has
only one string and that string is equal to
one of `yes', `true', `on', or `1'. If the
value is any other string or has more than
one string, the parameter is set to `no'.
zstyle -a context style name
The value is stored in name as an array. If
name is declared as an associative array,
the first, third, etc. strings are used as
the keys and the other strings are used as
the values.
zstyle -t context style [ strings ...]
zstyle -T context style [ strings ...]
Test the value of a style, i.e. the -t
option only returns a status (sets $?).
Without any strings the return status is
zero if the style is defined for at least
one matching pattern, has only one string in
its value, and that is equal to one of
`true', `yes', `on' or `1'. If any strings
are given the status is zero if and only if
at least one of the strings is equal to at
least one of the strings in the value. If
the style is not defined, the status is 2.
The -T option tests the values of the style
like -t, but it returns zero (rather than 2)
if the style is not defined for any matching
pattern.
zstyle -m context style pattern
Match a value. Returns status zero if the
in the value.
zformat -f param format specs ...
zformat -a array sep specs ...
This builtin provides two different forms of for
matting. The first form is selected with the -f
option. In this case the format string will be mod
ified by replacing sequences starting with a per
cent sign in it with strings from the specs. Each
spec should be of the form `char:string' which will
cause every appearance of the sequence `%char' in
format to be replaced by the string. The `%'
sequence may also contain optional minimum and max
imum field width specifications between the `%' and
the `char' in the form `%min.maxc', i.e. the mini
mum field width is given first and if the maximum
field width is used, it has to be preceded by a
dot. Specifying a minimum field width makes the
result be padded with spaces to the right if the
string is shorter than the requested width.
Padding to the left can be achieved by giving a
negative minimum field width. If a maximum field
width is specified, the string will be truncated
after that many characters. After all `%'
sequences for the given specs have been processed,
the resulting string is stored in the parameter
param.
The second form, using the -a option, can be used
for aligning strings. Here, the specs are of the
form `left:right' where `left' and `right' are
arbitrary strings. These strings are modified by
replacing the colons by the sep string and padding
the left strings with spaces to the right so that
the sep strings in the result (and hence the right
strings after them) are all aligned if the strings
are printed below each other. All strings without
a colon are left unchanged and all strings with an
empty right string have the trailing colon removed.
In both cases the lengths of the strings are not
used to determine how the other strings are to be
aligned. The resulting strings are stored in the
array.
zregexparse
This implements some internals of the _regex_argu
ments function.
zparseopts [ -D ] [ -K ] [ -E ] [ -a array ] [ -A assoc ]
specs
This builtin simplifies the parsing of options in
positional parameters, i.e. the set of arguments
given by $*. Each spec describes one option and
described by opt is found in the positional parame
ters it is copied into the array specified with the
-a option; if the optional `=array' is given, it is
instead copied into that array.
Note that it is an error to give any spec without
an `=array' unless one of the -a or -A options is
used.
Unless the -E option is given, parsing stops at the
first string that isn't described by one of the
specs. Even with -E, parsing always stops at a
positional parameter equal to `-' or `--'.
The opt description must be one of the following.
Any of the special characters can appear in the
option name provided it is preceded by a backslash.
name
name+ The name is the name of the option without
the leading `-'. To specify a GNU-style
long option, one of the usual two leading
`-' must be included in name; for example, a
`--file' option is represented by a name of
`-file'.
If a `+' appears after name, the option is
appended to array each time it is found in
the positional parameters; without the `+'
only the last occurrence of the option is
preserved.
If one of these forms is used, the option
takes no argument, so parsing stops if the
next positional parameter does not also
begin with `-' (unless the -E option is
used).
name:
name:-
name:: If one or two colons are given, the option
takes an argument; with one colon, the argu
ment is mandatory and with two colons it is
optional. The argument is appended to the
array after the option itself.
An optional argument is put into the same
array element as the option name (note that
this makes empty strings as arguments indis
tinguishable). A mandatory argument is
added as a separate element unless the `:-'
form is used, in which case the argument is
put into the same element.
the name and the first colon.
The options of zparseopts itself are:
-a array
As described above, this names the default array in
which to store the recognised options.
-A assoc
If this is given, the options and their values are
also put into an associative array with the option
names as keys and the arguments (if any) as the
values.
-D If this option is given, all options found are
removed from the positional parameters of the call
ing shell or shell function, up to but not includ
ing any not described by the specs. This is simi
lar to using the shift builtin.
-K With this option, the arrays specified with the -a
and -A options and with the `=array' forms are kept
unchanged when none of the specs for them is used.
This allows assignment of default values to them
before calling zparseopts.
-E This changes the parsing rules to not stop at the
first string that isn't described by one of the
specs. It can be used to test for or (if used
together with -D) extract options and their argu
ments, ignoring all other options and arguments
that may be in the positional parameters.
For example,
set -- -a -bx -c y -cz baz -cend
zparseopts a=foo b:=bar c+:=bar
will have the effect of
foo=(-a)
bar=(-b x -c y -c z)
The arguments from `baz' on will not be used.
As an example for the -E option, consider:
set -- -a x -b y -c z arg1 arg2
zparseopts -E -D b:=bar
will have the effect of
bar=(-b y)
I.e., the option -b and its arguments are taken from the
positional parameters and put into the array bar.
Man(1) output converted with
man2html