cffi-manual.texinfo - clic - Clic is an command line interactive client for gop… | |
git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65… | |
Log | |
Files | |
Refs | |
Tags | |
README | |
LICENSE | |
--- | |
cffi-manual.texinfo (218970B) | |
--- | |
1 \input texinfo @c -*- Mode: Texinfo; Mode: auto-fill -*- | |
2 @c %**start of header | |
3 @setfilename cffi.info | |
4 @settitle CFFI User Manual | |
5 @exampleindent 2 | |
6 | |
7 @c @documentencoding utf-8 | |
8 | |
9 @c Style notes: | |
10 @c | |
11 @c * The reference section names and "See Also" list are roman, not | |
12 @c @code. This is to follow the format of CLHS. | |
13 @c | |
14 @c * How it looks in HTML is the priority. | |
15 | |
16 @c ============================= Macros ============================= | |
17 @c The following macros are used throughout this manual. | |
18 | |
19 @macro Function {args} | |
20 @defun \args\ | |
21 @end defun | |
22 @end macro | |
23 | |
24 @macro Macro {args} | |
25 @defmac \args\ | |
26 @end defmac | |
27 @end macro | |
28 | |
29 @macro Accessor {args} | |
30 @deffn {Accessor} \args\ | |
31 @end deffn | |
32 @end macro | |
33 | |
34 @macro GenericFunction {args} | |
35 @deffn {Generic Function} \args\ | |
36 @end deffn | |
37 @end macro | |
38 | |
39 @macro ForeignType {args} | |
40 @deftp {Foreign Type} \args\ | |
41 @end deftp | |
42 @end macro | |
43 | |
44 @macro Variable {args} | |
45 @defvr {Special Variable} \args\ | |
46 @end defvr | |
47 @end macro | |
48 | |
49 @macro Condition {args} | |
50 @deftp {Condition Type} \args\ | |
51 @end deftp | |
52 @end macro | |
53 | |
54 @macro cffi | |
55 @acronym{CFFI} | |
56 @end macro | |
57 | |
58 @macro impnote {text} | |
59 @quotation | |
60 @strong{Implementor's note:} @emph{\text\} | |
61 @end quotation | |
62 @end macro | |
63 | |
64 @c Info "requires" that x-refs end in a period or comma, or ) in the | |
65 @c case of @pxref. So the following implements that requirement for | |
66 @c the "See also" subheadings that permeate this manual, but only in | |
67 @c Info mode. | |
68 @ifinfo | |
69 @macro seealso {name} | |
70 @ref{\name\}. | |
71 @end macro | |
72 @end ifinfo | |
73 | |
74 @ifnotinfo | |
75 @alias seealso = ref | |
76 @end ifnotinfo | |
77 | |
78 @c Typeset comments in roman font for the TeX output. | |
79 @iftex | |
80 @alias lispcmt = r | |
81 @end iftex | |
82 @ifnottex | |
83 @alias lispcmt = asis | |
84 @end ifnottex | |
85 | |
86 @alias res = result | |
87 | |
88 @c ============================= Macros ============================= | |
89 | |
90 | |
91 @c Show types, functions, and concepts in the same index. | |
92 @syncodeindex tp cp | |
93 @syncodeindex fn cp | |
94 | |
95 @copying | |
96 Copyright @copyright{} 2005 James Bielman <jamesjb at jamesjb.com> @* | |
97 Copyright @copyright{} 2005-2015 Lu@'{@dotless{i}}s Oliveira | |
98 <loliveira at common-lisp.net> @* | |
99 Copyright @copyright{} 2005-2006 Dan Knapp <danka at accela.net> @* | |
100 Copyright @copyright{} 2005-2006 Emily Backes <lucca at accela.net> @* | |
101 Copyright @copyright{} 2006 Stephen Compall <s11 at member.fsf.org> | |
102 | |
103 @quotation | |
104 Permission is hereby granted, free of charge, to any person obtaining | |
105 a copy of this software and associated documentation files (the | |
106 ``Software''), to deal in the Software without restriction, including | |
107 without limitation the rights to use, copy, modify, merge, publish, | |
108 distribute, sublicense, and/or sell copies of the Software, and to | |
109 permit persons to whom the Software is furnished to do so, subject to | |
110 the following conditions: | |
111 | |
112 The above copyright notice and this permission notice shall be | |
113 included in all copies or substantial portions of the Software. | |
114 | |
115 @sc{The software is provided ``as is'', without warranty of any kind, | |
116 express or implied, including but not limited to the warranties of | |
117 merchantability, fitness for a particular purpose and noninfringement. | |
118 In no event shall the authors or copyright holders be liable for any | |
119 claim, damages or other liability, whether in an action of contract, | |
120 tort or otherwise, arising from, out of or in connection with the | |
121 software or the use or other dealings in the software.} | |
122 @end quotation | |
123 @end copying | |
124 @c %**end of header | |
125 | |
126 @dircategory Software development | |
127 @direntry | |
128 * CFFI Manual: (cffi-manual). CFFI Manual. | |
129 @end direntry | |
130 | |
131 @titlepage | |
132 @title CFFI User Manual | |
133 @c @subtitle Version X.X | |
134 @c @author James Bielman | |
135 | |
136 @page | |
137 @vskip 0pt plus 1filll | |
138 @insertcopying | |
139 @end titlepage | |
140 | |
141 @contents | |
142 | |
143 @ifnottex | |
144 @node Top, Introduction, (dir), (dir) | |
145 @top cffi | |
146 @insertcopying | |
147 @end ifnottex | |
148 | |
149 @menu | |
150 * Introduction:: What is CFFI? | |
151 * Installation:: | |
152 * Implementation Support:: | |
153 * Tutorial:: Interactive intro to using CFFI. | |
154 * Wrapper generators:: CFFI forms from munging C source code. | |
155 * Foreign Types:: | |
156 * Pointers:: | |
157 * Strings:: | |
158 * Variables:: | |
159 * Functions:: | |
160 * Libraries:: | |
161 * Callbacks:: | |
162 * The Groveller:: | |
163 * Static Linking:: | |
164 * Limitations:: | |
165 * Platform-specific features:: Details about the underlying system. | |
166 * Glossary:: List of CFFI-specific terms and meanings. | |
167 * Comprehensive Index:: | |
168 | |
169 @detailmenu | |
170 --- Dictionary --- | |
171 | |
172 Foreign Types | |
173 | |
174 * convert-from-foreign:: Outside interface to backward type trans… | |
175 * convert-to-foreign:: Outside interface to forward type transl… | |
176 * defbitfield:: Defines a bitfield. | |
177 * defcstruct:: Defines a C structure type. | |
178 * defcunion:: Defines a C union type. | |
179 * defctype:: Defines a foreign typedef. | |
180 * defcenum:: Defines a C enumeration. | |
181 * define-foreign-type:: Defines a foreign type specifier. | |
182 * define-parse-method:: Specifies how a type should be parsed. | |
183 @c * explain-foreign-slot-value:: <unimplemented> | |
184 * foreign-bitfield-symbols:: Returns a list of symbols for a bitfield… | |
185 * foreign-bitfield-value:: Calculates a value for a bitfield type. | |
186 * foreign-enum-keyword:: Finds a keyword in an enum type. | |
187 * foreign-enum-value:: Finds a value in an enum type. | |
188 * foreign-slot-names:: Returns a list of slot names in a foreig… | |
189 * foreign-slot-offset:: Returns the offset of a slot in a foreig… | |
190 * foreign-slot-pointer:: Returns a pointer to a slot in a foreign… | |
191 * foreign-slot-value:: Returns the value of a slot in a foreign… | |
192 * foreign-type-alignment:: Returns the alignment of a foreign type. | |
193 * foreign-type-size:: Returns the size of a foreign type. | |
194 * free-converted-object:: Outside interface to typed object deallo… | |
195 * free-translated-object:: Defines how to free a oreign object. | |
196 * translate-from-foreign:: Defines a foreign-to-Lisp object transla… | |
197 * translate-to-foreign:: Defines a Lisp-to-foreign object transla… | |
198 * with-foreign-object:: Allocates a foreign object with dynamic … | |
199 * with-foreign-objects:: Plural form of @code{with-foreign-object… | |
200 * with-foreign-slots:: Accesses the slots of a foreign structur… | |
201 | |
202 Pointers | |
203 | |
204 * foreign-free:: Deallocates memory. | |
205 * foreign-alloc:: Allocates memory. | |
206 * foreign-symbol-pointer:: Returns a pointer to a foreign symbol. | |
207 * inc-pointer:: Increments the address held by a pointer. | |
208 * incf-pointer:: Increments the pointer address in a plac… | |
209 * make-pointer:: Returns a pointer to a given address. | |
210 * mem-aptr:: The pointer to an element of an array. | |
211 * mem-aref:: Accesses the value of an index in an arr… | |
212 * mem-ref:: Dereferences a pointer. | |
213 * null-pointer:: Returns a NULL pointer. | |
214 * null-pointer-p:: Tests a pointer for NULL value. | |
215 * pointerp:: Tests whether an object is a pointer or … | |
216 * pointer-address:: Returns the address pointed to by a poin… | |
217 * pointer-eq:: Tests if two pointers point to the same … | |
218 * with-foreign-pointer:: Allocates memory with dynamic extent. | |
219 | |
220 Strings | |
221 | |
222 * *default-foreign-encoding*:: Default encoding for the string types. | |
223 * foreign-string-alloc:: Converts a Lisp string to a foreign stri… | |
224 * foreign-string-free:: Deallocates memory used by a foreign str… | |
225 * foreign-string-to-lisp:: Converts a foreign string to a Lisp stri… | |
226 * lisp-string-to-foreign:: Copies a Lisp string into a foreign stri… | |
227 * with-foreign-string:: Allocates a foreign string with dynamic … | |
228 * with-foreign-strings:: Plural form of @code{with-foreign-string… | |
229 * with-foreign-pointer-as-string:: Similar to CL's with-output-to-strin… | |
230 | |
231 Variables | |
232 | |
233 * defcvar:: Defines a C global variable. | |
234 * get-var-pointer:: Returns a pointer to a defined global va… | |
235 | |
236 Functions | |
237 | |
238 * defcfun:: Defines a foreign function. | |
239 * foreign-funcall:: Performs a call to a foreign function. | |
240 * foreign-funcall-pointer:: Performs a call through a foreign pointe… | |
241 * translate-camelcase-name:: Converts a camelCase foreign name to/fro… | |
242 * translate-name-from-foreign:: Converts a foreign name to a Lisp name. | |
243 * translate-name-to-foreign:: Converts a Lisp name to a foreign name. | |
244 * translate-underscore-separated-name:: Converts an underscore_separate… | |
245 | |
246 Libraries | |
247 | |
248 * close-foreign-library:: Closes a foreign library. | |
249 * *darwin-framework-directories*:: Search path for Darwin frameworks. | |
250 * define-foreign-library:: Explain how to load a foreign library. | |
251 * *foreign-library-directories*:: Search path for shared libraries. | |
252 * load-foreign-library:: Load a foreign library. | |
253 * load-foreign-library-error:: Signalled on failure of its namesake. | |
254 @c * reload-foreign-libraries:: Reload foreign libraries. | |
255 * use-foreign-library:: Load a foreign library when needed. | |
256 | |
257 Callbacks | |
258 | |
259 * callback:: Returns a pointer to a defined callback. | |
260 * defcallback:: Defines a Lisp callback. | |
261 * get-callback:: Returns a pointer to a defined callback. | |
262 | |
263 @end detailmenu | |
264 @end menu | |
265 | |
266 | |
267 | |
268 | |
269 @c =================================================================== | |
270 @c CHAPTER: Introduction | |
271 | |
272 @node Introduction, Installation, Top, Top | |
273 @chapter Introduction | |
274 | |
275 @cffi{} is the Common Foreign Function Interface for @acronym{ANSI} | |
276 Common Lisp systems. By @dfn{foreign function} we mean a function | |
277 written in another programming language and having different data and | |
278 calling conventions than Common Lisp, namely, C. @cffi{} allows you | |
279 to call foreign functions and access foreign variables, all without | |
280 leaving the Lisp image. | |
281 | |
282 We consider this manual ever a work in progress. If you have | |
283 difficulty with anything @cffi{}-specific presented in the manual, | |
284 please contact @email{cffi-devel@@common-lisp.net,the developers} with | |
285 details. | |
286 | |
287 | |
288 @heading Motivation | |
289 | |
290 @xref{Tutorial-Comparison,, What makes Lisp different}, for | |
291 an argument in favor of @acronym{FFI} in general. | |
292 | |
293 @cffi{}'s primary role in any image is to mediate between Lisp | |
294 developers and the widely varying @acronym{FFI}s present in the | |
295 various Lisp implementations it supports. With @cffi{}, you can | |
296 define foreign function interfaces while still maintaining portability | |
297 between implementations. It is not the first Common Lisp package with | |
298 this objective; however, it is meant to be a more malleable framework | |
299 than similar packages. | |
300 | |
301 | |
302 @heading Design Philosophy | |
303 | |
304 @itemize | |
305 @item | |
306 Pointers do not carry around type information. Instead, type | |
307 information is supplied when pointers are dereferenced. | |
308 | |
309 @item | |
310 A type safe pointer interface can be developed on top of an | |
311 untyped one. It is difficult to do the opposite. | |
312 | |
313 @item | |
314 Functions are better than macros. When a macro could be used | |
315 for performance, use a compiler-macro instead. | |
316 @end itemize | |
317 | |
318 | |
319 @c =================================================================== | |
320 @c CHAPTER: Installation | |
321 | |
322 @node Installation, Implementation Support, Introduction, Top | |
323 @chapter Installation | |
324 | |
325 @cffi{} can be obtained through one of the following means available | |
326 through its @uref{http://common-lisp.net/project/cffi/,,website}: | |
327 | |
328 @itemize | |
329 @item | |
330 @uref{http://common-lisp.net/project/cffi/releases/?M=D,,official release | |
331 tarballs} | |
332 | |
333 @item | |
334 @uref{http://common-lisp.net/gitweb?p=projects/cffi/cffi.git,,git | |
335 repository} | |
336 | |
337 @c snapshots have been disabled as of | |
338 @c @item | |
339 @c @uref{http://common-lisp.net/project/cffi/tarballs/?M=D,,nightly-gene… | |
340 @c snapshots} | |
341 | |
342 @end itemize | |
343 | |
344 In addition, you will need to obtain and install the following | |
345 dependencies: | |
346 | |
347 @itemize | |
348 @item | |
349 @uref{http://common-lisp.net/project/babel/,,Babel}, a charset | |
350 encoding/decoding library. | |
351 | |
352 @item | |
353 @uref{http://common-lisp.net/project/alexandria/,,Alexandria}, a | |
354 collection of portable public-domain utilities. | |
355 | |
356 @item | |
357 @uref{http://www.cliki.net/trivial-features,,trivial-features}, a | |
358 portability layer that ensures consistent @code{*features*} across | |
359 multiple Common Lisp implementations. | |
360 | |
361 @end itemize | |
362 | |
363 Furthermore, if you wish to run the testsuite, | |
364 @uref{http://www.cliki.net/rt,,RT} is required. | |
365 | |
366 You may find mechanisms such as | |
367 @uref{https://www.quicklisp.org/beta/,Quicklisp} (recommended) | |
368 or @uref{http://common-lisp.net/project/clbuild/,,clbuild} (for advanced | |
369 uses) helpful in getting and managing @cffi{} and its | |
370 dependencies. | |
371 | |
372 | |
373 @c =================================================================== | |
374 @c CHAPTER: Implementation Support | |
375 | |
376 @node Implementation Support, Tutorial, Installation, Top | |
377 @chapter Implementation Support | |
378 | |
379 @cffi{} supports various free and commercial Lisp implementations: | |
380 @acronym{ABCL}, Allegro CL, Clasp, @sc{clisp}, Clozure CL, | |
381 @acronym{CMUCL}, Corman CL, @acronym{ECL}, @acronym{GCL}, LispWorks, | |
382 @acronym{MCL}, @acronym{SBCL} and the Scieneer CL. | |
383 | |
384 In general, you should work with the latest versions of each | |
385 implementation since those will usually be tested against recent | |
386 versions of CFFI more often and might include necessary features or | |
387 bug fixes. Reasonable patches for compatibility with earlier versions | |
388 are welcome nevertheless. | |
389 | |
390 @section Limitations | |
391 | |
392 Some features are not supported in all implementations. | |
393 @c TODO: describe these features here. | |
394 @c flat-namespace too | |
395 | |
396 @subheading Allegro CL | |
397 | |
398 @itemize | |
399 @item | |
400 Does not support the @code{:long-long} type natively. | |
401 @item | |
402 Unicode support is limited to the Basic Multilingual Plane (16-bit | |
403 code points). | |
404 @end itemize | |
405 | |
406 @subheading Clasp | |
407 | |
408 @itemize | |
409 @item | |
410 Only supports a flat namespace. | |
411 @end itemize | |
412 | |
413 @subheading CMUCL | |
414 | |
415 @itemize | |
416 @item | |
417 No Unicode support. (8-bit code points) | |
418 @end itemize | |
419 | |
420 @subheading Corman CL | |
421 | |
422 @itemize | |
423 @item | |
424 Does not support @code{foreign-funcall}. | |
425 @end itemize | |
426 | |
427 @subheading @acronym{ECL} | |
428 | |
429 @itemize | |
430 @item | |
431 On platforms where ECL's dynamic FFI is not supported (ie. when | |
432 @code{:dffi} is not present in @code{*features*}), | |
433 @code{cffi:load-foreign-library} does not work and you must use ECL's | |
434 own @code{ffi:load-foreign-library} with a constant string argument. | |
435 @end itemize | |
436 | |
437 @subheading Lispworks | |
438 | |
439 @itemize | |
440 @item | |
441 Does not completely support the @code{:long-long} type natively in | |
442 32-bit platforms. | |
443 @item | |
444 Unicode support is limited to the Basic Multilingual Plane (16-bit | |
445 code points). | |
446 @end itemize | |
447 | |
448 @subheading @acronym{SBCL} | |
449 | |
450 @itemize | |
451 @item | |
452 Not all platforms support callbacks. | |
453 | |
454 @end itemize | |
455 | |
456 | |
457 @c =================================================================== | |
458 @c CHAPTER: An Introduction to Foreign Interfaces and CFFI | |
459 | |
460 @c This macro is merely a marker that I don't think I'll use after | |
461 @c all. | |
462 @macro tutorialsource {text} | |
463 @c \text\ | |
464 @end macro | |
465 | |
466 @c because I don't want to type this over and over | |
467 @macro clikicffi | |
468 http://www.cliki.net/CFFI | |
469 @end macro | |
470 @c TeX puts spurious newlines in when you use the above macro | |
471 @c in @examples &c. So it is expanded below in some places. | |
472 | |
473 | |
474 @node Tutorial, Wrapper generators, Implementation Support, Top | |
475 @chapter An Introduction to Foreign Interfaces and @acronym{CFFI} | |
476 | |
477 @c Above, I don't use the cffi macro because it breaks TeX. | |
478 | |
479 @cindex tutorial, @cffi{} | |
480 Users of many popular languages bearing semantic similarity to Lisp, | |
481 such as Perl and Python, are accustomed to having access to popular C | |
482 libraries, such as @acronym{GTK}, by way of ``bindings''. In Lisp, we | |
483 do something similar, but take a fundamentally different approach. | |
484 This tutorial first explains this difference, then explains how you | |
485 can use @cffi{}, a powerful system for calling out to C and C++ and | |
486 access C data from many Common Lisp implementations. | |
487 | |
488 @cindex foreign functions and data | |
489 The concept can be generalized to other languages; at the time of | |
490 writing, only @cffi{}'s C support is fairly complete. Therefore, we | |
491 will interchangeably refer to @dfn{foreign functions} and @dfn{foreign | |
492 data}, and ``C functions'' and ``C data''. At no time will the word | |
493 ``foreign'' carry its usual, non-programming meaning. | |
494 | |
495 This tutorial expects you to have a working understanding of both | |
496 Common Lisp and C, including the Common Lisp macro system. | |
497 | |
498 @menu | |
499 * Tutorial-Comparison:: Why FFI? | |
500 * Tutorial-Getting a URL:: An FFI use case. | |
501 * Tutorial-Loading:: Load libcurl.so. | |
502 * Tutorial-Initializing:: Call a function in libcurl.so. | |
503 * Tutorial-easy_setopt:: An advanced libcurl function. | |
504 * Tutorial-Abstraction:: Why breaking it is necessary. | |
505 * Tutorial-Lisp easy_setopt:: Semi-Lispy option interface. | |
506 * Tutorial-Memory:: In C, you collect the garbage. | |
507 * Tutorial-Callbacks:: Make useful C function pointers. | |
508 * Tutorial-Completion:: Minimal get-url functionality. | |
509 * Tutorial-Types:: Defining new foreign types. | |
510 * Tutorial-Conclusion:: What's next? | |
511 @end menu | |
512 | |
513 | |
514 @node Tutorial-Comparison, Tutorial-Getting a URL, Tutorial, Tutorial | |
515 @section What makes Lisp different | |
516 | |
517 The following sums up how bindings to foreign libraries are usually | |
518 implemented in other languages, then in Common Lisp: | |
519 | |
520 @table @asis | |
521 @item Perl, Python, Java, other one-implementation languages | |
522 @cindex @acronym{SWIG} | |
523 @cindex Perl | |
524 @cindex Python | |
525 Bindings are implemented as shared objects written in C. In some | |
526 cases, the C code is generated by a tool, such as @acronym{SWIG}, but | |
527 the result is the same: a new C library that manually translates | |
528 between the language implementation's objects, such as @code{PyObject} | |
529 in Python, and whatever C object is called for, often using C | |
530 functions provided by the implementation. It also translates between | |
531 the calling conventions of the language and C. | |
532 | |
533 @item Common Lisp | |
534 @cindex @acronym{SLIME} | |
535 Bindings are written in Lisp. They can be created at-will by Lisp | |
536 programs. Lisp programmers can write new bindings and add them to the | |
537 image, using a listener such as @acronym{SLIME}, as easily as with | |
538 regular Lisp definitions. The only foreign library to load is the one | |
539 being wrapped---the one with the pure C interface; no C or other | |
540 non-Lisp compilation is required. | |
541 @end table | |
542 | |
543 @cindex advantages of @acronym{FFI} | |
544 @cindex benefits of @acronym{FFI} | |
545 We believe the advantages of the Common Lisp approach far outweigh any | |
546 disadvantages. Incremental development with a listener can be as | |
547 productive for C binding development as it is with other Lisp | |
548 development. Keeping it ``in the [Lisp] family'', as it were, makes | |
549 it much easier for you and other Lisp programmers to load and use the | |
550 bindings. Common Lisp implementations such as @acronym{CMUCL}, freed | |
551 from having to provide a C interface to their own objects, are thus | |
552 freed to be implemented in another language (as @acronym{CMUCL} is) | |
553 while still allowing programmers to call foreign functions. | |
554 | |
555 @cindex minimal bindings | |
556 Perhaps the greatest advantage is that using an @acronym{FFI} doesn't | |
557 obligate you to become a professional binding developer. Writers of | |
558 bindings for other languages usually end up maintaining or failing to | |
559 maintain complete bindings to the foreign library. Using an | |
560 @acronym{FFI}, however, means if you only need one or two functions, | |
561 you can write bindings for only those functions, and be assured that | |
562 you can just as easily add to the bindings if need be. | |
563 | |
564 @cindex C abstractions | |
565 @cindex abstractions in C | |
566 The removal of the C compiler, or C interpretation of any kind, | |
567 creates the main disadvantage: some of C's ``abstractions'' are not | |
568 available, violating information encapsulation. For example, | |
569 @code{struct}s that must be passed on the stack, or used as return | |
570 values, without corresponding functional abstractions to create and | |
571 manage the @code{struct}s, must be declared explicitly in Lisp. This | |
572 is fine for structs whose contents are ``public'', but is not so | |
573 pleasant when a struct is supposed to be ``opaque'' by convention, | |
574 even though it is not so defined.@footnote{Admittedly, this is an | |
575 advanced issue, and we encourage you to leave this text until you are | |
576 more familiar with how @cffi{} works.} | |
577 | |
578 Without an abstraction to create the struct, Lisp needs to be able to | |
579 lay out the struct in memory, so must know its internal details. | |
580 | |
581 @cindex workaround for C | |
582 In these cases, you can create a minimal C library to provide the | |
583 missing abstractions, without destroying all the advantages of the | |
584 Common Lisp approach discussed above. In the case of @code{struct}s, | |
585 you can write simple, pure C functions that tell you how many bytes a | |
586 struct requires or allocate new structs, read and write fields of the | |
587 struct, or whatever operations are supposed to be | |
588 public.@footnote{This does not apply to structs whose contents are | |
589 intended to be part of the public library interface. In those cases, | |
590 a pure Lisp struct definition is always preferred. In fact, many | |
591 prefer to stay in Lisp and break the encapsulation anyway, placing the | |
592 burden of correct library interface definition on the library.} | |
593 @ref{The Groveller} automates this and other processes. | |
594 | |
595 Another disadvantage appears when you would rather use the foreign | |
596 language than Lisp. However, someone who prefers C to Lisp is not a | |
597 likely candidate for developing a Lisp interface to a C library. | |
598 | |
599 | |
600 @node Tutorial-Getting a URL, Tutorial-Loading, Tutorial-Comparison, Tut… | |
601 @section Getting a @acronym{URL} | |
602 | |
603 @cindex c@acronym{URL} | |
604 The widely available @code{libcurl} is a library for downloading files | |
605 over protocols like @acronym{HTTP}. We will use @code{libcurl} with | |
606 @cffi{} to download a web page. | |
607 | |
608 Please note that there are many other ways to download files from the | |
609 web, not least the @sc{cl-curl} project to provide bindings to | |
610 @code{libcurl} via a similar @acronym{FFI}.@footnote{Specifically, | |
611 @acronym{UFFI}, an older @acronym{FFI} that takes a somewhat different | |
612 approach compared to @cffi{}. I believe that these days (December | |
613 2005) @cffi{} is more portable and actively developed, though not as | |
614 mature yet. Consensus in the free @sc{unix} Common Lisp community | |
615 seems to be that @cffi{} is preferred for new development, though | |
616 @acronym{UFFI} will likely go on for quite some time as many projects | |
617 already use it. @cffi{} includes the @code{UFFI-COMPAT} package for | |
618 complete compatibility with @acronym{UFFI}.} | |
619 | |
620 @uref{http://curl.haxx.se/libcurl/c/libcurl-tutorial.html,,libcurl-tutor… | |
621 is a tutorial for @code{libcurl} programming in C. We will follow | |
622 that to develop a binding to download a file. We will also use | |
623 @file{curl.h}, @file{easy.h}, and the @command{man} pages for the | |
624 @code{libcurl} function, all available in the @samp{curl-dev} package | |
625 or equivalent for your system, or in the c@acronym{URL} source code | |
626 package. If you have the development package, the headers should be | |
627 installed in @file{/usr/include/curl/}, and the @command{man} pages | |
628 may be accessed through your favorite @command{man} facility. | |
629 | |
630 | |
631 @node Tutorial-Loading, Tutorial-Initializing, Tutorial-Getting a URL, T… | |
632 @section Loading foreign libraries | |
633 | |
634 @cindex loading @cffi{} | |
635 @cindex requiring @cffi{} | |
636 First of all, we will create a package to work in. You can save these | |
637 forms in a file, or just send them to the listener as they are. If | |
638 creating bindings for an @acronym{ASDF} package of yours, you will | |
639 want to add @code{:cffi} to the @code{:depends-on} list in your | |
640 @file{.asd} file. Otherwise, just use the @code{asdf:load-system} funct… | |
641 load @cffi{}. | |
642 | |
643 @tutorialsource{Initialization} | |
644 @lisp | |
645 (asdf:load-system :cffi) | |
646 | |
647 ;;; @lispcmt{Nothing special about the "CFFI-USER" package. We're just} | |
648 ;;; @lispcmt{using it as a substitute for your own CL package.} | |
649 (defpackage :cffi-user | |
650 (:use :common-lisp :cffi)) | |
651 | |
652 (in-package :cffi-user) | |
653 | |
654 (define-foreign-library libcurl | |
655 (:darwin (:or "libcurl.3.dylib" "libcurl.dylib")) | |
656 (:unix (:or "libcurl.so.3" "libcurl.so")) | |
657 (t (:default "libcurl"))) | |
658 | |
659 (use-foreign-library libcurl) | |
660 @end lisp | |
661 | |
662 @cindex foreign library load | |
663 @cindex library, foreign | |
664 Using @code{define-foreign-library} and @code{use-foreign-library}, we | |
665 have loaded @code{libcurl} into Lisp, much as the linker does when you | |
666 start a C program, or @code{common-lisp:load} does with a Lisp source | |
667 file or @acronym{FASL} file. We special-cased for @sc{unix} machines | |
668 to always load a particular version, the one this tutorial was tested | |
669 with; for those who don't care, the @code{define-foreign-library} | |
670 clause @code{(t (:default "libcurl"))} should be satisfactory, and | |
671 will adapt to various operating systems. | |
672 | |
673 | |
674 @node Tutorial-Initializing, Tutorial-easy_setopt, Tutorial-Loading, Tut… | |
675 @section Initializing @code{libcurl} | |
676 | |
677 @cindex function definition | |
678 After the introductory matter, the tutorial goes on to present the | |
679 first function you should use. | |
680 | |
681 @example | |
682 CURLcode curl_global_init(long flags); | |
683 @end example | |
684 | |
685 @noindent | |
686 Let's pick this apart into appropriate Lisp code: | |
687 | |
688 @tutorialsource{First CURLcode} | |
689 @lisp | |
690 ;;; @lispcmt{A CURLcode is the universal error code. curl/curl.h says} | |
691 ;;; @lispcmt{no return code will ever be removed, and new ones will be} | |
692 ;;; @lispcmt{added to the end.} | |
693 (defctype curl-code :int) | |
694 | |
695 ;;; @lispcmt{Initialize libcurl with FLAGS.} | |
696 (defcfun "curl_global_init" curl-code | |
697 (flags :long)) | |
698 @end lisp | |
699 | |
700 @impnote{By default, CFFI assumes the UNIX viewpoint that there is one | |
701 C symbol namespace, containing all symbols in all loaded objects. | |
702 This is not so on Windows and Darwin, but we emulate UNIX's behaviour | |
703 there. @ref{defcfun} for more details.} | |
704 | |
705 Note the parallels with the original C declaration. We've defined | |
706 @code{curl-code} as a wrapping type for @code{:int}; right now, it | |
707 only marks it as special, but later we will do something more | |
708 interesting with it. The point is that we don't have to do it yet. | |
709 | |
710 @cindex calling foreign functions | |
711 Looking at @file{curl.h}, @code{CURL_GLOBAL_NOTHING}, a possible value | |
712 for @code{flags} above, is defined as @samp{0}. So we can now call | |
713 the function: | |
714 | |
715 @example | |
716 @sc{cffi-user>} (curl-global-init 0) | |
717 @result{} 0 | |
718 @end example | |
719 | |
720 @cindex looks like it worked | |
721 Looking at @file{curl.h} again, @code{0} means @code{CURLE_OK}, so it | |
722 looks like the call succeeded. Note that @cffi{} converted the | |
723 function name to a Lisp-friendly name. You can specify your own name | |
724 if you want; use @code{("curl_global_init" @var{your-name-here})} as | |
725 the @var{name} argument to @code{defcfun}. | |
726 | |
727 The tutorial goes on to have us allocate a handle. For good measure, | |
728 we should also include the deallocator. Let's look at these | |
729 functions: | |
730 | |
731 @example | |
732 CURL *curl_easy_init( ); | |
733 void curl_easy_cleanup(CURL *handle); | |
734 @end example | |
735 | |
736 Advanced users may want to define special pointer types; we will | |
737 explore this possibility later. For now, just treat every pointer as | |
738 the same: | |
739 | |
740 @tutorialsource{curl_easy handles} | |
741 @lisp | |
742 (defcfun "curl_easy_init" :pointer) | |
743 | |
744 (defcfun "curl_easy_cleanup" :void | |
745 (easy-handle :pointer)) | |
746 @end lisp | |
747 | |
748 Now we can continue with the tutorial: | |
749 | |
750 @example | |
751 @sc{cffi-user>} (defparameter *easy-handle* (curl-easy-init)) | |
752 @result{} *EASY-HANDLE* | |
753 @sc{cffi-user>} *easy-handle* | |
754 @result{} #<FOREIGN-ADDRESS #x09844EE0> | |
755 @end example | |
756 | |
757 @cindex pointers in Lisp | |
758 Note the print representation of a pointer. It changes depending on | |
759 what Lisp you are using, but that doesn't make any difference to | |
760 @cffi{}. | |
761 | |
762 | |
763 @node Tutorial-easy_setopt, Tutorial-Abstraction, Tutorial-Initializing,… | |
764 @section Setting download options | |
765 | |
766 The @code{libcurl} tutorial says we'll want to set many options before | |
767 performing any download actions. This is done through | |
768 @code{curl_easy_setopt}: | |
769 | |
770 @c That is literally ..., not an ellipsis. | |
771 @example | |
772 CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...); | |
773 @end example | |
774 | |
775 @cindex varargs | |
776 @cindex foreign arguments | |
777 We've introduced a new twist: variable arguments. There is no obvious | |
778 translation to the @code{defcfun} form, particularly as there are four | |
779 possible argument types. Because of the way C works, we could define | |
780 four wrappers around @code{curl_easy_setopt}, one for each type; in | |
781 this case, however, we'll use the general-purpose macro | |
782 @code{foreign-funcall} to call this function. | |
783 | |
784 @cindex enumeration, C | |
785 To make things easier on ourselves, we'll create an enumeration of the | |
786 kinds of options we want to set. The @code{enum CURLoption} isn't the | |
787 most straightforward, but reading the @code{CINIT} C macro definition | |
788 should be enlightening. | |
789 | |
790 @tutorialsource{CURLoption enumeration} | |
791 @lisp | |
792 (defmacro define-curl-options (name type-offsets &rest enum-args) | |
793 "As with CFFI:DEFCENUM, except each of ENUM-ARGS is as follows: | |
794 | |
795 (NAME TYPE NUMBER) | |
796 | |
797 Where the arguments are as they are with the CINIT macro defined | |
798 in curl.h, except NAME is a keyword. | |
799 | |
800 TYPE-OFFSETS is a plist of TYPEs to their integer offsets, as | |
801 defined by the CURLOPTTYPE_LONG et al constants in curl.h." | |
802 (flet ((enumerated-value (type offset) | |
803 (+ (getf type-offsets type) offset))) | |
804 `(progn | |
805 (defcenum ,name | |
806 ,@@(loop for (name type number) in enum-args | |
807 collect (list name (enumerated-value type number)))) | |
808 ',name))) ;@lispcmt{for REPL users' sanity} | |
809 | |
810 (define-curl-options curl-option | |
811 (long 0 objectpoint 10000 functionpoint 20000 off-t 30000) | |
812 (:noprogress long 43) | |
813 (:nosignal long 99) | |
814 (:errorbuffer objectpoint 10) | |
815 (:url objectpoint 2)) | |
816 @end lisp | |
817 | |
818 With some well-placed Emacs @code{query-replace-regexp}s, you could | |
819 probably similarly define the entire @code{CURLoption} enumeration. I | |
820 have selected to transcribe a few that we will use in this tutorial. | |
821 | |
822 If you're having trouble following the macrology, just macroexpand the | |
823 @code{curl-option} definition, or see the following macroexpansion, | |
824 conveniently downcased and reformatted: | |
825 | |
826 @tutorialsource{DEFINE-CURL-OPTIONS macroexpansion} | |
827 @lisp | |
828 (progn | |
829 (defcenum curl-option | |
830 (:noprogress 43) | |
831 (:nosignal 99) | |
832 (:errorbuffer 10010) | |
833 (:url 10002)) | |
834 'curl-option) | |
835 @end lisp | |
836 | |
837 @noindent | |
838 That seems more than reasonable. You may notice that we only use the | |
839 @var{type} to compute the real enumeration offset; we will also need | |
840 the type information later. | |
841 | |
842 First, however, let's make sure a simple call to the foreign function | |
843 works: | |
844 | |
845 @example | |
846 @sc{cffi-user>} (foreign-funcall "curl_easy_setopt" | |
847 :pointer *easy-handle* | |
848 curl-option :nosignal :long 1 curl-code) | |
849 @result{} 0 | |
850 @end example | |
851 | |
852 @code{foreign-funcall}, despite its surface simplicity, can be used to | |
853 call any C function. Its first argument is a string, naming the | |
854 function to be called. Next, for each argument, we pass the name of | |
855 the C type, which is the same as in @code{defcfun}, followed by a Lisp | |
856 object representing the data to be passed as the argument. The final | |
857 argument is the return type, for which we use the @code{curl-code} | |
858 type defined earlier. | |
859 | |
860 @code{defcfun} just puts a convenient fa@,cade on | |
861 @code{foreign-funcall}.@footnote{This isn't entirely true; some Lisps | |
862 don't support @code{foreign-funcall}, so @code{defcfun} is implemented | |
863 without it. @code{defcfun} may also perform optimizations that | |
864 @code{foreign-funcall} cannot.} Our earlier call to | |
865 @code{curl-global-init} could have been written as follows: | |
866 | |
867 @example | |
868 @sc{cffi-user>} (foreign-funcall "curl_global_init" :long 0 | |
869 curl-code) | |
870 @result{} 0 | |
871 @end example | |
872 | |
873 Before we continue, we will take a look at what @cffi{} can and can't | |
874 do, and why this is so. | |
875 | |
876 | |
877 @node Tutorial-Abstraction, Tutorial-Lisp easy_setopt, Tutorial-easy_set… | |
878 @section Breaking the abstraction | |
879 | |
880 @cindex breaking the abstraction | |
881 @cindex abstraction breaking | |
882 In @ref{Tutorial-Comparison,, What makes Lisp different}, we mentioned | |
883 that writing an @acronym{FFI} sometimes requires depending on | |
884 information not provided as part of the interface. The easy option | |
885 @code{CURLOPT_WRITEDATA}, which we will not provide as part of the | |
886 Lisp interface, illustrates this issue. | |
887 | |
888 Strictly speaking, the @code{curl-option} enumeration is not | |
889 necessary; we could have used @code{:int 99} instead of | |
890 @code{curl-option :nosignal} in our call to @code{curl_easy_setopt} | |
891 above. We defined it anyway, in part to hide the fact that we are | |
892 breaking the abstraction that the C @code{enum} provides. If the | |
893 c@acronym{URL} developers decide to change those numbers later, we | |
894 must change the Lisp enumeration, because enumeration values are not | |
895 provided in the compiled C library, @code{libcurl.so.3}. | |
896 | |
897 @cffi{} works because the most useful things in C libraries --- | |
898 non-static functions and non-static variables --- are included | |
899 accessibly in @code{libcurl.so.3}. A C compiler that violated this | |
900 would be considered a worthless compiler. | |
901 | |
902 The other thing @code{define-curl-options} does is give the ``type'' | |
903 of the third argument passed to @code{curl_easy_setopt}. Using this | |
904 information, we can tell that the @code{:nosignal} option should | |
905 accept a long integer argument. We can implicitly assume @code{t} | |
906 @equiv{} 1 and @code{nil} @equiv{} 0, as it is in C, which takes care | |
907 of the fact that @code{CURLOPT_NOSIGNAL} is really asking for a | |
908 boolean. | |
909 | |
910 The ``type'' of @code{CURLOPT_WRITEDATA} is @code{objectpoint}. | |
911 However, it is really looking for a @code{FILE*}. | |
912 @code{CURLOPT_ERRORBUFFER} is looking for a @code{char*}, so there is | |
913 no obvious @cffi{} type but @code{:pointer}. | |
914 | |
915 The first thing to note is that nowhere in the C interface includes | |
916 this information; it can only be found in the manual. We could | |
917 disjoin these clearly different types ourselves, by splitting | |
918 @code{objectpoint} into @code{filepoint} and @code{charpoint}, but we | |
919 are still breaking the abstraction, because we have to augment the | |
920 entire enumeration form with this additional | |
921 information.@footnote{Another possibility is to allow the caller to | |
922 specify the desired C type of the third argument. This is essentially | |
923 what happens in a call to the function written in C.} | |
924 | |
925 @cindex streams and C | |
926 @cindex @sc{file}* and streams | |
927 The second is that the @code{CURLOPT_WRITEDATA} argument is completely | |
928 incompatible with the desired Lisp data, a | |
929 stream.@footnote{@xref{Other Kinds of Streams,,, libc, GNU C Library | |
930 Reference}, for a @acronym{GNU}-only way to extend the @code{FILE*} | |
931 type. You could use this to convert Lisp streams to the needed C | |
932 data. This would be quite involved and far outside the scope of this | |
933 tutorial.} It is probably acceptable if we are controlling every file | |
934 we might want to use as this argument, in which case we can just call | |
935 the foreign function @code{fopen}. Regardless, though, we can't write | |
936 to arbitrary streams, which is exactly what we want to do for this | |
937 application. | |
938 | |
939 Finally, note that the @code{curl_easy_setopt} interface itself is a | |
940 hack, intended to work around some of the drawbacks of C. The | |
941 definition of @code{Curl_setopt}, while long, is far less cluttered | |
942 than the equivalent disjoint-function set would be; in addition, | |
943 setting a new option in an old @code{libcurl} can generate a run-time | |
944 error rather than breaking the compile. Lisp can just as concisely | |
945 generate functions as compare values, and the ``undefined function'' | |
946 error is just as useful as any explicit error we could define here | |
947 might be. | |
948 | |
949 | |
950 @node Tutorial-Lisp easy_setopt, Tutorial-Memory, Tutorial-Abstraction, … | |
951 @section Option functions in Lisp | |
952 | |
953 We could use @code{foreign-funcall} directly every time we wanted to | |
954 call @code{curl_easy_setopt}. However, we can encapsulate some of the | |
955 necessary information with the following. | |
956 | |
957 @lisp | |
958 ;;; @lispcmt{We will use this type later in a more creative way. For} | |
959 ;;; @lispcmt{now, just consider it a marker that this isn't just any} | |
960 ;;; @lispcmt{pointer.} | |
961 (defctype easy-handle :pointer) | |
962 | |
963 (defmacro curl-easy-setopt (easy-handle enumerated-name | |
964 value-type new-value) | |
965 "Call `curl_easy_setopt' on EASY-HANDLE, using ENUMERATED-NAME | |
966 as the OPTION. VALUE-TYPE is the CFFI foreign type of the third | |
967 argument, and NEW-VALUE is the Lisp data to be translated to the | |
968 third argument. VALUE-TYPE is not evaluated." | |
969 `(foreign-funcall "curl_easy_setopt" easy-handle ,easy-handle | |
970 curl-option ,enumerated-name | |
971 ,value-type ,new-value curl-code)) | |
972 @end lisp | |
973 | |
974 Now we define a function for each kind of argument that encodes the | |
975 correct @code{value-type} in the above. This can be done reasonably | |
976 in the @code{define-curl-options} macroexpansion; after all, that is | |
977 where the different options are listed! | |
978 | |
979 @cindex Lispy C functions | |
980 We could make @code{cl:defun} forms in the expansion that simply call | |
981 @code{curl-easy-setopt}; however, it is probably easier and clearer to | |
982 use @code{defcfun}. @code{define-curl-options} was becoming unwieldy, | |
983 so I defined some helpers in this new definition. | |
984 | |
985 @smalllisp | |
986 (defun curry-curl-option-setter (function-name option-keyword) | |
987 "Wrap the function named by FUNCTION-NAME with a version that | |
988 curries the second argument as OPTION-KEYWORD. | |
989 | |
990 This function is intended for use in DEFINE-CURL-OPTION-SETTER." | |
991 (setf (symbol-function function-name) | |
992 (let ((c-function (symbol-function function-name))) | |
993 (lambda (easy-handle new-value) | |
994 (funcall c-function easy-handle option-keyword | |
995 new-value))))) | |
996 | |
997 (defmacro define-curl-option-setter (name option-type | |
998 option-value foreign-type) | |
999 "Define (with DEFCFUN) a function NAME that calls | |
1000 curl_easy_setopt. OPTION-TYPE and OPTION-VALUE are the CFFI | |
1001 foreign type and value to be passed as the second argument to | |
1002 easy_setopt, and FOREIGN-TYPE is the CFFI foreign type to be used | |
1003 for the resultant function's third argument. | |
1004 | |
1005 This macro is intended for use in DEFINE-CURL-OPTIONS." | |
1006 `(progn | |
1007 (defcfun ("curl_easy_setopt" ,name) curl-code | |
1008 (easy-handle easy-handle) | |
1009 (option ,option-type) | |
1010 (new-value ,foreign-type)) | |
1011 (curry-curl-option-setter ',name ',option-value))) | |
1012 | |
1013 (defmacro define-curl-options (type-name type-offsets &rest enum-args) | |
1014 "As with CFFI:DEFCENUM, except each of ENUM-ARGS is as follows: | |
1015 | |
1016 (NAME TYPE NUMBER) | |
1017 | |
1018 Where the arguments are as they are with the CINIT macro defined | |
1019 in curl.h, except NAME is a keyword. | |
1020 | |
1021 TYPE-OFFSETS is a plist of TYPEs to their integer offsets, as | |
1022 defined by the CURLOPTTYPE_LONG et al constants in curl.h. | |
1023 | |
1024 Also, define functions for each option named | |
1025 set-`TYPE-NAME'-`OPTION-NAME', where OPTION-NAME is the NAME from | |
1026 the above destructuring." | |
1027 (flet ((enumerated-value (type offset) | |
1028 (+ (getf type-offsets type) offset)) | |
1029 ;; @lispcmt{map PROCEDURE, destructuring each of ENUM-ARGS} | |
1030 (map-enum-args (procedure) | |
1031 (mapcar (lambda (arg) (apply procedure arg)) enum-args)) | |
1032 ;; @lispcmt{build a name like SET-CURL-OPTION-NOSIGNAL} | |
1033 (make-setter-name (option-name) | |
1034 (intern (concatenate | |
1035 'string "SET-" (symbol-name type-name) | |
1036 "-" (symbol-name option-name))))) | |
1037 `(progn | |
1038 (defcenum ,type-name | |
1039 ,@@(map-enum-args | |
1040 (lambda (name type number) | |
1041 (list name (enumerated-value type number))))) | |
1042 ,@@(map-enum-args | |
1043 (lambda (name type number) | |
1044 (declare (ignore number)) | |
1045 `(define-curl-option-setter ,(make-setter-name name) | |
1046 ,type-name ,name ,(ecase type | |
1047 (long :long) | |
1048 (objectpoint :pointer) | |
1049 (functionpoint :pointer) | |
1050 (off-t :long))))) | |
1051 ',type-name))) | |
1052 @end smalllisp | |
1053 | |
1054 @noindent | |
1055 Macroexpanding our @code{define-curl-options} form once more, we | |
1056 see something different: | |
1057 | |
1058 @lisp | |
1059 (progn | |
1060 (defcenum curl-option | |
1061 (:noprogress 43) | |
1062 (:nosignal 99) | |
1063 (:errorbuffer 10010) | |
1064 (:url 10002)) | |
1065 (define-curl-option-setter set-curl-option-noprogress | |
1066 curl-option :noprogress :long) | |
1067 (define-curl-option-setter set-curl-option-nosignal | |
1068 curl-option :nosignal :long) | |
1069 (define-curl-option-setter set-curl-option-errorbuffer | |
1070 curl-option :errorbuffer :pointer) | |
1071 (define-curl-option-setter set-curl-option-url | |
1072 curl-option :url :pointer) | |
1073 'curl-option) | |
1074 @end lisp | |
1075 | |
1076 @noindent | |
1077 Macroexpanding one of the new @code{define-curl-option-setter} | |
1078 forms yields the following: | |
1079 | |
1080 @lisp | |
1081 (progn | |
1082 (defcfun ("curl_easy_setopt" set-curl-option-nosignal) curl-code | |
1083 (easy-handle easy-handle) | |
1084 (option curl-option) | |
1085 (new-value :long)) | |
1086 (curry-curl-option-setter 'set-curl-option-nosignal ':nosignal)) | |
1087 @end lisp | |
1088 | |
1089 @noindent | |
1090 Finally, let's try this out: | |
1091 | |
1092 @example | |
1093 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1) | |
1094 @result{} 0 | |
1095 @end example | |
1096 | |
1097 @noindent | |
1098 Looks like it works just as well. This interface is now reasonably | |
1099 high-level to wash out some of the ugliness of the thinnest possible | |
1100 @code{curl_easy_setopt} @acronym{FFI}, without obscuring the remaining | |
1101 C bookkeeping details we will explore. | |
1102 | |
1103 | |
1104 @node Tutorial-Memory, Tutorial-Callbacks, Tutorial-Lisp easy_setopt, Tu… | |
1105 @section Memory management | |
1106 | |
1107 According to the documentation for @code{curl_easy_setopt}, the type | |
1108 of the third argument when @var{option} is @code{CURLOPT_ERRORBUFFER} | |
1109 is @code{char*}. Above, we've defined | |
1110 @code{set-curl-option-errorbuffer} to accept a @code{:pointer} as the | |
1111 new option value. However, there is a @cffi{} type @code{:string}, | |
1112 which translates Lisp strings to C strings when passed as arguments to | |
1113 foreign function calls. Why not, then, use @code{:string} as the | |
1114 @cffi{} type of the third argument? There are two reasons, both | |
1115 related to the necessity of breaking abstraction described in | |
1116 @ref{Tutorial-Abstraction,, Breaking the abstraction}. | |
1117 | |
1118 The first reason also applies to @code{CURLOPT_URL}, which we will use | |
1119 to illustrate the point. Assuming we have changed the type of the | |
1120 third argument underlying @code{set-curl-option-url} to | |
1121 @code{:string}, look at these two equivalent forms. | |
1122 | |
1123 @lisp | |
1124 (set-curl-option-url *easy-handle* "http://www.cliki.net/CFFI") | |
1125 | |
1126 @equiv{} (with-foreign-string (url "http://www.cliki.net/CFFI") | |
1127 (foreign-funcall "curl_easy_setopt" easy-handle *easy-handle* | |
1128 curl-option :url :pointer url curl-code)) | |
1129 @end lisp | |
1130 | |
1131 @noindent | |
1132 The latter, in fact, is mostly equivalent to what a foreign function | |
1133 call's macroexpansion actually does. As you can see, the Lisp string | |
1134 @code{"@clikicffi{}"} is copied into a @code{char} array and | |
1135 null-terminated; the pointer to beginning of this array, now a C | |
1136 string, is passed as a @cffi{} @code{:pointer} to the foreign | |
1137 function. | |
1138 | |
1139 @cindex dynamic extent | |
1140 @cindex foreign values with dynamic extent | |
1141 Unfortunately, the C abstraction has failed us, and we must break it. | |
1142 While @code{:string} works well for many @code{char*} arguments, it | |
1143 does not for cases like this. As the @code{curl_easy_setopt} | |
1144 documentation explains, ``The string must remain present until curl no | |
1145 longer needs it, as it doesn't copy the string.'' The C string | |
1146 created by @code{with-foreign-string}, however, only has dynamic | |
1147 extent: it is ``deallocated'' when the body (above containing the | |
1148 @code{foreign-funcall} form) exits. | |
1149 | |
1150 @cindex premature deallocation | |
1151 If we are supposed to keep the C string around, but it goes away, what | |
1152 happens when some @code{libcurl} function tries to access the | |
1153 @acronym{URL} string? We have reentered the dreaded world of C | |
1154 ``undefined behavior''. In some Lisps, it will probably get a chunk | |
1155 of the Lisp/C stack. You may segfault. You may get some random piece | |
1156 of other data from the heap. Maybe, in a world where ``dynamic | |
1157 extent'' is defined to be ``infinite extent'', everything will turn | |
1158 out fine. Regardless, results are likely to be almost universally | |
1159 unpleasant.@footnote{``@i{But I thought Lisp was supposed to protect | |
1160 me from all that buggy C crap!}'' Before asking a question like that, | |
1161 remember that you are a stranger in a foreign land, whose residents | |
1162 have a completely different set of values.} | |
1163 | |
1164 Returning to the current @code{set-curl-option-url} interface, here is | |
1165 what we must do: | |
1166 | |
1167 @lisp | |
1168 (let (easy-handle) | |
1169 (unwind-protect | |
1170 (with-foreign-string (url "http://www.cliki.net/CFFI") | |
1171 (setf easy-handle (curl-easy-init)) | |
1172 (set-curl-option-url easy-handle url) | |
1173 #|@lispcmt{do more with the easy-handle, like actually get the URL… | |
1174 (when easy-handle | |
1175 (curl-easy-cleanup easy-handle)))) | |
1176 @end lisp | |
1177 | |
1178 @c old comment to luis: I go on to say that this isn't obviously | |
1179 @c extensible to new option settings that require C strings to stick | |
1180 @c around, as it would involve re-evaluating the unwind-protect form | |
1181 @c with more dynamic memory allocation. So I plan to show how to | |
1182 @c write something similar to ObjC's NSAutoreleasePool, to be managed | |
1183 @c with a simple unwind-protect form. | |
1184 | |
1185 @noindent | |
1186 That is fine for the single string defined here, but for every string | |
1187 option we want to pass, we have to surround the body of | |
1188 @code{with-foreign-string} with another @code{with-foreign-string} | |
1189 wrapper, or else do some extremely error-prone pointer manipulation | |
1190 and size calculation in advance. We could alleviate some of the pain | |
1191 with a recursively expanding macro, but this would not remove the need | |
1192 to modify the block every time we want to add an option, anathema as | |
1193 it is to a modular interface. | |
1194 | |
1195 Before modifying the code to account for this case, consider the other | |
1196 reason we can't simply use @code{:string} as the foreign type. In C, | |
1197 a @code{char *} is a @code{char *}, not necessarily a string. The | |
1198 option @code{CURLOPT_ERRORBUFFER} accepts a @code{char *}, but does | |
1199 not expect anything about the data there. However, it does expect | |
1200 that some @code{libcurl} function we call later can write a C string | |
1201 of up to 255 characters there. We, the callers of the function, are | |
1202 expected to read the C string at a later time, exactly the opposite of | |
1203 what @code{:string} implies. | |
1204 | |
1205 With the semantics for an input string in mind --- namely, that the | |
1206 string should be kept around until we @code{curl_easy_cleanup} the | |
1207 easy handle --- we are ready to extend the Lisp interface: | |
1208 | |
1209 @lisp | |
1210 (defvar *easy-handle-cstrings* (make-hash-table) | |
1211 "Hashtable of easy handles to lists of C strings that may be | |
1212 safely freed after the handle is freed.") | |
1213 | |
1214 (defun make-easy-handle () | |
1215 "Answer a new CURL easy interface handle, to which the lifetime | |
1216 of C strings may be tied. See `add-curl-handle-cstring'." | |
1217 (let ((easy-handle (curl-easy-init))) | |
1218 (setf (gethash easy-handle *easy-handle-cstrings*) '()) | |
1219 easy-handle)) | |
1220 | |
1221 (defun free-easy-handle (handle) | |
1222 "Free CURL easy interface HANDLE and any C strings created to | |
1223 be its options." | |
1224 (curl-easy-cleanup handle) | |
1225 (mapc #'foreign-string-free | |
1226 (gethash handle *easy-handle-cstrings*)) | |
1227 (remhash handle *easy-handle-cstrings*)) | |
1228 | |
1229 (defun add-curl-handle-cstring (handle cstring) | |
1230 "Add CSTRING to be freed when HANDLE is, answering CSTRING." | |
1231 (car (push cstring (gethash handle *easy-handle-cstrings*)))) | |
1232 @end lisp | |
1233 | |
1234 @noindent | |
1235 Here we have redefined the interface to create and free handles, to | |
1236 associate a list of allocated C strings with each handle while it | |
1237 exists. The strategy of using different function names to wrap around | |
1238 simple foreign functions is more common than the solution implemented | |
1239 earlier with @code{curry-curl-option-setter}, which was to modify the | |
1240 function name's function slot.@footnote{There are advantages and | |
1241 disadvantages to each approach; I chose to @code{(setf | |
1242 symbol-function)} earlier because it entailed generating fewer magic | |
1243 function names.} | |
1244 | |
1245 Incidentally, the next step is to redefine | |
1246 @code{curry-curl-option-setter} to allocate C strings for the | |
1247 appropriate length of time, given a Lisp string as the | |
1248 @code{new-value} argument: | |
1249 | |
1250 @lisp | |
1251 (defun curry-curl-option-setter (function-name option-keyword) | |
1252 "Wrap the function named by FUNCTION-NAME with a version that | |
1253 curries the second argument as OPTION-KEYWORD. | |
1254 | |
1255 This function is intended for use in DEFINE-CURL-OPTION-SETTER." | |
1256 (setf (symbol-function function-name) | |
1257 (let ((c-function (symbol-function function-name))) | |
1258 (lambda (easy-handle new-value) | |
1259 (funcall c-function easy-handle option-keyword | |
1260 (if (stringp new-value) | |
1261 (add-curl-handle-cstring | |
1262 easy-handle | |
1263 (foreign-string-alloc new-value)) | |
1264 new-value)))))) | |
1265 @end lisp | |
1266 | |
1267 @noindent | |
1268 A quick analysis of the code shows that you need only reevaluate the | |
1269 @code{curl-option} enumeration definition to take advantage of these | |
1270 new semantics. Now, for good measure, let's reallocate the handle | |
1271 with the new functions we just defined, and set its @acronym{URL}: | |
1272 | |
1273 @example | |
1274 @sc{cffi-user>} (curl-easy-cleanup *easy-handle*) | |
1275 @result{} NIL | |
1276 @sc{cffi-user>} (setf *easy-handle* (make-easy-handle)) | |
1277 @result{} #<FOREIGN-ADDRESS #x09844EE0> | |
1278 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1) | |
1279 @result{} 0 | |
1280 @sc{cffi-user>} (set-curl-option-url *easy-handle* | |
1281 "http://www.cliki.net/CFFI") | |
1282 @result{} 0 | |
1283 @end example | |
1284 | |
1285 @cindex strings | |
1286 For fun, let's inspect the Lisp value of the C string that was created | |
1287 to hold @code{"@clikicffi{}"}. By virtue of the implementation of | |
1288 @code{add-curl-handle-cstring}, it should be accessible through the | |
1289 hash table defined: | |
1290 | |
1291 @example | |
1292 @sc{cffi-user>} (foreign-string-to-lisp | |
1293 (car (gethash *easy-handle* *easy-handle-cstrings*))) | |
1294 @result{} "http://www.cliki.net/CFFI" | |
1295 @end example | |
1296 | |
1297 @noindent | |
1298 Looks like that worked, and @code{libcurl} now knows what | |
1299 @acronym{URL} we want to retrieve. | |
1300 | |
1301 Finally, we turn back to the @code{:errorbuffer} option mentioned at | |
1302 the beginning of this section. Whereas the abstraction added to | |
1303 support string inputs works fine for cases like @code{CURLOPT_URL}, it | |
1304 hides the detail of keeping the C string; for @code{:errorbuffer}, | |
1305 however, we need that C string. | |
1306 | |
1307 In a moment, we'll define something slightly cleaner, but for now, | |
1308 remember that you can always hack around anything. We're modifying | |
1309 handle creation, so make sure you free the old handle before | |
1310 redefining @code{free-easy-handle}. | |
1311 | |
1312 @smalllisp | |
1313 (defvar *easy-handle-errorbuffers* (make-hash-table) | |
1314 "Hashtable of easy handles to C strings serving as error | |
1315 writeback buffers.") | |
1316 | |
1317 ;;; @lispcmt{An extra byte is very little to pay for peace of mind.} | |
1318 (defparameter *curl-error-size* 257 | |
1319 "Minimum char[] size used by cURL to report errors.") | |
1320 | |
1321 (defun make-easy-handle () | |
1322 "Answer a new CURL easy interface handle, to which the lifetime | |
1323 of C strings may be tied. See `add-curl-handle-cstring'." | |
1324 (let ((easy-handle (curl-easy-init))) | |
1325 (setf (gethash easy-handle *easy-handle-cstrings*) '()) | |
1326 (setf (gethash easy-handle *easy-handle-errorbuffers*) | |
1327 (foreign-alloc :char :count *curl-error-size* | |
1328 :initial-element 0)) | |
1329 easy-handle)) | |
1330 | |
1331 (defun free-easy-handle (handle) | |
1332 "Free CURL easy interface HANDLE and any C strings created to | |
1333 be its options." | |
1334 (curl-easy-cleanup handle) | |
1335 (foreign-free (gethash handle *easy-handle-errorbuffers*)) | |
1336 (remhash handle *easy-handle-errorbuffers*) | |
1337 (mapc #'foreign-string-free | |
1338 (gethash handle *easy-handle-cstrings*)) | |
1339 (remhash handle *easy-handle-cstrings*)) | |
1340 | |
1341 (defun get-easy-handle-error (handle) | |
1342 "Answer a string containing HANDLE's current error message." | |
1343 (foreign-string-to-lisp | |
1344 (gethash handle *easy-handle-errorbuffers*))) | |
1345 @end smalllisp | |
1346 | |
1347 Be sure to once again set the options we've set thus far. You may | |
1348 wish to define yet another wrapper function to do this. | |
1349 | |
1350 | |
1351 @node Tutorial-Callbacks, Tutorial-Completion, Tutorial-Memory, Tutorial | |
1352 @section Calling Lisp from C | |
1353 | |
1354 If you have been reading | |
1355 @uref{http://curl.haxx.se/libcurl/c/curl_easy_setopt.html,, | |
1356 @code{curl_easy_setopt(3)}}, you should have noticed that some options | |
1357 accept a function pointer. In particular, we need one function | |
1358 pointer to set as @code{CURLOPT_WRITEFUNCTION}, to be called by | |
1359 @code{libcurl} rather than the reverse, in order to receive data as it | |
1360 is downloaded. | |
1361 | |
1362 A binding writer without the aid of @acronym{FFI} usually approaches | |
1363 this problem by writing a C function that accepts C data, converts to | |
1364 the language's internal objects, and calls the callback provided by | |
1365 the user, again in a reverse of usual practices. | |
1366 | |
1367 The @cffi{} approach to callbacks precisely mirrors its differences | |
1368 with the non-@acronym{FFI} approach on the ``calling C from Lisp'' | |
1369 side, which we have dealt with exclusively up to now. That is, you | |
1370 define a callback function in Lisp using @code{defcallback}, and | |
1371 @cffi{} effectively creates a C function to be passed as a function | |
1372 pointer. | |
1373 | |
1374 @impnote{This is much trickier than calling C functions from Lisp, as | |
1375 it literally involves somehow generating a new C function that is as | |
1376 good as any created by the compiler. Therefore, not all Lisps support | |
1377 them. @xref{Implementation Support}, for information about @cffi{} | |
1378 support issues in this and other areas. You may want to consider | |
1379 changing to a Lisp that supports callbacks in order to continue with | |
1380 this tutorial.} | |
1381 | |
1382 @cindex callback definition | |
1383 @cindex defining callbacks | |
1384 Defining a callback is very similar to defining a callout; the main | |
1385 difference is that we must provide some Lisp forms to be evaluated as | |
1386 part of the callback. Here is the signature for the function the | |
1387 @code{:writefunction} option takes: | |
1388 | |
1389 @example | |
1390 size_t | |
1391 @var{function}(void *ptr, size_t size, size_t nmemb, void *stream); | |
1392 @end example | |
1393 | |
1394 @impnote{size_t is almost always an unsigned int. You can get this | |
1395 and many other types using feature tests for your system by using | |
1396 cffi-grovel.} | |
1397 | |
1398 The above signature trivially translates into a @cffi{} | |
1399 @code{defcallback} form, as follows. | |
1400 | |
1401 @lisp | |
1402 ;;; @lispcmt{Alias in case size_t changes.} | |
1403 (defctype size :unsigned-int) | |
1404 | |
1405 ;;; @lispcmt{To be set as the CURLOPT_WRITEFUNCTION of every easy handle… | |
1406 (defcallback easy-write size ((ptr :pointer) (size size) | |
1407 (nmemb size) (stream :pointer)) | |
1408 (let ((data-size (* size nmemb))) | |
1409 (handler-case | |
1410 ;; @lispcmt{We use the dynamically-bound *easy-write-procedure* to} | |
1411 ;; @lispcmt{call a closure with useful lexical context.} | |
1412 (progn (funcall (symbol-value '*easy-write-procedure*) | |
1413 (foreign-string-to-lisp ptr :count data-size)) | |
1414 data-size) ;@lispcmt{indicates success} | |
1415 ;; @lispcmt{The WRITEFUNCTION should return something other than t… | |
1416 ;; @lispcmt{#bytes available to signal an error.} | |
1417 (error () (if (zerop data-size) 1 0))))) | |
1418 @end lisp | |
1419 | |
1420 First, note the correlation of the first few forms, used to declare | |
1421 the C function's signature, with the signature in C syntax. We | |
1422 provide a Lisp name for the function, its return type, and a name and | |
1423 type for each argument. | |
1424 | |
1425 In the body, we call the dynamically-bound | |
1426 @code{*easy-write-procedure*} with a ``finished'' translation, of | |
1427 pulling together the raw data and size into a Lisp string, rather than | |
1428 deal with the data directly. As part of calling | |
1429 @code{curl_easy_perform} later, we'll bind that variable to a closure | |
1430 with more useful lexical bindings than the top-level | |
1431 @code{defcallback} form. | |
1432 | |
1433 Finally, we make a halfhearted effort to prevent non-local exits from | |
1434 unwinding the C stack, covering the most likely case with an | |
1435 @code{error} handler, which is usually triggered | |
1436 unexpectedly.@footnote{Unfortunately, we can't protect against | |
1437 @emph{all} non-local exits, such as @code{return}s and @code{throw}s, | |
1438 because @code{unwind-protect} cannot be used to ``short-circuit'' a | |
1439 non-local exit in Common Lisp, due to proposal @code{minimal} in | |
1440 @uref{http://www.lisp.org/HyperSpec/Issues/iss152-writeup.html, | |
1441 @acronym{ANSI} issue @sc{Exit-Extent}}. Furthermore, binding an | |
1442 @code{error} handler prevents higher-up code from invoking restarts | |
1443 that may be provided under the callback's dynamic context. Such is | |
1444 the way of compromise.} The reason is that most C code is written to | |
1445 understand its own idiosyncratic error condition, implemented above in | |
1446 the case of @code{curl_easy_perform}, and more ``undefined behavior'' | |
1447 can result if we just wipe C stack frames without allowing them to | |
1448 execute whatever cleanup actions as they like. | |
1449 | |
1450 Using the @code{CURLoption} enumeration in @file{curl.h} once more, we | |
1451 can describe the new option by modifying and reevaluating | |
1452 @code{define-curl-options}. | |
1453 | |
1454 @lisp | |
1455 (define-curl-options curl-option | |
1456 (long 0 objectpoint 10000 functionpoint 20000 off-t 30000) | |
1457 (:noprogress long 43) | |
1458 (:nosignal long 99) | |
1459 (:errorbuffer objectpoint 10) | |
1460 (:url objectpoint 2) | |
1461 (:writefunction functionpoint 11)) ;@lispcmt{new item here} | |
1462 @end lisp | |
1463 | |
1464 Finally, we can use the defined callback and the new | |
1465 @code{set-curl-option-writefunction} to finish configuring the easy | |
1466 handle, using the @code{callback} macro to retrieve a @cffi{} | |
1467 @code{:pointer}, which works like a function pointer in C code. | |
1468 | |
1469 @example | |
1470 @sc{cffi-user>} (set-curl-option-writefunction | |
1471 *easy-handle* (callback easy-write)) | |
1472 @result{} 0 | |
1473 @end example | |
1474 | |
1475 | |
1476 @node Tutorial-Completion, Tutorial-Types, Tutorial-Callbacks, Tutorial | |
1477 @section A complete @acronym{FFI}? | |
1478 | |
1479 @c TeX goes insane on @uref{@clikicffi{}} | |
1480 | |
1481 With all options finally set and a medium-level interface developed, | |
1482 we can finish the definition and retrieve | |
1483 @uref{http://www.cliki.net/CFFI}, as is done in the tutorial. | |
1484 | |
1485 @lisp | |
1486 (defcfun "curl_easy_perform" curl-code | |
1487 (handle easy-handle)) | |
1488 @end lisp | |
1489 | |
1490 @example | |
1491 @sc{cffi-user>} (with-output-to-string (contents) | |
1492 (let ((*easy-write-procedure* | |
1493 (lambda (string) | |
1494 (write-string string contents)))) | |
1495 (declare (special *easy-write-procedure*)) | |
1496 (curl-easy-perform *easy-handle*))) | |
1497 @result{} "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" | |
1498 @enddots{} | |
1499 Now fear, comprehensively</P> | |
1500 " | |
1501 @end example | |
1502 | |
1503 Of course, that itself is slightly unwieldy, so you may want to define | |
1504 a function around it that simply retrieves a @acronym{URL}. I will | |
1505 leave synthesis of all the relevant @acronym{REPL} forms presented | |
1506 thus far into a single function as an exercise for the reader. | |
1507 | |
1508 The remaining sections of this tutorial explore some advanced features | |
1509 of @cffi{}; the definition of new types will receive special | |
1510 attention. Some of these features are essential for particular | |
1511 foreign function calls; some are very helpful when trying to develop a | |
1512 Lispy interface to C. | |
1513 | |
1514 | |
1515 @node Tutorial-Types, Tutorial-Conclusion, Tutorial-Completion, Tutorial | |
1516 @section Defining new types | |
1517 | |
1518 We've occasionally used the @code{defctype} macro in previous sections | |
1519 as a kind of documentation, much what you'd use @code{typedef} for in | |
1520 C. We also tried one special kind of type definition, the | |
1521 @code{defcenum} type. @xref{defcstruct}, for a definition macro that | |
1522 may come in handy if you need to use C @code{struct}s as data. | |
1523 | |
1524 @cindex type definition | |
1525 @cindex data in Lisp and C | |
1526 @cindex translating types | |
1527 However, all of these are mostly sugar for the powerful underlying | |
1528 foreign type interface called @dfn{type translators}. You can easily | |
1529 define new translators for any simple named foreign type. Since we've | |
1530 defined the new type @code{curl-code} to use as the return type for | |
1531 various @code{libcurl} functions, we can use that to directly convert | |
1532 c@acronym{URL} errors to Lisp errors. | |
1533 | |
1534 @code{defctype}'s purpose is to define simple @code{typedef}-like | |
1535 aliases. In order to use @dfn{type translators} we must use the | |
1536 @code{define-foreign-type} macro. So let's redefine @code{curl-code} | |
1537 using it. | |
1538 | |
1539 @lisp | |
1540 (define-foreign-type curl-code-type () | |
1541 () | |
1542 (:actual-type :int) | |
1543 (:simple-parser curl-code)) | |
1544 @end lisp | |
1545 | |
1546 @code{define-foreign-type} is a thin wrapper around @code{defclass}. | |
1547 For now, all you need to know in the context of this example is that | |
1548 it does what @code{(defctype curl-code :int)} would do and, | |
1549 additionally, defines a new class @code{curl-code-type} which we will | |
1550 take advantage of shortly. | |
1551 | |
1552 The @code{CURLcode} enumeration seems to follow the typical error code | |
1553 convention of @samp{0} meaning all is well, and each non-zero integer | |
1554 indicating a different kind of error. We can apply that trivially to | |
1555 differentiate between normal exits and error exits. | |
1556 | |
1557 @lisp | |
1558 (define-condition curl-code-error (error) | |
1559 (($code :initarg :curl-code :reader curl-error-code)) | |
1560 (:report (lambda (c stream) | |
1561 (format stream "libcurl function returned error ~A" | |
1562 (curl-error-code c)))) | |
1563 (:documentation "Signalled when a libcurl function answers | |
1564 a code other than CURLE_OK.")) | |
1565 | |
1566 (defmethod translate-from-foreign (value (type curl-code-type)) | |
1567 "Raise a CURL-CODE-ERROR if VALUE, a curl-code, is non-zero." | |
1568 (if (zerop value) | |
1569 :curle-ok | |
1570 (error 'curl-code-error :curl-code value))) | |
1571 @end lisp | |
1572 | |
1573 @noindent | |
1574 The heart of this translator is new method | |
1575 @code{translate-from-foreign}. By specializing the @var{type} | |
1576 parameter on @code{curl-code-type}, we immediately modify the behavior | |
1577 of every function that returns a @code{curl-code} to pass the result | |
1578 through this new method. | |
1579 | |
1580 To see the translator in action, try invoking a function that returns | |
1581 a @code{curl-code}. You need to reevaluate the respective | |
1582 @code{defcfun} form so that it picks up the new @code{curl-code} | |
1583 definition. | |
1584 | |
1585 @example | |
1586 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1) | |
1587 @result{} :CURLE-OK | |
1588 @end example | |
1589 | |
1590 @noindent | |
1591 As the result was @samp{0}, the new method returned @code{:curle-ok}, | |
1592 just as specified.@footnote{It might be better to return | |
1593 @code{(values)} than @code{:curle-ok} in real code, but this is good | |
1594 for illustration.} I will leave disjoining the separate | |
1595 @code{CURLcode}s into condition types and improving the @code{:report} | |
1596 function as an exercise for you. | |
1597 | |
1598 The creation of @code{*easy-handle-cstrings*} and | |
1599 @code{*easy-handle-errorbuffers*} as properties of @code{easy-handle}s | |
1600 is a kluge. What we really want is a Lisp structure that stores these | |
1601 properties along with the C pointer. Unfortunately, | |
1602 @code{easy-handle} is currently just a fancy name for the foreign type | |
1603 @code{:pointer}; the actual pointer object varies from Common Lisp | |
1604 implementation to implementation, needing only to satisfy | |
1605 @code{pointerp} and be returned from @code{make-pointer} and friends. | |
1606 | |
1607 One solution that would allow us to define a new Lisp structure to | |
1608 represent @code{easy-handle}s would be to write a wrapper around every | |
1609 function that currently takes an @code{easy-handle}; the wrapper would | |
1610 extract the pointer and pass it to the foreign function. However, we | |
1611 can use type translators to more elegantly integrate this | |
1612 ``translation'' into the foreign function calling framework, using | |
1613 @code{translate-to-foreign}. | |
1614 | |
1615 @smalllisp | |
1616 (defclass easy-handle () | |
1617 ((pointer :initform (curl-easy-init) | |
1618 :documentation "Foreign pointer from curl_easy_init") | |
1619 (error-buffer | |
1620 :initform (foreign-alloc :char :count *curl-error-size* | |
1621 :initial-element 0) | |
1622 :documentation "C string describing last error") | |
1623 (c-strings :initform '() | |
1624 :documentation "C strings set as options")) | |
1625 (:documentation "I am a parameterization you may pass to | |
1626 curl-easy-perform to perform a cURL network protocol request.")) | |
1627 | |
1628 (defmethod initialize-instance :after ((self easy-handle) &key) | |
1629 (set-curl-option-errorbuffer self (slot-value self 'error-buffer))) | |
1630 | |
1631 (defun add-curl-handle-cstring (handle cstring) | |
1632 "Add CSTRING to be freed when HANDLE is, answering CSTRING." | |
1633 (car (push cstring (slot-value handle 'c-strings)))) | |
1634 | |
1635 (defun get-easy-handle-error (handle) | |
1636 "Answer a string containing HANDLE's current error message." | |
1637 (foreign-string-to-lisp | |
1638 (slot-value handle 'error-buffer))) | |
1639 | |
1640 (defun free-easy-handle (handle) | |
1641 "Free CURL easy interface HANDLE and any C strings created to | |
1642 be its options." | |
1643 (with-slots (pointer error-buffer c-strings) handle | |
1644 (curl-easy-cleanup pointer) | |
1645 (foreign-free error-buffer) | |
1646 (mapc #'foreign-string-free c-strings))) | |
1647 | |
1648 (define-foreign-type easy-handle-type () | |
1649 () | |
1650 (:actual-type :pointer) | |
1651 (:simple-parser easy-handle)) | |
1652 | |
1653 (defmethod translate-to-foreign (handle (type easy-handle-type)) | |
1654 "Extract the pointer from an easy-HANDLE." | |
1655 (slot-value handle 'pointer)) | |
1656 @end smalllisp | |
1657 | |
1658 While we changed some of the Lisp functions defined earlier to use | |
1659 @acronym{CLOS} slots rather than hash tables, the foreign functions | |
1660 work just as well as they did before. | |
1661 | |
1662 @cindex limitations of type translators | |
1663 The greatest strength, and the greatest limitation, of the type | |
1664 translator comes from its generalized interface. As stated | |
1665 previously, we could define all foreign function calls in terms of the | |
1666 primitive foreign types provided by @cffi{}. The type translator | |
1667 interface allows us to cleanly specify the relationship between Lisp | |
1668 and C data, independent of where it appears in a function call. This | |
1669 independence comes at a price; for example, it cannot be used to | |
1670 modify translation semantics based on other arguments to a function | |
1671 call. In these cases, you should rely on other features of Lisp, | |
1672 rather than the powerful, yet domain-specific, type translator | |
1673 interface. | |
1674 | |
1675 | |
1676 @node Tutorial-Conclusion, , Tutorial-Types, Tutorial | |
1677 @section What's next? | |
1678 | |
1679 @cffi{} provides a rich and powerful foundation for communicating with | |
1680 foreign libraries; as we have seen, it is up to you to make that | |
1681 experience a pleasantly Lispy one. This tutorial does not cover all | |
1682 the features of @cffi{}; please see the rest of the manual for | |
1683 details. In particular, if something seems obviously missing, it is | |
1684 likely that either code or a good reason for lack of code is already | |
1685 present. | |
1686 | |
1687 @impnote{There are some other things in @cffi{} that might deserve | |
1688 tutorial sections, such as free-translated-object, or structs. Let us | |
1689 know which ones you care about.} | |
1690 | |
1691 | |
1692 @c =================================================================== | |
1693 @c CHAPTER: Wrapper generators | |
1694 | |
1695 @node Wrapper generators, Foreign Types, Tutorial, Top | |
1696 @chapter Wrapper generators | |
1697 | |
1698 @cffi{}'s interface is designed for human programmers, being aimed at | |
1699 aesthetic as well as technical sophistication. However, there are a | |
1700 few programs aimed at translating C and C++ header files, or | |
1701 approximations thereof, into @cffi{} forms constituting a foreign | |
1702 interface to the symbols in those files. | |
1703 | |
1704 These wrapper generators are known to support output of @cffi{} forms. | |
1705 | |
1706 @table @asis | |
1707 @item @uref{http://www.cliki.net/Verrazano,Verrazano} | |
1708 Designed specifically for Common Lisp. Uses @acronym{GCC}'s parser | |
1709 output in @acronym{XML} format to discover functions, variables, and | |
1710 other header file data. This means you need @acronym{GCC} to generate | |
1711 forms; on the other hand, the parser employed is mostly compliant with | |
1712 @acronym{ANSI} C. | |
1713 | |
1714 @item @uref{http://www.cliki.net/SWIG,SWIG} | |
1715 A foreign interface generator originally designed to generate Python | |
1716 bindings, it has been ported to many other systems, including @cffi{} | |
1717 in version 1.3.28. Includes its own C declaration munger, not | |
1718 intended to be fully-compliant with @acronym{ANSI} C. | |
1719 @end table | |
1720 | |
1721 First, this manual does not describe use of these other programs; they | |
1722 have documentation of their own. If you have problems using a | |
1723 generated interface, please look at the output @cffi{} forms and | |
1724 verify that they are a correct @cffi{} interface to the library in | |
1725 question; if they are correct, contact @cffi{} developers with | |
1726 details, keeping in mind that they communicate in terms of those forms | |
1727 rather than any particular wrapper generator. Otherwise, contact the | |
1728 maintainers of the wrapper generator you are using, provided you can | |
1729 reasonably expect more accuracy from the generator. | |
1730 | |
1731 When is more accuracy an unreasonable expectation? As described in | |
1732 the tutorial (@pxref{Tutorial-Abstraction,, Breaking the | |
1733 abstraction}), the information in C declarations is insufficient to | |
1734 completely describe every interface. In fact, it is quite common to | |
1735 run into an interface that cannot be handled automatically, and | |
1736 generators should be excused from generating a complete interface in | |
1737 these cases. | |
1738 | |
1739 As further described in the tutorial, the thinnest Lisp interface to a | |
1740 C function is not always the most pleasant one. In many cases, you | |
1741 will want to manually write a Lispier interface to the C functions | |
1742 that interest you. | |
1743 | |
1744 Wrapper generators should be treated as time-savers, not complete | |
1745 automation of the full foreign interface writing job. Reports of the | |
1746 amount of work done by generators vary from 30% to 90%. The | |
1747 incremental development style enabled by @cffi{} generally reduces | |
1748 this proportion below that for languages like Python. | |
1749 | |
1750 @c Where I got the above 30-90% figures: | |
1751 @c 30%: lemonodor's post about SWIG | |
1752 @c 90%: Balooga on #lisp. He said 99%, but that's probably an | |
1753 @c exaggeration (leave it to me to pass judgement :) | |
1754 @c -stephen | |
1755 | |
1756 | |
1757 @c =================================================================== | |
1758 @c CHAPTER: Foreign Types | |
1759 | |
1760 @node Foreign Types, Pointers, Wrapper generators, Top | |
1761 @chapter Foreign Types | |
1762 | |
1763 Foreign types describe how data is translated back and forth between C | |
1764 and Lisp. @cffi{} provides various built-in types and allows the user to | |
1765 define new types. | |
1766 | |
1767 @menu | |
1768 * Built-In Types:: | |
1769 * Other Types:: | |
1770 * Defining Foreign Types:: | |
1771 * Foreign Type Translators:: | |
1772 * Optimizing Type Translators:: | |
1773 * Foreign Structure Types:: | |
1774 * Allocating Foreign Objects:: | |
1775 | |
1776 Dictionary | |
1777 | |
1778 * convert-from-foreign:: | |
1779 * convert-to-foreign:: | |
1780 * defbitfield:: | |
1781 * defcstruct:: | |
1782 * defcunion:: | |
1783 * defctype:: | |
1784 * defcenum:: | |
1785 @c * define-type-spec-parser:: | |
1786 * define-foreign-type:: | |
1787 * define-parse-method:: | |
1788 @c * explain-foreign-slot-value: | |
1789 * foreign-bitfield-symbols:: | |
1790 * foreign-bitfield-value:: | |
1791 * foreign-enum-keyword:: | |
1792 * foreign-enum-value:: | |
1793 * foreign-slot-names:: | |
1794 * foreign-slot-offset:: | |
1795 * foreign-slot-pointer:: | |
1796 * foreign-slot-value:: | |
1797 * foreign-type-alignment:: | |
1798 * foreign-type-size:: | |
1799 * free-converted-object:: | |
1800 * free-translated-object:: | |
1801 * translate-from-foreign:: | |
1802 * translate-to-foreign:: | |
1803 * translate-into-foreign-memory:: | |
1804 * with-foreign-slots:: | |
1805 @end menu | |
1806 | |
1807 @node Built-In Types, Other Types, Foreign Types, Foreign Types | |
1808 @section Built-In Types | |
1809 | |
1810 @ForeignType{:char} | |
1811 @ForeignType{:unsigned-char} | |
1812 @ForeignType{:short} | |
1813 @ForeignType{:unsigned-short} | |
1814 @ForeignType{:int} | |
1815 @ForeignType{:unsigned-int} | |
1816 @ForeignType{:long} | |
1817 @ForeignType{:unsigned-long} | |
1818 @ForeignType{:long-long} | |
1819 @ForeignType{:unsigned-long-long} | |
1820 | |
1821 These types correspond to the native C integer types according to the | |
1822 @acronym{ABI} of the Lisp implementation's host system. | |
1823 | |
1824 @code{:long-long} and @code{:unsigned-long-long} are not supported | |
1825 natively on all implementations. However, they are emulated by | |
1826 @code{mem-ref} and @code{mem-set}. | |
1827 | |
1828 When those types are @strong{not} available, the symbol | |
1829 @code{cffi-sys::no-long-long} is pushed into @code{*features*}. | |
1830 | |
1831 @ForeignType{:uchar} | |
1832 @ForeignType{:ushort} | |
1833 @ForeignType{:uint} | |
1834 @ForeignType{:ulong} | |
1835 @ForeignType{:llong} | |
1836 @ForeignType{:ullong} | |
1837 | |
1838 For convenience, the above types are provided as shortcuts for | |
1839 @code{unsigned-char}, @code{unsigned-short}, @code{unsigned-int}, | |
1840 @code{unsigned-long}, @code{long-long} and @code{unsigned-long-long}, | |
1841 respectively. | |
1842 | |
1843 @ForeignType{:int8} | |
1844 @ForeignType{:uint8} | |
1845 @ForeignType{:int16} | |
1846 @ForeignType{:uint16} | |
1847 @ForeignType{:int32} | |
1848 @ForeignType{:uint32} | |
1849 @ForeignType{:int64} | |
1850 @ForeignType{:uint64} | |
1851 | |
1852 Foreign integer types of specific sizes, corresponding to the C types | |
1853 defined in @code{stdint.h}. | |
1854 | |
1855 @c @ForeignType{:size} | |
1856 @c @ForeignType{:ssize} | |
1857 @c @ForeignType{:ptrdiff} | |
1858 @c @ForeignType{:time} | |
1859 | |
1860 @c Foreign integer types corresponding to the standard C types (without | |
1861 @c the @code{_t} suffix). | |
1862 | |
1863 @c @impnote{These are not implemented yet. --luis} | |
1864 | |
1865 @c @impnote{I'm sure there are more of these that could be useful, let's | |
1866 @c add any types that can't be defined portably to this list as | |
1867 @c necessary. --james} | |
1868 | |
1869 @ForeignType{:float} | |
1870 @ForeignType{:double} | |
1871 | |
1872 On all systems, the @code{:float} and @code{:double} types represent a | |
1873 C @code{float} and @code{double}, respectively. On most but not all | |
1874 systems, @code{:float} and @code{:double} represent a Lisp | |
1875 @code{single-float} and @code{double-float}, respectively. It is not | |
1876 so useful to consider the relationship between Lisp types and C types | |
1877 as isomorphic, as simply to recognize the relationship, and relative | |
1878 precision, among each respective category. | |
1879 | |
1880 @ForeignType{:long-double} | |
1881 | |
1882 This type is only supported on SCL. | |
1883 | |
1884 @ForeignType{:pointer &optional type} | |
1885 | |
1886 A foreign pointer to an object of any type, corresponding to | |
1887 @code{void *}. You can optionally specify type of pointer | |
1888 (e.g. @code{(:pointer :char)}). Although @cffi{} won't do anything | |
1889 with that information yet, it is useful for documentation purposes. | |
1890 | |
1891 @ForeignType{:void} | |
1892 | |
1893 No type at all. Only valid as the return type of a function. | |
1894 | |
1895 @node Other Types, Defining Foreign Types, Built-In Types, Foreign Types | |
1896 @section Other Types | |
1897 | |
1898 @cffi{} also provides a few useful types that aren't built-in C | |
1899 types. | |
1900 | |
1901 @ForeignType{:string} | |
1902 | |
1903 The @code{:string} type performs automatic conversion between Lisp and | |
1904 C strings. Note that, in the case of functions the converted C string | |
1905 will have dynamic extent (i.e.@: it will be automatically freed after | |
1906 the foreign function returns). | |
1907 | |
1908 In addition to Lisp strings, this type will accept foreign pointers | |
1909 and pass them unmodified. | |
1910 | |
1911 A method for @ref{free-translated-object} is specialized for this | |
1912 type. So, for example, foreign strings allocated by this type and | |
1913 passed to a foreign function will be freed after the function | |
1914 returns. | |
1915 | |
1916 @lisp | |
1917 CFFI> (foreign-funcall "getenv" :string "SHELL" :string) | |
1918 @result{} "/bin/bash" | |
1919 | |
1920 CFFI> (with-foreign-string (str "abcdef") | |
1921 (foreign-funcall "strlen" :string str :int)) | |
1922 @result{} 6 | |
1923 @end lisp | |
1924 | |
1925 @ForeignType{:string+ptr} | |
1926 | |
1927 Like @code{:string} but returns a list with two values when convert | |
1928 from C to Lisp: a Lisp string and the C string's foreign pointer. | |
1929 | |
1930 @lisp | |
1931 CFFI> (foreign-funcall "getenv" :string "SHELL" :string+ptr) | |
1932 @result{} ("/bin/bash" #.(SB-SYS:INT-SAP #XBFFFFC6F)) | |
1933 @end lisp | |
1934 | |
1935 @ForeignType{:boolean &optional (base-type :int)} | |
1936 | |
1937 The @code{:boolean} type converts between a Lisp boolean and a C | |
1938 boolean. It canonicalizes to @var{base-type} which is @code{:int} by | |
1939 default. | |
1940 | |
1941 @lisp | |
1942 (convert-to-foreign nil :boolean) @result{} 0 | |
1943 (convert-to-foreign t :boolean) @result{} 1 | |
1944 (convert-from-foreign 0 :boolean) @result{} nil | |
1945 (convert-from-foreign 1 :boolean) @result{} t | |
1946 @end lisp | |
1947 | |
1948 @ForeignType{:bool} | |
1949 | |
1950 The @code{:bool} type represents the C99 @code{_Bool} or C++ | |
1951 @code{bool}. Its size is usually 1 byte except on OSX where it's an | |
1952 @code{int}. | |
1953 | |
1954 @ForeignType{:wrapper base-type &key to-c from-c} | |
1955 | |
1956 The @code{:wrapper} type stores two symbols passed to the @var{to-c} | |
1957 and @var{from-c} arguments. When a value is being translated to or | |
1958 from C, this type @code{funcall}s the respective symbol. | |
1959 | |
1960 @code{:wrapper} types will be typedefs for @var{base-type} and will | |
1961 inherit its translators, if any. | |
1962 | |
1963 Here's an example of how the @code{:boolean} type could be defined in | |
1964 terms of @code{:wrapper}. | |
1965 | |
1966 @lisp | |
1967 (defun bool-c-to-lisp (value) | |
1968 (not (zerop value))) | |
1969 | |
1970 (defun bool-lisp-to-c (value) | |
1971 (if value 1 0)) | |
1972 | |
1973 (defctype my-bool (:wrapper :int :from-c bool-c-to-lisp | |
1974 :to-c bool-lisp-to-c)) | |
1975 | |
1976 (convert-to-foreign nil 'my-bool) @result{} 0 | |
1977 (convert-from-foreign 1 'my-bool) @result{} t | |
1978 @end lisp | |
1979 | |
1980 @node Defining Foreign Types, Foreign Type Translators, Other Types, For… | |
1981 @section Defining Foreign Types | |
1982 | |
1983 You can define simple C-like @code{typedef}s through the | |
1984 @code{defctype} macro. Defining a typedef is as simple as giving | |
1985 @code{defctype} a new name and the name of the type to be wrapped. | |
1986 | |
1987 @lisp | |
1988 ;;; @lispcmt{Define MY-INT as an alias for the built-in type :INT.} | |
1989 (defctype my-int :int) | |
1990 @end lisp | |
1991 | |
1992 With this type definition, one can, for instance, declare arguments to | |
1993 foreign functions as having the type @code{my-int}, and they will be | |
1994 passed as integers. | |
1995 | |
1996 @subheading More complex types | |
1997 | |
1998 @cffi{} offers another way to define types through | |
1999 @code{define-foreign-type}, a thin wrapper macro around | |
2000 @code{defclass}. As an example, let's go through the steps needed to | |
2001 define a @code{(my-string &key encoding)} type. First, we need to | |
2002 define our type class: | |
2003 | |
2004 @lisp | |
2005 (define-foreign-type my-string-type () | |
2006 ((encoding :reader string-type-encoding :initarg :encoding)) | |
2007 (:actual-type :pointer)) | |
2008 @end lisp | |
2009 | |
2010 The @code{:actual-type} class option tells CFFI that this type will | |
2011 ultimately be passed to and received from foreign code as a | |
2012 @code{:pointer}. Now you need to tell CFFI how to parse a type | |
2013 specification such as @code{(my-string :encoding :utf8)} into an | |
2014 instance of @code{my-string-type}. We do that with | |
2015 @code{define-parse-method}: | |
2016 | |
2017 @lisp | |
2018 (define-parse-method my-string (&key (encoding :utf-8)) | |
2019 (make-instance 'my-string-type :encoding encoding)) | |
2020 @end lisp | |
2021 | |
2022 The next section describes how make this type actually translate | |
2023 between C and Lisp strings. | |
2024 | |
2025 @node Foreign Type Translators, Optimizing Type Translators, Defining Fo… | |
2026 @section Foreign Type Translators | |
2027 | |
2028 Type translators are used to automatically convert Lisp values to or | |
2029 from foreign values. For example, using type translators, one can | |
2030 take the @code{my-string} type defined in the previous section and | |
2031 specify that it should: | |
2032 | |
2033 @itemize | |
2034 @item | |
2035 convert C strings to Lisp strings; | |
2036 @item | |
2037 convert Lisp strings to newly allocated C strings; | |
2038 @item | |
2039 free said C strings when they are no longer needed. | |
2040 @end itemize | |
2041 | |
2042 In order to tell @cffi{} how to automatically convert Lisp values to | |
2043 foreign values, define a specialized method for the | |
2044 @code{translate-to-foreign} generic function: | |
2045 | |
2046 @lisp | |
2047 ;;; @lispcmt{Define a method that converts Lisp strings to C strings.} | |
2048 (defmethod translate-to-foreign (string (type my-string-type)) | |
2049 (foreign-string-alloc string :encoding (string-type-encoding type))) | |
2050 @end lisp | |
2051 | |
2052 @noindent | |
2053 From now on, whenever an object is passed as a @code{my-string} to a | |
2054 foreign function, this method will be invoked to convert the Lisp | |
2055 value. To perform the inverse operation, which is needed for functions | |
2056 that return a @code{my-string}, specialize the | |
2057 @code{translate-from-foreign} generic function in the same manner: | |
2058 | |
2059 @lisp | |
2060 ;;; @lispcmt{Define a method that converts C strings to Lisp strings.} | |
2061 (defmethod translate-from-foreign (pointer (type my-string-type)) | |
2062 (foreign-string-to-lisp pointer :encoding (string-type-encoding type))) | |
2063 @end lisp | |
2064 | |
2065 @noindent | |
2066 When a @code{translate-to-foreign} method requires allocation of | |
2067 foreign memory, you must also define a @code{free-translated-object} | |
2068 method to free the memory once the foreign object is no longer needed, | |
2069 otherwise you'll be faced with memory leaks. This generic function is | |
2070 called automatically by @cffi{} when passing objects to foreign | |
2071 functions. Let's do that: | |
2072 | |
2073 @lisp | |
2074 ;;; @lispcmt{Free strings allocated by translate-to-foreign.} | |
2075 (defmethod free-translated-object (pointer (type my-string-type) param) | |
2076 (declare (ignore param)) | |
2077 (foreign-string-free pointer)) | |
2078 @end lisp | |
2079 | |
2080 @noindent | |
2081 In this specific example, we don't need the @var{param} argument, so | |
2082 we ignore it. See @ref{free-translated-object}, for an explanation of | |
2083 its purpose and how you can use it. | |
2084 | |
2085 A type translator does not necessarily need to convert the value. For | |
2086 example, one could define a typedef for @code{:pointer} that ensures, | |
2087 in the @code{translate-to-foreign} method, that the value is not a | |
2088 null pointer, signalling an error if a null pointer is passed. This | |
2089 would prevent some pointer errors when calling foreign functions that | |
2090 cannot handle null pointers. | |
2091 | |
2092 @strong{Please note:} these methods are meant as extensible hooks | |
2093 only, and you should not call them directly. Use | |
2094 @code{convert-to-foreign}, @code{convert-from-foreign} and | |
2095 @code{free-converted-object} instead. | |
2096 | |
2097 @xref{Tutorial-Types,, Defining new types}, for another example of | |
2098 type translators. | |
2099 | |
2100 @node Optimizing Type Translators, Foreign Structure Types, Foreign Type… | |
2101 @section Optimizing Type Translators | |
2102 | |
2103 @cindex type translators, optimizing | |
2104 @cindex compiler macros for type translation | |
2105 @cindex defining type-translation compiler macros | |
2106 Being based on generic functions, the type translation mechanism | |
2107 described above can add a bit of overhead. This is usually not | |
2108 significant, but we nevertheless provide a way of getting rid of the | |
2109 overhead for the cases where it matters. | |
2110 | |
2111 A good way to understand this issue is to look at the code generated | |
2112 by @code{defcfun}. Consider the following example using the previously | |
2113 defined @code{my-string} type: | |
2114 | |
2115 @lisp | |
2116 CFFI> (macroexpand-1 '(defcfun foo my-string (x my-string))) | |
2117 ;; @lispcmt{(simplified, downcased, etc...)} | |
2118 (defun foo (x) | |
2119 (multiple-value-bind (#:G2019 #:PARAM3149) | |
2120 (translate-to-foreign x #<MY-STRING-TYPE @{11ED5A79@}>) | |
2121 (unwind-protect | |
2122 (translate-from-foreign | |
2123 (foreign-funcall "foo" :pointer #:G2019 :pointer) | |
2124 #<MY-STRING-TYPE @{11ED5659@}>) | |
2125 (free-translated-object #:G2019 #<MY-STRING-TYPE @{11ED51A79@}> | |
2126 #:PARAM3149)))) | |
2127 @end lisp | |
2128 | |
2129 @noindent | |
2130 In order to get rid of those generic function calls, @cffi{} has | |
2131 another set of extensible generic functions that provide functionality | |
2132 similar to @acronym{CL}'s compiler macros: | |
2133 @code{expand-to-foreign-dyn}, @code{expand-to-foreign} and | |
2134 @code{expand-from-foreign}. Here's how one could define a | |
2135 @code{my-boolean} with them: | |
2136 | |
2137 @lisp | |
2138 (define-foreign-type my-boolean-type () | |
2139 () | |
2140 (:actual-type :int) | |
2141 (:simple-parser my-boolean)) | |
2142 | |
2143 (defmethod expand-to-foreign (value (type my-boolean-type)) | |
2144 `(if ,value 1 0)) | |
2145 | |
2146 (defmethod expand-from-foreign (value (type my-boolean-type)) | |
2147 `(not (zerop ,value))) | |
2148 @end lisp | |
2149 | |
2150 @noindent | |
2151 And here's what the macroexpansion of a function using this type would | |
2152 look like: | |
2153 | |
2154 @lisp | |
2155 CFFI> (macroexpand-1 '(defcfun bar my-boolean (x my-boolean))) | |
2156 ;; @lispcmt{(simplified, downcased, etc...)} | |
2157 (defun bar (x) | |
2158 (let ((#:g3182 (if x 1 0))) | |
2159 (not (zerop (foreign-funcall "bar" :int #:g3182 :int))))) | |
2160 @end lisp | |
2161 | |
2162 @noindent | |
2163 No generic function overhead. | |
2164 | |
2165 Let's go back to our @code{my-string} type. The expansion interface | |
2166 has no equivalent of @code{free-translated-object}; you must instead | |
2167 define a method on @code{expand-to-foreign-dyn}, the third generic | |
2168 function in this interface. This is especially useful when you can | |
2169 allocate something much more efficiently if you know the object has | |
2170 dynamic extent, as is the case with function calls that don't save the | |
2171 relevant allocated arguments. | |
2172 | |
2173 This exactly what we need for the @code{my-string} type: | |
2174 | |
2175 @lisp | |
2176 (defmethod expand-from-foreign (form (type my-string-type)) | |
2177 `(foreign-string-to-lisp ,form)) | |
2178 | |
2179 (defmethod expand-to-foreign-dyn (value var body (type my-string-type)) | |
2180 (let ((encoding (string-type-encoding type))) | |
2181 `(with-foreign-string (,var ,value :encoding ',encoding) | |
2182 ,@@body))) | |
2183 @end lisp | |
2184 | |
2185 @noindent | |
2186 So let's look at the macro expansion: | |
2187 | |
2188 @lisp | |
2189 CFFI> (macroexpand-1 '(defcfun foo my-string (x my-string))) | |
2190 ;; @lispcmt{(simplified, downcased, etc...)} | |
2191 (defun foo (x) | |
2192 (with-foreign-string (#:G2021 X :encoding ':utf-8) | |
2193 (foreign-string-to-lisp | |
2194 (foreign-funcall "foo" :pointer #:g2021 :pointer)))) | |
2195 @end lisp | |
2196 | |
2197 @noindent | |
2198 Again, no generic function overhead. | |
2199 | |
2200 @subheading Other details | |
2201 | |
2202 To short-circuit expansion and use the @code{translate-*} functions | |
2203 instead, simply call the next method. Return its result in cases | |
2204 where your method cannot generate an appropriate replacement for it. | |
2205 This analogous to the @code{&whole form} mechanism compiler macros | |
2206 provide. | |
2207 | |
2208 The @code{expand-*} methods have precedence over their | |
2209 @code{translate-*} counterparts and are guaranteed to be used in | |
2210 @code{defcfun}, @code{foreign-funcall}, @code{defcvar} and | |
2211 @code{defcallback}. If you define a method on each of the | |
2212 @code{expand-*} generic functions, you are guaranteed to have full | |
2213 control over the expressions generated for type translation in these | |
2214 macros. | |
2215 | |
2216 They may or may not be used in other @cffi{} operators that need to | |
2217 translate between Lisp and C data; you may only assume that | |
2218 @code{expand-*} methods will probably only be called during Lisp | |
2219 compilation. | |
2220 | |
2221 @code{expand-to-foreign-dyn} has precedence over | |
2222 @code{expand-to-foreign} and is only used in @code{defcfun} and | |
2223 @code{foreign-funcall}, only making sense in those contexts. | |
2224 | |
2225 @strong{Important note:} this set of generic functions is called at | |
2226 macroexpansion time. Methods are defined when loaded or evaluated, | |
2227 not compiled. You are responsible for ensuring that your | |
2228 @code{expand-*} methods are defined when the @code{foreign-funcall} or | |
2229 other forms that use them are compiled. One way to do this is to put | |
2230 the method definitions earlier in the file and inside an appropriate | |
2231 @code{eval-when} form; another way is to always load a separate Lisp | |
2232 or @acronym{FASL} file containing your @code{expand-*} definitions | |
2233 before compiling files with forms that ought to use them. Otherwise, | |
2234 they will not be found and the runtime translators will be used | |
2235 instead. | |
2236 | |
2237 @node Foreign Structure Types, Allocating Foreign Objects, Optimizing Ty… | |
2238 @section Foreign Structure Types | |
2239 | |
2240 For more involved C types than simple aliases to built-in types, such | |
2241 as you can make with @code{defctype}, @cffi{} allows declaration of | |
2242 structures and unions with @code{defcstruct} and @code{defcunion}. | |
2243 | |
2244 For example, consider this fictional C structure declaration holding | |
2245 some personal information: | |
2246 | |
2247 @example | |
2248 struct person @{ | |
2249 int number; | |
2250 char* reason; | |
2251 @}; | |
2252 @end example | |
2253 | |
2254 @noindent | |
2255 The equivalent @code{defcstruct} form follows: | |
2256 | |
2257 @lisp | |
2258 (defcstruct person | |
2259 (number :int) | |
2260 (reason :string)) | |
2261 @end lisp | |
2262 | |
2263 @c LMH structure translation | |
2264 By default, @ref{convert-from-foreign} (and also @ref{mem-ref}) will | |
2265 make a plist with slot names as keys, and @ref{convert-to-foreign} will | |
2266 translate such a plist to a foreign structure. A user wishing to define | |
2267 other translations should use the @code{:class} argument to | |
2268 @ref{defcstruct}, and then define methods for | |
2269 @ref{translate-from-foreign} and | |
2270 @ref{translate-into-foreign-memory} that specialize on this class, | |
2271 possibly calling @code{call-next-method} to translate from and to the | |
2272 plists rather than provide a direct interface to the foreign object. | |
2273 The macro @code{translation-forms-for-class} will generate the forms | |
2274 necessary to translate a Lisp class into a foreign structure and vice | |
2275 versa. | |
2276 @c Write separate function doc section for translation-forms-for-class? | |
2277 @c Examples, perhaps taken from the tests? | |
2278 | |
2279 Please note that this interface is only for those that must know about | |
2280 the values contained in a relevant struct. If the library you are | |
2281 interfacing returns an opaque pointer that needs only be passed to | |
2282 other C library functions, by all means just use @code{:pointer} or a | |
2283 type-safe definition munged together with @code{defctype} and type | |
2284 translation. To pass or return a structure by value to a function, load | |
2285 the cffi-libffi system and specify the structure as @code{(:struct | |
2286 @var{structure-name})}. To pass or return the pointer, you can use | |
2287 either @code{:pointer} or @code{(:pointer (:struct | |
2288 @var{structure-name}))}. | |
2289 | |
2290 @subheading Optimizing translate-into-foreign-memory | |
2291 | |
2292 Just like how @ref{translate-from-foreign} had | |
2293 @code{expand-from-foreign} to optimize away the generic function call | |
2294 and @ref{translate-to-foreign} had the same in | |
2295 @code{expand-to-foreign}, @ref{translate-into-foreign-memory} has | |
2296 @code{expand-into-foreign-memory}. | |
2297 | |
2298 Let's use our @code{person} struct in an example. However, we are | |
2299 going to spice it up by using a lisp struct rather than a plist to | |
2300 represent the person in lisp. | |
2301 | |
2302 First we redefine @code{person} very slightly. | |
2303 | |
2304 @lisp | |
2305 (defcstruct (person :class c-person) | |
2306 (number :int) | |
2307 (reason :string)) | |
2308 @end lisp | |
2309 | |
2310 By adding @code{:class} we can specialize the @code{translate-*} | |
2311 methods on the type @code{c-person}. | |
2312 | |
2313 Next we define a lisp struct to use instead of the plists. | |
2314 | |
2315 @lisp | |
2316 (defstruct lisp-person | |
2317 (number 0 :type integer) | |
2318 (reason "" :type string)) | |
2319 @end lisp | |
2320 | |
2321 And now let's define the type translators we know already: | |
2322 | |
2323 @lisp | |
2324 (defmethod translate-from-foreign (ptr (type c-person)) | |
2325 (with-foreign-slots ((number reason) ptr (:struct person)) | |
2326 (make-lisp-person :number number :reason reason))) | |
2327 | |
2328 (defmethod expand-from-foreign (ptr (type c-person)) | |
2329 `(with-foreign-slots ((number reason) ,ptr (:struct person)) | |
2330 (make-lisp-person :number number :reason reason))) | |
2331 | |
2332 (defmethod translate-into-foreign-memory (value (type c-person) ptr) | |
2333 (with-foreign-slots ((number reason) ptr (:struct person)) | |
2334 (setf number (lisp-person-number value) | |
2335 reason (lisp-person-reason value)))) | |
2336 @end lisp | |
2337 | |
2338 At this point everything works, we can convert to and from our | |
2339 @code{lisp-person} and foreign @code{person}. If we macroexpand | |
2340 | |
2341 @lisp | |
2342 (setf (mem-aref ptr '(:struct person)) x) | |
2343 @end lisp | |
2344 | |
2345 we get something like: | |
2346 | |
2347 @lisp | |
2348 (let ((#:store879 x)) | |
2349 (translate-into-foreign-memory #:store879 #<c-person person> | |
2350 (inc-pointer ptr 0)) | |
2351 #:store879) | |
2352 @end lisp | |
2353 | |
2354 Which is good, but now we can do better and get rid of that generic | |
2355 function call to @code{translate-into-foreign-memory}. | |
2356 | |
2357 @lisp | |
2358 (defmethod expand-into-foreign-memory (value (type c-person) ptr) | |
2359 `(with-foreign-slots ((number reason) ,ptr (:struct person)) | |
2360 (setf number (lisp-person-number ,value) | |
2361 reason (lisp-person-reason ,value)))) | |
2362 @end lisp | |
2363 | |
2364 Now we can expand again so see the changes: | |
2365 | |
2366 @lisp | |
2367 ;; this: | |
2368 (setf (mem-aref ptr '(:struct person)) x) | |
2369 | |
2370 ;; expands to this | |
2371 ;; (simplified, downcased, etc..) | |
2372 (let ((#:store887 x)) | |
2373 (with-foreign-slots ((number reason) (inc-pointer ptr 0) (:struct pers… | |
2374 (setf number (lisp-person-number #:store887) | |
2375 reason (lisp-person-reason #:store887))) #:store887) | |
2376 @end lisp | |
2377 | |
2378 And there we are, no generic function overhead. | |
2379 | |
2380 @subheading Compatibility note | |
2381 | |
2382 Previous versions of CFFI accepted the | |
2383 ``bare'' @var{structure-name} as a type specification, which was | |
2384 interpreted as a pointer to the structure. This is deprecated and | |
2385 produces a style warning. Using this deprecated form means that | |
2386 @ref{mem-aref} retains its prior meaning and returns a pointer. Using | |
2387 the @code{(:struct @var{structure-name})} form for the type, | |
2388 @ref{mem-aref} provides a Lisp object translated from the | |
2389 structure (by default a plist). Thus the semantics are consistent with … | |
2390 types in returning the object as represented in Lisp, and not a pointer, | |
2391 with the exception of the ``bare'' structure compatibility retained. | |
2392 In order to obtain the pointer, you should use the function @ref{mem-apt… | |
2393 | |
2394 See @ref{defcstruct} for more details. | |
2395 | |
2396 @node Allocating Foreign Objects, convert-from-foreign, Foreign Structur… | |
2397 @section Allocating Foreign Objects | |
2398 | |
2399 @c I moved this because I moved with-foreign-object to the Pointers | |
2400 @c chapter, where foreign-alloc is. | |
2401 | |
2402 @xref{Allocating Foreign Memory}. | |
2403 | |
2404 | |
2405 @c =================================================================== | |
2406 @c CONVERT-FROM-FOREIGN | |
2407 | |
2408 @page | |
2409 @node convert-from-foreign, convert-to-foreign, Allocating Foreign Objec… | |
2410 @heading convert-from-foreign | |
2411 @subheading Syntax | |
2412 @Function{convert-from-foreign foreign-value type @res{} value} | |
2413 | |
2414 @subheading Arguments and Values | |
2415 | |
2416 @table @var | |
2417 @item foreign-value | |
2418 The primitive C value as returned from a primitive foreign function or | |
2419 from @code{convert-to-foreign}. | |
2420 | |
2421 @item type | |
2422 A @cffi{} type specifier. | |
2423 | |
2424 @item value | |
2425 The Lisp value translated from @var{foreign-value}. | |
2426 @end table | |
2427 | |
2428 @subheading Description | |
2429 | |
2430 This is an external interface to the type translation facility. In | |
2431 the implementation, all foreign functions are ultimately defined as | |
2432 type translation wrappers around primitive foreign function | |
2433 invocations. | |
2434 | |
2435 This function is available mostly for inspection of the type | |
2436 translation process, and possibly optimization of special cases of | |
2437 your foreign function calls. | |
2438 | |
2439 Its behavior is better described under @code{translate-from-foreign}'s | |
2440 documentation. | |
2441 | |
2442 @subheading Examples | |
2443 | |
2444 @lisp | |
2445 CFFI-USER> (convert-to-foreign "a boat" :string) | |
2446 @result{} #<FOREIGN-ADDRESS #x097ACDC0> | |
2447 @result{} T | |
2448 CFFI-USER> (convert-from-foreign * :string) | |
2449 @result{} "a boat" | |
2450 @end lisp | |
2451 | |
2452 @subheading See Also | |
2453 @seealso{convert-to-foreign} @* | |
2454 @seealso{free-converted-object} @* | |
2455 @seealso{translate-from-foreign} | |
2456 | |
2457 | |
2458 @c =================================================================== | |
2459 @c CONVERT-TO-FOREIGN | |
2460 | |
2461 @page | |
2462 @node convert-to-foreign, defbitfield, convert-from-foreign, Foreign Typ… | |
2463 @heading convert-to-foreign | |
2464 @subheading Syntax | |
2465 @Function{convert-to-foreign value type @res{} foreign-value, alloc-para… | |
2466 | |
2467 @subheading Arguments and Values | |
2468 | |
2469 @table @var | |
2470 @item value | |
2471 The Lisp object to be translated to a foreign object. | |
2472 | |
2473 @item type | |
2474 A @cffi{} type specifier. | |
2475 | |
2476 @item foreign-value | |
2477 The primitive C value, ready to be passed to a primitive foreign | |
2478 function. | |
2479 | |
2480 @item alloc-params | |
2481 Something of a translation state; you must pass it to | |
2482 @code{free-converted-object} along with the foreign value for that to | |
2483 work. | |
2484 @end table | |
2485 | |
2486 @subheading Description | |
2487 | |
2488 This is an external interface to the type translation facility. In | |
2489 the implementation, all foreign functions are ultimately defined as | |
2490 type translation wrappers around primitive foreign function | |
2491 invocations. | |
2492 | |
2493 This function is available mostly for inspection of the type | |
2494 translation process, and possibly optimization of special cases of | |
2495 your foreign function calls. | |
2496 | |
2497 Its behavior is better described under @code{translate-to-foreign}'s | |
2498 documentation. | |
2499 | |
2500 @subheading Examples | |
2501 | |
2502 @lisp | |
2503 CFFI-USER> (convert-to-foreign t :boolean) | |
2504 @result{} 1 | |
2505 @result{} NIL | |
2506 CFFI-USER> (convert-to-foreign "hello, world" :string) | |
2507 @result{} #<FOREIGN-ADDRESS #x097C5F80> | |
2508 @result{} T | |
2509 CFFI-USER> (code-char (mem-aref * :char 5)) | |
2510 @result{} #\, | |
2511 @end lisp | |
2512 | |
2513 @subheading See Also | |
2514 @seealso{convert-from-foreign} @* | |
2515 @seealso{free-converted-object} @* | |
2516 @seealso{translate-to-foreign} | |
2517 | |
2518 | |
2519 @c =================================================================== | |
2520 @c DEFBITFIELD | |
2521 | |
2522 @page | |
2523 @node defbitfield, defcstruct, convert-to-foreign, Foreign Types | |
2524 @heading defbitfield | |
2525 @subheading Syntax | |
2526 @Macro{defbitfield name-and-options &body masks} | |
2527 | |
2528 masks ::= [docstring] @{ (symbol value) @}* @* | |
2529 name-and-options ::= name | (name &optional (base-type :int)) | |
2530 | |
2531 @subheading Arguments and Values | |
2532 | |
2533 @table @var | |
2534 @item name | |
2535 The name of the new bitfield type. | |
2536 | |
2537 @item docstring | |
2538 A documentation string, ignored. | |
2539 | |
2540 @item base-type | |
2541 A symbol denoting a foreign type. | |
2542 | |
2543 @item symbol | |
2544 A Lisp symbol. | |
2545 | |
2546 @item value | |
2547 An integer representing a bitmask. | |
2548 @end table | |
2549 | |
2550 @subheading Description | |
2551 The @code{defbitfield} macro is used to define foreign types that map | |
2552 lists of symbols to integer values. | |
2553 | |
2554 If @var{value} is omitted, it will be computed as follows: find the | |
2555 greatest @var{value} previously used, including those so computed, | |
2556 with only a single 1-bit in its binary representation (that is, powers | |
2557 of two), and left-shift it by one. This rule guarantees that a | |
2558 computed @var{value} cannot clash with previous values, but may clash | |
2559 with future explicitly specified values. | |
2560 | |
2561 Symbol lists will be automatically converted to values and vice versa | |
2562 when being passed as arguments to or returned from foreign functions, | |
2563 respectively. The same applies to any other situations where an object | |
2564 of a bitfield type is expected. | |
2565 | |
2566 Types defined with @code{defbitfield} canonicalize to @var{base-type} | |
2567 which is @code{:int} by default. | |
2568 | |
2569 @subheading Examples | |
2570 @lisp | |
2571 (defbitfield open-flags | |
2572 (:rdonly #x0000) | |
2573 :wronly ;@lispcmt{#x0001} | |
2574 :rdwr ;@lispcmt{@dots{}} | |
2575 :nonblock | |
2576 :append | |
2577 (:creat #x0200)) | |
2578 ;; @lispcmt{etc@dots{}} | |
2579 | |
2580 CFFI> (foreign-bitfield-symbols 'open-flags #b1101) | |
2581 @result{} (:WRONLY :NONBLOCK :APPEND) | |
2582 | |
2583 CFFI> (foreign-bitfield-value 'open-flags '(:rdwr :creat)) | |
2584 @result{} 514 ; #x0202 | |
2585 | |
2586 (defcfun ("open" unix-open) :int | |
2587 (path :string) | |
2588 (flags open-flags) | |
2589 (mode :uint16)) ; unportable | |
2590 | |
2591 CFFI> (unix-open "/tmp/foo" '(:wronly :creat) #o644) | |
2592 @result{} #<an fd> | |
2593 | |
2594 ;;; @lispcmt{Consider also the following lispier wrapper around open()} | |
2595 (defun lispier-open (path mode &rest flags) | |
2596 (unix-open path flags mode)) | |
2597 @end lisp | |
2598 | |
2599 @subheading See Also | |
2600 @seealso{foreign-bitfield-value} @* | |
2601 @seealso{foreign-bitfield-symbols} | |
2602 | |
2603 | |
2604 @c =================================================================== | |
2605 @c DEFCSTRUCT | |
2606 | |
2607 @page | |
2608 @node defcstruct, defcunion, defbitfield, Foreign Types | |
2609 @heading defcstruct | |
2610 @subheading Syntax | |
2611 @Macro{defcstruct name-and-options &body doc-and-slots @res{} name} | |
2612 | |
2613 name-and-options ::= structure-name | (structure-name &key size) | |
2614 | |
2615 doc-and-slots ::= [docstring] @{ (slot-name slot-type &key count offset)… | |
2616 | |
2617 @subheading Arguments and Values | |
2618 | |
2619 @table @var | |
2620 @item structure-name | |
2621 The name of new structure type. | |
2622 | |
2623 @item docstring | |
2624 A documentation string, ignored. | |
2625 | |
2626 @item slot-name | |
2627 A symbol naming the slot. It must be unique among slot names in this | |
2628 structure. | |
2629 | |
2630 @item size | |
2631 Use this option to override the size (in bytes) of the struct. | |
2632 | |
2633 @item slot-type | |
2634 The type specifier for the slot. | |
2635 | |
2636 @item count | |
2637 Used to declare an array of size @var{count} inside the | |
2638 structure. Defaults to @code{1} as such an array and a single element | |
2639 are semantically equivalent. | |
2640 | |
2641 @item offset | |
2642 Overrides the slot's offset. The next slot's offset is calculated | |
2643 based on this one. | |
2644 @end table | |
2645 | |
2646 @subheading Description | |
2647 This defines a new @cffi{} aggregate type akin to C @code{struct}s. | |
2648 In other words, it specifies that foreign objects of the type | |
2649 @var{structure-name} are groups of different pieces of data, or | |
2650 ``slots'', of the @var{slot-type}s, distinguished from each other by | |
2651 the @var{slot-name}s. Each structure is located in memory at a | |
2652 position, and the slots are allocated sequentially beginning at that | |
2653 point in memory (with some padding allowances as defined by the C | |
2654 @acronym{ABI}, unless otherwise requested by specifying an | |
2655 @var{offset} from the beginning of the structure (offset 0). | |
2656 | |
2657 In other words, it is isomorphic to the C @code{struct}, giving | |
2658 several extra features. | |
2659 | |
2660 There are two kinds of slots, for the two kinds of @cffi{} types: | |
2661 | |
2662 @table @dfn | |
2663 @item Simple | |
2664 Contain a single instance of a type that canonicalizes to a built-in | |
2665 type, such as @code{:long} or @code{:pointer}. Used for simple | |
2666 @cffi{} types. | |
2667 | |
2668 @item Aggregate | |
2669 Contain an embedded structure or union, or an array of objects. Used | |
2670 for aggregate @cffi{} types. | |
2671 @end table | |
2672 | |
2673 The use of @acronym{CLOS} terminology for the structure-related | |
2674 features is intentional; structure definitions are very much like | |
2675 classes with (far) fewer features. | |
2676 | |
2677 @subheading Examples | |
2678 @lisp | |
2679 (defcstruct point | |
2680 "Point structure." | |
2681 (x :int) | |
2682 (y :int)) | |
2683 | |
2684 CFFI> (with-foreign-object (ptr 'point) | |
2685 ;; @lispcmt{Initialize the slots} | |
2686 (setf (foreign-slot-value ptr 'point 'x) 42 | |
2687 (foreign-slot-value ptr 'point 'y) 42) | |
2688 ;; @lispcmt{Return a list with the coordinates} | |
2689 (with-foreign-slots ((x y) ptr point) | |
2690 (list x y))) | |
2691 @result{} (42 42) | |
2692 @end lisp | |
2693 | |
2694 @lisp | |
2695 ;; @lispcmt{Using the :size and :offset options to define a partial stru… | |
2696 ;; @lispcmt{(this is useful when you are interested in only a few slots} | |
2697 ;; @lispcmt{of a big foreign structure)} | |
2698 | |
2699 (defcstruct (foo :size 32) | |
2700 "Some struct with 32 bytes." | |
2701 ; @lispcmt{<16 bytes we don't care about>} | |
2702 (x :int :offset 16) ; @lispcmt{an int at offset 16} | |
2703 (y :int) ; @lispcmt{another int at offset 16+sizeof(int)} | |
2704 ; @lispcmt{<a couple more bytes we don't care ab… | |
2705 (z :char :offset 24)) ; @lispcmt{a char at offset 24} | |
2706 ; @lispcmt{<7 more bytes ignored (since size is … | |
2707 | |
2708 CFFI> (foreign-type-size 'foo) | |
2709 @result{} 32 | |
2710 @end lisp | |
2711 | |
2712 @lisp | |
2713 ;;; @lispcmt{Using :count to define arrays inside of a struct.} | |
2714 (defcstruct video_tuner | |
2715 (name :char :count 32)) | |
2716 @end lisp | |
2717 | |
2718 @subheading See Also | |
2719 @seealso{foreign-slot-pointer} @* | |
2720 @seealso{foreign-slot-value} @* | |
2721 @seealso{with-foreign-slots} | |
2722 | |
2723 | |
2724 @c =================================================================== | |
2725 @c DEFCUNION | |
2726 | |
2727 @page | |
2728 @node defcunion, defctype, defcstruct, Foreign Types | |
2729 @heading defcunion | |
2730 @subheading Syntax | |
2731 @Macro{defcunion name &body doc-and-slots @res{} name} | |
2732 | |
2733 doc-and-slots ::= [docstring] @{ (slot-name slot-type &key count) @}* | |
2734 | |
2735 @subheading Arguments and Values | |
2736 | |
2737 @table @var | |
2738 @item name | |
2739 The name of new union type. | |
2740 | |
2741 @item docstring | |
2742 A documentation string, ignored. | |
2743 | |
2744 @item slot-name | |
2745 A symbol naming the slot. | |
2746 | |
2747 @item slot-type | |
2748 The type specifier for the slot. | |
2749 | |
2750 @item count | |
2751 Used to declare an array of size @var{count} inside the | |
2752 structure. | |
2753 @end table | |
2754 | |
2755 @subheading Description | |
2756 A union is a structure in which all slots have an offset of zero. It | |
2757 is isomorphic to the C @code{union}. Therefore, you should use the | |
2758 usual foreign structure operations for accessing a union's slots. | |
2759 | |
2760 @subheading Examples | |
2761 @lisp | |
2762 (defcunion uint32-bytes | |
2763 (int-value :unsigned-int) | |
2764 (bytes :unsigned-char :count 4)) | |
2765 @end lisp | |
2766 | |
2767 @subheading See Also | |
2768 @seealso{foreign-slot-pointer} @* | |
2769 @seealso{foreign-slot-value} | |
2770 | |
2771 | |
2772 @c =================================================================== | |
2773 @c DEFCTYPE | |
2774 | |
2775 @page | |
2776 @node defctype, defcenum, defcunion, Foreign Types | |
2777 @heading defctype | |
2778 @subheading Syntax | |
2779 @Macro{defctype name base-type &optional documentation} | |
2780 | |
2781 @subheading Arguments and Values | |
2782 | |
2783 @table @var | |
2784 @item name | |
2785 The name of the new foreign type. | |
2786 | |
2787 @item base-type | |
2788 A symbol or a list defining the new type. | |
2789 | |
2790 @item documentation | |
2791 A documentation string, currently ignored. | |
2792 @end table | |
2793 | |
2794 @subheading Description | |
2795 The @code{defctype} macro provides a mechanism similar to C's | |
2796 @code{typedef} to define new types. The new type inherits | |
2797 @var{base-type}'s translators, if any. There is no way to define | |
2798 translations for types defined with @code{defctype}. For that, | |
2799 you should use @ref{define-foreign-type}. | |
2800 | |
2801 @subheading Examples | |
2802 @lisp | |
2803 (defctype my-string :string | |
2804 "My own string type.") | |
2805 | |
2806 (defctype long-bools (:boolean :long) | |
2807 "Booleans that map to C longs.") | |
2808 @end lisp | |
2809 | |
2810 @subheading See Also | |
2811 @seealso{define-foreign-type} | |
2812 | |
2813 | |
2814 @c =================================================================== | |
2815 @c DEFCENUM | |
2816 | |
2817 @page | |
2818 @node defcenum, define-foreign-type, defctype, Foreign Types | |
2819 @heading defcenum | |
2820 @subheading Syntax | |
2821 @Macro{defcenum name-and-options &body enum-list} | |
2822 | |
2823 enum-list ::= [docstring] @{ keyword | (keyword value) @}* | |
2824 name-and-options ::= name | (name &optional (base-type :int)) | |
2825 | |
2826 @subheading Arguments and Values | |
2827 | |
2828 @table @var | |
2829 @item name | |
2830 The name of the new enum type. | |
2831 | |
2832 @item docstring | |
2833 A documentation string, ignored. | |
2834 | |
2835 @item base-type | |
2836 A symbol denoting a foreign type. | |
2837 | |
2838 @item keyword | |
2839 A keyword symbol. | |
2840 | |
2841 @item value | |
2842 An index value for a keyword. | |
2843 @end table | |
2844 | |
2845 @subheading Description | |
2846 The @code{defcenum} macro is used to define foreign types that map | |
2847 keyword symbols to integer values, similar to the C @code{enum} type. | |
2848 | |
2849 If @var{value} is omitted its value will either be 0, if it's the | |
2850 first entry, or it it will continue the progression from the last | |
2851 specified value. | |
2852 | |
2853 Keywords will be automatically converted to values and vice-versa when | |
2854 being passed as arguments to or returned from foreign functions, | |
2855 respectively. The same applies to any other situations where an object | |
2856 of an @code{enum} type is expected. | |
2857 | |
2858 Types defined with @code{defcenum} canonicalize to @var{base-type} | |
2859 which is @code{:int} by default. | |
2860 | |
2861 @subheading Examples | |
2862 @lisp | |
2863 (defcenum boolean | |
2864 :no | |
2865 :yes) | |
2866 | |
2867 CFFI> (foreign-enum-value 'boolean :no) | |
2868 @result{} 0 | |
2869 @end lisp | |
2870 | |
2871 @lisp | |
2872 (defcenum numbers | |
2873 (:one 1) | |
2874 :two | |
2875 (:four 4)) | |
2876 | |
2877 CFFI> (foreign-enum-keyword 'numbers 2) | |
2878 @result{} :TWO | |
2879 @end lisp | |
2880 | |
2881 @subheading See Also | |
2882 @seealso{foreign-enum-value} @* | |
2883 @seealso{foreign-enum-keyword} | |
2884 | |
2885 | |
2886 @c =================================================================== | |
2887 @c DEFINE-FOREIGN-TYPE | |
2888 | |
2889 @page | |
2890 @node define-foreign-type, define-parse-method, defcenum, Foreign Types | |
2891 @heading define-foreign-type | |
2892 @subheading Syntax | |
2893 @Macro{define-foreign-type class-name supers slots &rest options @res{} … | |
2894 | |
2895 options ::= (@code{:actual-type} @var{type}) | @ | |
2896 (@code{:simple-parser} @var{symbol}) | @ | |
2897 @emph{regular defclass option} | |
2898 | |
2899 @subheading Arguments and Values | |
2900 | |
2901 @table @var | |
2902 @item class-name | |
2903 A symbol naming the new foreign type class. | |
2904 | |
2905 @item supers | |
2906 A list of symbols naming the super classes. | |
2907 | |
2908 @item slots | |
2909 A list of slot definitions, passed to @code{defclass}. | |
2910 @end table | |
2911 | |
2912 @subheading Description | |
2913 | |
2914 @c TODO rewrite | |
2915 | |
2916 The macro @code{define-foreign-type} defines a new class | |
2917 @var{class-name}. It is a thin wrapper around @code{defclass}. Among | |
2918 other things, it ensures that @var{class-name} becomes a subclass of | |
2919 @var{foreign-type}, what you need to know about that is that there's | |
2920 an initarg @code{:actual-type} which serves the same purpose as | |
2921 @code{defctype}'s @var{base-type} argument. | |
2922 | |
2923 @c TODO mention the type translators here | |
2924 @c FIX FIX | |
2925 | |
2926 @subheading Examples | |
2927 Taken from @cffi{}'s @code{:boolean} type definition: | |
2928 | |
2929 @lisp | |
2930 (define-foreign-type :boolean (&optional (base-type :int)) | |
2931 "Boolean type. Maps to an :int by default. Only accepts integer types." | |
2932 (ecase base-type | |
2933 ((:char | |
2934 :unsigned-char | |
2935 :int | |
2936 :unsigned-int | |
2937 :long | |
2938 :unsigned-long) base-type))) | |
2939 | |
2940 CFFI> (canonicalize-foreign-type :boolean) | |
2941 @result{} :INT | |
2942 CFFI> (canonicalize-foreign-type '(:boolean :long)) | |
2943 @result{} :LONG | |
2944 CFFI> (canonicalize-foreign-type '(:boolean :float)) | |
2945 ;; @lispcmt{@error{} signalled by ECASE.} | |
2946 @end lisp | |
2947 | |
2948 @subheading See Also | |
2949 @seealso{defctype} @* | |
2950 @seealso{define-parse-method} | |
2951 | |
2952 | |
2953 @c =================================================================== | |
2954 @c DEFINE-PARSE-METHOD | |
2955 | |
2956 @page | |
2957 @node define-parse-method, foreign-bitfield-symbols, define-foreign-type… | |
2958 @heading define-parse-method | |
2959 @subheading Syntax | |
2960 @Macro{define-parse-method name lambda-list &body body @res{} name} | |
2961 | |
2962 @subheading Arguments and Values | |
2963 | |
2964 @table @var | |
2965 @item type-name | |
2966 A symbol naming the new foreign type. | |
2967 | |
2968 @item lambda-list | |
2969 A lambda list which is the argument list of the new foreign type. | |
2970 | |
2971 @item body | |
2972 One or more forms that provide a definition of the new foreign type. | |
2973 @end table | |
2974 | |
2975 @subheading Description | |
2976 | |
2977 | |
2978 @c TODO: update example. The boolean type is probably a good choice. | |
2979 | |
2980 @subheading Examples | |
2981 Taken from @cffi{}'s @code{:boolean} type definition: | |
2982 | |
2983 @lisp | |
2984 (define-foreign-type :boolean (&optional (base-type :int)) | |
2985 "Boolean type. Maps to an :int by default. Only accepts integer types." | |
2986 (ecase base-type | |
2987 ((:char | |
2988 :unsigned-char | |
2989 :int | |
2990 :unsigned-int | |
2991 :long | |
2992 :unsigned-long) base-type))) | |
2993 | |
2994 CFFI> (canonicalize-foreign-type :boolean) | |
2995 @result{} :INT | |
2996 CFFI> (canonicalize-foreign-type '(:boolean :long)) | |
2997 @result{} :LONG | |
2998 CFFI> (canonicalize-foreign-type '(:boolean :float)) | |
2999 ;; @lispcmt{@error{} signalled by ECASE.} | |
3000 @end lisp | |
3001 | |
3002 @subheading See Also | |
3003 @seealso{define-foreign-type} | |
3004 | |
3005 | |
3006 @c =================================================================== | |
3007 @c EXPLAIN-FOREIGN-SLOT-VALUE | |
3008 | |
3009 @c @node explain-foreign-slot-value | |
3010 @c @heading explain-foreign-slot-value | |
3011 @c @subheading Syntax | |
3012 @c @Macro{explain-foreign-slot-value ptr type &rest slot-names} | |
3013 | |
3014 @c @subheading Arguments and Values | |
3015 | |
3016 @c @table @var | |
3017 @c @item ptr | |
3018 @c ... | |
3019 | |
3020 @c @item type | |
3021 @c ... | |
3022 | |
3023 @c @item slot-names | |
3024 @c ... | |
3025 @c @end table | |
3026 | |
3027 @c @subheading Description | |
3028 @c This macro translates the slot access that would occur by calling | |
3029 @c @code{foreign-slot-value} with the same arguments into an equivalent | |
3030 @c expression in C and prints it to @code{*standard-output*}. | |
3031 | |
3032 @c @emph{Note: this is not implemented yet.} | |
3033 | |
3034 @c @subheading Examples | |
3035 @c @lisp | |
3036 @c CFFI> (explain-foreign-slot-value ptr 'timeval 'tv-secs) | |
3037 @c @result{} ptr->tv_secs | |
3038 | |
3039 @c CFFI> (explain-foreign-slot-value emp 'employee 'hire-date 'tv-usecs) | |
3040 @c @result{} emp->hire_date.tv_usecs | |
3041 @c @end lisp | |
3042 | |
3043 @c @subheading See Also | |
3044 | |
3045 | |
3046 @c =================================================================== | |
3047 @c FOREIGN-BITFIELD-SYMBOLS | |
3048 | |
3049 @page | |
3050 @node foreign-bitfield-symbols, foreign-bitfield-value, define-parse-met… | |
3051 @heading foreign-bitfield-symbols | |
3052 @subheading Syntax | |
3053 @Function{foreign-bitfield-symbols type value @res{} symbols} | |
3054 | |
3055 @subheading Arguments and Values | |
3056 | |
3057 @table @var | |
3058 @item type | |
3059 A bitfield type. | |
3060 | |
3061 @item value | |
3062 An integer. | |
3063 | |
3064 @item symbols | |
3065 A potentially shared list of symbols. | |
3066 @code{nil}. | |
3067 @end table | |
3068 | |
3069 @subheading Description | |
3070 The function @code{foreign-bitfield-symbols} returns a possibly shared | |
3071 list of symbols that correspond to @var{value} in @var{type}. | |
3072 | |
3073 @subheading Examples | |
3074 @lisp | |
3075 (defbitfield flags | |
3076 (flag-a 1) | |
3077 (flag-b 2) | |
3078 (flag-c 4)) | |
3079 | |
3080 CFFI> (foreign-bitfield-symbols 'flags #b101) | |
3081 @result{} (FLAG-A FLAG-C) | |
3082 @end lisp | |
3083 | |
3084 @subheading See Also | |
3085 @seealso{defbitfield} @* | |
3086 @seealso{foreign-bitfield-value} | |
3087 | |
3088 | |
3089 @c =================================================================== | |
3090 @c FOREIGN-BITFIELD-VALUE | |
3091 | |
3092 @page | |
3093 @node foreign-bitfield-value, foreign-enum-keyword, foreign-bitfield-sym… | |
3094 @heading foreign-bitfield-value | |
3095 @subheading Syntax | |
3096 @Function{foreign-bitfield-value type symbols @res{} value} | |
3097 | |
3098 @subheading Arguments and Values | |
3099 | |
3100 @table @var | |
3101 @item type | |
3102 A @code{bitfield} type. | |
3103 | |
3104 @item symbol | |
3105 A Lisp symbol. | |
3106 | |
3107 @item value | |
3108 An integer. | |
3109 @end table | |
3110 | |
3111 @subheading Description | |
3112 The function @code{foreign-bitfield-value} returns the @var{value} that | |
3113 corresponds to the symbols in the @var{symbols} list. | |
3114 | |
3115 @subheading Examples | |
3116 @lisp | |
3117 (defbitfield flags | |
3118 (flag-a 1) | |
3119 (flag-b 2) | |
3120 (flag-c 4)) | |
3121 | |
3122 CFFI> (foreign-bitfield-value 'flags '(flag-a flag-c)) | |
3123 @result{} 5 ; #b101 | |
3124 @end lisp | |
3125 | |
3126 @subheading See Also | |
3127 @seealso{defbitfield} @* | |
3128 @seealso{foreign-bitfield-symbols} | |
3129 | |
3130 | |
3131 @c =================================================================== | |
3132 @c FOREIGN-ENUM-KEYWORD | |
3133 | |
3134 @page | |
3135 @node foreign-enum-keyword, foreign-enum-value, foreign-bitfield-value, … | |
3136 @heading foreign-enum-keyword | |
3137 @subheading Syntax | |
3138 @Function{foreign-enum-keyword type value &key errorp @res{} keyword} | |
3139 | |
3140 @subheading Arguments and Values | |
3141 | |
3142 @table @var | |
3143 @item type | |
3144 An @code{enum} type. | |
3145 | |
3146 @item value | |
3147 An integer. | |
3148 | |
3149 @item errorp | |
3150 If true (the default), signal an error if @var{value} is not defined | |
3151 in @var{type}. If false, @code{foreign-enum-keyword} returns | |
3152 @code{nil}. | |
3153 | |
3154 @item keyword | |
3155 A keyword symbol. | |
3156 @end table | |
3157 | |
3158 @subheading Description | |
3159 The function @code{foreign-enum-keyword} returns the keyword symbol | |
3160 that corresponds to @var{value} in @var{type}. | |
3161 | |
3162 An error is signaled if @var{type} doesn't contain such @var{value} | |
3163 and @var{errorp} is true. | |
3164 | |
3165 @subheading Examples | |
3166 @lisp | |
3167 (defcenum boolean | |
3168 :no | |
3169 :yes) | |
3170 | |
3171 CFFI> (foreign-enum-keyword 'boolean 1) | |
3172 @result{} :YES | |
3173 @end lisp | |
3174 | |
3175 @subheading See Also | |
3176 @seealso{defcenum} @* | |
3177 @seealso{foreign-enum-value} | |
3178 | |
3179 | |
3180 @c =================================================================== | |
3181 @c FOREIGN-ENUM-VALUE | |
3182 | |
3183 @page | |
3184 @node foreign-enum-value, foreign-slot-names, foreign-enum-keyword, Fore… | |
3185 @heading foreign-enum-value | |
3186 @subheading Syntax | |
3187 @Function{foreign-enum-value type keyword &key errorp @res{} value} | |
3188 | |
3189 @subheading Arguments and Values | |
3190 | |
3191 @table @var | |
3192 @item type | |
3193 An @code{enum} type. | |
3194 | |
3195 @item keyword | |
3196 A keyword symbol. | |
3197 | |
3198 @item errorp | |
3199 If true (the default), signal an error if @var{keyword} is not | |
3200 defined in @var{type}. If false, @code{foreign-enum-value} returns | |
3201 @code{nil}. | |
3202 | |
3203 @item value | |
3204 An integer. | |
3205 @end table | |
3206 | |
3207 @subheading Description | |
3208 The function @code{foreign-enum-value} returns the @var{value} that | |
3209 corresponds to @var{keyword} in @var{type}. | |
3210 | |
3211 An error is signaled if @var{type} doesn't contain such | |
3212 @var{keyword}, and @var{errorp} is true. | |
3213 | |
3214 @subheading Examples | |
3215 @lisp | |
3216 (defcenum boolean | |
3217 :no | |
3218 :yes) | |
3219 | |
3220 CFFI> (foreign-enum-value 'boolean :yes) | |
3221 @result{} 1 | |
3222 @end lisp | |
3223 | |
3224 @subheading See Also | |
3225 @seealso{defcenum} @* | |
3226 @seealso{foreign-enum-keyword} | |
3227 | |
3228 | |
3229 @c =================================================================== | |
3230 @c FOREIGN-SLOT-NAMES | |
3231 | |
3232 @page | |
3233 @node foreign-slot-names, foreign-slot-offset, foreign-enum-value, Forei… | |
3234 @heading foreign-slot-names | |
3235 @subheading Syntax | |
3236 @Function{foreign-slot-names type @res{} names} | |
3237 | |
3238 @subheading Arguments and Values | |
3239 | |
3240 @table @var | |
3241 @item type | |
3242 A foreign struct type. | |
3243 | |
3244 @item names | |
3245 A list. | |
3246 @end table | |
3247 | |
3248 @subheading Description | |
3249 The function @code{foreign-slot-names} returns a potentially shared | |
3250 list of slot @var{names} for the given structure @var{type}. This list | |
3251 has no particular order. | |
3252 | |
3253 @subheading Examples | |
3254 @lisp | |
3255 (defcstruct timeval | |
3256 (tv-secs :long) | |
3257 (tv-usecs :long)) | |
3258 | |
3259 CFFI> (foreign-slot-names '(:struct timeval)) | |
3260 @result{} (TV-SECS TV-USECS) | |
3261 @end lisp | |
3262 | |
3263 @subheading See Also | |
3264 @seealso{defcstruct} @* | |
3265 @seealso{foreign-slot-offset} @* | |
3266 @seealso{foreign-slot-value} @* | |
3267 @seealso{foreign-slot-pointer} | |
3268 | |
3269 | |
3270 @c =================================================================== | |
3271 @c FOREIGN-SLOT-OFFSET | |
3272 | |
3273 @page | |
3274 @node foreign-slot-offset, foreign-slot-pointer, foreign-slot-names, For… | |
3275 @heading foreign-slot-offset | |
3276 @subheading Syntax | |
3277 @Function{foreign-slot-offset type slot-name @res{} offset} | |
3278 | |
3279 @subheading Arguments and Values | |
3280 | |
3281 @table @var | |
3282 @item type | |
3283 A foreign struct type. | |
3284 | |
3285 @item slot-name | |
3286 A symbol. | |
3287 | |
3288 @item offset | |
3289 An integer. | |
3290 @end table | |
3291 | |
3292 @subheading Description | |
3293 The function @code{foreign-slot-offset} returns the @var{offset} in | |
3294 bytes of a slot in a foreign struct type. | |
3295 | |
3296 @subheading Examples | |
3297 @lisp | |
3298 (defcstruct timeval | |
3299 (tv-secs :long) | |
3300 (tv-usecs :long)) | |
3301 | |
3302 CFFI> (foreign-slot-offset '(:struct timeval) 'tv-secs) | |
3303 @result{} 0 | |
3304 CFFI> (foreign-slot-offset '(:struct timeval) 'tv-usecs) | |
3305 @result{} 4 | |
3306 @end lisp | |
3307 | |
3308 @subheading See Also | |
3309 @seealso{defcstruct} @* | |
3310 @seealso{foreign-slot-names} @* | |
3311 @seealso{foreign-slot-pointer} @* | |
3312 @seealso{foreign-slot-value} | |
3313 | |
3314 | |
3315 @c =================================================================== | |
3316 @c FOREIGN-SLOT-POINTER | |
3317 | |
3318 @page | |
3319 @node foreign-slot-pointer, foreign-slot-value, foreign-slot-offset, For… | |
3320 @heading foreign-slot-pointer | |
3321 @subheading Syntax | |
3322 @Function{foreign-slot-pointer ptr type slot-name @res{} pointer} | |
3323 | |
3324 @subheading Arguments and Values | |
3325 | |
3326 @table @var | |
3327 @item ptr | |
3328 A pointer to a structure. | |
3329 | |
3330 @item type | |
3331 A foreign structure type. | |
3332 | |
3333 @item slot-names | |
3334 A slot name in the @var{type}. | |
3335 | |
3336 @item pointer | |
3337 A pointer to the slot @var{slot-name}. | |
3338 @end table | |
3339 | |
3340 @subheading Description | |
3341 Returns a pointer to the location of the slot @var{slot-name} in a | |
3342 foreign object of type @var{type} at @var{ptr}. The returned pointer | |
3343 points inside the structure. Both the pointer and the memory it points | |
3344 to have the same extent as @var{ptr}. | |
3345 | |
3346 For aggregate slots, this is the same value returned by | |
3347 @code{foreign-slot-value}. | |
3348 | |
3349 @subheading Examples | |
3350 @lisp | |
3351 (defcstruct point | |
3352 "Pointer structure." | |
3353 (x :int) | |
3354 (y :int)) | |
3355 | |
3356 CFFI> (with-foreign-object (ptr '(:struct point)) | |
3357 (foreign-slot-pointer ptr '(:struct point) 'x)) | |
3358 @result{} #<FOREIGN-ADDRESS #xBFFF6E60> | |
3359 ;; @lispcmt{Note: the exact pointer representation varies from lisp to l… | |
3360 @end lisp | |
3361 | |
3362 @subheading See Also | |
3363 @seealso{defcstruct} @* | |
3364 @seealso{foreign-slot-value} @* | |
3365 @seealso{foreign-slot-names} @* | |
3366 @seealso{foreign-slot-offset} | |
3367 | |
3368 | |
3369 @c =================================================================== | |
3370 @c FOREIGN-SLOT-VALUE | |
3371 | |
3372 @page | |
3373 @node foreign-slot-value, foreign-type-alignment, foreign-slot-pointer, … | |
3374 @heading foreign-slot-value | |
3375 @subheading Syntax | |
3376 @Accessor{foreign-slot-value ptr type slot-name @res{} object} | |
3377 | |
3378 @subheading Arguments and Values | |
3379 | |
3380 @table @var | |
3381 @item ptr | |
3382 A pointer to a structure. | |
3383 | |
3384 @item type | |
3385 A foreign structure type. | |
3386 | |
3387 @item slot-name | |
3388 A symbol naming a slot in the structure type. | |
3389 | |
3390 @item object | |
3391 The object contained in the slot specified by @var{slot-name}. | |
3392 @end table | |
3393 | |
3394 @subheading Description | |
3395 For simple slots, @code{foreign-slot-value} returns the value of the | |
3396 object, such as a Lisp integer or pointer. In C, this would be | |
3397 expressed as @code{ptr->slot}. | |
3398 | |
3399 For aggregate slots, a pointer inside the structure to the beginning | |
3400 of the slot's data is returned. In C, this would be expressed as | |
3401 @code{&ptr->slot}. This pointer and the memory it points to have the | |
3402 same extent as @var{ptr}. | |
3403 | |
3404 There are compiler macros for @code{foreign-slot-value} and its | |
3405 @code{setf} expansion that open code the memory access when | |
3406 @var{type} and @var{slot-names} are constant at compile-time. | |
3407 | |
3408 @subheading Examples | |
3409 @lisp | |
3410 (defcstruct point | |
3411 "Pointer structure." | |
3412 (x :int) | |
3413 (y :int)) | |
3414 | |
3415 CFFI> (with-foreign-object (ptr '(:struct point)) | |
3416 ;; @lispcmt{Initialize the slots} | |
3417 (setf (foreign-slot-value ptr '(:struct point) 'x) 42 | |
3418 (foreign-slot-value ptr '(:struct point) 'y) 42) | |
3419 ;; @lispcmt{Return a list with the coordinates} | |
3420 (with-foreign-slots ((x y) ptr (:struct point)) | |
3421 (list x y))) | |
3422 @result{} (42 42) | |
3423 @end lisp | |
3424 | |
3425 @subheading See Also | |
3426 @seealso{defcstruct} @* | |
3427 @seealso{foreign-slot-names} @* | |
3428 @seealso{foreign-slot-offset} @* | |
3429 @seealso{foreign-slot-pointer} @* | |
3430 @seealso{with-foreign-slots} | |
3431 | |
3432 | |
3433 @c =================================================================== | |
3434 @c FOREIGN-TYPE-ALIGNMENT | |
3435 | |
3436 @page | |
3437 @node foreign-type-alignment, foreign-type-size, foreign-slot-value, For… | |
3438 @heading foreign-type-alignment | |
3439 @subheading Syntax | |
3440 @c XXX: This is actually a generic function. | |
3441 @Function{foreign-type-alignment type @res{} alignment} | |
3442 | |
3443 @subheading Arguments and Values | |
3444 | |
3445 @table @var | |
3446 @item type | |
3447 A foreign type. | |
3448 | |
3449 @item alignment | |
3450 An integer. | |
3451 @end table | |
3452 | |
3453 @subheading Description | |
3454 The function @code{foreign-type-alignment} returns the | |
3455 @var{alignment} of @var{type} in bytes. | |
3456 | |
3457 @subheading Examples | |
3458 @lisp | |
3459 CFFI> (foreign-type-alignment :char) | |
3460 @result{} 1 | |
3461 CFFI> (foreign-type-alignment :short) | |
3462 @result{} 2 | |
3463 CFFI> (foreign-type-alignment :int) | |
3464 @result{} 4 | |
3465 @end lisp | |
3466 | |
3467 @lisp | |
3468 (defcstruct foo | |
3469 (a :char)) | |
3470 | |
3471 CFFI> (foreign-type-alignment '(:struct foo)) | |
3472 @result{} 1 | |
3473 @end lisp | |
3474 | |
3475 @subheading See Also | |
3476 @seealso{foreign-type-size} | |
3477 | |
3478 | |
3479 @c =================================================================== | |
3480 @c FOREIGN-TYPE-SIZE | |
3481 | |
3482 @page | |
3483 @node foreign-type-size, free-converted-object, foreign-type-alignment, … | |
3484 @heading foreign-type-size | |
3485 @subheading Syntax | |
3486 @c XXX: this is actually a generic function. | |
3487 @Function{foreign-type-size type @res{} size} | |
3488 | |
3489 @subheading Arguments and Values | |
3490 | |
3491 @table @var | |
3492 @item type | |
3493 A foreign type. | |
3494 | |
3495 @item size | |
3496 An integer. | |
3497 @end table | |
3498 | |
3499 @subheading Description | |
3500 The function @code{foreign-type-size} return the @var{size} of | |
3501 @var{type} in bytes. This includes any padding within and following | |
3502 the in-memory representation as needed to create an array of | |
3503 @var{type} objects. | |
3504 | |
3505 @subheading Examples | |
3506 @lisp | |
3507 (defcstruct foo | |
3508 (a :double) | |
3509 (c :char)) | |
3510 | |
3511 CFFI> (foreign-type-size :double) | |
3512 @result{} 8 | |
3513 CFFI> (foreign-type-size :char) | |
3514 @result{} 1 | |
3515 CFFI> (foreign-type-size '(:struct foo)) | |
3516 @result{} 16 | |
3517 @end lisp | |
3518 | |
3519 @subheading See Also | |
3520 @seealso{foreign-type-alignment} | |
3521 | |
3522 | |
3523 @c =================================================================== | |
3524 @c FREE-CONVERTED-OBJECT | |
3525 | |
3526 @page | |
3527 @node free-converted-object, free-translated-object, foreign-type-size, … | |
3528 @heading free-converted-object | |
3529 @subheading Syntax | |
3530 @Function{free-converted-object foreign-value type params} | |
3531 | |
3532 @subheading Arguments and Values | |
3533 | |
3534 @table @var | |
3535 @item foreign-value | |
3536 The C object to be freed. | |
3537 | |
3538 @item type | |
3539 A @cffi{} type specifier. | |
3540 | |
3541 @item params | |
3542 The state returned as the second value from @code{convert-to-foreign}; | |
3543 used to implement the third argument to @code{free-translated-object}. | |
3544 @end table | |
3545 | |
3546 @subheading Description | |
3547 | |
3548 The return value is unspecified. | |
3549 | |
3550 This is an external interface to the type translation facility. In | |
3551 the implementation, all foreign functions are ultimately defined as | |
3552 type translation wrappers around primitive foreign function | |
3553 invocations. | |
3554 | |
3555 This function is available mostly for inspection of the type | |
3556 translation process, and possibly optimization of special cases of | |
3557 your foreign function calls. | |
3558 | |
3559 Its behavior is better described under @code{free-translated-object}'s | |
3560 documentation. | |
3561 | |
3562 @subheading Examples | |
3563 | |
3564 @lisp | |
3565 CFFI-USER> (convert-to-foreign "a boat" :string) | |
3566 @result{} #<FOREIGN-ADDRESS #x097ACDC0> | |
3567 @result{} T | |
3568 CFFI-USER> (free-converted-object * :string t) | |
3569 @result{} NIL | |
3570 @end lisp | |
3571 | |
3572 @subheading See Also | |
3573 @seealso{convert-from-foreign} @* | |
3574 @seealso{convert-to-foreign} @* | |
3575 @seealso{free-translated-object} | |
3576 | |
3577 | |
3578 @c =================================================================== | |
3579 @c FREE-TRANSLATED-OBJECT | |
3580 | |
3581 @c TODO: update | |
3582 | |
3583 @page | |
3584 @node free-translated-object, translate-from-foreign, free-converted-obj… | |
3585 @heading free-translated-object | |
3586 @subheading Syntax | |
3587 @GenericFunction{free-translated-object value type-name param} | |
3588 | |
3589 @subheading Arguments and Values | |
3590 | |
3591 @table @var | |
3592 @item pointer | |
3593 The foreign value returned by @code{translate-to-foreign}. | |
3594 | |
3595 @item type-name | |
3596 A symbol naming a foreign type defined by @code{defctype}. | |
3597 | |
3598 @item param | |
3599 The second value, if any, returned by @code{translate-to-foreign}. | |
3600 @end table | |
3601 | |
3602 @subheading Description | |
3603 This generic function may be specialized by user code to perform | |
3604 automatic deallocation of foreign objects as they are passed to C | |
3605 functions. | |
3606 | |
3607 Any methods defined on this generic function must EQL-specialize the | |
3608 @var{type-name} parameter on a symbol defined as a foreign type by | |
3609 the @code{defctype} macro. | |
3610 | |
3611 @subheading See Also | |
3612 @seealso{Foreign Type Translators} @* | |
3613 @seealso{translate-to-foreign} | |
3614 | |
3615 | |
3616 @c =================================================================== | |
3617 @c TRANSLATE-FROM-FOREIGN | |
3618 | |
3619 @c TODO: update | |
3620 | |
3621 @page | |
3622 @node translate-from-foreign, translate-to-foreign, free-translated-obje… | |
3623 @heading translate-from-foreign | |
3624 @subheading Syntax | |
3625 @GenericFunction{translate-from-foreign foreign-value type-name @ | |
3626 @res{} lisp-value} | |
3627 | |
3628 @subheading Arguments and Values | |
3629 | |
3630 @table @var | |
3631 @item foreign-value | |
3632 The foreign value to convert to a Lisp object. | |
3633 | |
3634 @item type-name | |
3635 A symbol naming a foreign type defined by @code{defctype}. | |
3636 | |
3637 @item lisp-value | |
3638 The lisp value to pass in place of @code{foreign-value} to Lisp code. | |
3639 @end table | |
3640 | |
3641 @subheading Description | |
3642 This generic function is invoked by @cffi{} to convert a foreign value to | |
3643 a Lisp value, such as when returning from a foreign function, passing | |
3644 arguments to a callback function, or accessing a foreign variable. | |
3645 | |
3646 To extend the @cffi{} type system by performing custom translations, this | |
3647 method may be specialized by @sc{eql}-specializing @code{type-name} on a | |
3648 symbol naming a foreign type defined with @code{defctype}. This | |
3649 method should return the appropriate Lisp value to use in place of the | |
3650 foreign value. | |
3651 | |
3652 The results are undefined if the @code{type-name} parameter is | |
3653 specialized in any way except an @sc{eql} specializer on a foreign type | |
3654 defined with @code{defctype}. Specifically, translations may not be | |
3655 defined for built-in types. | |
3656 | |
3657 @subheading See Also | |
3658 @seealso{Foreign Type Translators} @* | |
3659 @seealso{translate-to-foreign} @* | |
3660 @seealso{free-translated-object} | |
3661 | |
3662 | |
3663 @c =================================================================== | |
3664 @c TRANSLATE-TO-FOREIGN | |
3665 | |
3666 @c TODO: update | |
3667 | |
3668 @page | |
3669 @node translate-to-foreign, translate-into-foreign-memory, translate-fro… | |
3670 @heading translate-to-foreign | |
3671 @subheading Syntax | |
3672 @GenericFunction{translate-to-foreign lisp-value type-name @ | |
3673 @res{} foreign-value, alloc-param} | |
3674 | |
3675 @subheading Arguments and Values | |
3676 | |
3677 @table @var | |
3678 @item lisp-value | |
3679 The Lisp value to convert to foreign representation. | |
3680 | |
3681 @item type-name | |
3682 A symbol naming a foreign type defined by @code{defctype}. | |
3683 | |
3684 @item foreign-value | |
3685 The foreign value to pass in place of @code{lisp-value} to foreign code. | |
3686 | |
3687 @item alloc-param | |
3688 If present, this value will be passed to | |
3689 @code{free-translated-object}. | |
3690 @end table | |
3691 | |
3692 @subheading Description | |
3693 This generic function is invoked by @cffi{} to convert a Lisp value to a | |
3694 foreign value, such as when passing arguments to a foreign function, | |
3695 returning a value from a callback, or setting a foreign variable. A | |
3696 ``foreign value'' is one appropriate for passing to the next-lowest | |
3697 translator, including the low-level translators that are ultimately | |
3698 invoked invisibly with @cffi{}. | |
3699 | |
3700 To extend the @cffi{} type system by performing custom translations, this | |
3701 method may be specialized by @sc{eql}-specializing @code{type-name} on a | |
3702 symbol naming a foreign type defined with @code{defctype}. This | |
3703 method should return the appropriate foreign value to use in place of | |
3704 the Lisp value. | |
3705 | |
3706 In cases where @cffi{} can determine the lifetime of the foreign object | |
3707 returned by this method, it will invoke @code{free-translated-object} | |
3708 on the foreign object at the appropriate time. If | |
3709 @code{translate-to-foreign} returns a second value, it will be passed | |
3710 as the @code{param} argument to @code{free-translated-object}. This | |
3711 can be used to establish communication between the allocation and | |
3712 deallocation methods. | |
3713 | |
3714 The results are undefined if the @code{type-name} parameter is | |
3715 specialized in any way except an @sc{eql} specializer on a foreign type | |
3716 defined with @code{defctype}. Specifically, translations may not be | |
3717 defined for built-in types. | |
3718 | |
3719 @subheading See Also | |
3720 @seealso{Foreign Type Translators} @* | |
3721 @seealso{translate-from-foreign} @* | |
3722 @seealso{free-translated-object} | |
3723 | |
3724 | |
3725 @c =================================================================== | |
3726 @c TRANSLATE-INTO-FOREIGN-MEMORY | |
3727 | |
3728 @page | |
3729 @node translate-into-foreign-memory, with-foreign-slots, translate-to-fo… | |
3730 @heading translate-into-foreign-memory | |
3731 @subheading Syntax | |
3732 @GenericFunction{translate-into-foreign-memory lisp-value type-name poin… | |
3733 | |
3734 @subheading Arguments and Values | |
3735 | |
3736 @table @var | |
3737 @item lisp-value | |
3738 The Lisp value to convert to foreign representation. | |
3739 | |
3740 @item type-name | |
3741 A symbol or list @code{(:struct @var{structure-name})} naming a foreign … | |
3742 | |
3743 @item pointer | |
3744 The foreign pointer where the translated object should be stored. | |
3745 @end table | |
3746 | |
3747 @subheading Description | |
3748 Translate the Lisp value into the foreign memory location given by | |
3749 pointer. The return value is not used. | |
3750 | |
3751 @c =================================================================== | |
3752 @c WITH-FOREIGN-SLOTS | |
3753 | |
3754 @page | |
3755 @node with-foreign-slots, , translate-into-foreign-memory, Foreign Types | |
3756 @heading with-foreign-slots | |
3757 @subheading Syntax | |
3758 @Macro{with-foreign-slots (vars ptr type) &body body} | |
3759 | |
3760 @subheading Arguments and Values | |
3761 | |
3762 @table @var | |
3763 @item vars | |
3764 A list with each element a symbol, or list of length two with the | |
3765 first element @code{:pointer} and the second a symbol. | |
3766 | |
3767 @item ptr | |
3768 A foreign pointer to a structure. | |
3769 | |
3770 @item type | |
3771 A structure type. | |
3772 | |
3773 @item body | |
3774 A list of forms to be executed. | |
3775 @end table | |
3776 | |
3777 @subheading Description | |
3778 The @code{with-foreign-slots} macro creates local symbol macros for each | |
3779 var in @var{vars} to reference foreign slots in @var{ptr} of @var{type}. | |
3780 If the var is a list starting with @code{:pointer}, it will bind the | |
3781 pointer to the slot (rather than the value). It is similar to Common | |
3782 Lisp's @code{with-slots} macro. | |
3783 | |
3784 @subheading Examples | |
3785 @lisp | |
3786 (defcstruct tm | |
3787 (sec :int) | |
3788 (min :int) | |
3789 (hour :int) | |
3790 (mday :int) | |
3791 (mon :int) | |
3792 (year :int) | |
3793 (wday :int) | |
3794 (yday :int) | |
3795 (isdst :boolean) | |
3796 (zone :string) | |
3797 (gmtoff :long)) | |
3798 | |
3799 CFFI> (with-foreign-object (time :int) | |
3800 (setf (mem-ref time :int) | |
3801 (foreign-funcall "time" :pointer (null-pointer) :int)) | |
3802 (foreign-funcall "gmtime" :pointer time (:pointer (:struct tm)))) | |
3803 @result{} #<A Mac Pointer #x102A30> | |
3804 CFFI> (with-foreign-slots ((sec min hour mday mon year) * (:struct tm)) | |
3805 (format nil "~A:~A:~A, ~A/~A/~A" | |
3806 hour min sec (+ 1900 year) mon mday)) | |
3807 @result{} "7:22:47, 2005/8/2" | |
3808 @end lisp | |
3809 | |
3810 @subheading See Also | |
3811 @seealso{defcstruct} @* | |
3812 @seealso{defcunion} @* | |
3813 @seealso{foreign-slot-value} | |
3814 | |
3815 | |
3816 @c =================================================================== | |
3817 @c CHAPTER: Pointers | |
3818 | |
3819 @node Pointers, Strings, Foreign Types, Top | |
3820 @chapter Pointers | |
3821 | |
3822 All C data in @cffi{} is referenced through pointers. This includes | |
3823 defined C variables that hold immediate values, and integers. | |
3824 | |
3825 To see why this is, consider the case of the C integer. It is not | |
3826 only an arbitrary representation for an integer, congruent to Lisp's | |
3827 fixnums; the C integer has a specific bit pattern in memory defined by | |
3828 the C @acronym{ABI}. Lisp has no such constraint on its fixnums; | |
3829 therefore, it only makes sense to think of fixnums as C integers if | |
3830 you assume that @cffi{} converts them when necessary, such as when | |
3831 storing one for use in a C function call, or as the value of a C | |
3832 variable. This requires defining an area of memory@footnote{The | |
3833 definition of @dfn{memory} includes the @acronym{CPU} registers.}, | |
3834 represented through an effective address, and storing it there. | |
3835 | |
3836 Due to this compartmentalization, it only makes sense to manipulate | |
3837 raw C data in Lisp through pointers to it. For example, while there | |
3838 may be a Lisp representation of a @code{struct} that is converted to C | |
3839 at store time, you may only manipulate its raw data through a pointer. | |
3840 The C compiler does this also, albeit informally. | |
3841 | |
3842 @menu | |
3843 * Basic Pointer Operations:: | |
3844 * Allocating Foreign Memory:: | |
3845 * Accessing Foreign Memory:: | |
3846 | |
3847 Dictionary | |
3848 | |
3849 * foreign-free:: | |
3850 * foreign-alloc:: | |
3851 * foreign-symbol-pointer:: | |
3852 * inc-pointer:: | |
3853 * incf-pointer:: | |
3854 * make-pointer:: | |
3855 * mem-aptr:: | |
3856 * mem-aref:: | |
3857 * mem-ref:: | |
3858 * null-pointer:: | |
3859 * null-pointer-p:: | |
3860 * pointerp:: | |
3861 * pointer-address:: | |
3862 * pointer-eq:: | |
3863 * with-foreign-object:: | |
3864 * with-foreign-objects:: | |
3865 * with-foreign-pointer:: | |
3866 @end menu | |
3867 | |
3868 @node Basic Pointer Operations, Allocating Foreign Memory, Pointers, Poi… | |
3869 @section Basic Pointer Operations | |
3870 | |
3871 Manipulating pointers proper can be accomplished through most of the | |
3872 other operations defined in the Pointers dictionary, such as | |
3873 @code{make-pointer}, @code{pointer-address}, and @code{pointer-eq}. | |
3874 When using them, keep in mind that they merely manipulate the Lisp | |
3875 representation of pointers, not the values they point to. | |
3876 | |
3877 @deftp {Lisp Type} foreign-pointer | |
3878 The pointers' representations differ from implementation to | |
3879 implementation and have different types. @code{foreign-pointer} | |
3880 provides a portable type alias to each of these types. | |
3881 @end deftp | |
3882 | |
3883 | |
3884 @node Allocating Foreign Memory, Accessing Foreign Memory, Basic Pointer… | |
3885 @section Allocating Foreign Memory | |
3886 | |
3887 @cffi{} provides support for stack and heap C memory allocation. | |
3888 Stack allocation, done with @code{with-foreign-object}, is sometimes | |
3889 called ``dynamic'' allocation in Lisp, because memory allocated as | |
3890 such has dynamic extent, much as with @code{let} bindings of special | |
3891 variables. | |
3892 | |
3893 This should not be confused with what C calls ``dynamic'' allocation, | |
3894 or that done with @code{malloc} and friends. This sort of heap | |
3895 allocation is done with @code{foreign-alloc}, creating objects that | |
3896 exist until freed with @code{foreign-free}. | |
3897 | |
3898 | |
3899 @node Accessing Foreign Memory, foreign-free, Allocating Foreign Memory,… | |
3900 @section Accessing Foreign Memory | |
3901 | |
3902 When manipulating raw C data, consider that all pointers are pointing | |
3903 to an array. When you only want one C value, such as a single | |
3904 @code{struct}, this array only has one such value. It is worthwhile | |
3905 to remember that everything is an array, though, because this is also | |
3906 the semantic that C imposes natively. | |
3907 | |
3908 C values are accessed as the @code{setf}-able places defined by | |
3909 @code{mem-aref} and @code{mem-ref}. Given a pointer and a @cffi{} | |
3910 type (@pxref{Foreign Types}), either of these will dereference the | |
3911 pointer, translate the C data there back to Lisp, and return the | |
3912 result of said translation, performing the reverse operation when | |
3913 @code{setf}-ing. To decide which one to use, consider whether you | |
3914 would use the array index operator @code{[@var{n}]} or the pointer | |
3915 dereference @code{*} in C; use @code{mem-aref} for array indexing and | |
3916 @code{mem-ref} for pointer dereferencing. | |
3917 | |
3918 | |
3919 @c =================================================================== | |
3920 @c FOREIGN-FREE | |
3921 | |
3922 @page | |
3923 @node foreign-free, foreign-alloc, Accessing Foreign Memory, Pointers | |
3924 @heading foreign-free | |
3925 @subheading Syntax | |
3926 @Function{foreign-free ptr @res{} undefined} | |
3927 | |
3928 @subheading Arguments and Values | |
3929 | |
3930 @table @var | |
3931 @item ptr | |
3932 A foreign pointer. | |
3933 @end table | |
3934 | |
3935 @subheading Description | |
3936 The @code{foreign-free} function frees a @code{ptr} previously | |
3937 allocated by @code{foreign-alloc}. The consequences of freeing a given | |
3938 pointer twice are undefined. | |
3939 | |
3940 @subheading Examples | |
3941 | |
3942 @lisp | |
3943 CFFI> (foreign-alloc :int) | |
3944 @result{} #<A Mac Pointer #x1022E0> | |
3945 CFFI> (foreign-free *) | |
3946 @result{} NIL | |
3947 @end lisp | |
3948 | |
3949 @subheading See Also | |
3950 @seealso{foreign-alloc} @* | |
3951 @seealso{with-foreign-pointer} | |
3952 | |
3953 | |
3954 @c =================================================================== | |
3955 @c FOREIGN-ALLOC | |
3956 | |
3957 @page | |
3958 @node foreign-alloc, foreign-symbol-pointer, foreign-free, Pointers | |
3959 @heading foreign-alloc | |
3960 @subheading Syntax | |
3961 @Function{foreign-alloc type &key initial-element initial-contents (coun… | |
3962 null-terminated-p @res{} pointer} | |
3963 | |
3964 @subheading Arguments and Values | |
3965 | |
3966 @table @var | |
3967 @item type | |
3968 A foreign type. | |
3969 | |
3970 @item initial-element | |
3971 A Lisp object. | |
3972 | |
3973 @item initial-contents | |
3974 A sequence. | |
3975 | |
3976 @item count | |
3977 An integer. Defaults to 1 or the length of @var{initial-contents} if | |
3978 supplied. | |
3979 | |
3980 @item null-terminated-p | |
3981 A boolean, false by default. | |
3982 | |
3983 @item pointer | |
3984 A foreign pointer to the newly allocated memory. | |
3985 @end table | |
3986 | |
3987 @subheading Description | |
3988 The @code{foreign-alloc} function allocates enough memory to hold | |
3989 @var{count} objects of type @var{type} and returns a | |
3990 @var{pointer}. This memory must be explicitly freed using | |
3991 @code{foreign-free} once it is no longer needed. | |
3992 | |
3993 If @var{initial-element} is supplied, it is used to initialize the | |
3994 @var{count} objects the newly allocated memory holds. | |
3995 | |
3996 If an @var{initial-contents} sequence is supplied, it must have a | |
3997 length less than or equal to @var{count} and each of its elements | |
3998 will be used to initialize the contents of the newly allocated | |
3999 memory. | |
4000 | |
4001 If @var{count} is omitted and @var{initial-contents} is specified, it | |
4002 will default to @code{(length @var{initial-contents})}. | |
4003 | |
4004 @var{initial-element} and @var{initial-contents} are mutually | |
4005 exclusive. | |
4006 | |
4007 When @var{null-terminated-p} is true, | |
4008 @code{(1+ (max @var{count} (length @var{initial-contents})))} elements | |
4009 are allocated and the last one is set to @code{NULL}. Note that in | |
4010 this case @var{type} must be a pointer type (ie. a type that | |
4011 canonicalizes to @code{:pointer}), otherwise an error is signaled. | |
4012 | |
4013 @subheading Examples | |
4014 @lisp | |
4015 CFFI> (foreign-alloc :char) | |
4016 @result{} #<A Mac Pointer #x102D80> ; @lispcmt{A pointer to 1 byte o… | |
4017 | |
4018 CFFI> (foreign-alloc :char :count 20) | |
4019 @result{} #<A Mac Pointer #x1024A0> ; @lispcmt{A pointer to 20 bytes… | |
4020 | |
4021 CFFI> (foreign-alloc :int :initial-element 12) | |
4022 @result{} #<A Mac Pointer #x1028B0> | |
4023 CFFI> (mem-ref * :int) | |
4024 @result{} 12 | |
4025 | |
4026 CFFI> (foreign-alloc :int :initial-contents '(1 2 3)) | |
4027 @result{} #<A Mac Pointer #x102950> | |
4028 CFFI> (loop for i from 0 below 3 | |
4029 collect (mem-aref * :int i)) | |
4030 @result{} (1 2 3) | |
4031 | |
4032 CFFI> (foreign-alloc :int :initial-contents #(1 2 3)) | |
4033 @result{} #<A Mac Pointer #x102960> | |
4034 CFFI> (loop for i from 0 below 3 | |
4035 collect (mem-aref * :int i)) | |
4036 @result{} (1 2 3) | |
4037 | |
4038 ;;; @lispcmt{Allocate a char** pointer that points to newly allocated me… | |
4039 ;;; @lispcmt{by the :string type translator for the string "foo".} | |
4040 CFFI> (foreign-alloc :string :initial-element "foo") | |
4041 @result{} #<A Mac Pointer #x102C40> | |
4042 @end lisp | |
4043 | |
4044 @lisp | |
4045 ;;; @lispcmt{Allocate a null-terminated array of strings.} | |
4046 ;;; @lispcmt{(Note: FOREIGN-STRING-TO-LISP returns NIL when passed a nul… | |
4047 CFFI> (foreign-alloc :string | |
4048 :initial-contents '("foo" "bar" "baz") | |
4049 :null-terminated-p t) | |
4050 @result{} #<A Mac Pointer #x102D20> | |
4051 CFFI> (loop for i from 0 below 4 | |
4052 collect (mem-aref * :string i)) | |
4053 @result{} ("foo" "bar" "baz" NIL) | |
4054 CFFI> (progn | |
4055 (dotimes (i 3) | |
4056 (foreign-free (mem-aref ** :pointer i))) | |
4057 (foreign-free **)) | |
4058 @result{} nil | |
4059 @end lisp | |
4060 | |
4061 @subheading See Also | |
4062 @seealso{foreign-free} @* | |
4063 @seealso{with-foreign-object} @* | |
4064 @seealso{with-foreign-pointer} | |
4065 | |
4066 | |
4067 @c =================================================================== | |
4068 @c FOREIGN-SYMBOL-POINTER | |
4069 | |
4070 @page | |
4071 @node foreign-symbol-pointer, inc-pointer, foreign-alloc, Pointers | |
4072 @heading foreign-symbol-pointer | |
4073 @subheading Syntax | |
4074 @Function{foreign-symbol-pointer foreign-name &key library @res{} pointe… | |
4075 | |
4076 @subheading Arguments and Values | |
4077 | |
4078 @table @var | |
4079 @item foreign-name | |
4080 A string. | |
4081 | |
4082 @item pointer | |
4083 A foreign pointer, or @code{nil}. | |
4084 | |
4085 @item library | |
4086 A Lisp symbol or an instance of @code{foreign-library}. | |
4087 @end table | |
4088 | |
4089 @subheading Description | |
4090 The function @code{foreign-symbol-pointer} will return a foreign | |
4091 pointer corresponding to the foreign symbol denoted by the string | |
4092 @var{foreign-name}. If a foreign symbol named @var{foreign-name} | |
4093 doesn't exist, @code{nil} is returned. | |
4094 | |
4095 ABI name manglings will be performed on @var{foreign-name} by | |
4096 @code{foreign-symbol-pointer} if necessary. (eg: adding a leading | |
4097 underscore on darwin/ppc) | |
4098 | |
4099 @var{library} should name a foreign library as defined by | |
4100 @code{define-foreign-library}, @code{:default} (which is the default) | |
4101 or an instance of @code{foreign-library} as returned by | |
4102 @code{load-foreign-library}. | |
4103 | |
4104 @strong{Important note:} do not keep these pointers across saved Lisp | |
4105 cores as the foreign-library may move across sessions. | |
4106 | |
4107 @subheading Examples | |
4108 | |
4109 @lisp | |
4110 CFFI> (foreign-symbol-pointer "errno") | |
4111 @result{} #<A Mac Pointer #xA0008130> | |
4112 CFFI> (foreign-symbol-pointer "strerror") | |
4113 @result{} #<A Mac Pointer #x9002D0F8> | |
4114 CFFI> (foreign-funcall-pointer * () :int (mem-ref ** :int) :string) | |
4115 @result{} "No such file or directory" | |
4116 | |
4117 CFFI> (foreign-symbol-pointer "inexistent symbol") | |
4118 @result{} NIL | |
4119 @end lisp | |
4120 | |
4121 @subheading See Also | |
4122 @seealso{defcvar} | |
4123 | |
4124 | |
4125 @c =================================================================== | |
4126 @c INC-POINTER | |
4127 | |
4128 @page | |
4129 @node inc-pointer, incf-pointer, foreign-symbol-pointer, Pointers | |
4130 @heading inc-pointer | |
4131 @subheading Syntax | |
4132 @Function{inc-pointer pointer offset @res{} new-pointer} | |
4133 | |
4134 @subheading Arguments and Values | |
4135 | |
4136 @table @var | |
4137 @item pointer | |
4138 @itemx new-pointer | |
4139 A foreign pointer. | |
4140 | |
4141 @item offset | |
4142 An integer. | |
4143 @end table | |
4144 | |
4145 @subheading Description | |
4146 The function @code{inc-pointer} will return a @var{new-pointer} pointing | |
4147 @var{offset} bytes past @var{pointer}. | |
4148 | |
4149 @subheading Examples | |
4150 | |
4151 @lisp | |
4152 CFFI> (foreign-string-alloc "Common Lisp") | |
4153 @result{} #<A Mac Pointer #x102EA0> | |
4154 CFFI> (inc-pointer * 7) | |
4155 @result{} #<A Mac Pointer #x102EA7> | |
4156 CFFI> (foreign-string-to-lisp *) | |
4157 @result{} "Lisp" | |
4158 @end lisp | |
4159 | |
4160 @subheading See Also | |
4161 @seealso{incf-pointer} @* | |
4162 @seealso{make-pointer} @* | |
4163 @seealso{pointerp} @* | |
4164 @seealso{null-pointer} @* | |
4165 @seealso{null-pointer-p} | |
4166 | |
4167 | |
4168 @c =================================================================== | |
4169 @c INCF-POINTER | |
4170 | |
4171 @page | |
4172 @node incf-pointer, make-pointer, inc-pointer, Pointers | |
4173 @heading incf-pointer | |
4174 @subheading Syntax | |
4175 @Macro{incf-pointer place &optional (offset 1) @res{} new-pointer} | |
4176 | |
4177 @subheading Arguments and Values | |
4178 | |
4179 @table @var | |
4180 @item place | |
4181 A @code{setf} place. | |
4182 | |
4183 @item new-pointer | |
4184 A foreign pointer. | |
4185 | |
4186 @item offset | |
4187 An integer. | |
4188 @end table | |
4189 | |
4190 @subheading Description | |
4191 The @code{incf-pointer} macro takes the foreign pointer from | |
4192 @var{place} and creates a @var{new-pointer} incremented by | |
4193 @var{offset} bytes and which is stored in @var{place}. | |
4194 | |
4195 @subheading Examples | |
4196 | |
4197 @lisp | |
4198 CFFI> (defparameter *two-words* (foreign-string-alloc "Common Lisp")) | |
4199 @result{} *TWO-WORDS* | |
4200 CFFI> (defparameter *one-word* *two-words*) | |
4201 @result{} *ONE-WORD* | |
4202 CFFI> (incf-pointer *one-word* 7) | |
4203 @result{} #.(SB-SYS:INT-SAP #X00600457) | |
4204 CFFI> (foreign-string-to-lisp *one-word*) | |
4205 @result{} "Lisp" | |
4206 CFFI> (foreign-string-to-lisp *two-words*) | |
4207 @result{} "Common Lisp" | |
4208 @end lisp | |
4209 | |
4210 @subheading See Also | |
4211 @seealso{inc-pointer} @* | |
4212 @seealso{make-pointer} @* | |
4213 @seealso{pointerp} @* | |
4214 @seealso{null-pointer} @* | |
4215 @seealso{null-pointer-p} | |
4216 | |
4217 | |
4218 @c =================================================================== | |
4219 @c MAKE-POINTER | |
4220 | |
4221 @page | |
4222 @node make-pointer, mem-aptr, incf-pointer, Pointers | |
4223 @heading make-pointer | |
4224 @subheading Syntax | |
4225 @Function{make-pointer address @res{} ptr} | |
4226 | |
4227 @subheading Arguments and Values | |
4228 | |
4229 @table @var | |
4230 @item address | |
4231 An integer. | |
4232 | |
4233 @item ptr | |
4234 A foreign pointer. | |
4235 @end table | |
4236 | |
4237 @subheading Description | |
4238 The function @code{make-pointer} will return a foreign pointer | |
4239 pointing to @var{address}. | |
4240 | |
4241 @subheading Examples | |
4242 | |
4243 @lisp | |
4244 CFFI> (make-pointer 42) | |
4245 @result{} #<FOREIGN-ADDRESS #x0000002A> | |
4246 CFFI> (pointerp *) | |
4247 @result{} T | |
4248 CFFI> (pointer-address **) | |
4249 @result{} 42 | |
4250 CFFI> (inc-pointer *** -42) | |
4251 @result{} #<FOREIGN-ADDRESS #x00000000> | |
4252 CFFI> (null-pointer-p *) | |
4253 @result{} T | |
4254 CFFI> (typep ** 'foreign-pointer) | |
4255 @result{} T | |
4256 @end lisp | |
4257 | |
4258 @subheading See Also | |
4259 @seealso{inc-pointer} @* | |
4260 @seealso{null-pointer} @* | |
4261 @seealso{null-pointer-p} @* | |
4262 @seealso{pointerp} @* | |
4263 @seealso{pointer-address} @* | |
4264 @seealso{pointer-eq} @* | |
4265 @seealso{mem-ref} | |
4266 | |
4267 | |
4268 @c =================================================================== | |
4269 @c MEM-APTR | |
4270 | |
4271 @page | |
4272 @node mem-aptr, mem-aref, make-pointer, Pointers | |
4273 @heading mem-aptr | |
4274 @subheading Syntax | |
4275 @Accessor{mem-aptr ptr type &optional (index 0)} | |
4276 | |
4277 @subheading Arguments and Values | |
4278 | |
4279 @table @var | |
4280 @item ptr | |
4281 A foreign pointer. | |
4282 | |
4283 @item type | |
4284 A foreign type. | |
4285 | |
4286 @item index | |
4287 An integer. | |
4288 | |
4289 @item new-value | |
4290 A Lisp value compatible with @var{type}. | |
4291 @end table | |
4292 | |
4293 @subheading Description | |
4294 The @code{mem-aptr} function finds the pointer to an element of the arra… | |
4295 | |
4296 @lisp | |
4297 (mem-aptr ptr type n) | |
4298 | |
4299 ;; @lispcmt{is identical to:} | |
4300 | |
4301 (inc-pointer ptr (* n (foreign-type-size type))) | |
4302 @end lisp | |
4303 | |
4304 @subheading Examples | |
4305 | |
4306 @lisp | |
4307 CFFI> (with-foreign-string (str "Hello, foreign world!") | |
4308 (mem-aptr str :char 6)) | |
4309 @result{} #.(SB-SYS:INT-SAP #X0063D4B6) | |
4310 @end lisp | |
4311 | |
4312 @c =================================================================== | |
4313 @c MEM-AREF | |
4314 | |
4315 @page | |
4316 @node mem-aref, mem-ref, mem-aptr, Pointers | |
4317 @heading mem-aref | |
4318 @subheading Syntax | |
4319 @Accessor{mem-aref ptr type &optional (index 0)} | |
4320 | |
4321 (setf (@strong{mem-aref} @emph{ptr type &optional (index 0)) new-value}) | |
4322 | |
4323 @subheading Arguments and Values | |
4324 | |
4325 @table @var | |
4326 @item ptr | |
4327 A foreign pointer. | |
4328 | |
4329 @item type | |
4330 A foreign type. | |
4331 | |
4332 @item index | |
4333 An integer. | |
4334 | |
4335 @item new-value | |
4336 A Lisp value compatible with @var{type}. | |
4337 @end table | |
4338 | |
4339 @subheading Description | |
4340 The @code{mem-aref} function is similar to @code{mem-ref} but will | |
4341 automatically calculate the offset from an @var{index}. | |
4342 | |
4343 @lisp | |
4344 (mem-aref ptr type n) | |
4345 | |
4346 ;; @lispcmt{is identical to:} | |
4347 | |
4348 (mem-ref ptr type (* n (foreign-type-size type))) | |
4349 @end lisp | |
4350 | |
4351 @subheading Examples | |
4352 | |
4353 @lisp | |
4354 CFFI> (with-foreign-string (str "Hello, foreign world!") | |
4355 (mem-aref str :char 6)) | |
4356 @result{} 32 | |
4357 CFFI> (code-char *) | |
4358 @result{} #\Space | |
4359 | |
4360 CFFI> (with-foreign-object (array :int 10) | |
4361 (loop for i below 10 | |
4362 do (setf (mem-aref array :int i) (random 100))) | |
4363 (loop for i below 10 collect (mem-aref array :int i))) | |
4364 @result{} (22 7 22 52 69 1 46 93 90 65) | |
4365 @end lisp | |
4366 | |
4367 @subheading Compatibility Note | |
4368 | |
4369 For compatibility with older versions of CFFI, @ref{mem-aref} will | |
4370 produce a pointer for the deprecated bare structure specification, but | |
4371 it is consistent with other types for the current specification form | |
4372 @code{(:struct @var{structure-name})} and provides a Lisp object | |
4373 translated from the structure (by default a plist). In order to obtain | |
4374 the pointer, you should use the new function @ref{mem-aptr}. | |
4375 | |
4376 @subheading See Also | |
4377 @seealso{mem-ref} @* | |
4378 @seealso{mem-aptr} | |
4379 | |
4380 @c =================================================================== | |
4381 @c MEM-REF | |
4382 | |
4383 @page | |
4384 @node mem-ref, null-pointer, mem-aref, Pointers | |
4385 @heading mem-ref | |
4386 @subheading Syntax | |
4387 @Accessor{mem-ref ptr type &optional offset @res{} object} | |
4388 | |
4389 @subheading Arguments and Values | |
4390 | |
4391 @table @var | |
4392 @item ptr | |
4393 A pointer. | |
4394 | |
4395 @item type | |
4396 A foreign type. | |
4397 | |
4398 @item offset | |
4399 An integer (in byte units). | |
4400 | |
4401 @item object | |
4402 The value @var{ptr} points to. | |
4403 @end table | |
4404 | |
4405 @subheading Description | |
4406 @subheading Examples | |
4407 | |
4408 @lisp | |
4409 CFFI> (with-foreign-string (ptr "Saluton") | |
4410 (setf (mem-ref ptr :char 3) (char-code #\a)) | |
4411 (loop for i from 0 below 8 | |
4412 collect (code-char (mem-ref ptr :char i)))) | |
4413 @result{} (#\S #\a #\l #\a #\t #\o #\n #\Null) | |
4414 CFFI> (setq ptr-to-int (foreign-alloc :int)) | |
4415 @result{} #<A Mac Pointer #x1047D0> | |
4416 CFFI> (mem-ref ptr-to-int :int) | |
4417 @result{} 1054619 | |
4418 CFFI> (setf (mem-ref ptr-to-int :int) 1984) | |
4419 @result{} 1984 | |
4420 CFFI> (mem-ref ptr-to-int :int) | |
4421 @result{} 1984 | |
4422 @end lisp | |
4423 | |
4424 @subheading See Also | |
4425 @seealso{mem-aref} | |
4426 | |
4427 | |
4428 @c =================================================================== | |
4429 @c NULL-POINTER | |
4430 | |
4431 @page | |
4432 @node null-pointer, null-pointer-p, mem-ref, Pointers | |
4433 @heading null-pointer | |
4434 @subheading Syntax | |
4435 @Function{null-pointer @res{} pointer} | |
4436 | |
4437 @subheading Arguments and Values | |
4438 | |
4439 @table @var | |
4440 @item pointer | |
4441 A @code{NULL} pointer. | |
4442 @end table | |
4443 | |
4444 @subheading Description | |
4445 The function @code{null-pointer} returns a null pointer. | |
4446 | |
4447 @subheading Examples | |
4448 | |
4449 @lisp | |
4450 CFFI> (null-pointer) | |
4451 @result{} #<A Null Mac Pointer> | |
4452 CFFI> (pointerp *) | |
4453 @result{} T | |
4454 @end lisp | |
4455 | |
4456 @subheading See Also | |
4457 @seealso{null-pointer-p} @* | |
4458 @seealso{make-pointer} | |
4459 | |
4460 | |
4461 @c =================================================================== | |
4462 @c NULL-POINTER-P | |
4463 | |
4464 @page | |
4465 @node null-pointer-p, pointerp, null-pointer, Pointers | |
4466 @heading null-pointer-p | |
4467 @subheading Syntax | |
4468 @Function{null-pointer-p ptr @res{} boolean} | |
4469 | |
4470 @subheading Arguments and Values | |
4471 | |
4472 @table @var | |
4473 @item ptr | |
4474 A foreign pointer that may be a null pointer. | |
4475 | |
4476 @item boolean | |
4477 @code{T} or @code{NIL}. | |
4478 @end table | |
4479 | |
4480 @subheading Description | |
4481 The function @code{null-pointer-p} returns true if @var{ptr} is a null | |
4482 pointer and false otherwise. | |
4483 | |
4484 @subheading Examples | |
4485 | |
4486 @lisp | |
4487 CFFI> (null-pointer-p (null-pointer)) | |
4488 @result{} T | |
4489 @end lisp | |
4490 | |
4491 @lisp | |
4492 (defun contains-str-p (big little) | |
4493 (not (null-pointer-p | |
4494 (foreign-funcall "strstr" :string big :string little :pointer)))) | |
4495 | |
4496 CFFI> (contains-str-p "Popcorns" "corn") | |
4497 @result{} T | |
4498 CFFI> (contains-str-p "Popcorns" "salt") | |
4499 @result{} NIL | |
4500 @end lisp | |
4501 | |
4502 @subheading See Also | |
4503 @seealso{null-pointer} @* | |
4504 @seealso{pointerp} | |
4505 | |
4506 | |
4507 @c =================================================================== | |
4508 @c POINTERP | |
4509 | |
4510 @page | |
4511 @node pointerp, pointer-address, null-pointer-p, Pointers | |
4512 @heading pointerp | |
4513 @subheading Syntax | |
4514 @Function{pointerp ptr @res{} boolean} | |
4515 | |
4516 @subheading Arguments and Values | |
4517 | |
4518 @table @var | |
4519 @item ptr | |
4520 An object that may be a foreign pointer. | |
4521 | |
4522 @item boolean | |
4523 @code{T} or @code{NIL}. | |
4524 @end table | |
4525 | |
4526 @subheading Description | |
4527 The function @code{pointerp} returns true if @var{ptr} is a foreign | |
4528 pointer and false otherwise. | |
4529 | |
4530 @subheading Implementation-specific Notes | |
4531 In Allegro CL, foreign pointers are integers thus in this | |
4532 implementation @code{pointerp} will return true for any ordinary integer. | |
4533 | |
4534 @subheading Examples | |
4535 | |
4536 @lisp | |
4537 CFFI> (foreign-alloc 32) | |
4538 @result{} #<A Mac Pointer #x102D20> | |
4539 CFFI> (pointerp *) | |
4540 @result{} T | |
4541 CFFI> (pointerp "this is not a pointer") | |
4542 @result{} NIL | |
4543 @end lisp | |
4544 | |
4545 @subheading See Also | |
4546 @seealso{make-pointer} | |
4547 @seealso{null-pointer-p} | |
4548 | |
4549 | |
4550 @c =================================================================== | |
4551 @c POINTER-ADDRESS | |
4552 | |
4553 @page | |
4554 @node pointer-address, pointer-eq, pointerp, Pointers | |
4555 @heading pointer-address | |
4556 @subheading Syntax | |
4557 @Function{pointer-address ptr @res{} address} | |
4558 | |
4559 @subheading Arguments and Values | |
4560 | |
4561 @table @var | |
4562 @item ptr | |
4563 A foreign pointer. | |
4564 | |
4565 @item address | |
4566 An integer. | |
4567 @end table | |
4568 | |
4569 @subheading Description | |
4570 The function @code{pointer-address} will return the @var{address} of | |
4571 a foreign pointer @var{ptr}. | |
4572 | |
4573 @subheading Examples | |
4574 | |
4575 @lisp | |
4576 CFFI> (pointer-address (null-pointer)) | |
4577 @result{} 0 | |
4578 CFFI> (pointer-address (make-pointer 123)) | |
4579 @result{} 123 | |
4580 @end lisp | |
4581 | |
4582 @subheading See Also | |
4583 @seealso{make-pointer} @* | |
4584 @seealso{inc-pointer} @* | |
4585 @seealso{null-pointer} @* | |
4586 @seealso{null-pointer-p} @* | |
4587 @seealso{pointerp} @* | |
4588 @seealso{pointer-eq} @* | |
4589 @seealso{mem-ref} | |
4590 | |
4591 | |
4592 @c =================================================================== | |
4593 @c POINTER-EQ | |
4594 | |
4595 @page | |
4596 @node pointer-eq, with-foreign-object, pointer-address, Pointers | |
4597 @heading pointer-eq | |
4598 @subheading Syntax | |
4599 @Function{pointer-eq ptr1 ptr2 @res{} boolean} | |
4600 | |
4601 @subheading Arguments and Values | |
4602 | |
4603 @table @var | |
4604 @item ptr1 | |
4605 @itemx ptr2 | |
4606 A foreign pointer. | |
4607 | |
4608 @item boolean | |
4609 @code{T} or @code{NIL}. | |
4610 @end table | |
4611 | |
4612 @subheading Description | |
4613 The function @code{pointer-eq} returns true if @var{ptr1} and | |
4614 @var{ptr2} point to the same memory address and false otherwise. | |
4615 | |
4616 @subheading Implementation-specific Notes | |
4617 The representation of foreign pointers varies across the various Lisp | |
4618 implementations as does the behaviour of the built-in Common Lisp | |
4619 equality predicates. Comparing two pointers that point to the same | |
4620 address with @code{EQ} Lisps will return true on some Lisps, others requ… | |
4621 more general predicates like @code{EQL} or @code{EQUALP} and finally | |
4622 some will return false using any of these predicates. Therefore, for | |
4623 portability, you should use @code{POINTER-EQ}. | |
4624 | |
4625 @subheading Examples | |
4626 This is an example using @acronym{SBCL}, see the | |
4627 implementation-specific notes above. | |
4628 | |
4629 @lisp | |
4630 CFFI> (eql (null-pointer) (null-pointer)) | |
4631 @result{} NIL | |
4632 CFFI> (pointer-eq (null-pointer) (null-pointer)) | |
4633 @result{} T | |
4634 @end lisp | |
4635 | |
4636 @subheading See Also | |
4637 @seealso{inc-pointer} | |
4638 | |
4639 | |
4640 @c =================================================================== | |
4641 @c WITH-FOREIGN-OBJECT | |
4642 | |
4643 @page | |
4644 @node with-foreign-object, with-foreign-pointer, pointer-eq, Pointers | |
4645 @heading with-foreign-object, with-foreign-objects | |
4646 @subheading Syntax | |
4647 @Macro{with-foreign-object (var type &optional count) &body body} | |
4648 | |
4649 @anchor{with-foreign-objects} | |
4650 @Macro{with-foreign-objects (bindings) &body body} | |
4651 | |
4652 bindings ::= @{(var type &optional count)@}* | |
4653 | |
4654 @subheading Arguments and Values | |
4655 | |
4656 @table @var | |
4657 @item var | |
4658 A symbol. | |
4659 | |
4660 @item type | |
4661 A foreign type, evaluated. | |
4662 | |
4663 @item count | |
4664 An integer. | |
4665 @end table | |
4666 | |
4667 @subheading Description | |
4668 The macros @code{with-foreign-object} and @code{with-foreign-objects} | |
4669 bind @var{var} to a pointer to @var{count} newly allocated objects | |
4670 of type @var{type} during @var{body}. The buffer has dynamic extent | |
4671 and may be stack allocated if supported by the host Lisp. | |
4672 | |
4673 @subheading Examples | |
4674 | |
4675 @lisp | |
4676 CFFI> (with-foreign-object (array :int 10) | |
4677 (dotimes (i 10) | |
4678 (setf (mem-aref array :int i) (random 100))) | |
4679 (loop for i below 10 | |
4680 collect (mem-aref array :int i))) | |
4681 @result{} (22 7 22 52 69 1 46 93 90 65) | |
4682 @end lisp | |
4683 | |
4684 @subheading See Also | |
4685 @seealso{foreign-alloc} | |
4686 | |
4687 | |
4688 @c =================================================================== | |
4689 @c WITH-FOREIGN-POINTER | |
4690 | |
4691 @page | |
4692 @node with-foreign-pointer, , with-foreign-object, Pointers | |
4693 @heading with-foreign-pointer | |
4694 @subheading Syntax | |
4695 @Macro{with-foreign-pointer (var size &optional size-var) &body body} | |
4696 | |
4697 @subheading Arguments and Values | |
4698 | |
4699 @table @var | |
4700 @item var | |
4701 @itemx size-var | |
4702 A symbol. | |
4703 | |
4704 @item size | |
4705 An integer. | |
4706 | |
4707 @item body | |
4708 A list of forms to be executed. | |
4709 @end table | |
4710 | |
4711 @subheading Description | |
4712 The @code{with-foreign-pointer} macro, binds @var{var} to @var{size} | |
4713 bytes of foreign memory during @var{body}. The pointer in @var{var} | |
4714 is invalid beyond the dynamic extend of @var{body} and may be | |
4715 stack-allocated if supported by the implementation. | |
4716 | |
4717 If @var{size-var} is supplied, it will be bound to @var{size} during | |
4718 @var{body}. | |
4719 | |
4720 @subheading Examples | |
4721 | |
4722 @lisp | |
4723 CFFI> (with-foreign-pointer (string 4 size) | |
4724 (setf (mem-ref string :char (1- size)) 0) | |
4725 (lisp-string-to-foreign "Popcorns" string size) | |
4726 (loop for i from 0 below size | |
4727 collect (code-char (mem-ref string :char i)))) | |
4728 @result{} (#\P #\o #\p #\Null) | |
4729 @end lisp | |
4730 | |
4731 @subheading See Also | |
4732 @seealso{foreign-alloc} @* | |
4733 @seealso{foreign-free} | |
4734 | |
4735 | |
4736 @c =================================================================== | |
4737 @c CHAPTER: Strings | |
4738 | |
4739 @node Strings, Variables, Pointers, Top | |
4740 @chapter Strings | |
4741 | |
4742 As with many languages, Lisp and C have special support for logical | |
4743 arrays of characters, going so far as to give them a special name, | |
4744 ``strings''. In that spirit, @cffi{} provides special support for | |
4745 translating between Lisp and C strings. | |
4746 | |
4747 The @code{:string} type and the symbols related below also serve as an | |
4748 example of what you can do portably with @cffi{}; were it not | |
4749 included, you could write an equally functional @file{strings.lisp} | |
4750 without referring to any implementation-specific symbols. | |
4751 | |
4752 @menu | |
4753 Dictionary | |
4754 | |
4755 * *default-foreign-encoding*:: | |
4756 * foreign-string-alloc:: | |
4757 * foreign-string-free:: | |
4758 * foreign-string-to-lisp:: | |
4759 * lisp-string-to-foreign:: | |
4760 * with-foreign-string:: | |
4761 * with-foreign-strings:: | |
4762 * with-foreign-pointer-as-string:: | |
4763 @end menu | |
4764 | |
4765 | |
4766 @c =================================================================== | |
4767 @c *DEFAULT-FOREIGN-ENCODING* | |
4768 | |
4769 @page | |
4770 @node *default-foreign-encoding*, foreign-string-alloc, Strings, Strings | |
4771 @heading *default-foreign-encoding* | |
4772 @subheading Syntax | |
4773 | |
4774 @Variable{*default-foreign-encoding*} | |
4775 | |
4776 @subheading Value type | |
4777 | |
4778 A keyword. | |
4779 | |
4780 @subheading Initial value | |
4781 | |
4782 @code{:utf-8} | |
4783 | |
4784 @subheading Description | |
4785 | |
4786 This special variable holds the default foreign encoding. | |
4787 | |
4788 @subheading Examples | |
4789 | |
4790 @lisp | |
4791 CFFI> *default-foreign-encoding* | |
4792 :utf-8 | |
4793 CFFI> (foreign-funcall "strdup" (:string :encoding :utf-16) "foo" :strin… | |
4794 "f" | |
4795 CFFI> (let ((*default-foreign-encoding* :utf-16)) | |
4796 (foreign-funcall "strdup" (:string :encoding :utf-16) "foo" :str… | |
4797 "foo" | |
4798 @end lisp | |
4799 | |
4800 @subheading See also | |
4801 | |
4802 @seealso{Other Types} (@code{:string} type) @* | |
4803 @seealso{foreign-string-alloc} @* | |
4804 @seealso{foreign-string-to-lisp} @* | |
4805 @seealso{lisp-string-to-foreign} @* | |
4806 @seealso{with-foreign-string} @* | |
4807 @seealso{with-foreign-pointer-as-string} | |
4808 | |
4809 | |
4810 @c =================================================================== | |
4811 @c FOREIGN-STRING-ALLOC | |
4812 | |
4813 @page | |
4814 @node foreign-string-alloc, foreign-string-free, *default-foreign-encodi… | |
4815 @heading foreign-string-alloc | |
4816 @subheading Syntax | |
4817 @Function{foreign-string-alloc string &key encoding null-terminated-p @ | |
4818 start end @res{} pointer} | |
4819 | |
4820 @subheading Arguments and Values | |
4821 | |
4822 @table @emph | |
4823 @item @var{string} | |
4824 A Lisp string. | |
4825 | |
4826 @item @var{encoding} | |
4827 Foreign encoding. Defaults to @code{*default-foreign-encoding*}. | |
4828 | |
4829 @item @var{null-terminated-p} | |
4830 Boolean, defaults to true. | |
4831 | |
4832 @item @var{start}, @var{end} | |
4833 Bounding index designators of @var{string}. 0 and @code{nil}, by | |
4834 default. | |
4835 | |
4836 @item @var{pointer} | |
4837 A pointer to the newly allocated foreign string. | |
4838 @end table | |
4839 | |
4840 @subheading Description | |
4841 The @code{foreign-string-alloc} function allocates foreign memory | |
4842 holding a copy of @var{string} converted using the specified | |
4843 @var{encoding}. @var{Start} specifies an offset into @var{string} and | |
4844 @var{end} marks the position following the last element of the foreign | |
4845 string. | |
4846 | |
4847 This string must be freed with @code{foreign-string-free}. | |
4848 | |
4849 If @var{null-terminated-p} is false, the string will not be | |
4850 null-terminated. | |
4851 | |
4852 @subheading Examples | |
4853 | |
4854 @lisp | |
4855 CFFI> (defparameter *str* (foreign-string-alloc "Hello, foreign world!")) | |
4856 @result{} #<FOREIGN-ADDRESS #x00400560> | |
4857 CFFI> (foreign-funcall "strlen" :pointer *str* :int) | |
4858 @result{} 21 | |
4859 @end lisp | |
4860 | |
4861 @subheading See Also | |
4862 @seealso{foreign-string-free} @* | |
4863 @seealso{with-foreign-string} | |
4864 @c @seealso{:string} | |
4865 | |
4866 | |
4867 @c =================================================================== | |
4868 @c FOREIGN-STRING-FREE | |
4869 | |
4870 @page | |
4871 @node foreign-string-free, foreign-string-to-lisp, foreign-string-alloc,… | |
4872 @heading foreign-string-free | |
4873 @subheading Syntax | |
4874 @Function{foreign-string-free pointer} | |
4875 | |
4876 @subheading Arguments and Values | |
4877 | |
4878 @table @var | |
4879 @item pointer | |
4880 A pointer to a string allocated by @code{foreign-string-alloc}. | |
4881 @end table | |
4882 | |
4883 @subheading Description | |
4884 The @code{foreign-string-free} function frees a foreign string | |
4885 allocated by @code{foreign-string-alloc}. | |
4886 | |
4887 @subheading Examples | |
4888 | |
4889 @subheading See Also | |
4890 @seealso{foreign-string-alloc} | |
4891 | |
4892 | |
4893 @c =================================================================== | |
4894 @c FOREIGN-STRING-TO-LISP | |
4895 | |
4896 @page | |
4897 @node foreign-string-to-lisp, lisp-string-to-foreign, foreign-string-fre… | |
4898 @heading foreign-string-to-lisp | |
4899 @subheading Syntax | |
4900 @Function{foreign-string-to-lisp ptr &key offset count max-chars @ | |
4901 encoding @res{} string} | |
4902 | |
4903 @subheading Arguments and Values | |
4904 | |
4905 @table @var | |
4906 @item ptr | |
4907 A pointer. | |
4908 | |
4909 @item offset | |
4910 An integer greater than or equal to 0. Defauls to 0. | |
4911 | |
4912 @item count | |
4913 Either @code{nil} (the default), or an integer greater than or equal to … | |
4914 | |
4915 @item max-chars | |
4916 An integer greater than or equal to 0. | |
4917 @code{(1- array-total-size-limit)}, by default. | |
4918 | |
4919 @item encoding | |
4920 Foreign encoding. Defaults to @code{*default-foreign-encoding*}. | |
4921 | |
4922 @item string | |
4923 A Lisp string. | |
4924 @end table | |
4925 | |
4926 @subheading Description | |
4927 The @code{foreign-string-to-lisp} function converts at most | |
4928 @var{count} octets from @var{ptr} into a Lisp string, using the | |
4929 defined @var{encoding}. | |
4930 | |
4931 If @var{count} is @code{nil} (the default), characters are copied | |
4932 until @var{max-chars} is reached or a @code{NULL} character is found. | |
4933 | |
4934 If @var{ptr} is a null pointer, returns @code{nil}. | |
4935 | |
4936 Note that the @code{:string} type will automatically convert between | |
4937 Lisp strings and foreign strings. | |
4938 | |
4939 @subheading Examples | |
4940 | |
4941 @lisp | |
4942 CFFI> (foreign-funcall "getenv" :string "HOME" :pointer) | |
4943 @result{} #<FOREIGN-ADDRESS #xBFFFFFD5> | |
4944 CFFI> (foreign-string-to-lisp *) | |
4945 @result{} "/Users/luis" | |
4946 @end lisp | |
4947 | |
4948 @subheading See Also | |
4949 @seealso{lisp-string-to-foreign} @* | |
4950 @seealso{foreign-string-alloc} | |
4951 @c @seealso{:string} | |
4952 | |
4953 | |
4954 @c =================================================================== | |
4955 @c LISP-STRING-TO-FOREIGN | |
4956 | |
4957 @page | |
4958 @node lisp-string-to-foreign, with-foreign-string, foreign-string-to-lis… | |
4959 @heading lisp-string-to-foreign | |
4960 @subheading Syntax | |
4961 @Function{lisp-string-to-foreign string buffer bufsize &key start @ | |
4962 end offset encoding @res{} buffer} | |
4963 | |
4964 @subheading Arguments and Values | |
4965 | |
4966 @table @emph | |
4967 @item @var{string} | |
4968 A Lisp string. | |
4969 | |
4970 @item @var{buffer} | |
4971 A foreign pointer. | |
4972 | |
4973 @item @var{bufsize} | |
4974 An integer. | |
4975 | |
4976 @item @var{start}, @var{end} | |
4977 Bounding index designators of @var{string}. 0 and @code{nil}, by | |
4978 default. | |
4979 | |
4980 @item @var{offset} | |
4981 An integer greater than or equal to 0. Defauls to 0. | |
4982 | |
4983 @item @var{encoding} | |
4984 Foreign encoding. Defaults to @code{*default-foreign-encoding*}. | |
4985 @end table | |
4986 | |
4987 @subheading Description | |
4988 The @code{lisp-string-to-foreign} function copies at most | |
4989 @var{bufsize}-1 octets from a Lisp @var{string} using the specified | |
4990 @var{encoding} into @var{buffer}+@var{offset}. The foreign string will | |
4991 be null-terminated. | |
4992 | |
4993 @var{Start} specifies an offset into @var{string} and | |
4994 @var{end} marks the position following the last element of the foreign | |
4995 string. | |
4996 | |
4997 @subheading Examples | |
4998 | |
4999 @lisp | |
5000 CFFI> (with-foreign-pointer-as-string (str 255) | |
5001 (lisp-string-to-foreign "Hello, foreign world!" str 6)) | |
5002 @result{} "Hello" | |
5003 @end lisp | |
5004 | |
5005 @subheading See Also | |
5006 @seealso{foreign-string-alloc} @* | |
5007 @seealso{foreign-string-to-lisp} @* | |
5008 @seealso{with-foreign-pointer-as-string} | |
5009 | |
5010 | |
5011 @c =================================================================== | |
5012 @c WITH-FOREIGN-STRING | |
5013 | |
5014 @page | |
5015 @node with-foreign-string, with-foreign-pointer-as-string, lisp-string-t… | |
5016 @heading with-foreign-string, with-foreign-strings | |
5017 @subheading Syntax | |
5018 @Macro{with-foreign-string (var-or-vars string &rest args) &body body} | |
5019 | |
5020 @anchor{with-foreign-strings} | |
5021 @Macro{with-foreign-strings (bindings) &body body} | |
5022 | |
5023 var-or-vars ::= var | (var &optional octet-size-var) | |
5024 bindings ::= @{(var-or-vars string &rest args)@}* | |
5025 | |
5026 @subheading Arguments and Values | |
5027 | |
5028 @table @emph | |
5029 @item @var{var}, @var{byte-size-var} | |
5030 A symbol. | |
5031 | |
5032 @item @var{string} | |
5033 A Lisp string. | |
5034 | |
5035 @item @var{body} | |
5036 A list of forms to be executed. | |
5037 @end table | |
5038 | |
5039 @subheading Description | |
5040 The @code{with-foreign-string} macro will bind @var{var} to a newly | |
5041 allocated foreign string containing @var{string}. @var{Args} is passed | |
5042 to the underlying @code{foreign-string-alloc} call. | |
5043 | |
5044 If @var{octet-size-var} is provided, it will be bound the length of | |
5045 foreign string in octets including the null terminator. | |
5046 | |
5047 @subheading Examples | |
5048 | |
5049 @lisp | |
5050 CFFI> (with-foreign-string (foo "12345") | |
5051 (foreign-funcall "strlen" :pointer foo :int)) | |
5052 @result{} 5 | |
5053 | |
5054 CFFI> (let ((array (coerce #(84 117 114 97 110 103 97) | |
5055 '(array (unsigned-byte 8))))) | |
5056 (with-foreign-string (foreign-string array) | |
5057 (foreign-string-to-lisp foreign-string))) | |
5058 @result{} "Turanga" | |
5059 @end lisp | |
5060 | |
5061 @subheading See Also | |
5062 @seealso{foreign-string-alloc} @* | |
5063 @seealso{with-foreign-pointer-as-string} | |
5064 | |
5065 | |
5066 @c =================================================================== | |
5067 @c WITH-FOREIGN-POINTER-AS-STRING | |
5068 | |
5069 @page | |
5070 @node with-foreign-pointer-as-string, , with-foreign-string, Strings | |
5071 @heading with-foreign-pointer-as-string | |
5072 @subheading Syntax | |
5073 @Macro{with-foreign-pointer-as-string (var size &optional size-var @ | |
5074 &rest args) &body body @res{} stri… | |
5075 | |
5076 @subheading Arguments and Values | |
5077 | |
5078 @table @var | |
5079 @item var | |
5080 A symbol. | |
5081 | |
5082 @item string | |
5083 A Lisp string. | |
5084 | |
5085 @item body | |
5086 List of forms to be executed. | |
5087 @end table | |
5088 | |
5089 @subheading Description | |
5090 The @code{with-foreign-pointer-as-string} macro is similar to | |
5091 @code{with-foreign-pointer} except that @var{var} is used as the | |
5092 returned value of an implicit @code{progn} around @var{body}, after | |
5093 being converted to a Lisp string using the provided @var{args}. | |
5094 | |
5095 @subheading Examples | |
5096 | |
5097 @lisp | |
5098 CFFI> (with-foreign-pointer-as-string (str 6 str-size :encoding :ascii) | |
5099 (lisp-string-to-foreign "Hello, foreign world!" str str-size)) | |
5100 @result{} "Hello" | |
5101 @end lisp | |
5102 | |
5103 @subheading See Also | |
5104 @seealso{foreign-string-alloc} @* | |
5105 @seealso{with-foreign-string} | |
5106 | |
5107 | |
5108 @c =================================================================== | |
5109 @c CHAPTER: Variables | |
5110 | |
5111 @node Variables, Functions, Strings, Top | |
5112 @chapter Variables | |
5113 | |
5114 @menu | |
5115 Dictionary | |
5116 | |
5117 * defcvar:: | |
5118 * get-var-pointer:: | |
5119 @end menu | |
5120 | |
5121 | |
5122 @c =================================================================== | |
5123 @c DEFCVAR | |
5124 | |
5125 @page | |
5126 @node defcvar, get-var-pointer, Variables, Variables | |
5127 @heading defcvar | |
5128 @subheading Syntax | |
5129 @Macro{defcvar name-and-options type &optional documentation @res{} lisp… | |
5130 | |
5131 @var{name-and-options} ::= name | (name &key read-only (library :default… | |
5132 @var{name} ::= lisp-name [foreign-name] | foreign-name [lisp-name] | |
5133 | |
5134 @subheading Arguments and Values | |
5135 | |
5136 @table @var | |
5137 @item foreign-name | |
5138 A string denoting a foreign function. | |
5139 | |
5140 @item lisp-name | |
5141 A symbol naming the Lisp function to be created. | |
5142 | |
5143 @item type | |
5144 A foreign type. | |
5145 | |
5146 @item read-only | |
5147 A boolean. | |
5148 | |
5149 @item documentation | |
5150 A Lisp string; not evaluated. | |
5151 @end table | |
5152 | |
5153 @subheading Description | |
5154 The @code{defcvar} macro defines a symbol macro @var{lisp-name} that loo… | |
5155 up @var{foreign-name} and dereferences it acording to @var{type}. It | |
5156 can also be @code{setf}ed, unless @var{read-only} is true, in which | |
5157 case an error will be signaled. | |
5158 | |
5159 When one of @var{lisp-name} or @var{foreign-name} is omitted, the | |
5160 other is automatically derived using the following rules: | |
5161 | |
5162 @itemize | |
5163 @item | |
5164 Foreign names are converted to Lisp names by uppercasing, replacing | |
5165 underscores with hyphens, and wrapping around asterisks. | |
5166 @item | |
5167 Lisp names are converted to foreign names by lowercasing, replacing | |
5168 hyphens with underscores, and removing asterisks, if any. | |
5169 @end itemize | |
5170 | |
5171 @subheading Examples | |
5172 | |
5173 @lisp | |
5174 CFFI> (defcvar "errno" :int) | |
5175 @result{} *ERRNO* | |
5176 CFFI> (foreign-funcall "strerror" :int *errno* :string) | |
5177 @result{} "Inappropriate ioctl for device" | |
5178 CFFI> (setf *errno* 1) | |
5179 @result{} 1 | |
5180 CFFI> (foreign-funcall "strerror" :int *errno* :string) | |
5181 @result{} "Operation not permitted" | |
5182 @end lisp | |
5183 | |
5184 Trying to modify a read-only foreign variable: | |
5185 | |
5186 @lisp | |
5187 CFFI> (defcvar ("errno" +error-number+ :read-only t) :int) | |
5188 @result{} +ERROR-NUMBER+ | |
5189 CFFI> (setf +error-number+ 12) | |
5190 ;; @lispcmt{@error{} Trying to modify read-only foreign var: +ERROR-NUMB… | |
5191 @end lisp | |
5192 | |
5193 @emph{Note that accessing @code{errno} this way won't work with every | |
5194 implementation of the C standard library.} | |
5195 | |
5196 @subheading See Also | |
5197 @seealso{get-var-pointer} | |
5198 | |
5199 | |
5200 @c =================================================================== | |
5201 @c GET-VAR-POINTER | |
5202 | |
5203 @page | |
5204 @node get-var-pointer, , defcvar, Variables | |
5205 @heading get-var-pointer | |
5206 @subheading Syntax | |
5207 @Function{get-var-pointer symbol @res{} pointer} | |
5208 | |
5209 @subheading Arguments and Values | |
5210 | |
5211 @table @var | |
5212 @item symbol | |
5213 A symbol denoting a foreign variable defined with @code{defcvar}. | |
5214 | |
5215 @item pointer | |
5216 A foreign pointer. | |
5217 @end table | |
5218 | |
5219 @subheading Description | |
5220 The function @code{get-var-pointer} will return a @var{pointer} to the | |
5221 foreign global variable @var{symbol} previously defined with | |
5222 @code{defcvar}. | |
5223 | |
5224 @subheading Examples | |
5225 | |
5226 @lisp | |
5227 CFFI> (defcvar "errno" :int :read-only t) | |
5228 @result{} *ERRNO* | |
5229 CFFI> *errno* | |
5230 @result{} 25 | |
5231 CFFI> (get-var-pointer '*errno*) | |
5232 @result{} #<A Mac Pointer #xA0008130> | |
5233 CFFI> (mem-ref * :int) | |
5234 @result{} 25 | |
5235 @end lisp | |
5236 | |
5237 @subheading See Also | |
5238 @seealso{defcvar} | |
5239 | |
5240 | |
5241 @c =================================================================== | |
5242 @c CHAPTER: Functions | |
5243 | |
5244 @node Functions, Libraries, Variables, Top | |
5245 @chapter Functions | |
5246 | |
5247 @menu | |
5248 @c * Defining Foreign Functions:: | |
5249 @c * Calling Foreign Functions:: | |
5250 | |
5251 Dictionary | |
5252 | |
5253 * defcfun:: | |
5254 * foreign-funcall:: | |
5255 * foreign-funcall-pointer:: | |
5256 * foreign-funcall-varargs:: | |
5257 * foreign-funcall-pointer-varargs:: | |
5258 * translate-camelcase-name:: | |
5259 * translate-name-from-foreign:: | |
5260 * translate-name-to-foreign:: | |
5261 * translate-underscore-separated-name:: | |
5262 @end menu | |
5263 | |
5264 @c @node Calling Foreign Functions | |
5265 @c @section Calling Foreign Functions | |
5266 | |
5267 @c @node Defining Foreign Functions | |
5268 @c @section Defining Foreign Functions | |
5269 | |
5270 | |
5271 @c =================================================================== | |
5272 @c DEFCFUN | |
5273 | |
5274 @page | |
5275 @node defcfun, foreign-funcall, Functions, Functions | |
5276 @heading defcfun | |
5277 @subheading Syntax | |
5278 @Macro{defcfun name-and-options return-type &body [docstring] arguments … | |
5279 @res{} lisp-name} | |
5280 | |
5281 @var{name-and-options} ::= @var{name} | (@var{name} &key @var{library} @… | |
5282 @var{name} ::= @var{lisp-name} [@var{foreign-name}] | @var{foreign-name}… | |
5283 @var{arguments} ::= @{ (@var{arg-name} @var{arg-type}) @}* @* | |
5284 | |
5285 @subheading Arguments and Values | |
5286 | |
5287 @table @var | |
5288 @item foreign-name | |
5289 A string denoting a foreign function. | |
5290 | |
5291 @item lisp-name | |
5292 A symbol naming the Lisp function to be created. | |
5293 | |
5294 @item arg-name | |
5295 A symbol. | |
5296 | |
5297 @item return-type | |
5298 @itemx arg-type | |
5299 A foreign type. | |
5300 | |
5301 @item convention | |
5302 One of @code{:cdecl} (default) or @code{:stdcall}. | |
5303 | |
5304 @item library | |
5305 A symbol designating a foreign library. | |
5306 | |
5307 @item docstring | |
5308 A documentation string. | |
5309 @end table | |
5310 | |
5311 @subheading Description | |
5312 The @code{defcfun} macro provides a declarative interface for defining | |
5313 Lisp functions that call foreign functions. | |
5314 | |
5315 When one of @var{lisp-name} or @var{foreign-name} is omitted, the | |
5316 other is automatically derived using the following rules: | |
5317 | |
5318 @itemize | |
5319 @item | |
5320 Foreign names are converted to Lisp names by uppercasing and replacing | |
5321 underscores with hyphens. | |
5322 @item | |
5323 Lisp names are converted to foreign names by lowercasing and replacing | |
5324 hyphens with underscores. | |
5325 @end itemize | |
5326 | |
5327 If you place the symbol @code{&rest} in the end of the argument list | |
5328 after the fixed arguments, @code{defcfun} will treat the foreign | |
5329 function as a @strong{variadic function}. The variadic arguments | |
5330 should be passed in a way similar to what @code{foreign-funcall} would | |
5331 expect. Unlike @code{foreign-funcall} though, @code{defcfun} will take | |
5332 care of doing argument promotion. Note that in this case | |
5333 @code{defcfun} will generate a Lisp @emph{macro} instead of a | |
5334 function and will only work for Lisps that support | |
5335 @code{foreign-funcall.} | |
5336 | |
5337 If a foreign structure is to be passed or returned by value (that is, | |
5338 the type is of the form @code{(:struct ...)}), then the cffi-libffi syst… | |
5339 must be loaded, which in turn depends on | |
5340 @uref{http://sourceware.org/libffi/,libffi}, including the header files. | |
5341 Failure to load that system will result in an error. | |
5342 Variadic functions cannot at present accept or return structures by | |
5343 value. | |
5344 | |
5345 @subheading Examples | |
5346 | |
5347 @lisp | |
5348 (defcfun "strlen" :int | |
5349 "Calculate the length of a string." | |
5350 (n :string)) | |
5351 | |
5352 CFFI> (strlen "123") | |
5353 @result{} 3 | |
5354 @end lisp | |
5355 | |
5356 @lisp | |
5357 (defcfun ("abs" c-abs) :int (n :int)) | |
5358 | |
5359 CFFI> (c-abs -42) | |
5360 @result{} 42 | |
5361 @end lisp | |
5362 | |
5363 Function without arguments: | |
5364 | |
5365 @lisp | |
5366 (defcfun "rand" :int) | |
5367 | |
5368 CFFI> (rand) | |
5369 @result{} 1804289383 | |
5370 @end lisp | |
5371 | |
5372 Variadic function example: | |
5373 | |
5374 @lisp | |
5375 (defcfun "sprintf" :int | |
5376 (str :pointer) | |
5377 (control :string) | |
5378 &rest) | |
5379 | |
5380 CFFI> (with-foreign-pointer-as-string (s 100) | |
5381 (sprintf s "%c %d %.2f %s" :char 90 :short 42 :float pi | |
5382 :string "super-locrian")) | |
5383 @result{} "A 42 3.14 super-locrian" | |
5384 @end lisp | |
5385 | |
5386 @subheading See Also | |
5387 @seealso{foreign-funcall} @* | |
5388 @seealso{foreign-funcall-pointer} @* | |
5389 @seealso{foreign-funcall-varargs} @* | |
5390 @seealso{foreign-funcall-pointer-varargs} | |
5391 | |
5392 | |
5393 @c =================================================================== | |
5394 @c FOREIGN-FUNCALL | |
5395 | |
5396 @page | |
5397 @node foreign-funcall, foreign-funcall-pointer, defcfun, Functions | |
5398 @heading foreign-funcall | |
5399 @subheading Syntax | |
5400 @Macro{foreign-funcall name-and-options &rest arguments @res{} return-va… | |
5401 | |
5402 @var{arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] … | |
5403 @var{name-and-options} ::= @var{name} | (@var{name} &key @var{library} @… | |
5404 | |
5405 @subheading Arguments and Values | |
5406 | |
5407 @table @var | |
5408 @item name | |
5409 A Lisp string. | |
5410 | |
5411 @item arg-type | |
5412 A foreign type. | |
5413 | |
5414 @item arg | |
5415 An argument of type @var{arg-type}. | |
5416 | |
5417 @item return-type | |
5418 A foreign type, @code{:void} by default. | |
5419 | |
5420 @item return-value | |
5421 A lisp object. | |
5422 | |
5423 @item library | |
5424 A lisp symbol; not evaluated. | |
5425 | |
5426 @item convention | |
5427 One of @code{:cdecl} (default) or @code{:stdcall}. | |
5428 @end table | |
5429 | |
5430 @subheading Description | |
5431 The @code{foreign-funcall} macro is the main primitive for calling | |
5432 foreign functions. | |
5433 | |
5434 If a foreign structure is to be passed or returned by value (that is, | |
5435 the type is of the form @code{(:struct ...)}), then the cffi-libffi syst… | |
5436 must be loaded, which in turn depends on | |
5437 @uref{http://sourceware.org/libffi/,libffi}, including the header files. | |
5438 Failure to load that system will result in an error. | |
5439 Variadic functions cannot at present accept or return structures by | |
5440 value. | |
5441 | |
5442 @emph{Note: The return value of foreign-funcall on functions with a | |
5443 :void return type is still undefined.} | |
5444 | |
5445 @subheading Implementation-specific Notes | |
5446 @itemize | |
5447 @item | |
5448 Corman Lisp does not support @code{foreign-funcall}. On | |
5449 implementations that @strong{don't} support @code{foreign-funcall} | |
5450 @code{cffi-sys::no-foreign-funcall} will be present in | |
5451 @code{*features*}. Note: in these Lisps you can still use the | |
5452 @code{defcfun} interface. | |
5453 @end itemize | |
5454 | |
5455 @subheading Examples | |
5456 | |
5457 @lisp | |
5458 CFFI> (foreign-funcall "strlen" :string "foo" :int) | |
5459 @result{} 3 | |
5460 @end lisp | |
5461 | |
5462 Given the C code: | |
5463 | |
5464 @example | |
5465 void print_number(int n) | |
5466 @{ | |
5467 printf("N: %d\n", n); | |
5468 @} | |
5469 @end example | |
5470 | |
5471 @lisp | |
5472 CFFI> (foreign-funcall "print_number" :int 123456) | |
5473 @print{} N: 123456 | |
5474 @result{} NIL | |
5475 @end lisp | |
5476 | |
5477 @noindent | |
5478 Or, equivalently: | |
5479 | |
5480 @lisp | |
5481 CFFI> (foreign-funcall "print_number" :int 123456 :void) | |
5482 @print{} N: 123456 | |
5483 @result{} NIL | |
5484 @end lisp | |
5485 | |
5486 @lisp | |
5487 CFFI> (foreign-funcall "printf" :string (format nil "%s: %d.~%") | |
5488 :string "So long and thanks for all the fish" | |
5489 :int 42 :int) | |
5490 @print{} So long and thanks for all the fish: 42. | |
5491 @result{} 41 | |
5492 @end lisp | |
5493 | |
5494 @subheading See Also | |
5495 @seealso{defcfun} @* | |
5496 @seealso{foreign-funcall-pointer} | |
5497 | |
5498 | |
5499 @c =================================================================== | |
5500 @c FOREIGN-FUNCALL-POINTER | |
5501 | |
5502 @page | |
5503 @node foreign-funcall-pointer, foreign-funcall-varargs, foreign-funcall,… | |
5504 @heading foreign-funcall-pointer | |
5505 @subheading Syntax | |
5506 @Macro{foreign-funcall-pointer pointer options &rest arguments @res{} re… | |
5507 | |
5508 @var{arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] … | |
5509 @var{options} ::= (&key @var{convention}) @* | |
5510 | |
5511 @subheading Arguments and Values | |
5512 | |
5513 @table @var | |
5514 @item pointer | |
5515 A foreign pointer. | |
5516 | |
5517 @item arg-type | |
5518 A foreign type. | |
5519 | |
5520 @item arg | |
5521 An argument of type @var{arg-type}. | |
5522 | |
5523 @item return-type | |
5524 A foreign type, @code{:void} by default. | |
5525 | |
5526 @item return-value | |
5527 A lisp object. | |
5528 | |
5529 @item convention | |
5530 One of @code{:cdecl} (default) or @code{:stdcall}. | |
5531 @end table | |
5532 | |
5533 @subheading Description | |
5534 The @code{foreign-funcall} macro is the main primitive for calling | |
5535 foreign functions. | |
5536 | |
5537 @emph{Note: The return value of foreign-funcall on functions with a | |
5538 :void return type is still undefined.} | |
5539 | |
5540 @subheading Implementation-specific Notes | |
5541 @itemize | |
5542 @item | |
5543 Corman Lisp does not support @code{foreign-funcall}. On | |
5544 implementations that @strong{don't} support @code{foreign-funcall} | |
5545 @code{cffi-sys::no-foreign-funcall} will be present in | |
5546 @code{*features*}. Note: in these Lisps you can still use the | |
5547 @code{defcfun} interface. | |
5548 @end itemize | |
5549 | |
5550 @subheading Examples | |
5551 | |
5552 @lisp | |
5553 CFFI> (foreign-funcall-pointer (foreign-symbol-pointer "abs") () | |
5554 :int -42 :int) | |
5555 @result{} 42 | |
5556 @end lisp | |
5557 | |
5558 @subheading See Also | |
5559 @seealso{defcfun} @* | |
5560 @seealso{foreign-funcall} | |
5561 | |
5562 | |
5563 @c =================================================================== | |
5564 @c FOREIGN-FUNCALL-VARARGS | |
5565 | |
5566 @page | |
5567 @node foreign-funcall-varargs, foreign-funcall-pointer-varargs, foreign-… | |
5568 @heading foreign-funcall-varargs | |
5569 @subheading Syntax | |
5570 @Macro{foreign-funcall-varargs name-and-options (fixed-arguments) &rest … | |
5571 | |
5572 @var{fixed-arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-t… | |
5573 @var{arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] … | |
5574 @var{name-and-options} ::= @var{name} | (@var{name} &key @var{library} @… | |
5575 | |
5576 @subheading Arguments and Values | |
5577 | |
5578 @table @var | |
5579 @item name | |
5580 A Lisp string. | |
5581 | |
5582 @item arg-type | |
5583 A foreign type. | |
5584 | |
5585 @item arg | |
5586 An argument of type @var{arg-type}. | |
5587 | |
5588 @item return-type | |
5589 A foreign type, @code{:void} by default. | |
5590 | |
5591 @item return-value | |
5592 A lisp object. | |
5593 | |
5594 @item library | |
5595 A lisp symbol; not evaluated. | |
5596 | |
5597 @item convention | |
5598 One of @code{:cdecl} (default) or @code{:stdcall}. | |
5599 @end table | |
5600 | |
5601 @subheading Description | |
5602 The @code{foreign-funcall-varargs} macro is the main primitive for | |
5603 calling foreign variadic functions. It behaves similarily to | |
5604 @code{foreign-funcall} except @code{fixed-arguments} are distinguished | |
5605 from the remaining arguments. | |
5606 | |
5607 @subheading Examples | |
5608 | |
5609 @lisp | |
5610 CFFI> (with-foreign-pointer-as-string (s 100) | |
5611 (setf (mem-ref s :char) 0) | |
5612 (foreign-funcall-varargs | |
5613 "sprintf" (:pointer s :string) "%.2f") | |
5614 :double (coerce pi 'double-float) :int)) | |
5615 @result{} 3.14 | |
5616 @end lisp | |
5617 | |
5618 | |
5619 @c =================================================================== | |
5620 @c FOREIGN-FUNCALL-POINTER-VARARGS | |
5621 | |
5622 @page | |
5623 @node foreign-funcall-pointer-varargs, translate-camelcase-name, foreign… | |
5624 @heading foreign-funcall-pointer-varargs | |
5625 @subheading Syntax | |
5626 @Macro{foreign-funcall-pointer-varargs pointer options (fixed-arguments)… | |
5627 | |
5628 @var{fixed-arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-t… | |
5629 @var{arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] … | |
5630 @var{options} ::= (&key @var{convention}) @* | |
5631 | |
5632 @subheading Arguments and Values | |
5633 | |
5634 @table @var | |
5635 @item pointer | |
5636 A foreign pointer. | |
5637 | |
5638 @item arg-type | |
5639 A foreign type. | |
5640 | |
5641 @item arg | |
5642 An argument of type @var{arg-type}. | |
5643 | |
5644 @item return-type | |
5645 A foreign type, @code{:void} by default. | |
5646 | |
5647 @item return-value | |
5648 A lisp object. | |
5649 | |
5650 @item convention | |
5651 One of @code{:cdecl} (default) or @code{:stdcall}. | |
5652 @end table | |
5653 | |
5654 @subheading Description | |
5655 The @code{foreign-funcall-pointer-varargs} macro is the main primitive | |
5656 for calling foreign variadic functions. It behaves similarily to | |
5657 @code{foreign-funcall-pointer} except @code{fixed-arguments} are | |
5658 distinguished from the remaining arguments. | |
5659 | |
5660 @subheading Examples | |
5661 | |
5662 @lisp | |
5663 CFFI> (with-foreign-pointer-as-string (s 100) | |
5664 (setf (mem-ref s :char) 0) | |
5665 (foreign-funcall-pointer-varargs | |
5666 (foreign-symbol-pointer "sprintf") () (:pointer s :string "%.2f… | |
5667 :double (coerce pi 'double-float) :int)) | |
5668 @result{} 3.14 | |
5669 @end lisp | |
5670 | |
5671 | |
5672 @c =================================================================== | |
5673 @c TRANSLATE-CAMELCASE-NAME | |
5674 | |
5675 @page | |
5676 @node translate-camelcase-name, translate-name-from-foreign, foreign-fun… | |
5677 @heading translate-camelcase-name | |
5678 @subheading Syntax | |
5679 @Function{translate-camelcase-name name &key upper-initial-p special-wor… | |
5680 | |
5681 @subheading Arguments and Values | |
5682 | |
5683 @table @var | |
5684 @item name | |
5685 Either a symbol or a string. | |
5686 | |
5687 @item upper-initial-p | |
5688 A generalized boolean. | |
5689 | |
5690 @item special words | |
5691 A list of strings. | |
5692 | |
5693 @item return-value | |
5694 If @var{name} is a symbol, this is a string, and vice versa. | |
5695 @end table | |
5696 | |
5697 @subheading Description | |
5698 @code{translate-camelcase-name} is a helper function for | |
5699 specializations of @code{translate-name-from-foreign} and | |
5700 @code{translate-name-to-foreign}. It handles the common case of | |
5701 converting between foreign camelCase names and lisp | |
5702 names. @var{upper-initial-p} indicates whether the first letter of the | |
5703 foreign name should be uppercase. @var{special-words} is a list of | |
5704 strings that should be treated atomically in translation. This list is | |
5705 case-sensitive. | |
5706 | |
5707 @subheading Examples | |
5708 | |
5709 @lisp | |
5710 CFFI> (translate-camelcase-name some-xml-function) | |
5711 @result{} "someXmlFunction" | |
5712 CFFI> (translate-camelcase-name some-xml-function :upper-initial-p t) | |
5713 @result{} "SomeXmlFunction" | |
5714 CFFI> (translate-camelcase-name some-xml-function :special-words '("XML"… | |
5715 @result{} "someXMLFunction" | |
5716 CFFI> (translate-camelcase-name "someXMLFunction") | |
5717 @result{} SOME-X-M-L-FUNCTION | |
5718 CFFI> (translate-camelcase-name "someXMLFunction" :special-words '("XML"… | |
5719 @result{} SOME-XML-FUNCTION | |
5720 @end lisp | |
5721 | |
5722 @subheading See Also | |
5723 @seealso{translate-name-from-foreign} @* | |
5724 @seealso{translate-name-to-foreign} @* | |
5725 @seealso{translate-underscore-separated-name} | |
5726 | |
5727 | |
5728 @c =================================================================== | |
5729 @c TRANSLATE-NAME-FROM-FOREIGN | |
5730 | |
5731 @page | |
5732 @node translate-name-from-foreign, translate-name-to-foreign, translate-… | |
5733 @heading translate-name-from-foreign | |
5734 @subheading Syntax | |
5735 @Function{translate-name-from-foreign foreign-name package &optional var… | |
5736 | |
5737 @subheading Arguments and Values | |
5738 | |
5739 @table @var | |
5740 @item foreign-name | |
5741 A string denoting a foreign function. | |
5742 | |
5743 @item package | |
5744 A Lisp package | |
5745 | |
5746 @item varp | |
5747 A generalized boolean. | |
5748 | |
5749 @item symbol | |
5750 The Lisp symbol to be used a function name. | |
5751 @end table | |
5752 | |
5753 @subheading Description | |
5754 @code{translate-name-from-foreign} is used by @ref{defcfun} to handle | |
5755 the conversion of foreign names to lisp names. By default, it | |
5756 translates using @ref{translate-underscore-separated-name}. However, | |
5757 you can create specialized methods on this function to make | |
5758 translating more closely match the foreign library's naming | |
5759 conventions. | |
5760 | |
5761 Specialize @var{package} on some package. This allows other packages | |
5762 to load libraries with different naming conventions. | |
5763 | |
5764 @subheading Examples | |
5765 | |
5766 @lisp | |
5767 CFFI> (defcfun "someXmlFunction" ...) | |
5768 @result{} SOMEXMLFUNCTION | |
5769 CFFI> (defmethod translate-name-from-foreign ((spec string) | |
5770 (package (eql *package*)) | |
5771 &optional varp) | |
5772 (let ((name (translate-camelcase-name spec))) | |
5773 (if varp (intern (format nil "*~a*" name)) name))) | |
5774 @result{} #<STANDARD-METHOD TRANSLATE-NAME-FROM-FOREIGN (STRING (EQL #<P… | |
5775 CFFI> (defcfun "someXmlFunction" ...) | |
5776 @result{} SOME-XML-FUNCTION | |
5777 @end lisp | |
5778 | |
5779 @subheading See Also | |
5780 @seealso{defcfun} @* | |
5781 @seealso{translate-camelcase-name} @* | |
5782 @seealso{translate-name-to-foreign} @* | |
5783 @seealso{translate-underscore-separated-name} | |
5784 | |
5785 | |
5786 @c =================================================================== | |
5787 @c TRANSLATE-NAME-TO-FOREIGN | |
5788 | |
5789 @page | |
5790 @node translate-name-to-foreign, translate-underscore-separated-name, tr… | |
5791 @heading translate-name-to-foreign | |
5792 @subheading Syntax | |
5793 @Function{translate-name-to-foreign lisp-name package &optional varp @re… | |
5794 | |
5795 @subheading Arguments and Values | |
5796 | |
5797 @table @var | |
5798 @item lisp-name | |
5799 A symbol naming the Lisp function to be created. | |
5800 | |
5801 @item package | |
5802 A Lisp package | |
5803 | |
5804 @item varp | |
5805 A generalized boolean. | |
5806 | |
5807 @item string | |
5808 The string representing the foreign function name. | |
5809 @end table | |
5810 | |
5811 @subheading Description | |
5812 @code{translate-name-to-foreign} is used by @ref{defcfun} to handle | |
5813 the conversion of lisp names to foreign names. By default, it | |
5814 translates using @ref{translate-underscore-separated-name}. However, | |
5815 you can create specialized methods on this function to make | |
5816 translating more closely match the foreign library's naming | |
5817 conventions. | |
5818 | |
5819 Specialize @var{package} on some package. This allows other packages | |
5820 to load libraries with different naming conventions. | |
5821 | |
5822 @subheading Examples | |
5823 | |
5824 @lisp | |
5825 CFFI> (defcfun some-xml-function ...) | |
5826 @result{} "some_xml_function" | |
5827 CFFI> (defmethod translate-name-to-foreign ((spec symbol) | |
5828 (package (eql *package*)) | |
5829 &optional varp) | |
5830 (let ((name (translate-camelcase-name spec))) | |
5831 (if varp (subseq name 1 (1- (length name))) name))) | |
5832 @result{} #<STANDARD-METHOD TRANSLATE-NAME-TO-FOREIGN (STRING (EQL #<Pac… | |
5833 CFFI> (defcfun some-xml-function ...) | |
5834 @result{} "someXmlFunction" | |
5835 @end lisp | |
5836 | |
5837 @subheading See Also | |
5838 @seealso{defcfun} @* | |
5839 @seealso{translate-camelcase-name} @* | |
5840 @seealso{translate-name-from-foreign} @* | |
5841 @seealso{translate-underscore-separated-name} | |
5842 | |
5843 | |
5844 @c =================================================================== | |
5845 @c TRANSLATE-UNDERSCORE-SEPARATED-NAME | |
5846 | |
5847 @page | |
5848 @node translate-underscore-separated-name, , translate-name-to-foreign,… | |
5849 @heading translate-underscore-separated-name | |
5850 @subheading Syntax | |
5851 @Function{translate-underscore-separated-name name @res{} return-value} | |
5852 | |
5853 @subheading Arguments and Values | |
5854 | |
5855 @table @var | |
5856 @item name | |
5857 Either a symbol or a string. | |
5858 | |
5859 @item return-value | |
5860 If @var{name} is a symbol, this is a string, and vice versa. | |
5861 @end table | |
5862 | |
5863 @subheading Description | |
5864 @code{translate-underscore-separated-name} is a helper function for | |
5865 specializations of @ref{translate-name-from-foreign} and | |
5866 @ref{translate-name-to-foreign}. It handles the common case of | |
5867 converting between foreign underscore_separated names and lisp names. | |
5868 | |
5869 @subheading Examples | |
5870 | |
5871 @lisp | |
5872 CFFI> (translate-underscore-separated-name some-xml-function) | |
5873 @result{} "some_xml_function" | |
5874 CFFI> (translate-camelcase-name "some_xml_function") | |
5875 @result{} SOME-XML-FUNCTION | |
5876 @end lisp | |
5877 | |
5878 @subheading See Also | |
5879 @seealso{translate-name-from-foreign} @* | |
5880 @seealso{translate-name-to-foreign} @* | |
5881 @seealso{translate-camelcase-name} | |
5882 | |
5883 | |
5884 @c =================================================================== | |
5885 @c CHAPTER: Libraries | |
5886 | |
5887 @node Libraries, Callbacks, Functions, Top | |
5888 @chapter Libraries | |
5889 | |
5890 @menu | |
5891 * Defining a library:: | |
5892 * Library definition style:: | |
5893 | |
5894 Dictionary | |
5895 | |
5896 * close-foreign-library:: Close a foreign library. | |
5897 * *darwin-framework-directories*:: Search path for Darwin frameworks. | |
5898 * define-foreign-library:: Explain how to load a foreign library. | |
5899 * *foreign-library-directories*:: Search path for shared libraries. | |
5900 * load-foreign-library:: Load a foreign library. | |
5901 * load-foreign-library-error:: Signalled on failure of its namesake. | |
5902 * use-foreign-library:: Load a foreign library when needed. | |
5903 @end menu | |
5904 | |
5905 | |
5906 @node Defining a library, Library definition style, Libraries, Libraries | |
5907 @section Defining a library | |
5908 | |
5909 Almost all foreign code you might want to access exists in some kind | |
5910 of shared library. The meaning of @dfn{shared library} varies among | |
5911 platforms, but for our purposes, we will consider it to include | |
5912 @file{.so} files on @sc{unix}, frameworks on Darwin (and derivatives | |
5913 like Mac @acronym{OS X}), and @file{.dll} files on Windows. | |
5914 | |
5915 Bringing one of these libraries into the Lisp image is normally a | |
5916 two-step process. | |
5917 | |
5918 @enumerate | |
5919 @item | |
5920 Describe to @cffi{} how to load the library at some future point, | |
5921 depending on platform and other factors, with a | |
5922 @code{define-foreign-library} top-level form. | |
5923 | |
5924 @item | |
5925 Load the library so defined with either a top-level | |
5926 @code{use-foreign-library} form or by calling the function | |
5927 @code{load-foreign-library}. | |
5928 @end enumerate | |
5929 | |
5930 @xref{Tutorial-Loading,, Loading foreign libraries}, for a working | |
5931 example of the above two steps. | |
5932 | |
5933 | |
5934 @node Library definition style, close-foreign-library, Defining a librar… | |
5935 @section Library definition style | |
5936 | |
5937 Looking at the @code{libcurl} library definition presented earlier, | |
5938 you may ask why we did not simply do this: | |
5939 | |
5940 @lisp | |
5941 (define-foreign-library libcurl | |
5942 (t (:default "libcurl"))) | |
5943 @end lisp | |
5944 | |
5945 @noindent | |
5946 Indeed, this would work just as well on the computer on which I tested | |
5947 the tutorial. There are a couple of good reasons to provide the | |
5948 @file{.so}'s current version number, however. Namely, the versionless | |
5949 @file{.so} is not packaged on most @sc{unix} systems along with the | |
5950 actual, fully-versioned library; instead, it is included in the | |
5951 ``development'' package along with C headers and static @file{.a} | |
5952 libraries. | |
5953 | |
5954 The reason @cffi{} does not try to account for this lies in the | |
5955 meaning of the version numbers. A full treatment of shared library | |
5956 versions is beyond this manual's scope; see @ref{Versioning,, Library | |
5957 interface versions, libtool, @acronym{GNU} Libtool}, for helpful | |
5958 information for the unfamiliar. For our purposes, consider that a | |
5959 mismatch between the library version with which you tested and the | |
5960 installed library version may cause undefined | |
5961 behavior.@footnote{Windows programmers may chafe at adding a | |
5962 @sc{unix}-specific clause to @code{define-foreign-library}. Instead, | |
5963 ask why the Windows solution to library incompatibility is ``include | |
5964 your own version of every library you use with every program''.} | |
5965 | |
5966 @impnote{Maybe some notes should go here about OS X, which I know | |
5967 little about. --stephen} | |
5968 | |
5969 | |
5970 @c =================================================================== | |
5971 @c CLOSE-FOREIGN-LIBRARY | |
5972 | |
5973 @page | |
5974 @node close-foreign-library, *darwin-framework-directories*, Library def… | |
5975 @heading close-foreign-library | |
5976 @subheading Syntax | |
5977 @Function{close-foreign-library library @res{} success} | |
5978 | |
5979 @subheading Arguments and Values | |
5980 | |
5981 @table @var | |
5982 @item library | |
5983 A symbol or an instance of @code{foreign-library}. | |
5984 | |
5985 @item success | |
5986 A Lisp boolean. | |
5987 @end table | |
5988 | |
5989 @subheading Description | |
5990 | |
5991 Closes @var{library} which can be a symbol designating a library | |
5992 define through @code{define-foreign-library} or an instance of | |
5993 @code{foreign-library} as returned by @code{load-foreign-library}. | |
5994 | |
5995 @c @subheading Examples | |
5996 @c @xref{Tutorial-Loading,, Loading foreign libraries}. | |
5997 | |
5998 @subheading See Also | |
5999 | |
6000 @seealso{define-foreign-library} @* | |
6001 @seealso{load-foreign-library} @* | |
6002 @seealso{use-foreign-library} | |
6003 | |
6004 | |
6005 @c =================================================================== | |
6006 @c *DARWIN-FRAMEWORK-DIRECTORIES* | |
6007 | |
6008 @page | |
6009 @node *darwin-framework-directories*, define-foreign-library, close-fore… | |
6010 @heading *darwin-framework-directories* | |
6011 @subheading Syntax | |
6012 | |
6013 @Variable{*darwin-framework-directories*} | |
6014 | |
6015 @subheading Value type | |
6016 | |
6017 A list, in which each element is a string, a pathname, or a simple | |
6018 Lisp expression. | |
6019 | |
6020 @subheading Initial value | |
6021 | |
6022 A list containing the following, in order: an expression corresponding | |
6023 to Darwin path @file{~/Library/Frameworks/}, | |
6024 @code{#P"/Library/Frameworks/"}, and | |
6025 @code{#P"/System/Library/Frameworks/"}. | |
6026 | |
6027 @subheading Description | |
6028 | |
6029 The meaning of ``simple Lisp expression'' is explained in | |
6030 @ref{*foreign-library-directories*}. In contrast to that variable, | |
6031 this is not a fallback search path; the default value described above | |
6032 is intended to be a reasonably complete search path on Darwin systems. | |
6033 | |
6034 @subheading Examples | |
6035 | |
6036 @lisp | |
6037 CFFI> (let ((lib (load-foreign-library '(:framework "OpenGL")))) | |
6038 (foreign-library-pathname lib)) | |
6039 @result{} #P"/System/Library/Frameworks/OpenGL.framework/OpenGL" | |
6040 @end lisp | |
6041 | |
6042 @subheading See also | |
6043 | |
6044 @seealso{*foreign-library-directories*} @* | |
6045 @seealso{define-foreign-library} | |
6046 | |
6047 | |
6048 @c =================================================================== | |
6049 @c DEFINE-FOREIGN-LIBRARY | |
6050 | |
6051 @page | |
6052 @node define-foreign-library, *foreign-library-directories*, *darwin-fra… | |
6053 @heading define-foreign-library | |
6054 | |
6055 @subheading Syntax | |
6056 | |
6057 @Macro{define-foreign-library name-and-options @{ load-clause @}* @res{}… | |
6058 | |
6059 name-and-options ::= name | (name &key convention search-path) | |
6060 load-clause ::= (feature library &key convention search-path) | |
6061 | |
6062 @subheading Arguments and Values | |
6063 | |
6064 @table @var | |
6065 @item name | |
6066 A symbol. | |
6067 | |
6068 @item feature | |
6069 A feature expression. | |
6070 | |
6071 @item library | |
6072 A library designator. | |
6073 | |
6074 @item convention | |
6075 One of @code{:cdecl} (default) or @code{:stdcall} | |
6076 | |
6077 @item search-path | |
6078 A path or list of paths where the library will be searched if not found … | |
6079 system-global directories. Paths specified in a load clause take priorit… | |
6080 paths specified as library option, with *foreign-library-directories* ha… | |
6081 lowest priority. | |
6082 @end table | |
6083 | |
6084 @subheading Description | |
6085 | |
6086 Creates a new library designator called @var{name}. The | |
6087 @var{load-clause}s describe how to load that designator when passed to | |
6088 @code{load-foreign-library} or @code{use-foreign-library}. | |
6089 | |
6090 When trying to load the library @var{name}, the relevant function | |
6091 searches the @var{load-clause}s in order for the first one where | |
6092 @var{feature} evaluates to true. That happens for any of the | |
6093 following situations: | |
6094 | |
6095 @enumerate 1 | |
6096 @item | |
6097 If @var{feature} is a symbol present in @code{common-lisp:*features*}. | |
6098 | |
6099 @item | |
6100 If @var{feature} is a list, depending on @code{(first @var{feature})}, | |
6101 a keyword: | |
6102 | |
6103 @table @code | |
6104 @item :and | |
6105 All of the feature expressions in @code{(rest @var{feature})} are | |
6106 true. | |
6107 | |
6108 @item :or | |
6109 At least one of the feature expressions in @code{(rest @var{feature})} | |
6110 is true. | |
6111 | |
6112 @item :not | |
6113 The feature expression @code{(second @var{feature})} is not true. | |
6114 @end table | |
6115 | |
6116 @item | |
6117 Finally, if @var{feature} is @code{t}, this @var{load-clause} is | |
6118 picked unconditionally. | |
6119 @end enumerate | |
6120 | |
6121 Upon finding the first true @var{feature}, the library loader then | |
6122 loads the @var{library}. The meaning of ``library designator'' is | |
6123 described in @ref{load-foreign-library}. | |
6124 | |
6125 Functions associated to a library defined by | |
6126 @code{define-foreign-library} (e.g. through @code{defcfun}'s | |
6127 @code{:library} option, will inherit the library's options. The | |
6128 precedence is as follows: | |
6129 | |
6130 @enumerate 1 | |
6131 @item | |
6132 @code{defcfun}/@code{foreign-funcall} specific options; | |
6133 | |
6134 @item | |
6135 @var{load-clause} options; | |
6136 | |
6137 @item | |
6138 global library options (the @var{name-and-options} argument) | |
6139 @end enumerate | |
6140 | |
6141 | |
6142 @subheading Examples | |
6143 | |
6144 @xref{Tutorial-Loading,, Loading foreign libraries}. | |
6145 | |
6146 | |
6147 @subheading See Also | |
6148 | |
6149 @seealso{close-foreign-library} @* | |
6150 @seealso{load-foreign-library} | |
6151 | |
6152 | |
6153 @c =================================================================== | |
6154 @c *FOREIGN-LIBRARY-DIRECTORIES* | |
6155 | |
6156 @page | |
6157 @node *foreign-library-directories*, load-foreign-library, define-foreig… | |
6158 @heading *foreign-library-directories* | |
6159 @subheading Syntax | |
6160 | |
6161 @Variable{*foreign-library-directories*} | |
6162 | |
6163 @subheading Value type | |
6164 | |
6165 A list, in which each element is a string, a pathname, or a simple | |
6166 Lisp expression. | |
6167 | |
6168 @subheading Initial value | |
6169 | |
6170 The empty list. | |
6171 | |
6172 @subheading Description | |
6173 | |
6174 You should not have to use this variable. | |
6175 | |
6176 Most, if not all, Lisps supported by @cffi{} have a reasonable default | |
6177 search algorithm for foreign libraries. For example, Lisps for | |
6178 @sc{unix} usually call | |
6179 @uref{http://www.opengroup.org/onlinepubs/009695399/functions/dlopen.htm… | |
6180 @code{dlopen(3)}}, which in turn looks in the system library | |
6181 directories. Only if that fails does @cffi{} look for the named | |
6182 library file in these directories, and load it from there if found. | |
6183 | |
6184 Thus, this is intended to be a @cffi{}-only fallback to the library | |
6185 search configuration provided by your operating system. For example, | |
6186 if you distribute a foreign library with your Lisp package, you can | |
6187 add the library's containing directory to this list and portably | |
6188 expect @cffi{} to find it. | |
6189 | |
6190 A @dfn{simple Lisp expression} is intended to provide functionality | |
6191 commonly used in search paths such as | |
6192 @acronym{ASDF}'s@footnote{@xref{Using asdf to load systems,,, asdf, | |
6193 asdf: another system definition facility}, for information on | |
6194 @code{asdf:*central-registry*}.}, and is defined recursively as | |
6195 follows:@footnote{See @code{mini-eval} in @file{libraries.lisp} for | |
6196 the source of this definition. As is always the case with a Lisp | |
6197 @code{eval}, it's easier to understand the Lisp definition than the | |
6198 english.} | |
6199 | |
6200 @enumerate | |
6201 @item | |
6202 A list, whose @samp{first} is a function designator, and whose | |
6203 @samp{rest} is a list of simple Lisp expressions to be evaluated and | |
6204 passed to the so-designated function. The result is the result of the | |
6205 function call. | |
6206 | |
6207 @item | |
6208 A symbol, whose result is its symbol value. | |
6209 | |
6210 @item | |
6211 Anything else evaluates to itself. | |
6212 @end enumerate | |
6213 | |
6214 The result of evaluating the @dfn{simple Lisp expression} should yield | |
6215 a @emph{designator} for a @emph{list} of @emph{pathname designators}. | |
6216 | |
6217 @strong{Note}: in Common Lisp, @code{#p"/foo/bar"} designates the | |
6218 @emph{bar} file within the @emph{/foo} directory whereas | |
6219 @code{#p"/foo/bar/"} designates the @emph{/foo/bar} directory. Keep | |
6220 that in mind when customising the value of | |
6221 @code{*foreign-library-directories*}. | |
6222 | |
6223 | |
6224 @subheading Examples | |
6225 | |
6226 @example | |
6227 $ ls | |
6228 @print{} liblibli.so libli.lisp | |
6229 @end example | |
6230 | |
6231 @noindent | |
6232 In @file{libli.lisp}: | |
6233 | |
6234 @lisp | |
6235 (pushnew #P"/home/sirian/lisp/libli/" *foreign-library-directories* | |
6236 :test #'equal) | |
6237 | |
6238 (load-foreign-library '(:default "liblibli")) | |
6239 @end lisp | |
6240 | |
6241 @noindent | |
6242 The following example would achieve the same effect: | |
6243 | |
6244 @lisp | |
6245 (pushnew '(merge-pathnames #p"lisp/libli/" (user-homedir-pathname)) | |
6246 *foreign-library-directories* | |
6247 :test #'equal) | |
6248 @result{} ((MERGE-PATHNAMES #P"lisp/libli/" (USER-HOMEDIR-PATHNAME))) | |
6249 | |
6250 (load-foreign-library '(:default "liblibli")) | |
6251 @end lisp | |
6252 | |
6253 @subheading See also | |
6254 | |
6255 @seealso{*darwin-framework-directories*} @* | |
6256 @seealso{define-foreign-library} | |
6257 | |
6258 | |
6259 @c =================================================================== | |
6260 @c LOAD-FOREIGN-LIBRARY | |
6261 | |
6262 @page | |
6263 @node load-foreign-library, load-foreign-library-error, *foreign-library… | |
6264 @heading load-foreign-library | |
6265 @subheading Syntax | |
6266 @Function{load-foreign-library library-designator @res{} library} | |
6267 | |
6268 @subheading Arguments and Values | |
6269 | |
6270 @table @var | |
6271 @item library-designator | |
6272 A library designator. | |
6273 | |
6274 @item library-designator | |
6275 An instance of @code{foreign-library}. | |
6276 @end table | |
6277 | |
6278 @subheading Description | |
6279 | |
6280 Load the library indicated by @var{library-designator}. A @dfn{library | |
6281 designator} is defined as follows: | |
6282 | |
6283 @enumerate | |
6284 @item | |
6285 If a symbol, is considered a name previously defined with | |
6286 @code{define-foreign-library}. | |
6287 | |
6288 @item | |
6289 If a string or pathname, passed as a namestring directly to the | |
6290 implementation's foreign library loader. If that fails, search the | |
6291 directories in @code{*foreign-library-directories*} with | |
6292 @code{cl:probe-file}; if found, the absolute path is passed to the | |
6293 implementation's loader. | |
6294 | |
6295 @item | |
6296 If a list, the meaning depends on @code{(first @var{library})}: | |
6297 | |
6298 @table @code | |
6299 @item :framework | |
6300 The second list element is taken to be a Darwin framework name, which | |
6301 is then searched in @code{*darwin-framework-directories*}, and loaded | |
6302 when found. | |
6303 | |
6304 @item :or | |
6305 Each remaining list element, itself a @dfn{library designator}, is loade… | |
6306 order, until one succeeds. | |
6307 | |
6308 @item :default | |
6309 The name is transformed according to the platform's naming convention | |
6310 to shared libraries, and the resultant string is loaded as a @dfn{library | |
6311 designator}. For example, on @sc{unix}, the name is suffixed with | |
6312 @file{.so}. | |
6313 @end table | |
6314 @end enumerate | |
6315 | |
6316 If the library is already loaded it will be reloaded. | |
6317 | |
6318 If the load fails, signal a @code{load-foreign-library-error}. | |
6319 | |
6320 @strong{Please note:} For system libraries, you should not need to | |
6321 specify the directory containing the library. Each operating system | |
6322 has its own idea of a default search path, and you should rely on it | |
6323 when it is reasonable. | |
6324 | |
6325 @subheading Implementation-specific Notes | |
6326 On ECL platforms where its dynamic FFI is not supported (ie. when | |
6327 @code{:dffi} is not present in @code{*features*}), | |
6328 @code{cffi:load-foreign-library} does not work and you must use ECL's | |
6329 own @code{ffi:load-foreign-library} with a constant string argument. | |
6330 | |
6331 @subheading Examples | |
6332 | |
6333 @xref{Tutorial-Loading,, Loading foreign libraries}. | |
6334 | |
6335 @subheading See Also | |
6336 | |
6337 @seealso{close-foreign-library} @* | |
6338 @seealso{*darwin-framework-directories*} @* | |
6339 @seealso{define-foreign-library} @* | |
6340 @seealso{*foreign-library-directories*} @* | |
6341 @seealso{load-foreign-library-error} @* | |
6342 @seealso{use-foreign-library} | |
6343 | |
6344 | |
6345 @c =================================================================== | |
6346 @c LOAD-FOREIGN-LIBRARY-ERROR | |
6347 | |
6348 @page | |
6349 @node load-foreign-library-error, use-foreign-library, load-foreign-libr… | |
6350 @heading load-foreign-library-error | |
6351 | |
6352 @subheading Syntax | |
6353 | |
6354 @Condition{load-foreign-library-error} | |
6355 | |
6356 @subheading Class precedence list | |
6357 | |
6358 @code{load-foreign-library-error}, @code{error}, | |
6359 @code{serious-condition}, @code{condition}, @code{t} | |
6360 | |
6361 @subheading Description | |
6362 | |
6363 Signalled when a foreign library load completely fails. The exact | |
6364 meaning of this varies depending on the real conditions at work, but | |
6365 almost universally, the implementation's error message is useless. | |
6366 However, @cffi{} does provide the useful restarts @code{retry} and | |
6367 @code{use-value}; invoke the @code{retry} restart to try loading the | |
6368 foreign library again, or the @code{use-value} restart to try loading | |
6369 a different foreign library designator. | |
6370 | |
6371 @subheading See also | |
6372 | |
6373 @seealso{load-foreign-library} | |
6374 | |
6375 | |
6376 @c =================================================================== | |
6377 @c USE-FOREIGN-LIBRARY | |
6378 | |
6379 @page | |
6380 @node use-foreign-library, , load-foreign-library-error, Libraries | |
6381 @heading use-foreign-library | |
6382 | |
6383 @subheading Syntax | |
6384 | |
6385 @Macro{use-foreign-library name} | |
6386 | |
6387 @subheading Arguments and values | |
6388 | |
6389 @table @var | |
6390 @item name | |
6391 A library designator; unevaluated. | |
6392 @end table | |
6393 | |
6394 | |
6395 @subheading Description | |
6396 | |
6397 @xref{load-foreign-library}, for the meaning of ``library | |
6398 designator''. This is intended to be the top-level form used | |
6399 idiomatically after a @code{define-foreign-library} form to go ahead | |
6400 and load the library. @c ; it also sets the ``current foreign library''. | |
6401 Finally, on implementations where the regular evaluation rule is | |
6402 insufficient for foreign library loading, it loads it at the required | |
6403 time.@footnote{Namely, @acronym{CMUCL}. See | |
6404 @code{use-foreign-library} in @file{libraries.lisp} for details.} | |
6405 | |
6406 @c current foreign library is a concept created a few hours ago as of | |
6407 @c this writing. It is not actually used yet, but probably will be. | |
6408 | |
6409 @subheading Examples | |
6410 | |
6411 @xref{Tutorial-Loading,, Loading foreign libraries}. | |
6412 | |
6413 | |
6414 @subheading See also | |
6415 | |
6416 @seealso{load-foreign-library} | |
6417 | |
6418 | |
6419 @c =================================================================== | |
6420 @c CHAPTER: Callbacks | |
6421 | |
6422 @node Callbacks, The Groveller, Libraries, Top | |
6423 @chapter Callbacks | |
6424 | |
6425 @menu | |
6426 Dictionary | |
6427 | |
6428 * callback:: | |
6429 * defcallback:: | |
6430 * get-callback:: | |
6431 @end menu | |
6432 | |
6433 | |
6434 @c =================================================================== | |
6435 @c CALLBACK | |
6436 | |
6437 @page | |
6438 @node callback, defcallback, Callbacks, Callbacks | |
6439 @heading callback | |
6440 @subheading Syntax | |
6441 @Macro{callback symbol @res{} pointer} | |
6442 | |
6443 @subheading Arguments and Values | |
6444 | |
6445 @table @var | |
6446 @item symbol | |
6447 A symbol denoting a callback. | |
6448 | |
6449 @item pointer | |
6450 @itemx new-value | |
6451 A pointer. | |
6452 @end table | |
6453 | |
6454 @subheading Description | |
6455 The @code{callback} macro is analogous to the standard CL special | |
6456 operator @code{function} and will return a pointer to the callback | |
6457 denoted by the symbol @var{name}. | |
6458 | |
6459 @subheading Examples | |
6460 | |
6461 @lisp | |
6462 CFFI> (defcallback sum :int ((a :int) (b :int)) | |
6463 (+ a b)) | |
6464 @result{} SUM | |
6465 CFFI> (callback sum) | |
6466 @result{} #<A Mac Pointer #x102350> | |
6467 @end lisp | |
6468 | |
6469 @subheading See Also | |
6470 @seealso{get-callback} @* | |
6471 @seealso{defcallback} | |
6472 | |
6473 | |
6474 @c =================================================================== | |
6475 @c DEFCALLBACK | |
6476 | |
6477 @page | |
6478 @node defcallback, get-callback, callback, Callbacks | |
6479 @heading defcallback | |
6480 @subheading Syntax | |
6481 @Macro{defcallback name-and-options return-type arguments &body body @re… | |
6482 | |
6483 name-and-options ::= name | (name &key convention) | |
6484 arguments ::= (@{ (arg-name arg-type) @}*) | |
6485 | |
6486 @subheading Arguments and Values | |
6487 | |
6488 @table @var | |
6489 @item name | |
6490 A symbol naming the callback created. | |
6491 | |
6492 @item return-type | |
6493 The foreign type for the callback's return value. | |
6494 | |
6495 @item arg-name | |
6496 A symbol. | |
6497 | |
6498 @item arg-type | |
6499 A foreign type. | |
6500 | |
6501 @item convention | |
6502 One of @code{:cdecl} (default) or @code{:stdcall}. | |
6503 @end table | |
6504 | |
6505 @subheading Description | |
6506 The @code{defcallback} macro defines a Lisp function that can be called | |
6507 from C. The arguments passed to this function will be converted to the | |
6508 appropriate Lisp representation and its return value will be converted | |
6509 to its C representation. | |
6510 | |
6511 This Lisp function can be accessed by the @code{callback} macro or the | |
6512 @code{get-callback} function. | |
6513 | |
6514 @strong{Portability note:} @code{defcallback} will not work correctly | |
6515 on some Lisps if it's not a top-level form. | |
6516 | |
6517 @subheading Examples | |
6518 | |
6519 @lisp | |
6520 (defcfun "qsort" :void | |
6521 (base :pointer) | |
6522 (nmemb :int) | |
6523 (size :int) | |
6524 (fun-compar :pointer)) | |
6525 | |
6526 (defcallback < :int ((a :pointer) (b :pointer)) | |
6527 (let ((x (mem-ref a :int)) | |
6528 (y (mem-ref b :int))) | |
6529 (cond ((> x y) 1) | |
6530 ((< x y) -1) | |
6531 (t 0)))) | |
6532 | |
6533 CFFI> (with-foreign-object (array :int 10) | |
6534 ;; @lispcmt{Initialize array.} | |
6535 (loop for i from 0 and n in '(7 2 10 4 3 5 1 6 9 8) | |
6536 do (setf (mem-aref array :int i) n)) | |
6537 ;; @lispcmt{Sort it.} | |
6538 (qsort array 10 (foreign-type-size :int) (callback <)) | |
6539 ;; @lispcmt{Return it as a list.} | |
6540 (loop for i from 0 below 10 | |
6541 collect (mem-aref array :int i))) | |
6542 @result{} (1 2 3 4 5 6 7 8 9 10) | |
6543 @end lisp | |
6544 | |
6545 @subheading See Also | |
6546 @seealso{callback} @* | |
6547 @seealso{get-callback} | |
6548 | |
6549 | |
6550 @c =================================================================== | |
6551 @c GET-CALLBACK | |
6552 | |
6553 @page | |
6554 @node get-callback, , defcallback, Callbacks | |
6555 @heading get-callback | |
6556 @subheading Syntax | |
6557 @Accessor{get-callback symbol @res{} pointer} | |
6558 | |
6559 @subheading Arguments and Values | |
6560 | |
6561 @table @var | |
6562 @item symbol | |
6563 A symbol denoting a callback. | |
6564 | |
6565 @item pointer | |
6566 A pointer. | |
6567 @end table | |
6568 | |
6569 @subheading Description | |
6570 This is the functional version of the @code{callback} macro. It | |
6571 returns a pointer to the callback named by @var{symbol} suitable, for | |
6572 example, to pass as arguments to foreign functions. | |
6573 | |
6574 @subheading Examples | |
6575 | |
6576 @lisp | |
6577 CFFI> (defcallback sum :int ((a :int) (b :int)) | |
6578 (+ a b)) | |
6579 @result{} SUM | |
6580 CFFI> (get-callback 'sum) | |
6581 @result{} #<A Mac Pointer #x102350> | |
6582 @end lisp | |
6583 | |
6584 @subheading See Also | |
6585 @seealso{callback} @* | |
6586 @seealso{defcallback} | |
6587 | |
6588 | |
6589 @c =================================================================== | |
6590 @c CHAPTER: The Groveller | |
6591 | |
6592 @node The Groveller, Limitations, Callbacks, Top | |
6593 @chapter The Groveller | |
6594 | |
6595 @cffi{}-Grovel is a tool which makes it easier to write @cffi{} | |
6596 declarations for libraries that are implemented in C. That is, it | |
6597 grovels through the system headers, getting information about types | |
6598 and structures, so you don't have to. This is especially important | |
6599 for libraries which are implemented in different ways by different | |
6600 vendors, such as the @sc{unix}/@sc{posix} functions. The @cffi{} | |
6601 declarations are usually quite different from platform to platform, | |
6602 but the information you give to @cffi{}-Grovel is the same. Hence, | |
6603 much less work is required! | |
6604 | |
6605 If you use @acronym{ASDF}, @cffi{}-Grovel is integrated, so that it | |
6606 will run automatically when your system is building. This feature was | |
6607 inspired by SB-Grovel, a similar @acronym{SBCL}-specific project. | |
6608 @cffi{}-Grovel can also be used without @acronym{ASDF}. | |
6609 | |
6610 @section Building FFIs with CFFI-Grovel | |
6611 | |
6612 @cffi{}-Grovel uses a specification file (*.lisp) describing the | |
6613 features that need groveling. The C compiler is used to retrieve this | |
6614 data and write a Lisp file (*.cffi.lisp) which contains the necessary | |
6615 @cffi{} definitions to access the variables, structures, constants, and | |
6616 enums mentioned in the specification. | |
6617 | |
6618 @c This is most similar to the SB-Grovel package, upon which it is | |
6619 @c based. Unlike SB-Grovel, we do not currently support defining | |
6620 @c regular foreign functions in the specification file; those are best | |
6621 @c defined in normal Lisp code. | |
6622 | |
6623 @cffi{}-Grovel provides an @acronym{ASDF} component for handling the | |
6624 necessary calls to the C compiler and resulting file management. | |
6625 | |
6626 @c See the included CFFI-Unix package for an example of how to | |
6627 @c integrate a specification file with ASDF-built packages. | |
6628 | |
6629 @menu | |
6630 * Groveller Syntax:: How grovel files should look like. | |
6631 * Groveller ASDF Integration:: ASDF components for grovel files. | |
6632 * Groveller Implementation Notes:: Implementation notes. | |
6633 * Wrapper for Inline/Static Functions and Macros:: Wrapper | |
6634 @end menu | |
6635 | |
6636 @node Groveller Syntax, Groveller ASDF Integration, The Groveller, The G… | |
6637 @section Specification File Syntax | |
6638 | |
6639 The specification files are read by the normal Lisp reader, so they | |
6640 have syntax very similar to normal Lisp code. In particular, | |
6641 semicolon-comments and reader-macros will work as expected. | |
6642 | |
6643 There are several forms recognized by @cffi{}-Grovel: | |
6644 | |
6645 @deffn {Grovel Form} progn &rest forms | |
6646 | |
6647 Processes a list of forms. Useful for conditionalizing several | |
6648 forms. For example: | |
6649 @end deffn | |
6650 | |
6651 @lisp | |
6652 #+freebsd | |
6653 (progn | |
6654 (constant (ev-enable "EV_ENABLE")) | |
6655 (constant (ev-disable "EV_DISABLE"))) | |
6656 @end lisp | |
6657 | |
6658 @deffn {Grovel Form} include &rest files | |
6659 | |
6660 Include the specified files (specified as strings) in the generated C | |
6661 source code. | |
6662 @end deffn | |
6663 | |
6664 @deffn {Grovel Form} in-package symbol | |
6665 | |
6666 Set the package to be used for the final Lisp output. | |
6667 @end deffn | |
6668 | |
6669 @deffn {Grovel Form} ctype lisp-name size-designator | |
6670 | |
6671 Define a @cffi{} foreign type for the string in @var{size-designator}, | |
6672 e.g. @code{(ctype :pid "pid_t")}. | |
6673 @end deffn | |
6674 | |
6675 @deffn {Grovel Form} constant (lisp-name &rest c-names) &key type docume… | |
6676 | |
6677 Search for the constant named by the first @var{c-name} string found | |
6678 to be known to the C preprocessor and define it as @var{lisp-name}. | |
6679 | |
6680 The @var{type} keyword argument specifies how to grovel the constant: | |
6681 either @code{integer} (the default) or @code{double-float}. If | |
6682 @var{optional} is true, no error will be raised if all the | |
6683 @var{c-names} are unknown. If @var{lisp-name} is a keyword, the actual | |
6684 constant will be a symbol of the same name interned in the current | |
6685 package. | |
6686 @end deffn | |
6687 | |
6688 @deffn {Grovel Form} feature lisp-feature-name c-name &key feature-list | |
6689 | |
6690 Adds @var{lisp-feature-name} to the list @var{feature-list} if the @var{… | |
6691 string is known to the C preprocessor. @var{feature-list} defaults | |
6692 to @code{cl:*features*}. | |
6693 @end deffn | |
6694 | |
6695 @deffn {Grovel Form} define name &optional value | |
6696 | |
6697 Defines an additional C preprocessor symbol, which is useful for | |
6698 altering the behavior of included system headers. | |
6699 @end deffn | |
6700 | |
6701 @deffn {Grovel Form} cc-flags &rest flags | |
6702 | |
6703 Adds @var{cc-flags} to the command line arguments used for the C compiler | |
6704 invocation. | |
6705 @end deffn | |
6706 | |
6707 @deffn {Grovel Form} pkg-config-cflags pkg &key optional | |
6708 | |
6709 Adds @var{pkg} to the command line arguments for the external program | |
6710 @code{pkg-config} and runs it to retrieve the relevant include flags | |
6711 used for the C compiler invocation. This syntax can be used instead of | |
6712 hard-coding paths using @code{cc-flags}, and ensures that include | |
6713 flags are added correctly on the build system. Assumes | |
6714 @code{pkg-config} is installed and working. @var{pkg} is a string | |
6715 that identifies an installed @code{pkg-config} package. See the | |
6716 pkg-config manual for more information. If @var{optional} is true, | |
6717 failure to execute @code{pkg-config} does @emph{not} abort | |
6718 compilation. | |
6719 @end deffn | |
6720 | |
6721 @deffn {Grovel Form} cstruct lisp-name c-name slots | |
6722 | |
6723 Define a @cffi{} foreign struct with the slot data specfied. Slots | |
6724 are of the form @code{(lisp-name c-name &key type count (signed t))}. | |
6725 @end deffn | |
6726 | |
6727 @deffn {Grovel Form} cunion lisp-name c-name slots | |
6728 | |
6729 Identical to @code{cstruct}, but defines a @cffi{} foreign union. | |
6730 @end deffn | |
6731 | |
6732 @deffn {Grovel Form} cstruct-and-class c-name slots | |
6733 | |
6734 Defines a @cffi{} foreign struct, as with @code{cstruct} and defines a | |
6735 @acronym{CLOS} class to be used with it. This is useful for mapping | |
6736 foreign structures to application-layer code that shouldn't need to | |
6737 worry about memory allocation issues. | |
6738 @end deffn | |
6739 | |
6740 @deffn {Grovel Form} cvar namespec type &key read-only | |
6741 | |
6742 Defines a foreign variable of the specified type, even if that | |
6743 variable is potentially a C preprocessor pseudo-variable. e.g. | |
6744 @code{(cvar ("errno" errno) errno-values)}, assuming that errno-values | |
6745 is an enum or equivalent to type @code{:int}. | |
6746 | |
6747 The @var{namespec} is similar to the one used in @ref{defcvar}. | |
6748 @end deffn | |
6749 | |
6750 @deffn {Grovel Form} cenum name-and-opts &rest elements | |
6751 | |
6752 Defines a true C enum, with elements specified as @code{((lisp-name | |
6753 &rest c-names) &key optional documentation)}. | |
6754 @var{name-and-opts} can be either a symbol as name, or a list | |
6755 @code{(name &key base-type define-constants)}. If @var{define-constants} | |
6756 is non-null, a Lisp constant will be defined for each enum member. | |
6757 @end deffn | |
6758 | |
6759 @deffn {Grovel Form} constantenum name-and-opts &rest elements | |
6760 | |
6761 Defines an enumeration of pre-processor constants, with elements | |
6762 specified as @code{((lisp-name &rest c-names) &key optional | |
6763 documentation)}. | |
6764 @var{name-and-opts} can be either a symbol as name, or a list | |
6765 @code{(name &key base-type define-constants)}. If @var{define-constants} | |
6766 is non-null, a Lisp constant will be defined for each enum member. | |
6767 | |
6768 This example defines @code{:af-inet} to represent the value held by | |
6769 @code{AF_INET} or @code{PF_INET}, whichever the pre-processor finds | |
6770 first. Similarly for @code{:af-packet}, but no error will be | |
6771 signalled if the platform supports neither @code{AF_PACKET} nor | |
6772 @code{PF_PACKET}. | |
6773 @end deffn | |
6774 | |
6775 @lisp | |
6776 (constantenum address-family | |
6777 ((:af-inet "AF_INET" "PF_INET") | |
6778 :documentation "IPv4 Protocol family") | |
6779 ((:af-local "AF_UNIX" "AF_LOCAL" "PF_UNIX" "PF_LOCAL") | |
6780 :documentation "File domain sockets") | |
6781 ((:af-inet6 "AF_INET6" "PF_INET6") | |
6782 :documentation "IPv6 Protocol family") | |
6783 ((:af-packet "AF_PACKET" "PF_PACKET") | |
6784 :documentation "Raw packet access" | |
6785 :optional t)) | |
6786 @end lisp | |
6787 | |
6788 @deffn {Grovel Form} bitfield name-and-opts &rest elements | |
6789 | |
6790 Defines a bitfield, with elements specified as @code{((lisp-name &rest | |
6791 c-names) &key optional documentation)}. @var{name-and-opts} can be eith… | |
6792 symbol as name, or a list @code{(name &key base-type)}. For example: | |
6793 @end deffn | |
6794 | |
6795 @lisp | |
6796 (bitfield flags-ctype | |
6797 ((:flag-a "FLAG_A") | |
6798 :documentation "DOCU_A") | |
6799 ((:flag-b "FLAG_B" "FLAG_B_ALT") | |
6800 :documentation "DOCU_B") | |
6801 ((:flag-c "FLAG_C") | |
6802 :documentation "DOCU_C" | |
6803 :optional t)) | |
6804 @end lisp | |
6805 | |
6806 | |
6807 @c =================================================================== | |
6808 @c SECTION: Groveller ASDF Integration | |
6809 | |
6810 @node Groveller ASDF Integration, Groveller Implementation Notes, Grovel… | |
6811 @section ASDF Integration | |
6812 | |
6813 An example software project might contain four files; an | |
6814 @acronym{ASDF} file, a package definition file, an implementation | |
6815 file, and a @cffi{}-Grovel specification file. | |
6816 | |
6817 The @acronym{ASDF} file defines the system and its dependencies. | |
6818 Notice the use of @code{eval-when} to ensure @cffi{}-Grovel is present | |
6819 and the use of @code{(cffi-grovel:grovel-file name &key cc-flags)} | |
6820 instead of @code{(:file name)}. | |
6821 | |
6822 The @file{example-software.asd} file would look like that: | |
6823 | |
6824 @lisp | |
6825 ;;; @lispcmt{CFFI-Grovel is needed for processing grovel-file components} | |
6826 (defsystem "example-software" | |
6827 :defsystem-depends-on ("cffi-grovel") | |
6828 :depends-on ("cffi") | |
6829 :serial t | |
6830 :components | |
6831 ((:file "package") | |
6832 (:cffi-grovel-file "example-grovelling") | |
6833 (:cffi-wrapper-file "example-wrappers") | |
6834 (:file "example"))) | |
6835 @end lisp | |
6836 | |
6837 The @file{package.lisp} file would contain one or several | |
6838 @code{defpackage} forms, to remove circular dependencies and make | |
6839 building the project easier. Note that you may or may not want to | |
6840 @code{:use} your internal package. | |
6841 | |
6842 @impnote{Note that it's a not a good idea to @code{:use} when names may | |
6843 clash with, say, CL symbols. | |
6844 Or you could use @code{uiop:define-package} and its @code{:mix} option.} | |
6845 | |
6846 @lisp | |
6847 (defpackage #:example-internal | |
6848 (:use) | |
6849 (:nicknames #:exampleint)) | |
6850 | |
6851 (defpackage #:example-software | |
6852 (:export ...) | |
6853 (:use #:cl #:cffi #:exampleint)) | |
6854 @end lisp | |
6855 | |
6856 The internal package is created by Lisp code output from the C program | |
6857 written by @cffi{}-Grovel; if your specification file is | |
6858 @file{exampleint.lisp}, the @file{exampleint.cffi.lisp} file will contai… | |
6859 @cffi{} definitions needed by the rest of your project. | |
6860 @xref{Groveller Syntax}. | |
6861 | |
6862 @node Groveller Implementation Notes, Wrapper for Inline/Static Functio… | |
6863 @section Implementation Notes | |
6864 | |
6865 @cffi{}-Grovel will generate many files that not only architecture-speci… | |
6866 but also implementation-specific, and should not be distributed. | |
6867 ASDF will generate these files in its output cache; | |
6868 if you build with multiple architectures (e.g. with NFS/AFS home | |
6869 directories) or implementations, it is critical for avoiding clashes | |
6870 to keep this cache in an implementation-dependent directory (as is the | |
6871 default). | |
6872 | |
6873 For @code{foo-internal.lisp}, the resulting @code{foo-internal.c}, | |
6874 @code{foo-internal}, and @code{foo-internal.cffi.lisp} are all | |
6875 platform-specific, either because of possible reader-macros in | |
6876 foo-internal.lisp, or because of varying C environments on the host | |
6877 system. For this reason, it is not helpful to distribute any of those | |
6878 files; end users building @cffi{}-Grovel based software will need | |
6879 @code{cffi}-Grovel anyway. | |
6880 | |
6881 @impnote{For now, after some experimentation with @sc{clisp} having no | |
6882 long-long, it seems appropriate to assert that the generated @code{.c} | |
6883 files are architecture and operating-system dependent, but | |
6884 lisp-implementation independent. This way the same @code{.c} file | |
6885 (and so the same @code{.grovel-tmp.lisp} file) will be shareable | |
6886 between the implementations running on a given system.} | |
6887 | |
6888 @c TODO: document the new wrapper stuff. | |
6889 | |
6890 @node Wrapper for Inline/Static Functions and Macros, , Groveller Imple… | |
6891 @section Wrapper for Inline/Static Functions and Macros | |
6892 | |
6893 In a shared library, information in static/inlined functions and | |
6894 macros are already removed during the compilation. Wrapper file | |
6895 enables to write an uninlined function wrapping the call to them. | |
6896 | |
6897 A wrapper file compilation/loading proceeds as follows: | |
6898 Unlike groveller which generates C code that emits lisp files | |
6899 containing cffi definitions, it generates C code, compiles it as a | |
6900 shared library, loads the library, generate the cffi definitions (as | |
6901 lisp code) and then loads the lisp code. | |
6902 | |
6903 It has asdf integration similar to groveller. | |
6904 | |
6905 @lisp | |
6906 (defsystem "example-software" | |
6907 :defsystem-depends-on ("cffi-grovel") | |
6908 :depends-on ("cffi") | |
6909 :serial t | |
6910 :components | |
6911 ((:file "package") | |
6912 (:cffi-grovel-file "example-grovelling") | |
6913 (:cffi-wrapper-file "example-wrappers") ;; <<--- this part | |
6914 (:file "example"))) | |
6915 @end lisp | |
6916 | |
6917 @deffn {Wrapper Form} defwrapper name-and-options return-type &rest args | |
6918 @end deffn | |
6919 | |
6920 @example | |
6921 static inline int foo(int i) @{ | |
6922 return 1+i; | |
6923 @}; | |
6924 #define bar(i) (1+(i)) | |
6925 @end example | |
6926 | |
6927 @lisp | |
6928 (in-package :mypackage) | |
6929 (defwrapper ("foo" foo) :int | |
6930 (i :int)) | |
6931 (defwrapper ("bar" bar) :int | |
6932 (i :int)) | |
6933 @end lisp | |
6934 | |
6935 Other forms are similar to grovel files. | |
6936 | |
6937 @deffn {Wrapper Form} progn &rest forms | |
6938 | |
6939 Processes a list of forms. Useful for conditionalizing several | |
6940 forms. For example: | |
6941 @end deffn | |
6942 | |
6943 @lisp | |
6944 #+freebsd | |
6945 (progn | |
6946 (constant (ev-enable "EV_ENABLE")) | |
6947 (constant (ev-disable "EV_DISABLE"))) | |
6948 @end lisp | |
6949 | |
6950 @deffn {Wrapper Form} include &rest files | |
6951 | |
6952 Include the specified files (specified as strings) in the generated C | |
6953 source code. | |
6954 @end deffn | |
6955 | |
6956 @deffn {Wrapper Form} in-package symbol | |
6957 | |
6958 Set the package to be used for the final Lisp output. | |
6959 @end deffn | |
6960 | |
6961 @deffn {Wrapper Form} flags &rest flags | |
6962 | |
6963 Adds @var{cc-flags} to the command line arguments used for the C compiler | |
6964 invocation. | |
6965 @end deffn | |
6966 | |
6967 @deffn {Wrapper Form} proclaim &rest proclaimations | |
6968 @end deffn | |
6969 @deffn {Wrapper Form} declaim &rest declaimations | |
6970 @end deffn | |
6971 | |
6972 | |
6973 | |
6974 @c =================================================================== | |
6975 @c CHAPTER: Static Linking | |
6976 | |
6977 @node Static Linking, Limitations, The Groveller, Top | |
6978 @chapter Static Linking | |
6979 | |
6980 On recent enough versions of supported implementations (currently, | |
6981 GNU CLISP 2.49, CMUCL 2015-11, and SBCL 1.2.17), and with a recent | |
6982 enough ASDF (3.1.2 or later), you can create a statically linked | |
6983 Lisp executable image that includes all the C extensions | |
6984 (wrappers and any other objects output by @code{compile-op}) | |
6985 as well as your Lisp code --- or a standalone application executable. | |
6986 This makes it easier to deliver your code as a single file. | |
6987 | |
6988 To dump a statically linked executable image, use: | |
6989 | |
6990 @lisp | |
6991 (asdf:load-system :cffi-grovel) | |
6992 (asdf:operate :static-image-op :example-software) | |
6993 @end lisp | |
6994 | |
6995 To dump a statically linked executable standalone application, use: | |
6996 | |
6997 @lisp | |
6998 (asdf:load-system :cffi-grovel) | |
6999 (asdf:operate :static-program-op :example-software) | |
7000 @end lisp | |
7001 | |
7002 See @uref{https://common-lisp.net/project/asdf/,,the ASDF | |
7003 manual} for documentation about @code{image-op} and @code{program-op} | |
7004 which are the parent operation classes that behave similarly except | |
7005 they don't statically link C code. | |
7006 | |
7007 @impnote{There is also an operation @code{:static-runtime-op} to create … | |
7008 statically linked runtime alone, but it's admittedly not very useful | |
7009 except as an intermediate step dependency towards building | |
7010 @code{:static-image-op} or @code{:static-program-op}.} | |
7011 | |
7012 | |
7013 | |
7014 @c =================================================================== | |
7015 @c CHAPTER: Limitations | |
7016 | |
7017 @node Limitations, Platform-specific features, The Groveller, Top | |
7018 @chapter Limitations | |
7019 | |
7020 These are @cffi{}'s limitations across all platforms; for information | |
7021 on the warts on particular Lisp implementations, see | |
7022 @ref{Implementation Support}. | |
7023 | |
7024 @itemize @bullet | |
7025 @item | |
7026 The tutorial includes a treatment of the primary, intractable | |
7027 limitation of @cffi{}, or any @acronym{FFI}: that the abstractions | |
7028 commonly used by C are insufficiently expressive. | |
7029 @xref{Tutorial-Abstraction,, Breaking the abstraction}, for more | |
7030 details. | |
7031 | |
7032 @end itemize | |
7033 | |
7034 | |
7035 @node Platform-specific features, Glossary, Limitations, Top | |
7036 @appendix Platform-specific features | |
7037 | |
7038 Whenever a backend doesn't support one of @cffi{}'s features, a | |
7039 specific symbol is pushed onto @code{common-lisp:*features*}. The | |
7040 meanings of these symbols follow. | |
7041 | |
7042 @table @var | |
7043 @item cffi-sys::flat-namespace | |
7044 This Lisp has a flat namespace for foreign symbols meaning that you | |
7045 won't be able to load two different libraries with homograph functions | |
7046 and successfully differentiate them through the @code{:library} | |
7047 option to @code{defcfun}, @code{defcvar}, etc@dots{} | |
7048 | |
7049 @item cffi-sys::no-foreign-funcall | |
7050 The macro @code{foreign-funcall} is @strong{not} available. On such | |
7051 platforms, the only way to call a foreign function is through | |
7052 @code{defcfun}. @xref{foreign-funcall}, and @ref{defcfun}. | |
7053 | |
7054 @item cffi-sys::no-long-long | |
7055 The C @code{long long} type is @strong{not} available as a foreign | |
7056 type. | |
7057 | |
7058 However, on such platforms @cffi{} provides its own implementation of | |
7059 the @code{long long} type for all of operations in chapters | |
7060 @ref{Foreign Types}, @ref{Pointers} and @ref{Variables}. The | |
7061 functionality described in @ref{Functions} and @ref{Callbacks} will | |
7062 not be available. | |
7063 | |
7064 32-bit Lispworks 5.0+ is an exception. In addition to the @cffi{} | |
7065 implementation described above, Lispworks itself implements the | |
7066 @code{long long} type for @ref{Functions}. @ref{Callbacks} are still | |
7067 missing @code{long long} support, though. | |
7068 | |
7069 @item cffi-sys::no-stdcall | |
7070 This Lisp doesn't support the @code{stdcall} calling convention. Note | |
7071 that it only makes sense to support @code{stdcall} on (32-bit) x86 | |
7072 platforms. | |
7073 | |
7074 @end table | |
7075 | |
7076 | |
7077 @node Glossary, Comprehensive Index, Platform-specific features, Top | |
7078 @appendix Glossary | |
7079 | |
7080 @table @dfn | |
7081 @item aggregate type | |
7082 A @cffi{} type for C data defined as an organization of data of simple | |
7083 type; in structures and unions, which are themselves aggregate types, | |
7084 they are represented by value. | |
7085 | |
7086 @item foreign value | |
7087 This has two meanings; in any context, only one makes sense. | |
7088 | |
7089 When using type translators, the foreign value is the lower-level Lisp | |
7090 value derived from the object passed to @code{translate-to-foreign} | |
7091 (@pxref{translate-to-foreign}). This value should be a Lisp number or | |
7092 a pointer (satisfies @code{pointerp}), and it can be treated like any | |
7093 general Lisp object; it only completes the transformation to a true | |
7094 foreign value when passed through low-level code in the Lisp | |
7095 implementation, such as the foreign function caller or indirect memory | |
7096 addressing combined with a data move. | |
7097 | |
7098 In other contexts, this refers to a value accessible by C, but which | |
7099 may only be accessed through @cffi{} functions. The closest you can | |
7100 get to such a foreign value is through a pointer Lisp object, which | |
7101 itself counts as a foreign value in only the previous sense. | |
7102 | |
7103 @item simple type | |
7104 A @cffi{} type that is ultimately represented as a builtin type; | |
7105 @cffi{} only provides extra semantics for Lisp that are invisible to C | |
7106 code or data. | |
7107 @end table | |
7108 | |
7109 @node Comprehensive Index, , Glossary, Top | |
7110 @unnumbered Index | |
7111 @printindex cp | |
7112 | |
7113 @bye |