1 \input texinfo @c -*- Mode: Texinfo; Mode: auto-fill -*-
4 @settitle CFFI User Manual
7 @c @documentencoding utf-8
12 * The reference section names and "See Also" list are roman, not
13 @code. This is to follow the format of CLHS.
15 * How it looks in HTML is the priority.
18 @c ============================= Macros =============================
19 @c The following macros are used throughout this manual.
21 @macro Function {args}
31 @macro Accessor {args}
32 @deffn {Accessor} \args\
36 @macro GenericFunction {args}
37 @deffn {Generic Function} \args\
41 @macro ForeignType {args}
42 @deftp {Foreign Type} \args\
46 @macro Variable {args}
47 @defvr {Special Variable} \args\
51 @macro Condition {args}
52 @deftp {Condition Type} \args\
62 @strong{Implementor's note:} @emph{\text\}
66 @c Info "requires" that x-refs end in a period or comma, or ) in the
67 @c case of @pxref. So the following implements that requirement for
68 @c the "See also" subheadings that permeate this manual, but only in
80 @c Set ROMANCOMMENTS to get comments in roman font.
84 @ifclear ROMANCOMMENTS
89 @c ============================= Macros =============================
92 @c Show types, functions, and concepts in the same index.
97 Copyright @copyright{} 2005 James Bielman <jamesjb at jamesjb.com> @*
98 Copyright @copyright{} 2005-2007 Lu@'{@dotless{i}}s Oliveira
99 <loliveira at common-lisp.net> @*
100 Copyright @copyright{} 2006 Stephen Compall <s11 at member.fsf.org>
103 Permission is hereby granted, free of charge, to any person obtaining
104 a copy of this software and associated documentation files (the
105 ``Software''), to deal in the Software without restriction, including
106 without limitation the rights to use, copy, modify, merge, publish,
107 distribute, sublicense, and/or sell copies of the Software, and to
108 permit persons to whom the Software is furnished to do so, subject to
109 the following conditions:
111 The above copyright notice and this permission notice shall be
112 included in all copies or substantial portions of the Software.
114 @sc{The software is provided ``as is'', without warranty of any kind,
115 express or implied, including but not limited to the warranties of
116 merchantability, fitness for a particular purpose and noninfringement.
117 In no event shall the authors or copyright holders be liable for any
118 claim, damages or other liability, whether in an action of contract,
119 tort or otherwise, arising from, out of or in connection with the
120 software or the use or other dealings in the software.}
126 @title CFFI User Manual
127 @c @subtitle Version X.X
128 @c @author James Bielman
131 @vskip 0pt plus 1filll
144 * Introduction:: What is CFFI?
145 * Implementation Support::
146 * Tutorial:: Interactive intro to using CFFI.
147 * Wrapper generators:: CFFI forms from munging C source code.
156 * Platform-specific features:: Details about the underlying system.
157 * Glossary:: List of CFFI-specific terms and meanings.
158 * Comprehensive Index::
165 * convert-from-foreign:: Outside interface to backward type translator.
166 * convert-to-foreign:: Outside interface to forward type translator.
167 * defbitfield:: Defines a bitfield.
168 * defcstruct:: Defines a C structure type.
169 * defcunion:: Defines a C union type.
170 * defctype:: Defines a foreign typedef.
171 * defcenum:: Defines a C enumeration.
172 * define-foreign-type:: Defines a foreign type specifier.
173 * define-parse-method:: Specifies how a type should be parsed.
174 @c * explain-foreign-slot-value:: <unimplemented>
175 * foreign-bitfield-symbols:: Returns a list of symbols for a bitfield type.
176 * foreign-bitfield-value:: Calculates a value for a bitfield type.
177 * foreign-enum-keyword:: Finds a keyword in an enum type.
178 * foreign-enum-value:: Finds a value in an enum type.
179 * foreign-slot-names:: Returns a list of slot names in a foreign struct.
180 * foreign-slot-offset:: Returns the offset of a slot in a foreign struct.
181 * foreign-slot-pointer:: Returns a pointer to a slot in a foreign struct.
182 * foreign-slot-value:: Returns the value of a slot in a foreign struct.
183 * foreign-type-alignment:: Returns the alignment of a foreign type.
184 * foreign-type-size:: Returns the size of a foreign type.
185 * free-converted-object:: Outside interface to typed object deallocators.
186 * free-translated-object:: Free a type translated foreign object.
187 * translate-from-foreign:: Translate a foreign object to a Lisp object.
188 * translate-to-foreign:: Translate a Lisp object to a foreign object.
189 * with-foreign-object:: Allocates a foreign object with dynamic extent.
190 * with-foreign-slots:: Access the slots of a foreign structure.
194 * foreign-free:: Deallocates memory.
195 * foreign-alloc:: Allocates memory.
196 * foreign-symbol-pointer:: Returns a pointer to a foreign symbol.
197 * inc-pointer:: Increments the address held by a pointer.
198 * incf-pointer:: Increments the pointer address in a place.
199 * make-pointer:: Returns a pointer to a given address.
200 * mem-aref:: Accesses the value of an index in an array.
201 * mem-ref:: Dereferences a pointer.
202 * null-pointer:: Returns a NULL pointer.
203 * null-pointer-p:: Tests a pointer for NULL value.
204 * pointerp:: Tests whether an object is a pointer or not.
205 * pointer-address:: Returns the address pointed to by a pointer.
206 * pointer-eq:: Tests if two pointers point to the same address.
207 * with-foreign-pointer:: Allocates memory with dynamic extent.
211 * foreign-string-alloc:: Converts a Lisp string to a foreign string.
212 * foreign-string-free:: Deallocates memory used by a foreign string.
213 * foreign-string-to-lisp:: Converts a foreign string to a Lisp string.
214 * lisp-string-to-foreign:: Copies a Lisp string into a foreign string.
215 * with-foreign-string:: Allocates a foreign string with dynamic extent.
216 * with-foreign-pointer-as-string:: Similar to CL's with-output-to-string.
220 * defcvar:: Defines a C global variable.
221 * get-var-pointer:: Returns a pointer to a defined global variable.
225 * defcfun:: Defines a foreign function.
226 * foreign-funcall:: Performs a call to a foreign function.
227 * foreign-funcall-pointer:: Performs a call through a foreign pointer.
231 * close-foreign-library:: Closes a foreign library.
232 * *darwin-framework-directories*:: Search path for Darwin frameworks.
233 * define-foreign-library:: Explain how to load a foreign library.
234 * *foreign-library-directories*:: Search path for shared libraries.
235 * load-foreign-library:: Load a foreign library.
236 * load-foreign-library-error:: Signalled on failure of its namesake.
237 * use-foreign-library:: Load a foreign library when needed.
241 * callback:: Returns a pointer to a defined callback.
242 * defcallback:: Defines a Lisp callback.
243 * get-callback:: Returns a pointer to a defined callback.
251 @c ===================================================================
252 @c CHAPTER: Introduction
255 @chapter Introduction
257 @cffi{} is the Common Foreign Function Interface for @acronym{ANSI}
258 Common Lisp systems. By @dfn{foreign function} we mean a function
259 written in another programming language and having different data and
260 calling conventions than Common Lisp, namely, C. @cffi{} allows you
261 to call foreign functions and access foreign variables, all without
262 leaving the Lisp image.
264 We consider this manual ever a work in progress. If you have
265 difficulty with anything @cffi{}-specific presented in the manual,
266 please contact @email{cffi-devel@@common-lisp.net,the developers} with
272 @xref{Tutorial-Comparison,, What makes Lisp different}, for
273 an argument in favor of @acronym{FFI} in general.
275 @cffi{}'s primary role in any image is to mediate between Lisp
276 developers and the widely varying @acronym{FFI}s present in the
277 various Lisp implementations it supports. With @cffi{}, you can
278 define foreign function interfaces while still maintaining portability
279 between implementations. It is not the first Common Lisp package with
280 this objective; however, it is meant to be a more malleable framework
281 than similar packages.
284 @heading Design Philosophy
288 Pointers do not carry around type information. Instead, type
289 information is supplied when pointers are dereferenced.
292 A type safe pointer interface can be developed on top of an
293 untyped one. It is difficult to do the opposite.
296 Functions are better than macros. When a macro could be used
297 for performance, use a compiler-macro instead.
301 @c ===================================================================
302 @c CHAPTER: Implementation Support
304 @node Implementation Support
305 @chapter Implementation Support
307 @cffi{} supports various free and commercial Lisp implementations:
308 Allegro CL, Corman CL, @sc{clisp}, @acronym{CMUCL}, @acronym{ECL},
309 LispWorks, Open@acronym{MCL}, @acronym{SBCL} and the Scieneer CL.
311 There are also plans to support Digitool @acronym{MCL}, and @acronym{GCL}.
316 @strong{Tested platforms:} linux/x86, linux/ppc, win32/x86, darwin/ppc.
318 Version 7.0 is supported. The 8.0 beta is also known to work. Earlier
319 versions are untested and unsupported but patches to support them
322 @subheading Limitations
326 Does not support the @code{:long-long} type.
331 @strong{Tested platforms:} win32/x86.
333 Versions prior to 2.51 are untested and unsupported. Also, you will
334 need to avoid Corman's buggy @code{COMPILE-FILE} and fasl
335 loader. Please follow @uref{http://www.weitz.de/corman-asdf/, these
336 instructions} by Edi Weitz to setup ASDF for Corman CL in a way that
337 works around these issues.
339 @subheading Limitations
343 Does not support @code{foreign-funcall}.
349 @strong{Tested platforms:} linux/x86, linux/ppc, win32/x86, darwin/ppc.
351 Version is 2.34 or newer is required on win32/x86. For other platforms
352 version 2.35 or newer is required.
355 @section @acronym{CMUCL}
357 @strong{Tested platforms:} linux/x86, darwin/ppc.
359 Versions prior to 19B are untested. For darwin/ppc, the 2006-02 (19C)
360 snapshot or later is recommended.
363 @section @acronym{ECL}
365 @strong{Tested platforms:} @emph{needs testing...}
367 As of November 2005, the CVS version of ECL is required. It is
368 reported to pass all tests.
370 @subheading Limitations
373 Does not support the @code{:long-long} type.
376 On platforms where ECL's dynamic FFI is not supported (ie. when
377 @code{:dffi} is not present in @code{*features*}),
378 @code{cffi:load-foreign-library} does not work and you must use ECL's
379 own @code{ffi:load-foreign-library} with a constant string argument.
385 @strong{Tested platforms:} linux/x86, win32/x86, darwin/ppc.
387 Versions prior to 4.4 are untested.
389 @subheading Limitations
392 Does not support the @code{:long-long} type.
396 @section Open@acronym{MCL}
398 @strong{Tested platforms:} darwin/ppc, linux/ppc.
400 Open@acronym{MCL} 1.0 or newer is recommended.
403 @section @acronym{SBCL}
405 @strong{Tested platforms:} linux/x86, linux/ppc, darwin/ppc.
407 Version 0.9.6 or newer is recommended.
409 @subheading Limitations
413 Not all platforms support callbacks.
419 @strong{Tested platforms:} linux/x86, linux/amd64.
421 Version 1.2.10 or newer is recommended. Passes all tests.
422 The x86 and AMD64 ports feature long-double support.
425 @c ===================================================================
426 @c CHAPTER: An Introduction to Foreign Interfaces and CFFI
428 @c This macro is merely a marker that I don't think I'll use after
430 @macro tutorialsource {text}
434 @c because I don't want to type this over and over
436 http://www.cliki.net/CFFI
438 @c TeX puts spurious newlines in when you use the above macro
439 @c in @examples &c. So it is expanded below in some places.
443 @chapter An Introduction to Foreign Interfaces and @acronym{CFFI}
445 @c Above, I don't use the cffi macro because it breaks TeX.
447 @cindex tutorial, @cffi{}
448 Users of many popular languages bearing semantic similarity to Lisp,
449 such as Perl and Python, are accustomed to having access to popular C
450 libraries, such as @acronym{GTK}, by way of ``bindings''. In Lisp, we
451 do something similar, but take a fundamentally different approach.
452 This tutorial first explains this difference, then explains how you
453 can use @cffi{}, a powerful system for calling out to C and C++ and
454 access C data from many Common Lisp implementations.
456 @cindex foreign functions and data
457 The concept can be generalized to other languages; at the time of
458 writing, only @cffi{}'s C support is fairly complete, but C++
459 support is being worked on. Therefore, we will interchangeably refer
460 to @dfn{foreign functions} and @dfn{foreign data}, and ``C functions''
461 and ``C data''. At no time will the word ``foreign'' carry its usual,
462 non-programming meaning.
464 This tutorial expects you to have a working understanding of both
465 Common Lisp and C, including the Common Lisp macro system.
468 * Tutorial-Comparison:: Why FFI?
469 * Tutorial-Getting a URL:: An FFI use case.
470 * Tutorial-Loading:: Load libcurl.so.
471 * Tutorial-Initializing:: Call a function in libcurl.so.
472 * Tutorial-easy_setopt:: An advanced libcurl function.
473 * Tutorial-Abstraction:: Why breaking it is necessary.
474 * Tutorial-Lisp easy_setopt:: Semi-Lispy option interface.
475 * Tutorial-Memory:: In C, you collect the garbage.
476 * Tutorial-Callbacks:: Make useful C function pointers.
477 * Tutorial-Completion:: Minimal get-url functionality.
478 * Tutorial-Types:: Defining new foreign types.
479 * Tutorial-Conclusion:: What's next?
483 @node Tutorial-Comparison
484 @section What makes Lisp different
486 The following sums up how bindings to foreign libraries are usually
487 implemented in other languages, then in Common Lisp:
490 @item Perl, Python, Java, other one-implementation languages
491 @cindex @acronym{SWIG}
494 Bindings are implemented as shared objects written in C. In some
495 cases, the C code is generated by a tool, such as @acronym{SWIG}, but
496 the result is the same: a new C library that manually translates
497 between the language implementation's objects, such as @code{PyObject}
498 in Python, and whatever C object is called for, often using C
499 functions provided by the implementation. It also translates between
500 the calling conventions of the language and C.
503 @cindex @acronym{SLIME}
504 Bindings are written in Lisp. They can be created at-will by Lisp
505 programs. Lisp programmers can write new bindings and add them to the
506 image, using a listener such as @acronym{SLIME}, as easily as with
507 regular Lisp definitions. The only foreign library to load is the one
508 being wrapped---the one with the pure C interface; no C or other
509 non-Lisp compilation is required.
512 @cindex advantages of @acronym{FFI}
513 @cindex benefits of @acronym{FFI}
514 We believe the advantages of the Common Lisp approach far outweigh any
515 disadvantages. Incremental development with a listener can be as
516 productive for C binding development as it is with other Lisp
517 development. Keeping it ``in the [Lisp] family'', as it were, makes
518 it much easier for you and other Lisp programmers to load and use the
519 bindings. Common Lisp implementations such as @acronym{CMUCL}, freed
520 from having to provide a C interface to their own objects, are thus
521 freed to be implemented in another language (as @acronym{CMUCL} is)
522 while still allowing programmers to call foreign functions.
524 @cindex minimal bindings
525 Perhaps the greatest advantage is that using an @acronym{FFI} doesn't
526 obligate you to become a professional binding developer. Writers of
527 bindings for other languages usually end up maintaining or failing to
528 maintain complete bindings to the foreign library. Using an
529 @acronym{FFI}, however, means if you only need one or two functions,
530 you can write bindings for only those functions, and be assured that
531 you can just as easily add to the bindings if need be.
533 @cindex C abstractions
534 @cindex abstractions in C
535 The removal of the C compiler, or C interpretation of any kind,
536 creates the main disadvantage: some of C's ``abstractions'' are not
537 available, violating information encapsulation. For example,
538 @code{struct}s that must be passed on the stack, or used as return
539 values, without corresponding functional abstractions to create and
540 manage the @code{struct}s, must be declared explicitly in Lisp. This
541 is fine for structs whose contents are ``public'', but is not so
542 pleasant when a struct is supposed to be ``opaque'' by convention,
543 even though it is not so defined.@footnote{Admittedly, this is an
544 advanced issue, and we encourage you to leave this text until you are
545 more familiar with how @cffi{} works.}
547 Without an abstraction to create the struct, Lisp needs to be able to
548 lay out the struct in memory, so must know its internal details.
550 @cindex workaround for C
551 In these cases, you can create a minimal C library to provide the
552 missing abstractions, without destroying all the advantages of the
553 Common Lisp approach discussed above. In the case of @code{struct}s,
554 you can write simple, pure C functions that tell you how many bytes a
555 struct requires or allocate new structs, read and write fields of the
556 struct, or whatever operations are supposed to be
557 public.@footnote{This does not apply to structs whose contents are
558 intended to be part of the public library interface. In those cases,
559 a pure Lisp struct definition is always preferred. In fact, many
560 prefer to stay in Lisp and break the encapsulation anyway, placing the
561 burden of correct library interface definition on the library.}
563 @impnote{cffi-grovel, a project not yet part of @cffi{}, automates
564 this and other processes.}
566 Another disadvantage appears when you would rather use the foreign
567 language than Lisp. However, someone who prefers C to Lisp is not a
568 likely candidate for developing a Lisp interface to a C library.
571 @node Tutorial-Getting a URL
572 @section Getting a @acronym{URL}
574 @cindex c@acronym{URL}
575 The widely available @code{libcurl} is a library for downloading files
576 over protocols like @acronym{HTTP}. We will use @code{libcurl} with
577 @cffi{} to download a web page.
579 Please note that there are many other ways to download files from the
580 web, not least the @sc{cl-curl} project to provide bindings to
581 @code{libcurl} via a similar @acronym{FFI}.@footnote{Specifically,
582 @acronym{UFFI}, an older @acronym{FFI} that takes a somewhat different
583 approach compared to @cffi{}. I believe that these days (December
584 2005) @cffi{} is more portable and actively developed, though not as
585 mature yet. Consensus in the free @sc{unix} Common Lisp community
586 seems to be that @cffi{} is preferred for new development, though
587 @acronym{UFFI} will likely go on for quite some time as many projects
588 already use it. @cffi{} includes the @code{UFFI-COMPAT} package for
589 complete compatibility with @acronym{UFFI}.}
591 @uref{http://curl.haxx.se/libcurl/c/libcurl-tutorial.html,,libcurl-tutorial(3)}
592 is a tutorial for @code{libcurl} programming in C. We will follow
593 that to develop a binding to download a file. We will also use
594 @file{curl.h}, @file{easy.h}, and the @command{man} pages for the
595 @code{libcurl} function, all available in the @samp{curl-dev} package
596 or equivalent for your system, or in the c@acronym{URL} source code
597 package. If you have the development package, the headers should be
598 installed in @file{/usr/include/curl/}, and the @command{man} pages
599 may be accessed through your favorite @command{man} facility.
602 @node Tutorial-Loading
603 @section Loading foreign libraries
605 @cindex loading @cffi{}
606 @cindex requiring @cffi{}
607 First of all, we will create a package to work in. You can save these
608 forms in a file, or just send them to the listener as they are. If
609 creating bindings for an @acronym{ASDF} package of yours, you will
610 want to add @code{:cffi} to the @code{:depends-on} list in your
611 @file{.asd} file. Otherwise, just use the @code{asdf:oos} function to
614 @tutorialsource{Initialization}
616 (asdf:oos 'asdf:load-op :cffi)
618 ;;; @lispcmt{Nothing special about the "CFFI-USER" package. We're just}
619 ;;; @lispcmt{using it as a substitute for your own CL package.}
620 (defpackage :cffi-user
621 (:use :common-lisp :cffi))
623 (in-package :cffi-user)
625 (define-foreign-library libcurl
626 (:unix (:or "libcurl.so.3" "libcurl.so"))
627 (t (:default "libcurl")))
629 (use-foreign-library libcurl)
632 @cindex foreign library load
633 @cindex library, foreign
634 Using @code{define-foreign-library} and @code{use-foreign-library}, we
635 have loaded @code{libcurl} into Lisp, much as the linker does when you
636 start a C program, or @code{common-lisp:load} does with a Lisp source
637 file or @acronym{FASL} file. We special-cased for @sc{unix} machines
638 to always load a particular version, the one this tutorial was tested
639 with; for those who don't care, the @code{define-foreign-library}
640 clause @code{(t (:default "libcurl"))} should be satisfactory, and
641 will adapt to various operating systems.
644 @node Tutorial-Initializing
645 @section Initializing @code{libcurl}
647 @cindex function definition
648 After the introductory matter, the tutorial goes on to present the
649 first function you should use.
652 CURLcode curl_global_init(long flags);
656 Let's pick this apart into appropriate Lisp code:
658 @tutorialsource{First CURLcode}
660 ;;; @lispcmt{A CURLcode is the universal error code. curl/curl.h says}
661 ;;; @lispcmt{no return code will ever be removed, and new ones will be}
662 ;;; @lispcmt{added to the end.}
663 (defctype curl-code :int)
665 ;;; @lispcmt{Initialize libcurl with FLAGS.}
666 (defcfun "curl_global_init" curl-code
670 @impnote{CFFI currently assumes the UNIX viewpoint that there is one C
671 symbol namespace, containing all symbols in all loaded objects. This
672 is not so on Windows and Darwin. The interface may be changed to deal
675 Note the parallels with the original C declaration. We've defined
676 @code{curl-code} as a wrapping type for @code{:int}; right now, it
677 only marks it as special, but later we will do something more
678 interesting with it. The point is that we don't have to do it yet.
680 @cindex calling foreign functions
681 Looking at @file{curl.h}, @code{CURL_GLOBAL_NOTHING}, a possible value
682 for @code{flags} above, is defined as @samp{0}. So we can now call
686 @sc{cffi-user>} (curl-global-init 0)
690 @cindex looks like it worked
691 Looking at @file{curl.h} again, @code{0} means @code{CURLE_OK}, so it
692 looks like the call succeeded. Note that @cffi{} converted the
693 function name to a Lisp-friendly name. You can specify your own name
694 if you want; use @code{("curl_global_init" @var{your-name-here})} as
695 the @var{name} argument to @code{defcfun}.
697 The tutorial goes on to have us allocate a handle. For good measure,
698 we should also include the deallocator. Let's look at these
702 CURL *curl_easy_init( );
703 void curl_easy_cleanup(CURL *handle);
706 Advanced users may want to define special pointer types; we will
707 explore this possibility later. For now, just treat every pointer as
710 @tutorialsource{curl_easy handles}
712 (defcfun "curl_easy_init" :pointer)
714 (defcfun "curl_easy_cleanup" :void
715 (easy-handle :pointer))
718 Now we can continue with the tutorial:
721 @sc{cffi-user>} (defparameter *easy-handle* (curl-easy-init))
722 @result{} *EASY-HANDLE*
723 @sc{cffi-user>} *easy-handle*
724 @result{} #<FOREIGN-ADDRESS #x09844EE0>
727 @cindex pointers in Lisp
728 Note the print representation of a pointer. It changes depending on
729 what Lisp you are using, but that doesn't make any difference to
733 @node Tutorial-easy_setopt
734 @section Setting download options
736 The @code{libcurl} tutorial says we'll want to set many options before
737 performing any download actions. This is done through
738 @code{curl_easy_setopt}:
740 @c That is literally ..., not an ellipsis.
742 CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...);
746 @cindex foreign arguments
747 We've introduced a new twist: variable arguments. There is no obvious
748 translation to the @code{defcfun} form, particularly as there are four
749 possible argument types. Because of the way C works, we could define
750 four wrappers around @code{curl_easy_setopt}, one for each type; in
751 this case, however, we'll use the general-purpose macro
752 @code{foreign-funcall} to call this function.
754 @cindex enumeration, C
755 To make things easier on ourselves, we'll create an enumeration of the
756 kinds of options we want to set. The @code{enum CURLoption} isn't the
757 most straightforward, but reading the @code{CINIT} C macro definition
758 should be enlightening.
760 @tutorialsource{CURLoption enumeration}
762 (defmacro define-curl-options (name type-offsets &rest enum-args)
763 "As with CFFI:DEFCENUM, except each of ENUM-ARGS is as follows:
767 Where the arguments are as they are with the CINIT macro defined
768 in curl.h, except NAME is a keyword.
770 TYPE-OFFSETS is a plist of TYPEs to their integer offsets, as
771 defined by the CURLOPTTYPE_LONG et al constants in curl.h."
772 (flet ((enumerated-value (type offset)
773 (+ (getf type-offsets type) offset)))
776 ,@@(loop for (name type number) in enum-args
777 collect (list name (enumerated-value type number))))
778 ',name))) ;@lispcmt{for REPL users' sanity}
780 (define-curl-options curl-option
781 (long 0 objectpoint 10000 functionpoint 20000 off-t 30000)
782 (:noprogress long 43)
784 (:errorbuffer objectpoint 10)
785 (:url objectpoint 2))
788 With some well-placed Emacs @code{query-replace-regexp}s, you could
789 probably similarly define the entire @code{CURLoption} enumeration. I
790 have selected to transcribe a few that we will use in this tutorial.
792 If you're having trouble following the macrology, just macroexpand the
793 @code{curl-option} definition, or see the following macroexpansion,
794 conveniently downcased and reformatted:
796 @tutorialsource{DEFINE-CURL-OPTIONS macroexpansion}
799 (defcenum curl-option
808 That seems more than reasonable. You may notice that we only use the
809 @var{type} to compute the real enumeration offset; we will also need
810 the type information later.
812 First, however, let's make sure a simple call to the foreign function
816 @sc{cffi-user>} (foreign-funcall "curl_easy_setopt"
817 :pointer *easy-handle*
818 curl-option :nosignal :long 1 curl-code)
822 @code{foreign-funcall}, despite its surface simplicity, can be used to
823 call any C function. Its first argument is a string, naming the
824 function to be called. Next, for each argument, we pass the name of
825 the C type, which is the same as in @code{defcfun}, followed by a Lisp
826 object representing the data to be passed as the argument. The final
827 argument is the return type, for which we use the @code{curl-code}
828 type defined earlier.
830 @code{defcfun} just puts a convenient fa@,cade on
831 @code{foreign-funcall}.@footnote{This isn't entirely true; some Lisps
832 don't support @code{foreign-funcall}, so @code{defcfun} is implemented
833 without it. @code{defcfun} may also perform optimizations that
834 @code{foreign-funcall} cannot.} Our earlier call to
835 @code{curl-global-init} could have been written as follows:
838 @sc{cffi-user>} (foreign-funcall "curl_global_init" :long 0
843 Before we continue, we will take a look at what @cffi{} can and can't
844 do, and why this is so.
847 @node Tutorial-Abstraction
848 @section Breaking the abstraction
850 @cindex breaking the abstraction
851 @cindex abstraction breaking
852 In @ref{Tutorial-Comparison,, What makes Lisp different}, we mentioned
853 that writing an @acronym{FFI} sometimes requires depending on
854 information not provided as part of the interface. The easy option
855 @code{CURLOPT_WRITEDATA}, which we will not provide as part of the
856 Lisp interface, illustrates this issue.
858 Strictly speaking, the @code{curl-option} enumeration is not
859 necessary; we could have used @code{:int 99} instead of
860 @code{curl-option :nosignal} in our call to @code{curl_easy_setopt}
861 above. We defined it anyway, in part to hide the fact that we are
862 breaking the abstraction that the C @code{enum} provides. If the
863 c@acronym{URL} developers decide to change those numbers later, we
864 must change the Lisp enumeration, because enumeration values are not
865 provided in the compiled C library, @code{libcurl.so.3}.
867 @cffi{} works because the most useful things in C libraries ---
868 non-static functions and non-static variables --- are included
869 accessibly in @code{libcurl.so.3}. A C compiler that violated this
870 would be considered a worthless compiler.
872 The other thing @code{define-curl-options} does is give the ``type''
873 of the third argument passed to @code{curl_easy_setopt}. Using this
874 information, we can tell that the @code{:nosignal} option should
875 accept a long integer argument. We can implicitly assume @code{t}
876 @equiv{} 1 and @code{nil} @equiv{} 0, as it is in C, which takes care
877 of the fact that @code{CURLOPT_NOSIGNAL} is really asking for a
880 The ``type'' of @code{CURLOPT_WRITEDATA} is @code{objectpoint}.
881 However, it is really looking for a @code{FILE*}.
882 @code{CURLOPT_ERRORBUFFER} is looking for a @code{char*}, so there is
883 no obvious @cffi{} type but @code{:pointer}.
885 The first thing to note is that nowhere in the C interface includes
886 this information; it can only be found in the manual. We could
887 disjoin these clearly different types ourselves, by splitting
888 @code{objectpoint} into @code{filepoint} and @code{charpoint}, but we
889 are still breaking the abstraction, because we have to augment the
890 entire enumeration form with this additional
891 information.@footnote{Another possibility is to allow the caller to
892 specify the desired C type of the third argument. This is essentially
893 what happens in a call to the function written in C.}
895 @cindex streams and C
896 @cindex @sc{file}* and streams
897 The second is that the @code{CURLOPT_WRITEDATA} argument is completely
898 incompatible with the desired Lisp data, a
899 stream.@footnote{@xref{Other Kinds of Streams,,, libc, GNU C Library
900 Reference}, for a @acronym{GNU}-only way to extend the @code{FILE*}
901 type. You could use this to convert Lisp streams to the needed C
902 data. This would be quite involved and far outside the scope of this
903 tutorial.} It is probably acceptable if we are controlling every file
904 we might want to use as this argument, in which case we can just call
905 the foreign function @code{fopen}. Regardless, though, we can't write
906 to arbitrary streams, which is exactly what we want to do for this
909 Finally, note that the @code{curl_easy_setopt} interface itself is a
910 hack, intended to work around some of the drawbacks of C. The
911 definition of @code{Curl_setopt}, while long, is far less cluttered
912 than the equivalent disjoint-function set would be; in addition,
913 setting a new option in an old @code{libcurl} can generate a run-time
914 error rather than breaking the compile. Lisp can just as concisely
915 generate functions as compare values, and the ``undefined function''
916 error is just as useful as any explicit error we could define here
920 @node Tutorial-Lisp easy_setopt
921 @section Option functions in Lisp
923 We could use @code{foreign-funcall} directly every time we wanted to
924 call @code{curl_easy_setopt}. However, we can encapsulate some of the
925 necessary information with the following.
928 ;;; @lispcmt{We will use this type later in a more creative way. For}
929 ;;; @lispcmt{now, just consider it a marker that this isn't just any}
930 ;;; @lispcmt{pointer.}
931 (defctype easy-handle :pointer)
933 (defmacro curl-easy-setopt (easy-handle enumerated-name
934 value-type new-value)
935 "Call `curl_easy_setopt' on EASY-HANDLE, using ENUMERATED-NAME
936 as the OPTION. VALUE-TYPE is the CFFI foreign type of the third
937 argument, and NEW-VALUE is the Lisp data to be translated to the
938 third argument. VALUE-TYPE is not evaluated."
939 `(foreign-funcall "curl_easy_setopt" easy-handle ,easy-handle
940 curl-option ,enumerated-name
941 ,value-type ,new-value curl-code))
944 Now we define a function for each kind of argument that encodes the
945 correct @code{value-type} in the above. This can be done reasonably
946 in the @code{define-curl-options} macroexpansion; after all, that is
947 where the different options are listed!
949 @cindex Lispy C functions
950 We could make @code{cl:defun} forms in the expansion that simply call
951 @code{curl-easy-setopt}; however, it is probably easier and clearer to
952 use @code{defcfun}. @code{define-curl-options} was becoming unwieldy,
953 so I defined some helpers in this new definition.
956 (defun curry-curl-option-setter (function-name option-keyword)
957 "Wrap the function named by FUNCTION-NAME with a version that
958 curries the second argument as OPTION-KEYWORD.
960 This function is intended for use in DEFINE-CURL-OPTION-SETTER."
961 (setf (symbol-function function-name)
962 (let ((c-function (symbol-function function-name)))
963 (lambda (easy-handle new-value)
964 (funcall c-function easy-handle option-keyword
967 (defmacro define-curl-option-setter (name option-type
968 option-value foreign-type)
969 "Define (with DEFCFUN) a function NAME that calls
970 curl_easy_setopt. OPTION-TYPE and OPTION-VALUE are the CFFI
971 foreign type and value to be passed as the second argument to
972 easy_setopt, and FOREIGN-TYPE is the CFFI foreign type to be used
973 for the resultant function's third argument.
975 This macro is intended for use in DEFINE-CURL-OPTIONS."
977 (defcfun ("curl_easy_setopt" ,name) curl-code
978 (easy-handle easy-handle)
979 (option ,option-type)
980 (new-value ,foreign-type))
981 (curry-curl-option-setter ',name ',option-value)))
983 (defmacro define-curl-options (type-name type-offsets &rest enum-args)
984 "As with CFFI:DEFCENUM, except each of ENUM-ARGS is as follows:
988 Where the arguments are as they are with the CINIT macro defined
989 in curl.h, except NAME is a keyword.
991 TYPE-OFFSETS is a plist of TYPEs to their integer offsets, as
992 defined by the CURLOPTTYPE_LONG et al constants in curl.h.
994 Also, define functions for each option named
995 set-`TYPE-NAME'-`OPTION-NAME', where OPTION-NAME is the NAME from
996 the above destructuring."
997 (flet ((enumerated-value (type offset)
998 (+ (getf type-offsets type) offset))
999 ;;@lispcmt{map PROCEDURE, destructuring each of ENUM-ARGS}
1000 (map-enum-args (procedure)
1001 (mapcar (lambda (arg) (apply procedure arg)) enum-args))
1002 ;;@lispcmt{build a name like SET-CURL-OPTION-NOSIGNAL}
1003 (make-setter-name (option-name)
1004 (intern (concatenate
1005 'string "SET-" (symbol-name type-name)
1006 "-" (symbol-name option-name)))))
1008 (defcenum ,type-name
1010 (lambda (name type number)
1011 (list name (enumerated-value type number)))))
1013 (lambda (name type number)
1014 (declare (ignore number))
1015 `(define-curl-option-setter ,(make-setter-name name)
1016 ,type-name ,name ,(ecase type
1018 (objectpoint :pointer)
1019 (functionpoint :pointer)
1025 Macroexpanding our @code{define-curl-options} form once more, we
1026 see something different:
1030 (defcenum curl-option
1033 (:errorbuffer 10010)
1035 (define-curl-option-setter set-curl-option-noprogress
1036 curl-option :noprogress :long)
1037 (define-curl-option-setter set-curl-option-nosignal
1038 curl-option :nosignal :long)
1039 (define-curl-option-setter set-curl-option-errorbuffer
1040 curl-option :errorbuffer :pointer)
1041 (define-curl-option-setter set-curl-option-url
1042 curl-option :url :pointer)
1047 Macroexpanding one of the new @code{define-curl-option-setter}
1048 forms yields the following:
1052 (defcfun ("curl_easy_setopt" set-curl-option-nosignal) curl-code
1053 (easy-handle easy-handle)
1054 (option curl-option)
1056 (curry-curl-option-setter 'set-curl-option-nosignal ':nosignal))
1060 Finally, let's try this out:
1063 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1)
1068 Looks like it works just as well. This interface is now reasonably
1069 high-level to wash out some of the ugliness of the thinnest possible
1070 @code{curl_easy_setopt} @acronym{FFI}, without obscuring the remaining
1071 C bookkeeping details we will explore.
1074 @node Tutorial-Memory
1075 @section Memory management
1077 According to the documentation for @code{curl_easy_setopt}, the type
1078 of the third argument when @var{option} is @code{CURLOPT_ERRORBUFFER}
1079 is @code{char*}. Above, we've defined
1080 @code{set-curl-option-errorbuffer} to accept a @code{:pointer} as the
1081 new option value. However, there is a @cffi{} type @code{:string},
1082 which translates Lisp strings to C strings when passed as arguments to
1083 foreign function calls. Why not, then, use @code{:string} as the
1084 @cffi{} type of the third argument? There are two reasons, both
1085 related to the necessity of breaking abstraction described in
1086 @ref{Tutorial-Abstraction,, Breaking the abstraction}.
1088 The first reason also applies to @code{CURLOPT_URL}, which we will use
1089 to illustrate the point. Assuming we have changed the type of the
1090 third argument underlying @code{set-curl-option-url} to
1091 @code{:string}, look at these two equivalent forms.
1094 (set-curl-option-url *easy-handle* "http://www.cliki.net/CFFI")
1096 @equiv{} (with-foreign-string (url "http://www.cliki.net/CFFI")
1097 (foreign-funcall "curl_easy_setopt" easy-handle *easy-handle*
1098 curl-option :url :pointer url curl-code))
1102 The latter, in fact, is mostly equivalent to what a foreign function
1103 call's macroexpansion actually does. As you can see, the Lisp string
1104 @code{"@clikicffi{}"} is copied into a @code{char} array and
1105 null-terminated; the pointer to beginning of this array, now a C
1106 string, is passed as a @cffi{} @code{:pointer} to the foreign
1109 @cindex dynamic extent
1110 @cindex foreign values with dynamic extent
1111 Unfortunately, the C abstraction has failed us, and we must break it.
1112 While @code{:string} works well for many @code{char*} arguments, it
1113 does not for cases like this. As the @code{curl_easy_setopt}
1114 documentation explains, ``The string must remain present until curl no
1115 longer needs it, as it doesn't copy the string.'' The C string
1116 created by @code{with-foreign-string}, however, only has dynamic
1117 extent: it is ``deallocated'' when the body (above containing the
1118 @code{foreign-funcall} form) exits.
1120 @cindex premature deallocation
1121 If we are supposed to keep the C string around, but it goes away, what
1122 happens when some @code{libcurl} function tries to access the
1123 @acronym{URL} string? We have reentered the dreaded world of C
1124 ``undefined behavior''. In some Lisps, it will probably get a chunk
1125 of the Lisp/C stack. You may segfault. You may get some random piece
1126 of other data from the heap. Maybe, in a world where ``dynamic
1127 extent'' is defined to be ``infinite extent'', everything will turn
1128 out fine. Regardless, results are likely to be almost universally
1129 unpleasant.@footnote{``@i{But I thought Lisp was supposed to protect
1130 me from all that buggy C crap!}'' Before asking a question like that,
1131 remember that you are a stranger in a foreign land, whose residents
1132 have a completely different set of values.}
1134 Returning to the current @code{set-curl-option-url} interface, here is
1140 (with-foreign-string (url "http://www.cliki.net/CFFI")
1141 (setf easy-handle (curl-easy-init))
1142 (set-curl-option-url easy-handle url)
1143 #|@lispcmt{do more with the easy-handle, like actually get the URL}|#)
1145 (curl-easy-cleanup easy-handle))))
1148 @c old comment to luis: I go on to say that this isn't obviously
1149 @c extensible to new option settings that require C strings to stick
1150 @c around, as it would involve re-evaluating the unwind-protect form
1151 @c with more dynamic memory allocation. So I plan to show how to
1152 @c write something similar to ObjC's NSAutoreleasePool, to be managed
1153 @c with a simple unwind-protect form.
1156 That is fine for the single string defined here, but for every string
1157 option we want to pass, we have to surround the body of
1158 @code{with-foreign-string} with another @code{with-foreign-string}
1159 wrapper, or else do some extremely error-prone pointer manipulation
1160 and size calculation in advance. We could alleviate some of the pain
1161 with a recursively expanding macro, but this would not remove the need
1162 to modify the block every time we want to add an option, anathema as
1163 it is to a modular interface.
1165 Before modifying the code to account for this case, consider the other
1166 reason we can't simply use @code{:string} as the foreign type. In C,
1167 a @code{char *} is a @code{char *}, not necessarily a string. The
1168 option @code{CURLOPT_ERRORBUFFER} accepts a @code{char *}, but does
1169 not expect anything about the data there. However, it does expect
1170 that some @code{libcurl} function we call later can write a C string
1171 of up to 255 characters there. We, the callers of the function, are
1172 expected to read the C string at a later time, exactly the opposite of
1173 what @code{:string} implies.
1175 With the semantics for an input string in mind --- namely, that the
1176 string should be kept around until we @code{curl_easy_cleanup} the
1177 easy handle --- we are ready to extend the Lisp interface:
1180 (defvar *easy-handle-cstrings* (make-hash-table)
1181 "Hashtable of easy handles to lists of C strings that may be
1182 safely freed after the handle is freed.")
1184 (defun make-easy-handle ()
1185 "Answer a new CURL easy interface handle, to which the lifetime
1186 of C strings may be tied. See `add-curl-handle-cstring'."
1187 (let ((easy-handle (curl-easy-init)))
1188 (setf (gethash easy-handle *easy-handle-cstrings*) '())
1191 (defun free-easy-handle (handle)
1192 "Free CURL easy interface HANDLE and any C strings created to
1194 (curl-easy-cleanup handle)
1195 (mapc #'foreign-string-free
1196 (gethash handle *easy-handle-cstrings*))
1197 (remhash handle *easy-handle-cstrings*))
1199 (defun add-curl-handle-cstring (handle cstring)
1200 "Add CSTRING to be freed when HANDLE is, answering CSTRING."
1201 (car (push cstring (gethash handle *easy-handle-cstrings*))))
1205 Here we have redefined the interface to create and free handles, to
1206 associate a list of allocated C strings with each handle while it
1207 exists. The strategy of using different function names to wrap around
1208 simple foreign functions is more common than the solution implemented
1209 earlier with @code{curry-curl-option-setter}, which was to modify the
1210 function name's function slot.@footnote{There are advantages and
1211 disadvantages to each approach; I chose to @code{(setf
1212 symbol-function)} earlier because it entailed generating fewer magic
1215 Incidentally, the next step is to redefine
1216 @code{curry-curl-option-setter} to allocate C strings for the
1217 appropriate length of time, given a Lisp string as the
1218 @code{new-value} argument:
1221 (defun curry-curl-option-setter (function-name option-keyword)
1222 "Wrap the function named by FUNCTION-NAME with a version that
1223 curries the second argument as OPTION-KEYWORD.
1225 This function is intended for use in DEFINE-CURL-OPTION-SETTER."
1226 (setf (symbol-function function-name)
1227 (let ((c-function (symbol-function function-name)))
1228 (lambda (easy-handle new-value)
1229 (funcall c-function easy-handle option-keyword
1230 (if (stringp new-value)
1231 (add-curl-handle-cstring
1233 (foreign-string-alloc new-value))
1238 A quick analysis of the code shows that you need only reevaluate the
1239 @code{curl-option} enumeration definition to take advantage of these
1240 new semantics. Now, for good measure, let's reallocate the handle
1241 with the new functions we just defined, and set its @acronym{URL}:
1244 @sc{cffi-user>} (curl-easy-cleanup *easy-handle*)
1246 @sc{cffi-user>} (setf *easy-handle* (make-easy-handle))
1247 @result{} #<FOREIGN-ADDRESS #x09844EE0>
1248 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1)
1250 @sc{cffi-user>} (set-curl-option-url *easy-handle*
1251 "http://www.cliki.net/CFFI")
1256 For fun, let's inspect the Lisp value of the C string that was created
1257 to hold @code{"@clikicffi{}"}. By virtue of the implementation of
1258 @code{add-curl-handle-cstring}, it should be accessible through the
1262 @sc{cffi-user>} (foreign-string-to-lisp
1263 (car (gethash *easy-handle* *easy-handle-cstrings*)))
1264 @result{} "http://www.cliki.net/CFFI"
1268 Looks like that worked, and @code{libcurl} now knows what
1269 @acronym{URL} we want to retrieve.
1271 Finally, we turn back to the @code{:errorbuffer} option mentioned at
1272 the beginning of this section. Whereas the abstraction added to
1273 support string inputs works fine for cases like @code{CURLOPT_URL}, it
1274 hides the detail of keeping the C string; for @code{:errorbuffer},
1275 however, we need that C string.
1277 In a moment, we'll define something slightly cleaner, but for now,
1278 remember that you can always hack around anything. We're modifying
1279 handle creation, so make sure you free the old handle before
1280 redefining @code{free-easy-handle}.
1283 (defvar *easy-handle-errorbuffers* (make-hash-table)
1284 "Hashtable of easy handles to C strings serving as error
1285 writeback buffers.")
1287 ;;; @lispcmt{An extra byte is very little to pay for peace of mind.}
1288 (defparameter *curl-error-size* 257
1289 "Minimum char[] size used by cURL to report errors.")
1291 (defun make-easy-handle ()
1292 "Answer a new CURL easy interface handle, to which the lifetime
1293 of C strings may be tied. See `add-curl-handle-cstring'."
1294 (let ((easy-handle (curl-easy-init)))
1295 (setf (gethash easy-handle *easy-handle-cstrings*) '())
1296 (setf (gethash easy-handle *easy-handle-errorbuffers*)
1297 (foreign-alloc :char :count *curl-error-size*
1298 :initial-element 0))
1301 (defun free-easy-handle (handle)
1302 "Free CURL easy interface HANDLE and any C strings created to
1304 (curl-easy-cleanup handle)
1305 (foreign-free (gethash handle *easy-handle-errorbuffers*))
1306 (remhash handle *easy-handle-errorbuffers*)
1307 (mapc #'foreign-string-free
1308 (gethash handle *easy-handle-cstrings*))
1309 (remhash handle *easy-handle-cstrings*))
1311 (defun get-easy-handle-error (handle)
1312 "Answer a string containing HANDLE's current error message."
1313 (foreign-string-to-lisp
1314 (gethash handle *easy-handle-errorbuffers*)))
1317 Be sure to once again set the options we've set thus far. You may
1318 wish to define yet another wrapper function to do this.
1321 @node Tutorial-Callbacks
1322 @section Calling Lisp from C
1324 If you have been reading
1325 @uref{http://curl.haxx.se/libcurl/c/curl_easy_setopt.html,,
1326 @code{curl_easy_setopt(3)}}, you should have noticed that some options
1327 accept a function pointer. In particular, we need one function
1328 pointer to set as @code{CURLOPT_WRITEFUNCTION}, to be called by
1329 @code{libcurl} rather than the reverse, in order to receive data as it
1332 A binding writer without the aid of @acronym{FFI} usually approaches
1333 this problem by writing a C function that accepts C data, converts to
1334 the language's internal objects, and calls the callback provided by
1335 the user, again in a reverse of usual practices.
1337 The @cffi{} approach to callbacks precisely mirrors its differences
1338 with the non-@acronym{FFI} approach on the ``calling C from Lisp''
1339 side, which we have dealt with exclusively up to now. That is, you
1340 define a callback function in Lisp using @code{defcallback}, and
1341 @cffi{} effectively creates a C function to be passed as a function
1344 @impnote{This is much trickier than calling C functions from Lisp, as
1345 it literally involves somehow generating a new C function that is as
1346 good as any created by the compiler. Therefore, not all Lisps support
1347 them. @xref{Implementation Support}, for information about @cffi{}
1348 support issues in this and other areas. You may want to consider
1349 changing to a Lisp that supports callbacks in order to continue with
1352 @cindex callback definition
1353 @cindex defining callbacks
1354 Defining a callback is very similar to defining a callout; the main
1355 difference is that we must provide some Lisp forms to be evaluated as
1356 part of the callback. Here is the signature for the function the
1357 @code{:writefunction} option takes:
1361 @var{function}(void *ptr, size_t size, size_t nmemb, void *stream);
1364 @impnote{size_t is almost always an unsigned int. You can get this
1365 and many other types using feature tests for your system by using
1368 The above signature trivially translates into a @cffi{}
1369 @code{defcallback} form, as follows.
1372 ;;; @lispcmt{Alias in case size_t changes.}
1373 (defctype size :unsigned-int)
1375 ;;; @lispcmt{To be set as the CURLOPT_WRITEFUNCTION of every easy handle.}
1376 (defcallback easy-write size ((ptr :pointer) (size size)
1377 (nmemb size) (stream :pointer))
1378 (let ((data-size (* size nmemb)))
1380 ;; @lispcmt{We use the dynamically-bound *easy-write-procedure* to}
1381 ;; @lispcmt{call a closure with useful lexical context.}
1382 (progn (funcall (symbol-value '*easy-write-procedure*)
1383 (foreign-string-to-lisp ptr data-size nil))
1384 data-size) ;@lispcmt{indicates success}
1385 ;; @lispcmt{The WRITEFUNCTION should return something other than the}
1386 ;; @lispcmt{#bytes available to signal an error.}
1387 (error () (if (zerop data-size) 1 0)))))
1390 First, note the correlation of the first few forms, used to declare
1391 the C function's signature, with the signature in C syntax. We
1392 provide a Lisp name for the function, its return type, and a name and
1393 type for each argument.
1395 In the body, we call the dynamically-bound
1396 @code{*easy-write-procedure*} with a ``finished'' translation, of
1397 pulling together the raw data and size into a Lisp string, rather than
1398 deal with the data directly. As part of calling
1399 @code{curl_easy_perform} later, we'll bind that variable to a closure
1400 with more useful lexical bindings than the top-level
1401 @code{defcallback} form.
1403 Finally, we make a halfhearted effort to prevent non-local exits from
1404 unwinding the C stack, covering the most likely case with an
1405 @code{error} handler, which is usually triggered
1406 unexpectedly.@footnote{Unfortunately, we can't protect against
1407 @emph{all} non-local exits, such as @code{return}s and @code{throw}s,
1408 because @code{unwind-protect} cannot be used to ``short-circuit'' a
1409 non-local exit in Common Lisp, due to proposal @code{minimal} in
1410 @uref{http://www.lisp.org/HyperSpec/Issues/iss152-writeup.html,
1411 @acronym{ANSI} issue @sc{Exit-Extent}}. Furthermore, binding an
1412 @code{error} handler prevents higher-up code from invoking restarts
1413 that may be provided under the callback's dynamic context. Such is
1414 the way of compromise.} The reason is that most C code is written to
1415 understand its own idiosyncratic error condition, implemented above in
1416 the case of @code{curl_easy_perform}, and more ``undefined behavior''
1417 can result if we just wipe C stack frames without allowing them to
1418 execute whatever cleanup actions as they like.
1420 Using the @code{CURLoption} enumeration in @file{curl.h} once more, we
1421 can describe the new option by modifying and reevaluating
1422 @code{define-curl-options}.
1425 (define-curl-options curl-option
1426 (long 0 objectpoint 10000 functionpoint 20000 off-t 30000)
1427 (:noprogress long 43)
1429 (:errorbuffer objectpoint 10)
1430 (:url objectpoint 2)
1431 (:writefunction functionpoint 11)) ;@lispcmt{new item here}
1434 Finally, we can use the defined callback and the new
1435 @code{set-curl-option-writefunction} to finish configuring the easy
1436 handle, using the @code{callback} macro to retrieve a @cffi{}
1437 @code{:pointer}, which works like a function pointer in C code.
1440 @sc{cffi-user>} (set-curl-option-writefunction
1441 *easy-handle* (callback easy-write))
1446 @node Tutorial-Completion
1447 @section A complete @acronym{FFI}?
1449 @c TeX goes insane on @uref{@clikicffi{}}
1451 With all options finally set and a medium-level interface developed,
1452 we can finish the definition and retrieve
1453 @uref{http://www.cliki.net/CFFI}, as is done in the tutorial.
1456 (defcfun "curl_easy_perform" curl-code
1457 (handle easy-handle))
1461 @sc{cffi-user>} (with-output-to-string (contents)
1462 (let ((*easy-write-procedure*
1464 (write-string string contents))))
1465 (declare (special *easy-write-procedure*))
1466 (curl-easy-perform *easy-handle*)))
1467 @result{} "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\"
1469 Now fear, comprehensively</P>
1473 Of course, that itself is slightly unwieldy, so you may want to define
1474 a function around it that simply retrieves a @acronym{URL}. I will
1475 leave synthesis of all the relevant @acronym{REPL} forms presented
1476 thus far into a single function as an exercise for the reader.
1478 The remaining sections of this tutorial explore some advanced features
1479 of @cffi{}; the definition of new types will receive special
1480 attention. Some of these features are essential for particular
1481 foreign function calls; some are very helpful when trying to develop a
1482 Lispy interface to C.
1485 @node Tutorial-Types
1486 @section Defining new types
1488 We've occasionally used the @code{defctype} macro in previous sections
1489 as a kind of documentation, much what you'd use @code{typedef} for in
1490 C. We also tried one special kind of type definition, the
1491 @code{defcenum} type. @xref{defcstruct}, for a definition macro that
1492 may come in handy if you need to use C @code{struct}s as data.
1494 @cindex type definition
1495 @cindex data in Lisp and C
1496 @cindex translating types
1497 However, all of these are mostly sugar for the powerful underlying
1498 foreign type interface called @dfn{type translators}. You can easily
1499 define new translators for any simple named foreign type. Since we've
1500 defined the new type @code{curl-code} to use as the return type for
1501 various @code{libcurl} functions, we can use that to directly convert
1502 c@acronym{URL} errors to Lisp errors.
1504 @code{defctype}'s purpose is to define simple @code{typedef}-like
1505 aliases. In order to use @dfn{type translators} we must use the
1506 @code{define-foreign-type} macro. So let's redefine @code{curl-code}
1510 (define-foreign-type curl-code-type ()
1513 (:simple-parser curl-code))
1516 @code{define-foreign-type} is a thin wrapper around @code{defclass}.
1517 For now, all you need to know in the context of this example is that
1518 it does what @code{(defctype curl-code :int)} would do and,
1519 additionally, defines a new class @code{curl-code-type} which we will
1520 take advantage of shortly.
1522 The @code{CURLcode} enumeration seems to follow the typical error code
1523 convention of @samp{0} meaning all is well, and each non-zero integer
1524 indicating a different kind of error. We can apply that trivially to
1525 differentiate between normal exits and error exits.
1528 (define-condition curl-code-error (error)
1529 (($code :initarg :curl-code :reader curl-error-code))
1530 (:report (lambda (c stream)
1531 (format stream "libcurl function returned error ~A"
1532 (curl-error-code c))))
1533 (:documentation "Signalled when a libcurl function answers
1534 a code other than CURLE_OK."))
1536 (defmethod translate-from-foreign (value (type curl-code-type))
1537 "Raise a CURL-CODE-ERROR if VALUE, a curl-code, is non-zero."
1540 (error 'curl-code-error :curl-code value)))
1544 The heart of this translator is new method
1545 @code{translate-from-foreign}. By specializing the @var{type}
1546 parameter on @code{curl-code-type}, we immediately modify the behavior
1547 of every function that returns a @code{curl-code} to pass the result
1548 through this new method.
1550 To see the translator in action, try invoking a function that returns
1551 a @code{curl-code}. You need to reevaluate the respective
1552 @code{defcfun} form so that it picks up the new @code{curl-code}
1556 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1)
1561 As the result was @samp{0}, the new method returned @code{:curle-ok},
1562 just as specified.@footnote{It might be better to return
1563 @code{(values)} than @code{:curle-ok} in real code, but this is good
1564 for illustration.} I will leave disjoining the separate
1565 @code{CURLcode}s into condition types and improving the @code{:report}
1566 function as an exercise for you.
1568 The creation of @code{*easy-handle-cstrings*} and
1569 @code{*easy-handle-errorbuffers*} as properties of @code{easy-handle}s
1570 is a kluge. What we really want is a Lisp structure that stores these
1571 properties along with the C pointer. Unfortunately,
1572 @code{easy-handle} is currently just a fancy name for the foreign type
1573 @code{:pointer}; the actual pointer object varies from Common Lisp
1574 implementation to implementation, needing only to satisfy
1575 @code{pointerp} and be returned from @code{make-pointer} and friends.
1577 One solution that would allow us to define a new Lisp structure to
1578 represent @code{easy-handle}s would be to write a wrapper around every
1579 function that currently takes an @code{easy-handle}; the wrapper would
1580 extract the pointer and pass it to the foreign function. However, we
1581 can use type translators to more elegantly integrate this
1582 ``translation'' into the foreign function calling framework, using
1583 @code{translate-to-foreign}.
1586 (defclass easy-handle ()
1587 ((pointer :initform (curl-easy-init)
1588 :documentation "Foreign pointer from curl_easy_init")
1590 :initform (foreign-alloc :char :count *curl-error-size*
1592 :documentation "C string describing last error")
1593 (c-strings :initform '()
1594 :documentation "C strings set as options"))
1595 (:documentation "I am a parameterization you may pass to
1596 curl-easy-perform to perform a cURL network protocol request."))
1598 (defmethod initialize-instance :after ((self easy-handle) &key)
1599 (set-curl-option-errorbuffer self (slot-value self 'error-buffer)))
1601 (defun add-curl-handle-cstring (handle cstring)
1602 "Add CSTRING to be freed when HANDLE is, answering CSTRING."
1603 (car (push cstring (slot-value handle 'c-strings))))
1605 (defun get-easy-handle-error (handle)
1606 "Answer a string containing HANDLE's current error message."
1607 (foreign-string-to-lisp
1608 (slot-value handle 'error-buffer)))
1610 (defun free-easy-handle (handle)
1611 "Free CURL easy interface HANDLE and any C strings created to
1613 (with-slots (pointer error-buffer c-strings) handle
1614 (curl-easy-cleanup pointer)
1615 (foreign-free error-buffer)
1616 (mapc #'foreign-string-free c-strings)))
1618 (define-foreign-type easy-handle-type ()
1620 (:actual-type :pointer)
1621 (:simple-parser easy-handle))
1623 (defmethod translate-to-foreign (handle (type easy-handle-type))
1624 "Extract the pointer from an easy-HANDLE."
1625 (slot-value handle 'pointer))
1628 While we changed some of the Lisp functions defined earlier to use
1629 @acronym{CLOS} slots rather than hash tables, the foreign functions
1630 work just as well as they did before.
1632 @cindex limitations of type translators
1633 The greatest strength, and the greatest limitation, of the type
1634 translator comes from its generalized interface. As stated
1635 previously, we could define all foreign function calls in terms of the
1636 primitive foreign types provided by @cffi{}. The type translator
1637 interface allows us to cleanly specify the relationship between Lisp
1638 and C data, independent of where it appears in a function call. This
1639 independence comes at a price; for example, it cannot be used to
1640 modify translation semantics based on other arguments to a function
1641 call. In these cases, you should rely on other features of Lisp,
1642 rather than the powerful, yet domain-specific, type translator
1646 @node Tutorial-Conclusion
1647 @section What's next?
1649 @cffi{} provides a rich and powerful foundation for communicating with
1650 foreign libraries; as we have seen, it is up to you to make that
1651 experience a pleasantly Lispy one. This tutorial does not cover all
1652 the features of @cffi{}; please see the rest of the manual for
1653 details. In particular, if something seems obviously missing, it is
1654 likely that either code or a good reason for lack of code is already
1657 @impnote{There are some other things in @cffi{} that might deserve
1658 tutorial sections, such as define-foreign-type,
1659 free-translated-object, or structs. Let us know which ones you care
1663 @c ===================================================================
1664 @c CHAPTER: Wrapper generators
1666 @node Wrapper generators
1667 @chapter Wrapper generators
1669 @cffi{}'s interface is designed for human programmers, being aimed at
1670 aesthetic as well as technical sophistication. However, there are a
1671 few programs aimed at translating C and C++ header files, or
1672 approximations thereof, into @cffi{} forms constituting a foreign
1673 interface to the symbols in those files.
1675 These wrapper generators are known to support output of @cffi{} forms.
1678 @item @uref{http://www.cliki.net/Verrazano,Verrazano}
1679 Designed specifically for Common Lisp. Uses @acronym{GCC}'s parser
1680 output in @acronym{XML} format to discover functions, variables, and
1681 other header file data. This means you need @acronym{GCC} to generate
1682 forms; on the other hand, the parser employed is mostly compliant with
1685 @item @uref{http://www.cliki.net/SWIG,SWIG}
1686 A foreign interface generator originally designed to generate Python
1687 bindings, it has been ported to many other systems, including @cffi{}
1688 in version 1.3.28. Includes its own C declaration munger, not
1689 intended to be fully-compliant with @acronym{ANSI} C.
1692 First, this manual does not describe use of these other programs; they
1693 have documentation of their own. If you have problems using a
1694 generated interface, please look at the output @cffi{} forms and
1695 verify that they are a correct @cffi{} interface to the library in
1696 question; if they are correct, contact @cffi{} developers with
1697 details, keeping in mind that they communicate in terms of those forms
1698 rather than any particular wrapper generator. Otherwise, contact the
1699 maintainers of the wrapper generator you are using, provided you can
1700 reasonably expect more accuracy from the generator.
1702 When is more accuracy an unreasonable expectation? As described in
1703 the tutorial (@pxref{Tutorial-Abstraction,, Breaking the
1704 abstraction}), the information in C declarations is insufficient to
1705 completely describe every interface. In fact, it is quite common to
1706 run into an interface that cannot be handled automatically, and
1707 generators should be excused from generating a complete interface in
1710 As further described in the tutorial, the thinnest Lisp interface to a
1711 C function is not always the most pleasant one. In many cases, you
1712 will want to manually write a Lispier interface to the C functions
1715 Wrapper generators should be treated as time-savers, not complete
1716 automation of the full foreign interface writing job. Reports of the
1717 amount of work done by generators vary from 30% to 90%. The
1718 incremental development style enabled by @cffi{} generally reduces
1719 this proportion below that for languages like Python.
1721 @c Where I got the above 30-90% figures:
1722 @c 30%: lemonodor's post about SWIG
1723 @c 90%: Balooga on #lisp. He said 99%, but that's probably an
1724 @c exaggeration (leave it to me to pass judgement :)
1728 @c ===================================================================
1729 @c CHAPTER: Foreign Types
1732 @chapter Foreign Types
1734 Foreign types describe how data is translated back and forth between C
1735 and Lisp. @cffi{} provides various built-in types and allows the user to
1741 * Defining Foreign Types::
1742 * Foreign Type Translators::
1743 * Optimizing Type Translators::
1744 * Foreign Structure Types::
1745 * Operations on Types::
1746 * Allocating Foreign Objects::
1750 * convert-from-foreign::
1751 * convert-to-foreign::
1757 @c * define-type-spec-parser::
1758 * define-foreign-type::
1759 * define-parse-method::
1760 @c * explain-foreign-slot-value:
1761 * foreign-bitfield-symbols::
1762 * foreign-bitfield-value::
1763 * foreign-enum-keyword::
1764 * foreign-enum-value::
1765 * foreign-slot-names::
1766 * foreign-slot-offset::
1767 * foreign-slot-pointer::
1768 * foreign-slot-value::
1769 * foreign-type-alignment::
1770 * foreign-type-size::
1771 * free-converted-object::
1772 * free-translated-object::
1773 * translate-from-foreign::
1774 * translate-to-foreign::
1775 * with-foreign-slots::
1778 @node Built-In Types
1779 @section Built-In Types
1782 @ForeignType{:unsigned-char}
1783 @ForeignType{:short}
1784 @ForeignType{:unsigned-short}
1786 @ForeignType{:unsigned-int}
1788 @ForeignType{:unsigned-long}
1789 @ForeignType{:long-long}
1790 @ForeignType{:unsigned-long-long}
1792 These types correspond to the native C integer types according to the
1793 @acronym{ABI} of the Lisp implementation's host system.
1795 @ForeignType{:uchar}
1796 @ForeignType{:ushort}
1798 @ForeignType{:ulong}
1799 @ForeignType{:llong}
1800 @ForeignType{:ullong}
1802 For convenience, the above types are provided as shortcuts for
1803 @code{unsigned-char}, @code{unsigned-short}, @code{unsigned-int},
1804 @code{unsigned-long}, @code{long-long} and @code{unsigned-long-long},
1807 @code{:long-long} and @code{:unsigned-long-long} are not supported on
1808 all implementations. When those types are @strong{not} available, the
1809 symbol @code{cffi-features:no-long-long} is pushed into
1813 @ForeignType{:uint8}
1814 @ForeignType{:int16}
1815 @ForeignType{:uint16}
1816 @ForeignType{:int32}
1817 @ForeignType{:uint32}
1818 @ForeignType{:int64}
1819 @ForeignType{:uint64}
1821 Foreign integer types of specific sizes, corresponding to the C types
1822 defined in @code{stdint.h}.
1824 @c @ForeignType{:size}
1825 @c @ForeignType{:ssize}
1826 @c @ForeignType{:ptrdiff}
1827 @c @ForeignType{:time}
1829 @c Foreign integer types corresponding to the standard C types (without
1830 @c the @code{_t} suffix).
1832 @c @impnote{These are not implemented yet. --luis}
1834 @c @impnote{I'm sure there are more of these that could be useful, let's
1835 @c add any types that can't be defined portably to this list as
1836 @c necessary. --james}
1838 @ForeignType{:float}
1839 @ForeignType{:double}
1841 On all systems, the @code{:float} and @code{:double} types represent a
1842 C @code{float} and @code{double}, respectively. On most but not all
1843 systems, @code{:float} and @code{:double} represent a Lisp
1844 @code{single-float} and @code{double-float}, respectively. It is not
1845 so useful to consider the relationship between Lisp types and C types
1846 as isomorphic, as simply to recognize the relationship, and relative
1847 precision, among each respective category.
1849 @ForeignType{:long-double}
1851 This type is only supported on SCL.
1853 @ForeignType{:pointer &optional type}
1855 A foreign pointer to an object of any type, corresponding to
1856 @code{void *}. You can optionally specify type of pointer
1857 (e.g. @code{(:pointer :char)}). Although @cffi{} won't do anything
1858 with that information yet, it is useful for documentation purposes.
1862 No type at all. Only valid as the return type of a function.
1865 @section Other Types
1867 @cffi{} also provides a few useful types that aren't built-in C
1870 @ForeignType{:string}
1872 The @code{:string} type performs automatic conversion between Lisp and
1873 C strings. Note that, in the case of functions the converted C string
1874 will have dynamic extent (i.e.@: it will be automatically freed after
1875 the foreign function returns).
1877 In addition to Lisp strings, this type will also convert
1878 Lisp arrays of element type @code{(unsigned-byte 8)} and will pass
1879 foreign pointers unmodified.
1881 A method for @ref{free-translated-object} is specialized for this
1882 type. So, for example, foreign strings allocated by this type and
1883 passed to a foreign function will be freed after the function
1887 CFFI> (foreign-funcall "getenv" :string "SHELL" :string)
1888 @result{} "/bin/bash"
1890 CFFI> (with-foreign-string (str "abcdef")
1891 (foreign-funcall "strlen" :string str :int))
1894 CFFI> (let ((str (make-array 4 :element-type '(unsigned-byte 8)
1895 :initial-element 65)))
1896 (foreign-funcall "strlen" :string str :int))
1900 @ForeignType{:string+ptr}
1902 Like @code{:string} but returns a list with two values when convert
1903 from C to Lisp: a Lisp string and the C string's foreign pointer.
1906 CFFI> (foreign-funcall "getenv" :string "SHELL" :string+ptr)
1907 @result{} ("/bin/bash" #.(SB-SYS:INT-SAP #XBFFFFC6F))
1910 @ForeignType{:boolean &optional (base-type :int)}
1912 The @code{:boolean} type converts between a Lisp boolean and a C
1913 boolean. It canonicalizes to @var{base-type} which is @code{:int} by
1917 (convert-to-foreign nil :boolean) @result{} 0
1918 (convert-to-foreign t :boolean) @result{} 1
1919 (convert-from-foreign 0 :boolean) @result{} nil
1920 (convert-from-foreign 1 :boolean) @result{} t
1923 @ForeignType{:wrapper base-type &key to-c from-c}
1925 The @code{:wrapper} type stores two symbols passed to the @var{to-c}
1926 and @var{from-c} arguments. When a value is being translated to or
1927 from C, this type @code{funcall}s the respective symbol.
1929 @code{:wrapper} types will be typedefs for @var{base-type} and will
1930 inherit its translators, if any.
1932 Here's an example of how the @code{:boolean} type could be defined in
1933 terms of @code{:wrapper}.
1936 (defun bool-c-to-lisp (value)
1937 (not (zerop value)))
1939 (defun bool-lisp-to-c (value)
1942 (defctype my-bool (:wrapper :int :from-c bool-c-to-lisp
1943 :to-c bool-lisp-to-c))
1945 (convert-to-foreign nil 'my-bool) @result{} 0
1946 (convert-from-foreign 1 'my-bool) @result{} t
1949 @node Defining Foreign Types
1950 @section Defining Foreign Types
1952 You can define simple C-like @code{typedef}s through the
1953 @code{defctype} macro. Defining a typedef is as simple as giving
1954 @code{defctype} a new name and the name of the type to be wrapped.
1957 ;;; @lispcmt{Define MY-INT as an alias for the built-in type :INT.}
1958 (defctype my-int :int)
1961 With this type definition, one can, for instance, declare arguments to
1962 foreign functions as having the type @code{my-int}, and they will be
1965 @subheading More complex types
1967 @cffi{} offers another way to define types through
1968 @code{define-foreign-type}, a thin wrapper macro around
1969 @code{defclass}. As an example, let's go through the steps needed to
1970 define a @code{(my-string &key encoding)} type. First, we need to
1971 define our type class:
1974 (define-foreign-type my-string-type ()
1975 ((encoding :reader string-type-encoding :initarg :encoding))
1976 (:actual-type :pointer))
1979 The @code{:actual-type} class option tells CFFI that this type will
1980 ultimately be passed to and received from foreign code as a
1981 @code{:pointer}. Now you need to tell CFFI how to parse a type
1982 specification such as @code{(my-string :encoding :utf8)} into an
1983 instance of @code{my-string-type}. We do that with
1984 @code{define-parse-method}:
1987 (define-parse-method my-string (&key (encoding :utf-8))
1988 (make-instance 'my-string-type :encoding encoding))
1991 The next section describes how make this type actually translate
1992 between C and Lisp strings.
1994 @node Foreign Type Translators
1995 @section Foreign Type Translators
1997 Type translators are used to automatically convert Lisp values to or
1998 from foreign values. For example, using type translators, one can
1999 take the @code{my-string} type defined in the previous section and
2000 specify that it should:
2004 convert C strings to Lisp strings;
2006 convert Lisp strings to newly allocated C strings;
2008 free said C strings when they are no longer needed.
2011 In order to tell @cffi{} how to automatically convert Lisp values to
2012 foreign values, define a specialized method for the
2013 @code{translate-to-foreign} generic function:
2016 ;;; @lispcmt{Define a method that converts Lisp strings to C strings.}
2017 (defmethod translate-to-foreign (string (type my-string-type))
2018 (foreign-string-alloc string :encoding (string-type-encoding type)))
2022 From now on, whenever an object is passed as a @code{my-string} to a
2023 foreign function, this method will be invoked to convert the Lisp
2024 value. To perform the inverse operation, which is needed for functions
2025 that return a @code{my-string}, specialize the
2026 @code{translate-from-foreign} generic function in the same manner:
2029 ;;; @lispcmt{Define a method that converts C strings to Lisp strings.}
2030 (defmethod translate-from-foreign (pointer (type my-string-type))
2031 (foreign-string-to-lisp pointer :encoding (string-type-encoding type)))
2035 When a @code{translate-to-foreign} method requires allocation of
2036 foreign memory, you must also define a @code{free-translated-object}
2037 method to free the memory once the foreign object is no longer needed,
2038 otherwise you'll be faced with memory leaks. This generic function is
2039 called automatically by @cffi{} when passing objects to foreign
2040 functions. Let's do that:
2043 ;;; @lispcmt{Free strings allocated by translate-to-foreign.}
2044 (defmethod free-translated-object (pointer (type my-string-type) param)
2045 (declare (ignore param))
2046 (foreign-string-free pointer))
2050 In this specific example, we don't need the @var{param} argument, so
2051 we ignore it. See @ref{free-translated-object}, for an explanation of
2052 its purpose and how you can use it.
2054 A type translator does not necessarily need to convert the value. For
2055 example, one could define a typedef for @code{:pointer} that ensures,
2056 in the @code{translate-to-foreign} method, that the value is not a
2057 null pointer, signalling an error if a null pointer is passed. This
2058 would prevent some pointer errors when calling foreign functions that
2059 cannot handle null pointers.
2061 @strong{Please note:} these methods are meant as extensible hooks
2062 only, and you should not call them directly. Use
2063 @code{convert-to-foreign}, @code{convert-from-foreign} and
2064 @code{free-converted-object} instead.
2066 @xref{Tutorial-Types,, Defining new types}, for another example of
2069 @node Optimizing Type Translators
2070 @section Optimizing Type Translators
2072 @cindex type translators, optimizing
2073 @cindex compiler macros for type translation
2074 @cindex defining type-translation compiler macros
2075 Being based on generic functions, the type translation mechanism
2076 described above can add a bit of overhead. This is usually not
2077 significant, but we nevertheless provide a way of getting rid of the
2078 overhead for the cases where it matters.
2080 A good way to understand this issue is to look at the code generated
2081 by @code{defcfun}. Consider the following example using the previously
2082 defined @code{my-string} type:
2085 CFFI> (macroexpand-1 '(defcfun foo my-string (x my-string)))
2086 ;; (simplified, downcased, etc...)
2088 (multiple-value-bind (#:G2019 #:PARAM3149)
2089 (translate-to-foreign x #<MY-STRING-TYPE @{11ED5A79@}>)
2091 (translate-from-foreign
2092 (foreign-funcall "foo" :pointer #:G2019 :pointer)
2093 #<MY-STRING-TYPE @{11ED5659@}>)
2094 (free-translated-object #:G2019 #<MY-STRING-TYPE @{11ED51A79@}>
2099 In order to get rid of those generic function calls, @cffi{} has
2100 another set of extensible generic functions that provide functionality
2101 similar to @acronym{CL}'s compiler macros:
2102 @code{expand-to-foreign-dyn}, @code{expand-to-foreign} and
2103 @code{expand-from-foreign}. Here's how one could define a
2104 @code{my-boolean} with them:
2107 (define-foreign-type my-boolean-type ()
2110 (:simple-parser my-boolean))
2112 (defmethod expand-to-foreign (value (type my-boolean-type))
2115 (defmethod expand-from-foreign (value (type my-boolean-type))
2116 `(not (zerop ,value)))
2120 And here's what the macroexpansion of a function using this type would
2124 CFFI> (macroexpand-1 '(defcfun bar my-boolean (x my-boolean)))
2125 ;; (simplified, downcased, etc...)
2127 (let ((#:g3182 (if x 1 0)))
2128 (not (zerop (foreign-funcall "bar" :int #:g3182 :int)))))
2132 No generic function overhead.
2134 Let's go back to our @code{my-string} type. The expansion interface
2135 has no equivalent of @code{free-translated-object}; you must instead
2136 define a method on @code{expand-to-foreign-dyn}, the third generic
2137 function in this interface. This is especially useful when you can
2138 allocate something much more efficiently if you know the object has
2139 dynamic extent, as is the case with function calls that don't save the
2140 relevant allocated arguments.
2142 This exactly what we need for the @code{my-string} type:
2145 (defmethod expand-from-foreign (form (type my-string-type))
2146 `(foreign-string-to-lisp ,form))
2148 (defmethod expand-to-foreign-dyn (value var body (type my-string-type))
2149 (let ((encoding (string-type-encoding type)))
2150 `(with-foreign-string (,var ,value :encoding ',encoding)
2155 So let's look at the macro expansion:
2158 CFFI> (macroexpand-1 '(defcfun foo my-string (x my-string)))
2159 ;; (simplified, downcased, etc...)
2161 (with-foreign-string (#:G2021 X :encoding ':utf-8)
2162 (foreign-string-to-lisp
2163 (foreign-funcall "foo" :pointer #:g2021 :pointer))))
2167 Again, no generic function overhead.
2169 @subheading Other details
2171 To short-circuit expansion and use the @code{translate-*} functions
2172 instead, simply call the next method. Return its result in cases
2173 where your method cannot generate an appropriate replacement for it.
2174 This analogous to the @code{&whole form} mechanism compiler macros
2177 The @code{expand-*} methods have precedence over their
2178 @code{translate-*} counterparts and are guaranteed to be used in
2179 @code{defcfun}, @code{foreign-funcall}, @code{defcvar} and
2180 @code{defcallback}. If you define a method on each of the
2181 @code{expand-*} generic functions, you are guaranteed to have full
2182 control over the expressions generated for type translation in these
2185 They may or may not be used in other @cffi{} operators that need to
2186 translate between Lisp and C data; you may only assume that
2187 @code{expand-*} methods will probably only be called during Lisp
2190 @code{expand-to-foreign-dyn} has precedence over
2191 @code{expand-to-foreign} and is only used in @code{defcfun} and
2192 @code{foreign-funcall}, only making sense in those contexts.
2194 @strong{Important note:} this set of generic functions is called at
2195 macroexpansion time. Methods are defined when loaded or evaluated,
2196 not compiled. You are responsible for ensuring that your
2197 @code{expand-*} methods are defined when the @code{foreign-funcall} or
2198 other forms that use them are compiled. One way to do this is to put
2199 the method definitions earlier in the file and inside an appropriate
2200 @code{eval-when} form; another way is to always load a separate Lisp
2201 or @acronym{FASL} file containing your @code{expand-*} definitions
2202 before compiling files with forms that ought to use them. Otherwise,
2203 they will not be found and the runtime translators will be used
2206 @node Foreign Structure Types
2207 @section Foreign Structure Types
2209 For more involved C types than simple aliases to built-in types, such
2210 as you can make with @code{defctype}, @cffi{} allows declaration of
2211 structures and unions with @code{defcstruct} and @code{defcunion}.
2213 For example, consider this fictional C structure declaration holding
2214 some personal information:
2224 The equivalent @code{defcstruct} form follows:
2232 @cffi{} knows how to align C @code{struct}s, and how to figure in
2233 padding between struct elements.
2235 Please note that this interface is only for those that must know about
2236 the values contained in a relevant struct. If the library you are
2237 interfacing returns an opaque pointer that needs only be passed to
2238 other C library functions, by all means just use @code{:pointer} or a
2239 type-safe definition munged together with @code{defctype} and type
2242 @node Operations on Types
2243 @section Operations on Types
2245 @impnote{Which ``operations'' are worth going over here? --stephen}
2247 @node Allocating Foreign Objects
2248 @section Allocating Foreign Objects
2250 @c I moved this because I moved with-foreign-object to the Pointers
2251 @c chapter, where foreign-alloc is.
2253 @xref{Allocating Foreign Memory}.
2256 @c ===================================================================
2257 @c CONVERT-FROM-FOREIGN
2259 @node convert-from-foreign
2260 @unnumberedsec convert-from-foreign
2262 @Function{convert-from-foreign foreign-value type @result{} value}
2264 @subheading Arguments and Values
2268 The primitive C value as returned from a primitive foreign function or
2269 from @code{convert-to-foreign}.
2272 A @cffi{} type specifier.
2275 The Lisp value translated from @var{foreign-value}.
2278 @subheading Description
2280 This is an external interface to the type translation facility. In
2281 the implementation, all foreign functions are ultimately defined as
2282 type translation wrappers around primitive foreign function
2285 This function is available mostly for inspection of the type
2286 translation process, and possibly optimization of special cases of
2287 your foreign function calls.
2289 Its behavior is better described under @code{translate-from-foreign}'s
2292 @subheading Examples
2295 CFFI-USER> (convert-to-foreign "a boat" :string)
2296 @result{} #<FOREIGN-ADDRESS #x097ACDC0>
2298 CFFI-USER> (convert-from-foreign * :string)
2302 @subheading See Also
2303 @seealso{convert-to-foreign} @*
2304 @seealso{translate-from-foreign}
2307 @c ===================================================================
2308 @c CONVERT-TO-FOREIGN
2310 @node convert-to-foreign
2311 @unnumberedsec convert-to-foreign
2313 @Function{convert-to-foreign value type @result{} foreign-value, alloc-params}
2315 @subheading Arguments and Values
2319 The Lisp object to be translated to a foreign object.
2322 A @cffi{} type specifier.
2325 The primitive C value, ready to be passed to a primitive foreign
2329 Something of a translation state; you must pass it to
2330 @code{free-converted-object} along with the foreign value for that to
2334 @subheading Description
2336 This is an external interface to the type translation facility. In
2337 the implementation, all foreign functions are ultimately defined as
2338 type translation wrappers around primitive foreign function
2341 This function is available mostly for inspection of the type
2342 translation process, and possibly optimization of special cases of
2343 your foreign function calls.
2345 Its behavior is better described under @code{translate-to-foreign}'s
2348 @subheading Examples
2351 CFFI-USER> (convert-to-foreign t :boolean)
2354 CFFI-USER> (convert-to-foreign "hello, world" :string)
2355 @result{} #<FOREIGN-ADDRESS #x097C5F80>
2357 CFFI-USER> (code-char (mem-aref * :char 5))
2361 @subheading See Also
2362 @seealso{convert-from-foreign} @*
2363 @seealso{free-converted-object} @*
2364 @seealso{translate-to-foreign}
2367 @c ===================================================================
2371 @unnumberedsec defbitfield
2373 @Macro{defbitfield name-and-options &body masks}
2375 masks ::= [docstring] @{ (symbol value) @}* @*
2376 name-and-options ::= name | (name &optional (base-type :int))
2378 @subheading Arguments and Values
2382 The name of the new bitfield type.
2385 A documentation string, ignored.
2388 A symbol denoting a foreign type.
2394 An integer representing a bitmask.
2397 @subheading Description
2398 The @code{defbitfield} macro is used to define foreign types that map
2399 lists of symbols to integer values.
2401 If @var{value} is omitted, it will be computed as follows: find the
2402 greatest @var{value} previously used, including those so computed,
2403 with only a single 1-bit in its binary representation (that is, powers
2404 of two), and left-shift it by one. This rule guarantees that a
2405 computed @var{value} cannot clash with previous values, but may clash
2406 with future explicitly specified values.
2408 Symbol lists will be automatically converted to values and vice versa
2409 when being passed as arguments to or returned from foreign functions,
2410 respectively. The same applies to any other situations where an object
2411 of a bitfield type is expected.
2413 Types defined with @code{defbitfield} canonicalize to @var{base-type}
2414 which is @code{:int} by default.
2416 @subheading Examples
2418 (defbitfield open-flags
2420 :wronly ;@lispcmt{#x0001}
2421 :rdwr ;@lispcmt{@dots{}}
2425 ;; @lispcmt{etc@dots{}}
2427 CFFI> (foreign-bitfield-symbols 'open-flags #b1101)
2428 @result{} (:RDONLY :WRONLY :NONBLOCK :APPEND)
2430 CFFI> (foreign-bitfield-value 'open-flags '(:rdwr :creat))
2431 @result{} 514 ; #x0202
2433 (defcfun ("open" unix-open) :int
2436 (mode :uint16)) ; unportable
2438 CFFI> (unix-open "/tmp/foo" '(:wronly :creat) #o644)
2441 ;;; @lispcmt{Consider also the following lispier wrapper around open()}
2442 (defun lispier-open (path mode &rest flags)
2443 (unix-open path flags mode))
2446 @subheading See Also
2447 @seealso{foreign-bitfield-value} @*
2448 @seealso{foreign-bitfield-symbols}
2451 @c ===================================================================
2455 @unnumberedsec defcstruct
2457 @Macro{defcstruct name-and-options &body doc-and-slots @result{} name}
2459 name-and-options ::= structure-name | (structure-name &key size)
2461 doc-and-slots ::= [docstring] @{ (slot-name slot-type &key count offset) @}*
2463 @subheading Arguments and Values
2466 @item structure-name
2467 The name of new structure type.
2470 A documentation string, ignored.
2473 A symbol naming the slot. It must be unique among slot names in this
2477 Use this option to override the size (in bytes) of the struct.
2480 The type specifier for the slot.
2483 Used to declare an array of size @var{count} inside the
2484 structure. Defaults to @code{1} as such an array and a single element
2485 are semantically equivalent.
2488 Overrides the slot's offset. The next slot's offset is calculated
2492 @subheading Description
2493 This defines a new @cffi{} aggregate type akin to C @code{struct}s.
2494 In other words, it specifies that foreign objects of the type
2495 @var{structure-name} are groups of different pieces of data, or
2496 ``slots'', of the @var{slot-type}s, distinguished from each other by
2497 the @var{slot-name}s. Each structure is located in memory at a
2498 position, and the slots are allocated sequentially beginning at that
2499 point in memory (with some padding allowances as defined by the C
2500 @acronym{ABI}, unless otherwise requested by specifying an
2501 @var{offset} from the beginning of the structure (offset 0).
2503 In other words, it is isomorphic to the C @code{struct}, giving
2504 several extra features.
2506 There are two kinds of slots, for the two kinds of @cffi{} types:
2510 Contain a single instance of a type that canonicalizes to a built-in
2511 type, such as @code{:long} or @code{:pointer}. Used for simple
2515 Contain an embedded structure or union, or an array of objects. Used
2516 for aggregate @cffi{} types.
2519 The use of @acronym{CLOS} terminology for the structure-related
2520 features is intentional; structure definitions are very much like
2521 classes with (far) fewer features.
2523 @subheading Examples
2526 "Pointer structure."
2530 CFFI> (with-foreign-object (ptr 'point)
2531 ;; @lispcmt{Initialize the slots}
2532 (setf (foreign-slot-value ptr 'point 'x) 42
2533 (foreign-slot-value ptr 'point 'y) 42)
2534 ;; @lispcmt{Return a list with the coordinates}
2535 (with-foreign-slots ((x y) ptr point)
2541 ;; @lispcmt{Using the :size and :offset options to define a partial structure.}
2542 ;; @lispcmt{(this is useful when you are interested in only a few slots}
2543 ;; @lispcmt{of a big foreign structure)}
2545 (defcstruct (foo :size 32)
2546 "Some struct with 32 bytes."
2547 ; @lispcmt{<16 bytes we don't care about>}
2548 (x :int :offset 16) ; @lispcmt{an int at offset 16}
2549 (y :int) ; @lispcmt{another int at offset 16+sizeof(int)}
2550 ; @lispcmt{<a couple more bytes we don't care about>}
2551 (z :char :offset 24)) ; @lispcmt{a char at offset 24}
2552 ; @lispcmt{<7 more bytes ignored (since size is 32)>}
2554 CFFI> (foreign-type-size 'foo)
2559 ;;; @lispcmt{Using :count to define arrays inside of a struct.}
2560 (defcstruct video_tuner
2561 (name :char :count 32))
2564 @subheading See Also
2565 @seealso{foreign-slot-pointer} @*
2566 @seealso{foreign-slot-value} @*
2567 @seealso{with-foreign-slots}
2570 @c ===================================================================
2574 @unnumberedsec defcunion
2576 @Macro{defcunion name &body doc-and-slots @result{} name}
2578 doc-and-slots ::= [docstring] @{ (slot-name slot-type &key count) @}*
2580 @subheading Arguments and Values
2584 The name of new union type.
2587 A documentation string, ignored.
2590 A symbol naming the slot.
2593 The type specifier for the slot.
2596 Used to declare an array of size @var{count} inside the
2600 @subheading Description
2601 A union is a structure in which all slots have an offset of zero. It
2602 is isomorphic to the C @code{union}. Therefore, you should use the
2603 usual foreign structure operations for accessing a union's slots.
2605 @subheading Examples
2607 (defcunion uint32-bytes
2608 (int-value :unsigned-int)
2609 (bytes :unsigned-char :count 4))
2612 @subheading See Also
2613 @seealso{foreign-slot-pointer} @*
2614 @seealso{foreign-slot-value}
2617 @c ===================================================================
2621 @unnumberedsec defctype
2623 @Macro{defctype name base-type &optional documentation}
2625 @subheading Arguments and Values
2629 The name of the new foreign type.
2632 A symbol or a list defining the new type.
2635 A documentation string, currently ignored.
2638 @subheading Description
2639 The @code{defctype} macro provides a mechanism similar to C's
2640 @code{typedef} to define new types. The new type inherits
2641 @var{base-type}'s translators, if any.
2643 There is no way to define translations for types for types defined
2644 with @code{defctype}. For that, you should use
2645 @ref{define-foreign-type}.
2647 @subheading Examples
2649 (defctype my-string :string
2650 "My own string type.")
2652 (defctype long-bools (:boolean :long)
2653 "Booleans that map to C longs.")
2656 @subheading See Also
2657 @seealso{define-foreign-type}
2660 @c ===================================================================
2664 @unnumberedsec defcenum
2666 @Macro{defcenum name-and-options &body enum-list}
2668 enum-list ::= [docstring] @{ keyword | (keyword value) @}*
2669 name-and-options ::= name | (name &optional (base-type :int))
2671 @subheading Arguments and Values
2675 The name of the new enum type.
2678 A documentation string, ignored.
2681 A symbol denoting a foreign type.
2687 An index value for a keyword.
2690 @subheading Description
2691 The @code{defcenum} macro is used to define foreign types that map
2692 keyword symbols to integer values, similar to the C @code{enum} type.
2694 If @var{value} is omitted its value will either be 0, if it's the
2695 first entry, or it it will continue the progression from the last
2698 Keywords will be automatically converted to values and vice-versa when
2699 being passed as arguments to or returned from foreign functions,
2700 respectively. The same applies to any other situations where an object
2701 of an @code{enum} type is expected.
2703 Types defined with @code{defcenum} canonicalize to @var{base-type}
2704 which is @code{:int} by default.
2706 @subheading Examples
2712 CFFI> (foreign-enum-value 'boolean :no)
2722 CFFI> (foreign-enum-keyword 'numbers 2)
2726 @subheading See Also
2727 @seealso{foreign-enum-value} @*
2728 @seealso{foreign-enum-keyword}
2731 @c ===================================================================
2732 @c DEFINE-FOREIGN-TYPE
2734 @node define-foreign-type
2735 @unnumberedsec define-foreign-type
2737 @Macro{define-foreign-type class-name supers slots &rest options @result{} class-name}
2739 options ::= (@code{:actual-type} @var{type}) | @
2740 (@code{:simple-parser} @var{symbol}) | @
2741 @emph{regular defclass option}
2743 @subheading Arguments and Values
2747 A symbol naming the new foreign type class.
2750 A list of symbols naming the super classes.
2753 A list of slot definitions, passed to @code{defclass}.
2756 @subheading Description
2760 The macro @code{define-foreign-type} defines a new class
2761 @var{class-name}. It is a thin wrapper around @code{defclass}. Among
2762 other things, it ensures that @var{class-name} becomes a subclass of
2763 @var{foreign-type}, what you need to know about that is that there's
2764 an initarg @code{:actual-type} which serves the same purpose as
2765 @code{defctype}'s @var{base-type} argument.
2767 @c TODO mention the type translators here
2770 @subheading Examples
2771 Taken from @cffi{}'s @code{:boolean} type definition:
2774 (define-foreign-type :boolean (&optional (base-type :int))
2775 "Boolean type. Maps to an :int by default. Only accepts integer types."
2782 :unsigned-long) base-type)))
2784 CFFI> (canonicalize-foreign-type :boolean)
2786 CFFI> (canonicalize-foreign-type '(:boolean :long))
2788 CFFI> (canonicalize-foreign-type '(:boolean :float))
2789 ;; @lispcmt{@error{} signalled by ECASE.}
2792 @subheading See Also
2793 @seealso{defctype} @*
2794 @seealso{define-parse-method}
2797 @c ===================================================================
2798 @c DEFINE-PARSE-METHOD
2800 @node define-parse-method
2801 @unnumberedsec define-parse-method
2803 @Macro{define-parse-method name lambda-list &body body @result{} name}
2805 @subheading Arguments and Values
2809 A symbol naming the new foreign type.
2812 A lambda list which is the argument list of the new foreign type.
2815 One or more forms that provide a definition of the new foreign type.
2818 @subheading Description
2821 @c TODO: update example. The boolean type is probably a good choice.
2823 @subheading Examples
2824 Taken from @cffi{}'s @code{:boolean} type definition:
2827 (define-foreign-type :boolean (&optional (base-type :int))
2828 "Boolean type. Maps to an :int by default. Only accepts integer types."
2835 :unsigned-long) base-type)))
2837 CFFI> (canonicalize-foreign-type :boolean)
2839 CFFI> (canonicalize-foreign-type '(:boolean :long))
2841 CFFI> (canonicalize-foreign-type '(:boolean :float))
2842 ;; @lispcmt{@error{} signalled by ECASE.}
2845 @subheading See Also
2846 @seealso{define-foreign-type}
2849 @c ===================================================================
2850 @c EXPLAIN-FOREIGN-SLOT-VALUE
2852 @c @node explain-foreign-slot-value
2853 @c @unnumberedsec explain-foreign-slot-value
2854 @c @subheading Syntax
2855 @c @Macro{explain-foreign-slot-value ptr type &rest slot-names}
2857 @c @subheading Arguments and Values
2870 @c @subheading Description
2871 @c This macro translates the slot access that would occur by calling
2872 @c @code{foreign-slot-value} with the same arguments into an equivalent
2873 @c expression in C and prints it to @code{*standard-output*}.
2875 @c @emph{Note: this is not implemented yet.}
2877 @c @subheading Examples
2879 @c CFFI> (explain-foreign-slot-value ptr 'timeval 'tv-secs)
2880 @c @result{} ptr->tv_secs
2882 @c CFFI> (explain-foreign-slot-value emp 'employee 'hire-date 'tv-usecs)
2883 @c @result{} emp->hire_date.tv_usecs
2886 @c @subheading See Also
2889 @c ===================================================================
2890 @c FOREIGN-BITFIELD-SYMBOLS
2892 @node foreign-bitfield-symbols
2893 @unnumberedsec foreign-bitfield-symbols
2895 @Function{foreign-bitfield-symbols type value @result{} symbols}
2897 @subheading Arguments and Values
2907 A potentially shared list of symbols.
2911 @subheading Description
2912 The function @code{foreign-bitfield-symbols} returns a possibly shared
2913 list of symbols that correspond to @var{value} in @var{type}.
2915 @subheading Examples
2922 CFFI> (foreign-bitfield-symbols 'boolean #b101)
2923 @result{} (FLAG-A FLAG-C)
2926 @subheading See Also
2927 @seealso{defbitfield} @*
2928 @seealso{foreign-bitfield-value}
2931 @c ===================================================================
2932 @c FOREIGN-BITFIELD-VALUE
2934 @node foreign-bitfield-value
2935 @unnumberedsec foreign-bitfield-value
2937 @Function{foreign-bitfield-value type symbols @result{} value}
2939 @subheading Arguments and Values
2943 A @code{bitfield} type.
2952 @subheading Description
2953 The function @code{foreign-bitfield-value} returns the @var{value} that
2954 corresponds to the symbols in the @var{symbols} list.
2956 @subheading Examples
2963 CFFI> (foreign-bitfield-value 'flags '(flag-a flag-c))
2967 @subheading See Also
2968 @seealso{defbitfield} @*
2969 @seealso{foreign-bitfield-symbols}
2972 @c ===================================================================
2973 @c FOREIGN-ENUM-KEYWORD
2975 @node foreign-enum-keyword
2976 @unnumberedsec foreign-enum-keyword
2978 @Function{foreign-enum-keyword type value &key errorp @result{} keyword}
2980 @subheading Arguments and Values
2984 An @code{enum} type.
2990 If true (the default), signal an error if @var{value} is not defined
2991 in @var{type}. If false, @code{foreign-enum-keyword} returns
2998 @subheading Description
2999 The function @code{foreign-enum-keyword} returns the keyword symbol
3000 that corresponds to @var{value} in @var{type}.
3002 An error is signaled if @var{type} doesn't contain such @var{value}
3003 and @var{errorp} is true.
3005 @subheading Examples
3011 CFFI> (foreign-enum-keyword 'boolean 1)
3015 @subheading See Also
3016 @seealso{defcenum} @*
3017 @seealso{foreign-enum-value}
3020 @c ===================================================================
3021 @c FOREIGN-ENUM-VALUE
3023 @node foreign-enum-value
3024 @unnumberedsec foreign-enum-value
3026 @Function{foreign-enum-value type keyword &key errorp @result{} value}
3028 @subheading Arguments and Values
3032 An @code{enum} type.
3038 If true (the default), signal an error if @var{keyword} is not
3039 defined in @var{type}. If false, @code{foreign-enum-value} returns
3046 @subheading Description
3047 The function @code{foreign-enum-value} returns the @var{value} that
3048 corresponds to @var{keyword} in @var{type}.
3050 An error is signaled if @var{type} doesn't contain such
3051 @var{keyword}, and @var{errorp} is true.
3053 @subheading Examples
3059 CFFI> (foreign-enum-value 'boolean :yes)
3063 @subheading See Also
3064 @seealso{defcenum} @*
3065 @seealso{foreign-enum-keyword}
3068 @c ===================================================================
3069 @c FOREIGN-SLOT-NAMES
3071 @node foreign-slot-names
3072 @unnumberedsec foreign-slot-names
3074 @Function{foreign-slot-names type @result{} names}
3076 @subheading Arguments and Values
3080 A foreign struct type.
3086 @subheading Description
3087 The function @code{foreign-slot-names} returns a potentially shared
3088 list of slot @var{names} for the given structure @var{type}. This list
3089 has no particular order.
3091 @subheading Examples
3097 CFFI> (foreign-slot-names 'timeval)
3098 @result{} (TV-SECS TV-USECS)
3101 @subheading See Also
3102 @seealso{defcstruct} @*
3103 @seealso{foreign-slot-offset} @*
3104 @seealso{foreign-slot-value} @*
3105 @seealso{foreign-slot-pointer}
3108 @c ===================================================================
3109 @c FOREIGN-SLOT-OFFSET
3111 @node foreign-slot-offset
3112 @unnumberedsec foreign-slot-offset
3114 @Function{foreign-slot-offset type slot-name @result{} offset}
3116 @subheading Arguments and Values
3120 A foreign struct type.
3129 @subheading Description
3130 The function @code{foreign-slot-offset} returns the @var{offset} in
3131 bytes of a slot in a foreign struct type.
3133 @subheading Examples
3139 CFFI> (foreign-slot-offset 'timeval 'tv-secs)
3141 CFFI> (foreign-slot-offset 'timeval 'tv-usecs)
3145 @subheading See Also
3146 @seealso{defcstruct} @*
3147 @seealso{foreign-slot-names} @*
3148 @seealso{foreign-slot-pointer} @*
3149 @seealso{foreign-slot-value}
3152 @c ===================================================================
3153 @c FOREIGN-SLOT-POINTER
3155 @node foreign-slot-pointer
3156 @unnumberedsec foreign-slot-pointer
3158 @Function{foreign-slot-pointer ptr type slot-name @result{} pointer}
3160 @subheading Arguments and Values
3164 A pointer to a structure.
3167 A foreign structure type.
3170 A slot name in the @var{type}.
3173 A pointer to the slot @var{slot-name}.
3176 @subheading Description
3177 Returns a pointer to the location of the slot @var{slot-name} in a
3178 foreign object of type @var{type} at @var{ptr}. The returned pointer
3179 points inside the structure. Both the pointer and the memory it points
3180 to have the same extent as @var{ptr}.
3182 For aggregate slots, this is the same value returned by
3183 @code{foreign-slot-value}.
3185 @subheading Examples
3188 "Pointer structure."
3192 CFFI> (with-foreign-object (ptr 'point)
3193 (foreign-slot-pointer ptr 'point 'x))
3194 @result{} #<FOREIGN-ADDRESS #xBFFF6E60>
3195 ;; @lispcmt{Note: the exact pointer representation varies from lisp to lisp.}
3198 @subheading See Also
3199 @seealso{defcstruct} @*
3200 @seealso{foreign-slot-value} @*
3201 @seealso{foreign-slot-names} @*
3202 @seealso{foreign-slot-offset}
3205 @c ===================================================================
3206 @c FOREIGN-SLOT-VALUE
3208 @node foreign-slot-value
3209 @unnumberedsec foreign-slot-value
3211 @Accessor{foreign-slot-value ptr type slot-name @result{} object}
3213 @subheading Arguments and Values
3217 A pointer to a structure.
3220 A foreign structure type.
3223 A symbol naming a slot in the structure type.
3226 The object contained in the slot specified by @var{slot-name}.
3229 @subheading Description
3230 For simple slots, @code{foreign-slot-value} returns the value of the
3231 object, such as a Lisp integer or pointer. In C, this would be
3232 expressed as @code{ptr->slot}.
3234 For aggregate slots, a pointer inside the structure to the beginning
3235 of the slot's data is returned. In C, this would be expressed as
3236 @code{&ptr->slot}. This pointer and the memory it points to have the
3237 same extent as @var{ptr}.
3239 There are compiler macros for @code{foreign-slot-value} and its
3240 @code{setf} expansion that open code the memory access when
3241 @var{type} and @var{slot-names} are constant at compile-time.
3243 @subheading Examples
3246 "Pointer structure."
3250 CFFI> (with-foreign-object (ptr 'point)
3251 ;; @lispcmt{Initialize the slots}
3252 (setf (foreign-slot-value ptr 'point 'x) 42
3253 (foreign-slot-value ptr 'point 'y) 42)
3254 ;; @lispcmt{Return a list with the coordinates}
3255 (with-foreign-slots ((x y) ptr point)
3260 @subheading See Also
3261 @seealso{defcstruct} @*
3262 @seealso{foreign-slot-names} @*
3263 @seealso{foreign-slot-offset} @*
3264 @seealso{foreign-slot-pointer} @*
3265 @seealso{with-foreign-slots}
3268 @c ===================================================================
3269 @c FOREIGN-TYPE-ALIGNMENT
3271 @node foreign-type-alignment
3272 @unnumberedsec foreign-type-alignment
3274 @c XXX: This is actually a generic function.
3275 @Function{foreign-type-alignment type @result{} alignment}
3277 @subheading Arguments and Values
3287 @subheading Description
3288 The function @code{foreign-type-alignment} returns the
3289 @var{alignment} of @var{type} in bytes.
3291 @subheading Examples
3293 CFFI> (foreign-type-alignment :char)
3295 CFFI> (foreign-type-alignment :short)
3297 CFFI> (foreign-type-alignment :int)
3305 CFFI> (foreign-type-alignment 'foo)
3309 @subheading See Also
3310 @seealso{foreign-type-size}
3313 @c ===================================================================
3314 @c FOREIGN-TYPE-SIZE
3316 @node foreign-type-size
3317 @unnumberedsec foreign-type-size
3319 @c XXX: this is actually a generic function.
3320 @Function{foreign-type-size type @result{} size}
3322 @subheading Arguments and Values
3332 @subheading Description
3333 The function @code{foreign-type-size} return the @var{size} of
3334 @var{type} in bytes. This includes any padding within and following
3335 the in-memory representation as needed to create an array of
3338 @subheading Examples
3344 CFFI> (foreign-type-size :double)
3346 CFFI> (foreign-type-size :char)
3348 CFFI> (foreign-type-size 'foo)
3352 @subheading See Also
3353 @seealso{foreign-type-alignment}
3356 @c ===================================================================
3357 @c FREE-CONVERTED-OBJECT
3359 @node free-converted-object
3360 @unnumberedsec free-converted-object
3362 @Function{free-converted-object foreign-value type params}
3364 @subheading Arguments and Values
3368 The C object to be freed.
3371 A @cffi{} type specifier.
3374 The state returned as the second value from @code{convert-to-foreign};
3375 used to implement the third argument to @code{free-translated-object}.
3378 @subheading Description
3380 The return value is unspecified.
3382 This is an external interface to the type translation facility. In
3383 the implementation, all foreign functions are ultimately defined as
3384 type translation wrappers around primitive foreign function
3387 This function is available mostly for inspection of the type
3388 translation process, and possibly optimization of special cases of
3389 your foreign function calls.
3391 Its behavior is better described under @code{free-translated-object}'s
3394 @subheading Examples
3397 CFFI-USER> (convert-to-foreign "a boat" :string)
3398 @result{} #<FOREIGN-ADDRESS #x097ACDC0>
3400 CFFI-USER> (free-converted-object * :string '(t))
3404 @subheading See Also
3405 @seealso{convert-from-foreign} @*
3406 @seealso{convert-to-foreign} @*
3407 @seealso{free-translated-object}
3410 @c ===================================================================
3411 @c FREE-TRANSLATED-OBJECT
3415 @node free-translated-object
3416 @unnumberedsec free-translated-object
3418 @GenericFunction{free-translated-object value type-name param}
3420 @subheading Arguments and Values
3424 The foreign value returned by @code{translate-to-foreign}.
3427 A symbol naming a foreign type defined by @code{defctype}.
3430 The second value, if any, returned by @code{translate-to-foreign}.
3433 @subheading Description
3434 This generic function may be specialized by user code to perform
3435 automatic deallocation of foreign objects as they are passed to C
3438 Any methods defined on this generic function must EQL-specialize the
3439 @var{type-name} parameter on a symbol defined as a foreign type by
3440 the @code{defctype} macro.
3442 @subheading See Also
3443 @seealso{Foreign Type Translators} @*
3444 @seealso{translate-to-foreign}
3447 @c ===================================================================
3448 @c TRANSLATE-FROM-FOREIGN
3452 @node translate-from-foreign
3453 @unnumberedsec translate-from-foreign
3455 @GenericFunction{translate-from-foreign foreign-value type-name @
3456 @result{} lisp-value}
3458 @subheading Arguments and Values
3462 The foreign value to convert to a Lisp object.
3465 A symbol naming a foreign type defined by @code{defctype}.
3468 The lisp value to pass in place of @code{foreign-value} to Lisp code.
3471 @subheading Description
3472 This generic function is invoked by @cffi{} to convert a foreign value to
3473 a Lisp value, such as when returning from a foreign function, passing
3474 arguments to a callback function, or accessing a foreign variable.
3476 To extend the @cffi{} type system by performing custom translations, this
3477 method may be specialized by @sc{eql}-specializing @code{type-name} on a
3478 symbol naming a foreign type defined with @code{defctype}. This
3479 method should return the appropriate Lisp value to use in place of the
3482 The results are undefined if the @code{type-name} parameter is
3483 specialized in any way except an @sc{eql} specializer on a foreign type
3484 defined with @code{defctype}. Specifically, translations may not be
3485 defined for built-in types.
3487 @subheading See Also
3488 @seealso{Foreign Type Translators} @*
3489 @seealso{translate-to-foreign} @*
3490 @seealso{free-translated-object}
3493 @c ===================================================================
3494 @c TRANSLATE-TO-FOREIGN
3498 @node translate-to-foreign
3499 @unnumberedsec translate-to-foreign
3501 @GenericFunction{translate-to-foreign lisp-value type-name @
3502 @result{} foreign-value, alloc-param}
3504 @subheading Arguments and Values
3508 The Lisp value to convert to foreign representation.
3511 A symbol naming a foreign type defined by @code{defctype}.
3514 The foreign value to pass in place of @code{lisp-value} to foreign code.
3517 If present, this value will be passed to
3518 @code{free-translated-object}.
3521 @subheading Description
3522 This generic function is invoked by @cffi{} to convert a Lisp value to a
3523 foreign value, such as when passing arguments to a foreign function,
3524 returning a value from a callback, or setting a foreign variable. A
3525 ``foreign value'' is one appropriate for passing to the next-lowest
3526 translator, including the low-level translators that are ultimately
3527 invoked invisibly with @cffi{}.
3529 To extend the @cffi{} type system by performing custom translations, this
3530 method may be specialized by @sc{eql}-specializing @code{type-name} on a
3531 symbol naming a foreign type defined with @code{defctype}. This
3532 method should return the appropriate foreign value to use in place of
3535 In cases where @cffi{} can determine the lifetime of the foreign object
3536 returned by this method, it will invoke @code{free-translated-object}
3537 on the foreign object at the appropriate time. If
3538 @code{translate-to-foreign} returns a second value, it will be passed
3539 as the @code{param} argument to @code{free-translated-object}. This
3540 can be used to establish communication between the allocation and
3541 deallocation methods.
3543 The results are undefined if the @code{type-name} parameter is
3544 specialized in any way except an @sc{eql} specializer on a foreign type
3545 defined with @code{defctype}. Specifically, translations may not be
3546 defined for built-in types.
3548 @subheading See Also
3549 @seealso{Foreign Type Translators} @*
3550 @seealso{translate-from-foreign} @*
3551 @seealso{free-translated-object}
3554 @c ===================================================================
3555 @c WITH-FOREIGN-SLOTS
3557 @node with-foreign-slots
3558 @unnumberedsec with-foreign-slots
3560 @Macro{with-foreign-slots (vars ptr type) &body body}
3562 @subheading Arguments and Values
3569 A foreign pointer to a structure.
3575 A list of forms to be executed.
3578 @subheading Description
3579 The @code{with-foreign-slots} macro creates local symbol macros for
3580 each var in @var{vars} to reference foreign slots in @var{ptr} of
3581 @var{type}. It is similar to Common Lisp's @code{with-slots} macro.
3583 @subheading Examples
3598 CFFI> (with-foreign-object (time :int)
3599 (setf (mem-ref time :int)
3600 (foreign-funcall "time" :pointer (null-pointer) :int))
3601 (foreign-funcall "gmtime" :pointer time tm))
3602 @result{} #<A Mac Pointer #x102A30>
3603 CFFI> (with-foreign-slots ((sec min hour mday mon year) * tm)
3604 (format nil "~A:~A:~A, ~A/~A/~A"
3605 hour min sec (+ 1900 year) mon mday))
3606 @result{} "7:22:47, 2005/8/2"
3609 @subheading See Also
3610 @seealso{defcstruct} @*
3611 @seealso{defcunion} @*
3612 @seealso{foreign-slot-value}
3615 @c ===================================================================
3616 @c CHAPTER: Pointers
3621 All C data in @cffi{} is referenced through pointers. This includes
3622 defined C variables that hold immediate values, and integers.
3624 To see why this is, consider the case of the C integer. It is not
3625 only an arbitrary representation for an integer, congruent to Lisp's
3626 fixnums; the C integer has a specific bit pattern in memory defined by
3627 the C @acronym{ABI}. Lisp has no such constraint on its fixnums;
3628 therefore, it only makes sense to think of fixnums as C integers if
3629 you assume that @cffi{} converts them when necessary, such as when
3630 storing one for use in a C function call, or as the value of a C
3631 variable. This requires defining an area of memory@footnote{The
3632 definition of @dfn{memory} includes the @acronym{CPU} registers.},
3633 represented through an effective address, and storing it there.
3635 Due to this compartmentalization, it only makes sense to manipulate
3636 raw C data in Lisp through pointers to it. For example, while there
3637 may be a Lisp representation of a @code{struct} that is converted to C
3638 at store time, you may only manipulate its raw data through a pointer.
3639 The C compiler does this also, albeit informally.
3642 * Basic Pointer Operations::
3643 * Allocating Foreign Memory::
3644 * Accessing Foreign Memory::
3650 * foreign-symbol-pointer::
3661 * with-foreign-object::
3662 * with-foreign-pointer::
3665 @node Basic Pointer Operations
3666 @section Basic Pointer Operations
3668 Manipulating pointers proper can be accomplished through most of the
3669 other operations defined in the Pointers dictionary, such as
3670 @code{make-pointer}, @code{pointer-address}, and @code{pointer-eq}.
3671 When using them, keep in mind that they merely manipulate the Lisp
3672 representation of pointers, not the values they point to.
3674 @deftp {Lisp Type} foreign-pointer
3675 The pointers' representations differ from implementation to
3676 implementation and have different types. @code{foreign-pointer}
3677 provides a portable type alias to each of these types.
3681 @node Allocating Foreign Memory
3682 @section Allocating Foreign Memory
3684 @cffi{} provides support for stack and heap C memory allocation.
3685 Stack allocation, done with @code{with-foreign-object}, is sometimes
3686 called ``dynamic'' allocation in Lisp, because memory allocated as
3687 such has dynamic extent, much as with @code{let} bindings of special
3690 This should not be confused with what C calls ``dynamic'' allocation,
3691 or that done with @code{malloc} and friends. This sort of heap
3692 allocation is done with @code{foreign-alloc}, creating objects that
3693 exist until freed with @code{foreign-free}.
3696 @node Accessing Foreign Memory
3697 @section Accessing Foreign Memory
3699 When manipulating raw C data, consider that all pointers are pointing
3700 to an array. When you only want one C value, such as a single
3701 @code{struct}, this array only has one such value. It is worthwhile
3702 to remember that everything is an array, though, because this is also
3703 the semantic that C imposes natively.
3705 C values are accessed as the @code{setf}-able places defined by
3706 @code{mem-aref} and @code{mem-ref}. Given a pointer and a @cffi{}
3707 type (@pxref{Foreign Types}), either of these will dereference the
3708 pointer, translate the C data there back to Lisp, and return the
3709 result of said translation, performing the reverse operation when
3710 @code{setf}-ing. To decide which one to use, consider whether you
3711 would use the array index operator @code{[@var{n}]} or the pointer
3712 dereference @code{*} in C; use @code{mem-aref} for array indexing and
3713 @code{mem-ref} for pointer dereferencing.
3716 @c ===================================================================
3720 @unnumberedsec foreign-free
3722 @Function{foreign-free ptr @result{} undefined}
3724 @subheading Arguments and Values
3731 @subheading Description
3732 The @code{foreign-free} function frees a @code{ptr} previously
3733 allocated by @code{foreign-alloc}. The consequences of freeing a given
3734 pointer twice are undefined.
3736 @subheading Examples
3739 CFFI> (foreign-alloc :int)
3740 @result{} #<A Mac Pointer #x1022E0>
3741 CFFI> (foreign-free *)
3745 @subheading See Also
3746 @seealso{foreign-alloc} @*
3747 @seealso{with-foreign-pointer}
3750 @c ===================================================================
3754 @unnumberedsec foreign-alloc
3756 @Function{foreign-alloc type &key initial-element initial-contents (count 1) @
3757 null-terminated-p @result{} pointer}
3759 @subheading Arguments and Values
3765 @item initial-element
3768 @item initial-contents
3772 An integer. Defaults to 1 or the length of @var{initial-contents} if
3775 @item null-terminated-p
3776 A boolean, false by default.
3779 A foreign pointer to the newly allocated memory.
3782 @subheading Description
3783 The @code{foreign-alloc} function allocates enough memory to hold
3784 @var{count} objects of type @var{type} and returns a
3785 @var{pointer}. This memory must be explicitly freed using
3786 @code{foreign-free} once it is no longer needed.
3788 If @var{initial-element} is supplied, it is used to initialize the
3789 @var{count} objects the newly allocated memory holds.
3791 If an @var{initial-contents} sequence is supplied, it must have a
3792 length less than or equal to @var{count} and each of its elements
3793 will be used to initialize the contents of the newly allocated
3796 If @var{count} is omitted and @var{initial-contents} is specified, it
3797 will default to @code{(length @var{initial-contents})}.
3799 @var{initial-element} and @var{initial-contents} are mutually
3802 When @var{null-terminated-p} is true,
3803 @code{(1+ (max @var{count} (length @var{initial-contents})))} elements
3804 are allocated and the last one is set to @code{NULL}. Note that in
3805 this case @var{type} must be a pointer type (ie. a type that
3806 canonicalizes to @code{:pointer}), otherwise an error is signaled.
3808 @subheading Examples
3810 CFFI> (foreign-alloc :char)
3811 @result{} #<A Mac Pointer #x102D80> ; @lispcmt{A pointer to 1 byte of memory.}
3813 CFFI> (foreign-alloc :char :count 20)
3814 @result{} #<A Mac Pointer #x1024A0> ; @lispcmt{A pointer to 20 bytes of memory.}
3816 CFFI> (foreign-alloc :int :initial-element 12)
3817 @result{} #<A Mac Pointer #x1028B0>
3818 CFFI> (mem-ref * :int)
3821 CFFI> (foreign-alloc :int :initial-contents '(1 2 3))
3822 @result{} #<A Mac Pointer #x102950>
3823 CFFI> (loop for i from 0 below 3
3824 collect (mem-aref * :int i))
3827 CFFI> (foreign-alloc :int :initial-contents #(1 2 3))
3828 @result{} #<A Mac Pointer #x102960>
3829 CFFI> (loop for i from 0 below 3
3830 collect (mem-aref * :int i))
3833 ;;; Allocate a char** pointer that points to newly allocated memory
3834 ;;; by the :string type translator for the string "foo".
3835 CFFI> (foreign-alloc :string :initial-element "foo")
3836 @result{} #<A Mac Pointer #x102C40>
3840 ;;; Allocate a null-terminated array of strings.
3841 ;;; (Note: FOREIGN-STRING-TO-LISP returns NIL when passed a null pointer)
3842 CFFI> (foreign-alloc :string
3843 :initial-contents '("foo" "bar" "baz")
3844 :null-terminated-p t)
3845 @result{} #<A Mac Pointer #x102D20>
3846 CFFI> (loop for i from 0 below 4
3847 collect (mem-aref * :string i))
3848 @result{} ("foo" "bar" "baz" NIL)
3851 (foreign-free (mem-aref ** :pointer i)))
3856 @subheading See Also
3857 @seealso{foreign-free} @*
3858 @seealso{with-foreign-object} @*
3859 @seealso{with-foreign-pointer}
3862 @c ===================================================================
3863 @c FOREIGN-SYMBOL-POINTER
3865 @node foreign-symbol-pointer
3866 @unnumberedsec foreign-symbol-pointer
3868 @Function{foreign-symbol-pointer foreign-name &key library @result{} pointer}
3870 @subheading Arguments and Values
3877 A foreign pointer, or @code{nil}.
3880 A Lisp symbol or an instance of @code{foreign-library}.
3883 @subheading Description
3884 The function @code{foreign-symbol-pointer} will return a foreign
3885 pointer corresponding to the foreign symbol denoted by the string
3886 @var{foreign-name}. If a foreign symbol named @var{foreign-name}
3887 doesn't exist, @code{nil} is returned.
3889 ABI name manglings will be performed on @var{foreign-name} by
3890 @code{foreign-symbol-pointer} if necessary. (eg: adding a leading
3891 underscore on darwin/ppc)
3893 @var{library} should name a foreign library as defined by
3894 @code{define-foreign-library}, @code{:default} (which is the default)
3895 or an instance of @code{foreign-library} as returned by
3896 @code{load-foreign-library}.
3898 @strong{Important note:} do not keep these pointers across saved Lisp
3899 cores as the foreign-library may move across sessions.
3901 @subheading Examples
3904 CFFI> (foreign-symbol-pointer "errno")
3905 @result{} #<A Mac Pointer #xA0008130>
3906 CFFI> (foreign-symbol-pointer "strerror")
3907 @result{} #<A Mac Pointer #x9002D0F8>
3908 CFFI> (foreign-funcall-pointer * () :int (mem-ref ** :int) :string)
3909 @result{} "No such file or directory"
3911 CFFI> (foreign-symbol-pointer "inexistent symbol")
3915 @subheading See Also
3919 @c ===================================================================
3923 @unnumberedsec inc-pointer
3925 @Function{inc-pointer pointer offset @result{} new-pointer}
3927 @subheading Arguments and Values
3938 @subheading Description
3939 The function @code{inc-pointer} will return a @var{new-pointer} pointing
3940 @var{offset} bytes past @var{pointer}.
3942 @subheading Examples
3945 CFFI> (foreign-string-alloc "Common Lisp")
3946 @result{} #<A Mac Pointer #x102EA0>
3947 CFFI> (inc-pointer * 7)
3948 @result{} #<A Mac Pointer #x102EA7>
3949 CFFI> (foreign-string-to-lisp *)
3953 @subheading See Also
3954 @seealso{incf-pointer} @*
3955 @seealso{make-pointer} @*
3956 @seealso{pointerp} @*
3957 @seealso{null-pointer} @*
3958 @seealso{null-pointer-p}
3961 @c ===================================================================
3965 @unnumberedsec inc-pointer
3967 @Macro{incf-pointer place &optional (offset 1) @result{} new-pointer}
3969 @subheading Arguments and Values
3973 A @code{setf} place.
3982 @subheading Description
3983 The @code{incf-pointer} macro takes the foreign pointer from
3984 @var{place} and creates a @var{new-pointer} incremented by
3985 @var{offset} bytes and which is stored in @var{place}.
3987 @subheading Examples
3990 CFFI> (defparameter *two-words* (foreign-string-alloc "Common Lisp"))
3991 @result{} *TWO-WORDS*
3992 CFFI> (defparameter *one-word* *two-words*)
3993 @result{} *ONE-WORD*
3994 CFFI> (incf-pointer *one-word* 7)
3995 @result{} #.(SB-SYS:INT-SAP #X00600457)
3996 CFFI> (foreign-string-to-lisp *one-word*)
3998 CFFI> (foreign-string-to-lisp *two-words*)
3999 @result{} "Common Lisp"
4002 @subheading See Also
4003 @seealso{inc-pointer} @*
4004 @seealso{make-pointer} @*
4005 @seealso{pointerp} @*
4006 @seealso{null-pointer} @*
4007 @seealso{null-pointer-p}
4010 @c ===================================================================
4014 @unnumberedsec make-pointer
4016 @Function{make-pointer address @result{} ptr}
4018 @subheading Arguments and Values
4028 @subheading Description
4029 The function @code{make-pointer} will return a foreign pointer
4030 pointing to @var{address}.
4032 @subheading Examples
4035 CFFI> (make-pointer 42)
4036 @result{} #<FOREIGN-ADDRESS #x0000002A>
4039 CFFI> (pointer-address **)
4041 CFFI> (inc-pointer *** -42)
4042 @result{} #<FOREIGN-ADDRESS #x00000000>
4043 CFFI> (null-pointer-p *)
4045 CFFI> (typep ** 'foreign-pointer)
4049 @subheading See Also
4050 @seealso{inc-pointer} @*
4051 @seealso{null-pointer} @*
4052 @seealso{null-pointer-p} @*
4053 @seealso{pointerp} @*
4054 @seealso{pointer-address} @*
4055 @seealso{pointer-eq} @*
4059 @c ===================================================================
4063 @unnumberedsec mem-aref
4065 @Accessor{mem-aref ptr type &optional (index 0)}
4067 (setf (@strong{mem-aref} @emph{ptr type &optional (index 0)) new-value})
4069 @subheading Arguments and Values
4082 A Lisp value compatible with @var{type}.
4085 @subheading Description
4086 The @code{mem-aref} function is similar to @code{mem-ref} but will
4087 automatically calculate the offset from an @var{index}.
4090 (mem-aref ptr type n)
4092 ;; @lispcmt{is identical to:}
4094 (mem-ref ptr type (* n (foreign-type-size type)))
4097 @subheading Examples
4100 CFFI> (with-foreign-string (str "Hello, foreign world!")
4101 (mem-aref str :char 6))
4106 CFFI> (with-foreign-object (array :int 10)
4107 (loop for i below 10
4108 do (setf (mem-aref array :int i) (random 100)))
4109 (loop for i below 10 collect (mem-aref array :int i)))
4110 @result{} (22 7 22 52 69 1 46 93 90 65)
4113 @subheading See Also
4117 @c ===================================================================
4121 @unnumberedsec mem-ref
4123 @Accessor{mem-ref ptr type &optional offset @result{} object}
4125 @subheading Arguments and Values
4135 An integer (in byte units).
4138 The value @var{ptr} points to.
4141 @subheading Description
4142 @subheading Examples
4145 CFFI> (with-foreign-string (ptr "Saluton")
4146 (setf (mem-ref ptr :char 3) (char-code #\a))
4147 (loop for i from 0 below 8
4148 collect (code-char (mem-ref ptr :char i))))
4149 @result{} (#\S #\a #\l #\a #\t #\o #\n #\Null)
4150 CFFI> (setq ptr-to-int (foreign-alloc :int))
4151 @result{} #<A Mac Pointer #x1047D0>
4152 CFFI> (mem-ref ptr-to-int :int)
4154 CFFI> (setf (mem-ref ptr-to-int :int) 1984)
4156 CFFI> (mem-ref ptr-to-int :int)
4160 @subheading See Also
4164 @c ===================================================================
4168 @unnumberedsec null-pointer
4170 @Function{null-pointer @result{} pointer}
4172 @subheading Arguments and Values
4176 A @code{NULL} pointer.
4179 @subheading Description
4180 The function @code{null-pointer} returns a null pointer.
4182 @subheading Examples
4185 CFFI> (null-pointer)
4186 @result{} #<A Null Mac Pointer>
4191 @subheading See Also
4192 @seealso{null-pointer-p} @*
4193 @seealso{make-pointer}
4196 @c ===================================================================
4199 @node null-pointer-p
4200 @unnumberedsec null-pointer-p
4202 @Function{null-pointer-p ptr @result{} boolean}
4204 @subheading Arguments and Values
4208 A foreign pointer that may be a null pointer.
4211 @code{T} or @code{NIL}.
4214 @subheading Description
4215 The function @code{null-pointer-p} returns true if @var{ptr} is a null
4216 pointer and false otherwise.
4218 @subheading Examples
4221 CFFI> (null-pointer-p (null-pointer))
4226 (defun contains-str-p (big little)
4227 (not (null-pointer-p
4228 (foreign-funcall "strstr" :string big :string little :pointer))))
4230 CFFI> (contains-str-p "Popcorns" "corn")
4232 CFFI> (contains-str-p "Popcorns" "salt")
4236 @subheading See Also
4237 @seealso{null-pointer} @*
4241 @c ===================================================================
4245 @unnumberedsec pointerp
4247 @Function{pointerp ptr @result{} boolean}
4249 @subheading Arguments and Values
4253 An object that may be a foreign pointer.
4256 @code{T} or @code{NIL}.
4259 @subheading Description
4260 The function @code{pointerp} returns true if @var{ptr} is a foreign
4261 pointer and false otherwise.
4263 @subheading Implementation-specific Notes
4264 In Allegro CL, foreign pointers are integers thus in this
4265 implementation @code{pointerp} will return true for any ordinary integer.
4267 @subheading Examples
4270 CFFI> (foreign-alloc 32)
4271 @result{} #<A Mac Pointer #x102D20>
4274 CFFI> (pointerp "this is not a pointer")
4278 @subheading See Also
4279 @seealso{make-pointer}
4280 @seealso{null-pointer-p}
4283 @c ===================================================================
4286 @node pointer-address
4287 @unnumberedsec pointer-address
4289 @Function{pointer-address ptr @result{} address}
4291 @subheading Arguments and Values
4301 @subheading Description
4302 The function @code{pointer-address} will return the @var{address} of
4303 a foreign pointer @var{ptr}.
4305 @subheading Examples
4308 CFFI> (pointer-address (null-pointer))
4310 CFFI> (pointer-address (make-pointer 123))
4314 @subheading See Also
4315 @seealso{make-pointer} @*
4316 @seealso{inc-pointer} @*
4317 @seealso{null-pointer} @*
4318 @seealso{null-pointer-p} @*
4319 @seealso{pointerp} @*
4320 @seealso{pointer-eq} @*
4324 @c ===================================================================
4328 @unnumberedsec pointer-eq
4330 @Function{pointer-eq ptr1 ptr2 @result{} boolean}
4332 @subheading Arguments and Values
4340 @code{T} or @code{NIL}.
4343 @subheading Description
4344 The function @code{pointer-eq} returns true if @var{ptr1} and
4345 @var{ptr2} point to the same memory address and false otherwise.
4347 @subheading Implementation-specific Notes
4348 The representation of foreign pointers varies across the various Lisp
4349 implementations as does the behaviour of the built-in Common Lisp
4350 equality predicates. Comparing two pointers that point to the same
4351 address with @code{EQ} Lisps will return true on some Lisps, others require
4352 more general predicates like @code{EQL} or @code{EQUALP} and finally
4353 some will return false using any of these predicates. Therefore, for
4354 portability, you should use @code{POINTER-EQ}.
4356 @subheading Examples
4357 This is an example using @acronym{SBCL}, see the
4358 implementation-specific notes above.
4361 CFFI> (eql (null-pointer) (null-pointer))
4363 CFFI> (pointer-eq (null-pointer) (null-pointer))
4367 @subheading See Also
4368 @seealso{inc-pointer}
4371 @c ===================================================================
4372 @c WITH-FOREIGN-OBJECT
4374 @node with-foreign-object
4375 @unnumberedsec with-foreign-object
4377 @Macro{with-foreign-object (var type &optional count) &body body}
4379 @Macro{with-foreign-objects (bindings) &body body}
4381 bindings ::= @{(var type &optional count)@}*
4383 @subheading Arguments and Values
4390 A foreign type, evaluated.
4396 @subheading Description
4397 The macros @code{with-foreign-object} and @code{with-foreign-objects}
4398 bind @var{var} to a pointer to @var{count} newly allocated objects
4399 of type @var{type} during @var{body}. The buffer has dynamic extent
4400 and may be stack allocated if supported by the host Lisp.
4402 @subheading Examples
4405 CFFI> (with-foreign-object (array :int 10)
4407 (setf (mem-aref array :int i) (random 100)))
4408 (loop for i below 10
4409 collect (mem-aref array :int i)))
4410 @result{} (22 7 22 52 69 1 46 93 90 65)
4413 @subheading See Also
4414 @seealso{foreign-alloc}
4417 @c ===================================================================
4418 @c WITH-FOREIGN-POINTER
4420 @node with-foreign-pointer
4421 @unnumberedsec with-foreign-pointer
4423 @Macro{with-foreign-pointer (var size &optional size-var) &body body}
4425 @subheading Arguments and Values
4436 A list of forms to be executed.
4439 @subheading Description
4440 The @code{with-foreign-pointer} macro, binds @var{var} to @var{size}
4441 bytes of foreign memory during @var{body}. The pointer in @var{var}
4442 is invalid beyond the dynamic extend of @var{body} and may be
4443 stack-allocated if supported by the implementation.
4445 If @var{size-var} is supplied, it will be bound to @var{size} during
4448 @subheading Examples
4451 CFFI> (with-foreign-pointer (string 4 size)
4452 (setf (mem-ref string :char (1- size)) 0)
4453 (lisp-string-to-foreign "Popcorns" string size)
4454 (loop for i from 0 below size
4455 collect (code-char (mem-ref string :char i))))
4456 @result{} (#\P #\o #\p #\Null)
4459 @subheading See Also
4460 @seealso{foreign-alloc} @*
4461 @seealso{foreign-free}
4464 @c ===================================================================
4470 As with many languages, Lisp and C have special support for logical
4471 arrays of characters, going so far as to give them a special name,
4472 ``strings''. In that spirit, @cffi{} provides special support for
4473 translating between Lisp and C strings.
4475 The @code{:string} type and the symbols related below also serve as an
4476 example of what you can do portably with @cffi{}; were it not
4477 included, you could write an equally functional @file{strings.lisp}
4478 without referring to any implementation-specific symbols.
4483 * foreign-string-alloc::
4484 * foreign-string-free::
4485 * foreign-string-to-lisp::
4486 * lisp-string-to-foreign::
4487 * with-foreign-string::
4488 * with-foreign-pointer-as-string::
4492 @c ===================================================================
4493 @c FOREIGN-STRING-ALLOC
4495 @node foreign-string-alloc
4496 @unnumberedsec foreign-string-alloc
4498 @Function{foreign-string-alloc string-or-ub8-array @result{} pointer}
4500 @subheading Arguments and Values
4503 @item string-or-ub8-array
4504 A Lisp string or a Lisp array with element-type @code{(unsigned-byte 8)}.
4507 A pointer to the newly allocated foreign string.
4510 @subheading Description
4511 The @code{foreign-string-alloc} function allocates a foreign string
4512 containing a Lisp string or @code{(unsigned-byte 8)} array.
4514 This string must be freed with @code{foreign-string-free}.
4516 @subheading Examples
4519 CFFI> (setq str (foreign-string-alloc "Hello, foreign world!"))
4520 @result{} #<FOREIGN-ADDRESS #x00400560>
4521 CFFI> (foreign-funcall "strlen" :pointer str :int)
4525 @subheading See Also
4526 @seealso{foreign-string-free} @*
4527 @seealso{with-foreign-string}
4528 @c @seealso{:string}
4531 @c ===================================================================
4532 @c FOREIGN-STRING-FREE
4534 @node foreign-string-free
4535 @unnumberedsec foreign-string-free
4537 @Function{foreign-string-free pointer}
4539 @subheading Arguments and Values
4543 A pointer to a string allocated by @code{foreign-string-alloc}.
4546 @subheading Description
4547 The @code{foreign-string-free} function frees a foreign string
4548 allocated by @code{foreign-string-alloc}.
4550 @subheading Examples
4552 @subheading See Also
4553 @seealso{foreign-string-alloc}
4556 @c ===================================================================
4557 @c FOREIGN-STRING-TO-LISP
4559 @node foreign-string-to-lisp
4560 @unnumberedsec foreign-string-to-lisp
4562 @Function{foreign-string-to-lisp ptr &optional size null-terminated-p @
4565 @subheading Arguments and Values
4572 The maximum string size. @code{array-total-size-limit}, by default.
4574 @item null-terminated-p
4575 Specifies if the string @var{ptr} points to is null terminated. True,
4579 @subheading Description
4580 The @code{foreign-string-to-lisp} function copies at most @var{size}
4581 characters from @var{ptr} into a Lisp string.
4583 When @var{null-terminated-p} is true (the default), characters are
4584 copied until @var{size} is reached or a @code{NULL} character is
4587 If @var{ptr} is a null pointer, returns nil.
4589 Note that the @code{:string} type will automatically convert between
4590 Lisp strings and foreign strings.
4592 @subheading Examples
4595 CFFI> (foreign-funcall "getenv" :string "HOME" :pointer)
4596 @result{} #<FOREIGN-ADDRESS #xBFFFFFD5>
4597 CFFI> (foreign-string-to-lisp *)
4598 @result{} "/Users/luis"
4601 @subheading See Also
4602 @seealso{lisp-string-to-foreign} @*
4603 @seealso{foreign-string-alloc}
4604 @c @seealso{:string}
4607 @c ===================================================================
4608 @c LISP-STRING-TO-FOREIGN
4610 @node lisp-string-to-foreign
4611 @unnumberedsec lisp-string-to-foreign
4613 @Function{lisp-string-to-foreign string-or-ub8-array ptr size}
4615 @subheading Arguments and Values
4618 @item string-or-ub8-array
4619 A Lisp string or a Lisp @code{(unsigned-byte 8)} array.
4628 @subheading Description
4629 The @code{lisp-string-to-foreign} function copies at most @var{size}-1
4630 characters from a Lisp string or @code{(unsigned-byte 8)} arrayto
4631 @var{ptr}. The foreign string will be null-terminated.
4633 @subheading Examples
4636 CFFI> (with-foreign-pointer-as-string (str 255)
4637 (lisp-string-to-foreign "Hello, foreign world!" str 6))
4640 CFFI> (with-foreign-pointer-as-string (str 255)
4641 (lisp-string-to-foreign
4642 (make-array 6 :element-type '(unsigned-byte 8)
4643 :initial-contents '(65 66 67 68 69 60))
4648 @subheading See Also
4649 @seealso{foreign-string-alloc} @*
4650 @seealso{foreign-string-to-lisp} @*
4651 @seealso{with-foreign-pointer-as-string}
4654 @c ===================================================================
4655 @c WITH-FOREIGN-STRING
4657 @node with-foreign-string
4658 @unnumberedsec with-foreign-string
4660 @Macro{with-foreign-string (var lisp-string-or-ub8-array) &body body}
4662 @subheading Arguments and Values
4668 @item lisp-string-or-ub8-array
4669 A Lisp string or a Lisp array with element type @code{(unsigned-byte 8)}.
4672 A list of forms to be executed.
4675 @subheading Description
4676 The @code{with-foreign-string} macro will bind @var{var} to a newly
4677 allocated foreign string containing @var{lisp-string-or-ub8-array}.
4679 @subheading Examples
4682 CFFI> (with-foreign-string (foo "12345")
4683 (foreign-funcall "strlen" :pointer foo :int))
4686 CFFI> (let ((array (coerce #(84 117 114 97 110 103 97)
4687 '(array (unsigned-byte 8)))))
4688 (with-foreign-string (foreign-string array)
4689 (foreign-string-to-lisp foreign-string)))
4693 @subheading See Also
4694 @seealso{foreign-string-alloc} @*
4695 @seealso{with-foreign-pointer-as-string}
4698 @c ===================================================================
4699 @c WITH-FOREIGN-POINTER-AS-STRING
4701 @node with-foreign-pointer-as-string
4702 @unnumberedsec with-foreign-pointer-as-string
4704 @Macro{with-foreign-pointer-as-string (var size &optional size-var) &body body}
4706 @subheading Arguments and Values
4716 List of forms to be executed.
4719 @subheading Description
4720 The @code{with-foreign-pointer-as-string} macro is similar to
4721 @code{with-foreign-pointer} except that @var{var}, as a Lisp string, is
4722 used as the returned value of an implicit @code{progn} around @var{body}.
4724 @subheading Examples
4727 CFFI> (with-foreign-pointer-as-string (str 6 str-size)
4728 (lisp-string-to-foreign "Hello, foreign world!" str str-size))
4732 @subheading See Also
4733 @seealso{foreign-string-alloc} @*
4734 @seealso{with-foreign-string}
4737 @c ===================================================================
4738 @c CHAPTER: Variables
4751 @c ===================================================================
4755 @unnumberedsec defcvar
4757 @Macro{defcvar name-and-options type documentation @result{} lisp-name}
4759 name-and-options ::= name | (name &key read-only (library :default))
4760 name ::= lisp-name [foreign-name] | foreign-name [lisp-name]
4762 @subheading Arguments and Values
4766 A string denoting a foreign function.
4769 A symbol naming the Lisp function to be created.
4778 A Lisp string; not evaluated.
4781 @subheading Description
4782 The @code{defcvar} macro defines a symbol macro @var{lisp-name} that looks
4783 up @var{foreign-name} and dereferences it acording to @var{type}. It
4784 can also be @code{setf}ed, unless @var{read-only} is true, in which
4785 case an error will be signaled.
4787 When one of @var{lisp-name} or @var{foreign-name} is omitted, the
4788 other is automatically derived using the following rules:
4792 Foreign names are converted to Lisp names by uppercasing, replacing
4793 underscores with hyphens, and wrapping around asterisks.
4795 Lisp names are converted to foreign names by lowercasing, replacing
4796 hyphens with underscores, and removing asterisks, if any.
4799 @subheading Examples
4802 CFFI> (defcvar "errno" :int)
4804 CFFI> (foreign-funcall "strerror" :int *errno* :string)
4805 @result{} "Inappropriate ioctl for device"
4806 CFFI> (setf *errno* 1)
4808 CFFI> (foreign-funcall "strerror" :int *errno* :string)
4809 @result{} "Operation not permitted"
4812 Trying to modify a read-only foreign variable:
4815 CFFI> (defcvar ("errno" +error-number+) :int :read-only t)
4816 @result{} +ERROR-NUMBER+
4817 CFFI> (setf +error-number+ 12)
4818 ;; @lispcmt{@error{} Trying to modify read-only foreign var: +ERROR-NUMBER+.}
4821 @emph{Note that accessing @code{errno} this way won't work with every
4822 C standard library.}
4824 @subheading See Also
4825 @seealso{get-var-pointer}
4828 @c ===================================================================
4831 @node get-var-pointer
4832 @unnumberedsec get-var-pointer
4834 @Function{get-var-pointer symbol @result{} pointer}
4836 @subheading Arguments and Values
4840 A symbol denoting a foreign variable defined with @code{defcvar}.
4846 @subheading Description
4847 The function @code{get-var-pointer} will return a @var{pointer} to the
4848 foreign global variable @var{symbol} previously defined with
4851 @subheading Examples
4854 CFFI> (defcvar "errno" :int :read-only t)
4858 CFFI> (get-var-pointer '*errno*)
4859 @result{} #<A Mac Pointer #xA0008130>
4860 CFFI> (mem-ref * :int)
4864 @subheading See Also
4868 @c ===================================================================
4869 @c CHAPTER: Functions
4875 * Calling Foreign Functions::
4876 * Defining Foreign Functions::
4882 * foreign-funcall-pointer::
4885 @node Calling Foreign Functions
4886 @section Calling Foreign Functions
4888 @node Defining Foreign Functions
4889 @section Defining Foreign Functions
4892 @c ===================================================================
4896 @unnumberedsec defcfun
4898 @Macro{defcfun name-and-options return-type &body arguments [&rest] @
4899 @result{} lisp-name}
4902 @item @var{name-and-options} name | (name &key library calling-convention cconv)
4903 @item @var{name} ::= @var{lisp-name} [@var{foreign-name}] | @var{foreign-name} [@var{lisp-name}]
4904 @item @var{arguments} ::= @{ (arg-name arg-type) @}*
4907 @subheading Arguments and Values
4911 A string denoting a foreign function.
4914 A symbol naming the Lisp function to be created.
4923 @item calling-convention
4925 One of @code{:cdecl} (default) or @code{stdcall}.
4928 A symbol designating a foreign library.
4931 @subheading Description
4932 The @code{defcfun} macro provides a declarative interface for defining
4933 Lisp functions that call foreign functions.
4935 When one of @var{lisp-name} or @var{foreign-name} is omitted, the
4936 other is automatically derived using the following rules:
4940 Foreign names are converted to Lisp names by uppercasing and replacing
4941 underscores with hyphens.
4943 Lisp names are converted to foreign names by lowercasing and replacing
4944 hyphens with underscores.
4947 If you place the symbol @code{&rest} in the end of the argument list
4948 after the fixed arguments, @code{defcfun} will treat the foreign
4949 function as a @strong{variadic function}. The variadic arguments
4950 should be passed in a way similar to what @code{foreign-funcall} would
4951 expect. Unlike @code{foreign-funcall} though, @code{defcfun} will take
4952 care of doing argument promotion. Note that in this case
4953 @code{defcfun} will generate a Lisp @emph{macro} instead of a
4954 function and will only work for Lisps that support
4955 @code{foreign-funcall.}
4958 @subheading Examples
4961 (defcfun "strlen" :int (n :string))
4963 CFFI> (strlen "123")
4968 (defcfun ("abs" c-abs) :int (n :int))
4974 Variadic function example:
4977 (defcfun "sprintf" :int
4982 CFFI> (with-foreign-pointer-as-string (s 100)
4983 (sprintf s "%c %d %.2f %s" :char 90 :short 42 :float pi
4984 :string "super-locrian"))
4985 @result{} "A 42 3.14 super-locrian"
4988 @subheading See Also
4989 @seealso{foreign-funcall} @*
4990 @seealso{foreign-funcall-pointer}
4993 @c ===================================================================
4996 @node foreign-funcall
4997 @unnumberedsec foreign-funcall
4999 @Macro{foreign-funcall name-and-options &rest arguments @result{} return-value}
5001 arguments ::= @{ arg-type arg @}* [return-type]
5002 name-and-options ::= name | ( name &key library calling-convention cconv)
5004 @subheading Arguments and Values
5014 An argument of type @var{arg-type}.
5017 A foreign type, @code{:void} by default.
5023 A lisp symbol; not evaluated.
5025 @item calling-convention
5027 One of @code{:cdecl} (default) or @code{:stdcall}.
5030 @subheading Description
5031 The @code{foreign-funcall} macro is the main primitive for calling
5034 @emph{Note: The return value of foreign-funcall on functions with a
5035 :void return type is still undefined.}
5037 @subheading Implementation-specific Notes
5040 Corman Lisp does not support @code{foreign-funcall}. On
5041 implementations that @strong{don't} support @code{foreign-funcall}
5042 @code{cffi-features:no-foreign-funcall} will be present in
5043 @code{*features*}. Note: in these Lisps you can still use the
5044 @code{defcfun} interface.
5047 @subheading Examples
5050 CFFI> (foreign-funcall "strlen" :string "foo" :int)
5057 void print_number(int n)
5059 printf("N: %d\n", n);
5064 CFFI> (foreign-funcall "print_number" :int 123456)
5073 CFFI> (foreign-funcall "print_number" :int 123456 :void)
5079 CFFI> (foreign-funcall "printf" :string (format nil "%s: %d.~%")
5080 :string "So long and thanks for all the fish"
5082 @print{} So long and thanks for all the fish: 42.
5086 @subheading See Also
5087 @seealso{defcfun} @*
5088 @seealso{foreign-funcall-pointer}
5091 @c ===================================================================
5092 @c FOREIGN-FUNCALL-POINTER
5094 @node foreign-funcall-pointer
5095 @unnumberedsec foreign-funcall-pointer
5097 @Macro{foreign-funcall pointer options &rest arguments @result{} return-value}
5099 arguments ::= @{ arg-type arg @}* [return-type]
5100 options ::= ( &key calling-convention cconv )
5102 @subheading Arguments and Values
5112 An argument of type @var{arg-type}.
5115 A foreign type, @code{:void} by default.
5120 @item calling-convention
5122 One of @code{:cdecl} (default) or @code{:stdcall}.
5125 @subheading Description
5126 The @code{foreign-funcall} macro is the main primitive for calling
5129 @emph{Note: The return value of foreign-funcall on functions with a
5130 :void return type is still undefined.}
5132 @subheading Implementation-specific Notes
5135 Corman Lisp does not support @code{foreign-funcall}. On
5136 implementations that @strong{don't} support @code{foreign-funcall}
5137 @code{cffi-features:no-foreign-funcall} will be present in
5138 @code{*features*}. Note: in these Lisps you can still use the
5139 @code{defcfun} interface.
5142 @subheading Examples
5145 CFFI> (foreign-funcall-pointer (foreign-symbol-pointer "abs")
5150 @subheading See Also
5151 @seealso{defcfun} @*
5152 @seealso{foreign-funcall}
5155 @c ===================================================================
5156 @c CHAPTER: Libraries
5162 * Defining a library::
5163 * Library definition style::
5167 * close-foreign-library:: Close a foreign library.
5168 * *darwin-framework-directories*:: Search path for Darwin frameworks.
5169 * define-foreign-library:: Explain how to load a foreign library.
5170 * *foreign-library-directories*:: Search path for shared libraries.
5171 * load-foreign-library:: Load a foreign library.
5172 * load-foreign-library-error:: Signalled on failure of its namesake.
5173 * use-foreign-library:: Load a foreign library when needed.
5177 @node Defining a library
5178 @section Defining a library
5180 Almost all foreign code you might want to access exists in some kind
5181 of shared library. The meaning of @dfn{shared library} varies among
5182 platforms, but for our purposes, we will consider it to include
5183 @file{.so} files on @sc{unix}, frameworks on Darwin (and derivatives
5184 like Mac @acronym{OS X}), and @file{.dll} files on Windows.
5186 Bringing one of these libraries into the Lisp image is normally a
5191 Describe to @cffi{} how to load the library at some future point,
5192 depending on platform and other factors, with a
5193 @code{define-foreign-library} top-level form.
5196 Load the library so defined with either a top-level
5197 @code{use-foreign-library} form or by calling the function
5198 @code{load-foreign-library}.
5201 @xref{Tutorial-Loading,, Loading foreign libraries}, for a working
5202 example of the above two steps.
5205 @node Library definition style
5206 @section Library definition style
5208 Looking at the @code{libcurl} library definition presented earlier,
5209 you may ask why we did not simply do this:
5212 (define-foreign-library libcurl
5213 (t (:default "libcurl")))
5217 Indeed, this would work just as well on the computer on which I tested
5218 the tutorial. There are a couple of good reasons to provide the
5219 @file{.so}'s current version number, however. Namely, the versionless
5220 @file{.so} is not packaged on most @sc{unix} systems along with the
5221 actual, fully-versioned library; instead, it is included in the
5222 ``development'' package along with C headers and static @file{.a}
5225 The reason @cffi{} does not try to account for this lies in the
5226 meaning of the version numbers. A full treatment of shared library
5227 versions is beyond this manual's scope; see @ref{Versioning,, Library
5228 interface versions, libtool, @acronym{GNU} Libtool}, for helpful
5229 information for the unfamiliar. For our purposes, consider that a
5230 mismatch between the library version with which you tested and the
5231 installed library version may cause undefined
5232 behavior.@footnote{Windows programmers may chafe at adding a
5233 @sc{unix}-specific clause to @code{define-foreign-library}. Instead,
5234 ask why the Windows solution to library incompatibility is ``include
5235 your own version of every library you use with every program''.}
5237 @impnote{Maybe some notes should go here about OS X, which I know
5238 little about. --stephen}
5241 @c ===================================================================
5242 @c CLOSE-FOREIGN-LIBRARY
5244 @node close-foreign-library
5245 @unnumberedsec close-foreign-library
5247 @Function{close-foreign-library library @result{} success}
5249 @subheading Arguments and Values
5253 A symbol or an instance of @code{foreign-library}.
5259 @subheading Description
5261 Closes @var{library} which can be a symbol designating a library
5262 define through @code{define-foreign-library} or an instance of
5263 @code{foreign-library} as returned by @code{load-foreign-library}.
5265 @c @subheading Examples
5266 @c @xref{Tutorial-Loading,, Loading foreign libraries}.
5268 @subheading See Also
5270 @seealso{define-foreign-library} @*
5271 @seealso{load-foreign-library} @*
5272 @seealso{use-foreign-library}
5275 @c ===================================================================
5276 @c *DARWIN-FRAMEWORK-DIRECTORIES*
5278 @node *darwin-framework-directories*
5279 @unnumberedsec *darwin-framework-directories*
5282 @Variable{*darwin-framework-directories*}
5284 @subheading Value type
5286 A list, in which each element is a string, a pathname, or a simple
5289 @subheading Initial value
5291 A list containing the following, in order: an expression corresponding
5292 to Darwin path @file{~/Library/Frameworks/},
5293 @code{#P"/Library/Frameworks/"}, and
5294 @code{#P"/System/Library/Frameworks/"}.
5296 @subheading Description
5298 The meaning of ``simple Lisp expression'' is explained in
5299 @ref{*foreign-library-directories*}. In contrast to that variable,
5300 this is not a fallback search path; the default value described above
5301 is intended to be a reasonably complete search path on Darwin systems.
5303 @subheading Examples
5306 CFFI> (load-foreign-library '(:framework "OpenGL"))
5307 @result{} #P"/System/Library/Frameworks/OpenGL.framework/OpenGL"
5310 @subheading See also
5312 @seealso{*foreign-library-directories*} @*
5313 @seealso{define-foreign-library}
5316 @c ===================================================================
5317 @c DEFINE-FOREIGN-LIBRARY
5319 @node define-foreign-library
5320 @unnumberedsec define-foreign-library
5324 @Macro{define-foreign-library name-and-options @{ load-clause @}* @result{} name}
5326 name-and-options ::= name | (name &key calling-convention cconv)
5327 load-clause ::= (feature library &key calling-convention cconv)
5329 @subheading Arguments and Values
5336 A feature expression.
5339 A library designator.
5341 @item calling-convention
5343 One of @code{:cdecl} (default) or @code{:stdcall}
5346 @subheading Description
5348 Creates a new library designator called @var{name}. The
5349 @var{load-clause}s describe how to load that designator when passed to
5350 @code{load-foreign-library} or @code{use-foreign-library}.
5352 When trying to load the library @var{name}, the relevant function
5353 searches the @var{load-clause}s in order for the first one where
5354 @var{feature} evaluates to true. That happens for any of the
5355 following situations:@footnote{This is described in
5356 @code{cffi-feature-p} in @file{libraries.lisp}.}
5360 If @var{feature} is a symbol (idiomatically a keyword), a symbol with
5361 the same name, but interned into the @code{cffi-features} package, is
5362 present in @code{common-lisp:*features*}.
5365 If @var{feature} is a list, depending on @code{(first @var{feature})},
5370 All of the feature expressions in @code{(rest @var{feature})} are
5374 At least one of the feature expressions in @code{(rest @var{feature})}
5378 The feature expression @code{(second @var{feature})} is not true.
5382 Finally, if @var{feature} is @code{t}, this @var{load-clause} is
5383 picked unconditionally.
5386 Upon finding the first true @var{feature}, the library loader then
5387 loads the @var{library}. The meaning of ``library designator'' is
5388 described in @ref{load-foreign-library}.
5390 Functions associated to a library defined by
5391 @code{define-foreign-library} (e.g. through @code{defcfun}'s
5392 @code{:library} option, will inherit the library's options. The
5393 precedence is as follows:
5397 @code{defcfun}/@code{foreign-funcall} specific options;
5400 @var{load-clause} options;
5403 global library options (the @var{name-and-options} argument)
5407 @subheading Examples
5409 @xref{Tutorial-Loading,, Loading foreign libraries}.
5412 @subheading See Also
5414 @seealso{close-foreign-library} @*
5415 @seealso{load-foreign-library}
5418 @c ===================================================================
5419 @c *FOREIGN-LIBRARY-DIRECTORIES*
5421 @node *foreign-library-directories*
5422 @unnumberedsec *foreign-library-directories*
5425 @Variable{*foreign-library-directories*}
5427 @subheading Value type
5429 A list, in which each element is a string, a pathname, or a simple
5432 @subheading Initial value
5436 @subheading Description
5438 You should not have to use this variable.
5440 Most, if not all, Lisps supported by @cffi{} have a reasonable default
5441 search algorithm for foreign libraries. For example, Lisps for
5442 @sc{unix} usually call
5443 @uref{http://www.opengroup.org/onlinepubs/009695399/functions/dlopen.html,,
5444 @code{dlopen(3)}}, which in turn looks in the system library
5445 directories. Only if that fails does @cffi{} look for the named
5446 library file in these directories, and load it from there if found.
5448 Thus, this is intended to be a @cffi{}-only fallback to the library
5449 search configuration provided by your operating system. For example,
5450 if you distribute a foreign library with your Lisp package, you can
5451 add the library's containing directory to this list and portably
5452 expect @cffi{} to find it.
5454 A @dfn{simple Lisp expression} is intended to provide functionality
5455 commonly used in search paths such as
5456 @acronym{ASDF}'s@footnote{@xref{Using asdf to load systems,,, asdf,
5457 asdf: another system definition facility}, for information on
5458 @code{asdf:*central-registry*}.}, and is defined recursively as
5459 follows:@footnote{See @code{mini-eval} in @file{libraries.lisp} for
5460 the source of this definition. As is always the case with a Lisp
5461 @code{eval}, it's easier to understand the Lisp definition than the
5466 A list, whose @samp{first} is a function designator, and whose
5467 @samp{rest} is a list of simple Lisp expressions to be evaluated and
5468 passed to the so-designated function. The result is the result of the
5472 A symbol, whose result is its symbol value.
5475 Anything else evaluates to itself.
5479 @subheading Examples
5483 @print{} liblibli.so libli.lisp
5487 In @file{libli.lisp}:
5490 (pushnew #P"/home/sirian/lisp/libli/" *foreign-library-directories*
5493 (load-foreign-library '(:default "liblibli"))
5497 The following example would achieve the same effect:
5500 (pushnew '(merge-pathnames #p"lisp/libli/" (user-homedir-pathname))
5501 *foreign-library-directories*
5503 @result{} ((MERGE-PATHNAMES #P"lisp/libli/" (USER-HOMEDIR-PATHNAME)))
5505 (load-foreign-library '(:default "liblibli"))
5508 @subheading See also
5510 @seealso{*darwin-framework-directories*} @*
5511 @seealso{define-foreign-library}
5514 @c ===================================================================
5515 @c LOAD-FOREIGN-LIBRARY
5517 @node load-foreign-library
5518 @unnumberedsec load-foreign-library
5520 @Function{load-foreign-library library @result{} handler}
5522 @subheading Arguments and Values
5526 A library designator.
5529 An instance of @code{foreign-library}.
5532 @subheading Description
5534 Load the library indicated by @var{library}. A @dfn{library
5535 designator} is defined as follows:
5539 If a symbol, is considered a name previously defined with
5540 @code{define-foreign-library}.
5543 If a string or pathname, passed as a namestring directly to the
5544 implementation's foreign library loader. If that fails, search the
5545 directories in @code{*foreign-library-directories*} with
5546 @code{cl:probe-file}; if found, the absolute path is passed to the
5547 implementation's loader.
5550 If a list, the meaning depends on @code{(first @var{library})}:
5554 The second list element is taken to be a Darwin framework name, which
5555 is then searched in @code{*darwin-framework-directories*}, and loaded
5559 Each remaining list element, itself a library designator, is loaded in
5560 order, until one succeeds.
5563 The name is transformed according to the platform's naming convention
5564 to shared libraries, and the resultant string is loaded as a library
5565 designator. For example, on @sc{unix}, the name is suffixed with
5570 If the load fails, signal a @code{load-foreign-library-error}.
5572 @strong{Please note:} For system libraries, you should not need to
5573 specify the directory containing the library. Each operating system
5574 has its own idea of a default search path, and you should rely on it
5575 when it is reasonable.
5577 @subheading Implementation-specific Notes
5578 On ECL platforms where its dynamic FFI is not supported (ie. when
5579 @code{:dffi} is not present in @code{*features*}),
5580 @code{cffi:load-foreign-library} does not work and you must use ECL's
5581 own @code{ffi:load-foreign-library} with a constant string argument.
5583 @subheading Examples
5585 @xref{Tutorial-Loading,, Loading foreign libraries}.
5587 @subheading See Also
5589 @seealso{close-foreign-library} @*
5590 @seealso{*darwin-framework-directories*} @*
5591 @seealso{define-foreign-library} @*
5592 @seealso{*foreign-library-directories*} @*
5593 @seealso{load-foreign-library-error} @*
5594 @seealso{use-foreign-library}
5597 @c ===================================================================
5598 @c LOAD-FOREIGN-LIBRARY-ERROR
5600 @node load-foreign-library-error
5601 @unnumberedsec load-foreign-library-error
5605 @Condition{load-foreign-library-error}
5607 @subheading Class precedence list
5609 @code{load-foreign-library-error}, @code{error},
5610 @code{serious-condition}, @code{condition}, @code{t}
5612 @subheading Description
5614 Signalled when a foreign library load completely fails. The exact
5615 meaning of this varies depending on the real conditions at work, but
5616 almost universally, the implementation's error message is useless.
5617 However, @cffi{} does provide the useful restarts @code{retry} and
5618 @code{use-value}; invoke the @code{retry} restart to try loading the
5619 foreign library again, or the @code{use-value} restart to try loading
5620 a different foreign library designator.
5622 @subheading See also
5624 @seealso{load-foreign-library}
5627 @c ===================================================================
5628 @c USE-FOREIGN-LIBRARY
5630 @node use-foreign-library
5631 @unnumberedsec use-foreign-library
5635 @Macro{use-foreign-library name}
5637 @subheading Arguments and values
5641 A library designator; unevaluated.
5645 @subheading Description
5647 @xref{load-foreign-library}, for the meaning of ``library
5648 designator''. This is intended to be the top-level form used
5649 idiomatically after a @code{define-foreign-library} form to go ahead
5650 and load the library. @c ; it also sets the ``current foreign library''.
5651 Finally, on implementations where the regular evaluation rule is
5652 insufficient for foreign library loading, it loads it at the required
5653 time.@footnote{Namely, @acronym{CMUCL}. See
5654 @code{use-foreign-library} in @file{libraries.lisp} for details.}
5656 @c current foreign library is a concept created a few hours ago as of
5657 @c this writing. It is not actually used yet, but probably will be.
5659 @subheading Examples
5661 @xref{Tutorial-Loading,, Loading foreign libraries}.
5664 @subheading See also
5666 @seealso{load-foreign-library}
5669 @c ===================================================================
5670 @c CHAPTER: Callbacks
5684 @c ===================================================================
5688 @unnumberedsec callback
5690 @Macro{callback symbol @result{} pointer}
5692 @subheading Arguments and Values
5696 A symbol denoting a callback.
5703 @subheading Description
5704 The @code{callback} macro is analogous to the standard CL special
5705 operator @code{function} and will return a pointer to the callback
5706 denoted by the symbol @var{name}.
5708 @subheading Examples
5711 CFFI> (defcallback sum :int ((a :int) (b :int))
5714 CFFI> (callback sum)
5715 @result{} #<A Mac Pointer #x102350>
5718 @subheading See Also
5719 @seealso{get-callback} @*
5720 @seealso{defcallback}
5723 @c ===================================================================
5727 @unnumberedsec defcallback
5729 @Macro{defcallback name-and-options return-type arguments &body body @result{} name}
5731 name-and-options ::= name | (name &key calling-convention cconv)
5732 arguments ::= (@{ (arg-name arg-type) @}*)
5734 @subheading Arguments and Values
5738 A symbol naming the callback created.
5741 The foreign type for the callback's return value.
5749 @item calling-convention
5751 One of @code{:cdecl} (default) or @code{:stdcall}.
5754 @subheading Description
5755 The macro @code{defcallback} defines a Lisp function the can be called
5756 from C (but not from Lisp). The arguments passed to this function will
5757 be converted to the appropriate Lisp representation and its return
5758 value will be converted to its C representation.
5760 This Lisp function can be accessed by the @code{callback} macro or the
5761 @code{get-callback} function.
5763 @strong{Portability note:} @code{defcallback} will not work correctly
5764 on some Lisps if it's not a top-level form.
5766 @subheading Examples
5769 (defcfun "qsort" :void
5773 (fun-compar :pointer))
5775 (defcallback < :int ((a :pointer) (b :pointer))
5776 (let ((x (mem-ref a :int))
5777 (y (mem-ref b :int)))
5782 CFFI> (with-foreign-object (array :int 10)
5783 ;; @lispcmt{Initialize array.}
5784 (loop for i from 0 and n in '(7 2 10 4 3 5 1 6 9 8)
5785 do (setf (mem-aref array :int i) n))
5786 ;; @lispcmt{Sort it.}
5787 (qsort array 10 (foreign-type-size :int) (callback <))
5788 ;; @lispcmt{Return it as a list.}
5789 (loop for i from 0 below 10
5790 collect (mem-aref array :int i)))
5791 @result{} (1 2 3 4 5 6 7 8 9 10)
5794 @subheading See Also
5795 @seealso{callback} @*
5796 @seealso{get-callback}
5799 @c ===================================================================
5803 @unnumberedsec get-callback
5805 @Accessor{get-callback symbol @result{} pointer}
5807 @subheading Arguments and Values
5811 A symbol denoting a callback.
5817 @subheading Description
5818 This is the functional version of the @code{callback} macro. It
5819 returns a pointer to the callback named by @var{symbol} suitable, for
5820 example, to pass as arguments to foreign functions.
5822 @subheading Examples
5825 CFFI> (defcallback sum :int ((a :int) (b :int))
5828 CFFI> (get-callback 'sum)
5829 @result{} #<A Mac Pointer #x102350>
5832 @subheading See Also
5833 @seealso{callback} @*
5834 @seealso{defcallback}
5836 @c ===================================================================
5837 @c CHAPTER: Limitations
5840 @chapter Limitations
5842 These are @cffi{}'s limitations across all platforms; for information
5843 on the warts on particular Lisp implementations, see
5844 @ref{Implementation Support}.
5848 The tutorial includes a treatment of the primary, intractable
5849 limitation of @cffi{}, or any @acronym{FFI}: that the abstractions
5850 commonly used by C are insufficiently expressive.
5851 @xref{Tutorial-Abstraction,, Breaking the abstraction}, for more
5855 C @code{struct}s cannot be passed by value.
5861 @node Platform-specific features
5862 @appendix Platform-specific features
5864 @cffi{} does some platform tests on loading. The details vary between
5865 Lisps; in fact, the purpose is to unify the list of available platform
5866 features for use elsewhere in the @cffi{} code. These features are
5867 also part of the public interface; see @ref{define-foreign-library}.
5869 The exact meanings of the features follow. Though you will usually
5870 refer to these symbols as keywords, @cffi{} internally views them in
5871 the package @code{cffi-features}.
5874 @item flat-namespace
5875 This Lisp has a flat namespace for foreign symbols meaning that you
5876 won't be able to load two different libraries with homograph functions
5877 and successfully differentiate them through the @code{:library}
5878 option to @code{defcfun}, @code{defcvar}, etc@dots{}
5881 This operating system is Darwin or a derivative thereof, such as
5884 @item no-foreign-funcall
5885 The macro @code{foreign-funcall} is @strong{not} available. On such
5886 platforms, the only way to call a foreign function is through
5887 @code{defcfun}. @xref{foreign-funcall}, and @ref{defcfun}.
5890 The C @code{long long} type is @strong{not} available as a foreign
5894 This Lisp doesn't support the @code{stdcall} calling convention. Note
5895 that it only makes sense to support @code{stdcall} on (32-bit) x86
5899 The underlying @acronym{CPU} architecture is 32-bit PowerPC.
5902 This operating system is a @sc{unix}-like, such as
5903 @acronym{GNU}/Linux, Darwin, or even Cygwin on Lisps that show the
5904 @sc{unix}-like interface provided by Cygwin to Lisp code.
5907 This operating system is Windows.
5910 The underlying @acronym{CPU} architecture is x86, such as on
5911 processors from Intel or @acronym{AMD}.
5919 @item aggregate type
5920 A @cffi{} type for C data defined as an organization of data of simple
5921 type; in structures and unions, which are themselves aggregate types,
5922 they are represented by value.
5925 This has two meanings; in any context, only one makes sense.
5927 When using type translators, the foreign value is the lower-level Lisp
5928 value derived from the object passed to @code{translate-to-foreign}
5929 (@pxref{translate-to-foreign}). This value should be a Lisp number or
5930 a pointer (satisfies @code{pointerp}), and it can be treated like any
5931 general Lisp object; it only completes the transformation to a true
5932 foreign value when passed through low-level code in the Lisp
5933 implementation, such as the foreign function caller or indirect memory
5934 addressing combined with a data move.
5936 In other contexts, this refers to a value accessible by C, but which
5937 may only be accessed through @cffi{} functions. The closest you can
5938 get to such a foreign value is through a pointer Lisp object, which
5939 itself counts as a foreign value in only the previous sense.
5942 A @cffi{} type that is ultimately represented as a builtin type;
5943 @cffi{} only provides extra semantics for Lisp that are invisible to C
5947 @node Comprehensive Index