12.4.3 Input and output

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.