I/O streams. 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_DLLEXPORT jas_stream_t *	jas_stream_fopen (const char filename, const char mode)
	Open a file as a stream. More...

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

JAS_DLLEXPORT jas_stream_t *	jas_stream_memopen2 (char *buffer, size_t buffer_size)

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

JAS_DLLEXPORT 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_DLLEXPORT jas_stream_t *	jas_stream_tmpfile (void)
	Open a temporary file as a stream. More...

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

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

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

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

JAS_DLLEXPORT 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_DLLEXPORT unsigned	jas_stream_write (jas_stream_t stream, const void buffer, unsigned count)
	Write characters from a buffer to a stream. More...

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

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

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

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

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

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

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

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

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

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

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

JAS_DLLEXPORT int	jas_stream_gobble (jas_stream_t *stream, int count)
	Consume (i.e., discard) characters from stream. More...

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

JAS_ATTRIBUTE_PURE JAS_DLLEXPORT 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.

For more detail on I/O streams, please refer to 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.

◆ 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.

Function Documentation

◆ jas_stream_close()

JAS_DLLEXPORT 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_DLLEXPORT int jas_stream_copy	(	jas_stream_t *	destination,
		jas_stream_t *	source,
		int	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.

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

Todo:: TODO/FIXME: count should probably be a size_t; return type ssize_t?

◆ jas_stream_display()

JAS_DLLEXPORT 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_DLLEXPORT 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_DLLEXPORT 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.

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

◆ jas_stream_fopen()

JAS_DLLEXPORT 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_DLLEXPORT 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 string containing the path of the filename associated with the stdio stream.
mode	A pointer to a string containing the open mode to be used for the (JasPer) stream. This string is similar to that used by the fdopen function in the C standard library.
fp	A pointer to the stdio stream.

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_DLLEXPORT 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.

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_DLLEXPORT int jas_stream_gobble	(	jas_stream_t *	stream,
		int	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.

Warning: TODO/FIXME: count be size_t and return type should be ssize_t

◆ jas_stream_isseekable()

JAS_ATTRIBUTE_PURE JAS_DLLEXPORT 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_ATTRIBUTE_PURE JAS_DLLEXPORT long jas_stream_length ( jas_stream_t * stream )

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

Parameters

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.

Warning: TODO/FIXME: the return type should be ssize_t?

◆ jas_stream_memopen()

JAS_DLLEXPORT jas_stream_t* jas_stream_memopen	(	char *	buffer,
		int	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.

Warning: TODO/FIXME: The type of the buffer_size parameter will be changed to size_t in the future.; TODO/FIXME: In a later release, this function will be changed to have the same prototype as jas_stream_memopen2, at which point jas_stream_memopen2 will be removed.

◆ jas_stream_memopen2()

JAS_DLLEXPORT jas_stream_t* jas_stream_memopen2	(	char *	buffer,
		size_t	buffer_size
	)

Warning: This function will be renamed jas_stream_memopen in a future release. Do not use this function.

◆ jas_stream_pad()

JAS_DLLEXPORT int jas_stream_pad	(	jas_stream_t *	stream,
		int	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.

Todo:: TODO: should the count be size_t; return type maybe size_t?

◆ jas_stream_peek()

JAS_DLLEXPORT 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

◆ jas_stream_printf()

JAS_DLLEXPORT 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_DLLEXPORT 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.

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

◆ jas_stream_read()

JAS_DLLEXPORT unsigned jas_stream_read	(	jas_stream_t *	stream,
		void *	buffer,
		unsigned	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.

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.

TODO/CHECK: can items 1 and 2 be distinguished currently?

Warning: TODO/FIXME/CHECK: jas_stream_error should be true if RWLIMIT exceeded? or need a jas_stream_rwlimit predicate?; TODO/FIXME: In the future, the type of the count parameter and the return type will be changed to size_t.

◆ jas_stream_rewind()

JAS_DLLEXPORT 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).

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

◆ jas_stream_seek()

JAS_DLLEXPORT 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_DLLEXPORT 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_DLLEXPORT 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_ATTRIBUTE_PURE JAS_DLLEXPORT 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.

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

◆ jas_stream_tmpfile()

JAS_DLLEXPORT 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_DLLEXPORT 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_DLLEXPORT unsigned jas_stream_write	(	jas_stream_t *	stream,
		const void *	buffer,
		unsigned	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.

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

Warning: TODO/FIXME: The type of the count parameter should be size_t. The return type should be size_t.

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()