The SWI-Prolog foreign language interface provides access to Prolog
IO streams. This interface may be used to get hold of Prolog streams for
reading and writing. In addition, this interface allows to define new
stream types. For example, the Windows swipl-win.exe executable
that runs Prolog in a Windows GUI redefines the Prolog standard IO
streams (user_input, user_output and
user_error to read from and write to the GUI window.
The interface is built around the IOSTREAM type which
plays a role similar to the POSIX FILE type. Most of the
functions are modeled after their FILE counterpart,
prefixed by S, e.g. Sfwrite().
The IOSTREAM type has considerably more features though.
The IOSTREAM type is practically disconnected from the rest
of the Prolog system. Prolog refers to streams either by
alias (user_input, etc. or created using the
alias(Name) option of open/4)
or using a stream handle which is represented as a blob
(see section
12.4.10). Foreign extensions that wish to access or define streams
should include
SWI-Stream.h in addition to SWI-Prolog.h as
below. Both headers may be used with C as well as C++.
The interface also defines Sinput, Suser, Serror
for direct access to the operating system's input and output streams,
bypassing Prolog's control - for example, these will not be affected by with_output_to/3.
There is also a convenience function for debugging, which goes directly
to stderr: Sdprintf().242On
Windows the output is also emitted using OutputDebugString().
#include <SWI-Stream.h> #include <SWI-Prolog.h>
There are several ways to get access to an IO Stream handle,
basically get them from Prolog, get access to the standard streams and
create a new stream. The standard streams are available as
Sinput, Soutput and Serror. Note
that these are thread specific. Creating a new stream is discussed with Snew().
Below are the functions to obtain a stream handle from a Prolog term,
obtain and release ownership.
TRUE
on success and FALSE on failure, by default generating an
exception. The flags argument is a bitwise disjunction of
these flags:
SIO_INPUTSIO_OUTPUTSIO_INPUT for details.
If neither SIO_OUTPUT nor SIO_INPUT is given t
may not be a pair.SIO_TRYLOCKFALSE if the stream cannot be locked immediately. No
error is generated.SIO_NOERRORThe returned stream is owned by the calling thread using PL_acquire_stream().
atom_t object rather than a IOSTREAM*.FALSE with an
exception. Otherwise return TRUE.
In general, stream functions do not set any Prolog error state; that
is done by PL_release_stream().
Once a stream is in an error state, all subsequent functions act as
no-ops (returning -1) unless Sclearerr()
is called. Sferror()
may be used to check whether a stream is in an error condition. This
error may be turned into a Prolog exception by calling
PL_acquire_stream()
followed by PL_release_stream().
In this case,
PL_release_stream()
will set the Prolog exception and return
FALSE.
Below is an example that writes “Hello World” to a stream provided by Prolog. Note that PL_release_stream() raises an exception if the Sfprintf() failed and (thus) left the stream in an error state.
static foreign_t
hello_world(term_t to)
{ IOSTREAM *s;
if ( PL_get_stream(to, &s, SIO_OUTPUT) )
{ Sfprintf(s, "Hello World!\n");
return PL_release_stream(s);
}
return FALSE;
}
... // fragment from install function
PL_register_foreign("hello world", 1, hello_world, 0);
A new stream is created using Snew().
Before we can create a stream we must create a function block of type IOFUNCTIONS
that provide function pointers for the basic operations on the stream.
This type is defined as follows:
typedef struct io_functions
{ Sread_function read; /* fill the buffer */
Swrite_function write; /* empty the buffer */
Sseek_function seek; /* seek to position */
Sclose_function close; /* close stream */
Scontrol_function control; /* Info/control */
Sseek64_function seek64; /* seek to position (large files) */
} IOFUNCTIONS;
NULL if
repositioning is not possible on this type or they may return -1 and set
errno to EPIPE if the pointer cannot be
repositioned on this instance. The function returns the new file
position. See Sseek()
for details on how repositioning is implemented. See
section 12.9.4
for raising errors.SIO_GETPENDING, size_t*SIO_LASTERROR, char*SIO_SETENCODING, IOENC*SIO_FLUSHOUTPUT, NULLSIO_GETSIZE, int64_t*SIO_GETFILENO, int*SIO_GETWINSOCK, SOCKET*
Given an IOFUNCTIONS block we can create a new stream
from a
handle using Snew():
IOSTREAM* from a handle, flags and a block of
callback functions. The flags argument is a bitwise or of
SIO_* flags. Flags that control the creation are:
SIO_INPUTSIO_OUTPUTSIO_NBUFSIO_LBUFSIO_FBUFSIO_NBUF), line buffered (SIO_LBUF)
or fully buffered (SIO_FBUF)SIO_TEXTENC_OCTET.SIO_RECORDPOSposition property and related predicates.SIO_NOMUTEX
If the stream is associated with an OS file handle the system
initializes the SIO_ISATTY flag (on POSIX systems) and if
possible tells the OS not to inherit this stream to child processes.
The symbol Sfilefunctions is a IOFUNCTIONS
struct that contains the callbacks for accessing a regular file. After
opening an file using the POSIX open() API we can create a stream
to this file using Snew():
int fno = open(path, O_RDONLY);
IOSTREAM *s;
if ( fno >= 0 )
s = Snew((void*)fno,
SIO_INPUT|SIO_FBUF|SIO_RECORDPOS|SIO_TEXT,
&Sfilefunctions);
...
Snew() can
only fail if there is not enough memory. In that case the return value
is NULL and errno is set to ENOMEM.
r or w and may be followed
by b to create a binary stream. The default is to
create a text stream using the platform conventions and locale."wa". If the buffer is allocated or enlarged, this is
achieved using malloc() or realloc(). In this case the
returned buffer should be freed by the caller when done. Example:
{ char buf[1024]; // don't allocate for small stuff
char *s = buf;
IOSTREAM *fd;
size_t size = sizeof(buf);
fd = Sopenmem(&s, &size, "w");
...
Sclose(fd);
...
if ( s != buf ) // apparently moved
Sfree(s);
}
The mode is "r" or "w". The mode "rF"
calls
PL_free(buffer)
when closed.
Note: Its is not allowed to access streams created with this call from multiple threads. This is ok for all usage inside Prolog itself. This call is intended to use Sfprintf() and other output functions to create strings.
A stream can be made accessible from Prolog using PL_unify_stream():
ENC_UNICODE_BE
and ENC_UNICODE_LE, sizeof(wchar_t) for ENC_WCHAR
and 1 for all other encodings (including multibyte encodings such as
ENC_UTF8.\n when
in
SIO_LBUF buffering mode and updates the stream position
information if enabled (SIO_RECORDPOS). Returns 0 on
success, -1 on error.SIO_RECORDPOS). Returns -1 on end of file or
error. Use Sferror()
or Sfeof() to
distinguish end of file from an error. This is a C macro.SIO_REPXML႒SIO_REPPL\x4242\SIO_REPPLU\u4242 or
\U42424242
Updates the stream position information if enabled (SIO_RECORDPOS)
0xfffd is returned. Other errors and end-of-file return -1;
Use
Sferror() or Sfeof()
to distinguish end of file from an error.SIO_NBUF).SIO_FEOF flag, (2) test whether the
buffer is non-empty, (3) fill the buffer and return non-zero if the
Sread_function() returned 0 (zero).SIO_FLUSHOUTPUT after the buffer was successfully written.long as 32-bits.long. Whence is one of SIO_SEEK_SET,
SIO_SEEK_CUR or SIO_SEEK_END, seeking relative
to the start, current position or end.long as 32-bits.SIO_CLOSE_TRYLOCK which causes Sgcclose()
to return -1 with
errno set to EDEADLK if the stream is locked.
Alternatively, using SIO_CLOSE_FORCE the stream is closed
and released without gaining a lock. This should be safe because the
stream is garbage and thus no thread can use the lock.
In addition, Sgcclose() never raises a Prolog exception because Prolog interaction is not allowed from the blob release hook and there is no meaningful way to raise a Prolog exception from this context.
\n
character. On end-of-file or an error, NULL is returned. If
the input line is longer that n bytes buf is not
0-terminated.Sfgets(buf,
Slinesize, Sinput). Deletes the terminating \n
character. Slinesize is a global variable that defines the
length of the input buffer. Deprecated.SIO_RP_BLOCK, fill the buffer (possibly blocking) if the
buffer is empty. Update the stream position information unless flags
include SIO_RP_NOPOS. This function effectively provides
functionality similar to POSIX read() on a stream. This function
is used by read_pending_codes/3.SIO_GETPENDING.Sfputs(q,
Soutput).% escape sequences. The % character is
followed by numeric arguments and modifier characters. The generic
format of this is described by the regular expression [+-0 #]*(\d*|\*)(.(\d*|\*))?.
Here, +-0 0-padding and, a space white-space
padding and #*
This sequence is followed by optional type information. For integers
this is one of l (long), ll (long
long) or
z (size_t). For strings this is one of L
(ISO Latin 1), U (UTF-8) or W (wchar_t*).
Finally we come to the format specifier. This is one of
%%cpdil (long), ll
(long long) or z (size_t) denote
the size.
ouxXfeEgGdouble.
s
Unlike the POSIX fprintf(), this function, and the related
functions (Svprintf(),
etc.) returns the number of characters written. Due to multibyte
encodings the number of bytes written can be more. On error, it returns
a negative value; in some cases there is extra information (e.g., in errno)
but it cannot be relied on.
Each call to Sfprintf()
is atomic in the sense that another thread that calls Sfprintf()
on the same stream will block. If you wish to do a series of print
statements without any other thread interleaving, you should call PL_acquire_stream()
and use its returned IOSTREAM* value, then call
PL_release_stream()
at the end of the print statements.
"%Ws"
or "%Us".-1 is returned rather than
the number of bytes that would be written. Future versions may improve
compatibility with the POSIX functions."%Ws"
or "%Us"."%Ws"
and "%Us".INVALID_SOCKETNULL, asking the system to allocate a
buffer or points at a buffer of (at least) the indicated size long. The
default buffer size is defined by the C macro SIO_BUFSIZE
PL_WRT_QUOTEDPL_WRT_IGNOREOPSPL_WRT_NUMBERVARSPL_WRT_PORTRAYPL_WRT_CHARESCAPESPL_WRT_NO_CHARESCAPESPL_WRT_NO_CHARESCAPES does not map to a write_term/2
option. If one of PL_WRT_CHARESCAPES or PL_WRT_NO_CHARESCAPES
is specified, character escapes are (not) applied. If neither is
specified the default depends, like for write/1,
on the
character_escapes
flag on the module
user.243Prior to
version 9.1.6 the default (no flag) was to escape the quotes and the
backslash (\PL_WRT_BACKQUOTED_STRINGPL_WRT_ATTVAR_IGNOREPL_WRT_ATTVAR_DOTSPL_WRT_ATTVAR_WRITEPL_WRT_ATTVAR_PORTRAYPL_WRT_BLOB_PORTRAYPL_WRT_NO_CYCLESPL_WRT_NEWLINEPL_WRT_VARNAMESPL_WRT_BACKQUOTE_IS_SYMBOLPL_WRT_DOTLISTSPL_WRT_BRACETERMSPL_WRT_NODICTPL_WRT_NODOTINATOMPL_WRT_NO_LISTSPL_WRT_RAT_NATURALPL_WRT_CHARESCAPES_UNICODEPL_WRT_QUOTE_NON_ASCIIPL_WRT_PARTIAL
For example, to print a term to user_error as the
toplevel does, use
PL_write_term(Suser_error, t, 1200,
PL_WRT_QUOTED|PL_WRT_PORTRAY|
PL_WRT_VARNAMES|PL_WRT_NEWLINE)
TRUE if the stream is in an error condition,
FALSE if the stream is valid and in normal condition and -1
if the stream is invalid.SIO_WARN or SIO_FERR. This
causes PL_release_stream()
to print a message (SIO_WARN) or raise an exception (SIO_FERR).SIO_FERR condition on the stream. If an exception is
assocated PL_release_stream()
raises this exception.
IOSTREAM has a field encoding that is
managed at initialization from SIO_TEXT. The available
encodings are defined as a C enum as below.
typedef enum
{ ENC_UNKNOWN = 0, /* invalid/unknown */
ENC_OCTET, /* raw 8 bit input */
ENC_ASCII, /* US-ASCII (0..127) */
ENC_ISO_LATIN_1, /* ISO Latin-1 (0..256) */
ENC_ANSI, /* default (multibyte) codepage */
ENC_UTF8,
ENC_UNICODE_BE, /* big endian unicode file */
ENC_UNICODE_LE, /* little endian unicode file */
ENC_WCHAR /* wchar_t */
} IOENC;
Binary streams always have the encoding ENC_OCTET.
The default encoding of a text stream depends on the Prolog flag
encoding. The
encoding is used by all functions that perform text I/O on a stream. The
encoding can be changed at any moment using Ssetenc()
which is available from Prolog using the set_stream/2
encoding(Encoding) property. Functions that explicitly
manage the encoding are:
NULL, return the old encoding. This function may
fail, returning -1 if the Scontrol_function() of the stream
returns -1 on the SIO_SETENCODING request. On success it
returns 0. If
new_enc is ENC_OCTET the stream is switched to
binary mode. Otherwise text mode is enabled.SIO_BOM
is set on the stream. Possibly resulting encodings are ENC_UTF8,
ENC_UNICODE_BE and ENC_UNICODE_LE.ENC_UTF8, ENC_UNICODE_BE
or
ENC_UNICODE_LE it writes the code point \ufeff
(a zero-width white space) to the stream in the current encoding and
sets the SIO_BOM flag on the stream.
Text streams have a field newline that controls the
handling of the newline convention. Note that inside Prolog all lines
end with a single newline (\u000a, \n) code
point. The values are described below. The default depends on the OS and
can be manipulated using the newline(Mode) property of set_stream/2.
SIO_NL_DETECTSIO_NL_POSIXSIO_NL_DOS\n) as \r\n. Discard \r
from the input.244The current
implementation does not check that the character is followed by \
The IOSTREAM has a field position that
points at a structure of type IOPOS. This structure is
defined as below.
typedef struct io_position
{ int64_t byteno; /* byte-position in file */
int64_t charno; /* character position in file */
int lineno; /* lineno in file */
int linepos; /* position in line */
intptr_t reserved[2]; /* future extensions */
} IOPOS;
If a stream is created using the flag SIO_RECORDPOS the
IO functions maintain the position information. Note that, supporting
the ISO stream position data (see stream_property/2),
both the byte and character position is maintained. These may differ if
the stream uses a multibyte encoding.
The linepos is updated as follows: \n and \r
reset the position to 0 (zero). The backspace (\b)
decrements the position if it is positive. The tab (\t)
tabs to the next multiple of 8. Any other character increments the line
position by one. Future versions may change that, notably the tab width
might no longer be hard coded.
The functions in this sections are intended to support blobs
to define save()
and load()
functions so they can be part of a saved state or .qlf
file. The matching pair of functions is guaranteed to give the same
result, regardless of byte ordering (big or little endian). The user
must not make any assumptions on the exact data format used for storing
the data. The atom read/write functions can only be used from the blob
callback functions.
For saving an uninterpreted array of bytes, it is suggested that the
length is output as a size_t value using PL_qlf_put_uint32()
followed by the bytes using Sfwrite();
and for loading, the length is read using PL_qlf_get_uint32(),
a buffer is allocated, and the bytes are read using Sfread().