Interchangable file and memory I/O

nxs_stream.h More...


Data Structures
union	nxs_stream_pos
	Holds stream positioning information. More...
Typedefs
typedef struct nxs_stream	nxs_stream
	Structure representing a stream.
Functions
void	nxs_stream_close (nxs_stream *ptr)
	Releases any resources in use by stream ptr and frees the stream object.
size_t	nxs_stream_copy (nxs_stream restrict src, nxs_stream restrict dst, size_t size)
	Copies up to size bytes of data from stream src to stream dst and returns the number of bytes successfully copied.
size_t	nxs_stream_copy_full (nxs_stream restrict src, nxs_stream restrict dst)
	Copies as much data as possible from stream src to stream dst and returns the number of bytes successfully copied.
static nxs_stream *	nxs_stream_create (void)
	Creates and returns a new stream object.
nxs_stream *	nxs_stream_createFromConstMemory (const void *mem, size_t length)
	Creates and returns a new stream object that will operate on up to length bytes starting at mem.
static nxs_stream *	nxs_stream_createFromFile (const char path, const char mode)
	Creates and returns a new stream object that will operate on a file at path.
nxs_stream *	nxs_stream_createFromFP (FILE *fp, bool shouldClose)
	Creates and returns a new stream object that will operate on the file designated by fp.
nxs_stream *	nxs_stream_createFromMemory (void *mem, size_t length, bool autorelease, bool shouldExpand)
	Creates and returns a new stream object that will operate on up to length bytes starting at mem.
static nxs_stream *	nxs_stream_createFromNewMemory (size_t length, bool shouldExpand)
	Creates and returns a new stream object with allocated memory length bytes long.
bool	nxs_stream_eof (const nxs_stream *ptr)
	If there is no more data to be read from stream ptr, returns `true`.
bool	nxs_stream_flush (nxs_stream *ptr)
	Causes any buffered data for stream ptr to be written out.
int	nxs_stream_getc (nxs_stream *ptr)
	Reads and returns the next character from stream ptr as an `unsigned char` converted to an `int`.
char *	nxs_stream_gets (nxs_stream restrict ptr, char restrict str, size_t size)
	Reads up to size bytes into buffer str, or until a newline character is copied, whichever comes first, from stream ptr.
static int	nxs_stream_printf (nxs_stream restrict ptr, const char restrict format,...)
	Writes the formatted output specified by format, and any following arguments, to stream ptr.
int	nxs_stream_putc (nxs_stream *ptr, int c)
	Writes the character c (converted to an `unsigned char`) to stream ptr.
bool	nxs_stream_puts (nxs_stream restrict ptr, const char restrict str)
	Writes the string str to stream ptr.
size_t	nxs_stream_read (nxs_stream restrict ptr, void restrict buffer, size_t size)
	Reads up to size bytes into buffer from stream ptr and returns the number of bytes successfully read.
bool	nxs_stream_seek (nxs_stream restrict ptr, const nxs_stream_pos restrict pos)
	Sets the position of stream ptr to the value of the object pointed to by pos.
bool	nxs_stream_seekEnd (nxs_stream *ptr)
	Sets the position of stream ptr to the end of the data.
bool	nxs_stream_seekStart (nxs_stream *ptr)
	Sets the position of stream ptr to the beginning of the data.
bool	nxs_stream_tell (const nxs_stream restrict ptr, nxs_stream_pos restrict pos)
	Stores the current position of stream ptr in the object pointed to by pos.
int	nxs_stream_ungetc (nxs_stream *ptr, int c)
	Pushes the character c (converted to an `unsigned char`) back onto input stream ptr.
int	nxs_stream_vprintf (nxs_stream restrict ptr, const char restrict format, va_list arg)
	Writes the formatted output specified by format, and the arguments referenced by arg, to stream ptr.
size_t	nxs_stream_write (nxs_stream restrict ptr, const void restrict buffer, size_t size)
	Writes up to size bytes to stream ptr from buffer and returns the number of bytes successfully written.

Detailed Description

nxs_stream.h

Typedef Documentation

typedef struct nxs_stream nxs_stream

Structure representing a stream.

There is no need to ever create an object of this type.

Function Documentation

void nxs_stream_close ( nxs_stream * ptr )

Releases any resources in use by stream ptr and frees the stream object.

size_t nxs_stream_copy	(	nxs_stream *restrict	src,
		nxs_stream *restrict	dst,
		size_t	size
	)

Copies up to size bytes of data from stream src to stream dst and returns the number of bytes successfully copied.

A number smaller than size may be returned if end-of-file is encountered or an error occurs.

See also:: nxs_stream_copy_full

size_t nxs_stream_copy_full	(	nxs_stream *restrict	src,
		nxs_stream *restrict	dst
	)

Copies as much data as possible from stream src to stream dst and returns the number of bytes successfully copied.

Copying may stop before end-of-file if an error occurs.

See also:: nxs_stream_copy

static nxs_stream * nxs_stream_create ( void ) [inline, static]

Creates and returns a new stream object.

Write operations to the stream will allocate memory as needed. If memory could not be allocated, NULL is returned.

See also:: nxs_stream_close nxs_stream_createFromNewMemory

nxs_stream* nxs_stream_createFromConstMemory	(	const void *	mem,
		size_t	length
	)

Creates and returns a new stream object that will operate on up to length bytes starting at mem.

Any attempted write operations on the stream will fail. If memory could not be allocated, NULL is returned.

See also:: nxs_stream_close nxs_stream_createFromMemory

static nxs_stream * nxs_stream_createFromFile	(	const char *	path,
		const char *	mode
	)			`[inline, static]`

Creates and returns a new stream object that will operate on a file at path.

Both path and mode are passed directly to fopen(). The file will be closed when the stream is. If a file at path could not be opened, NULL is returned.

See also:: nxs_stream_close nxs_stream_createFromFP

nxs_stream* nxs_stream_createFromFP	(	FILE *	fp,
		bool	shouldClose
	)

Creates and returns a new stream object that will operate on the file designated by fp.

If shouldClose is true, the file will be closed when the stream is. If fp is NULL or memory could not be allocated, NULL is returned.

See also:: nxs_stream_close nxs_stream_createFromFile

nxs_stream* nxs_stream_createFromMemory	(	void *	mem,
		size_t	length,
		bool	autorelease,
		bool	shouldExpand
	)

Creates and returns a new stream object that will operate on up to length bytes starting at mem.

If autorelease is true, mem will be freed when the stream is closed. If shouldExpand is true (which should only happen when autorelease is as well), memory will be reallocated as needed (invalidating mem). If memory could not be allocated, NULL is returned.

See also:: nxs_stream_close nxs_stream_createFromConstMemory

static nxs_stream * nxs_stream_createFromNewMemory	(	size_t	length,
		bool	shouldExpand
	)			`[inline, static]`

Creates and returns a new stream object with allocated memory length bytes long.

If shouldExpand is true, memory will be reallocated as needed. If memory could not be allocated, NULL is returned.

See also:: nxs_stream_close nxs_stream_create

bool nxs_stream_eof ( const nxs_stream * ptr )

If there is no more data to be read from stream ptr, returns true.

If this function returns false and read operations return a short byte count or EOF, a stream error has occurred instead.

bool nxs_stream_flush ( nxs_stream * ptr )

Causes any buffered data for stream ptr to be written out.

If the last operation on stream ptr was input, the behavior of this function is undefined. If a write error occurs, false is returned.

int nxs_stream_getc ( nxs_stream * ptr )

Reads and returns the next character from stream ptr as an unsigned char converted to an int.

If a read error occurs or there are no more characters to be read, EOF is returned.

char* nxs_stream_gets	(	nxs_stream *restrict	ptr,
		char *restrict	str,
		size_t	size
	)

Reads up to size bytes into buffer str, or until a newline character is copied, whichever comes first, from stream ptr.

Returns str on success. If a read error occurs or there is no data to be read, NULL is returned.

static int nxs_stream_printf	(	nxs_stream *restrict	ptr,
		const char *restrict	format,
			...
	)			`[inline, static]`

Writes the formatted output specified by format, and any following arguments, to stream ptr.

See fprintf() documentation for information on how to use format strings. Returns the number of characters successfully written. If an error occurs, a negative value is returned.

int nxs_stream_putc	(	nxs_stream *	ptr,
		int	c
	)

Writes the character c (converted to an unsigned char) to stream ptr.

Returns c on success. If a write error occurs or the value of c is EOF, EOF is returned.

bool nxs_stream_puts	(	nxs_stream *restrict	ptr,
		const char *restrict	str
	)

Writes the string str to stream ptr.

The terminating NUL character of str is not written. If a write error occurs, false is returned.

size_t nxs_stream_read	(	nxs_stream *restrict	ptr,
		void *restrict	buffer,
		size_t	size
	)

Reads up to size bytes into buffer from stream ptr and returns the number of bytes successfully read.

A number smaller than size may be returned if end-of-file is encountered or an error occurs.

bool nxs_stream_seek	(	nxs_stream *restrict	ptr,
		const nxs_stream_pos *restrict	pos
	)

Sets the position of stream ptr to the value of the object pointed to by pos.

The object pointed to by pos should be a value obtained from an earlier successful call to nxs_stream_tell(). If a read or write error occurs, false is returned. On success, any effects of the nxs_stream_ungetc() function are undone.

See also:: nxs_stream_seekStart nxs_stream_seekEnd

bool nxs_stream_seekEnd ( nxs_stream * ptr )

Sets the position of stream ptr to the end of the data.

If a read or write error occurs, false is returned. On success, any effects of the nxs_stream_ungetc() function are undone.

See also:: nxs_stream_seek nxs_stream_seekStart

bool nxs_stream_seekStart ( nxs_stream * ptr )

Sets the position of stream ptr to the beginning of the data.

If a read or write error occurs, false is returned. On success, any effects of the nxs_stream_ungetc() function are undone.

See also:: nxs_stream_seek nxs_stream_seekEnd

bool nxs_stream_tell	(	const nxs_stream *restrict	ptr,
		nxs_stream_pos *restrict	pos
	)

Stores the current position of stream ptr in the object pointed to by pos.

If an error occurs, false is returned.

See also:: nxs_stream_seek

int nxs_stream_ungetc	(	nxs_stream *	ptr,
		int	c
	)

Pushes the character c (converted to an unsigned char) back onto input stream ptr.

Pushed-back characters will be returned by reads in the reverse order of their pushing. A successful intervening call to nxs_stream_seek(), nxs_stream_seekEnd(), or nxs_stream_seekStart() discards all pushed-back characters. The storage corresponding to stream ptr is unchanged. Returns c on success. If an error occurs or the value of c is EOF, EOF is returned.

int nxs_stream_vprintf	(	nxs_stream *restrict	ptr,
		const char *restrict	format,
		va_list	arg
	)

Writes the formatted output specified by format, and the arguments referenced by arg, to stream ptr.

See vfprintf() documentation for information on how to use format strings. Returns the number of characters successfully written. If an error occurs, a negative value is returned.

size_t nxs_stream_write	(	nxs_stream *restrict	ptr,
		const void *restrict	buffer,
		size_t	size
	)

Writes up to size bytes to stream ptr from buffer and returns the number of bytes successfully written.

A number smaller than size may be returned if an error occurs.

Generated on Thu Dec 20 13:42:46 2007 for NXS Toolkit by

1.5.4

Interchangable file and memory I/O

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation