SYSTEM(3)

NAME
sys_open, sys_close, sys_read, sys_write, sys_reset, sys_access, sys_modtime, sys_remove, sys_rename, sys_filesize, sys_chmode, sys_lock, sys_unlock, sys_break, sys_stop - system call interface

SYNOPSIS
#include <system.h>

File *STDIN, *STDOUT, *STDERR;

int sys_open(path, flag, filep)
char *path;
int flag;
File **filep;

void sys_close(filep)
File *filep;

int sys_read(filep, bufptr, bufsiz, pnbytes)
File *filep;
char *bufptr;
int bufsiz, *pnbytes;

int sys_write(filep, bufptr, nbytes)
File *filep;
char *bufptr;
int nbytes;

int sys_seek(filep, offset, whence, poffset)
File *filep;
long offset;
int whence;
long *poffset;

int sys_reset(filep)
File *filep

int sys_access(path, mode)
char *path;
int mode;

int sys_remove(path)
char *path;

int sys_rename(path1, path2)
char *path1, *path2;

long sys_filesize(path)
char *path;

int sys_chmode(path, mode)
char *path;
int mode;

int sys_lock(name)
char *name;

int sys_unlock(name)
char *name;

char *sys_break(incr)
int incr;

void sys_stop(how)
int how;

long sys_modtime(path)
char *path;

DESCRIPTION
This package provides a rather system-independent set of "system" calls primarily intended for use in compilers. The include file contains a defined constant, BUFSIZ, which gives the system-dependent block size. Another constant, SYS_NOPEN, gives the maximum number of open files in a process.

Sys_open opens a file called path for sequential reading or writing, as specified by flag and returns in filep a decsriptor for the opened file. The allowed values for flag are

OP_READ
    open for reading

OP_WRITE
    open for rewriting (create path if it did not exist)

OP_APPEND
    open for writing at the end (create path if it did not exist)

Created files are given read and write permission for its creator and read permission for other users.
Specifying path as null pointer opens a so-called anonymous file, which has no name and disappears when it is closed or when the program exits. It is possible to read the contents of an anonymous file by using reset .
There are three normally open files with the following descriptors:

STDIN
    standard input file; opened as OP_READ

STDOUT
    standard output file; opened as OP_APPEND

STDERR
    standard error file; opened as OP_APPEND

Sys_close causes the open file known by filep to be closed.

Sys_read causes up to bufsiz contiguous bytes to be read from the open file known by filep into a piece of memory pointed at by bufptr. The number of bytes actually read is returned in *pnbytes. If *pnbytes is set to 0 then the end-of-file is reached.

Sys_write writes nbytes contiguous bytes from the memory pointed at by bufptr onto the open file known by filep. A non-zero return value indicates that nbytes are actually written.

Sys_seek sets the file pointer of filep as follows:

    If whence is 0, the pointer is set to offset bytes.

    If whence is 1, the pointer is set to its current location plus offset.

    If whence is 2, the pointer is set to the size of the file plus offset.

Upon succesful completion, the resulting pointer location is returned in poffset, and 1 is returned. Otherwise, 0 is returned.

Sys_reset causes the open file known by filep to be re-opened for reading (cf. open flag OP_READ). This may be useful in reading anonymous files.

Sys_access checks the given file path for accessibility according to mode which is the result of or'ing one or more of the following values:

AC_READ
    file exists and is readable

AC_WRITE
    file exists and is writable

AC_EXEC
    file exists and is executable

Specifying mode as 0 tests whether the directories leading to the file can be searched and the file exists. The return value is either 0 if the file is not reachable, does not exist or if the access is not allowed, or 1 if the indicated access is permitted.

Sys_modtime returns the last-modified time of the file specified in path. Any failure is indicated by a return value of -1L.

Sys_remove removes file path from the system. It is supposed that, if the file is still open, the contents of the file are available until the last sys_close is performed on it. A non-zero return value indicates successful action whereas 0 indicates that the given file does not exist or cannot be removed.

Sys_rename renames file path1 to path2. A non-zero return value indicates successful action. If path2 exists, it is removed first.

The function sys_filesize returns the size in bytes of the file specified by path, if possible. The value -1L is returned if the size cannot be retrieved for some reason.

Sys_chmode changes the file-protection mode of file path to mode.

Sys_lock and sys_unlock provide a mechanism for setting and clearing symbolic locks for external objects. This is done by creating and removing file name. Sys_lock returns zero if the lock is already set and a non-zero value if the lock did not exist and has been created. Sys_unlock returns a non-zero value if the lock did not exist or if the lock has been removed succesfully. Zero is returned otherwise. The actions performed by these routines are atomic: race conditions cannot occur.

Sys_break adds incr more bytes to the program's data space and returns a pointer to the newly allocated area. ILL_BREAK is returned in case of some error, due to a lack of space or some interrupt. It is equivalent to the UNIX version 7 sbrk(2).

Sys_stop should be called when the process is terminated due to the end of the program or some error. This routine closes all open files and causes the program to stop in a way specified by how, which parameter has one of the following values:

S_END
    normal termination, indicate successful completion

S_EXIT
    terminate the process with status 1

S_ABORT
    abort this process and produce a post-mortem dump

Sys_time returns a long value that stands for the system's time. Its return value is a long that stands for the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds.

FILES
~em/modules/h/system.h
~em/modules/lib/libsystem.a

DIAGNOSTICS

The routines sys_open, sys_read, sys_write, sys_reset, sys_chmode, sys_rename, and sys_remove return a value of zero upon any failure and a non-zero value if the call succeeds.

BUGS
The current implementation does not allow the use of anonymous files.
Sys_reset is not implemented. A sys_close followed by a sys_open with the proper mode has the same effect on non-anonymous files.

SEE ALSO
UNIX version 7 manual volume 1, chapter 2