A+ Reference: The sys Context

# The sys Context

Introduction
Functions that Modify Arguments
Path Names
File Permissions Mode
Manifest Constants
Definitions of sys-Context Functions (alphabetized by A+ function name)

sys.access{f;m} access
sys.agetdents{f} Directory Entries
sys.alstat{c} Linked File Stats

Table: sys.astat and sys.alstat Results in Terms of stat System Call Result

sys.amsync{a;i} Synchronize a Mapped File
sys.aread{f;w} Read from a Socket
sys.areadlink{f} Readlink
sys.areadstat{f;w;s} Read from a Socket and Return the Status
sys.areadwait{f;s;u} Read from a Socket within a Time Interval
sys.aselect{r;w;x;t} Select
sys.astat{c} File Stats

Table: sys.astat and sys.alstat Results in Terms of stat System Call Result

sys.awrite{f;a} Write to a Socket
sys.chdir{s} chdir
sys.chmod{s;m} chmod
sys.chown{s;m;n} chown
sys.close{f} close
sys.closelog{} closelog
sys.cpu{} CPU Time
sys.creat{f;m} create
sys.dup{f} dup
sys.dup2{f;g} dup2
sys.errno{} errno
sys.errsym{n} Error Symbol
sys.exit{n} exit
sys.exp{a} Simplified Export
sys.export{a;t;f} Export an Array
sys.fchmod{f;m} fchmod
sys.fchown{f;m;n} fchown
sys.fcntl{f;c;a} fcntl
sys.fflush_stdout{} Flush Standard Out
sys.filesize{f} File Size
sys.flock{f;o} flock
sys.fsync{f} fsync
sys.ftruncate{f;n} ftruncate
sys.getdomainname{} Domain Name
sys.getdtablesize{} getdtablesize
sys.geteuid{} geteuid
sys.getgid{} getgid
sys.gethostname{} Host Name
sys.getpid{} getpid
sys.getppid{} getppid
sys.getsockopt{s,l,on,ov,ol} getsockopt
sys.gettod{x} Time of Day
sys.getuid{} getuid
sys.getusername{} User Name
sys.imp{v} Simplified Import
sys.import{v;t} Import an A+ Array

Table: CDR-to-A+ Type Conversion

sys.ioctl{f;c;a} ioctl
sys.kill{n;s} kill
sys.link{a;b} link
sys.lseek{f;o;w} lseek
sys.mkdir{f;m} mkdir
sys.mkts1{x} Time in Seconds
sys.open{f;l;m} open
sys.openlog{c;l;f} openlog
sys.pathfind{v;p;f;m} pathfind
sys.perror{v} perror
sys.read{f;a;n} File to Character Vector
sys.readenv{x} getenv
sys.readinto{f;b;n} read
sys.readmat{f} File to Character Matrix
sys.rename{f;g} rename
sys.rmdir{f} rmdir
sys.secs_in_epoch{} Seconds in Epoch
sys.setenv{x} putenv
sys.setsockopt{s,l,on,ov,ol} setsockopt
sys.sfe{v;a} Socket ForkExec
sys.sleep{s} sleep
sys.sockaccept{f;w} Socket Accept
sys.sockblock{f;b} Socket Block
sys.sockconnect{h;p} Socket Connect
sys.socklisten{p} Socket Listen
sys.symlink{a;b} symlink
sys.syslog{a;m} syslog
sys.system{v} system
sys.truncate{f;n} truncate
sys.ts{} Current Local Time
sys.ts1{c} Local Time
sys.ts1gmt{c} GMT
sys.tsgmt{} Current GMT
sys.tzset{} Reset Time Zone
sys.umask{m} umask
sys.unlink{f} unlink
sys.updtime{f} File Update Time
sys.username{i} User Name from ID
sys.write{f;a;n} write
sys.zombiekiller{} Delete Defunct Children

# Introduction

> The sys context is native to A+. It is not to be loaded.

> Many of the sys-context functions are equivalent to Unix system calls or C-library routines. These system calls and library routines are not described here, but only their relationships to the sys-context functions. See the system manual pages for documentation. For example, the documentation on the chmod() system call can be viewed by executing man 2 chmod in an XTerm session, while the documentation on the times() library routine can be viewed by executing man 3 times.

# Functions that Modify Arguments

> Some functions in this chapter, e.g., sys.fcntl, modify some of their arguments. In such cases, the argument should have a name and the name should be used in the argument position, for then you can see the changes after the function has completed execution. In addition, you must be sure that other objects are not modified as well. The reason is that A+ manages reference counts on objects, meaning that at any point in an execution two or more names can actually share the same array value; sharing stops when the value of one of the objects changes in a normal A+ way. However, when functions like sys.fcntl modify an array value, that is not a normal A+ value change, and all names that had previously shared the value will now share the modified value. The remedy is to replace the named argument a with something like a0û(Òa)Òa.

# Path Names

> Path names to files and directories are represented by character vectors. Since Unix file names can contain blanks, blanks in the character vectors are considered significant. In particular, trailing blanks are considered significant, and therefore should be removed from the character vector representations unless they are necessary. Both sys.astat and sys.alstat, however, do remove trailing blanks.

# File Permissions Mode

> When a Unix file is created, its access permission characteristics are set, specifying who can read, write, and execute the file. The access permission characteristics are represented numerically as 4 for read, 2 for write, and 1 for execute. In addition, any additive combination of these three is allowed. For example, a file that is both readable and executable has file access 4+1, or 5, while a file opened for both reading and writing is opened with access permission 4+2, or 6. All possible access permissions are represented by the integers 1 through 7.

> Files have access characteristics for three independent classes of users: owner of the access, group access, and general access. If the access permissions are o for the owner, g for the group, and u for general users, then the access permissions of the file is the octal representation 8 8 8Âo,g,u.

# Manifest Constants

> Many of the sys-context functions are equivalent to Unix system calls. These system calls often have parameters which are specified by so-called manifest constants. For example, to open a file (in a C-language program) for reading only, one of the parameters to the open system call would be O_RDONLY. These constants can be specified in two ways in A+, either as symbols or integers. The symbol form is the most direct since it uses the names of the constants unchanged, and the names of these constants can be found in the "man page" documentation for the system calls. For example, in the case of the opening a file for reading only, the A+ function sys.open would be called with the second argument `O_RDONLY. The integer values of the constants can also be used, and can be found in the appropriate include files, although you are urged to use the symbols.

> Warning! The integer values may differ for Sun, IBM, and other systems.

> When more than one constant is to be specified, simply call the A+ function with the appropriate symbol vector. To use an integer argument in this case, OR the integer values of the individual constants together bitwise.

# Definitions of sys-Context Functions

## Export an Array sys.export{a;t;f}

Arguments and Result

> The argument a is any A+ array that does not contain a function expression, t is a character vector of length 256 or 0 (or the Null), and f is an integer scalar. The result is a one- or two-element nested vector.

Definition

> This function maps the object a to CDR (Common Data Representation) format for transferring among workstations or to APL systems. The argument t is a translation table. For example, if the object is to be sent to an APL2 system, then character (sub)arrays should be translated to EBCDIC character encoding. If the length of t is 0 then no translation occurs. The argument f is a boolean flag. If 1, symbols are not modified; if 0, which should be used when transferring A+ arrays to APL systems, symbols are converted to character vectors and the character translation defined by t is applied. If the mapping of a to CDR format is successful, the result is a two-element nested vector of the form (0;v), where v is the CDR formatted object. If the mapping fails, the result is of the form 1Ò<n, where the integer n is related to the length of the mapped portion of a at the time the error occurred.

> The function sys.exp should be used in place of this function.

## Import an A+ Array sys.import{v;t}

Arguments and Result

> Both the left argument v and the right argument t are character vectors; the right argument can also be the Null. The length of the right argument is either 0 or 256. The result is a one- or two-element nested vector.

Definition

> This function maps the CDR (Common Data Representation) formatted array v to an A+ object. The left argument v is the CDR formatted array. The right argument t is a translation table. For example, if the left argument v comes from an APL2 system, then character (sub)arrays must be translated from EBCDIC character encoding. If the length of t is 0 then no translation occurs. If v is successfully mapped to an A+ object then the result is a two-element nested vector of the form (0;a), where a is the decoded A+ object. If v cannot be mapped then the result is 1Ò<1.

> The CDR format allows for a richer set of data types than that used by A+. These are listed in the table "CDR-to-A+ Type Conversion", along with the A+ data types to which they are mapped. The mapping fails if v contains elements of data types that are rejected.

> The function sys.imp should be used in place of this function.

> CDR-to-A+ Type Conversion
> CDR Type | A+ Type
> --- | ---
> B1, B4 and B8 (1-bit, 4-bit, and 1-byte boolean) | `int
> I2 and I4 (2-byte and 4-byte integer) | `int
> C1 (1-byte character) | `char
> E4 and E8 (4-byte and 8-byte floating point) (assumed to be in IEEE floating-point format) | `float
> G0 (general array) | `box
> S1 (A+ extension to the CDR format for symbols) | `sym
> E16 (16-byte floating point) | rejected
> J8, J16 and J32 are rejected (8-byte, 16-byte, and 32-byte complex numbers) | rejected
> C4 (4-byte character) | rejected
> A8 (integer progression) | rejected
> Pn (packed decimal format) | rejected
> Zn (zoned decimal format) | rejected
> X0 (filler - the data in the object is meaningless) | rejected

## Simplified Export sys.exp{a}

Argument and Result

> The argument a is any A+ object that does not contain function expressions. The result is a character vector.

Definition

> This function is a simplified version of sys.export for transferring A+ objects among workstations. That is, sys.exp{a} is essentially equivalent to 1Øsys.export{a;();1). The result is the CDR format of a. If the translation fails, a domain error is signalled in the usual A+ manner. A lengthy call can be interrupted by a SIGINT (Ctl-c Ctl-c from an Emacs session). This capability allows one to rescue machines that are frozen because of a large sys.exp or adap.Send call.

> Handles little-endian files and 64-bit platforms.

## Simplified Import sys.imp{v}

Argument and Result

> The argument v is a character vector. The result is an A+ array.

Definition

> This function is a simplified version of sys.import for transferring A+ objects among workstations. That is, sys.imp{a} is essentially equivalent to 1Øsys.import{a;()}. The result is the A+ array represented by v. If the translation fails, a domain error is signalled in the usual A+ manner.

> Handles little-endian files and 64-bit platforms.

## Synchronize a Mapped File sys.amsync{a;i}

Arguments and Result

> The left argument a is a mapped file, and the right argument i is an integer scalar or vector. The result is an integer scalar.

Definition

> This function uses the msync() system call to synchronize the virtual memory pages of the mapped file with the file on disk. The value of the function is the value of that system call.

## File to Character Matrix sys.readmat{f}

Arguments and Result

> The argument f is a character vector. The result is a character matrix, or 0, or the Null.

Definition

> The argument f holds a path name of a file (see "Path Names"). The result is a character matrix holding the contents of that file; blanks are appended to rows to make them the same length as the longest line in the file. If the function fails, the result is 0 or the Null.

## exit sys.exit{n}

Argument and Result

> Both the argument and result are integer scalars.

Definition

> This function is equivalent to the exit() system call, for exiting from the process. The result of the function is the result of the system call. The A+ system function _exit should be used in place of this function.

## kill sys.kill{n;s}

Arguments

> The first argument is a scalar integer, the second a scalar symbol.

Definition

> This function is equivalent to the kill(pid, sig) system call, for sending a signal (the second argument) to a process (the first argument). The signals are:

> `SIGABRT | `SIGALRM | `SIGBUS | `SIGCHLD
> `SIGCONT | `SIGEMT | `SIGFPE | `SIGHUP
> `SIGILL | `SIGINT | `SIGIO | `SIGIOT
> `SIGKILL | `SIGPIPE | `SIGPROF | `SIGQUIT
> `SIGSEGV | `SIGSTOP | `SIGSYS | `SIGTERM
> `SIGTRAP | `SIGTSTP | `SIGTTIN | `SIGTTOU
> `SIGURG | `SIGUSR1 | `SIGUSR2 | `SIGVTALRM
> `SIGWINCH | `SIGXCPU | `SIGXFSZ

## Flush Standard Out sys.fflush_stdout{}

Definition

> This function is equivalent to the fflush(stdout) C-library call. The result is the Null.

## getenv sys.readenv{x}

Argument and Result

> The argument x is a character vector. The result is either a character vector or the Null.

Definition

> This function is equivalent to the getenv() system call, which returns the value of the environment variable named in x. The result of the function is the result of the system call if the system call is successful, and the Null otherwise.

## putenv sys.setenv{x}

Argument and Result

> The argument x is a character vector. The result is an integer scalar.

Definition

> This function is equivalent to the putenv() system call; the value of the argument x is of the form "NAME=VALUE", and environment variable named in NAME is given the value specified by VALUE. The result of the function is the result of the system call.

## sleep sys.sleep{s}

Argument and Result

> The argument s is a numeric scalar and the result is a scalar integer.

Definition

> This function suspends execution for s seconds. If s is an integer, negative (treated as 0), or floating-point and greater than 2147 (converted to the nearest integer), the sleep() system call is used. Otherwise, s is converted to the nearest microsecond (multiplied by one million and rounded to an integer) and the usleep() system call is used. The result of the function is the result of the system call.

## system sys.system{v}

Argument and Result

> The argument is a character vector. The result is a scalar integer.

Definition

> This function is equivalent to the system() system call, for executing character strings as if they were commands typed at a terminal. The result of the function is the result of the system call. This result depends upon the particular system - sys.system is highly nonportable. If you need advice about the use of this function, you should usually ask someone who knows a lot about Unix, and not necessarily someone who knows a lot about A+.

> Note that sh is invoked by default, not ksh, csh, or whatever; in particular, this means that ~ in path names is not treated as a "magic" character. If you need this or some other property of one of these shells, invoke that shell explicitly.

## access sys.access{f;m}

Arguments and Result

> The left argument f is a character vector and the right argument m is a symbol scalar or vector, or integer scalar. The result is an integer scalar.

Definition

> This function is equivalent to the access() system call, for determining the accessibility of a file. The left argument f holds a path name of a file (see "Path Names"), and the right argument m holds manifest constants (see "Manifest Constants"). The result of the function is the result of the system call.

## File Stats sys.astat{c}

Argument and Result

> The argument c is a character array. The result is an integer array of shape (¢1ÕÒc),13.

Definition

> The value of this function contains a variety of information produced by the stat() system call. If the argument c is a scalar or vector, it contains a path name of a file, and the result contains 13 entries for that file. If the argument has rank greater than 2, each cell of rank 1, i.e., each vector along the last axis, is a path name of a file, and the corresponding cell of rank 1 in the result contains 13 entries for that file. Trailing blanks are removed from the path names in both cases (see "Path Names"). The meanings of these entries in terms of the structure of the stat result are given in the table "sys.astat and sys.alstat Results in Terms of stat System Call Result". If the stat() system call fails for a path name, the corresponding entries in the result are all zero.

> sys.astat and sys.alstat Results in Terms of stat System Call Result
> A+ Index | stat Entry
> --- | ---
> 0 | st_dev
> 1 | st_ino
> 2 | st_mode
> 3 | st_nlink
> 4 | st_uid
> A+ Index | stat Entry
> --- | ---
> 5 | st_gid
> 6 | st_rdev
> 7 | st_size
> 8 | st_atime
> A+ Index | stat Entry
> --- | ---
> 9 | st_mtime
> 10 | st_ctime
> 11 | st_blksize
> 12 | st_blocks

## close sys.close{f}

Argument and Result

> The argument f and the result are scalar integers.

Definition

> This function is equivalent to the close() system call, for deleting the file descriptor f. The result of the function is the result of the system call.

## create sys.creat{f;m}

Arguments and Result

> The left argument f is a character vector, and both the right argument m and result are scalar integers.

Definition

> This function is equivalent to the creat() system call, for creating a new file or rewriting an existing one. The left argument f is the path name of a file (see "Path Names"), and the right argument m is the permissions mode (see "File Permissions Mode"). The result of the function is the result of the system call.

## File Size sys.filesize{f}

Argument and Result

> The argument f is a character vector. The result is an integer scalar.

Definition

> The result is the size in bytes of the open file whose path name is in the argument f (see "Path Names"). This function uses the fstat() system call, which provides a variety of information about (possibly) open files.

## flock sys.flock{f;o}

Arguments and Result

> The left argument f is a file descriptor, and the right argument o is a symbol scalar or vector, or integer scalar. The result is an integer scalar.

Definition

> This function is equivalent to the flock() system call, for applying or removing advisory locks on a file. The left argument f holds the descriptor of a file. The right argument o holds manifest constants (see "Manifest Constants") for the second argument of flock. The result of the function is the result of the system call. For some releases and some architectures, the file must be opened for writing in order for this function to succeed.

## fsync sys.fsync{f}

Argument and Result

> Both the argument and result are integer scalars.

Definition

> This function is equivalent to the fsync() system call, for synchronizing the incore copy of a file with the copy on disk. The argument f is a file descriptor. The result of the function is the result of the system call.

## getdtablesize sys.getdtablesize{}

Arguments and Result

> The result is an integer scalar.

Definition

> This function is equivalent to the getdtablesize() system call, which returns the maximum number of file descriptors. The result of the function is the result of the system call.

## lseek sys.lseek{f;o;w}

Arguments and Result

> All arguments and the result are integer scalars.

Definition

> This function is equivalent to the lseek() system call, for setting the pointer in the open file pointed to by the file descriptor f. The arguments of the function are in the same order as they will be in the call to lseek(). The result of the function is the result of the system call.

> For the argument w, use 0 for SEEK_SET, 1 for SEEK_CUR, and 2 for SEEK_END.

## open sys.open{f;l;m}

Arguments and Result

> The argument f is a character vector or symbol. The argument l is a symbol vector or scalar, or an integer scalar. The argument m and the result are integer scalars.

Definition

> This function is equivalent to the open() system call, which opens a file for reading, or writing, or both. The argument f holds the path name of a file (see "Path Names"), the argument l holds the manifest constants flags for the call to open() (see "Manifest Constants"), and the argument m is the permissions mode (see "File Permissions Mode"), perhaps modified by the process's umask value - see the open() man page. The result of the function is the result of the system call.

## pathfind sys.pathfind{v;p;f;m}

Arguments and Result

> The arguments v, p, and f are character vectors. The argument m is an integer scalar. The result is either a character vector or the Null.

Definition

> This function searches for the file named in the argument f, and returns its full path name if it is found and if it can be opened with the permissions specified by the argument m (see "File Permissions Mode"). Otherwise, it returns the Null. If the argument v holds an environment variable name, then the value of that variable specifies the search path. Otherwise, the argument p specifies the search path.

## File to Character Vector sys.read{f;a;n}

Arguments and Result

> The arguments f and n, and the result, are integer scalars. The argument a is a character vector.

Definition

> This function is nearly equivalent to the read() system call, for reading from the object specified by a file descriptor. The argument f is a file descriptor, n is the number of bytes to be read, and a is an A+ character vector of length at least n. The effect is to read at most n bytes from the file pointed to by f and place them in the value of a. The result is the actual number of bytes read.

> Warning! In most uses of sys.read, the argument a is a variable, and this variable exhibits the same behavior under ordinary assignment as mapped files. Consider the sequence:

>          xû100Ò' '
>          yûx
>          sys.read{fd;x;#x}

> At this point the value of y also has the same 100 characters that were read from the file into x; that is, y½x both before and after the sys.read evaluation.

## rename sys.rename{f;g}

Arguments and Result

> The arguments f and g are character vectors. The result is an integer scalar.

Definition

> This function is equivalent to the rename() system call, for renaming links. The arguments of the function are in the same order as they will be in the call to rename(). The result of the function is the result of the system call.

## truncate sys.truncate{f;n}

Arguments and Result

> The left argument f is a character vector. The right argument n and the result are scalar integers.

Definition

> This function is equivalent to the truncate() system call, for specifying the size of a file in bytes. The left argument f holds the path name of a file and the right argument n is the file size, in bytes. The result of the function is the result of the system call.

## ftruncate sys.ftruncate{f;n}

Arguments and Result

> Both arguments and the result are integer scalars.

Definition

> This function is equivalent to the ftruncate() system call, for specifying the size of a file in bytes. The left argument f is a file descriptor and the right argument n is the file size, in bytes. The result of the function is the result of the system call.

## umask sys.umask{m}

Argument and Result

> Both the argument and result are integer scalars.

Definition

> This function is equivalent to the umask() system call, for changing the session default file creation mask. The result of the function is the current setting, so later restoration is possible - including an immediate restoration when the aim is only to check the value. The new setting is the exclusive OR of m and 666 (octal) for a file or 777 for a directory. Thus an argument of 002 gives complete access to the group and read (and directory search) access to others.

> Execute
> sys.umask Õsys.umask 0;
> to display the current setting while leaving it unchanged.

## File Update Time sys.updtime{f}

Argument and Result

> The argument is a character vector. The result is a one-element integer vector.

Definition

> The argument f holds the path name of a file (see "Path Names"). The result is the time of the latest update of the file, measured in seconds since 00:00:00 GMT, January 1, 1970. This function uses the fstat() system call, which provides a variety of information about (possibly) open files.

## write sys.write{f;a;n}

Arguments and Result

> The arguments f and n, and the result, are integer scalars. The argument a is a character vector.

Definition

> This function is nearly equivalent to the write() system call, for writing in a file. The argument f is a file descriptor , n is the number of bytes to be written, and a is an A+ character vector of length at least n. The effect is to write at most n bytes from a in the file pointed to by f. The result is the actual number of bytes written.

> For example, sys.write{1;'hey';#'hey'}; will write 'hey' to stdout, and sys.write{2;'ho';#'ho'}; will write 'ho' to stderr, both without a newline. The file descriptors 1 and 2 are already opened when you start A+; there is no need to call sys.open.

## closelog sys.closelog{}

Result

> The result is the Null.

Definition

> This function is equivalent to the closelog() system call, for closing the system log.

## openlog sys.openlog{c;l;f}

Arguments and Result

> The argument c is a character vector. The arguments l and f are symbol vectors or scalars, or integer scalars. The result is the Null.

Definition

> This function is equivalent to the openlog() system call, for initializing the system log file. The arguments of the function are in the same order as they will be in the call to openlog(). The arguments l and f hold manifest constants (see "Manifest Constants").

## syslog sys.syslog{a;m}

Arguments and Result

> The left argument a is a symbol scalar or vector, or an integer scalar. The right argument m is a character vector.

Definition

> This function is equivalent to the syslog() system call, for logging messages. The arguments of the function are in the same order as they will be in the call to syslog(). The argument m holds manifest constants (see "Manifest Constants").

## errno sys.errno{}

Result

> The result is a scalar integer.

Definition

> The result is identical to the global errno in the Unix system, which is set by the last system call. About obtaining error descriptions, see sys.errsym, below.

## Error Symbol sys.errsym{n}

Argument and Result

> The argument n is a scalar integer. The result is a scalar symbol.

Definition

> The argument is an error number, as produced by sys.errno (above). The result is text describing the error.

## perror sys.perror{v}

Argument and Result

> The argument v is a character vector. The result is the Null.

Definition

> This function is equivalent to the perror() system call, which writes a short error message to standard error describing the error whose number is in errno (see sys.errno, above).

## Readlink sys.areadlink{f}

Argument and Result

> The argument is a character vector. The result is either a character vector or the scalar integer -1.

Definition

> The argument holds a path name of a file (see "Path Names"). If the file is a symbolic link, the result is a character vector holding the name of the file it references. If the file named in the argument is not a symbolic link, the result is -1.

## Linked File Stats sys.alstat{c}

Argument and Result

> The argument c is a character array. The result is an integer array of shape (¢1ÕÒc),13.

Definition

> This function is the same as sys.astat, except that it uses the lstat() system call instead of stat().

## link sys.link{a;b}

Arguments and Result

> The arguments a and b are character vectors. The result is an integer scalar.

Definition

> This function is equivalent to the link() system call, for establishing file links. The arguments, which are path names (see "Path Names") of the function are in the same order as they will be in the call to link().

> The result of the function is the result of the system call.

## symlink sys.symlink{a;b}

Arguments and Result

> The arguments a and b are character vectors. The result is an integer scalar.

Definition

> This function is equivalent to the symlink() system call, for creating symbolic links. The arguments of the function are in the same order as they will be in the call to symlink(). The result of the function is the result of the system call.

## unlink sys.unlink{f}

Argument and Result

> The argument f is a character vector. The result is an integer scalar.

Definition

> This function is equivalent to the unlink() system call, for removing the directory entry named by the path name f (see "Path Names") and decrementing the link count on the file named by f. The result of the function is the result of the system call.

## Domain Name sys.getdomainname{}

Result

> The result is a character vector.

Definition

> The result is the name of the domain of the current network domain.

## getgid sys.getgid{}

Result

> The result is an integer scalar.

Definition

> This function is equivalent to the getgid() system call, which returns the (real) group ID of the current process. The result of the function is the result of the system call.

## Host Name sys.gethostname{}

Result

> The result is a character vector.

Definition

> The result is the name of the current host machine.

## getpid sys.getpid{}

Result

> The result is an integer scalar.

Definition

> This function is equivalent to the getpid() system call, which returns the process ID of the current process. The result of the function is the result of the system call.

## getppid sys.getppid{}

Result

> The result is an integer scalar.

Definition

> This function is equivalent to the getppid() system call, which returns the process ID of the parent of the current process. The result of the function is the result of the system call.

## geteuid sys.geteuid{}

Result

> The result is an integer scalar.

Definition

> This function returns the effective user id, corresponding to the name returned by $whoami. See getuid, User Name, and User Name from ID, below.

## getuid sys.getuid{}

Result

> The result is an integer scalar.

Definition

> This function is equivalent to the getuid() system call, which returns the real user id of the current process. The result of the function is the result of the system call.

## User Name sys.getusername{}

Result

> The result is a character vector, or the null.

Definition

> The result is the name of the logged-in user: the "real" user name, in contrast to the "effective" user name, which is returned by $whoami. These two names can differ when su or a setuid script is used. sys.getusername{} calls the c library function pwd=getpwuid(getuid()) and returns the pwd->pw_name member of pwd. Null is returned if the requested entry is not found, or on an error or EOF; if null is returned, you can retry in a few seconds and see whether the problem (perhaps an updating) is gone.

## User Name from ID sys.username{i}

Result

> The result is a character vector.

Definition

> This function returns the user name corresponding to the user id i. See geteuid, getuid, and User Name, above.

## Directory Entries sys.agetdents{f}

Argument and Result

> The argument f is a character vector. The result is a character matrix.

Definition

> The argument f holds a path name to a directory (see "Path Names"). The rows of the result are the names of the files in that directory. The special files named . and .. are removed from the list.

## chdir sys.chdir{s}

Argument and Result

> The argument s is a character vector. The result is an integer scalar.

Definition

> This function is equivalent to the chdir() system call, for changing the process's working directory. The argument s holds the path name of a directory (see "Path Names"). The result of the function is the result of the system call. The PWD environment variable is set.

> The A+ system function _cd should be used in place of this function.

## mkdir sys.mkdir{f;m}

Arguments and Result

> The left argument f is a character vector, and the right argument m is an integer scalar.

Definition

> This function is equivalent to the mkdir() system call, for creating directories. The left argument f holds the path name of a file (see "Path Names"), and the right argument m is the permissions mode (see "File Permissions Mode"). The result of the function is the result of the system call.

## rmdir sys.rmdir{f}

Argument and Result

> The argument f is a character vector. The result is an integer scalar.

Definition

> This function is equivalent to the rmdir() system call, for removing directories. The argument f holds a path name of a file (see "Path Names"). The result of the function is the result of the system call.

## chmod sys.chmod{s;m}

Arguments and Result

> The left argument s is a character vector. The right argument m and the result are integer scalars.

Definition

> This function is equivalent to the chmod() system call, for changing permissions mode of a file. The left argument s holds the path name of a file (see "Path Names"), and the right argument m holds the permissions mode (see "File Permissions Mode"). The result of the function is the result of the system call.

## fchmod sys.fchmod{f;m}

Arguments and Result

> The left argument f, the right argument m, and the result are all integer scalars.

Definition

> This function is equivalent to the fchmod() system call, for changing permissions mode of a file. The left argument f is a file descriptor, and the right argument m holds the file permissions mode (see "File Permissions Mode"). The result of the function is the result of the system call.

## chown sys.chown{s;m;n}

Arguments and Result

> The argument s is a character vector. The arguments m and n, and the result, are integer scalars.

Definition

> This function is equivalent to the chown() system call, for changing owner and group of a file. The argument s holds the path name of a file (see "Path Names"), and the arguments m and n are the specifications for the owner and group, respectively. The result of the function is the result of the system call.

> Only a superuser can change the owner of a file. An owner can change the group of a file to one of which he is a member.

## fchown sys.fchown{f;m;n}

Arguments and Result

> The arguments f, m, and n, and the result, are all integer scalars.

Definition

> This function is equivalent to the fchown() system call, for changing the owner and group of a file. The argument f is a file descriptor, and the arguments m and n are the specifications for the owner and group, respectively. The result of the function is the result of the system call.

> Only a superuser can change the owner of a file. An owner can change the group of a file to one of which he is a member.

## CPU Time sys.cpu{}

Result

> The result is a four-element integer vector.

Definition

> This function uses the times() C-library routine to produce a four-element vector whose elements are (in order): user time of the current process; system time of the current process; user time for the children of the current process; system time for the children.

## Current GMT sys.tsgmt{}

Result

> The result is a seven-element integer vector.

Definition

> The result is the current Greenwich mean time, GMT, represented as: year, month, day, hour, minute, second, millisecond.

## Current Local Time sys.ts{}

Result

> The result is a seven-element integer vector.

Definition

> The result is the current local time, represented as: year, month, day, hour, minute, second, millisecond.

## Time of Day sys.gettod{x}

Argument and Result

> The argument x is an integer vector. The result is a two-element integer vector.

Definition

> This function uses the gettimeofday() system call. If the argument x has two elements then the first element represents minutes west of Greenwich and the second element is the Daylight Savings flag. If x does not have two elements, gettimeofday() is called with the NULL pointer as its second argument. The result of the function is the result of the system call.

## GMT sys.ts1gmt{c}

Argument and Result

> The argument is an integer scalar. The result is a seven-element integer vector.

Definition

> The argument represents some number of seconds since 00:00:00 GMT, January 1, 1970. The result is the equivalent GMT, represented as: year, month, day, hour, minute, second, 0.

## Local Time sys.ts1{c}

Argument and Result

> The argument is an integer scalar. The result is a seven-element integer vector.

Definition

> The argument represents some number of seconds since 00:00:00 GMT, January 1, 1970. The result is the equivalent local time, represented as: year, month, day, hour, minute, second, 0.

## Time in Seconds sys.mkts1{x}

Argument and Result

> The argument is an integer vector of length 7. The result is a scalar integer.

Definition

> The argument should be a local time in the form years, months, days, hours, minutes, seconds, microseconds. The argument is changed to 7Ù¢1Õx - i.e., the given time with the microseconds ignored.

> The result is this time converted to the number of seconds since 00:00:00 GMT, Jan. 1, 1970. If the conversion cannot be made (1930 ... or 2094 ... , for example), the result is -1.

> For an argument x that is in the appropriate range, sys.mkts1 sys.ts1 x is x.

## Seconds in Epoch sys.secs_in_epoch{}

Result

> The result is an integer scalar.

Definition

> The result is the current time measured in seconds since 00:00:00 GMT, January 1, 1970.

> Note that the result, which is identical to 0#sys.gettod{0}, can be used as an argument to sys.ts1 or sys.ts1gmt.

## Reset Time Zone sys.tzset{}

Definition

> Resets the time zone to the current local time zone. The result is Null.

## dup sys.dup{f}

Argument and Result

> The argument f and the result are integer scalars.

Definition

> This function is equivalent to the dup() system call, for duplicating the file descriptor f. The result of the function is the result of the system call.

## dup2 sys.dup2{f;g}

Arguments and Result

> Both the left argument f and the right argument g are integer scalars.

Definition

> This function is equivalent to the dup2() system call, for duplicating the file descriptor f and specifying its value to be that of the file descriptor g. The result of the function is the result of the system call.

## Read from a Socket sys.aread{f;w}

Arguments and Result

> The left argument f and the right argument w are integer scalars. The result is a simple character, integer, or floating-point array.

Definition

> The left argument f is the file descriptor of an internet stream socket. The effect of this function is to read the simple character, integer, or floating-point array from the connected process. If the right argument w is 0 then the system call select() is used with the zero timer to determine whether the file descriptor is ready to read. If not, execution ends and the result of this function is the Null. Otherwise, or if the value of w is not 0, the read() system call is invoked as often as necessary to build the array. If the function succeeds, the result is that array. If it fails for any reason, the result is the Null.

## Read from a Socket and Return the Status sys.areadstat{f;w;s}

Arguments and Result

> The arguments f, w and s are integer scalars. The argument s may be modified directly by this function (see "Functions that Modify Arguments"). The result is a simple character, integer, or floating-point array.

Definition

> This function is the same as sys.aread{f;w}, except that if the read fails the value of the argument s is set to -2 for an EWOULDBLOCK error, and -1 for all other errors.

## Read from a Socket within a Time Interval sys.areadwait{f;s;u}

Arguments and Result

> The arguments f, s, and u are integer scalars. The result is a simple character, integer, or floating-point array.

Definition

> This function is the same as sys.aread{f;0}, except that it uses the select() system call with the timer set to s seconds and u microseconds, instead of 0.

## getsockopt sys.getsockopt{s,l,on,ov,ol}

Arguments and Result

> The arguments s, l, and on, and the result, are integer scalars. The arguments ov and ol are integer vectors. Both these arguments can be modified directly by the function (see "Functions that Modify Arguments").

Definition

> This function is equivalent to the getsockopt() system call, for manipulating options associated with a socket. The arguments of the function are in the same order as they will be in the call to getsockopt(). The result of the function is the result of the system call.

## setsockopt sys.setsockopt{s,l,on,ov,ol}

Arguments and Result

> The arguments s, l, on, and ol, and the result, are integer scalars. The argument ov is an integer vector that can be modified directly by the function (see "Functions that Modify Arguments").

Definition

> This function is equivalent to the setsockopt() system call, which manipulates options associated with a socket. The arguments of the function are in the same order as they will be in the call to setsockopt(). The result of the function is the result of the system call.

## Socket Accept sys.sockaccept{f;w}

Arguments and Result

> Both arguments f and w, and the result are scalar integers.

Definition

> The argument f is the file descriptor of an internet stream socket. This is a server function whose effect is to accept connections from clients. The argument w is a wait flag. If w is 1 then the function blocks, i.e., does not return, until a connection is made. Otherwise, it returns immediately. If a connection is made, the result is the file descriptor of the connected socket. The result is -1 in case of an error, or -2 if w is 0 and no connection is made. This function uses the following system calls: accept(), select(), and setsockopt() (setting SO_KEEPALIVE).

## Socket Block sys.sockblock{f;b}

Arguments and Result

> Both arguments f and b are scalar integers. The result is the Null.

Definition

> The argument f is a file descriptor of an internet stream socket. The effect of this function is to set blocking on the socket if the blocking flag b is 1, and to set no blocking if b is 0. If blocking is set to 1 then sys.awrite does not return until the A+ array is entirely written, even though this may require the system to break the array into pieces and send them separately. This function uses the system call ioctl().

## Socket Connect sys.sockconnect{h;p}

Arguments and Result

> The left argument h is a character vector. The right argument p is an integer scalar. The result is an integer scalar.

Definition

> The left argument h holds the name of a host machine, and the right argument p is an internet TCP port. This is a client function whose effect is to connect to an internet stream socket on that port and host; a listening server is expected to be present. The result is the file descriptor of the connected socket if the connection is successful, and -1 otherwise. This function uses the following system calls: connect(), setsockopt() (setting SO_KEEPALIVE), and socket().

## Socket Listen sys.socklisten{p}

Argument and Result

> The argument p and the result are scalar integers.

Definition

> This is a server function whose effect is to create an internet stream socket for listening, and bind it to the internet TCP port specified by the argument p. The result is the file descriptor of the listening socket, or -1 if an error occurs. This function uses the following system calls: bind(), listen(), setsockopt() (setting SO_REUSEADDR), and socket().

## Socket ForkExec sys.sfe{v;a}

Arguments and Result

> The left argument v is a character vector and the right argument a is a simple integer vector.

Definition

> This function opens a bidirectional pipe, forks a new process, and makes the system call execvp().

> The arguments v and a hold valid first and second parameters to execvp(), respectively. In particular, the right argument is a vector of pointers to character strings, and its last element is 0 (if x is an A+ character vector, then c.ptr x is the pointer to the character string value of x). The result is the file descriptor for stdin and stdout of the forked process.

## Delete Defunct Children sys.zombiekiller{}

Result

> This function returns a count of how many processes it reaped, for lack of anything more useful.

Definition

> This function deletes any defunct child processes of the current A+ session.

## Write to a Socket sys.awrite{f;a}

Arguments and Result

> The left argument f is a scalar integer, and the right argument a is any simple character, integer, or floating-point array. The result is a scalar integer.

Definition

> The left argument f is the file descriptor of an internet stream socket. The effect of this function is to send the A+ array a to the connected process. The result is 0 if the function is successful. The result is -2 if an EWOULDBLOCK error occurs; all other errors produce a result of -1. This function uses the write() system call.

> Note that if a blocking error occurs, then an initial segment of the array a was sent.

## Select sys.aselect{r;w;x;t}

Arguments and Result

> The arguments are all integer scalars or vectors, with t of length 0, 1, or 2. The result is a five-element nested vector.

Definition

> This function calls the select() system call with the arguments r, w, and x as the read, write, and exceptional condition file descriptors, respectively, to determine which are ready. If the argument t is empty then select is called with the zero timer. Otherwise, the first element of t is seconds and the second element, if present, is microseconds. The width parameter of the select() call is computed to be one plus the largest value among the file descriptors in r, w, and x.

> The first element of the result is the return code from select(). The second element is the value of errno if that return code is negative, and 0 otherwise. The last three elements are the modified r, w, and x lists produced by select().

## fcntl sys.fcntl{f;c;a}

Arguments and Result

> The arguments f and a, and the result, are integer scalars. The argument c is a symbol scalar or integer scalar. The argument a may be modified directly by this function (see "Manifest Constants").

Definition

> This function is equivalent to the fcntl() system call, for performing a variety of functions on file descriptors. The argument f is a file descriptor, and the argument c is a manifest constant (see "Functions that Modify Arguments") designating the function for the system call. The argument a contains additional information, or is modified with new information, depending on c. The result of the function is the result of the system call.

## ioctl sys.ioctl{f;c;a}

Arguments and Result

> The arguments f and a, and the result, are integer scalars. The argument c is a symbol scalar or integer scalar. The argument a may be modified directly by this function (see "Functions that Modify Arguments").

Definition

> This function is equivalent to the ioctl() system call, for performing special functions on an object with the open file descriptor f. The argument c is a manifest constant (see "Manifest Constants") designating the function for the system call. The argument a contains additional information, or is modified with new information, depending on c. The result of the function is the result of the system call.

## read sys.readinto{f;b;n}

Arguments and Result

> The arguments f, b , and n, and the result, are integer scalars.

Definition

> This function is equivalent to the read() system call, for reading from a file. The argument f is a file descriptor, n is the number of bytes to be read, and b is a pointer to a character string of length at least n. The effect is to read at most n bytes from the file pointed to by f and place them in the character string pointed to by b. The result is the actual number of bytes read.