ossp-pkg/sio/BRAINSTORM/postfix-vstream.txt
1.1
VSTREAM(3) VSTREAM(3)
NNAAMMEE
vstream - light-weight buffered I/O package
SSYYNNOOPPSSIISS
#include <vstream.h>
VSTREAM *vstream_fopen(path, flags, mode)
char *path;
int flags;
int mode;
VSTREAM *vstream_fdopen(fd, flags)
int fd;
int flags;
int vstream_fclose(stream)
VSTREAM *stream;
VSTREAM *vstream_printf(format, ...)
char *format;
VSTREAM *vstream_fprintf(stream, format, ...)
VSTREAM *stream;
char *format;
int VSTREAM_GETC(stream)
VSTREAM *stream;
int VSTREAM_PUTC(ch, stream)
int ch;
int VSTREAM_GETCHAR(void)
int VSTREAM_PUTCHAR(ch)
int ch;
int vstream_ungetc(stream, ch)
VSTREAM *stream;
int ch;
int vstream_fputs(str, stream)
char *str;
VSTREAM *stream;
long vstream_ftell(stream)
VSTREAM *stream;
long vstream_fseek(stream, offset, whence)
VSTREAM *stream;
long offset;
int whence;
int vstream_fflush(stream)
VSTREAM *stream;
1
VSTREAM(3) VSTREAM(3)
int vstream_fread(stream, buf, len)
VSTREAM *stream;
char *buf;
int len;
int vstream_fwrite(stream, buf, len)
VSTREAM *stream;
char *buf;
int len;
void vstream_control(stream, name, ...)
VSTREAM *stream;
int name;
int vstream_fileno(stream)
VSTREAM *stream;
int vstream_ferror(stream)
VSTREAM *stream;
int vstream_feof(stream)
VSTREAM *stream;
int vstream_clearerr(stream)
VSTREAM *stream;
char *VSTREAM_PATH(stream)
VSTREAM *stream;
char *vstream_vfprintf(vp, format, ap)
char *format;
va_list *ap;
int vstream_peek(stream)
VSTREAM *stream;
DDEESSCCRRIIPPTTIIOONN
The _v_s_t_r_e_a_m module implements light-weight buffered I/O
similar to the standard I/O routines.
The interface is implemented in terms of VSTREAM structure
pointers, also called streams. For convenience, three
streams are predefined: VSTREAM_IN, VSTREAM_OUT, and
VSTREAM_ERR. These streams are connected to the standard
input, output and error file descriptors, respectively.
Although the interface is patterned after the standard I/O
library, there are some major differences:
+o File descriptors are not limited to the range
0..255. This was reason #1 to write these routines
in the first place.
+o The application can switch between reading and
2
VSTREAM(3) VSTREAM(3)
writing on the same stream without having to per-
form a flush or seek operation, and can change
write position without having to flush. This was
reason #2. Upon position or direction change,
unread input is discarded, and unwritten output is
flushed automatically. Exception: with double-
buffered streams, unread input is not discarded
upon change of I/O direction, and output flushing
is delayed until the read buffer must be refilled.
+o A bidirectional stream can read and write with the
same buffer and file descriptor, or it can have
separate read/write buffers and/or file descrip-
tors.
+o No automatic flushing of VSTREAM_OUT upon program
exit, or of VSTREAM_ERR at any time. No unbuffered
or line buffered modes. This functionality may be
added when it is really needed.
vstream_fopen() opens the named file and associates a
buffered stream with it. The _p_a_t_h, _f_l_a_g_s and _m_o_d_e argu-
ments are passed on to the open(2) routine. The result is
a null pointer in case of problems. The _p_a_t_h argument is
copied and can be looked up with VSTREAM_PATH().
vstream_fdopen() takes an open file and associates a
buffered stream with it. The _f_l_a_g_s argument specifies how
the file was opened. vstream_fdopen() either succeeds or
never returns.
vstream_fclose() closes the named buffered stream. The
result is 0 in case of success, VSTREAM_EOF in case of
problems.
vstream_fprintf() formats its arguments according to the
_f_o_r_m_a_t argument and writes the result to the named stream.
The result is the stream argument. It understands the s,
c, d, u, o, x, X, e, f and g format types, the l modifier,
field width and precision, sign, and padding with zeros or
spaces. In addition, vstream_fprintf() recognizes the %m
format specifier and expands it to the error message cor-
responding to the current value of the global _e_r_r_n_o vari-
able.
vstream_printf() performs formatted output to the standard
output stream.
VSTREAM_GETC() reads the next character from the named
stream. The result is VSTREAM_EOF when end-of-file is
reached or if a read error was detected. VSTREAM_GETC() is
an unsafe macro that evaluates some arguments more than
once.
3
VSTREAM(3) VSTREAM(3)
VSTREAM_GETCHAR() is an alias for
VSTREAM_GETC(VSTREAM_IN).
VSTREAM_PUTC() appends the specified character to the
specified stream. The result is the stored character, or
VSTREAM_EOF in case of problems. VSTREAM_PUTC() is an
unsafe macro that evaluates some arguments more than once.
VSTREAM_PUTCHAR(c) is an alias for VSTREAM_PUTC(c,
VSTREAM_OUT).
vstream_unget() pushes back a character onto the specified
stream and returns the character, or VSTREAM_EOF in case
of problems. It is an error to push back before reading
(or immediately after changing the stream offset via
vstream_fseek()). Upon successful return, vstream_unget()
clears the end-of-file stream flag.
vstream_fputs() appends the given null-terminated string
to the specified buffered stream. The result is 0 in case
of success, VSTREAM_EOF in case of problems.
vstream_ftell() returns the file offset for the specified
stream, -1 if the stream is connected to a non-seekable
file.
vstream_fseek() changes the file position for the next
read or write operation. Unwritten output is flushed. With
unidirectional streams, unread input is discarded. The
_o_f_f_s_e_t argument specifies the file position from the
beginning of the file (_w_h_e_n_c_e is SEEK_SET), from the cur-
rent file position (_w_h_e_n_c_e is SEEK_CUR), or from the file
end (SEEK_END). The result value is the file offset from
the beginning of the file, -1 in case of problems.
vstream_fflush() flushes unwritten data to a file that was
opened in read-write or write-only mode. vstream_fflush()
returns 0 in case of success, VSTREAM_EOF in case of prob-
lems. It is an error to flush a read-only stream.
vstream_fread() and vstream_fwrite() perform unformatted
I/O on the named stream. The result value is the number of
bytes transferred. A short count is returned in case of
end-of-file or error conditions.
vstream_control() allows the user to fine tune the behav-
ior of the specified stream. The arguments are a list of
(name, value) pairs, terminated with VSTREAM_CTL_END. The
following lists the names and the types of the correspond-
ing value arguments.
VSTREAM_CTL_READ_FN (int (*)(int, void *, unsigned))
The argument specifies an alternative for the
read(2) function, for example, a read function that
4
VSTREAM(3) VSTREAM(3)
enforces a time limit.
VSTREAM_CTL_WRITE_FN (int (*)(int, void *, unsigned))
The argument specifies an alternative for the
write(2) function, for example, a write function
that enforces a time limit.
VSTREAM_CTL_PATH (char *)
Updates the stored pathname of the specified
stream. The pathname is copied.
VSTREAM_CTL_DOUBLE (no value)
Use separate buffers for reading and for writing.
This prevents unread input from being discarded
upon change of I/O direction.
VSTREAM_CTL_READ_FD (int)
The argument specifies the file descriptor to be
used for reading. This feature is limited to dou-
ble-buffered streams, and makes the stream non-
seekable.
VSTREAM_CTL_WRITE_FD (int)
The argument specifies the file descriptor to be
used for writing. This feature is limited to dou-
ble-buffered streams, and makes the stream non-
seekable.
VSTREAM_CTL_WAITPID_FN (int (*)(pid_t, WAIT_STATUS_T *,
int))
A pointer to function that behaves like waitpid().
This information is used by the vstream_pclose()
routine.
vstream_fileno() gives access to the file handle associ-
ated with a buffered stream. With streams that have sepa-
rate read/write file descriptors, the result is the cur-
rent descriptor.
VSTREAM_PATH() is an unsafe macro that returns the name
stored with vstream_fopen() or with vstream_control(). The
macro is unsafe because it evaluates some arguments more
than once.
vstream_ferror() (vstream_feof()) returns non-zero when a
previous operation on the specified stream caused an error
(end-of-file) condition.
vstream_clearerr() resets the error and end-of-file indi-
cation of specified stream, and returns no useful result.
vstream_vfprintf() provides an alternate interface for
formatting an argument list according to a format string.
5
VSTREAM(3) VSTREAM(3)
vstream_peek() returns the number of characters that can
be read from the named stream without refilling the read
buffer.
DDIIAAGGNNOOSSTTIICCSS
Panics: interface violations. Fatal errors: out of memory.
SSEEEE AALLSSOO
vbuf_print(3) formatting engine
BBUUGGSS
Should use mmap() on reasonable systems.
LLIICCEENNSSEE
The Secure Mailer license must be distributed with this
software.
AAUUTTHHOORR((SS))
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
6
