cking, garbage
collection and stack-shifts, so generally the only safe operations are
to pass it immediately to a C function that doesn't involve Prolog.
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_STACK implies, if the data is not static (as from an
atom), that the data is pushed on a stack. 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_STACKis 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_VARIABLEandCVT_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_STACK
- Data is stored on a stack. The older
BUF_RINGis an alias forBUF_STACK. See section 12.4.12. - 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.