- Reference manual
- Foreign Language Interface
- Foreign access to Prolog IO streams
- Get IO stream handles
- Creating an IO stream
- Interacting with foreign streams
- Writing Prolog terms to foreign streams
- Foreign stream error handling
- Foreign stream encoding
- Foreign stream line endings
- Foreign stream position information
- Support functions for blob save/load
- Foreign access to Prolog IO streams
- Foreign Language Interface
- Reference manual
- int Sset_timeout(IOSTREAM *s, int milliseconds)
- Set the timeout on an input stream to milliseconds. If this value is non-negative the the poll() or select() API is used to wait until input is available. If no input is available within the specified time an error is raised on the stream.
- int Sunit_size()
- Returns the size of a code unit in bytes depending on the stream's
encoding. This returns 2 for the encodings
ENC_WCHARand 1 for all other encodings (including multibyte encodings such as
- int Sputc(int c, IOSTREAM *s)
- Emit a byte to s. Flushes the buffer on
SIO_LBUFbuffering mode and updates the stream position information if enabled (
SIO_RECORDPOS). Returns 0 on success, -1 on error.
- int Sgetc(IOSTREAM *s)
- Read a byte from s. Fills the input buffer if buffering is
enabled and the buffer is empty. Updates the stream position information
if enabled (
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.
- int Sfgetc(IOSTREAM *s)
- Function equivalent to Sgetc().
- int Sungetc(int c, IOSTREAM *s)
- Put a byte back into the input buffer. Returns -1 if this is not possible. Deprecated. New code should use Speekcode() because that reliably maintains the position information on the stream.
- int Sputcode(int c, IOSTREAM *s)
- Emit a Unicode code point to s. This function also performs
newline encoding (see section
12.9.6). If the encoding of s cannot represent c,
the behaviour depends on the the following flags. Only one of these
flags may be enabled. If none of these flags is enabled an error is
raised and the function returns -1.
- Emit as XML character entity, e.g.
- Emit as ISO escape, e.g.,
- Emit as Unicode escape, e.g.,
Updates the stream position information if enabled (
- int Sgetcode(IOSTREAM *s)
- Read a Unicode code point from s. If it detects an invalid
multibyte character a warning is emitted and the code point
0xfffdis returned. Other errors and end-of-file return -1; Use Sferror() or Sfeof() to distinguish end of file from an error.
- int Speekcode(IOSTREAM *s)
- As Sgetcode(),
but leaves the character in the input buffer and does not update the
stream position. Returns -1 if the stream is not buffered (
- int Sputw(int w, IOSTREAM *s)
- int Sgetw(IOSTREAM *s)
- Reads/writes an integer in native byte order. Deprecated.
- int Sfread(void *data, size_t size, size_t elems, IOSTREAM *s)
- int Sfwrite(const void *data, size_t size, size_t elems, IOSTREAM *s)
- Emulations of the POSIX fread() and fwrite() calls for Prolog streams. These functions read or write elems objects of size size and return the number of objects successfully read or written. Data exchange is binary (even if the stream is in text mode) and unlike read() and write(), these functions keep reading or writing until end-of-file (for Sfread()) or an error.
- int Sfeof(IOSTREAM *s)
- Returns non-zero if the stream is at the end. It performs the following
checks: (1) test the
SIO_FEOFflag, (2) test whether the buffer is non-empty, (3) fill the buffer and return non-zero if the Sread_function() returned 0 (zero).
- int Sfpasteof(IOSTREAM *s)
- Returns non-zero when a read operation was performed after signalling end-of-file. On other words, reaching end-of-file first triggers Sfeof() and after another read triggers Sfpasteof().
- int Ssetlocale(IOSTREAM *s, struct PL_locale *new_loc, struct PL_locale **old_loc)
- Change the locale associated with a stream. The current system does not provide a public C API for dealing with Prolog locale objects. See section 4.23.
- int Sflush(IOSTREAM *s)
- Flush buffered output, returning 0 on success and -1 after a (write)
error occurred. Calls Scontrol_function() using the action
SIO_FLUSHOUTPUTafter the buffer was successfully written.
- int64_t Ssize(IOSTREAM *s)
- Returns the size in bytes of the object associated to the stream or -1 if this is not known.
- int Sseek(IOSTREAM *s, long pos, int whence)
- int Sseek64(IOSTREAM *s, int64_t pos, int whence)
- Reposition the file pointer in the object associated to s,
returning 0 on success and -1 otherwise. If the stream is buffered and
position information is maintained these functions readjust the buffer
information if possible. Otherwise they call Sseek64_function()
or Sseek_function() as a fallback iff pos can be
represented as a C
long. Whence is one of
SIO_SEEK_END, seeking relative to the start, current position or end.
- long Stell(IOSTREAM *s)
- int64_t Stell64(IOSTREAM *s)
- Return the current position in the stream. This is obtained from the recorded position or based on information from the seek handlers, adjusted with the buffer information.
- int Sclose(IOSTREAM *s)
- Close the stream. This first locks the stream (see PL_acquire_stream()). When successful it flushes pending output and calls the Sclose_function() hook. Finally, the stream is unlocked and all memory associated to the stream is released. On success, the function returns 0. On failure a Prolog exception is raised and the return value is -1. Regardless of the return value, s becomes invalid after completion of Sclose(). See also Sgcclose().
- int Sgcclose(IOSTREAM *s, int flags)
- As Sclose(),
but intended to be used from the atom garbage collector if a stream is
closed because it is garbage. The SWI-Prolog atom garbage collector
normally runs in a separate thread and thus may be unable to obtain a
lock on s if some thread lost access to the stream while it
is locked. For this situation flags may be
SIO_CLOSE_TRYLOCKwhich causes Sgcclose() to return -1 with errno set to
EDEADLKif the stream is locked. Alternatively, using
SIO_CLOSE_FORCEthe 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.
- char* Sfgets(char *buf, int n, IOSTREAM *s)
- Read a line of input as a sequence of bytes. The buf
is n bytes long. On success, buf is returned and
contains a 0-terminated C string that ends with a
\ncharacter. On end-of-file or an error,
NULLis returned. If the input line is longer that n bytes buf is not 0-terminated.
- int Sgets(char *buf)
- Shorthand for
Sfgets(buf, Slinesize, Sinput). Deletes the terminating
\ncharacter. Slinesize is a global variable that defines the length of the input buffer. Deprecated.
- int Sread_pending(IOSTREAM *s, char *buf, size_t limit, int flags)
- Return the data buffered on an input stream. If flags
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.
- size_t Spending(IOSTREAM *s)
- Return the number of bytes that can be read from s without
blocking. If there is buffered input, this is the number of bytes
buffered. Otherwise it is the result of the Scontrol_function()
using the action
- int Sfputs(const char *q, IOSTREAM *s)
- Emit a 0-terminated C string. The input string q is handled as a sequence of unsigned characters (code points 1 ... 255.
- int Sputs(const char *q)
- Equivalent to
- int Sfprintf(IOSTREAM *s, const char *fm, ...)
- Similar to POSIX fprintf(). This function largely accepts the same
%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,
00-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
long long) or
size_t). For strings this is one of
L(ISO Latin 1),
Finally we come to the format specifier. This is one of
Emit a Unicode code point.
Emit a pointer.
Emit a a signed integer as decimal. The
long long) or
size_t) denote the size.
Emit a a unsigned integer as octal, decimal or hexadecimal.
Emit a 0-terminated string.
Unlike the POSIX fprintf(), this function, and the related functions
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
but it cannot be relied on.
-1is returned rather than the number of bytes that would be written. Future versions may improve compatibility with the POSIX functions.
NULL, 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
- int PL_write_term(IOSTREAM *s, term_t term, int precedence, int flags)
- Write term to s. precedence is the
initial operator precedence, typically 1200. flags is a
bitwise or of the constants below. These flags map to options for write_term/2.
PL_WRT_NO_CHARESCAPESdoes not map to a write_term/2 option. If one of
PL_WRT_NO_CHARESCAPESis 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.236Prior to version 9.1.6 the default (no flag) was to escape the quotes and the backslash (