system.3 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324
  1. .TH SYSTEM 3 "$Revision$"
  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