You can edit this page using wiki syntax for markup.

Article contents:[[tags: manual]] [[toc:]] == Foreign type specifiers Here is a list of valid foreign type specifiers for use in [[Accessing external objects|accessing external objects]]. === Void <type>void</type> Specifies an undefined return value. Not allowed as argument type. === Boolean <type>bool</type> As argument: any value ({{#f}} is false (zero), anything else is true (non-zero). As result: anything different from 0 and the {{NULL}} pointer is {{#t}}. This type maps to {{int}} in both C and C++. === Characters <type>char</type><br> <type>unsigned-char</type><br> A signed or unsigned character. As an argument, the input Scheme character is cast to C {{char}} or {{unsigned char}}, resulting in an 8-bit value. A Scheme character with an integer value outside 0-127 (signed) or 0-255 (unsigned) will be silently truncated to fit; in other words, don't feed it UTF-8 data. As a return type, accepts any valid Unicode code point; the return type is treated as a C int, and converted to a Scheme character. === Integers <type>byte</type><br> <type>unsigned-byte</type><br> An 8-bit integer value in range -128 - 127 (byte) or 0 - 255 (unsigned byte). Values are cast to and from C {{char}} or {{unsigned char}} type, so values outside this 8-bit range will be unceremoniously truncated. <type>short</type><br> <type>unsigned-short</type><br> A short integer number in 16-bit range. Maps to C {{short}} or {{unsigned short}}. <type>int</type><br> <type>unsigned-int</type><br> <type>int32</type><br> <type>unsigned-int32</type><br> An integer number in fixnum range (-1073741824 to 1073741823, i.e. 31 bit signed). {{unsigned-int}} further restricts this range to 30 bit unsigned (0 to 1073741823). {{int}} maps to C type {{int}} and {{int32}} maps to {{int32_t}}. As an argument type, these expect a fixnum value, and as a return type they return a fixnum. Values outside the ranges prescribed above are silently truncated; you should use e.g. {{integer}} if you need the full 32-bit range. Note: {{int32}} is not recognized as an argument type prior to CHICKEN 4.7.2. Notes for 64-bit architectures: * C's {{int}} is 32 bits on most 64-bit systems ([[https://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models|LP64]]), so {{int}} and {{int32}} are functionally (if not semantically) equivalent. * The fixnum type is larger than 32 bits and consequently the entire signed or unsigned 32-bit range is available for this type on 64-bit systems. However, for compatibility with 32-bit systems it is probably unwise to rely on this. If you need a 32-bit range, you should use (unsigned) {{integer}} or {{integer32}}. <type>integer</type><br> <type>unsigned-integer</type><br> <type>integer32</type><br> <type>unsigned-integer32</type><br> A fixnum or bignum, mapping to {{int}} or {{int32_t}} or their unsigned variants. When outside of fixnum range the value will overflow into a bignum. Prior to CHICKEN 5, the value would overflow into a flonum. C's {{int}} is 32 bits on most 64-bit systems ([[https://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models|LP64]]), so {{integer}} and {{integer32}} are functionally (if not semantically) equivalent. <type>integer64</type><br> <type>unsigned-integer64</type> A fixnum or bignum, mapping to {{int64_t}} or {{uint64_t}}. When outside of fixnum range the value will overflow into a bignum. Prior to CHICKEN 5, the value would overflow into a flonum. <type>long</type><br> <type>unsigned-long</type> A fixnum or bignum, mapping to {{long}} or {{unsigned long}}. Similar to {{integer32}} on 32-bit systems or {{integer64}} on 64-bit. <type>size_t</type> <type>ssize_t</type> A direct mapping to C's {{size_t}} and {{ssize_t}}. === Floating-point <type>float</type><br> <type>double</type> A floating-point number. If an exact integer is passed as an argument, then it is automatically converted to a float. <type>number</type> A floating-point number. Similar to {{double}}, but when used as a result type, then either an exact integer or a floating-point number is returned, depending on whether the result fits into an exact integer or not. === Strings <type>c-string</type><br> <type>nonnull-c-string</type> A zero-terminated C string. The argument value {{#f}} is allowed and is passed as a {{NULL}} pointer; similarly, a NULL pointer is returned as {{#f}}. Note that the string contents are copied into (automatically managed) temporary storage with a zero byte appended when passed as an argument. Also, a return value of this type is copied into garbage collected memory using {{strcpy(3)}}. For the {{nonnull-}} variant, passing {{#f}} will raise an exception, and returning a NULL pointer will result in undefined behavior (e.g. a segfault). <type>c-string*</type><br> <type>nonnull-c-string*</type> Similar to {{c-string}} and {{nonnull-c-string}}, but if used as a result type, the pointer returned by the foreign code will be freed (using the C library's {{free(3)}}) after copying. This type specifier is not valid as a result type for callbacks defined with {{define-external}}. <type>unsigned-c-string</type><br> <type>nonnull-unsigned-c-string</type><br> <type>unsigned-c-string*</type><br> <type>nonnull-unsigned-c-string*</type><br> Same as {{c-string}}, {{nonnull-c-string}}, etc. but mapping to C's {{unsigned char *}} type. <type>c-string-list</type><br> <type>c-string-list*</type> Takes a pointer to an array of C strings terminated by a {{NULL}} pointer and returns a list of strings. The starred version {{c-string-list*}} also releases the storage of each string and the pointer array afterward using {{free(1)}}. Only valid as a result type, and can only be used with non-callback functions. <type>symbol</type> A symbol, which will be passed to foreign code as a zero-terminated string. When declared as the result of foreign code, the result should be a string and a symbol with the same name will be interned in the symbol table (and returned to the caller). Attempting to return a NULL string will raise an exception. === Bytevectors <type>blob</type><br> <type>nonnull-blob</type> A blob object, passed as a pointer to its contents. Permitted only as argument type, not return type. Arguments of type {{blob}} may optionally be {{#f}}, which is passed as a NULL pointer. For the {{nonnull-}} variant, passing a {{#f}} value will raise an exception. <type>u8vector</type><br> <type>u16vector</type><br> <type>u32vector</type><br> <type>u64vector</type><br> <type>s8vector</type><br> <type>s16vector</type><br> <type>s32vector</type><br> <type>s64vector</type><br> <type>f32vector</type><br> <type>f64vector</type><br> <type>nonnull-u8vector </type><br> <type>nonnull-u16vector </type><br> <type>nonnull-u32vector </type><br> <type>nonnull-u64vector </type><br> <type>nonnull-s8vector </type><br> <type>nonnull-s16vector</type><br> <type>nonnull-s32vector</type><br> <type>nonnull-s64vector</type><br> <type>nonnull-f32vector</type><br> <type>nonnull-f64vector</type><br> A [[Module srfi-4|SRFI-4]] number-vector object, passed as a pointer to its contents. These are allowed only as argument types, not as return types. The value {{#f}} is also allowed and is passed to C as a NULL pointer. For the {{nonnull-}} variants, passing {{#f}} will raise an exception. === Pointers <type>c-pointer</type><br> <type>(c-pointer TYPE)</type><br> <type>nonnull-c-pointer</type><br> <type>(nonnull-c-pointer TYPE)</type><br> An operating-system pointer or a locative. {{c-pointer}} is untyped, whereas {{(c-pointer TYPE)}} points to an object of foreign type TYPE. The value {{#f}} is allowed and is passed to C as a {{NULL}} pointer; similarly, NULL is returned as {{#f}}. For the two {{nonnull-}} variants, passing {{#f}} will raise an exception, and returning NULL will result in a null {{pointer}} object. (Note: It is still possible to deliberately pass a null pointer through a {{nonnull-c-pointer}} by manually creating a null pointer object, e.g. via {{(address->pointer 0)}}.) <type>pointer-vector</type><br> <type>nonnull-pointer-vector</type> A vector of foreign pointer objects; see [[/man/5/Module (chicken memory)#pointer-vectors|Pointer vectors]]. Permitted only as an argument type, not as return type. This type was introduced in CHICKEN 4.6.3. A pointer vector contains a C array of void pointers, and the argument is passed as a {{void **}} pointer to these contents. Just as for bytevector types, you must somehow communicate the length of this array to the callee; there is no sentinel node or NULL terminator. {{#f}} is allowed and passed as a {{NULL}} pointer. For the {{nonnull-}} variant, passing a {{#f}} value will raise an exception. <type>(ref TYPE)</type> A C++ reference type. Reference types are handled the same way as pointers inside Scheme code. <type>(function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])</type> A function pointer. {{CALLCONV}} specifies an optional calling convention and should be a string. The meaning of this string is entirely platform dependent. The value {{#f}} is also allowed and is passed as a {{NULL}} pointer. === Scheme objects <type>scheme-object</type> An arbitrary, raw Scheme data object (immediate or non-immediate). A {{scheme-object}} is passed or returned as a {{C_word}}, the internal CHICKEN type for objects. Typically, this consists of an object header and tag bits. It is up to you to build or take apart such objects using the core library routines in {{chicken.h}} and {{runtime.c}}. More information on object structure can be found in [[Data representation]]. <type>scheme-pointer</type><br> <type>(scheme-pointer TYPE)</type><br> <type>nonnull-scheme-pointer</type><br> <type>(nonnull-scheme-pointer TYPE)</type> An untyped pointer to the ''contents'' of a non-immediate Scheme object; for example, the raw byte contents of a string. Only allowed as an argument type, not a return type. The optional element type {{TYPE}} may be used to specify what C type should be used in the generated code. This avoids the need to cast the argument. The value {{#f}} is also allowed and is passed as a {{NULL}} pointer. For the {{nonnull-}} variant, passing {{#f}} will raise an exception. Don't confuse this type with {{(c-pointer ...)}} which means something different (a machine-pointer object). {{scheme-pointer}} is typically used to get a pointer to the raw byte content of strings and blobs. But if you pass in a SRFI-4 vector, you will get a pointer to a blob object header (''not'' the blob's contents), which is almost certainly wrong. Instead, convert to a blob beforehand, or use a SRFI-4 specific type. === User-defined C types <type>(struct NAME)</type> A struct of the name {{NAME}}, which should be a string. Structs cannot be directly passed as arguments to foreign functions, nor can they be result values. However, pointers to structs are allowed. <type>(union NAME)</type> A union of the name {{NAME}}, which should be a string. Unions cannot be directly passed as arguments to foreign functions, nor can they be result values. However, pointers to unions are allowed. <type>(enum NAME)</type> An enumeration type. Handled internally as an {{integer}}. === C++ types <type>(instance CNAME SCHEMECLASS)</type> A pointer to a C++ class instance wrapped into a Scheme object instance. {{CNAME}} should designate the name of the C++ class, and {{SCHEMECLASS}} should be the class that wraps the instance pointer. To use this, an extension will be required that provides an object-creation- and access-interface compatible to [[/eggref/4/coops|coops]] or [[/eggref/4/tinyclos|tinyclos]]. Specifically, it should provide the following operations: (make SCHEMECLASS 'this POINTER) (slot-ref INSTANCE 'this) <type>(instance-ref CNAME SCHEMECLASS)</type> A reference to a C++ class instance. <type>(template TYPE ARGTYPE ...)</type> A C++ template type. For example {{vector<int>}} would be specified as {{(template "vector" int)}}. Template types cannot be directly passed as arguments or returned as results. However, pointers to template types are allowed. === Type qualifiers <type>(const TYPE)</type> The foreign type {{TYPE}} with an additional {{const}} qualifier. === Map of foreign types to C types <table> <tr><th>Foreign type</th><th>C type</th></tr> <tr><td>{{bool}}</td><td>{{int}}</td></tr> <tr><td>{{[unsigned-]char}}</td><td>{{[unsigned] char}}</td></tr> <tr><td>{{[unsigned-]byte}}</td><td>{{[unsigned] char}}</td></tr> <tr><td>{{[unsigned-]short}}</td><td>{{[unsigned] short}}</td></tr> <tr><td>{{[unsigned-]int}}</td><td>{{[unsigned] int}}</td></tr> <tr><td>{{[unsigned-]int32}}</td><td>{{[unsigned] int32_t}}</td></tr> <tr><td>{{[unsigned-]integer}}</td><td>{{[unsigned] int}}</td></tr> <tr><td>{{[unsigned-]integer32}}</td><td>{{[unsigned] int32_t}}</td></tr> <tr><td>{{[unsigned-]integer64}}</td><td>{{[unsigned] int64_t}}</td></tr> <tr><td>{{[unsigned-]long}}</td><td>{{[unsigned] long}}</td></tr> <tr><td>{{size_t}}</td><td>{{size_t}}</td></tr> <tr><td>{{ssize_t}}</td><td>{{ssize_t}}</td></tr> <tr><td>{{float}}</td><td>{{float}}</td></tr> <tr><td>{{double}}</td><td>{{double}}</td></tr> <tr><td>{{number}}</td><td>{{double}}</td></tr> <tr><td>{{[nonnull-]c-pointer}}</td><td>{{void *}}</td></tr> <tr><td>{{[nonnull-]pointer-vector}}</td><td>{{void **}}</td></tr> <tr><td>{{[nonnull-]blob}}</td><td>{{unsigned char *}}</td></tr> <tr><td>{{[nonnull-]u8vector}}</td><td>{{unsigned char *}}</td></tr> <tr><td>{{[nonnull-]s8vector}}</td><td>{{char *}}</td></tr> <tr><td>{{[nonnull-]u16vector}}</td><td>{{unsigned short *}}</td></tr> <tr><td>{{[nonnull-]s16vector}}</td><td>{{short *}}</td></tr> <tr><td>{{[nonnull-]u32vector}}</td><td>{{uint32_t *}}</td></tr> <tr><td>{{[nonnull-]s32vector}}</td><td>{{int32_t *}}</td></tr> <tr><td>{{[nonnull-]u64vector}}</td><td>{{uint64_t *}}</td></tr> <tr><td>{{[nonnull-]s64vector}}</td><td>{{int64_t *}}</td></tr> <tr><td>{{[nonnull-]f32vector}}</td><td>{{float *}}</td></tr> <tr><td>{{[nonnull-]f64vector}}</td><td>{{double *}}</td></tr> <tr><td>{{[nonnull-]c-string}}</td><td>{{char *}}</td></tr> <tr><td>{{[nonnull-]unsigned-c-string}}</td><td>{{unsigned char *}}</td></tr> <tr><td>{{c-string-list}}</td><td>{{char **}}</td></tr> <tr><td>{{symbol}}</td><td>{{char *}}</td></tr> <tr><td>{{void}}</td><td>{{void}}</td></tr> <tr><td>{{([nonnull-]c-pointer TYPE)}}</td><td>{{TYPE *}}</td></tr> <tr><td>{{([nonnull-]scheme-pointer TYPE)}}</td><td>{{TYPE *}}</td></tr> <tr><td>{{(enum NAME)}}</td><td>{{enum NAME}}</td></tr> <tr><td>{{(struct NAME)}}</td><td>{{struct NAME}}</td></tr> <tr><td>{{(ref TYPE)}}</td><td>{{TYPE &}}</td></tr> <tr><td>{{(template T1 T2 ...)}}</td><td>{{T1&lt;T2, ...>}}</td></tr> <tr><td>{{(union NAME)}}</td><td>{{union NAME}}</td></tr> <tr><td>{{(function RTYPE (ATYPE ...) [CALLCONV])}}</td><td>{{[CALLCONV] RTYPE (*)(ATYPE, ...)}}</td></tr> <tr><td>{{(instance CNAME SNAME)}}</td><td>{{CNAME *}}</td></tr> <tr><td>{{(instance-ref CNAME SNAME)}}</td><td>{{CNAME &}}</td></tr> </table> --- Previous: [[Accessing external objects]] Next: [[Embedding]] Description of your changes:

I would like to authenticate

Spam control

What do you get when you subtract 24 from 1?