This is zsh.info, produced by makeinfo version 4.5 from ./zsh.texi.

INFO-DIR-SECTION Utilities
START-INFO-DIR-ENTRY
* ZSH: (zsh).                     The Z Shell Manual.
END-INFO-DIR-ENTRY


File: zsh.info,  Node: The zsh/computil Module,  Next: The zsh/datetime Module,  Prev: The zsh/complist Module,  Up: Zsh Modules

The zsh/computil Module
=======================

The zsh/computil module adds several builtin commands that are used by
some of the completion functions in the completion system based on shell
functions (see *Note Completion System:: ).  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 compdescribe 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
     different 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 complex recursive
     filename generation (globbing).  It does three things.  With the
     -p and -P options it builds the glob patterns to use, including
     the 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 internals 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 consecutive 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 mechanism.

compvalues
     Like comparguments, but for the _values function.



File: zsh.info,  Node: The zsh/datetime Module,  Next: The zsh/deltochar Module,  Prev: The zsh/computil Module,  Up: Zsh Modules

The zsh/datetime Module
=======================

The zsh/datetime module makes available one builtin command:

strftime [ -s SCALAR ] FORMAT EPOCHTIME
     Output the date denoted by EPOCHTIME in the FORMAT specified.

     If -s SCALAR is given, assign the date to SCALAR instead of
     printing it.


The zsh/datetime module makes available one parameter:

EPOCHSECONDS
     An integer value representing the number of seconds since the
     epoch.



File: zsh.info,  Node: The zsh/deltochar Module,  Next: The zsh/example Module,  Prev: The zsh/datetime Module,  Up: Zsh Modules

The zsh/deltochar Module
========================

The zsh/deltochar module makes available two ZLE functions:

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 backwards.

zap-to-char
     This behaves like delete-to-char, except that the final occurrence
     of the character itself is not deleted.



File: zsh.info,  Node: The zsh/example Module,  Next: The zsh/files Module,  Prev: The zsh/deltochar Module,  Up: Zsh Modules

The zsh/example Module
======================

The zsh/example module makes available one builtin command:

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.


File: zsh.info,  Node: The zsh/files Module,  Next: The zsh/mapfile Module,  Prev: The zsh/example Module,  Up: Zsh Modules

The zsh/files Module
====================

The zsh/files module makes some standard commands available as builtins:

chgrp [ -Rs ] GROUP FILENAME ...
     Changes group of files specified.  This is equivalent 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 separator 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 precedence, 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 of the directory itself.

     The -s option is a zsh extension to chown functionality.  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
     directories.  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, without 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 permissions for the
     created directories, otherwise mode 777 modified by the current
     umask (see man page 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 DIRectory that has the same last pathname component.

     By default, the user will be queried before replacing 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
     replacing 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 man page unlink(2)), the same method used for files.
     Typically only the super-user can actually succeed in unlinking
     directories in this way.  -d takes precedence over -r.

     By default, the user will be queried before removing 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 man page rmdir(2)).

     The -s option is a zsh extension to rm functionality.  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.

rmdir DIR ...
     Removes empty directories specified.

sync
     Calls the system call of the same name (see man page sync(2)),
     which flushes dirty buffers to disk.  It might return before the
     I/O has actually been completed.



File: zsh.info,  Node: The zsh/mapfile Module,  Next: The zsh/mathfunc Module,  Prev: The zsh/files Module,  Up: Zsh Modules

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 efficiency 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, unreadable, or
unwritable files, as the parameter mechanism is too low in the shell
execution hierarchy to make this convenient.

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.


File: zsh.info,  Node: The zsh/mathfunc Module,  Next: The zsh/parameter Module,  Prev: The zsh/mapfile Module,  Up: Zsh Modules

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 argument: 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 function
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 man page 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
expressions.

The following functions take two floating point arguments: copysign,
fmod, hypot, nextafter.

The following take an integer first argument and a floating 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 floating point number or an
integer.  The functions float 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 function rand48 is available if your system's mathematical library
has the function erand48(3).  It returns a pseudo-random floating point
number between 0 and 1.  It takes a single string optional argument.

If the argument is not present, the random number seed is initialised by
three calls to the rand(3) function -- this produces the same random
numbers as the next three values of $RANDOM.

If the argument is present, it gives the name of a scalar parameter
where the current random number seed will be stored.  On the first
call, the value must contain at least twelve hexadecimal digits (the
remainder of the string is ignored), or the seed will be initialised in
the same manner as for a call to rand48 with no argument.  Subsequent
calls to rand48(PARAM) will then maintain the seed in the parameter
PARAM as a string of twelve hexadecimal digits, with no base signifier.
The random number sequences for different parameters are completely
independent, and are also independent from that used by calls to rand48
with no argument.

For example, consider

     print $(( rand48(seed) ))
     print $(( rand48() ))
     print $(( rand48(seed) ))

Assuming $seed does not exist, it will be initialised by the first
call.  In the second call, the default seed is initialised; note,
however, that because of the properties of rand() there is a
correlation between the seeds used for the two initialisations, so for
more secure uses, you should generate your own 12-byte seed.  The third
call returns to the same sequence of random numbers used in the first
call, unaffected by the intervening rand48().


File: zsh.info,  Node: The zsh/parameter Module,  Next: The zsh/pcre Module,  Prev: The zsh/mathfunc Module,  Up: Zsh Modules

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 setting or unsetting the
     option, respectively. Unsetting 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
     command hash table.

functions
     This associative array maps names of enabled functions 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.

dis_builtins
     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 currently enabled to
     their expansions.

dis_aliases
     Like aliases but for disabled regular aliases.

galiases
     Like aliases, but for global aliases.

dis_galiases
     Like galiases but for disabled global aliases.

saliases
     Like raliases, but for suffix aliases.

dis_saliases
     Like saliases but for disabled suffix 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
     *Note Parameter Expansion:: .  Setting or unsetting keys in this
     array is not possible.

modules
     An associative array giving information about modules. 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 possible.

dirstack
     A normal array holding the elements of the directory 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 history.

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 pathnames of their
     home directories.

funcstack
     This array contains the names of the functions currently being
     executed. The first element is the name of the function using the
     parameter.



File: zsh.info,  Node: The zsh/pcre Module,  Next: The zsh/sched Module,  Prev: The zsh/parameter Module,  Up: Zsh Modules

The zsh/pcre Module
===================

The zsh/pcre module makes some commands available as builtins:

pcre_compile [ -aimx ] PCRE
     Compiles a perl-compatible regular expression.

     Option -a will force the pattern to be anchored.  Option -i will
     compile a case-insensitive pattern.  Option -m will compile a
     multi-line pattern; that is, ^ and $ will match newlines within
     the pattern.  Option -x will compile an extended pattern, wherein
     whitespace and # comments are ignored.

pcre_study
     Studies the previously-compiled PCRE which may result in faster
     matching.

pcre_match [ -a ARR ] STRING
     Returns successfully if string matches the previously-compiled
     PCRE.

     If the expression captures substrings within parentheses,
     pcre_match will set the array $MATCH to those substrings, unless
     the -a option is given, in which case it will set the array ARR.



File: zsh.info,  Node: The zsh/sched Module,  Next: The zsh/net/socket Module,  Prev: The zsh/pcre Module,  Up: Zsh Modules

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 absolute or relative time.  With
     no arguments, prints the list of scheduled commands.  With the
     argument `-ITEM', removes the given item from the list.



File: zsh.info,  Node: The zsh/net/socket Module,  Next: The zsh/stat Module,  Prev: The zsh/sched Module,  Up: Zsh Modules

The zsh/net/socket Module
=========================

The zsh/net/socket module makes available one builtin command:

zsocket [ -altv ] [ -d FD ] [ ARGS ]
     zsocket is implemented as a builtin to allow full use of shell
     command line editing, file I/O, and job control mechanisms.

Outbound Connections
--------------------

    zsocket [ -v ] [ -d FD ] FILENAME
          Open a new Unix domain connection to FILENAME.  The shell
          parameter REPLY will be set to the file descriptor associated
          with that connection.  Currently, only stream connections are
          supported.

          If -d is specified, its argument will be taken as the target
          file descriptor for the connection.

          In order to elicit more verbose output, use -v.


Inbound Connections
-------------------

    zsocket -l [ -v ] [ -d FD ] FILENAME
          zsocket -l will open a socket listening on FILENAME.  The
          shell parameter REPLY will be set to the file descriptor
          associated with that listener.

          If -d is specified, its argument will be taken as the target
          file descriptor for the connection.

          In order to elicit more verbose output, use -v.

    zsocket -a [ -tv ] [ -d TARGETFD ] LISTENFD
          zsocket -a will accept an incoming connection to the socket
          associated with LISTENFD.  The shell parameter REPLY will be
          set to the file descriptor associated with the inbound
          connection.

          If -d is specified, its argument will be taken as the target
          file descriptor for the connection.

          If -t is specified, zsocket will return if no incoming
          connection is pending.  Otherwise it will wait for one.

          In order to elicit more verbose output, use -v.




File: zsh.info,  Node: The zsh/stat Module,  Next: The zsh/system Module,  Prev: The zsh/net/socket Module,  Up: Zsh Modules

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 ... ]
     The command acts as a front end to the stat system call (see man
     page 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 provided.  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 file linked to, otherwise it is
          empty.  Note 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 shortened to any unique set of leading
     characters.  Otherwise, all elements will be shown for all files.

     Options:

    -A ARRAY
          Instead of displaying the results on standard 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 man page 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 man page 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 returned.
          This option is required to make the link element useful.

    -n
          Always show the names of files.  Usually these are only shown
          when output is to standard 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 consumption 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) alongside string data
          (the -s format); the string data appears in parentheses after
          the raw data.

    -s
          Print mode, uid, gid and the three time elements 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.




File: zsh.info,  Node: The zsh/system Module,  Next: The zsh/net/tcp Module,  Prev: The zsh/stat Module,  Up: Zsh Modules

The zsh/system Module
=====================

The zsh/system module makes available three builtin commands and a
parameter.

Builtins
========

syserror [ -e ERRVAR ] [ -p PREFIX ] [ ERRNO | ERRNAME ]
     This command prints out the error message associated with ERRNO, a
     system error number, followed by a newline to standard error.

     Instead of the error number, a name ERRNAME, for example ENOENT,
     may be used.  The set of names is the same as the contents of the
     array errnos, see below.

     If the string PREFIX is given, it is printed in front of the error
     message, with no intervening space.

     If ERRVAR is supplied, the entire message, without a newline, is
     assigned to the parameter names ERRVAR and nothing is output.

     A return value of 0 indicates the message was successfully printed
     (although it may not be useful if the error number was out of the
     system's range), a return value of 1 indicates an error in the
     parameters, and a return value of 2 indicates the error name was
     not recognised (no message is printed for this).

sysread [ -c COUNTVAR ] [ -i INFD ] [ -o OUTFD ]
[ -s BUFSIZE ] [ -t TIMEOUT ] [ PARAM ]
     Perform a single system read from file descriptor INFD, or zero if
     that is not given.  The result of the read is stored in PARAM or
     REPLY if that is not given.  If COUNTVAR is given, the number of
     bytes read is assigned to the parameter named by COUNTVAR.

     The maximum number of bytes read is BUFSIZE or 8192 if that is not
     given, however the command returns as soon as any number of bytes
     was successfully read.

     If TIMEOUT is given, it specifies a timeout in seconds, which may
     be zero to poll the file descriptor.  This is handled by the poll
     system call if available, otherwise the select system call if
     available.

     If OUTFD is given, an attempt is made to write all the bytes just
     read to the file descriptor OUTFD.  If this fails, because of a
     system error other than EINTR or because of an internal zsh error
     during an interrupt, the bytes read but not written are stored in
     the parameter named by PARAM if supplied (no default is used in
     this case), and the number of bytes read but not written is stored
     in the parameter named by COUNTVAR if that is supplied.  If it was
     successful, COUNTVAR contains the full number of bytes transferred,
     as usual, and PARAM is not set.

     The error EINTR (interrupted system call) is handled internally so
     that shell interrupts are transparent to the caller.  Any other
     error causes a return.

     The possible return values are
    0
          At least one byte of data was successfully read and, if
          appropriate, written.

    1
          There was an error in the parameters to the command.  This is
          the only error for which a message is printed to standard
          error.

    2
          There was an error on the read, or on polling the input file
          descriptor for a timeout.  The parameter ERRNO gives the
          error.

    3
          Data were successfully read, but there was an error writing
          them to OUTFD.  The parameter ERRNO gives the error.

    4
          The attempt to read timed out.  Note this does not set ERRNO
          as this is not a system error.

    5
          No system error occurred, but zero bytes were read.  This
          usually indicates end of file.  The parameters are set
          according to the usual rules; no write to OUTFD is attempted.


syswrite [ -c COUNTVAR ] [ -o OUTFD ] DATA
     The data (a single string of bytes) are written to the file
     descriptor OUTFD, or 1 if that is not given, using the write
     system call.  Multiple write operations may be used if the first
     does not write all the data.

     If COUNTVAR is given, the number of byte written is stored in the
     parameter named by COUNTVAR; this may not be the full length of
     DATA if an error occurred.

     The error EINTR (interrupted system call) is handled internally by
     retrying; otherwise an error causes the command to return.  For
     example, if the file descriptor is set to non-blocking output, an
     error EAGAIN (on some systems, EWOULDBLOCK) may result in the
     command returning early.

     The return status may be 0 for success, 1 for an error in the
     parameters to the command, or 2 for an error on the write; no
     error message is printed in the last case, but the parameter ERRNO
     will reflect the error that occurred.


Parameters
==========

errnos
     A readonly array of the names of errors defined on the system.
     These are typically macros defined in C by including the system
     header file errno.h.  The index of each name (assuming the option
     KSH_ARRAYS is unset) corresponds to the error number.  Error
     numbers NUM before the last known error which have no name are
     given the name ENUM in the array.

     Note that aliases for errors are not handled; only the canonical
     name is used.



File: zsh.info,  Node: The zsh/net/tcp Module,  Next: The zsh/termcap Module,  Prev: The zsh/system Module,  Up: Zsh Modules

The zsh/net/tcp Module
======================

The zsh/net/tcp module makes available one builtin command:

ztcp [ -acflLtv ] [ -d FD ] [ ARGS ]
     ztcp is implemented as a builtin to allow full use of shell
     command line editing, file I/O, and job control mechanisms.

     If ztcp is run with no options, it will output the contents of its
     session table.

     If it is run with only the option -L, it will output the contents
     of the session table in a format suitable for automatic parsing.
     The option is ignored if given with a command to open or close a
     session.  The output consists of a set of lines, one per session,
     each containing the following elements separated by spaces:

    File descriptor
          The file descriptor in use for the connection.  For normal
          inbound (I) and outbound (O) connections this may be read and
          written by the usual shell mechanisms.  However, it should
          only be close with `ztcp -c'.

    Connection type
          A letter indicating how the session was created:

         Z
               A session created with the zftp command.

         L
               A connection opened for listening with `ztcp -l'.

         I
               An inbound connection accepted with `ztcp -a'.

         O
               An outbound connection created with `ztcp HOST ...'.


    The local host
          This is usually set to an all-zero IP address as the address
          of the localhost is irrelevant.

    The local port
          This is likely to be zero unless the connection is for
          listening.

    The remote host
          This is the fully qualified domain name of the peer, if
          available, else an IP address.  It is an all-zero IP address
          for a session opened for listening.

    The remote port
          This is zero for a connection opened for listening.



Outbound Connections
--------------------

ztcp [ -v ] [ -d FD ] HOST [ PORT ]
     Open a new TCP connection to HOST.  If the PORT is omitted, it
     will default to port 23.  The connection will be added to the
     session table and the shell parameter REPLY will be set to the
     file descriptor associated with that connection.

     If -d is specified, its argument will be taken as the target file
     descriptor for the connection.

     In order to elicit more verbose output, use -v.


Inbound Connections
-------------------

ztcp -l [ -v ] [ -d FD ] PORT
     ztcp -l will open a socket listening on TCP PORT.  The socket will
     be added to the session table and the shell parameter REPLY will
     be set to the file descriptor associated with that listener.

     If -d is specified, its argument will be taken as the target file
     descriptor for the connection.

     In order to elicit more verbose output, use -v.

ztcp -a [ -tv ] [ -d TARGETFD ] LISTENFD
     ztcp -a will accept an incoming connection to the port associated
     with LISTENFD.  The connection will be added to the session table
     and the shell parameter REPLY will be set to the file descriptor
     associated with the inbound connection.

     If -d is specified, its argument will be taken as the target file
     descriptor for the connection.

     If -t is specified, ztcp will return if no incoming connection is
     pending.  Otherwise it will wait for one.

     In order to elicit more verbose output, use -v.


Closing Connections
-------------------

ztcp -cf [ -v ] [ FD ]
ztcp -c [ -v ] [ FD ]
     ztcp -c will close the socket associated with FD.  The socket will
     be removed from the session table.  If FD is not specified, ztcp
     will close everything in the session table.

     Normally, sockets registered by zftp (see *Note The zsh/zftp
     Module:: ) cannot be closed this way.  In order to force such a
     socket closed, use -f.

     In order to elicit more verbose output, use -v.


Example
-------

Here is how to create a TCP connection between two instances of zsh.  We
need to pick an unassigned port; here we use the randomly chosen 5123.

On host1,
     zmodload zsh/net/tcp
     ztcp -l 5123
     listenfd=$REPLY
     ztcp -a $listenfd
     fd=$REPLY
   The second from last command blocks until there is an incoming
connection.

Now create a connection from host2 (which may, of course, be the same
machine):
     zmodload zsh/net/tcp
     ztcp host1 5123
     fd=$REPLY

Now on each host, $fd contains a file descriptor for talking to the
other.  For example, on host1:
     print This is a message >&$fd
   and on host2:
     read -r line <&$fd; print -r - $line
   prints `This is a message'.

To tidy up, on host1:
     ztcp -c $listenfd
     ztcp -c $fd
   and on host2
     ztcp -c $fd


File: zsh.info,  Node: The zsh/termcap Module,  Next: The zsh/terminfo Module,  Prev: The zsh/net/tcp Module,  Up: Zsh Modules

The zsh/termcap Module
======================

The zsh/termcap module makes available one builtin command:

echotc CAP [ ARG ... ]
     Output the termcap value corresponding to the capability CAP, with
     optional arguments.


The zsh/termcap module makes available one parameter:

termcap
     An associative array that maps termcap capability codes to their
     values.



File: zsh.info,  Node: The zsh/terminfo Module,  Next: The zsh/zftp Module,  Prev: The zsh/termcap Module,  Up: Zsh Modules

The zsh/terminfo Module
=======================

The zsh/terminfo module makes available one builtin command:

echoti CAP [ ARG ]
     Output the terminfo value corresponding to the capability CAP,
     instantiated with ARG if applicable.


The zsh/terminfo module makes available one parameter:

terminfo
     An associative array that maps terminfo capability names to their
     values.


