.. zsh-module-meta::
   :name: zsh/system
   :summary: A builtin interface to various low-level system features.

The ``zsh/system`` module makes available various builtin commands and
parameters.

Builtins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index:: single: syserror; Function

``syserror`` [ ``-e`` :var:`errvar` ] [ ``-p`` :var:`prefix` ] [ :var:`errno` | :var:`errname` ]
    
    This command prints out the error message associated with :var:`errno`, a
    system error number, followed by a newline to standard error.
    
    Instead of the error number, a name :var:`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 :var:`prefix` is given, it is printed in front of the error
    message, with no intervening space.
    
    If :var:`errvar` is supplied, the entire message, without a newline, is
    assigned to the parameter names :var:`errvar` and nothing is output.
    
    A return status 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 status of 1 indicates an error in the
    parameters, and a return status of 2 indicates the error name was
    not recognised (no message is printed for this).
    

.. index:: single: sysopen; Function

``sysopen`` [ ``-arw`` ] [ ``-m`` :var:`permissions` ] [ ``-o`` :var:`options` ]

        ``-u`` :var:`fd` :var:`file`
    
    This command opens a file. The ``-r``, ``-w`` and ``-a`` flags indicate
    whether the file should be opened for reading, writing and appending,
    respectively. The ``-m`` option allows the initial permissions to use when
    creating a file to be specified in octal form.  The file descriptor is
    specified with ``-u``. Either an explicit file descriptor in the range 0 to 9 can
    be specified or a variable name can be given to which the file descriptor
    number will be assigned.
    
    The ``-o`` option allows various system specific options to be
    specified as a comma-separated list. The following is a list of possible
    options. Note that, depending on the system, some may not be available.
    
    ``cloexec``
        
        mark file to be closed when other programs are executed (else
        the file descriptor remains open in subshells and forked external
        executables)
        
    
    ``create``
    
    ``creat``
        
        create file if it does not exist
        
    
    ``excl``
        
        create file, error if it already exists
        
    
    ``noatime``
        
        suppress updating of the file atime
        
    
    ``nofollow``
        
        fail if :var:`file` is a symbolic link
        
    
    ``nonblock``
        
        the file is opened in nonblocking mode
        
    
    ``sync``
        
        request that writes wait until data has been physically written
        
    
    ``truncate``
    
    ``trunc``
        
        truncate file to size 0
        
    
    
    
    A return status of 0 indicates the descriptor was successfully opened,
    otherwise an error message is printed, and 1 is returned for an error
    in the parameters to the command, or 2 is returned for a system error.
    The parameter ``ERRNO`` is nonzero for system errors.
    
    To close the file, use one of the following:
    
    
    .. parsed-literal::
       :class: example

        ``exec {``:var:`fd`\ ``}<&-``
        ``exec {``:var:`fd`\ ``}>&-``
    
    

.. index:: single: sysread; Function

``sysread`` [ ``-c`` :var:`countvar` ] [ ``-i`` :var:`infd` ] [ ``-o`` :var:`outfd` ]

        [ ``-s`` :var:`bufsize` ] [ ``-t`` :var:`timeout` ] [ :var:`param` ]
    
    Perform a single system read from file descriptor :var:`infd`, or zero if
    that is not given.  The result of the read is stored in :var:`param` or
    ``REPLY`` if that is not given.  If :var:`countvar` is given, the number
    of bytes read is assigned to the parameter named by :var:`countvar`.
    
    The maximum number of bytes read is :var:`bufsize` or 8192 if that is not
    given, however the command returns as soon as any number of bytes was
    successfully read.
    
    If :var:`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 :var:`outfd` is given, an attempt is made to write all the bytes just
    read to the file descriptor :var:`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 :var:`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 :var:`countvar` if that is supplied.  If it was
    successful, :var:`countvar` contains the full number of bytes transferred,
    as usual, and :var:`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 statuses 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`` identifies the error.
        
    
    3
        
        Data were successfully read, but there was an error writing them
        to :var:`outfd`.  The parameter ``ERRNO`` identifies 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 :var:`outfd` is attempted.
        
    
    
    

``sysseek`` [ ``-u`` :var:`fd` ] [ ``-w`` ``start|end|current`` ] :var:`offset`
    
    The current file position at which future reads and writes will take place is
    adjusted to the specified byte offset. The :var:`offset` is evaluated as a math
    expression. The ``-u`` option allows the file descriptor to be specified. By
    default the offset is specified relative to the start or the file but, with the
    ``-w`` option, it is possible to specify that the offset should be relative to
    the current position or the end of the file.
    
    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 seek; no error message is
    printed in the last case, but the parameter ``ERRNO`` reflects
    the error that occurred.
    

``syswrite`` [ ``-c`` :var:`countvar` ] [ ``-o`` :var:`outfd` ] :var:`data`
    
    The data (a single string of bytes) are written to the file descriptor
    :var:`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 :var:`countvar` is given, the number of byte written is stored in the
    parameter named by :var:`countvar`; this may not be the full length of
    :var:`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`` reflects
    the error that occurred.
    

``zsystem flock`` [ ``-t`` :var:`timeout` ] [ ``-i`` :var:`interval` ] [ ``-f`` :var:`var` ] [``-er``] :var:`file`

``zsystem flock -u`` :var:`fd_expr`
    
    The builtin ``zsystem``'s subcommand ``flock`` performs advisory file
    locking (via the :manpage:`fcntl(2)` system call) over the entire contents
    of the given file.  This form of locking requires the processes
    accessing the file to cooperate; its most obvious use is between two
    instances of the shell itself.
    
    In the first form the named :var:`file`, which must already exist, is
    locked by opening a file descriptor to the file and applying a lock to
    the file descriptor.  The lock terminates when the shell process that
    created the lock exits; it is therefore often convenient to create file
    locks within subshells, since the lock is automatically released when
    the subshell exits.  Note that use of the ``print`` builtin with the
    ``-u`` option will, as a side effect, release the lock, as will redirection
    to the file in the shell holding the lock.  To work around this use a
    subshell, e.g. ``(print message) >>`` :var:`file`.  Status 0 is
    returned if the lock succeeds, else status 1.
    
    In the second form the file descriptor given by the arithmetic
    expression :var:`fd_expr` is closed, releasing a lock.  The file descriptor
    can be queried by using the ``-f`` :var:`var` form during the lock;
    on a successful lock, the shell variable :var:`var` is set to the file
    descriptor used for locking.  The lock will be released if the
    file descriptor is closed by any other means, for example using
    ``exec {``:var:`var`\ ``}>&-``; however, the form described here performs
    a safety check that the file descriptor is in use for file locking.
    
    By default the shell waits indefinitely for the lock to succeed.
    The option ``-t`` :var:`timeout` specifies a timeout for the lock in
    seconds; fractional seconds are allowed.  During this period, the
    shell will attempt to lock the file every :var:`interval` seconds
    if the ``-i`` :var:`interval` option is given, otherwise once a second.
    (This :var:`interval` is shortened before the last attempt if needed,
    so that the shell waits only until the :var:`timeout` and not longer.)
    If the attempt times out, status 2 is returned.
    
    (Note: :var:`timeout` is limited to 2^30-1 seconds (about 34 years), and
    :var:`interval` to 0.999 * LONG_MAX microseconds (only about 35 minutes
    on 32-bit systems).)
    
    If the option ``-e`` is given, the file descriptor for the lock is
    preserved when the shell uses ``exec`` to start a new process;
    otherwise it is closed at that point and the lock released.
    
    If the option ``-r`` is given, the lock is only for reading, otherwise
    it is for reading and writing.  The file descriptor is opened
    accordingly.
    

``zsystem supports`` :var:`subcommand`
    
    The builtin ``zsystem``'s subcommand ``supports`` tests whether a
    given subcommand is supported.  It returns status 0 if so, else
    status 1.  It operates silently unless there was a syntax error
    (i.e. the wrong number of arguments), in which case status 255
    is returned.  Status 1 can indicate one of two things:  :var:`subcommand`
    is known but not supported by the current operating system, or
    :var:`subcommand` is not known (possibly because this is an older
    version of the shell before it was implemented).
    

Math Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``systell(:var:`fd`)``
    
    The systell math function returns the current file position for the file
    descriptor passed as an argument.
    

Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index:: single: errnos; Variable

``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 :var:`num`
    before the last known error which have no name are given the name
    ``E``:var:`num` in the array.
    
    Note that aliases for errors are not handled; only the canonical name is
    used.
    

.. index:: single: sysparams; Variable

``sysparams``
    
    A readonly associative array.  The keys are:
    
    
    ``pid``
        
        .. index:: single: pid, sysparams; Variable
        
        
        Returns the process ID of the current process, even in subshells.  Compare
        ``$$``, which returns the process ID of the main shell process.
        
    
    ``ppid``
        
        .. index:: single: ppid, sysparams; Variable
        
        
        Returns the current process ID of the parent of the current process, even
        in subshells.  Compare ``$PPID``, which returns the process ID of the
        initial parent of the main shell process.
        
    
    ``procsubstpid``
        
        Returns the process ID of the last process started for process
        substitution, i.e. the ``<(``:var:`...`\ ``)`` and
        ``>(``:var:`...`\ ``)`` expansions.
        
    
    
    

