| <head> |
| <title>bio(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>BIO(3)</b><td align=right><b>BIO(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Bopen, Bfdopen, 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<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h><br> |
| #include <libc.h><br> |
| #include <bio.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>Biobuf* Bopen(char *file, int mode) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>Biobuf* Bfdopen(int fd, int mode) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Binit(Biobuf *bp, int fd, int mode) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size) |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bterm(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bprint(Biobufhdr *bp, char *format, ...) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bvprint(Biobufhdr *bp, char *format, va_list arglist); |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void* Brdline(Biobufhdr *bp, int delim) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>char* Brdstr(Biobufhdr *bp, int delim, int nulldelim) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Blinelen(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>vlong Boffset(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bfildes(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bgetc(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>long Bgetrune(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bgetd(Biobufhdr *bp, double *d) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bungetc(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bungetrune(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>vlong Bseek(Biobufhdr *bp, vlong n, int type) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bputc(Biobufhdr *bp, int c) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bputrune(Biobufhdr *bp, long c) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>long Bread(Biobufhdr *bp, void *addr, long nbytes) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>long Bwrite(Biobufhdr *bp, void *addr, long nbytes) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bflush(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int Bbuffered(Biobufhdr *bp) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| These routines implement fast buffered I/O. I/O on different file |
| descriptors is independent. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bopen</i> opens <i>file</i> for mode <tt><font size=+1>OREAD</font></tt> or creates for mode <tt><font size=+1>OWRITE</font></tt>. It |
| calls <a href="../man3/malloc.html"><i>malloc</i>(3)</a> to allocate a buffer. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bfdopen</i> allocates a buffer for the already-open file descriptor |
| <i>fd</i> for mode <tt><font size=+1>OREAD</font></tt> or <tt><font size=+1>OWRITE</font></tt>. It calls <a href="../man3/malloc.html"><i>malloc</i>(3)</a> to allocate a |
| buffer. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Binit</i> initializes a standard size buffer, type <i>Biobuf</i>, with the |
| open file descriptor passed in by the user. <i>Binits</i> initializes |
| a non-standard size buffer, type <i>Biobufhdr</i>, with the open file |
| descriptor, buffer area, and buffer size passed in by the user. |
| <i>Biobuf</i> and <i>Biobufhdr</i> are related by the declaration: |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>typedef struct Biobuf Biobuf;<br> |
| struct Biobuf<br> |
| {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Biobufhdr;<br> |
| uchar b[Bungetsize+Bsize];<br> |
| |
| </table> |
| };<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| Arguments of types pointer to Biobuf and pointer to Biobufhdr |
| can be used interchangeably in the following routines. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bopen</i>, <i>Binit</i>, or <i>Binits</i> should be called before any of the other |
| routines on that buffer. <i>Bfildes</i> returns the integer file descriptor |
| of the associated open file. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bterm</i> flushes the buffer for <i>bp</i>. If the buffer was allocated by |
| <i>Bopen</i>, the buffer is <i>freed</i> and the file is closed. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Brdline</i> reads a string from the file associated with <i>bp</i> up to |
| and including the first <i>delim</i> character. The delimiter character |
| at the end of the line is not altered. <i>Brdline</i> returns a pointer |
| to the start of the line or <tt><font size=+1>0</font></tt> on end-of-file or read error. <i>Blinelen</i> |
| returns the length (including the delimiter) of the most recent |
| string |
| returned by <i>Brdline</i>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Brdstr</i> returns a <a href="../man3/malloc.html"><i>malloc</i>(3)</a>-allocated buffer containing the next |
| line of input delimited by <i>delim</i>, terminated by a NUL (0) byte. |
| Unlike <i>Brdline</i>, which returns when its buffer is full even if |
| no delimiter has been found, <i>Brdstr</i> will return an arbitrarily |
| long line in a single call. If <i>nulldelim</i> is set, the terminal |
| delimiter will be |
| overwritten with a NUL. After a successful call to <i>Brdstr</i>, the |
| return value of <i>Blinelen</i> will be the length of the returned buffer, |
| excluding the NUL. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bgetc</i> returns the next character from <i>bp</i>, or a negative value |
| at end of file. <i>Bungetc</i> may be called immediately after <i>Bgetc</i> |
| to allow the same character to be reread. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bgetrune</i> calls <i>Bgetc</i> to read the bytes of the next UTF sequence |
| in the input stream and returns the value of the rune represented |
| by the sequence. It returns a negative value at end of file. <i>Bungetrune</i> |
| may be called immediately after <i>Bgetrune</i> to allow the same UTF |
| sequence to be reread as either bytes or a rune. |
| <i>Bungetc</i> and <i>Bungetrune</i> may back up a maximum of five bytes. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bgetd</i> uses <i>charstod</i> (see <a href="../man3/atof.html"><i>atof</i>(3)</a>) and <i>Bgetc</i> to read the formatted |
| floating-point number in the input stream, skipping initial blanks |
| and tabs. The value is stored in <tt><font size=+1>*d. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <i>Bread</i> reads <i>nbytes</i> of data from <i>bp</i> into memory starting at <i>addr</i>. |
| The number of bytes read is returned on success and a negative |
| value is returned if a read error occurred. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bseek</i> applies <a href="../man3/seek.html"><i>seek</i>(3)</a> to <i>bp</i>. It returns the new file offset. <i>Boffset</i> |
| returns the file offset of the next character to be processed. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bputc</i> outputs the low order 8 bits of <i>c</i> on <i>bp</i>. If this causes |
| a <i>write</i> to occur and there is an error, a negative value is returned. |
| Otherwise, a zero is returned. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bputrune</i> calls <i>Bputc</i> to output the low order 16 bits of <i>c</i> as a |
| rune in UTF format on the output stream. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bprint</i> is a buffered interface to <a href="../man3/print.html"><i>print</i>(3)</a>. If this causes a <i>write</i> |
| to occur and there is an error, a negative value (<tt><font size=+1>Beof</font></tt>) is returned. |
| Otherwise, the number of bytes output is returned. <i>Bvprint</i> does |
| the same except it takes as argument a <tt><font size=+1>va_list</font></tt> parameter, so it |
| can be called within a variadic function. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bwrite</i> outputs <i>nbytes</i> of data starting at <i>addr</i> to <i>bp</i>. If this |
| causes a <i>write</i> to occur and there is an error, a negative value |
| is returned. Otherwise, the number of bytes written is returned. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bflush</i> causes any buffered output associated with <i>bp</i> to be written. |
| The return is as for <i>Bputc</i>. <i>Bflush</i> is called on exit for every |
| buffer still open for writing. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Bbuffered</i> returns the number of bytes in the buffer. When reading, |
| this is the number of bytes still available from the last read |
| on the file; when writing, it is the number of bytes ready to |
| be written.<br> |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/libbio<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man3/open.html"><i>open</i>(3)</a>, <a href="../man3/print.html"><i>print</i>(3)</a>, <a href="../man3/exits.html"><i>exits</i>(3)</a>, <a href="../man7/utf.html"><i>utf</i>(7)</a>,<br> |
| |
| </table> |
| <p><font size=+1><b>DIAGNOSTICS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Bio</i> routines that return integers yield <tt><font size=+1>Beof</font></tt> if <i>bp</i> is not the |
| descriptor of an open file. <i>Bopen</i> returns zero if the file cannot |
| be opened in the given mode. All routines set <i>errstr</i> on error.<br> |
| |
| </table> |
| <p><font size=+1><b>BUGS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Brdline</i> returns an error on strings longer than the buffer associated |
| with the file and also if the end-of-file is encountered before |
| a delimiter. <i>Blinelen</i> will tell how many characters are available |
| in these cases. In the case of a true end-of-file, <i>Blinelen</i> will |
| return zero. At the cost of allocating a buffer, <i>Brdstr</i> sidesteps |
| these issues. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The data returned by <i>Brdline</i> may be overwritten by calls to any |
| other <i>bio</i> routine on the same <i>bp.</i><br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
