cffi-sys-spec.texinfo - clic - Clic is an command line interactive client for g… | |
git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65… | |
Log | |
Files | |
Refs | |
Tags | |
README | |
LICENSE | |
--- | |
cffi-sys-spec.texinfo (10606B) | |
--- | |
1 \input texinfo @c -*-texinfo-*- | |
2 @c %**start of header | |
3 @setfilename cffi-sys.info | |
4 @settitle CFFI-SYS Interface Specification | |
5 | |
6 @c Show types in the same index as the functions. | |
7 @synindex tp fn | |
8 | |
9 @copying | |
10 Copyright @copyright{} 2005-2006, James Bielman <jamesjb at jamesjb.com> | |
11 | |
12 @quotation | |
13 Permission is hereby granted, free of charge, to any person | |
14 obtaining a copy of this software and associated documentation | |
15 files (the ``Software''), to deal in the Software without | |
16 restriction, including without limitation the rights to use, copy, | |
17 modify, merge, publish, distribute, sublicense, and/or sell copies | |
18 of the Software, and to permit persons to whom the Software is | |
19 furnished to do so, subject to the following conditions: | |
20 | |
21 The above copyright notice and this permission notice shall be | |
22 included in all copies or substantial portions of the Software. | |
23 | |
24 @sc{The software is provided ``as is'', without warranty of any kind, | |
25 express or implied, including but not limited to the warranties of | |
26 merchantability, fitness for a particular purpose and | |
27 noninfringement. In no event shall the authors or copyright | |
28 holders be liable for any claim, damages or other liability, | |
29 whether in an action of contract, tort or otherwise, arising from, | |
30 out of or in connection with the software or the use or other | |
31 dealings in the software.} | |
32 @end quotation | |
33 @end copying | |
34 | |
35 @macro impnote {text} | |
36 @emph{Implementor's note: \text\} | |
37 @end macro | |
38 @c %**end of header | |
39 | |
40 @dircategory Software development | |
41 @direntry | |
42 * CFFI Sys spec: (cffi-sys-spec). CFFI Sys spec. | |
43 @end direntry | |
44 | |
45 @titlepage | |
46 @title CFFI-SYS Interface Specification | |
47 @c @subtitle Version X.X | |
48 @c @author James Bielman | |
49 | |
50 @page | |
51 @vskip 0pt plus 1filll | |
52 @insertcopying | |
53 @end titlepage | |
54 | |
55 @contents | |
56 | |
57 @ifnottex | |
58 @node Top | |
59 @top cffi-sys | |
60 @insertcopying | |
61 @end ifnottex | |
62 | |
63 @menu | |
64 * Introduction:: | |
65 * Built-In Foreign Types:: | |
66 * Operations on Foreign Types:: | |
67 * Basic Pointer Operations:: | |
68 * Foreign Memory Allocation:: | |
69 * Memory Access:: | |
70 * Foreign Function Calling:: | |
71 * Loading Foreign Libraries:: | |
72 * Foreign Globals:: | |
73 * Symbol Index:: | |
74 @end menu | |
75 | |
76 @node Introduction | |
77 @chapter Introduction | |
78 | |
79 @acronym{CFFI}, the Common Foreign Function Interface, purports to be | |
80 a portable foreign function interface for Common Lisp. | |
81 | |
82 This specification defines a set of low-level primitives that must be | |
83 defined for each Lisp implementation supported by @acronym{CFFI}. | |
84 These operators are defined in the @code{CFFI-SYS} package. | |
85 | |
86 The @code{CFFI} package uses the @code{CFFI-SYS} interface | |
87 to implement an extensible foreign type system with support for | |
88 typedefs, structures, and unions, a declarative interface for | |
89 defining foreign function calls, and automatic conversion of | |
90 foreign function arguments to/from Lisp types. | |
91 | |
92 Please note the following conventions that apply to everything in | |
93 @code{CFFI-SYS}: | |
94 | |
95 @itemize @bullet | |
96 @item | |
97 Functions in @code{CFFI-SYS} that are low-level versions of functions | |
98 exported from the @code{CFFI} package begin with a leading | |
99 percent-sign (eg. @code{%mem-ref}). | |
100 | |
101 @item | |
102 Where ``foreign type'' is mentioned as the kind of an argument, the | |
103 meaning is restricted to that subset of all foreign types defined in | |
104 @ref{Built-In Foreign Types}. Support for higher-level types is | |
105 always defined in terms of those lower-level types in @code{CFFI} | |
106 proper. | |
107 @end itemize | |
108 | |
109 | |
110 @node Built-In Foreign Types | |
111 @chapter Built-In Foreign Types | |
112 | |
113 @deftp {Foreign Type} :char | |
114 @deftpx {Foreign Type} :unsigned-char | |
115 @deftpx {Foreign Type} :short | |
116 @deftpx {Foreign Type} :unsigned-short | |
117 @deftpx {Foreign Type} :int | |
118 @deftpx {Foreign Type} :unsigned-int | |
119 @deftpx {Foreign Type} :long | |
120 @deftpx {Foreign Type} :unsigned-long | |
121 @deftpx {Foreign Type} :long-long | |
122 @deftpx {Foreign Type} :unsigned-long-long | |
123 These types correspond to the native C integer types according to the | |
124 ABI of the system the Lisp implementation is compiled against. | |
125 @end deftp | |
126 | |
127 @deftp {Foreign Type} :int8 | |
128 @deftpx {Foreign Type} :uint8 | |
129 @deftpx {Foreign Type} :int16 | |
130 @deftpx {Foreign Type} :uint16 | |
131 @deftpx {Foreign Type} :int32 | |
132 @deftpx {Foreign Type} :uint32 | |
133 @deftpx {Foreign Type} :int64 | |
134 @deftpx {Foreign Type} :uint64 | |
135 Foreign integer types of specific sizes, corresponding to the C types | |
136 defined in @code{stdint.h}. | |
137 @end deftp | |
138 | |
139 @deftp {Foreign Type} :size | |
140 @deftpx {Foreign Type} :ssize | |
141 @deftpx {Foreign Type} :ptrdiff | |
142 @deftpx {Foreign Type} :time | |
143 Foreign integer types corresponding to the standard C types (without | |
144 the @code{_t} suffix). | |
145 @end deftp | |
146 | |
147 @impnote{I'm sure there are more of these that could be useful, let's | |
148 add any types that can't be defined portably to this list as | |
149 necessary.} | |
150 | |
151 @deftp {Foreign Type} :float | |
152 @deftpx {Foreign Type} :double | |
153 The @code{:float} type represents a C @code{float} and a Lisp | |
154 @code{single-float}. @code{:double} represents a C @code{double} and a | |
155 Lisp @code{double-float}. | |
156 @end deftp | |
157 | |
158 @deftp {Foreign Type} :pointer | |
159 A foreign pointer to an object of any type, corresponding to | |
160 @code{void *}. | |
161 @end deftp | |
162 | |
163 @deftp {Foreign Type} :void | |
164 No type at all. Only valid as the return type of a function. | |
165 @end deftp | |
166 | |
167 | |
168 @node Operations on Foreign Types | |
169 @chapter Operations on Built-in Foreign Types | |
170 | |
171 @defun %foreign-type-size type @result{} size | |
172 Return the @var{size}, in bytes, of objects having foreign type | |
173 @var{type}. An error is signalled if @var{type} is not a known | |
174 built-in foreign type. | |
175 @end defun | |
176 | |
177 @defun %foreign-type-alignment type @result{} alignment | |
178 Return the default alignment in bytes for structure members of foreign | |
179 type @var{type}. An error is signalled if @var{type} is not a known | |
180 built-in foreign type. | |
181 | |
182 @impnote{Maybe this should take an optional keyword argument specifying … | |
183 alternate alignment system, eg. :mac68k for 68000-compatible alignment | |
184 on Darwin.} | |
185 @end defun | |
186 | |
187 | |
188 @node Basic Pointer Operations | |
189 @chapter Basic Pointer Operations | |
190 | |
191 @defun pointerp ptr @result{} boolean | |
192 Return true if @var{ptr} is a foreign pointer. | |
193 @end defun | |
194 | |
195 @defun null-pointer @result{} pointer | |
196 Return a null foreign pointer. | |
197 @end defun | |
198 | |
199 @defun null-pointer-p ptr @result{} boolean | |
200 Return true if @var{ptr} is a null foreign pointer. | |
201 @end defun | |
202 | |
203 @defun make-pointer address @result{} pointer | |
204 Return a pointer corresponding to the numeric integer @var{address}. | |
205 @end defun | |
206 | |
207 @defun inc-pointer ptr offset @result{} pointer | |
208 Return the result of numerically incrementing @var{ptr} by @var{offset}. | |
209 @end defun | |
210 | |
211 | |
212 @node Foreign Memory Allocation | |
213 @chapter Foreign Memory Allocation | |
214 | |
215 @defun foreign-alloc size @result{} pointer | |
216 Allocate @var{size} bytes of foreign-addressable memory and return | |
217 a @var{pointer} to the allocated block. An implementation-specific | |
218 error is signalled if the memory cannot be allocated. | |
219 @end defun | |
220 | |
221 @defun foreign-free ptr @result{} unspecified | |
222 Free a pointer @var{ptr} allocated by @code{foreign-alloc}. The | |
223 results are undefined if @var{ptr} is used after being freed. | |
224 @end defun | |
225 | |
226 @defmac with-foreign-pointer (var size &optional size-var) &body body | |
227 Bind @var{var} to a pointer to @var{size} bytes of | |
228 foreign-accessible memory during @var{body}. Both @var{ptr} and the | |
229 memory block it points to have dynamic extent and may be stack | |
230 allocated if supported by the implementation. If @var{size-var} is | |
231 supplied, it will be bound to @var{size} during @var{body}. | |
232 @end defmac | |
233 | |
234 | |
235 @node Memory Access | |
236 @chapter Memory Access | |
237 | |
238 @deffn {Accessor} %mem-ref ptr type &optional offset | |
239 Dereference a pointer @var{offset} bytes from @var{ptr} to an object | |
240 for reading (or writing when used with @code{setf}) of built-in type | |
241 @var{type}. | |
242 @end deffn | |
243 | |
244 @heading Example | |
245 | |
246 @lisp | |
247 ;; An impractical example, since time returns the time as well, | |
248 ;; but it demonstrates %MEM-REF. Better (simple) examples wanted! | |
249 (with-foreign-pointer (p (foreign-type-size :time)) | |
250 (foreign-funcall "time" :pointer p :time) | |
251 (%mem-ref p :time)) | |
252 @end lisp | |
253 | |
254 | |
255 @node Foreign Function Calling | |
256 @chapter Foreign Function Calling | |
257 | |
258 @defmac %foreign-funcall name @{arg-type arg@}* &optional result-type @r… | |
259 @defmacx %foreign-funcall-pointer ptr @{arg-type arg@}* &optional result… | |
260 Invoke a foreign function called @var{name} in the foreign source code. | |
261 | |
262 Each @var{arg-type} is a foreign type specifier, followed by | |
263 @var{arg}, Lisp data to be converted to foreign data of type | |
264 @var{arg-type}. @var{result-type} is the foreign type of the | |
265 function's return value, and is assumed to be @code{:void} if not | |
266 supplied. | |
267 | |
268 @code{%foreign-funcall-pointer} takes a pointer @var{ptr} to the | |
269 function, as returned by @code{foreign-symbol-pointer}, rather than a | |
270 string @var{name}. | |
271 @end defmac | |
272 | |
273 @defmac %foreign-funcall-varargs name (@{fixed-type arg@}*) @{vararg-typ… | |
274 @defmacx %foreign-funcall-varargs-pointer ptr (@{fixed-type arg@}*) @{va… | |
275 Invoke a foreign variadic function called @var{name} in the foreign | |
276 source code. | |
277 | |
278 Each @var{fixed-type} and @var{vararg-type} is a foreign type | |
279 specifier, followed by @var{arg}, Lisp data to be converted to foreign | |
280 data of type @var{arg-type}. @var{result-type} is the foreign type of | |
281 the function's return value, and is assumed to be @code{:void} if not | |
282 supplied. | |
283 | |
284 @code{%foreign-funcall-pointer-varargs} takes a pointer @var{ptr} to | |
285 the variadic function, as returned by @code{foreign-symbol-pointer}, | |
286 rather than a string @var{name}. | |
287 | |
288 Both functions have default implementation which call | |
289 @code{%foreign-funcall} and @code{%foreign-funcall-pointer} | |
290 approprietly. | |
291 @end defmac | |
292 | |
293 @heading Examples | |
294 | |
295 @lisp | |
296 ;; Calling a standard C library function: | |
297 (%foreign-funcall "sqrtf" :float 16.0 :float) @result{} 4.0 | |
298 @end lisp | |
299 | |
300 @lisp | |
301 ;; Dynamic allocation of a buffer and passing to a function: | |
302 (with-foreign-ptr (buf 255 buf-size) | |
303 (%foreign-funcall "gethostname" :pointer buf :size buf-size :int) | |
304 ;; Convert buf to a Lisp string using MAKE-STRING and %MEM-REF or | |
305 ;; a portable CFFI function such as CFFI:FOREIGN-STRING-TO-LISP. | |
306 ) | |
307 @end lisp | |
308 | |
309 | |
310 @node Loading Foreign Libraries | |
311 @chapter Loading Foreign Libraries | |
312 | |
313 @defun %load-foreign-library name @result{} unspecified | |
314 Load the foreign shared library @var{name}. | |
315 | |
316 @impnote{There is a lot of behavior to decide here. Currently I lean | |
317 toward not requiring NAME to be a full path to the library so | |
318 we can search the system library directories (maybe even get | |
319 LD_LIBRARY_PATH from the environment) as necessary.} | |
320 @end defun | |
321 | |
322 | |
323 @node Foreign Globals | |
324 @chapter Foreign Globals | |
325 | |
326 @defun foreign-symbol-pointer name @result{} pointer | |
327 Return a pointer to a foreign symbol @var{name}. | |
328 @end defun | |
329 | |
330 @node Symbol Index | |
331 @unnumbered Symbol Index | |
332 @printindex fn | |
333 | |
334 @bye |