The zsh/system
module makes available various builtin commands and
parameters.
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 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).
sysopen
[ -arw
] [ -m
permissions ] [ -o
options ]
-u
fd fileThis 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 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
To close the file, use one of the following:
exec {
fd}<&-
exec {
fd}>&-
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 statuses are
At least one byte of data was successfully read and, if appropriate, written.
There was an error in the parameters to the command. This is the only error for which a message is printed to standard error.
There was an error on the read, or on polling the input file descriptor
for a timeout. The parameter ERRNO
gives the error.
Data were successfully read, but there was an error writing them
to outfd. The parameter ERRNO
gives the error.
The attempt to read timed out. Note this does not set ERRNO
as this
is not a system error.
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.
sysseek
[ -u
fd ] [ -w
start
|end
|current
] offsetThe current file position at which future reads and writes will take place is
adjusted to the specified byte offset. The 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.
syswrite
[ -c
countvar ] [ -o
outfd ] dataThe 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.
zsystem flock
[ -t
timeout ] [ -i
interval ] [ -f
var ] [-er
] filezsystem flock -u
fd_exprThe builtin zsystem
’s subcommand flock
performs advisory file
locking (via the 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 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) >>
file’. Status 0 is
returned if the lock succeeds, else status 1.
In the second form the file descriptor given by the arithmetic
expression fd_expr is closed, releasing a lock. The file descriptor
can be queried by using the ‘-f
var’ form during the lock;
on a successful lock, the shell variable 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}>&-
’; 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
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 interval seconds
if the -i
interval option is given, otherwise once a second.
(This interval is shortened before the last attempt if needed,
so that the shell waits only until the timeout and not longer.)
If the attempt times out, status 2 is returned.
(Note: timeout is limited to 2^30-1 seconds (about 34 years), and 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
subcommandThe 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: subcommand
is known but not supported by the current operating system, or
subcommand is not known (possibly because this is an older
version of the shell before it was implemented).
systell(fd)
The systell math function returns the current file position for the file descriptor passed as an argument.
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
E
num in the array.
Note that aliases for errors are not handled; only the canonical name is used.
sysparams
A readonly associative array. The keys are:
pid
¶Returns the process ID of the current process, even in subshells. Compare
$$
, which returns the process ID of the main shell process.
ppid
¶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 <(
...)
and
>(
...)
expansions.