substdio.3

NAME

substdio - the Sub-Standard Input/Output Library

SYNTAX

#include <substdio.h>

void substdio_fdbuf(&s,op,fd,buf,len);

int substdio_fileno(&s);

substdio s;
int (*op)();
int fd;
char *buf;
int len;

DESCRIPTION

substdio is the Sub-Standard I/O Library. substdio contains only a few of the features of stdio; it is a fast, lightweight, low-level library, suitable for use as a component of higher-level I/O libraries.

The point of substdio is to provide buffered I/O. The basic object in substdio is the substdio structure; a substdio variable stores an operation, a descriptor, and a pointer into a buffer of some nonzero length. The substdio operations read data from the buffer, filling the buffer as necessary using the operation on the descriptor, or write data to the buffer, flushing the buffer as necessary using the operation on the descriptor. Input and output operations cannot be mixed.

substdio_fdbuf initializes a substdiovariable**.** The operation is op. The descriptor is fd. The buffer is buf, an array of len chars.

op will be called as op(fd,x,n). Here x is a pointer to an array of characters of length n; op must read some characters from fd to that array, or write some characters to fd from that array. The return value from op must be the number of characters read or written. 0 characters read means end of input; 0 characters written means that the write operation should be tried again immediately. On error, op must return -1, setting errno appropriately, without reading or writing anything. Most errors are returned directly to the substdio caller, but an error of error_intr means that the operation should be tried again immediately.

There is a SUBSTDIO_FDBUF macro that can be used to statically initialize a substdio variable:

   substdio s = SUBSTDIO_FDBUF(op,fd,buf,len);

substdio_fileno returns the descriptor for an initialized substdio variable.

SEE ALSO

substdio_in(3), substdio_out(3), substdio_copy(3), error(3)