cffi-sys-spec.texinfo - clic - Clic is an command line interactive client for gopher written in Common LISP
(HTM) git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/clic/
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
(DIR) 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 an
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 @result{} object
259 @defmacx %foreign-funcall-pointer ptr @{arg-type arg@}* &optional result-type @result{} object
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-type arg@}* &optional result-type @result{} object
274 @defmacx %foreign-funcall-varargs-pointer ptr (@{fixed-type arg@}*) @{vararg-type arg@}* &optional result-type @result{} object
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