- Documentation
- Reference manual
- Foreign Language Interface
- Foreign access to Prolog IO streams
- Get IO stream handles
- Creating an IO stream
- Interacting with foreign streams
- Sset_timeout()
- Sunit_size()
- Sputc()
- Sgetc()
- Sfgetc()
- Sungetc()
- Sputcode()
- Sgetcode()
- Speekcode()
- Sputw()
- Sgetw()
- Sfread()
- Sfwrite()
- Sfeof()
- Sfpasteof()
- Ssetlocale()
- Sflush()
- Ssize()
- Sseek()
- Sseek64()
- Stell()
- Stell64()
- Sclose()
- Sgcclose()
- Sfgets()
- Sgets()
- Sread_pending()
- Spending()
- Sfputs()
- Sputs()
- Sfprintf()
- Sprintf()
- Svprintf()
- Ssprintf()
- Ssnprintf()
- Svsprintf()
- Svsnprintf()
- Sdprintf()
- Svdprintf()
- Slock()
- StryLock()
- Sunlock()
- Sfileno()
- Swinsock()
- Sclosehook()
- Sset_filter()
- Ssetbuffer()
- Foreign stream error handling
- Foreign stream encoding
- Foreign stream line endings
- Foreign stream position information
- Foreign access to Prolog IO streams
- Foreign Language Interface
- Packages
- Reference manual
ms.html#Sgcclose()">Sgcclose().
int SfprintfX(IOSTREAM
*s, const char *fm, ...) Same as Sfprintf()
but doesn't have the format-checking attribute. This is intended for
formats that include extended format specifiers such as
int Sprintf(const
char *fm, ...) Similar to Sfprintf(),
printing to Soutput
int Svprintf(IOSTREAM
*s, const char *fm, va_list args) Variadic argument list version of Sfprintf().
int Ssprintf(char
*buf, const char *fm, ...) Print to a C string. Deprecated. Use Ssnprintf()
instead.
int Ssnprintf(char
*buf, size_t size, const char *fm, ...) Print to a C string, emitting a maximum of size bytes.
Returns the number of bytes written. Currently buf uses
int SsnprintfX(char
*buf, size_t size, const char *fm, ...) Same as Ssnprintf()
but doesn't have the format-checking attribute. This is intended for
formats that include extended format specifiers such as
int Svsprintf(char
*buf, const char *fm, va_list args) Variadic argument list version of Ssprintf().
Deprecated. Use
Svsnprintf()
instead.
int Svsnprintf(char
*buf, size_t size, const char *fm, va_list args) Variadic argument list version of Ssnprintf().
int Sdprintf(const
char *fm, ...) Print to Serror. This function should be used for printing
debug output from foreign code.
int SdprintfX(const
char *fm, ...) Same as Sdprintf()
but doesn't have the format-checking attribute. This is intended for
formats that include extended format specifiers such as
int Svdprintf(const
char *fm, va_list args) Variadic argument list version of Sdprintf().
int Slock(IOSTREAM
*s)
int StryLock(IOSTREAM
*s)
int Sunlock(IOSTREAM
*s) Low level versions that perform only the (un)locking part of
PL_acquire_stream()
and PL_release_stream().
int Sfileno(IOSTREAM
*s) If the stream is associated to a POSIX file handle, return this handle.
Returns -1 otherwise.
SOCKET Swinsock(IOSTREAM
*s) Windows only. If the stream is associated to a Windows socket handle,
returns this handle. Otherwise return
12.9.3 Interacting with foreign streams
- 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_UNICODE_BE
andENC_UNICODE_LE
,sizeof(wchar_t)
forENC_WCHAR
and 1 for all other encodings (including multibyte encodings such asENC_UTF8
. - int Sputc(int c, IOSTREAM *s)
- Emit a byte to s. Flushes the buffer on
\n
when inSIO_LBUF
buffering 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.
SIO_REPXML
- Emit as XML character entity, e.g.
႒
SIO_REPPL
- Emit as ISO escape, e.g.,
\x4242\
SIO_REPPLU
- Emit as Unicode escape, e.g.,
\u4242
or\U42424242
Updates the stream position information if enabled (
SIO_RECORDPOS
) - 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
0xfffd
is 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 (
SIO_NBUF
). - 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_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). - 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_FLUSHOUTPUT
after 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 ofSIO_SEEK_SET
,SIO_SEEK_CUR
orSIO_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_TRYLOCK
which causes Sgcclose() to return -1 with errno set toEDEADLK
if the stream is locked. Alternatively, usingSIO_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.
- 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
\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. - int Sgets(char *buf)
- Shorthand for
Sfgets(buf, Slinesize, Sinput)
. Deletes the terminating\n
character. 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
includes
SIO_RP_BLOCK
, fill the buffer (possibly blocking) if the buffer is empty. Update the stream position information unless flags includeSIO_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
SIO_GETPENDING
. - 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
Sfputs(q, Soutput)
. - 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,+
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
) orz
(size_t
). For strings this is one ofL
(ISO Latin 1),U
(UTF-8) orW
(wchar_t*
).Finally we come to the format specifier. This is one of
%
Emit the
character itself.%
c
Emit a Unicode code point.p
Emit a pointer.d
i
Emit a a signed integer as decimal. Thel
(long
),ll
(long long
) orz
(size_t
) denote the size.o
u
x
X
Emit a a unsigned integer as octal, decimal or hexadecimal.f
e
E
g
G
Emit adouble
.s
Emit a 0-terminated string.
This function returns the number of characters written. Note that due to multibyte encodings the number of bytes written can be more.
"%Ws"
.ENC_ISO_LATIN_1
encoding. Future versions will probably
change to ENC_UTF8
."%Ws"
."%Ws"
.INVALID_SOCK