modules/src/system/system.3

   1 .TH SYSTEM 3 "$Revision: 1.7 $"
   2 .ad
   3 .SH NAME
   4 sys_open, sys_close, sys_read, sys_write, sys_reset, sys_access,
   5 sys_modtime, sys_remove, sys_rename, sys_filesize, sys_chmode,
   6 sys_lock, sys_unlock,
   7 sys_break, sys_stop, sys_time \- system call interface
   8 .SH SYNOPSIS
   9 .nf
  10 .B #include <system.h>
  11 .PP
  12 .B File *STDIN, *STDOUT, *STDERR;
  13 .PP
  14 .B int sys_open(path, flag, filep)
  15 .B char *path;
  16 .B int flag;
  17 .B File **filep;
  18 .PP
  19 .B void sys_close(filep)
  20 .B File *filep;
  21 .PP
  22 .B int sys_read(filep, bufptr, bufsiz, pnbytes)
  23 .B File *filep;
  24 .B char *bufptr;
  25 .B int bufsiz, *pnbytes;
  26 .PP
  27 .B int sys_write(filep, bufptr, nbytes)
  28 .B File *filep;
  29 .B char *bufptr;
  30 .B int nbytes;
  31 .PP
  32 .B int sys_seek(filep, offset, whence, poffset)
  33 .B File *filep;
  34 .B long offset;
  35 .B int whence;
  36 .B long *poffset;
  37 .PP
  38 .B int sys_reset(filep)
  39 .B File *filep
  40 .PP
  41 .B int sys_access(path, mode)
  42 .B char *path;
  43 .B int mode;
  44 .PP
  45 .B int sys_remove(path)
  46 .B char *path;
  47 .PP
  48 .B int sys_rename(path1, path2)
  49 .B char *path1, *path2;
  50 .PP
  51 .B long sys_filesize(path)
  52 .B char *path;
  53 .PP
  54 .B int sys_chmode(path, mode)
  55 .B char *path;
  56 .B int mode;
  57 .PP
  58 .B int sys_lock(name)
  59 .B char *name;
  60 .PP
  61 .B int sys_unlock(name)
  62 .B char *name;
  63 .PP
  64 .B char *sys_break(incr)
  65 .B int incr;
  66 .PP
  67 .B void sys_stop(how)
  68 .B int how;
  69 .PP
  70 .B long sys_time();
  71 .PP
  72 .B long sys_modtime(path)
  73 .B char *path;
  74 .fi
  75 .SH DESCRIPTION
  76 This package provides a rather system-independent set of "system" calls
  77 primarily intended for use in compilers.
  78 The include file contains a defined constant,
  79 .IR BUFSIZ ,
  80 which gives the system-dependent block size.
  81 Another constant,
  82 .IR SYS_NOPEN ,
  83 gives the maximum number of open files in a process.
  84 .PP
  85 .I Sys_open
  86 opens a file called
  87 .I path
  88 for sequential reading or writing, as specified by
  89 .I flag
  90 and returns in
  91 .I filep
  92 a decsriptor for the opened file.
  93 The allowed values for
  94 .I flag
  95 are
  96 .IP OP_READ 15
  97 open for reading
  98 .IP OP_WRITE 15
  99 open for rewriting (create
 100 .I path
 101 if it did not exist)
 102 .IP OP_APPEND 15
 103 open for writing at the end (create
 104 .I path
 105 if it did not exist)
 106 .LP
 107 Created files are given read and write permission for its creator and
 108 read permission for other users.
 109 .br
 110 Specifying
 111 .I path
 112 as null pointer opens a so-called anonymous file, which has no name and
 113 disappears when it is closed or when the program exits.
 114 It is possible to read the contents of an anonymous file by using
 115 .I reset .
 116 .br
 117 There are three normally open files with the following descriptors:
 118 .IP STDIN 15
 119 standard input file; opened as OP_READ
 120 .IP STDOUT 15
 121 standard output file; opened as OP_APPEND
 122 .IP STDERR 15
 123 standard error file; opened as OP_APPEND
 124 .LP
 125 .I Sys_close
 126 causes the open file known by
 127 .I filep
 128 to be closed.
 129 .PP
 130 .I Sys_read
 131 causes up to
 132 .I bufsiz
 133 contiguous bytes to be read from the open file known by
 134 .I filep
 135 into a piece of memory pointed at by
 136 .IR bufptr .
 137 The number of bytes actually read is returned in
 138 .IR *pnbytes .
 139 If
 140 .I *pnbytes
 141 is set to 0 then the end-of-file is reached.
 142 .PP
 143 .I Sys_write
 144 writes
 145 .I nbytes
 146 contiguous bytes from the memory pointed at by
 147 .I bufptr
 148 onto the open file known by
 149 .IR filep .
 150 A non-zero return value indicates that
 151 .I nbytes
 152 are actually written.
 153 .PP
 154 .I Sys_seek
 155 sets the file pointer of
 156 .I filep
 157 as follows:
 158 .IP " "
 159 If
 160 .I whence
 161 is 0, the pointer is set to
 162 .I offset
 163 bytes.
 164 .IP " "
 165 If
 166 .I whence
 167 is 1, the pointer is set to its current location plus
 168 .IR offset .
 169 .IP " "
 170 If
 171 .I whence
 172 is 2, the pointer is set to the size of the file plus
 173 .IR offset .
 174 .PP
 175 Upon succesful completion, the resulting pointer location is returned in
 176 .IR poffset ,
 177 and 1 is returned. Otherwise, 0 is returned.
 178 .PP
 179 .I Sys_reset
 180 causes the open file known by
 181 .I filep
 182 to be re-opened for reading (cf. open flag OP_READ).
 183 This may be useful in reading anonymous files.
 184 .PP
 185 .I Sys_access
 186 checks the given file
 187 .I path
 188 for accessibility according to
 189 .I mode
 190 which is the result of
 191 .IR or 'ing
 192 one or more of the following values:
 193 .IP AC_READ 15
 194 file exists and is readable
 195 .IP AC_WRITE 15
 196 file exists and is writable
 197 .IP AC_EXEC 15
 198 file exists and is executable
 199 .LP
 200 Specifying
 201 .I mode
 202 as 0 tests whether the directories leading to the file can be searched and the
 203 file exists.
 204 The return value is either 0 if the
 205 file is not reachable, does not exist or if the access is not allowed,
 206 or 1 if the indicated access is permitted.
 207 .PP
 208 .I Sys_modtime
 209 returns the last-modified time of the file specified in
 210 .IR path .
 211 Any failure is indicated by a return value of \-1L.
 212 .PP
 213 .I Sys_remove
 214 removes file
 215 .I path
 216 from the system.
 217 It is supposed that, if the file is still open, the contents of
 218 the file are available until the last
 219 .I sys_close
 220 is performed on it.
 221 A non-zero return value indicates successful action whereas 0
 222 indicates that the given file does not exist or cannot be removed.
 223 .PP
 224 .I Sys_rename
 225 renames file
 226 .I path1
 227 to
 228 .IR path2 .
 229 A non-zero return value indicates successful action. If
 230 .I path2
 231 exists, it is removed first.
 232 .PP
 233 The function
 234 .I sys_filesize
 235 returns the size in bytes of the
 236 file specified by
 237 .IR path ,
 238 if possible.
 239 The value \-1L is returned if the size cannot be retrieved for some reason.
 240 .PP
 241 .I Sys_chmode
 242 changes the file-protection mode of file
 243 .I path
 244 to
 245 .IR mode .
 246 .PP
 247 .I Sys_lock
 248 and
 249 .I sys_unlock
 250 provide a mechanism for setting and clearing symbolic locks for external
 251 objects.
 252 This is done by creating and removing file
 253 .IR name .
 254 .I Sys_lock
 255 returns zero if the lock is already set and a non-zero value if the lock
 256 did not exist and has been created.
 257 .I Sys_unlock
 258 returns a non-zero value if the lock did not exist or if the lock has been
 259 removed succesfully.
 260 Zero is returned otherwise.
 261 The actions performed by these routines are atomic:
 262 race conditions cannot
 263 occur.
 264 .PP
 265 .I Sys_break
 266 adds
 267 .I incr
 268 more bytes to the program's data space and returns a pointer to
 269 the newly allocated area.
 270 ILL_BREAK is returned in case of some error, due to a lack of space or
 271 some interrupt.
 272 It is equivalent to the UNIX version 7
 273 .IR sbrk (2).
 274 .PP
 275 .I Sys_stop
 276 should be called when the process is terminated due to
 277 the end of the program or some error.
 278 This routine closes all open files and causes the program to
 279 stop in a way specified by
 280 .IR how ,
 281 which parameter has one of the following values:
 282 .IP S_END 15
 283 normal termination, indicate successful completion
 284 .IP S_EXIT 15
 285 terminate the process with status
 286 .B 1
 287 .IP S_ABORT 15
 288 abort this process and produce a post-mortem dump
 289 .LP
 290 .PP
 291 .I Sys_time
 292 returns a long value that stands for the system's time.
 293 Its return value is a long that stands for the time
 294 since 00:00:00 GMT, Jan. 1, 1970, measured in seconds.
 295 .SH FILES
 296 .nf
 297 ~em/modules/h/system.h
 298 ~em/modules/lib/libsystem.a
 299 .fi
 300 .SH DIAGNOSTICS
 301 .PP
 302 The routines
 303 .IR sys_open ,
 304 .IR sys_read ,
 305 .IR sys_write ,
 306 .IR sys_reset ,
 307 .IR sys_chmode ,
 308 .IR sys_rename ,
 309 and
 310 .I sys_remove
 311 return a value of zero upon any failure and a non-zero
 312 value if the call succeeds.
 313 .SH BUGS
 314 The current implementation does not allow the use of anonymous files.
 315 .br
 316 .I Sys_reset
 317 is not implemented.
 318 A
 319 .I sys_close
 320 followed by a
 321 .I sys_open
 322 with the proper mode has the same effect on non-anonymous files.
 323 .SH "SEE ALSO"
 324 UNIX version 7 manual volume 1, chapter 2