JasPer: I/O Streams

JasPer 3.0.6 |

Classes | Macros | Functions
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_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:
  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

  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:
  1. failure due to an I/O error
  2. failure due to the read/write limit being exceeded