12.3.9 SP_create_stream()

Synopsis

#include <sicstus/sicstus.h>

spio_t_error_code
SP_create_stream(
   void *user_data,
   void const *user_class,
   spio_t_simple_device_read *user_read,
   spio_t_simple_device_write *user_write,
   spio_t_simple_device_flush_output *user_flush_output,
   spio_t_simple_device_seek *user_seek,
   spio_t_simple_device_close *user_close,
   spio_t_simple_device_interrupt *user_interrupt,
   spio_t_simple_device_ioctl *user_ioctl,
   spio_t_bits create_stream_options,
   SP_stream **pstream);

Create a Prolog stream that will call user defined functions to perform stream operations.

Arguments

user_data

This is a pointer to arbitrary user specified data. It is passed to all user defined stream methods. It must not be NULL.

user_class

Arbitrary pointer. This is used with SP_get_stream_user_data(), which see.

user_read

If non-NULL then this is an input stream. See cpg-ref-user_read for details.

user_write

If non-NULL then this is an output stream. See cpg-ref-user_write for details.

Note that both user_read and user_write can be specified, signifying a bidirectional stream.

user_flush_output

Will be called to flush output on the stream. Ignored if user_write is NULL. Can be NULL if the stream need not be flushed, e.g. if user_write always ensures that any output reaches its destination immediately. See cpg-ref-user_flush_output for details.

user_seek

Reserved, should be NULL.

user_close

Closes the stream. See cpg-ref-user_close for details.

user_interrupt

Reserved, should be NULL.

user_ioctl

Reserved, should be NULL.

args

Reserved, should be NULL.

create_stream_options

The following bits can be set:

SP_CREATE_STREAM_OPTION_BINARY

This is a binary stream. The user_read and user_write methods transfer bytes.

SP_CREATE_STREAM_OPTION_TEXT

This is a TEXT stream. The user_read and user_write methods transfer wide characters.

SP_CREATE_STREAM_OPTION_AUTOFLUSH

After writing to this stream prolog predicates will do a flush_output/1. In essence this ensures that the stream behaves as if it were unbuffered.

SP_CREATE_STREAM_OPTION_INTERACTIVE

Treat this stream as an interactive stream. Implies SP_CREATE_STREAM_OPTION_AUTOFLUSH.

SP_CREATE_STREAM_OPTION_EOF_ON_EOF

SP_CREATE_STREAM_OPTION_RESET_ON_EOF

These correspond to the open/4 options eof_action(eof) and eof_action(reset) respectively. The default is to give an error if reading after reaching end of file.

Exactly one of SP_CREATE_STREAM_OPTION_BINARY and SP_CREATE_STREAM_OPTION_TEXT must be set.

pstream

This is assigned to the created SICStus stream on success. It should be closed with SP_fclose() or close/[1,2].

Return Value

On success, *pstream is assigned, and SPIO_S_NOERR or some other success code is returned. You should use the SPIO_FAILED() macro to determine if the return value signifies failure or success.

See Also

Defining a New Stream.