12.3.40 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 behavior is as follows

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 behavior can be changed with the options argument, see above.

See Also

Prolog Streams.


Send feedback on this subject.