123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324 |
- .TH SYSTEM 3 "$Revision$"
- .ad
- .SH 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, 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_seek(filep, offset, whence, poffset)
- .B File *filep;
- .B long offset;
- .B int whence;
- .B long *poffset;
- .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 int sys_rename(path1, path2)
- .B char *path1, *path2;
- .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_seek
- sets the file pointer of
- .I filep
- as follows:
- .IP " "
- If
- .I whence
- is 0, the pointer is set to
- .I offset
- bytes.
- .IP " "
- If
- .I whence
- is 1, the pointer is set to its current location plus
- .IR offset .
- .IP " "
- If
- .I whence
- is 2, the pointer is set to the size of the file plus
- .IR offset .
- .PP
- Upon succesful completion, the resulting pointer location is returned in
- .IR poffset ,
- and 1 is returned. Otherwise, 0 is returned.
- .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
- .I Sys_rename
- renames file
- .I path1
- to
- .IR path2 .
- A non-zero return value indicates successful action. If
- .I path2
- exists, it is removed first.
- .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 ,
- .IR sys_chmode ,
- .IR sys_rename ,
- 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
|