bio 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351
  1. .TH BIO 2
  2. .SH NAME
  3. Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output
  4. .SH SYNOPSIS
  5. .ta \w'Biobuf* 'u
  6. .B #include <u.h>
  7. .br
  8. .B #include <libc.h>
  9. .br
  10. .B #include <bio.h>
  11. .PP
  12. .B
  13. Biobuf* Bopen(char *file, int mode)
  14. .PP
  15. .B
  16. int Binit(Biobuf *bp, int fd, int mode)
  17. .PP
  18. .B
  19. int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)
  20. .PP
  21. .B
  22. int Bterm(Biobufhdr *bp)
  23. .PP
  24. .B
  25. int Bprint(Biobufhdr *bp, char *format, ...)
  26. .PP
  27. .B
  28. int Bvprint(Biobufhdr *bp, char *format, va_list arglist);
  29. .PP
  30. .B
  31. void* Brdline(Biobufhdr *bp, int delim)
  32. .PP
  33. .B
  34. char* Brdstr(Biobufhdr *bp, int delim, int nulldelim)
  35. .PP
  36. .B
  37. int Blinelen(Biobufhdr *bp)
  38. .PP
  39. .B
  40. vlong Boffset(Biobufhdr *bp)
  41. .PP
  42. .B
  43. int Bfildes(Biobufhdr *bp)
  44. .PP
  45. .B
  46. int Bgetc(Biobufhdr *bp)
  47. .PP
  48. .B
  49. long Bgetrune(Biobufhdr *bp)
  50. .PP
  51. .B
  52. int Bgetd(Biobufhdr *bp, double *d)
  53. .PP
  54. .B
  55. int Bungetc(Biobufhdr *bp)
  56. .PP
  57. .B
  58. int Bungetrune(Biobufhdr *bp)
  59. .PP
  60. .B
  61. vlong Bseek(Biobufhdr *bp, vlong n, int type)
  62. .PP
  63. .B
  64. int Bputc(Biobufhdr *bp, int c)
  65. .PP
  66. .B
  67. int Bputrune(Biobufhdr *bp, long c)
  68. .PP
  69. .B
  70. long Bread(Biobufhdr *bp, void *addr, long nbytes)
  71. .PP
  72. .B
  73. long Bwrite(Biobufhdr *bp, void *addr, long nbytes)
  74. .PP
  75. .B
  76. int Bflush(Biobufhdr *bp)
  77. .PP
  78. .B
  79. int Bbuffered(Biobufhdr *bp)
  80. .PP
  81. .SH DESCRIPTION
  82. These routines implement fast buffered I/O.
  83. I/O on different file descriptors is independent.
  84. .PP
  85. .I Bopen
  86. opens
  87. .I file
  88. for mode
  89. .B OREAD
  90. or creates for mode
  91. .BR OWRITE .
  92. It calls
  93. .IR malloc (2)
  94. to allocate a buffer.
  95. .PP
  96. .I Binit
  97. initializes a standard size buffer, type
  98. .IR Biobuf ,
  99. with the open file descriptor passed in
  100. by the user.
  101. .I Binits
  102. initializes a non-standard size buffer, type
  103. .IR Biobufhdr ,
  104. with the open file descriptor,
  105. buffer area, and buffer size passed in
  106. by the user.
  107. .I Biobuf
  108. and
  109. .I Biobufhdr
  110. are related by the declaration:
  111. .IP
  112. .EX
  113. typedef struct Biobuf Biobuf;
  114. struct Biobuf
  115. {
  116. Biobufhdr;
  117. uchar b[Bungetsize+Bsize];
  118. };
  119. .EE
  120. .PP
  121. Arguments
  122. of types pointer to Biobuf and pointer to Biobufhdr
  123. can be used interchangeably in the following routines.
  124. .PP
  125. .IR Bopen ,
  126. .IR Binit ,
  127. or
  128. .I Binits
  129. should be called before any of the
  130. other routines on that buffer.
  131. .I Bfildes
  132. returns the integer file descriptor of the associated open file.
  133. .PP
  134. .I Bterm
  135. flushes the buffer for
  136. .IR bp .
  137. If the buffer was allocated by
  138. .IR Bopen ,
  139. the buffer is
  140. .I freed
  141. and the file is closed.
  142. .PP
  143. .I Brdline
  144. reads a string from the file associated with
  145. .I bp
  146. up to and including the first
  147. .I delim
  148. character.
  149. The delimiter character at the end of the line is
  150. not altered.
  151. .I Brdline
  152. returns a pointer to the start of the line or
  153. .L 0
  154. on end-of-file or read error.
  155. .I Blinelen
  156. returns the length (including the delimiter)
  157. of the most recent string returned by
  158. .IR Brdline .
  159. .PP
  160. .I Brdstr
  161. returns a
  162. .IR malloc (2)-allocated
  163. buffer containing the next line of input delimited by
  164. .IR delim ,
  165. terminated by a NUL (0) byte.
  166. Unlike
  167. .IR Brdline ,
  168. which returns when its buffer is full even if no delimiter has been found,
  169. .I Brdstr
  170. will return an arbitrarily long line in a single call.
  171. If
  172. .I nulldelim
  173. is set, the terminal delimiter will be overwritten with a NUL.
  174. After a successful call to
  175. .IR Brdstr ,
  176. the return value of
  177. .I Blinelen
  178. will be the length of the returned buffer, excluding the NUL.
  179. .PP
  180. .I Bgetc
  181. returns the next character from
  182. .IR bp ,
  183. or a negative value
  184. at end of file.
  185. .I Bungetc
  186. may be called immediately after
  187. .I Bgetc
  188. to allow the same character to be reread.
  189. .PP
  190. .I Bgetrune
  191. calls
  192. .I Bgetc
  193. to read the bytes of the next
  194. .SM UTF
  195. sequence in the input stream and returns the value of the rune
  196. represented by the sequence.
  197. It returns a negative value
  198. at end of file.
  199. .I Bungetrune
  200. may be called immediately after
  201. .I Bgetrune
  202. to allow the same
  203. .SM UTF
  204. sequence to be reread as either bytes or a rune.
  205. .I Bungetc
  206. and
  207. .I Bungetrune
  208. may back up a maximum of five bytes.
  209. .PP
  210. .I Bgetd
  211. uses
  212. .I charstod
  213. (see
  214. .IR atof (2))
  215. and
  216. .I Bgetc
  217. to read the formatted
  218. floating-point number in the input stream,
  219. skipping initial blanks and tabs.
  220. The value is stored in
  221. .BR *d.
  222. .PP
  223. .I Bread
  224. reads
  225. .I nbytes
  226. of data from
  227. .I bp
  228. into memory starting at
  229. .IR addr .
  230. The number of bytes read is returned on success
  231. and a negative value is returned if a read error occurred.
  232. .PP
  233. .I Bseek
  234. applies
  235. .IR seek (2)
  236. to
  237. .IR bp .
  238. It returns the new file offset.
  239. .I Boffset
  240. returns the file offset of the next character to be processed.
  241. .PP
  242. .I Bputc
  243. outputs the low order 8 bits of
  244. .I c
  245. on
  246. .IR bp .
  247. If this causes a
  248. .IR write
  249. to occur and there is an error,
  250. a negative value is returned.
  251. Otherwise, a zero is returned.
  252. .PP
  253. .I Bputrune
  254. calls
  255. .I Bputc
  256. to output the low order
  257. 16 bits of
  258. .I c
  259. as a rune
  260. in
  261. .SM UTF
  262. format
  263. on the output stream.
  264. .PP
  265. .I Bprint
  266. is a buffered interface to
  267. .IR print (2).
  268. If this causes a
  269. .IR write
  270. to occur and there is an error,
  271. a negative value
  272. .RB ( Beof )
  273. is returned.
  274. Otherwise,
  275. .I Bprint
  276. returns zero.
  277. .I Bvprint
  278. does the same except it takes as argument a
  279. .B va_list
  280. parameter, so it can be called within a variadic function.
  281. .PP
  282. .I Bwrite
  283. outputs
  284. .I nbytes
  285. of data starting at
  286. .I addr
  287. to
  288. .IR bp .
  289. If this causes a
  290. .IR write
  291. to occur and there is an error,
  292. a negative value is returned.
  293. Otherwise, the number of bytes written is returned.
  294. .PP
  295. .I Bflush
  296. causes any buffered output associated with
  297. .I bp
  298. to be written.
  299. The return is as for
  300. .IR Bputc .
  301. .I Bflush
  302. is called on
  303. exit for every buffer still open
  304. for writing.
  305. .PP
  306. .I Bbuffered
  307. returns the number of bytes in the buffer.
  308. When reading, this is the number of bytes still available from the last
  309. read on the file; when writing, it is the number of bytes ready to be
  310. written.
  311. .SH SOURCE
  312. .B /sys/src/libbio
  313. .SH SEE ALSO
  314. .IR open (2),
  315. .IR print (2),
  316. .IR exits (2),
  317. .IR utf (6),
  318. .SH DIAGNOSTICS
  319. .I Bio
  320. routines that return integers yield
  321. .B Beof
  322. if
  323. .I bp
  324. is not the descriptor of an open file.
  325. .I Bopen
  326. returns zero if the file cannot be opened in the given mode.
  327. All routines set
  328. .I errstr
  329. on error.
  330. .SH BUGS
  331. .I Brdline
  332. returns an error on strings longer than the buffer associated
  333. with the file
  334. and also if the end-of-file is encountered
  335. before a delimiter.
  336. .I Blinelen
  337. will tell how many characters are available
  338. in these cases.
  339. In the case of a true end-of-file,
  340. .I Blinelen
  341. will return zero.
  342. At the cost of allocating a buffer,
  343. .I Brdstr
  344. sidesteps these issues.
  345. .PP
  346. The data returned by
  347. .I Brdline
  348. may be overwritten by calls to any other
  349. .I bio
  350. routine on the same
  351. .IR bp.