source: project/chicken/branches/release/manual/Foreign type specifiers @ 7276

Last change on this file since 7276 was 7276, checked in by felix winkelmann, 12 years ago

merged trunk

File size: 7.7 KB
Line 
1[[tags: manual]]
2
3== Foreign type specifiers
4
5Here is a list of valid foreign type specifiers:
6
7=== scheme-object
8
9An arbitrary Scheme data object (immediate or non-immediate).
10
11=== bool
12
13As argument: any value ({{#f}} is false, anything else is true).
14
15As result: anything different from 0 and the {{NULL}} pointer is {{#t}}.
16
17=== byte unsigned-byte
18
19A byte.
20
21=== char unsigned-char
22
23A character.
24
25=== short unsigned-short
26
27A short integer number.
28
29=== int unsigned-int int32 unsigned-int32
30
31An small integer number in fixnum range (at least 30 bit).
32
33=== integer unsigned-integer integer32 unsigned-integer32 integer64
34
35Either a fixnum or a flonum in the range of a (unsigned) machine ''int''
36or with 32/64 bit width.
37
38=== long unsigned-long
39
40Either a fixnum or a flonum in the range of a (unsigned) machine ''long''
41or with 32 bit width.
42
43=== float double
44
45A floating-point number. If an exact integer is passed as an argument,
46then it is automatically converted to a float.
47
48=== number
49
50A floating-point number. Similar to {{double}}, but when used as a result type,
51then either an exact integer or a floating-point number is returned, depending
52on whether the result fits into an exact integer or not.
53
54=== symbol
55
56A symbol, which will be passed to foreign code as a zero-terminated string.
57
58When declared as the result of foreign code, the result should be a string and
59a symbol with the same name will be interned in the symbol table (and returned
60to the caller).
61
62=== scheme-pointer
63
64An untyped pointer to the contents of a non-immediate Scheme object (not
65allowed as return type). The value {{#f}} is also allowed and is passed as a
66{{NULL}} pointer.
67
68Don't confuse this type with {{(c-pointer ...)}} which means something
69different (a machine-pointer object).
70
71=== nonnull-scheme-pointer
72
73As {{scheme-pointer}}, but guaranteed not to be {{#f}}.
74
75Don't confuse this type with {{(nonnull-c-pointer ...)}} which means something
76different (a machine-pointer object).
77
78=== c-pointer
79
80An untyped operating-system pointer or a locative. The value {{#f}} is also
81allowed and is passed as a {{NULL}} pointer. If uses as the type of
82a return value, a {{NULL}} pointer will be returned as {{#f}}.
83
84=== nonnull-c-pointer
85
86As {{c-pointer}}, but guaranteed not to be {{#f/NULL}}.
87
88=== blob
89
90A blob object, passed as a pointer to its contents. Arguments of type {{blob}}
91may optionally be {{#f}}, which is passed as a NULL pointer.
92
93This is not allowed as a return type.
94
95=== nonnull-blob
96
97As {{blob}}, but guaranteed not to be {{#f}}.
98
99=== u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector
100
101A SRFI-4 number-vector object, passed as a pointer to its contents.
102
103These type specifiers are not allowed as return types.
104
105=== nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector
106
107As {{u8vector ...}}, but guaranteed not to be {{#f}}.
108
109=== c-string
110
111A C string (zero-terminated). The value {{#f}} is also allowed and is passed as
112a {{NULL}} pointer. If uses as the type of a return value, a {{NULL}} pointer
113will be returned as {{#f}}. Note that the string is copied (with a zero-byte
114appended) when passed as an argument to a foreign function. Also a return value
115of this type is copied into garbage collected memory.
116
117=== nonnull-c-string
118
119As {{c-string}}, but guaranteed not to be {{#f/NULL}}.
120
121=== [nonnull-] c-string*
122
123Similar to {{[nonnull-] c-string}}, but if used as a result-type, the pointer
124returned by the foreign code will be freed (using the C-libraries {{free(1)}})
125after copying. This type specifier is not valid as a result type for callbacks
126defined with {{define-external}}.
127
128=== [nonnull-] unsigned-c-string[*]
129
130Same as {{c-string}}, but maps to the {{unsigned char *}} C type.
131
132=== c-string-list
133
134Expects a pointer to a list of C strings teminated by a {{NULL}} pointer and
135returns a list of strings.
136
137Only valid as a result type of non-callback functions.
138
139=== c-string-list*
140
141Similar to {{c-string-list}} but releases the storage of each string and
142the pointer array using {{free(1)}}.
143
144=== void
145
146Specifies an undefined return value.
147
148Not allowed as argument type.
149
150=== (const TYPE)
151
152The foreign type {{TYPE}} with an additional {{const}} specifier.
153
154=== (enum NAME)
155
156An enumeration type. Handled internally as an {{integer}}.
157
158=== (c-pointer TYPE)
159
160An operating-system pointer or a locative to an object of {{TYPE}}.
161
162=== (nonnull-c-pointer TYPE)
163
164As {{(c-pointer TYPE)}}, but guaranteed not to be {{#f/NULL}}.
165
166=== (ref TYPE)
167
168A C++ reference type. Reference types are handled the same way as pointers
169inside Scheme code.
170
171=== (struct NAME)
172
173A struct of the name {{NAME}}, which should be a string.
174
175Structs cannot be directly passed as arguments to foreign function, neither
176can they be result values. Pointers to structs are allowed, though.
177
178=== (template TYPE ARGTYPE ...)
179
180A C++ template type. For example {{vector<int>}} would be specified as
181{{(template "vector" int)}}.
182
183Template types cannot be directly passed as arguments or returned as results.
184
185=== (union NAME)
186
187A union of the name {{NAME}}, which should be a string.
188
189Unions cannot be directly passed as arguments to foreign function, neither can
190they be result values. Pointers to unions are allowed, though.
191
192=== (instance CNAME SCHEMECLASS)
193
194A pointer to a C++ class instance. {{CNAME}} should designate the name of the
195C++ class, and {{SCHEMECLASS}} should be the class that wraps the instance
196pointer. Normally {{SCHEMECLASS}} should be a subclass of {{<c++-object>}}.
197
198=== (instance-ref CNAME SCHEMECLASS)
199
200A reference to a C++ class instance.
201
202=== (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])
203
204A function pointer. {{CALLCONV}} specifies an optional calling convention and
205should be a string. The meaning of this string is entirely platform dependent.
206The value {{#f}} is also allowed and is passed as a {{NULL}} pointer.
207
208=== Mappings
209
210Foreign types are mapped to C types in the following manner:
211
212<table>
213<tr><td>bool</td><td>
214int
215</td></tr><tr><td>[unsigned-]char</td><td>
216[unsigned] char
217</td></tr><tr><td>[unsigned-]short</td><td>
218[unsigned] short
219</td></tr><tr><td>[unsigned-]int</td><td>
220[unsigned] int
221</td></tr><tr><td>[unsigned-]integer</td><td>
222[unsigned] int
223</td></tr><tr><td>[unsigned-]long</td><td>
224[unsigned] long
225</td></tr><tr><td>float</td><td>
226float
227</td></tr><tr><td>double</td><td>
228double
229</td></tr><tr><td>number</td><td>
230double
231</td></tr><tr><td>[nonnull-]c-pointer</td><td>
232void *
233</td></tr><tr><td>[nonnull-]blob</td><td>
234unsigned char *
235</td></tr><tr><td>[nonnull-]u8vector</td><td>
236unsigned char *
237</td></tr><tr><td>[nonnull-]s8vector</td><td>
238char *
239</td></tr><tr><td>[nonnull-]u16vector</td><td>
240unsigned short *
241</td></tr><tr><td>[nonnull-]s16vector</td><td>
242short *
243</td></tr><tr><td>[nonnull-]u32vector</td><td>
244uint32_t *
245</td></tr><tr><td>[nonnull-]s32vector</td><td>
246int32_t *
247</td></tr><tr><td>[nonnull-]f32vector</td><td>
248float *
249</td></tr><tr><td>[nonnull-]f64vector</td><td>
250double *
251</td></tr><tr><td>[nonnull-]c-string</td><td>
252char *
253</td></tr><tr><td>[nonnull-]unsigned-c-string</td><td>
254unsigned char *
255</td></tr>
256<tr><td>c-string-list</td><td>char **</td></tr>
257<tr><td>symbol</td><td>
258char *
259</td></tr><tr><td>void</td><td>
260void
261</td></tr><tr><td>([nonnull-]c-pointer TYPE)</td><td>
262TYPE *
263</td></tr><tr><td>(enum NAME)</td><td>
264enum NAME
265</td></tr><tr><td>(struct NAME)</td><td>
266struct NAME
267</td></tr><tr><td>(ref TYPE)</td><td>
268TYPE &
269</td></tr><tr><td>(template T1 T2 ...)</td><td>
270T1<T2, ...>
271</td></tr><tr><td>(union NAME)</td><td>
272union NAME
273</td></tr><tr><td>(function RTYPE (ATYPE ...) [CALLCONV])</td><td>
274[CALLCONV] RTYPE (*)(ATYPE, ...)
275</td></tr><tr><td>(instance CNAME SNAME)</td><td>
276CNAME *
277</td></tr><tr><td>(instance-ref CNAME SNAME)</td><td>
278CNAME &
279</td></tr></table>
280
281Previous: [[Accessing external objects]]
282
283Next: [[Embedding]]
Note: See TracBrowser for help on using the repository browser.