fopen 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354
  1. .TH FOPEN 2
  2. .SH NAME
  3. fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw, sclose, fflush, setvbuf, setbuf, fgetpos, ftell, fsetpos, fseek, rewind, feof, ferror, clearerr \- standard buffered input/output package
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <stdio.h>
  8. .PP
  9. .ta \w'\fLFILE 'u
  10. .B
  11. FILE *fopen(char *filename, char *mode)
  12. .PP
  13. .B
  14. FILE *freopen(char *filename, char *mode, FILE *f)
  15. .PP
  16. .B
  17. FILE *fdopen(int fd, char *mode)
  18. .PP
  19. .B
  20. int fileno(FILE *f)
  21. .PP
  22. .B
  23. FILE *sopenr(char *s)
  24. .PP
  25. .B
  26. FILE *sopenw(void)
  27. .PP
  28. .B
  29. char *sclose(FILE *f)
  30. .PP
  31. .B
  32. int fclose(FILE *f)
  33. .PP
  34. .B
  35. int fflush(FILE *f)
  36. .PP
  37. .B
  38. int setvbuf(FILE *f, char *buf, int type, long size)
  39. .PP
  40. .B
  41. void setbuf(FILE *f, char *buf)
  42. .PP
  43. .B
  44. int fgetpos(FILE *f, long *pos)
  45. .PP
  46. .B
  47. long ftell(FILE *f)
  48. .PP
  49. .B
  50. int fsetpos(FILE *f, long *pos)
  51. .PP
  52. .B
  53. int fseek(FILE *f, long offset, int whence)
  54. .PP
  55. .B
  56. void rewind(FILE *f)
  57. .PP
  58. .B
  59. int feof(FILE *f)
  60. .PP
  61. .B
  62. int ferror(FILE *f)
  63. .PP
  64. .B
  65. void clearerr(FILE *f)
  66. .SH DESCRIPTION
  67. The functions described in this and related pages
  68. .RI ( fgetc (2),
  69. .IR fprintf (2),
  70. .IR fscanf (2),
  71. and
  72. .IR tmpfile (2))
  73. implement the
  74. ANSI C buffered I/O package with extensions.
  75. .PP
  76. A file with associated buffering is called a
  77. .I stream
  78. and is declared to be a pointer to a defined type
  79. .BR FILE .
  80. .IR Fopen (2)
  81. creates certain descriptive data for a stream
  82. and returns a pointer to designate the stream in all
  83. further transactions.
  84. There are three normally open streams with constant
  85. pointers declared in
  86. the include file and associated with the standard open files:
  87. .TP 10n
  88. .BR stdin
  89. standard input file
  90. .br
  91. .ns
  92. .TP
  93. .B stdout
  94. standard output file
  95. .br
  96. .ns
  97. .TP
  98. .B stderr
  99. standard error file
  100. .PP
  101. A constant pointer
  102. .B NULL
  103. designates no stream at all.
  104. .PP
  105. .I Fopen
  106. opens the file named by
  107. .I filename
  108. and associates a stream with it.
  109. .I Fopen
  110. returns a pointer to be used to identify
  111. the stream in subsequent operations, or
  112. .B NULL
  113. if the open fails.
  114. .I Mode
  115. is a character string having one of the following values:
  116. .nf
  117. .ta 8n
  118. \fL"r"\fP open for reading
  119. \fL"w"\fP truncate to zero length or create for writing
  120. \fL"a"\fP append; open or create for writing at end of file
  121. \fL"r+"\fP open for update (reading and writing)
  122. \fL"w+"\fP truncate to zero length or create for update
  123. \fL"a+"\fP append; open or create for update at end of file
  124. .fi
  125. .PP
  126. In addition, each of the above strings can have a
  127. .L b
  128. somewhere after the first character,
  129. meaning `binary file', but this implementation makes no distinction
  130. between binary and text files.
  131. .PP
  132. .I Fclose
  133. causes the stream pointed to by
  134. .I f
  135. to be flushed (see below) and does a
  136. .I close
  137. (see
  138. .IR open (2))
  139. on the associated file.
  140. It frees any automatically allocated buffer.
  141. .I Fclose
  142. is called automatically on
  143. .IR exits (2)
  144. for all open streams.
  145. .PP
  146. .I Freopen
  147. is like open except that it reuses stream pointer
  148. .IR f .
  149. .I Freopen
  150. first attempts to close any file associated with
  151. .IR f ;
  152. it ignores any errors in that close.
  153. .PP
  154. .I Fdopen
  155. associates a stream with an open Plan 9 file descriptor.
  156. .PP
  157. .I Fileno
  158. returns the number of the Plan 9 file descriptor associated with the stream.
  159. .PP
  160. .I Sopenr
  161. associates a read-only stream with a null-terminated string.
  162. .PP
  163. .I Sopenw
  164. opens a stream for writing.
  165. No file descriptor is associated with the stream;
  166. instead, all output is written to the stream buffer.
  167. .PP
  168. .I Sclose
  169. closes a stream opened with
  170. .I sopenr
  171. or
  172. .IR sopenw .
  173. It returns a pointer to the 0 terminated buffer associated with the stream.
  174. .PP
  175. By default, output to a stream is fully buffered: it is accumulated in
  176. a buffer until the buffer is full, and then
  177. .I write
  178. (see
  179. .IR read (2))
  180. is used to write the buffer.
  181. An exception is standard error, which is line buffered:
  182. output is accumulated in a buffer until
  183. a newline is written.
  184. Input is also fully buffered by default; this means that
  185. .IR read (2)
  186. is used to fill a buffer as much as it can, and then characters
  187. are taken from that buffer until it empties.
  188. .I Setvbuf
  189. changes the buffering method for file
  190. .I f
  191. according to
  192. .IR type:
  193. either
  194. .B _IOFBF
  195. for fully buffered,
  196. .B _IOLBF
  197. for line buffered,
  198. or
  199. .B _IONBF
  200. for unbuffered (each character causes a
  201. .I read
  202. or
  203. .IR write).
  204. If
  205. .I buf
  206. is supplied, it is used as the buffer and
  207. .I size
  208. should be its size;
  209. If
  210. .I buf
  211. is zero, a buffer of the given size is allocated (except for the unbuffered case) using
  212. .IR malloc (2).
  213. .PP
  214. .I Setbuf
  215. is an older method for changing buffering. If
  216. .I buf
  217. is supplied, it changes to fully buffered with the given buffer, which should
  218. be of size
  219. .B BUFSIZ
  220. (defined in
  221. .BR stdio.h ).
  222. If
  223. .I buf
  224. is zero, the buffering method changes to unbuffered.
  225. .PP
  226. .I Fflush
  227. flushes the buffer of output stream
  228. .IR f ,
  229. delivering any unwritten buffered data to the host file.
  230. .PP
  231. There is a
  232. .I file position indicator
  233. associated with each stream.
  234. It starts out pointing at the first character (unless the file is opened
  235. with append mode, in which case the indicator is always ignored).
  236. The file position indicator is maintained by the reading and writing
  237. functions described in
  238. .IR fgetc (2).
  239. .PP
  240. .I Fgetpos
  241. stores the current value of the file position indicator for stream
  242. .I f
  243. in the object pointed to by
  244. .IR pos .
  245. It returns zero on success, nonzero otherwise.
  246. .I Ftell
  247. returns the current value of the file position indicator.
  248. The file position indicator is to
  249. be used only as an argument to
  250. .IR fseek.
  251. .PP
  252. .I Fsetpos
  253. sets the file position indicator for stream
  254. .I f
  255. to the value of the object pointed to by
  256. .IR pos ,
  257. which shall be a value returned by an earlier call to
  258. .I fgetpos
  259. on the same stream.
  260. It returns zero on success, nonzero otherwise.
  261. .I Fseek
  262. obtains a new position, measured in characters from the beginning
  263. of the file, by adding
  264. .I offset
  265. to the position specified by
  266. .IR whence :
  267. the beginning of the file if
  268. .I whence
  269. is
  270. .BR SEEK_SET ;
  271. the current value of the file position indicator for
  272. .BR SEEK_CUR ;
  273. and the end-of-file for
  274. .BR SEEK_END .
  275. .I Rewind
  276. sets the file position indicator to the beginning of the file.
  277. .PP
  278. An integer constant
  279. .B EOF
  280. is returned
  281. upon end of file or error by integer-valued functions that
  282. deal with streams.
  283. .I Feof
  284. returns non-zero if and only if
  285. .I f
  286. is at its end of file.
  287. .PP
  288. .I Ferror
  289. returns non-zero if and only if
  290. .I f
  291. is in the error state. It can get into the error state
  292. if a system call failed on the associated file
  293. or a memory allocation failed.
  294. .I Clearerr
  295. takes a stream out of the error state.
  296. .SH SOURCE
  297. .B /sys/src/libstdio
  298. .SH "SEE ALSO"
  299. .IR fprintf (2),
  300. .IR fscanf (2),
  301. .IR fgetc (2)
  302. .br
  303. .IR open (2),
  304. .IR read (2)
  305. .SH DIAGNOSTICS
  306. The value
  307. .B EOF
  308. is returned uniformly to indicate that a
  309. .B FILE
  310. pointer has not been initialized with
  311. .IR fopen ,
  312. input (output) has been attempted on an output (input) stream,
  313. or a
  314. .B FILE
  315. pointer designates corrupt or otherwise unintelligible
  316. .B FILE
  317. data.
  318. .br
  319. Some of these functions set
  320. .IR errstr .
  321. .SH BUGS
  322. Buffering of output can prevent output data
  323. from being seen until long after it is computed \- perhaps
  324. never, as when an abort occurs between buffer filling and flushing.
  325. .br
  326. Buffering of input can cause a process to consume
  327. more input than it actually uses.
  328. This can cause trouble across
  329. .IR exec (2).
  330. .br
  331. Buffering may delay the receipt of a write error until a subsequent
  332. .I stdio
  333. writing, seeking, or file-closing call.
  334. .br
  335. ANSI says that a file can be fully buffered only if
  336. the file is not attached to an interactive device.
  337. In Plan 9 all are fully buffered except standard error.
  338. .PP
  339. .IR Fdopen ,
  340. .IR fileno ,
  341. .IR sopenr ,
  342. .IR sopenw ,
  343. and
  344. .I sclose
  345. are not ANSI Stdio functions.
  346. .PP
  347. Stdio offers no support for runes or
  348. .SM UTF
  349. characters.
  350. Unless external compatibility is necessary, use
  351. .IR bio (2),
  352. which supports
  353. .SM UTF
  354. and is smaller, faster, and simpler than Stdio.