Summary of WCX features in the foreign interface

All strings passed to foreign code, or expected from foreign code, which correspond to atoms or lists of character codes on the Prolog side, are in the internal encoding form, UTF-8. Note that this is of concern only if the strings contain non-ASCII characters (e.g. accented letters in the latin1 encoding).

Specifically, the C arguments corresponding to the following foreign specifications are passed and received as strings in the internal encoding:

     +chars +string +string(N)
     -chars -string -string(N)
     [-chars] [-string] [-string(N)]
     

Similarly, the following functions defined in the foreign interface expect and deliver internally encoded strings in their char * and char ** arguments.

     int SP_put_string(SP_term_ref t, char *name)
     int SP_put_list_chars(SP_term_ref t, SP_term_ref tail, char *s)
     int SP_put_list_n_chars(SP_term_ref t, SP_term_ref tail,
                         long n, char *s)
     int SP_get_string(SP_term_ref t, char **name)
     int SP_get_list_chars(SP_term_ref t, char **s)
     int SP_get_list_n_chars(SP_term_ref t, SP_term_ref tail,
                         long n, long *w, char *s)
     void SP_puts(char *string)
     void SP_fputs(char *string, SP_stream *s)
     int  SP_printf(char *format, ...)
     int  SP_fprintf(SP_stream *s, char *format, ...)
     SP_atom SP_atom_from_string(char *s)
     char *SP_string_from_atom(SP_atom a)
     SP_pred_ref SP_predicate(char *name_string,
                          long arity,
                          char *module_string)
     int SP_load(char *filename)
     int SP_restore(char *filename)
     int SP_read_from_string()
     

The following functions deliver or accept wide character codes (up to 31 bits), and read or write them on the appropriate stream in the external encoding form:

     int  SP_getc(void)
     int  SP_fgetc(SP_stream *s)
     void SP_putc(int c)
     void SP_fputc(int c, SP_stream *s)
     

In the following function, strings are expected in the encoding format relevant for the operating system:

     int SP_initialize(int argc, char **argv, char *boot_path)
     

Here, argv is an array of strings, as received from the operating system. These strings will be transformed to internal form using the wcx_from_os(WCX_OPTION,...) hook function. Also boot_path is expected to be in the format file names are encoded, and wcx_from_os(WCX_FILE,...) will be used to decode it.

There are other functions in the foreign interface that take or return strings. For these, the encoding is not relevant, either because the strings are guaranteed to be ASCII (SP_error_message(), SP_put_number_chars(), SP_get_number_chars()), or because the strings in question have no relation to Prolog code, as in SP_on_fault(), SP_raise_fault().

The SP_make_stream_context() foreign interface function is a variant of SP_make_stream() with two additional arguments: option and context. This extended form can be used to create streams from C with specified WCX features.

The context argument the SP_make_stream_context function can be one of the following values:

     SP_STREAMHOOK_WCI
     SP_STREAMHOOK_BIN
     SP_STREAMHOOK_C, SP_STREAMHOOK_C+1, ...
     

SP_STREAMHOOK_WCI means that input and output on the given stream should be performed using the SICStus internal encoding scheme, UTF-8, while SP_STREAMHOOK_BIN indicates that no encoding should be applied (binary files).

In the last two cases the wcx_open hook will not be called. In all other cases SP_make_stream_context will call the wcx_open hook function, with the option and context supplied to it. The option argument of SP_make_stream_context can be the standard representation of a Prolog atom, or the constant SP_WCX_FLAG, which prescribes that the value of the prolog flag wcx should be supplied to the open hook function.

The user may add further context constants for his own use, with values greater than SP_STREAMHOOK_C.