The generic stream pointer. For more info, see stream.c. More...

Inheritance diagram for SprStream:

Collaboration diagram for SprStream:

Data Fields
base::< SprObject >	interface_

const uint8_t *restrict	buf_rptr

uint8_t *restrict	buf_wptr

const uint8_t *spr_readonly	buf_end

unsigned int	buf_size

spr_readonly int	err

spr_readonly int	eof

SprKeySet *	keys

const char *	fname

Protected Member Functions
virtual const uint8_t *	buf_fill (public:SprStream *restrict fd, int min_fill)

virtual uint8_t *	buf_flush (public:SprStream *restrict fd)

virtual size_t	ebuf_read (public:SprStream restrict fd, void restrict buf, size_t size)

virtual int	ebuf_write (public:SprStream restrict fd, const void restrict buf, size_t size)

virtual size_t	read (SprStream restrict fd, void restrict buf, size_t size)

virtual int	write (SprStream restrict fd, const void restrict buf, size_t size)

virtual size_t	skip (SprStream *restrict fd, size_t size)

virtual int	fill (SprStream *restrict fd, int chr, size_t size)

virtual int	switch2read (SprStream *restrict fd)

virtual int	switch2write (SprStream *restrict fd)

virtual off_t	seek (SprStream *restrict fd, off_t offset, int mode)

virtual off_t	tell (SprStream *restrict fd)

virtual int	align (SprStream *restrict fd)

Protected Attributes
uint8_t *	buf_start

unsigned int	flags

int	mode

size_t	rdim2

SprStream_buf_fill	buf_fill

SprStream_buf_flush	buf_flush

SprStream_ebuf_read	ebuf_read

SprStream_ebuf_write	ebuf_write

Detailed Description

The generic stream pointer. For more info, see stream.c.

The basic stream object, i.e. the basic interface to which all stream objects must adhere.

Note

Routines are allowed direct access to the buf_rptr, buf_wptr, buf_end and buf_start fields, hence allowing the implementation of fast IO-routines. When doing so, you must adhere to rules imposed by the constraints on each pointer, i.e.:

On reads, you must check if buf_rptr < buf_end before you access any data, or use SprStream::buf_fill() otherwise (which may fail, e.g. if the stream is in write modus).
On writes you must verify that the pointer is not NULL (the stream is in read modus). Short writes (up till 16 bytes can be performed without first checking w.r.t. buf_end), longer writes will have to check that there is enough space available and if necessary issue a SprStream::buf_flush() operation. At the end of each write operation, a SprStream::buf_flush() operation must be performed if buf_wptr >= buf_end.

Member Function Documentation

virtual const uint8_t* SprStream::buf_fill	(	public:SprStream *restrict	fd,
		int	min_fill
	)

protectedvirtual

Fill the buffer with new data read from the underlaying media starting from the current read position; advance the read position by the number of bytes read. If the buffer contains less than min_fill bytes after the fill operation, a NULL is returned. In that case, fd->buf_rptr is still set according to the amount of data available in the buffer.

Returns: The new fd->buf_rptr on success or NULL if an error occurred.

virtual uint8_t* SprStream::buf_flush ( public:SprStream *restrict fd )

protectedvirtual

Flush the data in the buffer to the underlaying media starting from the current write position; advance the read position by the number of bytes written.

Returns: The new fd->buf_wptr on success or NULL if an error occurred.

Note: fd->err is set in case of an error.; When an error occurs, the data will still be cleared from the write buffer (and thus lost forever).

virtual size_t SprStream::ebuf_read	(	public:SprStream *restrict	fd,
		void *restrict	buf,
		size_t	size
	)

protectedvirtual

Read size bytes directly from the stream fd into the buffer buf (bypassing the read/write buffer) on the condition that the read/write buffer is empty.

Returns: The number of bytes that could not be read (equals 0 if the operation was successful). fd->err (errno) and fd->eof are set in case of an error.

Note: This method is optional
it does not have to be implemented (so check for a NULL pointer before using it)!

virtual int SprStream::ebuf_write	(	public:SprStream *restrict	fd,
		const void *restrict	buf,
		size_t	size
	)

protectedvirtual

Write size bytes directly from the buffer buf to the stream fd (bypassing the read/write buffer) on the condition that the read/write buffer is empty.

Returns: 0 if the operation was successful and -1 otherwise (one or more bytes could not be written). fd->err (errno) is set in the latter case.

Note: This method is optional
it does not have to be implemented (so check for a NULL pointer before using it)!

virtual size_t SprStream::read	(	SprStream *restrict	fd,
		void *restrict	buf,
		size_t	size
	)

protectedvirtual

Read from a stream.
Attempt to read size bytes from stream fd into the buffer buf and advance the read position by the number of bytes actually read.

Returns: Zero if all size bytes could be read successfully and the number of bytes that should still be read in order to have read size bytes otherwise. A non-zero return value does not necessarily indicates an error: on non-blocking devices this could also signal that the requested data is not yet available. If a non-zero value is returned, fd->err and fd->eof will be set to indicate the cause of the problem.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
buf	Buffer to write the data to.
size	Number of bytes to read.

virtual int SprStream::write	(	SprStream *restrict	fd,
		const void *restrict	buf,
		size_t	size
	)

protectedvirtual

Write to a stream.
Attempt to write size bytes from buffer buf to stream fd and advance the write position by the number of bytes actually written.

Returns: 0 if the operation was successful and -1 otherwise (one or more bytes could not be written). fd->err (errno) is set in the latter case.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
buf	Buffer containing the data to write.
size	Number of bytes to write.

virtual size_t SprStream::skip	(	SprStream *restrict	fd,
		size_t	size
	)

protectedvirtual

Skip data from a stream.
Skip size bytes (i.e. read but do not store) from the stream fd.

Returns: Zero if all size bytes could be read successfully and the number of bytes that should still be skipped in order to have skipped size bytes otherwise. A non-zero return value does not necessarily indicates an error: on non-blocking devices this could also signal that the requested data is not yet available. If a non-zero value is returned, fd->err and fd->eof will be set to indicate the cause of the problem.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
size	Number of bytes to skip.

virtual int SprStream::fill	(	SprStream *restrict	fd,
		int	chr,
		size_t	size
	)

protectedvirtual

Attempt to write size times the character chr to stream fd and advance the write position by the number of bytes actually written.

Returns: 0 if the operation was successful and -1 otherwise (one or more bytes could not be written). fd->err (errno) is set in the latter case.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
chr	Character used for filling.
size	Repeat factor.

virtual int SprStream::switch2read ( SprStream *restrict fd )

protectedvirtual

Switch a stream to read mode (if possible).

Returns: 0 on success and -1 on error (stream is write only).

Parameters

fd	Stream object.

virtual int SprStream::switch2write ( SprStream *restrict fd )

protectedvirtual

Switch a stream to write mode (if possible).

Returns: 0 on success and -1 on error (stream is read only).

Parameters

fd	Stream object.

virtual off_t SprStream::seek	(	SprStream *restrict	fd,
		off_t	offset,
		int	mode
	)

protectedvirtual

Reposition read/write stream offset.
Reposition the read/write position of the open stream fd according to the arguments offset and mode. mode can have the following values:

SEEK_SET: set the position to offset bytes after the beginning of the stream, i.e. offset is the requested absolute position.
SEEK_CUR: set the position to its current location plus offset bytes, i.e. relative w.r.t. to the current read/write position.
SEEK_END: set the position to the stream end plus offset bytes, i.e. relative w.r.t. the current end of the stream.

The seek() method allows the read/write position to be set beyond the end of the stream. This does not change the size of the stream. If data is later written at this point, the intermediate gap will be filled with random data (usually with '\0' bytes, but this is not guaranteed).

Returns: The resulting read/write position measured in bytes from the start of the stream or (off_t)-1 if the seek() operation failed. In the latter case, fd->err is set to indicate the cause of the error.

Note: A successful call clears the end-of-file indicator.

Parameters

fd	Stream object.
offset	New position (relative of absolute).
mode	Indicates how offset must be interpreted.

virtual off_t SprStream::tell ( SprStream *restrict fd )

protectedvirtual

Report read/write stream offset.
Report back the current read/write position of the open stream fd.

Returns: The current read/write position or (off_t)-1 if the operation failed. In the latter case, fd->err is set to indicate the cause of the error.

Parameters

fd	Stream object.

virtual int SprStream::align ( SprStream *restrict fd )

protectedvirtual

Align read/write buffers.
Try to align the read/write buffers for optimal access from/to the buffer.

Returns: -1 if there was an error (failed to flush data from the write buffers) and 0 otherwise.

Note: A 0 return value does not mean that the realignment was successfull, it just means that no data was lost in the process of trying to align the data.

Parameters

fd	Stream object.

Field Documentation

base::<SprObject> SprStream::interface_

const uint8_t* restrict SprStream::buf_rptr

The read pointer, i.e. location in the buffer of the next unread byte of data. The read pointer is guaranteed to be larger or equal to buf_end when in write mode.

uint8_t* restrict SprStream::buf_wptr

The write pointer, i.e. location in the buffer of the next byte of data to write to. The write pointer is guaranteed to be NULL if in read mode. The write buffer is also guaranteed to have at least 32 bytes of spill-space beyond the indicated end of the buffer, i.e. buf_end. This allows small writes to simply write and then check if the buffer was full instead of having to check before and after the write (a check after the write is always needed in order to accomodate unbuffered writes).

const uint8_t* spr_readonly SprStream::buf_end

Indicated end of the read/write buffer.

uint8_t* SprStream::buf_start

protected

Start of the read buffer (includes the extra space in front for pushing back bytes; is NULL when in write mode; may change in the future!).

unsigned int SprStream::buf_size

The size of the read/write buffer minus the spill space in front (read-operation) or at the end (write operation).

unsigned int SprStream::flags

protected

Various flags
see SprStreamFlags for more details.

int SprStream::mode

protected

File mode (SPR_STREAM_MODE_BIN, SPR_STREAM_MODE_BINSWAP or SPR_STREAM_MODE_ASCII).

spr_readonly int SprStream::err

The last reported error (errno).

spr_readonly int SprStream::eof

Set when trying to read past the end-of-the file.

size_t SprStream::rdim2

protected

Number of elements to write before a new-line is written in ASCII mode.

SprKeySet* SprStream::keys

Keyset to go with this stream.

const char* SprStream::fname

Indicative name of the file
to be used in (error) messages only.

SprStream_buf_fill SprStream::buf_fill

protected

Quick access pointer for the SprStream::buf_fill() method.

SprStream_buf_flush SprStream::buf_flush

protected

Quick access pointer for the SprStream::buf_flush() method.

SprStream_ebuf_read SprStream::ebuf_read

protected

Quick access pointer for the SprStream::ebuf_read() method.

SprStream_ebuf_write SprStream::ebuf_write

protected

Quick access pointer for the SprStream::ebuf_write() method.

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

Field Documentation