Next: , Previous: bpipe_iochannel_delete, Up: Internal Functions


A.5.16 bpipe_iochannel_fgetrn

Read a record from an I/O channel.

Synopsis

     #include <bpipe/bpipe.h>
     
     
     
char *bpipe_iochannel_fgetrn( char **buf, size_t *buf_len, IOchannel *ioc );

Parameters

char **buf
a two element array of pointers which will be set to point to the the buffers used to store the input string. the buffers are dyamically re-allocated, hence the need for the address of the user-supplied pointer. buf[0] should be NULL upon the first call with it.
size_t *buf_len
the length of the buffers
IOchannel *ioc
the channel from which to read the data

Description

This routine reads data from an I/O channel until a newline character is read or the channel returns EOF. It truncates the trailing newline character. It dynamically resizes its buffers to encompass the data, and can thus read any length record (up to the memory limits on the machine).

The calling procedure must provide a pointer to the buffer space and an integer of type size_t which will record the length of the buffer. Upon first calling bpipe_iochannel_fgetrn, the buffer pointer should be set to NULL. Note that the addresses of these variables are passed to bpipe_iochannel_fgetrn.

Returns

It returns NULL upon end of file, else a pointer to the input buffer. Upon error it returns NULL and sets bpipe_errno.

Errors

Upon error bpipe_errno is set to one of the following errors:

BPENOMEM
a memory allocation failed