• Places
    • Home
    • Graphs
    • Prefixes
  • Admin
    • Users
    • Settings
    • Plugins
    • Statistics
  • CPACK
    • Home
    • List packs
    • Submit pack
  • Repository
    • Load local file
    • Load from HTTP
    • Load from library
    • Remove triples
    • Clear repository
  • Query
    • YASGUI SPARQL Editor
    • Simple Form
    • SWISH Prolog shell
  • Help
    • Documentation
    • Tutorial
    • Roadmap
    • HTTP Services
  • Login

12.9 Foreign access to Prolog IO streams
AllApplicationManualNameSummaryHelp

  • Documentation
    • Reference manual
      • Foreign Language Interface
        • Foreign access to Prolog IO streams
          • Get IO stream handles
          • Creating an IO stream
          • Interacting with foreign streams
          • Foreign stream error handling
          • Foreign stream encoding
          • Foreign stream line endings
          • Foreign stream position information
    • Packages
/* 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:

int Ssetenc(IOSTREAM *s, IOENC new_enc, IOENC *old_enc)
Set the encoding for s to new_enc and, if old_enc is not 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.
int ScheckBOM(IOSTREAM *s)
This function may be called on a buffered input stream immediately after opening the stream. If the stream starts with a known Byte Order Mark (BOM) the encoding is set accordingly and the flag SIO_BOM is set on the stream. Possibly resulting encodings are ENC_UTF8, ENC_UNICODE_BE and ENC_UNICODE_LE.
int SwriteBOM(IOSTREAM *s)
This function writes a Byte Order Mark (BOM) to s and should be called immediately after opening a stream for writing. If the encoding is one of 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.
int Scanrepresent(int c, IOSTREAM *s)
Returns 0 if the encoding of s can represent the code point c and -1 otherwise.

12.9.6 Foreign stream line endings

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_DETECT
This mode may be enabled on an input stream. It causes the stream to read up to the first newline to set the newline mode accordingly.
SIO_NL_POSIX
Do not do any translation on input or output.
SIO_NL_DOS
Emit a newline (\n) as \r\n. Discard \r from the input.232The current implementation does not check that the character is followed by \n.

12.9.7 Foreign stream position information

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.

12.9.8 Support functions for blob save/load

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

int PL_qlf_put_int64(int64_t i, IOSTREAM *s)
int PL_qlf_put_int32(int32_t i, IOSTREAM *s)
int PL_qlf_put_uint32(uint32 i, IOSTREAM *s)
Write integers of several sizes. Signed integers are written in zigzag encoding. For unsigned integers we only write the non-zero bytes. The result is compact and the same for big or little endian.
int PL_qlf_put_double(double f, IOSTREAM *s)
Write double as 8 byte big endian.
int PL_qlf_put_atom(atom_t a, IOSTREAM *s)
Write an atom. The atom may be a blob. Note that this function may only be used from a blob save() function. Calling from another context results in a fatal error.
int PL_qlf_get_int64(IOSTREAM *s, int64_t *ip)
int PL_qlf_get_int32(IOSTREAM *s, int32_t *ip)
int PL_qlf_get_uint32(IOSTREAM *s, uint32_t *ip)
int PL_qlf_get_double(IOSTREAM *s, double *fp)
Counterparts of corresponding PL_qlf_put_*() functions.
int PL_qlf_get_atom(IOSTREAM *s, atom_t *ap)
Counterpart of PL_qlf_put_atom(). Again, this may only be used in the context of a blob load() function.

ClioPatria (version V3.1.1-42-gd6a756b-DIRTY)