VSTREAM(3) VSTREAM(3) NNAAMMEE vstream - light-weight buffered I/O package SSYYNNOOPPSSIISS #include 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