20.3 Lstream Functions

Function: Lstream * Lstream_new (Lstream_implementation *imp, const char *mode)

Allocate and return a new Lstream. This function is not really meant to be called directly; rather, each stream type should provide its own stream creation function, which creates the stream and does any other necessary creation stuff (e.g. opening a file).

Function: void Lstream_set_buffering (Lstream *lstr, Lstream_buffering buffering, int buffering_size)

Change the buffering of a stream. See lstream.h. By default the buffering is STREAM_BLOCK_BUFFERED.

Function: int Lstream_flush (Lstream *lstr)

Flush out any pending unwritten data in the stream. Clear any buffered input data. Returns 0 on success, -1 on error.

Macro: int Lstream_putc (Lstream *stream, int c)

Write out one byte to the stream. This is a macro and so it is very efficient. The c argument is only evaluated once but the stream argument is evaluated more than once. Returns 0 on success, -1 on error.

Macro: int Lstream_getc (Lstream *stream)

Read one byte from the stream. This is a macro and so it is very efficient. The stream argument is evaluated more than once. Return value is -1 for EOF or error.

Macro: void Lstream_ungetc (Lstream *stream, int c)

Push one byte back onto the input queue. This will be the next byte read from the stream. Any number of bytes can be pushed back and will be read in the reverse order they were pushed back—most recent first. (This is necessary for consistency—if there are a number of bytes that have been unread and I read and unread a byte, it needs to be the first to be read again.) This is a macro and so it is very efficient. The c argument is only evaluated once but the stream argument is evaluated more than once.

Function: int Lstream_fputc (Lstream *stream, int c)

Function: int Lstream_fgetc (Lstream *stream)

Function: void Lstream_fungetc (Lstream *stream, int c)

Function equivalents of the above macros.

Function: ssize_t Lstream_read (Lstream *stream, void *data, size_t size)

Read size bytes of data from the stream. Return the number of bytes read. 0 means EOF. -1 means an error occurred and no bytes were read.

Function: ssize_t Lstream_write (Lstream *stream, void *data, size_t size)

Write size bytes of data to the stream. Return the number of bytes written. -1 means an error occurred and no bytes were written.

Function: void Lstream_unread (Lstream *stream, void *data, size_t size)

Push back size bytes of data onto the input queue. The next call to Lstream_read() with the same size will read the same bytes back. Note that this will be the case even if there is other pending unread data.

Function: int Lstream_close (Lstream *stream)

Close the stream. All data will be flushed out.

Function: void Lstream_reopen (Lstream *stream)

Reopen a closed stream. This enables I/O on it again. This is not meant to be called except from a wrapper routine that reinitializes variables and such—the close routine may well have freed some necessary storage structures, for example.

Function: void Lstream_rewind (Lstream *stream)

Rewind the stream to the beginning.