.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 .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