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.8).
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++.
#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_NOERRORThe returned stream is owned by the calling thread using PL_acquire_stream().
FALSE with an
exception. Otherwise return TRUE.
Below is an example that writes “Hello World'' to a stream provided by Prolog.
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_NOMUTEXIf 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 ) // appearently moved
Sfree(s);
}
The mode is "r" or "w". The mode "rF"
calls
PL_free(*buffer)
at 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 intented to use write and other output predicates 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. Whence is one of SIO_SEEK_SET,
SIO_SEEK_CUR or SIO_SEEK_END, seeking relative
to the start, current position or end.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, + implies right alignment, -
left alignment, 0 0-padding and, a space white-space
padding and # modified output. The
two optional numerical arguments are separated by a full stop and may be *
to get them from the argument list. The first numerical argument
specifies the field width and the second the precision for floating
point numbers.
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
%% character itself.
cpdil (long), ll
(long long) or z (size_t) denote
the size.
ouxXfeEgGdouble.
sThis function returns the number of characters written. Note that due to multibyte encodings the number of bytes written can be more.
ENC_ISO_LATIN_1 encoding. Future versions will probably
change to ENC_UTF8.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
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 succcess 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.216The current
implementation does not check that the character is followed by \n.
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.