The sys Context


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 8o,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 TypeA+ 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 1sys.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 1sys.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 (1c),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+ Indexstat Entry
0st_dev
1st_ino
2st_mode
3st_nlink
4st_uid
A+ Indexstat Entry
5st_gid
6st_rdev
7st_size
8st_atime
A+ Indexstat Entry
9st_mtime
10st_ctime
11st_blksize
12st_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:

     x100' '
     yx
     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, yx 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 (1c),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٢1x - 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.

doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.