I/O streams. More...

Classes
struct	jas_stream_t
	I/O stream object. More...

Macros
#define	jas_stream_eof(stream) (((stream)->flags_ & JAS_STREAM_EOF) != 0)
	Get the EOF indicator for a stream. More...

#define	jas_stream_error(stream) (((stream)->flags_ & JAS_STREAM_ERR) != 0)
	Get the error indicator for a stream. More...

#define	jas_stream_clearerr(stream) ((stream)->flags_ &= ~(JAS_STREAM_ERR \| JAS_STREAM_EOF))
	Clear the error indicator for a stream. More...

#define	jas_stream_getrwlimit(stream) (((const jas_stream_t *)(stream))->rwlimit_)
	Get the read/write limit for a stream. More...

#define	jas_stream_getrwcount(stream) (((const jas_stream_t *)(stream))->rwcnt_)
	Get the read/write count for a stream. More...

#define	jas_stream_getc(stream) jas_stream_getc_func(stream)
	jas_stream_getc Read a character from a stream. More...

#define	jas_stream_putc(stream, c) jas_stream_putc_func(stream, c)
	jas_stream_putc Write a character to a stream. More...

#define	jas_stream_peekc(stream)
	Look at the next character to be read from a stream without actually removing the character from the stream. More...

Functions
JAS_EXPORT jas_stream_t *	jas_stream_fopen (const char filename, const char mode)
	Open a file as a stream. More...

JAS_EXPORT jas_stream_t *	jas_stream_memopen (char *buffer, size_t buffer_size)
	Open a memory buffer as a stream. More...

JAS_DEPRECATED JAS_EXPORT jas_stream_t *	jas_stream_memopen2 (char *buffer, size_t buffer_size)
	Do not use. More...

JAS_EXPORT jas_stream_t *	jas_stream_fdopen (int fd, const char *mode)
	Open a file descriptor as a stream. More...

JAS_EXPORT jas_stream_t *	jas_stream_freopen (const char path, const char mode, FILE *fp)
	Open a stdio (i.e., C standard library) stream as a stream. More...

JAS_EXPORT jas_stream_t *	jas_stream_tmpfile (void)
	Open a temporary file as a stream. More...

JAS_EXPORT int	jas_stream_close (jas_stream_t *stream)
	Close a stream. More...

JAS_EXPORT long	jas_stream_setrwlimit (jas_stream_t *stream, long rwlimit)
	Set the read/write limit for a stream. More...

JAS_EXPORT long	jas_stream_setrwcount (jas_stream_t *stream, long rw_count)
	Set the read/write count for a stream. More...

JAS_EXPORT size_t	jas_stream_read (jas_stream_t stream, void buffer, size_t count)
	Read characters from a stream into a buffer. More...

JAS_EXPORT unsigned	jas_stream_peek (jas_stream_t stream, void buffer, size_t count)
	Attempt to retrieve one or more pending characters of input from a stream into a buffer without actually removing the characters from the stream. More...

JAS_EXPORT size_t	jas_stream_write (jas_stream_t stream, const void buffer, size_t count)
	Write characters from a buffer to a stream. More...

JAS_EXPORT int	jas_stream_printf (jas_stream_t stream, const char format,...)
	Write formatted output to a stream. More...

JAS_EXPORT int	jas_stream_puts (jas_stream_t stream, const char s)
	Write a string to a stream. More...

JAS_EXPORT char *	jas_stream_gets (jas_stream_t stream, char buffer, int buffer_size)
	Read a line of input from a stream. More...

JAS_EXPORT int	jas_stream_ungetc (jas_stream_t *stream, int c)
	Put a character back on a stream. More...

JAS_EXPORT JAS_ATTRIBUTE_PURE int	jas_stream_isseekable (jas_stream_t *stream)
	Determine if stream supports seeking. More...

JAS_EXPORT long	jas_stream_seek (jas_stream_t *stream, long offset, int origin)
	Set the current position within the stream. More...

JAS_EXPORT long	jas_stream_tell (jas_stream_t *stream)
	Get the current position within the stream. More...

JAS_EXPORT int	jas_stream_rewind (jas_stream_t *stream)
	Seek to the beginning of a stream. More...

JAS_EXPORT int	jas_stream_flush (jas_stream_t *stream)
	Flush any pending output to a stream. More...

JAS_EXPORT int	jas_stream_copy (jas_stream_t destination, jas_stream_t source, ssize_t count)
	Copy data from one stream to another. More...

JAS_EXPORT int	jas_stream_display (jas_stream_t stream, FILE fp, int count)
	Print a hex dump of data read from a stream. More...

JAS_EXPORT ssize_t	jas_stream_gobble (jas_stream_t *stream, size_t count)
	Consume (i.e., discard) characters from stream. More...

JAS_EXPORT ssize_t	jas_stream_pad (jas_stream_t *stream, size_t count, int value)
	Write a fill character multiple times to a stream. More...

JAS_EXPORT long	jas_stream_length (jas_stream_t *stream)
	Get the size of the file associated with the specified stream. More...

Detailed Description

I/O streams.

General information can be found here.

Macro Definition Documentation

◆ jas_stream_clearerr

#define jas_stream_clearerr ( stream ) ((stream)->flags_ &= ~(JAS_STREAM_ERR | JAS_STREAM_EOF))

Clear the error indicator for a stream.

Parameters

stream The stream whose error indicator is to be cleared.

Todo:: TODO/FIXME: Should this macro evaluate to void?

◆ jas_stream_eof

#define jas_stream_eof ( stream ) (((stream)->flags_ & JAS_STREAM_EOF) != 0)

Get the EOF indicator for a stream.

Parameters

stream The stream whose EOF indicator is to be queried.

Returns: The value of the EOF indicator is returned. A nonzero value indicates that the stream has encountered EOF.

◆ jas_stream_error

#define jas_stream_error ( stream ) (((stream)->flags_ & JAS_STREAM_ERR) != 0)

Get the error indicator for a stream.

Parameters

stream The stream whose error indicator is to be queried.

Returns: The value of the error indicator is returned. A nonzero value indicates that the stream has encountered an error of some type (such as an I/O error). Note that EOF is not an error.

◆ jas_stream_getc

#define jas_stream_getc ( stream ) jas_stream_getc_func(stream)

jas_stream_getc Read a character from a stream.

Parameters

stream A pointer to the stream from which to read a character.

Returns: If a character is succesfully read, the character is returned. Otherwise, EOF is returned.

◆ jas_stream_getrwcount

#define jas_stream_getrwcount ( stream ) (((const jas_stream_t *)(stream))->rwcnt_)

Get the read/write count for a stream.

Parameters

stream A pointer to the stream whose read/write count is to be queried.

Returns: The read/write count is returned. This operation cannot fail.

◆ jas_stream_getrwlimit

#define jas_stream_getrwlimit ( stream ) (((const jas_stream_t *)(stream))->rwlimit_)

Get the read/write limit for a stream.

Parameters

stream A pointer to the stream whose read/write limit is to be queried.

Returns: The read/write limit for the stream is returned. This operation cannot fail. A negative read/write limit indicates no limit (i.e., an limit that is effectively infinite).

◆ jas_stream_peekc

#define jas_stream_peekc ( stream )

Value:

(((stream)->cnt_ <= 0) ? jas_stream_fillbuf(stream, 0) : \

((int)(*(stream)->ptr_)))

Look at the next character to be read from a stream without actually removing the character from the stream.

Parameters

stream A pointer to the stream to be examined.

This function examines the next character that would be read from the stream and returns this character without actually removing it from the stream.

Returns: If the peek operation fails (e.g., due to EOF or I/O error), EOF is returned. Otherwise, the character that would be next read from the stream is returned.

◆ jas_stream_putc

#define jas_stream_putc	(	stream,
		c
	)	jas_stream_putc_func(stream, c)

jas_stream_putc Write a character to a stream.

Parameters

stream	A pointer to the stream to which to write the character.
c	The character to be written.

Returns: If the character is successfully output, the value of the character is returned. Otherwise, EOF is returned.

Function Documentation

◆ jas_stream_close()

JAS_EXPORT int jas_stream_close ( jas_stream_t * stream )

Close a stream.

Parameters

stream A (nonnull) pointer to the stream to be closed.

The close operation will implicitly flush any pending output to the stream before closing. If such a flush operation fails, this will be reflected in the return value of this function. For many systems, it is likely that the main reason that this function can fail is due to an I/O error when flushing buffered output.

Returns: If no errors are encountered when closing the stream, 0 is returned. Otherwise, a nonzero value is returned.

◆ jas_stream_copy()

JAS_EXPORT int jas_stream_copy	(	jas_stream_t *	destination,
		jas_stream_t *	source,
		ssize_t	count
	)

Copy data from one stream to another.

Parameters

destination	A pointer to the stream that is the destination for the copy.
source	A pointer to the stream that is the source for the copy.
count	The number of characters to copy.

The function copies the specified number of characters from the source stream to the destination stream. In particular, if count is nonnegative, count characters are copied from the source stream source to the destination stream destination. Otherwise (i.e., if count is negative), the entire source stream source (i.e., until EOF is reached) is copied to the destination stream destination.

Returns: Upon success, 0 is returned; otherwise, -1 is returned.

Todo:: TODO/FIXME: should return type be ssize_t and the return value be the count of the characters copied? Perhaps, it might be safer to introduce a new function with differing semantics and deprecate this one?

◆ jas_stream_display()

JAS_EXPORT int jas_stream_display	(	jas_stream_t *	stream,
		FILE *	fp,
		int	count
	)

Print a hex dump of data read from a stream.

Parameters

stream	A pointer to the stream from which to read data.
fp	A pointer to a stdio stream (i.e., FILE) to which to print the hex dump.
count	The number of characters to include in the hex dump.

This function prints a hex dump of data read from a stream to a stdio stream. This function is most likely to be useful for debugging.

Returns: Upon success, 0 is returned. Otherwise, a negative value is returned.

Todo:: TODO/FIXME: should count be unsigned int or size_t instead of int?

◆ jas_stream_fdopen()

JAS_EXPORT jas_stream_t* jas_stream_fdopen	(	int	fd,
		const char *	mode
	)

Open a file descriptor as a stream.

Parameters

fd	The file descriptor of the file to open as a stream.
mode	A pointer to a string specifying the open mode. The format of this string is similar to that of the fdopen function in the C standard library.

Returns: Upon success, a pointer to the opened stream is returned. Otherwise, a null pointer is returned.

◆ jas_stream_flush()

JAS_EXPORT int jas_stream_flush ( jas_stream_t * stream )

Flush any pending output to a stream.

Parameters

stream A pointer to the stream for which output should be flushed.

The function flushes any buffered output to the underlying file object.

(This function is analogous to fflush for C standard library streams.)

Returns: Upon success, zero is returned. Otherwise, a negative value is returned.

◆ jas_stream_fopen()

JAS_EXPORT jas_stream_t* jas_stream_fopen	(	const char *	filename,
		const char *	mode
	)

Open a file as a stream.

Parameters

filename	A pointer to the pathname of the file to be opened.
mode	A pointer to the string specifying the open mode. The open mode is similar to that used by the fopen function in the C standard library.

Returns: Upon success, a pointer to the opened stream is returned. Otherwise, a null pointer is returned.

◆ jas_stream_freopen()

JAS_EXPORT jas_stream_t* jas_stream_freopen	(	const char *	path,
		const char *	mode,
		FILE *	fp
	)

Open a stdio (i.e., C standard library) stream as a stream.

Parameters

path	A pointer to a null-terminated string containing the pathname of the file to be reopened.
mode	A pointer to a null-terminated string containing the mode to be used for reopening the file. This string is similar to that used by the fdopen function in the C standard library.
fp	A pointer to the `FILE` (i.e., stdio stream) to be reopened.

It is unspecified whether the open mode specified by mode can be changed from the open mode used for opening the stdio stream.

Returns: Upon success, a pointer to the opened stream is returned. Otherwise, a null pointer is returned.

◆ jas_stream_gets()

JAS_EXPORT char* jas_stream_gets	(	jas_stream_t *	stream,
		char *	buffer,
		int	buffer_size
	)

Read a line of input from a stream.

Parameters

stream	A pointer to the stream from which to read input.
buffer	A pointer to the start of the buffer to hold to input to be read.
buffer_size	The size of the buffer in characters.

The function reads a line of input from a stream into a buffer. If a newline character is read, it is placed in the buffer. Since the buffer may be too small to hold the input, this operation can fail due to attempted buffer overrun.

(This function is analogous to fgets for C standard library streams.)

Returns: If the operation fails (e.g., due to an I/O error or attempted buffer overrun), a null pointer is returned. Otherwise, buffer is returned.

◆ jas_stream_gobble()

JAS_EXPORT ssize_t jas_stream_gobble	(	jas_stream_t *	stream,
		size_t	count
	)

Consume (i.e., discard) characters from stream.

Parameters

stream	A pointer to the stream from which to discard data.
count	The number of characters to discard.

This function reads and discards the specified number of characters from the given stream.

Returns: This function returns the number of characters read and discarded. If an error or EOF is encountered, the number of characters read will be less than count. To distinguish EOF from an I/O error, jas_stream_eof() and jas_stream_error() can be used.

◆ jas_stream_isseekable()

JAS_EXPORT JAS_ATTRIBUTE_PURE int jas_stream_isseekable ( jas_stream_t * stream )

Determine if stream supports seeking.

Parameters

stream A pointer to the stream to query.

The function is a predicate that tests if the underlying file object supports seek operations.

Returns: If the underlying file object supports seek operations, a (strictly) positive value is returned. Otherwise, 0 is returned.

◆ jas_stream_length()

JAS_EXPORT long jas_stream_length ( jas_stream_t * stream )

Get the size of the file associated with the specified stream.

Parameters

stream A pointer to the stream.

This function queries the size (i.e., length) of the underlying file object associated with the specified stream. The specified stream must be seekable.

Returns: Upon success, the size of the stream is returned. If an error occurs, a negative value is returned.

Todo:: Should the return type be long or ssize_t? long is consistent with the type used for seek offsets.

◆ jas_stream_memopen()

JAS_EXPORT jas_stream_t* jas_stream_memopen	(	char *	buffer,
		size_t	buffer_size
	)

Open a memory buffer as a stream.

Parameters

buffer	A pointer to the buffer to be used to store stream data.
buffer_size	The size of the buffer.

If buffer is 0 and buffer_size > 0: a buffer is dynamically allocated with size buffer_size and this buffer is not growable.
If buffer is 0 and buffer_size is 0: a buffer is dynamically allocated whose size will automatically grow to accommodate the amount of data written.
If buffer is not 0: buffer_size (which, in this case, is not currently allowed to be zero) is the size of the (nongrowable) buffer pointed to by buffer.

◆ jas_stream_memopen2()

JAS_DEPRECATED JAS_EXPORT jas_stream_t* jas_stream_memopen2	(	char *	buffer,
		size_t	buffer_size
	)

Do not use.

Deprecated:: Do not use this function. This function is deprecated. Use jas_stream_memopen instead.

◆ jas_stream_pad()

JAS_EXPORT ssize_t jas_stream_pad	(	jas_stream_t *	stream,
		size_t	count,
		int	value
	)

Write a fill character multiple times to a stream.

Parameters

stream	A pointer to the stream to which to write.
count	The number of times to write the fill character to the stream.
value	The fill character.

This function writes the given fill character to a stream a specified number of times. If a count of zero is specified, the function should have no effect.

Returns: The number of times the fill character was written to the stream is returned. If this value is less than the specified count, an error must have occurred.

◆ jas_stream_peek()

JAS_EXPORT unsigned jas_stream_peek	(	jas_stream_t *	stream,
		void *	buffer,
		size_t	count
	)

Attempt to retrieve one or more pending characters of input from a stream into a buffer without actually removing the characters from the stream.

Parameters

stream	A pointer to the stream from which to retrieve pending input.
buffer	A pointer to the start of the buffer.
count	A count of how many characters to retrieve.

The extent to which one can peek into the stream is limited. Therefore, this function can fail if count is sufficiently large.

Returns: Returns the number of bytes copied to the given buffer, or 0 on error or EOF.

Warning: TODO/FIXME: peeking at EOF should be distinguishable from an I/O error; also should return type be changed to size_t?

◆ jas_stream_printf()

JAS_EXPORT int jas_stream_printf	(	jas_stream_t *	stream,
		const char *	format,
			...
	)

Write formatted output to a stream.

Parameters

stream	A pointer to the stream to which to write output.
format	A pointer to a format string similar to the printf function in the C standard library.

The function prints the information associated with the format string to the specified stream.

Returns: Upon success, the number of characters output to the stream is returned. If an error is encountered, a negative value is returned.

Todo:: I think that the return type of int is okay here. It is consistent with printf and friends.

◆ jas_stream_puts()

JAS_EXPORT int jas_stream_puts	(	jas_stream_t *	stream,
		const char *	s
	)

Write a string to a stream.

Parameters

stream	A pointer to the stream to which the string should be written.
s	A pointer to a null-terminated string for output.

The null character is not output.

(This function is analogous to fputs for C standard library streams.)

Returns: Upon success, a nonnegative value is returned. Upon failure, a negative value is returned.

◆ jas_stream_read()

JAS_EXPORT size_t jas_stream_read	(	jas_stream_t *	stream,
		void *	buffer,
		size_t	count
	)

Read characters from a stream into a buffer.

Parameters

stream	A pointer to the stream from which to read data.
buffer	A pointer to the start of the buffer.
count	A count of the number of characters to read (nominally).

If count is zero, the function has no effect (and therefore cannot fail). Otherwise, the function attempts to read count characters from the stream stream into the buffer starting at buffer. The number of characters read can be less than count, due to end-of-file (EOF) or an I/O error.

(This function is analogous to fread with the two read-count parameters combined into a single size.)

Returns

The number of characters read is returned. In the case that the number of characters read is less than count, jas_stream_eof() and/or jas_stream_error() must be used to distinguish between:

a failure due to an I/O error
a failure due to the read/write limit being exceeded
EOF.

(The functions jas_stream_getrwcount() and jas_stream_getrwlimit() can be used to distinguish between failure due to an I/O error and failure due to the read/write limit being exceeed.)

Todo:: TODO: should jas_stream_error be true if RWLIMIT exceeded? or maybe introduce a jas_stream_rwlimit predicate?

◆ jas_stream_rewind()

JAS_EXPORT int jas_stream_rewind ( jas_stream_t * stream )

Seek to the beginning of a stream.

Parameters

stream A pointer to the stream whose position is to be set.

The stream position is set to the start of the stream. This function is equivalent to returning the value of jas_stream_seek(stream, 0, SEEK_SET).

(This function is analogous to frewind for C standard library streams.)

Returns: Upon success, the new stream position is returned. Otherwise, a negative value is returned.

◆ jas_stream_seek()

JAS_EXPORT long jas_stream_seek	(	jas_stream_t *	stream,
		long	offset,
		int	origin
	)

Set the current position within the stream.

Parameters

stream	A pointer to the stream for which to set the current position.
offset	The new position for the stream.
origin	The origin to which this new position is relative.

The origin can be SEEK_CUR, SEEK_SET, or SEEK_END in a similar fashion as the fseek function in the C standard library (and the lseek function in POSIX).

Returns: Upon success, the new stream position is returned. Upon failure, a negative value is returned.

◆ jas_stream_setrwcount()

JAS_EXPORT long jas_stream_setrwcount	(	jas_stream_t *	stream,
		long	rw_count
	)

Set the read/write count for a stream.

Parameters

stream	A pointer to the stream whose read/write count is to be set.
rw_count	The new value for the read/write count.

Returns: The old value of the read/write count is returned. This operation cannot fail.

Todo:: TODO/FIXME: Should this macro evaluate to void?

◆ jas_stream_setrwlimit()

JAS_EXPORT long jas_stream_setrwlimit	(	jas_stream_t *	stream,
		long	rwlimit
	)

Set the read/write limit for a stream.

Parameters

stream	A pointer to the stream whose read/write limit is to be set.
rwlimit	The new value for the read/write limit.

A negative read/write limit is treated as if it were infinity (i.e., there is no read/write limit).

Returns: The old read/write limit is returned.

◆ jas_stream_tell()

JAS_EXPORT long jas_stream_tell ( jas_stream_t * stream )

Get the current position within the stream.

Parameters

stream A pointer to the stream whose current position is to be queried.

The current position of the stream is returned.

(This function is analogous to ftell for C standard library streams.)

Returns: Upon success, the current stream position is returned. If an error is encountered, a negative value is returned.

◆ jas_stream_tmpfile()

JAS_EXPORT jas_stream_t* jas_stream_tmpfile ( void )

Open a temporary file as a stream.

A temporary file is created and opened as a stream. The temporary file is deleted when closed via jas_stream_close(). Some operating systems provide a mechanism for ensuring that a file is removed when closed. Such functionality may be used by the implementation when available.

Returns: Upon success, a pointer to the opened stream is returned. Otherwise, a null pointer is returned.

◆ jas_stream_ungetc()

JAS_EXPORT int jas_stream_ungetc	(	jas_stream_t *	stream,
		int	c
	)

Put a character back on a stream.

Parameters

stream	A pointer to the stream to which the character should be put back.
c	The character to put back.

The character c (which was presumably read previously from the stream stream) is put back on the stream (as if it had not yet been read). In other words, this function undoes the effect of jas_stream_getc(). It is unspecified what happens if the character put back was not the one originally read. The number of characters that can be pushed back onto the stream for subsequent reading is limited. Trying to push back too many characters on a stream will result in an error. The approximate limit is given by the value of JAS_STREAM_MAXPUTBACK.

Returns: Upon success, zero is returned. If the specified character cannot be pushed back, a negative value is returned.

◆ jas_stream_write()

JAS_EXPORT size_t jas_stream_write	(	jas_stream_t *	stream,
		const void *	buffer,
		size_t	count
	)

Write characters from a buffer to a stream.

Parameters

stream	A pointer to the stream to which to write data.
buffer	A pointer to the start of the buffer.
count	A count of the number of characters to write.

If count is zero, the function has no effect (and therefore cannot fail). Otherwise, the function will attempt to write count characters from the buffer starting at buffer to the stream stream. The number of characters written can be less than count due to an I/O error or the read/write limit being exceeded.

(This function is analogous to fwrite with the two write-count parameters combined into a single size.)

Returns

Upon success, the number of characters successfully written is returned. If an error occurs, the value returned will be less than count. The jas_stream_error() and jas_stream_rwlimit() function (TODO/CHECK: the latter of which does not currently exist?) can be used to distinguish between:

failure due to an I/O error
failure due to the read/write limit being exceeded

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ jas_stream_clearerr

◆ jas_stream_eof

◆ jas_stream_error

◆ jas_stream_getc

◆ jas_stream_getrwcount

◆ jas_stream_getrwlimit

◆ jas_stream_peekc

◆ jas_stream_putc

Function Documentation

◆ jas_stream_close()

◆ jas_stream_copy()

◆ jas_stream_display()

◆ jas_stream_fdopen()

◆ jas_stream_flush()

◆ jas_stream_fopen()

◆ jas_stream_freopen()

◆ jas_stream_gets()

◆ jas_stream_gobble()

◆ jas_stream_isseekable()

◆ jas_stream_length()

◆ jas_stream_memopen()

◆ jas_stream_memopen2()

◆ jas_stream_pad()

◆ jas_stream_peek()

◆ jas_stream_printf()

◆ jas_stream_puts()

◆ jas_stream_read()

◆ jas_stream_rewind()

◆ jas_stream_seek()

◆ jas_stream_setrwcount()

◆ jas_stream_setrwlimit()

◆ jas_stream_tell()

◆ jas_stream_tmpfile()

◆ jas_stream_ungetc()

◆ jas_stream_write()