source: project/chicken/trunk/manual/Foreign type specifiers @ 5945

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

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

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