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 and ENC_UNICODE_LE, sizeof(wchar_t) for ENC_WCHAR and 1 for all other encodings (including multibyte encodings such as ENC_UTF8.

int Sputc(int c, IOSTREAM *s)

Emit a byte to s. Flushes the buffer on \n when in SIO_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 of SIO_SEEK_SET, SIO_SEEK_CUR or 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_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.

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 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 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) 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

%
Emit the % character itself.

c
Emit a Unicode code point.

p
Emit a pointer.

d

i
Emit a a signed integer as decimal. The l (long), ll (long long) or z (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 a double.

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.

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 ENC_ISO_LATIN_1 encoding. Future versions will probably change to ENC_UTF8.

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 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 INVALID_SOCKET

int Sclosehook(void (*hook)(IOSTREAM *s))

Register a hook function to be called by Sclose() just before the stream is deallocated. This is used internally to update the Prolog administration of open streams on Sclose().

int Sset_filter(IOSTREAM *parent, IOSTREAM *filter)

Register filter as a stream that reads from or writes to the stream parent.

void Ssetbuffer(IOSTREAM *s, char *buf, size_t size)

Set the input or output buffer for s to size. The buf argument is either 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 SIO_BUFSIZE