294 lines
15 KiB
HTML
294 lines
15 KiB
HTML
|
<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>
|