cffi-manual.texinfo - clic - Clic is an command line interactive client for gopher written in Common LISP
(HTM) git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/clic/
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
(DIR) LICENSE
---
cffi-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 translator.
175 * convert-to-foreign:: Outside interface to forward type translator.
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 type.
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 foreign struct.
189 * foreign-slot-offset:: Returns the offset of a slot in a foreign struct.
190 * foreign-slot-pointer:: Returns a pointer to a slot in a foreign struct.
191 * foreign-slot-value:: Returns the value of a slot in a foreign struct.
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 deallocators.
195 * free-translated-object:: Defines how to free a oreign object.
196 * translate-from-foreign:: Defines a foreign-to-Lisp object translation.
197 * translate-to-foreign:: Defines a Lisp-to-foreign object translation.
198 * with-foreign-object:: Allocates a foreign object with dynamic extent.
199 * with-foreign-objects:: Plural form of @code{with-foreign-object}.
200 * with-foreign-slots:: Accesses the slots of a foreign structure.
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 place.
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 array.
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 not.
216 * pointer-address:: Returns the address pointed to by a pointer.
217 * pointer-eq:: Tests if two pointers point to the same address.
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 string.
224 * foreign-string-free:: Deallocates memory used by a foreign string.
225 * foreign-string-to-lisp:: Converts a foreign string to a Lisp string.
226 * lisp-string-to-foreign:: Copies a Lisp string into a foreign string.
227 * with-foreign-string:: Allocates a foreign string with dynamic extent.
228 * with-foreign-strings:: Plural form of @code{with-foreign-string}.
229 * with-foreign-pointer-as-string:: Similar to CL's with-output-to-string.
230
231 Variables
232
233 * defcvar:: Defines a C global variable.
234 * get-var-pointer:: Returns a pointer to a defined global variable.
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 pointer.
241 * translate-camelcase-name:: Converts a camelCase foreign name to/from a Lisp name.
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_separated foreign name to/from a Lisp name.
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-generated
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, Tutorial
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-tutorial(3)}
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, Tutorial
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} function to
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, Tutorial
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, Tutorial
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_setopt, Tutorial
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, Tutorial
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, Tutorial
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 the}
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, Foreign Types
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 Foreign Types, Foreign Types
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 Translators, Foreign Types
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 Type Translators, Foreign Types
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 person))
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 all
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-aptr}.
2393
2394 See @ref{defcstruct} for more details.
2395
2396 @node Allocating Foreign Objects, convert-from-foreign, Foreign Structure Types, Foreign Types
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 Objects, Foreign Types
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 Types
2463 @heading convert-to-foreign
2464 @subheading Syntax
2465 @Function{convert-to-foreign value type @res{} foreign-value, alloc-params}
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 structure.}
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 about>}
2705 (z :char :offset 24)) ; @lispcmt{a char at offset 24}
2706 ; @lispcmt{<7 more bytes ignored (since size is 32)>}
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{} class-name}
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, Foreign Types
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-method, Foreign Types
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-symbols, Foreign Types
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, Foreign Types
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, Foreign Types
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, Foreign Types
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, Foreign Types
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, Foreign Types
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 lisp.}
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, Foreign Types
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, Foreign Types
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, Foreign Types
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, Foreign Types
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-object, Foreign Types
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-object, Foreign Types
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-from-foreign, Foreign Types
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-foreign, Foreign Types
3730 @heading translate-into-foreign-memory
3731 @subheading Syntax
3732 @GenericFunction{translate-into-foreign-memory lisp-value type-name pointer}
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 type defined by @code{defctype}.
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, Pointers
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 Operations, Pointers
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, Pointers
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 (count 1) @
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 of memory.}
4017
4018 CFFI> (foreign-alloc :char :count 20)
4019 @result{} #<A Mac Pointer #x1024A0> ; @lispcmt{A pointer to 20 bytes of memory.}
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 memory}
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 null pointer)}
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{} pointer}
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 array.
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 require
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" :string)
4794 "f"
4795 CFFI> (let ((*default-foreign-encoding* :utf-16))
4796 (foreign-funcall "strdup" (:string :encoding :utf-16) "foo" :string))
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-encoding*, Strings
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, Strings
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-free, Strings
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 0.
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-lisp, Strings
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-to-foreign, Strings
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{} string}
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-name}
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 looks
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-NUMBER+.}
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 [&rest] @
5279 @res{} lisp-name}
5280
5281 @var{name-and-options} ::= @var{name} | (@var{name} &key @var{library} @var{convention}) @*
5282 @var{name} ::= @var{lisp-name} [@var{foreign-name}] | @var{foreign-name} [@var{lisp-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 system
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-value}
5401
5402 @var{arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] @*
5403 @var{name-and-options} ::= @var{name} | (@var{name} &key @var{library} @var{convention}) @*
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 system
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, Functions
5504 @heading foreign-funcall-pointer
5505 @subheading Syntax
5506 @Macro{foreign-funcall-pointer pointer options &rest arguments @res{} return-value}
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-funcall-pointer, Functions
5568 @heading foreign-funcall-varargs
5569 @subheading Syntax
5570 @Macro{foreign-funcall-varargs name-and-options (fixed-arguments) &rest arguments @res{} return-value}
5571
5572 @var{fixed-arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] @*
5573 @var{arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] @*
5574 @var{name-and-options} ::= @var{name} | (@var{name} &key @var{library} @var{convention}) @*
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-funcall-varargs, Functions
5624 @heading foreign-funcall-pointer-varargs
5625 @subheading Syntax
5626 @Macro{foreign-funcall-pointer-varargs pointer options (fixed-arguments) &rest arguments @res{} return-value}
5627
5628 @var{fixed-arguments} ::= @{ @var{arg-type} @var{arg} @}* [@var{return-type}] @*
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-funcall-pointer-varargs, Functions
5677 @heading translate-camelcase-name
5678 @subheading Syntax
5679 @Function{translate-camelcase-name name &key upper-initial-p special-words @res{} return-value}
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-camelcase-name, Functions
5733 @heading translate-name-from-foreign
5734 @subheading Syntax
5735 @Function{translate-name-from-foreign foreign-name package &optional varp @res{} symbol}
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 #<Package "SOME-PACKAGE">))>
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, translate-name-from-foreign, Functions
5791 @heading translate-name-to-foreign
5792 @subheading Syntax
5793 @Function{translate-name-to-foreign lisp-name package &optional varp @res{} string}
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 #<Package "SOME-PACKAGE">))>
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, Functions
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 library, Libraries
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 definition style, Libraries
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-foreign-library, Libraries
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-framework-directories*, Libraries
6053 @heading define-foreign-library
6054
6055 @subheading Syntax
6056
6057 @Macro{define-foreign-library name-and-options @{ load-clause @}* @res{} name}
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 in
6079 system-global directories. Paths specified in a load clause take priority over
6080 paths specified as library option, with *foreign-library-directories* having
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-foreign-library, Libraries
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.html,,
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-directories*, Libraries
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 loaded in
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-library, Libraries
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 @res{} name}
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 Groveller
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 documentation optional
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{c-name}
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 either a
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, Groveller Syntax, The Groveller
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 contain the
6859 @cffi{} definitions needed by the rest of your project.
6860 @xref{Groveller Syntax}.
6861
6862 @node Groveller Implementation Notes, Wrapper for Inline/Static Functions and Macros, Groveller ASDF Integration, The Groveller
6863 @section Implementation Notes
6864
6865 @cffi{}-Grovel will generate many files that not only architecture-specific,
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 Implementation Notes, The Groveller
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 the
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