12.3.41 SP_get_stream_counts()

Synopsis

     #include <sicstus/sicstus.h>
     
     spio_t_error_code
     SP_get_stream_counts(
        SP_stream *stream,
        spio_t_offset *pitem_count,
        spio_t_offset *pnewline_count,
        spio_t_offset *pline_length,
        spio_t_bits options);

Obtain the stream counters.

Arguments

stream

The stream.

item_count

If pitem_count is NULL it is not used, otherwise it is used as follows.

On success, *pitem_count is assigned to the number of items read from an input-only or bidirectional stream or with the number of items written to a output-only stream.

For binary streams, an item is a byte, for text streams it is a character.

pnewline_count

If pnewline_count is NULL it is not used, otherwise it is used as follows.

On success *pnewline_count is assigned to the number of newlines read from an input-only or bidirectional text stream or with the number of newlines written to a output-only text stream.

For binary streams, *pnewline_count is set to zero.

pline_length

If pline_length is NULL it is not used, otherwise it is used as follows.

On success, *pline_length is assigned to the number of characters read on the current line from an input-only or bidirectional text stream or with the characters written on the current line to a output-only text stream.

For binary streams, *pline_length is set to zero.

options

The following bits can be set:

SP_GET_STREAM_COUNTS_OPTION_READ

Return the real input counts of a read-only or bidirectional stream.

SP_GET_STREAM_COUNTS_OPTION_WRITE

Return the real output counts of a write-only stream.

Currently, the call will fail with SPIO_E_NOT_SUPPORTED if the stream is bidirectional and SP_GET_STREAM_COUNTS_OPTION_WRITE is specified. This is because there is only one set of counters for each stream and these are used to count in the input direction of bidirectional streams. This may be changed in a future release.

At most one of SP_GET_STREAM_COUNTS_OPTION_READ and SP_GET_STREAM_COUNTS_OPTION_WRITE can be specified. If neither is specified then default behaviour is as follows

• If stream is interactive, a common set of counts shared by all interactive streams is returned.
• If stream is write-only, the output counts are returned.
• Otherwise, the stream is read-only or bidirectional and the input counts are returned.

Return Value

On success, SPIO_S_NOERR or some other success code is returned.

On failure, returns a SPIO error code. Error codes with special meaning for SP_get_stream_counts():

SPIO_E_NOT_READ

SP_GET_STREAM_COUNTS_OPTION_READ was specified but stream is not an input stream.

SPIO_E_NOT_WRITE

SP_GET_STREAM_COUNTS_OPTION_WRITE was specified but stream is not an output stream.

SPIO_E_NOT_SUPPORTED

SP_GET_STREAM_COUNTS_OPTION_WRITE was specified but stream is a bidirectional stream.

Description

There is only one set of counters for each stream. For a bidirectional stream, these counters only count in the input direction and the output direction does not affect the counts.

There is a common set of stream counters for all interactive streams. By default, these will be returned if stream is interactive instead of the real counts. This behaviour can be changed with the options argument, see above.

See Also

Prolog Streams.