12.3.18 SP_fclose()

Synopsis

#include <sicstus/sicstus.h>

spio_t_error_code
SP_fclose(
  SP_stream *stream,
  spio_t_bits close_options);

Close the stream.

Arguments

stream

The stream to close unless the SP_FCLOSE_OPTION_USER_STREAMS is set, see below.

close_options

The following bits can be set:

SP_FCLOSE_OPTION_READ

SP_FCLOSE_OPTION_WRITE

Close the specified directions. If neither of these options is specified, the stream is closed in all opened directions, i.e. as if both options were specified. If the stream is not opened in a direction specified by an option, that option is ignored.

Note that it is possible to close only one direction of a bidirectional stream. The return value will tell whether the stream is still open; see below.

SP_FCLOSE_OPTION_FORCE

Close the specified direction forcibly, i.e. without flushing buffers etc. This also ensures that the close finishes quickly, i.e. does not block.

SP_FCLOSE_OPTION_NO_FSYNC

Do not use OS fclose() or similar when closing a stream in write direction, i.e. do not wait for written data to reach the disk.

By default, closing a stream will try to ensure that all written data have been stored on disk before the call returns. This makes stream handling more robust, e.g. if the process crashes shortly after closing the stream. However, waiting for data to reach the disk is sometimes very slow (e.g. on some Linux configurations), in which case this flag can be used to speed things up, at the cost of somewhat reduced robustness.

SP_FCLOSE_OPTION_NONBLOCKING

You should avoid using this option.

Pass non-blocking option to lower level routines, including the call to SP_flush_output() that is issued when non-forcibly closing write direction.

One possible use for this option is to perform a best effort close, which falls back to using SP_FCLOSE_OPTION_FORCE only if ordinary close would block.

SP_FCLOSE_OPTION_USER_STREAMS

In this case the stream should not be a stream but instead be the user_class of a user defined stream. When this option is passed, all currently opened streams of that class is closed, using the remaining option flags. E.g. to close all user defined streams of class my_class in the read direction only do: SP_fclose((SP_stream*)my_class,SP_FCLOSE_OPTION_USER_STREAMS|SP_FCLOSE_OPTION_READ).

Return Value

On success, all specified directions has been closed. Since some direction may still be open, there are two possible return values on success:

SPIO_S_NOERR

The stream is still valid, some direction is still not closed.

SPIO_S_DEALLOCATED

The stream has been deallocated and cannot be used further. All directions have been closed.

On failure, returns a SPIO error code. Error codes with special meaning for SP_fclose() are the same as for SP_flush_output(), which see. Other error codes may also be returned.

See Also

cpg-ref-SP_flush_output. Prolog Streams.