source: project/wiki/man/5/Foreign type specifiers @ 37686

Last change on this file since 37686 was 37686, checked in by svnwiki, 5 months ago

Anonymous wiki edit for IP [192.99.42.25]: srfi-4 page moved

File size: 15.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Foreign type specifiers
5
6Here is a list of valid foreign type specifiers for use in [[Accessing external objects|accessing external objects]].
7
8=== Void
9
10<type>void</type>
11
12Specifies an undefined return value.  Not allowed as argument type.
13
14=== Boolean
15
16<type>bool</type>
17
18As argument: any value ({{#f}} is false (zero), anything else is true (non-zero).
19
20As result: anything different from 0 and the {{NULL}} pointer is {{#t}}.
21
22This type maps to {{int}} in both C and C++.
23
24=== Characters
25
26<type>char</type><br>
27<type>unsigned-char</type><br>
28
29A signed or unsigned character. 
30
31As an argument, the input Scheme character is cast to C {{char}} or
32{{unsigned char}}, resulting in an 8-bit value.  A Scheme character
33with an integer value outside 0-127 (signed) or 0-255 (unsigned) will
34be silently truncated to fit; in other words, don't feed it
35UTF-8 data.
36
37As a return type, accepts any valid Unicode code point; the return
38type is treated as a C int, and converted to a Scheme character.
39
40=== Integers
41
42<type>byte</type><br>
43<type>unsigned-byte</type><br>
44
45An 8-bit integer value in range -128 - 127 (byte) or 0 - 255 (unsigned
46byte).  Values are cast to and from C {{char}} or {{unsigned char}}
47type, so values outside this 8-bit range will be unceremoniously
48truncated.
49
50<type>short</type><br>
51<type>unsigned-short</type><br>
52
53A short integer number in 16-bit range.  Maps to C {{short}} or
54{{unsigned short}}.
55
56<type>int</type><br>
57<type>unsigned-int</type><br>
58<type>int32</type><br>
59<type>unsigned-int32</type><br>
60
61An integer number in fixnum range (-1073741824 to 1073741823, i.e. 31
62bit signed).  {{unsigned-int}} further restricts this range to 30 bit
63unsigned (0 to 1073741823).  {{int}} maps to C type {{int}} and
64{{int32}} maps to {{int32_t}}.
65
66As an argument type, these expect a fixnum value, and as a return type
67they return a fixnum.  Values outside the ranges prescribed above are
68silently truncated; you should use e.g. {{integer}} if you need the full
6932-bit range.  Note: {{int32}} is not recognized as an argument type
70prior to CHICKEN 4.7.2.
71
72Notes for 64-bit architectures:
73
74* C's {{int}} is 32 bits on most 64-bit systems
75([[http://en.wikipedia.org/wiki/64-bit#Specific_C-language_data_models|LP64]]),
76so {{int}} and {{int32}} are functionally (if not semantically) equivalent.
77
78* The fixnum type is larger than 32 bits and consequently the entire
79signed or unsigned 32-bit range is available for this type on 64-bit
80systems.  However, for compatibility with 32-bit systems it is
81probably unwise to rely on this.  If you need a 32-bit range, you
82should use (unsigned) {{integer}} or {{integer32}}.
83
84<type>integer</type><br>
85<type>unsigned-integer</type><br>
86<type>integer32</type><br>
87<type>unsigned-integer32</type><br>
88
89A fixnum or integral flonum, mapping to {{int}} or {{int32_t}} or
90their unsigned variants.  When outside of fixnum range the value will
91overflow into a flonum.
92
93C's {{int}} is 32 bits on most 64-bit systems
94([[http://en.wikipedia.org/wiki/64-bit#Specific_C-language_data_models|LP64]]),
95so {{integer}} and {{integer32}} are functionally (if not semantically) equivalent.
96
97<type>integer64</type><br>
98<type>unsigned-integer64</type>
99
100A fixnum or integral flonum, mapping to {{int64_t}} or {{uint64_t}}.
101When outside of fixnum range the value will overflow into a flonum.
102
103On a 32-bit system, the effective precision of this type is 52 bits
104plus the sign bit, as it is stored in a {{double}} flonum.  (In other
105words, numbers between 2^52 and 2^64-1 can be represented but there are
106gaps in the sequence; the same goes for their negative counterparts.) 
107On a 64-bit system the range is 62 bits plus the sign bit, the
108maximum range of a fixnum.  (Numbers between 2^62 and 2^64-1 have gaps.)
109
110{{unsigned-integer64}} is not valid as a return type until CHICKEN 4.6.4.
111
112<type>long</type><br>
113<type>unsigned-long</type>
114
115Either a fixnum or a flonum in the range of an (unsigned) machine ''long''.
116Similar to {{integer32}} on 32-bit systems or {{integer64}} on 64-bit.
117
118<type>size_t</type>
119
120A direct mapping to C's {{size_t}}.
121
122=== Floating-point
123
124<type>float</type><br>
125<type>double</type>
126
127A floating-point number. If an exact integer is passed as an argument,
128then it is automatically converted to a float.
129
130<type>number</type>
131
132A floating-point number. Similar to {{double}}, but when used as a result type,
133then either an exact integer or a floating-point number is returned, depending
134on whether the result fits into an exact integer or not.
135
136=== Strings
137
138<type>c-string</type><br>
139<type>nonnull-c-string</type>
140
141A zero-terminated C string. The argument value {{#f}} is allowed and
142is passed as a {{NULL}} pointer; similarly, a NULL pointer is returned
143as {{#f}}.  Note that the string contents are copied into (automatically
144managed) temporary storage with a zero byte appended when passed as an
145argument. Also, a return value of this type is copied into garbage
146collected memory using {{strcpy(3)}}.
147
148For the {{nonnull-}} variant, passing {{#f}} will raise an exception, and returning
149a NULL pointer will result in undefined behavior (e.g. a segfault).
150
151<type>c-string*</type><br>
152<type>nonnull-c-string*</type>
153
154Similar to {{c-string}} and {{nonnull-c-string}}, but if used as a result type, the pointer
155returned by the foreign code will be freed (using the C library's {{free(3)}})
156after copying. This type specifier is not valid as a result type for callbacks
157defined with {{define-external}}.
158
159<type>unsigned-c-string</type><br>
160<type>nonnull-unsigned-c-string</type><br>
161<type>unsigned-c-string*</type><br>
162<type>nonnull-unsigned-c-string*</type><br>
163
164Same as {{c-string}}, {{nonnull-c-string}}, etc. but mapping to C's
165{{unsigned char *}} type.
166
167<type>c-string-list</type><br>
168<type>c-string-list*</type>
169
170Takes a pointer to an array of C strings terminated by a {{NULL}} pointer and
171returns a list of strings.  The starred version {{c-string-list*}} also releases
172the storage of each string and the pointer array afterward using {{free(1)}}.
173
174Only valid as a result type, and can only be used with non-callback functions.
175
176<type>symbol</type>
177
178A symbol, which will be passed to foreign code as a zero-terminated string.
179
180When declared as the result of foreign code, the result should be a string and
181a symbol with the same name will be interned in the symbol table (and returned
182to the caller).  Attempting to return a NULL string will raise an exception.
183
184=== Bytevectors
185
186<type>blob</type><br>
187<type>nonnull-blob</type>
188
189A blob object, passed as a pointer to its contents.  Permitted only as
190argument type, not return type. 
191
192Arguments of type {{blob}} may optionally be {{#f}}, which is passed
193as a NULL pointer.  For the {{nonnull-}} variant, passing a {{#f}}
194value will raise an exception.
195
196<type>u8vector</type><br>
197<type>u16vector</type><br>
198<type>u32vector</type><br>
199<type>u64vector</type><br>
200<type>s8vector</type><br>
201<type>s16vector</type><br>
202<type>s32vector</type><br>
203<type>s64vector</type><br>
204<type>f32vector</type><br>
205<type>f64vector</type><br>
206<type>nonnull-u8vector </type><br>
207<type>nonnull-u16vector </type><br>
208<type>nonnull-u32vector </type><br>
209<type>nonnull-u64vector </type><br>
210<type>nonnull-s8vector </type><br>
211<type>nonnull-s16vector</type><br>
212<type>nonnull-s32vector</type><br>
213<type>nonnull-s64vector</type><br>
214<type>nonnull-f32vector</type><br>
215<type>nonnull-f64vector</type><br>
216
217A [[Module srfi-4|SRFI-4]] number-vector object, passed as a pointer to its contents.
218These are allowed only as argument types, not as return types.
219
220The value {{#f}} is also allowed and is passed to C as a NULL pointer.
221For the {{nonnull-}} variants, passing {{#f}} will raise an exception.
222
223=== Pointers
224
225<type>c-pointer</type><br>
226<type>(c-pointer TYPE)</type><br>
227<type>nonnull-c-pointer</type><br>
228<type>(nonnull-c-pointer TYPE)</type><br>
229
230An operating-system pointer or a locative.  {{c-pointer}} is untyped, whereas
231{{(c-pointer TYPE)}} points to an object of foreign type TYPE.
232
233The value {{#f}} is allowed and is passed to C as a {{NULL}} pointer;
234similarly, NULL is returned as {{#f}}.  For the two {{nonnull-}} variants,
235passing {{#f}} will raise an exception, and returning NULL will result in
236a null {{pointer}} object. 
237
238(Note: It is still possible to deliberately pass a null pointer through a
239{{nonnull-c-pointer}} by manually creating a null pointer object,
240e.g. via {{(address->pointer 0)}}.)
241
242<type>pointer-vector</type><br>
243<type>nonnull-pointer-vector</type>
244
245A vector of foreign pointer objects; see [[Unit lolevel#Pointer vectors|Pointer vectors]].
246Permitted only as an argument type, not as return type.  This type was introduced in CHICKEN 4.6.3.
247
248A pointer vector contains a C array of void pointers, and the argument
249is passed as a {{void **}} pointer to these contents.  Just as for
250bytevector types, you must somehow communicate the length of this array
251to the callee; there is no sentinel node or NULL terminator.
252
253{{#f}} is allowed and passed as a {{NULL}} pointer.  For the
254{{nonnull-}} variant, passing a {{#f}} value will raise an exception.
255
256<type>(ref TYPE)</type>
257
258A C++ reference type. Reference types are handled the same way as pointers
259inside Scheme code.
260
261<type>(function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])</type>
262
263A function pointer. {{CALLCONV}} specifies an optional calling convention and
264should be a string. The meaning of this string is entirely platform dependent.
265The value {{#f}} is also allowed and is passed as a {{NULL}} pointer.
266
267=== Scheme objects
268
269<type>scheme-object</type>
270
271An arbitrary, raw Scheme data object (immediate or non-immediate).  A
272{{scheme-object}} is passed or returned as a {{C_word}}, the
273internal CHICKEN type for objects.  Typically, this consists of an
274object header and tag bits.  It is up to you to build or take apart
275such objects using the core library routines in {{chicken.h}} and
276{{runtime.c}}. 
277
278More information on object structure can be found in [[Data representation]].
279
280<type>scheme-pointer</type><br>
281<type>(scheme-pointer TYPE)</type><br>
282<type>nonnull-scheme-pointer</type><br>
283<type>(nonnull-scheme-pointer TYPE)</type>
284
285An untyped pointer to the ''contents'' of a non-immediate Scheme
286object; for example, the raw byte contents of a string. Only allowed
287as an argument type, not a return type. 
288
289The optional element type {{TYPE}} may be used to specify what C
290type should be used in the generated code. This avoids the need
291to cast the argument.
292
293The value {{#f}} is also allowed and is passed as a {{NULL}} pointer.
294For the {{nonnull-}} variant, passing {{#f}} will raise an exception.
295
296Don't confuse this type with {{(c-pointer ...)}} which means something
297different (a machine-pointer object).
298
299{{scheme-pointer}} is typically used to get a pointer to the raw byte
300content of strings and blobs.  But if you pass in a SRFI-4 vector, you
301will get a pointer to a blob object header (''not'' the blob's contents),
302which is almost certainly wrong.  Instead, convert to a blob
303beforehand, or use a SRFI-4 specific type.
304
305=== User-defined C types
306
307<type>(struct NAME)</type>
308
309A struct of the name {{NAME}}, which should be a string.
310
311Structs cannot be directly passed as arguments to foreign functions, nor
312can they be result values.  However, pointers to structs are allowed.
313
314<type>(union NAME)</type>
315
316A union of the name {{NAME}}, which should be a string.
317
318Unions cannot be directly passed as arguments to foreign functions, nor can
319they be result values. However, pointers to unions are allowed.
320
321<type>(enum NAME)</type>
322
323An enumeration type. Handled internally as an {{integer}}.
324
325=== C++ types
326
327<type>(instance CNAME SCHEMECLASS)</type>
328
329A pointer to a C++ class instance wrapped into a Scheme object
330instance. {{CNAME}} should designate the name of the C++ class, and
331{{SCHEMECLASS}} should be the class that wraps the instance pointer.
332
333To use this, an extension will be required that provides an
334object-creation- and access-interface compatible to
335[[/eggref/4/coops|coops]] or
336[[/eggref/4/tinyclos|tinyclos]]. Specifically, it should provide the
337following operations:
338
339  (make SCHEMECLASS 'this POINTER)
340  (slot-ref INSTANCE 'this)
341
342<type>(instance-ref CNAME SCHEMECLASS)</type>
343
344A reference to a C++ class instance.
345
346<type>(template TYPE ARGTYPE ...)</type>
347
348A C++ template type. For example {{vector<int>}} would be specified as
349{{(template "vector" int)}}.
350
351Template types cannot be directly passed as arguments or returned as results.
352However, pointers to template types are allowed.
353
354=== Type qualifiers
355
356<type>(const TYPE)</type>
357
358The foreign type {{TYPE}} with an additional {{const}} qualifier.
359
360=== Map of foreign types to C types
361
362<table>
363<tr><th>Foreign type</th><th>C type</th></tr>
364<tr><td>{{bool}}</td><td>{{int}}</td></tr>
365<tr><td>{{[unsigned-]char}}</td><td>{{[unsigned] char}}</td></tr>
366<tr><td>{{[unsigned-]byte}}</td><td>{{[unsigned] char}}</td></tr>
367<tr><td>{{[unsigned-]short}}</td><td>{{[unsigned] short}}</td></tr>
368<tr><td>{{[unsigned-]int}}</td><td>{{[unsigned] int}}</td></tr>
369<tr><td>{{[unsigned-]int32}}</td><td>{{[unsigned] int32_t}}</td></tr>
370<tr><td>{{[unsigned-]integer}}</td><td>{{[unsigned] int}}</td></tr>
371<tr><td>{{[unsigned-]integer32}}</td><td>{{[unsigned] int32_t}}</td></tr>
372<tr><td>{{[unsigned-]integer64}}</td><td>{{[unsigned] int64_t}}</td></tr>
373<tr><td>{{[unsigned-]long}}</td><td>{{[unsigned] long}}</td></tr>
374<tr><td>{{size_t}}</td><td>{{size_t}}</td></tr>
375<tr><td>{{float}}</td><td>{{float}}</td></tr>
376<tr><td>{{double}}</td><td>{{double}}</td></tr>
377<tr><td>{{number}}</td><td>{{double}}</td></tr>
378<tr><td>{{[nonnull-]c-pointer}}</td><td>{{void *}}</td></tr>
379<tr><td>{{[nonnull-]pointer-vector}}</td><td>{{void **}}</td></tr>
380<tr><td>{{[nonnull-]blob}}</td><td>{{unsigned char *}}</td></tr>
381<tr><td>{{[nonnull-]u8vector}}</td><td>{{unsigned char *}}</td></tr>
382<tr><td>{{[nonnull-]s8vector}}</td><td>{{char *}}</td></tr>
383<tr><td>{{[nonnull-]u16vector}}</td><td>{{unsigned short *}}</td></tr>
384<tr><td>{{[nonnull-]s16vector}}</td><td>{{short *}}</td></tr>
385<tr><td>{{[nonnull-]u32vector}}</td><td>{{uint32_t *}}</td></tr>
386<tr><td>{{[nonnull-]s32vector}}</td><td>{{int32_t *}}</td></tr>
387<tr><td>{{[nonnull-]u64vector}}</td><td>{{uint64_t *}}</td></tr>
388<tr><td>{{[nonnull-]s64vector}}</td><td>{{int64_t *}}</td></tr>
389<tr><td>{{[nonnull-]f32vector}}</td><td>{{float *}}</td></tr>
390<tr><td>{{[nonnull-]f64vector}}</td><td>{{double *}}</td></tr>
391<tr><td>{{[nonnull-]c-string}}</td><td>{{char *}}</td></tr>
392<tr><td>{{[nonnull-]unsigned-c-string}}</td><td>{{unsigned char *}}</td></tr>
393<tr><td>{{c-string-list}}</td><td>{{char **}}</td></tr>
394<tr><td>{{symbol}}</td><td>{{char *}}</td></tr>
395<tr><td>{{void}}</td><td>{{void}}</td></tr>
396<tr><td>{{([nonnull-]c-pointer TYPE)}}</td><td>{{TYPE *}}</td></tr>
397<tr><td>{{([nonnull-]scheme-pointer TYPE)}}</td><td>{{TYPE *}}</td></tr>
398<tr><td>{{(enum NAME)}}</td><td>{{enum NAME}}</td></tr>
399<tr><td>{{(struct NAME)}}</td><td>{{struct NAME}}</td></tr>
400<tr><td>{{(ref TYPE)}}</td><td>{{TYPE &}}</td></tr>
401<tr><td>{{(template T1 T2 ...)}}</td><td>{{T1&lt;T2, ...>}}</td></tr>
402<tr><td>{{(union NAME)}}</td><td>{{union NAME}}</td></tr>
403<tr><td>{{(function RTYPE (ATYPE ...) [CALLCONV])}}</td><td>{{[CALLCONV] RTYPE (*)(ATYPE, ...)}}</td></tr>
404<tr><td>{{(instance CNAME SNAME)}}</td><td>{{CNAME *}}</td></tr>
405<tr><td>{{(instance-ref CNAME SNAME)}}</td><td>{{CNAME &}}</td></tr>
406</table>
407
408---
409Previous: [[Accessing external objects]]
410
411Next: [[Embedding]]
Note: See TracBrowser for help on using the repository browser.