Next: cpg-ref-user_flush_output, Previous: cpg-ref-SU_initialize, Up: cpg-bif [Contents][Index]
user_close()
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.
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.
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.
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.
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
.
cpg-ref-SP_create_stream. Defining a New Stream.