For input and output, SWI-Stream.h defines a set of
functions that are similar to the C library functions, except prefixed
by S, e.g. Sfprintf().
They differ from the C functions in following ways:
- Instead of returning the number of bytes written and a negative
value for error, they return the number of characters written and a
negative value for error.
- Instead of a
FILE, they access the Prolog streams,
using IOSTREAM*. In particular, Scurrent_output
accesses the current output stream and works well with
with_output_to/2.
Similarly, there are
Scurrent_intput, Suser_output,
Suser_error, and Suser_input.
- If you wish to directly use the operating system's
stdin, stdout, stderr, you can
use
Sinput, Soutput, Serror. These
are not affected by predicates such as with_output_to/2.
In general, if a stream is acquired via PL_acquire_stream(),
an error is raised when PL_release_stream()
is called, so in that situation, there's no need to check the return
codes from the IO functions. Blob write callbacks are also called in the
context of an acquired stream, so there is no need to check the return
codes from its IO function calls. However, if you use one of the
standard streams such as
Scurrent_output, you should check the return code and
return
FALSE from the foreign predicate, at which point an error
will be raised. Not all IO functions follow this, because they need to
return other information, so you should check the details with each one
(e.g., Sputcode()
returns -1 on error).
For more details, including formatting extensions for printing terms,
see section 12.9.
