6.47 Raw C strings

The following functions perform operations on raw ASCII coded strings terminated by a zero byte, for short ASCIIZ strings; some functions act upon raw UTF-16 strings. The following bindings are exported by the libraries (vicare) and (vicare system $foreign) and reexported by the library (vicare ffi).

Function: bytevector->cstring bv

Function: bytevector->guarded-cstring bv

Convert from a Scheme bytevector to an ASCIIZ string. If successful return a pointer object referencing the string, else return #f.

Memory allocated by bytevector->cstring must be explicitly released by free; memory allocated by bytevector->guarded-cstring is automatically released by the garbage collector whenever the returned pointer is garbage collected.

Function: bytevector->cstring* bv

Function: bytevector->guarded-cstring* bv

Like bytevector->cstring and bytevector->guarded-cstring, but if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error.

Function: cstring->bytevector pointer

Function: cstring->bytevector pointer count

Convert between an ASCIIZ string and a Scheme bytevector. When used, count must be a fixnum representing the number of bytes to include in the bytevector.

Function: string->cstring str

Function: string->guarded-cstring str

Convert from a Scheme string to an ASCIIZ string. If successful return a pointer object referencing the string, else return #f.

The string argument must contain only characters with Unicode code points in the range [0, 255].

Memory allocated by string->cstring must be explicitly released by free; memory allocated by string->guarded-cstring is automatically released by the garbage collector whenever the returned pointer is garbage collected.

Function: cstring16->bytevector pointer

Convert between an UTF-16 string and a Scheme bytevector; this function works with all the possible encodings of the string. The end of the string is determined by searching for a sequence of two consecutive zero bytes, starting at even offset.

Function: cstring16n->string pointer

Function: cstring16le->string pointer

Function: cstring16be->string pointer

Like cstring16->bytevector, but convert the result to a Scheme string assuming the specified byte order (native, little endian, big endian).

Function: string->cstring* str

Function: string->guarded-cstring* str

Like string->cstring and string->guarded-cstring, but if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error.

Function: cstring->string pointer

Function: cstring->string pointer count

Convert between an ASCIIZ string and a Scheme string. When used, count must be a fixnum representing the number of bytes to include in the string.

Function: strlen pointer

Interface to the C function strlen(), (libc)strlen. Return an exact integer representing the length of the ASCIIZ string referenced by pointer.

Function: strcmp pointer1 pointer2

Interface to the C function strcmp(), (libc)strcmp. Return a fixnum representing the classic comparison ternary result of comparing the ASCIIZ strings referenced by pointer1 and pointer2.

Function: strncmp pointer1 pointer2 count

Interface to the C function strncmp(), (libc)strncmp. Return a fixnum representing the classic comparison ternary result of comparing the first count bytes in the ASCIIZ strings referenced by pointer1 and pointer2. count must be an exact integer in the range of the C language type size_t.

Function: strdup pointer

Function: guarded-strdup pointer

Interface to the C function strdup(), (libc)strdup. Duplicate the ASCIIZ string referenced by pointer; if successful return a new pointer object, if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error

Memory allocated by strdup must be explicitly released by free; memory allocated by guarded-strdup is automatically released by the garbage collector whenever the returned pointer is garbage collected.

Function: strndup pointer count

Function: guarded-strndup pointer count

Interface to the C function strndup(), (libc)strndup. Duplicate the first count bytes in the ASCIIZ string referenced by pointer; if successful return a new pointer object, if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error. count must be an exact integer in the range of the C language type size_t.

Memory allocated by strdup must be explicitly released by free; memory allocated by guarded-strdup is automatically released by the garbage collector whenever the returned pointer is garbage collected.

Function: bytevectors->argv list-of-bytevectors

Function: bytevectors->guarded-argv list-of-bytevectors

Given a list of bytevectors: convert them into ASCIIZ strings and build a NULL terminated array of C pointers referencing the strings. The strings and the array are stored in a single memory block. If successful return the pointer object; if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error.

Memory allocated by bytevectors->argv must be explicitly released by free; memory allocated by bytevectors->guarded-argv is automatically released by the garbage collector whenever the returned pointer is garbage collected.

Function: argv->bytevectors pointer

Given a pointer to a NULL terminated array of C pointers referencing ASCIIZ strings: build and return a list of bytevectors holding the same bytes of the strings.

Function: strings->argv list-of-strings

Function: strings->guarded-argv list-of-strings

Given a list of Scheme strings: convert them into ASCIIZ strings and build a NULL terminated array of C pointers referencing the strings. If successful return a pointer to the array; if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error. The strings and the array are stored in a single memory block.

The string arguments must contain only characters with Unicode code points in the range [0, 255].

Memory allocated by strings->argv must be explicitly released by free; memory allocated by strings->guarded-argv is automatically released by the garbage collector whenever the returned pointer is garbage collected.

Function: argv->strings pointer

Given a pointer to a NULL terminated array of C pointers referencing ASCIIZ strings: build and return a list of strings holding the same bytes of the strings.

Function: argv-length argv

Return the number of strings in the NULL–terminated array of strings referenced by the argv pointer.