283 lines
6.2 KiB
Groff
283 lines
6.2 KiB
Groff
.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>
|