IOFENDER(3) OpenBSD Programmer's Manual IOFENDER(3) NAME iofender - Low impact I/O library SYNOPSIS #include #include #include typedef ssize_t (*ior_handler)(int fd, void *buf, size_t len); typedef ssize_t (*iow_handler)(int fd, const void *buf, size_t len); Buffer manipulation routines iof_t * iof_new(void); iof_t * iof_new_embrace(struct iovec *iov); iof_t * iof_free(iof_t *iof); struct iovec * iof_disown(iof_t *iof); struct iovec * iof_pullup(iof_t *iof); ssize_t iof_readfd(iof_t *iof, int fd, size_t len, ior_handler ior); ssize_t iof_writefd(iof_t *iof, int fd, ssize_t len, iow_handler iow); ssize_t iof_read(iof_t *iof, void *buf, ssize_t len); ssize_t iof_write(iof_t *iof, const void *buf, size_t len); off_t iof_seek(iof_t *iof, off_t off, int whence); ssize_t iof_truncate(iof_t *iof, off_t off, int whence); size_t iof_len(iof_t *iof); Auxiliary routines ssize_t ior_readn(int fd, void *buf, size_t len); ssize_t iow_writen(int fd, const void *buf, size_t len); DESCRIPTION iofender provides a simple and efficient binary buffer interface that is independent of the backstore used. The interface is much like the tradi- tional file access interface; iofender buffers expand as needed, and an offset is kept for determining where in the buffer operations are applied to. iofender buffers are described by: typedef struct iof { size_t off; /* offset into data */ size_t len; /* total length of data */ void *iovq; } iof_t; Note that iof_t are meant to be opaque, and the fields it contains are not meant to be accessed directly. Buffer manipulation routines iop_new() creates a new iofender buffer. It returns NULL on failure. iop_new_embrace() creates a new iofender buffer. In addition, it uses the passed iov to initialize the buffer. It does not copy this buffer, but rather use it directly, hence the the caller passes over control of the buffer to iofender with this call. iop_new_embrace() returns NULL on failure. iof_free() deallocates all memory and state associated with buffer iof. iof_pullup() arranges the buffer iof so that all associated memory is in a continuous region of memory. It then returns a struct iovec * buffer referring to this area of memory. Note that this memory area is not valid across other iofender buffer manipulations on iof. A return value of NULL indicate failure. iof_disown() disowns the buffer iof; a buffer in the form of a struct iovec * is returned. This buffer references a continuous area of memory with the contents of iof. Additionally, all state associated with iof is deallocated. This allows for the caller to retrieve the buffer contents while destroying the iof. A return value of NULL indicates failure iof_readfd() reads len bytes from the file descriptor fd using the IO handler ior_handler into iof starting at the current offset. It returns how many bytes were read; the offset is incremented by the same value. A negative return value indicates a failure, while a return value of 0 in- dicates an EOF. iof_writefd() writes len bytes of data from iof starting at the current offset to the file descriptor fd using ior_handler. It returns how many bytes were written; the offset is consequently advanced to the new posi- tion. A negative return value indicates a failure. If len is set to IOF_WRITE_ALL then all remaining data in the buffer is written. iof_read() reads len bytes of data from iof into buf. A negative return value indicates failure. iof_write() writes len bytes of data from buf into iof. A negative return value indicates failure. iof_seek() changes the current offset of iof. The offset off is inter- preted differently depending on the value of whence. Whence can be one of the following: #define SEEK_SET 0 /* set offset to offset */ #define SEEK_CUR 1 /* set offset to current plus offset */ #define SEEK_END 2 /* set offset to EOF plus offset */ iof_seek() returns the resulting offset on success and -1 on failure. iof_truncate() truncates the buffer iof to the offset off which is inter- preted depending on the value of whence which can be one of the following values; #define TRUNC_SET SEEK_SET /* truncate to offset */ #define TRUNC_CUR SEEK_CUR /* truncate to current plug offset */ iof_truncate() returns the new length of the buffer, or -1 on failure. iof_len() return the current lenght of the buffer iof. Auxiliary routines ior_readn() is meant as an alternative for the ior_handler argument in iof_readfd(). ior_readn() guarantees that the specified number of bytes are read unless an error occurs, in which case an appropriate error is returned. iow_writen() is meant as an alternative for the iow_handler argument in iof_writefd(). iow_writen() gurantees that the specified number of bytes are written unless an error occurs, in which case an appropriate error is returned. RETURN VALUES iof_new() and iof_new_embrace() returns a pointer to a new iof_t buffer, and NULL if there is an error. iof_free() returns NULL. iof_disown() and iof_pullup() returns a pointer to a new struct iovec buffer, and NULL on failure. iof_readfd() and iof_writefd() returns the number of bytes read or writ- ten. Additionally, in the case of iof_readfd() returns 0, an EOF has been encountered. Negative values indicate failure, and are dependent of the passed ior_handler or iow_handler. iof_read() and iof_write() returns the number of bytes read or written, or -1 on failure. iof_seek() returns the new offset into the buffer, or -1 on failure. iof_truncate() returns the new length of the buffer. iof_len() returns the current length of the buffer. EXAMPLES Read from stdin until EOF, and then echo the data to stdout. iof_t *iof; ssize_t ret; ... if ((iof = iof_new()) == NULL) errx(1, "iof_new()"); while ((ret = iof_readfd(iof, fileno(stdin), 8, read)) > 0); if (ret != 0) errx(1, "iof_readfd()"); iof_seek(iof, SEEK_SET, 0); if (iof_writefd(iof, fileno(stdout), IOF_WRITE_ALL, iow_writen) < 0) errx(1, "iof_writefd"); SEE ALSO read(2) and write(2) AUTHOR The iofender library has been written by Marius Aamodt Eriksen OpenBSD 3.1 August 21, 2002 4