c('PL_get_chars')

Availability:C-language interface function

int PL_get_chars(term_t +t, char **s, unsigned flags)

Convert the argument term t to a 0-terminated C-string. flags is a bitwise disjunction from two groups of constants. The first specifies which term types should be converted and the second how the argument is stored. Below is a specification of these constants. BUF_RING implies, if the data is not static (as from an atom), that the data is copied to the next buffer from a ring of 16 buffers. This is a convenient way of converting multiple arguments passed to a foreign predicate to C-strings. If BUF_MALLOC is used, the data must be freed using PL_free() when no longer needed.

With the introduction of wide characters (see section 2.19.1), not all atoms can be converted into a char*. This function fails if t is of the wrong type, but also if the text cannot be represented. See the REP_* flags below for details.

CVT_ATOM: Convert if term is an atom.
CVT_STRING: Convert if term is a string.
CVT_LIST: Convert if term is a list of of character codes.
CVT_INTEGER: Convert if term is an integer.
CVT_FLOAT: Convert if term is a float. The characters returned are the same as write/1 would write for the floating point number.
CVT_NUMBER: Convert if term is an integer or float.
CVT_ATOMIC: Convert if term is atomic.
CVT_VARIABLE: Convert variable to print-name
CVT_WRITE: Convert any term that is not converted by any of the other flags using write/1. If no BUF_* is provided, BUF_RING is implied.
CVT_WRITE_CANONICAL: As CVT_WRITE, but using write_canonical/2.
CVT_WRITEQ: As CVT_WRITE, but using writeq/2.
CVT_ALL: Convert if term is any of the above, except for CVT_VARIABLE and CVT_WRITE*.
CVT_EXCEPTION: If conversion fails due to a type error, raise a Prolog type error exception in addition to failure
BUF_DISCARDABLE: Data must copied immediately
BUF_RING: Data is stored in a ring of buffers
BUF_MALLOC: Data is copied to a new buffer returned by PL_malloc(3). When no longer needed the user must call PL_free() on the data.
REP_ISO_LATIN_1: Text is in ISO Latin-1 encoding and the call fails if text cannot be represented. This flag has the value 0 and is thus the default.
REP_UTF8: Convert the text to a UTF-8 string. This works for all text.
REP_MB: Convert to default locale-defined 8-bit string. Success depends on the locale. Conversion is done using the wcrtomb() C library function.