$nl
"Passing a Factor string to a C function expecting a " { $link c-string } " allocates a " { $link byte-array } " in the Factor heap; the string is then converted to the requested format and a raw pointer is passed to the function."
$nl
-"If the conversion fails, for example if the string contains null bytes or characters with values higher than 255, a " { $link c-string-error. } " is thrown."
-$nl
"Care must be taken if the C function expects a pointer to a string with its length represented by another parameter rather than a null terminator. Passing the result of calling " { $link length } " on the string object will not suffice. This is because a Factor string of " { $emphasis "n" } " characters will not necessarily encode to " { $emphasis "n" } " bytes. The correct idiom for C functions which take a string with a length is to first encode the string using " { $link encode } ", and then pass the resulting byte array together with the length of this byte array."
$nl
"Sometimes a C function has a parameter type of " { $link void* } ", and various data types, among them strings, can be passed in. In this case, strings are not automatically converted to aliens, and instead you must call one of these words:"
HELP: array-size-error.
{ $error-description "Thrown by " { $link <array> } ", " { $link <string> } ", " { $link <vector> } " and " { $link <sbuf> } " if the specified capacity is negative or too large." } ;
-HELP: c-string-error.
-{ $error-description "Thrown by " { $link alien-invoke } " and various primitives if a string containing null bytes, or characters with values higher than 255 is passed in where a C string is expected. See " { $link "c-strings" } "." } ;
-
HELP: ffi-error.
{ $error-description "Thrown by " { $link dlopen } " and " { $link dlsym } " if a problem occurs while loading a native library or looking up a symbol. See " { $link "alien" } "." } ;
! basis/debugger/debugger.factor
! vm/errors.hpp
-CONSTANT: kernel-error-count 21
+CONSTANT: kernel-error-count 20
CONSTANT: ERROR-EXPIRED 0
CONSTANT: ERROR-IO 1
CONSTANT: ERROR-SIGNAL 5
CONSTANT: ERROR-ARRAY-SIZE 6
CONSTANT: ERROR-OUT-OF-FIXNUM-RANGE 7
-CONSTANT: ERROR-C-STRING 8
-CONSTANT: ERROR-FFI 9
-CONSTANT: ERROR-UNDEFINED-SYMBOL 10
-CONSTANT: ERROR-DATASTACK-UNDERFLOW 11
-CONSTANT: ERROR-DATASTACK-OVERFLOW 12
-CONSTANT: ERROR-RETAINSTACK-UNDERFLOW 13
-CONSTANT: ERROR-RETAINSTACK-OVERFLOW 14
-CONSTANT: ERROR-CALLSTACK-UNDERFLOW 15
-CONSTANT: ERROR-CALLSTACK-OVERFLOW 16
-CONSTANT: ERROR-MEMORY 17
-CONSTANT: ERROR-FP-TRAP 18
-CONSTANT: ERROR-INTERRUPT 19
-CONSTANT: ERROR-CALLBACK-SPACE-OVERFLOW 20
+CONSTANT: ERROR-FFI 8
+CONSTANT: ERROR-UNDEFINED-SYMBOL 9
+CONSTANT: ERROR-DATASTACK-UNDERFLOW 10
+CONSTANT: ERROR-DATASTACK-OVERFLOW 11
+CONSTANT: ERROR-RETAINSTACK-UNDERFLOW 12
+CONSTANT: ERROR-RETAINSTACK-OVERFLOW 13
+CONSTANT: ERROR-CALLSTACK-UNDERFLOW 14
+CONSTANT: ERROR-CALLSTACK-OVERFLOW 15
+CONSTANT: ERROR-MEMORY 16
+CONSTANT: ERROR-FP-TRAP 17
+CONSTANT: ERROR-INTERRUPT 18
+CONSTANT: ERROR-CALLBACK-SPACE-OVERFLOW 19
PRIMITIVE: callstack-for ( context -- array )
PRIMITIVE: retainstack-for ( context -- array )