JasPer  3.0.0
I/O Streams

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_tjas_stream_fopen (const char *filename, const char *mode)
 Open a file as a stream. More...
 
JAS_EXPORT jas_stream_tjas_stream_memopen (char *buffer, size_t buffer_size)
 Open a memory buffer as a stream. More...
 
JAS_DEPRECATED JAS_EXPORT jas_stream_tjas_stream_memopen2 (char *buffer, size_t buffer_size)
 Do not use. More...
 
JAS_EXPORT jas_stream_tjas_stream_fdopen (int fd, const char *mode)
 Open a file descriptor as a stream. More...
 
JAS_EXPORT jas_stream_tjas_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_tjas_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
streamThe 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
streamThe 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
streamThe 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
streamA 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
streamA 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
streamA 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
streamA 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,
 
)    jas_stream_putc_func(stream, c)

jas_stream_putc Write a character to a stream.

Parameters
streamA pointer to the stream to which to write the character.
cThe 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
streamA (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
destinationA pointer to the stream that is the destination for the copy.
sourceA pointer to the stream that is the source for the copy.
countThe 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
streamA pointer to the stream from which to read data.
fpA pointer to a stdio stream (i.e., FILE) to which to print the hex dump.
countThe 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
fdThe file descriptor of the file to open as a stream.
modeA 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
streamA 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
filenameA pointer to the pathname of the file to be opened.
modeA 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
pathA pointer to a null-terminated string containing the pathname of the file to be reopened.
modeA 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.
fpA 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
streamA pointer to the stream from which to read input.
bufferA pointer to the start of the buffer to hold to input to be read.
buffer_sizeThe 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
streamA pointer to the stream from which to discard data.
countThe 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
streamA 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
streamA 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
bufferA pointer to the buffer to be used to store stream data.
buffer_sizeThe 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
streamA pointer to the stream to which to write.
countThe number of times to write the fill character to the stream.
valueThe 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
streamA pointer to the stream from which to retrieve pending input.
bufferA pointer to the start of the buffer.
countA 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
streamA pointer to the stream to which to write output.
formatA 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
streamA pointer to the stream to which the string should be written.
sA 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
streamA pointer to the stream from which to read data.
bufferA pointer to the start of the buffer.
countA 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:
  1. a failure due to an I/O error
  2. a failure due to the read/write limit being exceeded
  3. 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
streamA 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
streamA pointer to the stream for which to set the current position.
offsetThe new position for the stream.
originThe 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
streamA pointer to the stream whose read/write count is to be set.
rw_countThe 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
streamA pointer to the stream whose read/write limit is to be set.
rwlimitThe 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
streamA 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
streamA pointer to the stream to which the character should be put back.
cThe 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
streamA pointer to the stream to which to write data.
bufferA pointer to the start of the buffer.
countA 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:
  1. failure due to an I/O error
  2. failure due to the read/write limit being exceeded