12.3.101 user_close()

Synopsis

     spio_t_error_code
     user_close(
       void **puser_data,
       spio_t_bits close_options
       );

This is the prototype for one of the methods of user defined streams. It is used when SICStus wants to close one or both directions of a user defined stream.

Arguments

puser_data

A pointer to the same value as was passed to SP_create_stream(). On successful return, if the stream has been closed and any resources freed, then *puser_data should be set to NULL.

If user_close fails, it can still set *puser_data to NULL to signify that the stream is no longer usable.

close_options

The following bits can be set:

SPIO_DEVICE_CLOSE_OPTION_READ

The read direction should be closed. Only set if the device was created as an input or bidirectional device.

SPIO_DEVICE_CLOSE_OPTION_WRITE

The write direction should be closed. Only set if the device was created as an output or bidirectional device.

SPIO_DEVICE_CLOSE_OPTION_FORCE

The specified directions should be closed without attempting to flush any data. Among other things this option may be passed if a previous call to user_close returned an error.

Note that a bidirectional stream should only close the directions specified by the close_options. Also note that user_close for a bidirectional stream may be called several times and that the same direction flag, e.g. SPIO_DEVICE_CLOSE_OPTION_READ may be specified more than once, even if that direction has already been closed successfully.

Once a call to user_close has set *puser_data to NULL, none of the device methods will be called again. Note that a *puser_data may be set to NULL even when a failure code is returned. This is useful if the failure is unrecoverable.

There is no option to specify non-blocking close, it is expected that user_close will finish quickly. To make this more likely, user_flush_output is called before non-forcibly closing an output stream.

Return Value

On success, return SPIO_S_NOERR or some other success code and set *puser_data if and only if the user data and any other resources have been freed.

On failure, return a SPIO error code. Error codes with special meaning for user_close:

SPIO_E_END_OF_FILE

Returned if there were buffered data and it is not possible to write more data onto the stream, e.g. some underlying device has been closed.

Other error codes may also be returned.

Description

Should close one or all directions depending on the close_options. If all directions have been closed, the user data should be deallocated and *puser_data set to NULL.

See Also

cpg-ref-SP_create_stream. Defining a New Stream.