ack/modules/src/system/system.3

.TH SYSTEM 3ACK "86/03/24"
.ad
.SH NAME
sys_open, sys_close, sys_read, sys_write, sys_reset, sys_access,
sys_modtime, sys_remove, sys_filesize, sys_chmode,
sys_lock, sys_unlock,
sys_break, sys_stop, sys_time \- system call interface
.SH SYNOPSIS
.nf
.B #include <system.h>
.PP
.B File *STDIN, *STDOUT, *STDERR;
.PP
.B int sys_open(path, flag, filep)
.B char *path;
.B int flag;
.B File **filep;
.PP
.B sys_close(filep)
.B File *filep;
.PP
.B int sys_read(filep, bufptr, bufsiz, pnbytes)
.B File *filep;
.B char *bufptr;
.B int bufsiz, *pnbytes;
.PP
.B int sys_write(filep, bufptr, nbytes)
.B File *filep;
.B char *bufptr;
.B int nbytes;
.PP
.B int sys_reset(filep)
.B File *filep
.PP
.B int sys_access(path, mode)
.B char *path;
.B int mode;
.PP
.B int sys_remove(path)
.B char *path;
.PP
.B long sys_filesize(path)
.B char *path;
.PP
.B int sys_chmode(path, mode)
.B char *path;
.B int mode;
.PP
.B int sys_lock(name)
.B char *name;
.PP
.B int sys_unlock(name)
.B char *name;
.PP
.B char *sys_break(incr)
.B int incr;
.PP
.B sys_stop(how)
.B int how;
.PP
.B long sys_time();
.PP
.B long sys_modtime(path)
.B char *path;
.fi
.SH 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, 
.IR BUFSIZ ,
which gives the system-dependent block size.
Another constant,
.IR SYS_NOPEN ,
gives the maximum number of open files in a process.
.PP
.I Sys_open
opens a file called
.I path
for sequential reading or writing, as specified by 
.I flag
and returns in
.I filep
a decsriptor for the opened file.
The allowed values for 
.I flag
are
.IP OP_READ 15
open for reading
.IP OP_WRITE 15
open for rewriting (create
.I path
if it did not exist)
.IP OP_APPEND 15
open for writing at the end (create
.I path
if it did not exist)
.LP
Created files are given read and write permission for its creator and
read permission for other users.
.br
Specifying
.I 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
.I reset .
.br
There are three normally open files with the following descriptors:
.IP STDIN 15
standard input file; opened as OP_READ
.IP STDOUT 15
standard output file; opened as OP_APPEND
.IP STDERR 15
standard error file; opened as OP_APPEND
.LP
.I Sys_close
causes the open file known by
.I filep
to be closed.
.PP
.I Sys_read
causes up to
.I bufsiz
contiguous bytes to be read from the open file known by
.I filep
into a piece of memory pointed at by
.IR bufptr .
The number of bytes actually read is returned in
.IR *pnbytes .
If
.I *pnbytes
is set to 0 then the end-of-file is reached.
.PP
.I Sys_write
writes
.I nbytes
contiguous bytes from the memory pointed at by
.I bufptr
onto the open file known by
.IR filep .
A non-zero return value indicates that
.I nbytes
are actually written.
.PP
.I Sys_reset
causes the open file known by
.I filep
to be re-opened for reading (cf. open flag OP_READ).
This may be useful in reading anonymous files.
.PP
.I Sys_access
checks the given file
.I path
for accessibility according to
.I mode
which is the result of
.IR or 'ing
one or more of the following values:
.IP AC_READ 15
file exists and is readable
.IP AC_WRITE 15
file exists and is writable
.IP AC_EXEC 15
file exists and is executable
.LP
Specifying 
.I 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.
.PP
.I Sys_modtime
returns the last-modified time of the file specified in
.IR path .
Any failure is indicated by a return value of \-1L.
.PP
.I Sys_remove
removes file
.I path
from the system.
It is supposed that, if the file is still open, the contents of
the file are available until the last
.I 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.
.PP
The function 
.I sys_filesize
returns the size in bytes of the
file specified by 
.IR path ,
if possible.
The value \-1L is returned if the size cannot be retrieved for some reason.
.PP
.I Sys_chmode
changes the file-protection mode of file
.I path
to 
.IR mode .
.PP
.I Sys_lock
and
.I sys_unlock
provide a mechanism for setting and clearing symbolic locks for external
objects.
This is done by creating and removing file
.IR name .
.I 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.
.I 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.
.PP
.I Sys_break
adds 
.I 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 
.IR sbrk (2).
.PP
.I 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 
.IR how ,
which parameter has one of the following values:
.IP S_END 15
normal termination, indicate successful completion
.IP S_EXIT 15
terminate the process with status 
.B 1
.IP S_ABORT 15
abort this process and produce a post-mortem dump
.LP
.PP
.I 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.
.SH FILES
.nf
~em/modules/h/system.h
~em/modules/lib/libsystem.a
.fi
.SH DIAGNOSTICS
.PP
The routines 
.IR sys_open ,
.IR sys_read ,
.IR sys_write ,
.IR sys_reset ,
.I sys_chmode
and
.I sys_remove
return a value of zero upon any failure and a non-zero
value if the call succeeds.
.SH BUGS
The current implementation does not allow the use of anonymous files.
.br
.I Sys_reset
is not implemented.
A
.I sys_close
followed by a
.I sys_open
with the proper mode has the same effect on non-anonymous files.
.SH "SEE ALSO"
UNIX version 7 manual volume 1, chapter 2
.SH AUTHOR
Erik Baalbergen <erikb@vu44.UUCP>