1 \input texinfo @c -*- Mode: Texinfo; Mode: auto-fill -*-
4 @settitle CFFI User Manual
7 @c @documentencoding utf-8
11 @c * The reference section names and "See Also" list are roman, not
12 @c @code. This is to follow the format of CLHS.
14 @c * How it looks in HTML is the priority.
16 @c ============================= Macros =============================
17 @c The following macros are used throughout this manual.
19 @macro Function {args}
29 @macro Accessor {args}
30 @deffn {Accessor} \args\
34 @macro GenericFunction {args}
35 @deffn {Generic Function} \args\
39 @macro ForeignType {args}
40 @deftp {Foreign Type} \args\
44 @macro Variable {args}
45 @defvr {Special Variable} \args\
49 @macro Condition {args}
50 @deftp {Condition Type} \args\
60 @strong{Implementor's note:} @emph{\text\}
64 @c Info "requires" that x-refs end in a period or comma, or ) in the
65 @c case of @pxref. So the following implements that requirement for
66 @c the "See also" subheadings that permeate this manual, but only in
78 @c Set ROMANCOMMENTS to get comments in roman font.
82 @ifclear ROMANCOMMENTS
86 @c My copy of makeinfo is not generating any HTML for @result{} for
87 @c some odd reason. (It certainly used to...)
94 @c Similar macro to @result. Its purpose is to work around the fact
95 @c that ⇒ does not work properly inside @lisp.
108 @c ============================= Macros =============================
111 @c Show types, functions, and concepts in the same index.
116 Copyright @copyright{} 2005 James Bielman <jamesjb at jamesjb.com> @*
117 Copyright @copyright{} 2005-2007 Lu@'{@dotless{i}}s Oliveira
118 <loliveira at common-lisp.net> @*
119 Copyright @copyright{} 2006 Stephen Compall <s11 at member.fsf.org>
122 Permission is hereby granted, free of charge, to any person obtaining
123 a copy of this software and associated documentation files (the
124 ``Software''), to deal in the Software without restriction, including
125 without limitation the rights to use, copy, modify, merge, publish,
126 distribute, sublicense, and/or sell copies of the Software, and to
127 permit persons to whom the Software is furnished to do so, subject to
128 the following conditions:
130 The above copyright notice and this permission notice shall be
131 included in all copies or substantial portions of the Software.
133 @sc{The software is provided ``as is'', without warranty of any kind,
134 express or implied, including but not limited to the warranties of
135 merchantability, fitness for a particular purpose and noninfringement.
136 In no event shall the authors or copyright holders be liable for any
137 claim, damages or other liability, whether in an action of contract,
138 tort or otherwise, arising from, out of or in connection with the
139 software or the use or other dealings in the software.}
145 @title CFFI User Manual
146 @c @subtitle Version X.X
147 @c @author James Bielman
150 @vskip 0pt plus 1filll
163 * Introduction:: What is CFFI?
164 * Implementation Support::
165 * Tutorial:: Interactive intro to using CFFI.
166 * Wrapper generators:: CFFI forms from munging C source code.
176 * Platform-specific features:: Details about the underlying system.
177 * Glossary:: List of CFFI-specific terms and meanings.
178 * Comprehensive Index::
185 * convert-from-foreign:: Outside interface to backward type translator.
186 * convert-to-foreign:: Outside interface to forward type translator.
187 * defbitfield:: Defines a bitfield.
188 * defcstruct:: Defines a C structure type.
189 * defcunion:: Defines a C union type.
190 * defctype:: Defines a foreign typedef.
191 * defcenum:: Defines a C enumeration.
192 * define-foreign-type:: Defines a foreign type specifier.
193 * define-parse-method:: Specifies how a type should be parsed.
194 @c * explain-foreign-slot-value:: <unimplemented>
195 * foreign-bitfield-symbols:: Returns a list of symbols for a bitfield type.
196 * foreign-bitfield-value:: Calculates a value for a bitfield type.
197 * foreign-enum-keyword:: Finds a keyword in an enum type.
198 * foreign-enum-value:: Finds a value in an enum type.
199 * foreign-slot-names:: Returns a list of slot names in a foreign struct.
200 * foreign-slot-offset:: Returns the offset of a slot in a foreign struct.
201 * foreign-slot-pointer:: Returns a pointer to a slot in a foreign struct.
202 * foreign-slot-value:: Returns the value of a slot in a foreign struct.
203 * foreign-type-alignment:: Returns the alignment of a foreign type.
204 * foreign-type-size:: Returns the size of a foreign type.
205 * free-converted-object:: Outside interface to typed object deallocators.
206 * free-translated-object:: Defines how to free a oreign object.
207 * translate-from-foreign:: Defines a foreign-to-Lisp object translation.
208 * translate-to-foreign:: Defines a Lisp-to-foreign object translation.
209 * with-foreign-object:: Allocates a foreign object with dynamic extent.
210 @c * with-foreign-objects:: Plural form of @code{with-foreign-object}.
211 * with-foreign-slots:: Accesses the slots of a foreign structure.
215 * foreign-free:: Deallocates memory.
216 * foreign-alloc:: Allocates memory.
217 * foreign-symbol-pointer:: Returns a pointer to a foreign symbol.
218 * inc-pointer:: Increments the address held by a pointer.
219 * incf-pointer:: Increments the pointer address in a place.
220 * make-pointer:: Returns a pointer to a given address.
221 * mem-aref:: Accesses the value of an index in an array.
222 * mem-ref:: Dereferences a pointer.
223 * null-pointer:: Returns a NULL pointer.
224 * null-pointer-p:: Tests a pointer for NULL value.
225 * pointerp:: Tests whether an object is a pointer or not.
226 * pointer-address:: Returns the address pointed to by a pointer.
227 * pointer-eq:: Tests if two pointers point to the same address.
228 * with-foreign-pointer:: Allocates memory with dynamic extent.
232 * *default-foreign-encoding*:: Default encoding for the string types.
233 * foreign-string-alloc:: Converts a Lisp string to a foreign string.
234 * foreign-string-free:: Deallocates memory used by a foreign string.
235 * foreign-string-to-lisp:: Converts a foreign string to a Lisp string.
236 * lisp-string-to-foreign:: Copies a Lisp string into a foreign string.
237 * with-foreign-string:: Allocates a foreign string with dynamic extent.
238 @c * with-foreign-strings:: Plural form of @code{with-foreign-string}.
239 * with-foreign-pointer-as-string:: Similar to CL's with-output-to-string.
243 * defcvar:: Defines a C global variable.
244 * get-var-pointer:: Returns a pointer to a defined global variable.
248 * defcfun:: Defines a foreign function.
249 * foreign-funcall:: Performs a call to a foreign function.
250 * foreign-funcall-pointer:: Performs a call through a foreign pointer.
254 * close-foreign-library:: Closes a foreign library.
255 * *darwin-framework-directories*:: Search path for Darwin frameworks.
256 * define-foreign-library:: Explain how to load a foreign library.
257 * *foreign-library-directories*:: Search path for shared libraries.
258 * load-foreign-library:: Load a foreign library.
259 * load-foreign-library-error:: Signalled on failure of its namesake.
260 * use-foreign-library:: Load a foreign library when needed.
264 * callback:: Returns a pointer to a defined callback.
265 * defcallback:: Defines a Lisp callback.
266 * get-callback:: Returns a pointer to a defined callback.
274 @c ===================================================================
275 @c CHAPTER: Introduction
278 @chapter Introduction
280 @cffi{} is the Common Foreign Function Interface for @acronym{ANSI}
281 Common Lisp systems. By @dfn{foreign function} we mean a function
282 written in another programming language and having different data and
283 calling conventions than Common Lisp, namely, C. @cffi{} allows you
284 to call foreign functions and access foreign variables, all without
285 leaving the Lisp image.
287 We consider this manual ever a work in progress. If you have
288 difficulty with anything @cffi{}-specific presented in the manual,
289 please contact @email{cffi-devel@@common-lisp.net,the developers} with
295 @xref{Tutorial-Comparison,, What makes Lisp different}, for
296 an argument in favor of @acronym{FFI} in general.
298 @cffi{}'s primary role in any image is to mediate between Lisp
299 developers and the widely varying @acronym{FFI}s present in the
300 various Lisp implementations it supports. With @cffi{}, you can
301 define foreign function interfaces while still maintaining portability
302 between implementations. It is not the first Common Lisp package with
303 this objective; however, it is meant to be a more malleable framework
304 than similar packages.
307 @heading Design Philosophy
311 Pointers do not carry around type information. Instead, type
312 information is supplied when pointers are dereferenced.
315 A type safe pointer interface can be developed on top of an
316 untyped one. It is difficult to do the opposite.
319 Functions are better than macros. When a macro could be used
320 for performance, use a compiler-macro instead.
324 @c ===================================================================
325 @c CHAPTER: Implementation Support
327 @node Implementation Support
328 @chapter Implementation Support
330 @cffi{} supports various free and commercial Lisp implementations:
331 Allegro CL, Corman CL, @sc{clisp}, @acronym{CMUCL}, @acronym{ECL},
332 LispWorks, Clozure CL, @acronym{SBCL} and the Scieneer CL.
334 In general, you should work with the latest versions of each
335 implementation since those will usually be tested against recent
336 versions of CFFI more often and might include necessary features or
337 bug fixes. Reasonable patches for compatibility with earlier versions
338 are welcome nevertheless.
342 Some features are not supported in all implementations.
343 @c TODO: describe these features here.
344 @c flat-namespace too
346 @subheading Allegro CL
350 Does not support the @code{:long-long} type natively.
352 Unicode support is limited to the Basic Multilingual Plane (16-bit
360 No Unicode support. (8-bit code points)
363 @subheading Corman CL
367 Does not support @code{foreign-funcall}.
370 @subheading @acronym{ECL}
374 On platforms where ECL's dynamic FFI is not supported (ie. when
375 @code{:dffi} is not present in @code{*features*}),
376 @code{cffi:load-foreign-library} does not work and you must use ECL's
377 own @code{ffi:load-foreign-library} with a constant string argument.
379 Does not support the @code{:long-long} type natively.
381 Unicode support is not enabled by default.
384 @subheading Lispworks
388 Does not support the @code{:long-long} type natively, except in 64-bit
391 Unicode support is limited to the Basic Multilingual Plane (16-bit
395 @subheading @acronym{SBCL}
399 Not all platforms support callbacks.
404 @c ===================================================================
405 @c CHAPTER: An Introduction to Foreign Interfaces and CFFI
407 @c This macro is merely a marker that I don't think I'll use after
409 @macro tutorialsource {text}
413 @c because I don't want to type this over and over
415 http://www.cliki.net/CFFI
417 @c TeX puts spurious newlines in when you use the above macro
418 @c in @examples &c. So it is expanded below in some places.
422 @chapter An Introduction to Foreign Interfaces and @acronym{CFFI}
424 @c Above, I don't use the cffi macro because it breaks TeX.
426 @cindex tutorial, @cffi{}
427 Users of many popular languages bearing semantic similarity to Lisp,
428 such as Perl and Python, are accustomed to having access to popular C
429 libraries, such as @acronym{GTK}, by way of ``bindings''. In Lisp, we
430 do something similar, but take a fundamentally different approach.
431 This tutorial first explains this difference, then explains how you
432 can use @cffi{}, a powerful system for calling out to C and C++ and
433 access C data from many Common Lisp implementations.
435 @cindex foreign functions and data
436 The concept can be generalized to other languages; at the time of
437 writing, only @cffi{}'s C support is fairly complete, but C++
438 support is being worked on. Therefore, we will interchangeably refer
439 to @dfn{foreign functions} and @dfn{foreign data}, and ``C functions''
440 and ``C data''. At no time will the word ``foreign'' carry its usual,
441 non-programming meaning.
443 This tutorial expects you to have a working understanding of both
444 Common Lisp and C, including the Common Lisp macro system.
447 * Tutorial-Comparison:: Why FFI?
448 * Tutorial-Getting a URL:: An FFI use case.
449 * Tutorial-Loading:: Load libcurl.so.
450 * Tutorial-Initializing:: Call a function in libcurl.so.
451 * Tutorial-easy_setopt:: An advanced libcurl function.
452 * Tutorial-Abstraction:: Why breaking it is necessary.
453 * Tutorial-Lisp easy_setopt:: Semi-Lispy option interface.
454 * Tutorial-Memory:: In C, you collect the garbage.
455 * Tutorial-Callbacks:: Make useful C function pointers.
456 * Tutorial-Completion:: Minimal get-url functionality.
457 * Tutorial-Types:: Defining new foreign types.
458 * Tutorial-Conclusion:: What's next?
462 @node Tutorial-Comparison
463 @section What makes Lisp different
465 The following sums up how bindings to foreign libraries are usually
466 implemented in other languages, then in Common Lisp:
469 @item Perl, Python, Java, other one-implementation languages
470 @cindex @acronym{SWIG}
473 Bindings are implemented as shared objects written in C. In some
474 cases, the C code is generated by a tool, such as @acronym{SWIG}, but
475 the result is the same: a new C library that manually translates
476 between the language implementation's objects, such as @code{PyObject}
477 in Python, and whatever C object is called for, often using C
478 functions provided by the implementation. It also translates between
479 the calling conventions of the language and C.
482 @cindex @acronym{SLIME}
483 Bindings are written in Lisp. They can be created at-will by Lisp
484 programs. Lisp programmers can write new bindings and add them to the
485 image, using a listener such as @acronym{SLIME}, as easily as with
486 regular Lisp definitions. The only foreign library to load is the one
487 being wrapped---the one with the pure C interface; no C or other
488 non-Lisp compilation is required.
491 @cindex advantages of @acronym{FFI}
492 @cindex benefits of @acronym{FFI}
493 We believe the advantages of the Common Lisp approach far outweigh any
494 disadvantages. Incremental development with a listener can be as
495 productive for C binding development as it is with other Lisp
496 development. Keeping it ``in the [Lisp] family'', as it were, makes
497 it much easier for you and other Lisp programmers to load and use the
498 bindings. Common Lisp implementations such as @acronym{CMUCL}, freed
499 from having to provide a C interface to their own objects, are thus
500 freed to be implemented in another language (as @acronym{CMUCL} is)
501 while still allowing programmers to call foreign functions.
503 @cindex minimal bindings
504 Perhaps the greatest advantage is that using an @acronym{FFI} doesn't
505 obligate you to become a professional binding developer. Writers of
506 bindings for other languages usually end up maintaining or failing to
507 maintain complete bindings to the foreign library. Using an
508 @acronym{FFI}, however, means if you only need one or two functions,
509 you can write bindings for only those functions, and be assured that
510 you can just as easily add to the bindings if need be.
512 @cindex C abstractions
513 @cindex abstractions in C
514 The removal of the C compiler, or C interpretation of any kind,
515 creates the main disadvantage: some of C's ``abstractions'' are not
516 available, violating information encapsulation. For example,
517 @code{struct}s that must be passed on the stack, or used as return
518 values, without corresponding functional abstractions to create and
519 manage the @code{struct}s, must be declared explicitly in Lisp. This
520 is fine for structs whose contents are ``public'', but is not so
521 pleasant when a struct is supposed to be ``opaque'' by convention,
522 even though it is not so defined.@footnote{Admittedly, this is an
523 advanced issue, and we encourage you to leave this text until you are
524 more familiar with how @cffi{} works.}
526 Without an abstraction to create the struct, Lisp needs to be able to
527 lay out the struct in memory, so must know its internal details.
529 @cindex workaround for C
530 In these cases, you can create a minimal C library to provide the
531 missing abstractions, without destroying all the advantages of the
532 Common Lisp approach discussed above. In the case of @code{struct}s,
533 you can write simple, pure C functions that tell you how many bytes a
534 struct requires or allocate new structs, read and write fields of the
535 struct, or whatever operations are supposed to be
536 public.@footnote{This does not apply to structs whose contents are
537 intended to be part of the public library interface. In those cases,
538 a pure Lisp struct definition is always preferred. In fact, many
539 prefer to stay in Lisp and break the encapsulation anyway, placing the
540 burden of correct library interface definition on the library.}
542 @impnote{cffi-grovel, a project not yet part of @cffi{}, automates
543 this and other processes.}
545 Another disadvantage appears when you would rather use the foreign
546 language than Lisp. However, someone who prefers C to Lisp is not a
547 likely candidate for developing a Lisp interface to a C library.
550 @node Tutorial-Getting a URL
551 @section Getting a @acronym{URL}
553 @cindex c@acronym{URL}
554 The widely available @code{libcurl} is a library for downloading files
555 over protocols like @acronym{HTTP}. We will use @code{libcurl} with
556 @cffi{} to download a web page.
558 Please note that there are many other ways to download files from the
559 web, not least the @sc{cl-curl} project to provide bindings to
560 @code{libcurl} via a similar @acronym{FFI}.@footnote{Specifically,
561 @acronym{UFFI}, an older @acronym{FFI} that takes a somewhat different
562 approach compared to @cffi{}. I believe that these days (December
563 2005) @cffi{} is more portable and actively developed, though not as
564 mature yet. Consensus in the free @sc{unix} Common Lisp community
565 seems to be that @cffi{} is preferred for new development, though
566 @acronym{UFFI} will likely go on for quite some time as many projects
567 already use it. @cffi{} includes the @code{UFFI-COMPAT} package for
568 complete compatibility with @acronym{UFFI}.}
570 @uref{http://curl.haxx.se/libcurl/c/libcurl-tutorial.html,,libcurl-tutorial(3)}
571 is a tutorial for @code{libcurl} programming in C. We will follow
572 that to develop a binding to download a file. We will also use
573 @file{curl.h}, @file{easy.h}, and the @command{man} pages for the
574 @code{libcurl} function, all available in the @samp{curl-dev} package
575 or equivalent for your system, or in the c@acronym{URL} source code
576 package. If you have the development package, the headers should be
577 installed in @file{/usr/include/curl/}, and the @command{man} pages
578 may be accessed through your favorite @command{man} facility.
581 @node Tutorial-Loading
582 @section Loading foreign libraries
584 @cindex loading @cffi{}
585 @cindex requiring @cffi{}
586 First of all, we will create a package to work in. You can save these
587 forms in a file, or just send them to the listener as they are. If
588 creating bindings for an @acronym{ASDF} package of yours, you will
589 want to add @code{:cffi} to the @code{:depends-on} list in your
590 @file{.asd} file. Otherwise, just use the @code{asdf:oos} function to
593 @tutorialsource{Initialization}
595 (asdf:oos 'asdf:load-op :cffi)
597 ;;; @lispcmt{Nothing special about the "CFFI-USER" package. We're just}
598 ;;; @lispcmt{using it as a substitute for your own CL package.}
599 (defpackage :cffi-user
600 (:use :common-lisp :cffi))
602 (in-package :cffi-user)
604 (define-foreign-library libcurl
605 (:unix (:or "libcurl.so.3" "libcurl.so"))
606 (t (:default "libcurl")))
608 (use-foreign-library libcurl)
611 @cindex foreign library load
612 @cindex library, foreign
613 Using @code{define-foreign-library} and @code{use-foreign-library}, we
614 have loaded @code{libcurl} into Lisp, much as the linker does when you
615 start a C program, or @code{common-lisp:load} does with a Lisp source
616 file or @acronym{FASL} file. We special-cased for @sc{unix} machines
617 to always load a particular version, the one this tutorial was tested
618 with; for those who don't care, the @code{define-foreign-library}
619 clause @code{(t (:default "libcurl"))} should be satisfactory, and
620 will adapt to various operating systems.
623 @node Tutorial-Initializing
624 @section Initializing @code{libcurl}
626 @cindex function definition
627 After the introductory matter, the tutorial goes on to present the
628 first function you should use.
631 CURLcode curl_global_init(long flags);
635 Let's pick this apart into appropriate Lisp code:
637 @tutorialsource{First CURLcode}
639 ;;; @lispcmt{A CURLcode is the universal error code. curl/curl.h says}
640 ;;; @lispcmt{no return code will ever be removed, and new ones will be}
641 ;;; @lispcmt{added to the end.}
642 (defctype curl-code :int)
644 ;;; @lispcmt{Initialize libcurl with FLAGS.}
645 (defcfun "curl_global_init" curl-code
649 @impnote{By default, CFFI assumes the UNIX viewpoint that there is one
650 C symbol namespace, containing all symbols in all loaded objects.
651 This is not so on Windows and Darwin, but we emulate UNIX's behaviour
652 there. @ref{defcfun} for more details.}
654 Note the parallels with the original C declaration. We've defined
655 @code{curl-code} as a wrapping type for @code{:int}; right now, it
656 only marks it as special, but later we will do something more
657 interesting with it. The point is that we don't have to do it yet.
659 @cindex calling foreign functions
660 Looking at @file{curl.h}, @code{CURL_GLOBAL_NOTHING}, a possible value
661 for @code{flags} above, is defined as @samp{0}. So we can now call
665 @sc{cffi-user>} (curl-global-init 0)
669 @cindex looks like it worked
670 Looking at @file{curl.h} again, @code{0} means @code{CURLE_OK}, so it
671 looks like the call succeeded. Note that @cffi{} converted the
672 function name to a Lisp-friendly name. You can specify your own name
673 if you want; use @code{("curl_global_init" @var{your-name-here})} as
674 the @var{name} argument to @code{defcfun}.
676 The tutorial goes on to have us allocate a handle. For good measure,
677 we should also include the deallocator. Let's look at these
681 CURL *curl_easy_init( );
682 void curl_easy_cleanup(CURL *handle);
685 Advanced users may want to define special pointer types; we will
686 explore this possibility later. For now, just treat every pointer as
689 @tutorialsource{curl_easy handles}
691 (defcfun "curl_easy_init" :pointer)
693 (defcfun "curl_easy_cleanup" :void
694 (easy-handle :pointer))
697 Now we can continue with the tutorial:
700 @sc{cffi-user>} (defparameter *easy-handle* (curl-easy-init))
701 @result{} *EASY-HANDLE*
702 @sc{cffi-user>} *easy-handle*
703 @result{} #<FOREIGN-ADDRESS #x09844EE0>
706 @cindex pointers in Lisp
707 Note the print representation of a pointer. It changes depending on
708 what Lisp you are using, but that doesn't make any difference to
712 @node Tutorial-easy_setopt
713 @section Setting download options
715 The @code{libcurl} tutorial says we'll want to set many options before
716 performing any download actions. This is done through
717 @code{curl_easy_setopt}:
719 @c That is literally ..., not an ellipsis.
721 CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...);
725 @cindex foreign arguments
726 We've introduced a new twist: variable arguments. There is no obvious
727 translation to the @code{defcfun} form, particularly as there are four
728 possible argument types. Because of the way C works, we could define
729 four wrappers around @code{curl_easy_setopt}, one for each type; in
730 this case, however, we'll use the general-purpose macro
731 @code{foreign-funcall} to call this function.
733 @cindex enumeration, C
734 To make things easier on ourselves, we'll create an enumeration of the
735 kinds of options we want to set. The @code{enum CURLoption} isn't the
736 most straightforward, but reading the @code{CINIT} C macro definition
737 should be enlightening.
739 @tutorialsource{CURLoption enumeration}
741 (defmacro define-curl-options (name type-offsets &rest enum-args)
742 "As with CFFI:DEFCENUM, except each of ENUM-ARGS is as follows:
746 Where the arguments are as they are with the CINIT macro defined
747 in curl.h, except NAME is a keyword.
749 TYPE-OFFSETS is a plist of TYPEs to their integer offsets, as
750 defined by the CURLOPTTYPE_LONG et al constants in curl.h."
751 (flet ((enumerated-value (type offset)
752 (+ (getf type-offsets type) offset)))
755 ,@@(loop for (name type number) in enum-args
756 collect (list name (enumerated-value type number))))
757 ',name))) ;@lispcmt{for REPL users' sanity}
759 (define-curl-options curl-option
760 (long 0 objectpoint 10000 functionpoint 20000 off-t 30000)
761 (:noprogress long 43)
763 (:errorbuffer objectpoint 10)
764 (:url objectpoint 2))
767 With some well-placed Emacs @code{query-replace-regexp}s, you could
768 probably similarly define the entire @code{CURLoption} enumeration. I
769 have selected to transcribe a few that we will use in this tutorial.
771 If you're having trouble following the macrology, just macroexpand the
772 @code{curl-option} definition, or see the following macroexpansion,
773 conveniently downcased and reformatted:
775 @tutorialsource{DEFINE-CURL-OPTIONS macroexpansion}
778 (defcenum curl-option
787 That seems more than reasonable. You may notice that we only use the
788 @var{type} to compute the real enumeration offset; we will also need
789 the type information later.
791 First, however, let's make sure a simple call to the foreign function
795 @sc{cffi-user>} (foreign-funcall "curl_easy_setopt"
796 :pointer *easy-handle*
797 curl-option :nosignal :long 1 curl-code)
801 @code{foreign-funcall}, despite its surface simplicity, can be used to
802 call any C function. Its first argument is a string, naming the
803 function to be called. Next, for each argument, we pass the name of
804 the C type, which is the same as in @code{defcfun}, followed by a Lisp
805 object representing the data to be passed as the argument. The final
806 argument is the return type, for which we use the @code{curl-code}
807 type defined earlier.
809 @code{defcfun} just puts a convenient fa@,cade on
810 @code{foreign-funcall}.@footnote{This isn't entirely true; some Lisps
811 don't support @code{foreign-funcall}, so @code{defcfun} is implemented
812 without it. @code{defcfun} may also perform optimizations that
813 @code{foreign-funcall} cannot.} Our earlier call to
814 @code{curl-global-init} could have been written as follows:
817 @sc{cffi-user>} (foreign-funcall "curl_global_init" :long 0
822 Before we continue, we will take a look at what @cffi{} can and can't
823 do, and why this is so.
826 @node Tutorial-Abstraction
827 @section Breaking the abstraction
829 @cindex breaking the abstraction
830 @cindex abstraction breaking
831 In @ref{Tutorial-Comparison,, What makes Lisp different}, we mentioned
832 that writing an @acronym{FFI} sometimes requires depending on
833 information not provided as part of the interface. The easy option
834 @code{CURLOPT_WRITEDATA}, which we will not provide as part of the
835 Lisp interface, illustrates this issue.
837 Strictly speaking, the @code{curl-option} enumeration is not
838 necessary; we could have used @code{:int 99} instead of
839 @code{curl-option :nosignal} in our call to @code{curl_easy_setopt}
840 above. We defined it anyway, in part to hide the fact that we are
841 breaking the abstraction that the C @code{enum} provides. If the
842 c@acronym{URL} developers decide to change those numbers later, we
843 must change the Lisp enumeration, because enumeration values are not
844 provided in the compiled C library, @code{libcurl.so.3}.
846 @cffi{} works because the most useful things in C libraries ---
847 non-static functions and non-static variables --- are included
848 accessibly in @code{libcurl.so.3}. A C compiler that violated this
849 would be considered a worthless compiler.
851 The other thing @code{define-curl-options} does is give the ``type''
852 of the third argument passed to @code{curl_easy_setopt}. Using this
853 information, we can tell that the @code{:nosignal} option should
854 accept a long integer argument. We can implicitly assume @code{t}
855 @equiv{} 1 and @code{nil} @equiv{} 0, as it is in C, which takes care
856 of the fact that @code{CURLOPT_NOSIGNAL} is really asking for a
859 The ``type'' of @code{CURLOPT_WRITEDATA} is @code{objectpoint}.
860 However, it is really looking for a @code{FILE*}.
861 @code{CURLOPT_ERRORBUFFER} is looking for a @code{char*}, so there is
862 no obvious @cffi{} type but @code{:pointer}.
864 The first thing to note is that nowhere in the C interface includes
865 this information; it can only be found in the manual. We could
866 disjoin these clearly different types ourselves, by splitting
867 @code{objectpoint} into @code{filepoint} and @code{charpoint}, but we
868 are still breaking the abstraction, because we have to augment the
869 entire enumeration form with this additional
870 information.@footnote{Another possibility is to allow the caller to
871 specify the desired C type of the third argument. This is essentially
872 what happens in a call to the function written in C.}
874 @cindex streams and C
875 @cindex @sc{file}* and streams
876 The second is that the @code{CURLOPT_WRITEDATA} argument is completely
877 incompatible with the desired Lisp data, a
878 stream.@footnote{@xref{Other Kinds of Streams,,, libc, GNU C Library
879 Reference}, for a @acronym{GNU}-only way to extend the @code{FILE*}
880 type. You could use this to convert Lisp streams to the needed C
881 data. This would be quite involved and far outside the scope of this
882 tutorial.} It is probably acceptable if we are controlling every file
883 we might want to use as this argument, in which case we can just call
884 the foreign function @code{fopen}. Regardless, though, we can't write
885 to arbitrary streams, which is exactly what we want to do for this
888 Finally, note that the @code{curl_easy_setopt} interface itself is a
889 hack, intended to work around some of the drawbacks of C. The
890 definition of @code{Curl_setopt}, while long, is far less cluttered
891 than the equivalent disjoint-function set would be; in addition,
892 setting a new option in an old @code{libcurl} can generate a run-time
893 error rather than breaking the compile. Lisp can just as concisely
894 generate functions as compare values, and the ``undefined function''
895 error is just as useful as any explicit error we could define here
899 @node Tutorial-Lisp easy_setopt
900 @section Option functions in Lisp
902 We could use @code{foreign-funcall} directly every time we wanted to
903 call @code{curl_easy_setopt}. However, we can encapsulate some of the
904 necessary information with the following.
907 ;;; @lispcmt{We will use this type later in a more creative way. For}
908 ;;; @lispcmt{now, just consider it a marker that this isn't just any}
909 ;;; @lispcmt{pointer.}
910 (defctype easy-handle :pointer)
912 (defmacro curl-easy-setopt (easy-handle enumerated-name
913 value-type new-value)
914 "Call `curl_easy_setopt' on EASY-HANDLE, using ENUMERATED-NAME
915 as the OPTION. VALUE-TYPE is the CFFI foreign type of the third
916 argument, and NEW-VALUE is the Lisp data to be translated to the
917 third argument. VALUE-TYPE is not evaluated."
918 `(foreign-funcall "curl_easy_setopt" easy-handle ,easy-handle
919 curl-option ,enumerated-name
920 ,value-type ,new-value curl-code))
923 Now we define a function for each kind of argument that encodes the
924 correct @code{value-type} in the above. This can be done reasonably
925 in the @code{define-curl-options} macroexpansion; after all, that is
926 where the different options are listed!
928 @cindex Lispy C functions
929 We could make @code{cl:defun} forms in the expansion that simply call
930 @code{curl-easy-setopt}; however, it is probably easier and clearer to
931 use @code{defcfun}. @code{define-curl-options} was becoming unwieldy,
932 so I defined some helpers in this new definition.
935 (defun curry-curl-option-setter (function-name option-keyword)
936 "Wrap the function named by FUNCTION-NAME with a version that
937 curries the second argument as OPTION-KEYWORD.
939 This function is intended for use in DEFINE-CURL-OPTION-SETTER."
940 (setf (symbol-function function-name)
941 (let ((c-function (symbol-function function-name)))
942 (lambda (easy-handle new-value)
943 (funcall c-function easy-handle option-keyword
946 (defmacro define-curl-option-setter (name option-type
947 option-value foreign-type)
948 "Define (with DEFCFUN) a function NAME that calls
949 curl_easy_setopt. OPTION-TYPE and OPTION-VALUE are the CFFI
950 foreign type and value to be passed as the second argument to
951 easy_setopt, and FOREIGN-TYPE is the CFFI foreign type to be used
952 for the resultant function's third argument.
954 This macro is intended for use in DEFINE-CURL-OPTIONS."
956 (defcfun ("curl_easy_setopt" ,name) curl-code
957 (easy-handle easy-handle)
958 (option ,option-type)
959 (new-value ,foreign-type))
960 (curry-curl-option-setter ',name ',option-value)))
962 (defmacro define-curl-options (type-name type-offsets &rest enum-args)
963 "As with CFFI:DEFCENUM, except each of ENUM-ARGS is as follows:
967 Where the arguments are as they are with the CINIT macro defined
968 in curl.h, except NAME is a keyword.
970 TYPE-OFFSETS is a plist of TYPEs to their integer offsets, as
971 defined by the CURLOPTTYPE_LONG et al constants in curl.h.
973 Also, define functions for each option named
974 set-`TYPE-NAME'-`OPTION-NAME', where OPTION-NAME is the NAME from
975 the above destructuring."
976 (flet ((enumerated-value (type offset)
977 (+ (getf type-offsets type) offset))
978 ;;@lispcmt{map PROCEDURE, destructuring each of ENUM-ARGS}
979 (map-enum-args (procedure)
980 (mapcar (lambda (arg) (apply procedure arg)) enum-args))
981 ;;@lispcmt{build a name like SET-CURL-OPTION-NOSIGNAL}
982 (make-setter-name (option-name)
984 'string "SET-" (symbol-name type-name)
985 "-" (symbol-name option-name)))))
989 (lambda (name type number)
990 (list name (enumerated-value type number)))))
992 (lambda (name type number)
993 (declare (ignore number))
994 `(define-curl-option-setter ,(make-setter-name name)
995 ,type-name ,name ,(ecase type
997 (objectpoint :pointer)
998 (functionpoint :pointer)
1004 Macroexpanding our @code{define-curl-options} form once more, we
1005 see something different:
1009 (defcenum curl-option
1012 (:errorbuffer 10010)
1014 (define-curl-option-setter set-curl-option-noprogress
1015 curl-option :noprogress :long)
1016 (define-curl-option-setter set-curl-option-nosignal
1017 curl-option :nosignal :long)
1018 (define-curl-option-setter set-curl-option-errorbuffer
1019 curl-option :errorbuffer :pointer)
1020 (define-curl-option-setter set-curl-option-url
1021 curl-option :url :pointer)
1026 Macroexpanding one of the new @code{define-curl-option-setter}
1027 forms yields the following:
1031 (defcfun ("curl_easy_setopt" set-curl-option-nosignal) curl-code
1032 (easy-handle easy-handle)
1033 (option curl-option)
1035 (curry-curl-option-setter 'set-curl-option-nosignal ':nosignal))
1039 Finally, let's try this out:
1042 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1)
1047 Looks like it works just as well. This interface is now reasonably
1048 high-level to wash out some of the ugliness of the thinnest possible
1049 @code{curl_easy_setopt} @acronym{FFI}, without obscuring the remaining
1050 C bookkeeping details we will explore.
1053 @node Tutorial-Memory
1054 @section Memory management
1056 According to the documentation for @code{curl_easy_setopt}, the type
1057 of the third argument when @var{option} is @code{CURLOPT_ERRORBUFFER}
1058 is @code{char*}. Above, we've defined
1059 @code{set-curl-option-errorbuffer} to accept a @code{:pointer} as the
1060 new option value. However, there is a @cffi{} type @code{:string},
1061 which translates Lisp strings to C strings when passed as arguments to
1062 foreign function calls. Why not, then, use @code{:string} as the
1063 @cffi{} type of the third argument? There are two reasons, both
1064 related to the necessity of breaking abstraction described in
1065 @ref{Tutorial-Abstraction,, Breaking the abstraction}.
1067 The first reason also applies to @code{CURLOPT_URL}, which we will use
1068 to illustrate the point. Assuming we have changed the type of the
1069 third argument underlying @code{set-curl-option-url} to
1070 @code{:string}, look at these two equivalent forms.
1073 (set-curl-option-url *easy-handle* "http://www.cliki.net/CFFI")
1075 @equiv{} (with-foreign-string (url "http://www.cliki.net/CFFI")
1076 (foreign-funcall "curl_easy_setopt" easy-handle *easy-handle*
1077 curl-option :url :pointer url curl-code))
1081 The latter, in fact, is mostly equivalent to what a foreign function
1082 call's macroexpansion actually does. As you can see, the Lisp string
1083 @code{"@clikicffi{}"} is copied into a @code{char} array and
1084 null-terminated; the pointer to beginning of this array, now a C
1085 string, is passed as a @cffi{} @code{:pointer} to the foreign
1088 @cindex dynamic extent
1089 @cindex foreign values with dynamic extent
1090 Unfortunately, the C abstraction has failed us, and we must break it.
1091 While @code{:string} works well for many @code{char*} arguments, it
1092 does not for cases like this. As the @code{curl_easy_setopt}
1093 documentation explains, ``The string must remain present until curl no
1094 longer needs it, as it doesn't copy the string.'' The C string
1095 created by @code{with-foreign-string}, however, only has dynamic
1096 extent: it is ``deallocated'' when the body (above containing the
1097 @code{foreign-funcall} form) exits.
1099 @cindex premature deallocation
1100 If we are supposed to keep the C string around, but it goes away, what
1101 happens when some @code{libcurl} function tries to access the
1102 @acronym{URL} string? We have reentered the dreaded world of C
1103 ``undefined behavior''. In some Lisps, it will probably get a chunk
1104 of the Lisp/C stack. You may segfault. You may get some random piece
1105 of other data from the heap. Maybe, in a world where ``dynamic
1106 extent'' is defined to be ``infinite extent'', everything will turn
1107 out fine. Regardless, results are likely to be almost universally
1108 unpleasant.@footnote{``@i{But I thought Lisp was supposed to protect
1109 me from all that buggy C crap!}'' Before asking a question like that,
1110 remember that you are a stranger in a foreign land, whose residents
1111 have a completely different set of values.}
1113 Returning to the current @code{set-curl-option-url} interface, here is
1119 (with-foreign-string (url "http://www.cliki.net/CFFI")
1120 (setf easy-handle (curl-easy-init))
1121 (set-curl-option-url easy-handle url)
1122 #|@lispcmt{do more with the easy-handle, like actually get the URL}|#)
1124 (curl-easy-cleanup easy-handle))))
1127 @c old comment to luis: I go on to say that this isn't obviously
1128 @c extensible to new option settings that require C strings to stick
1129 @c around, as it would involve re-evaluating the unwind-protect form
1130 @c with more dynamic memory allocation. So I plan to show how to
1131 @c write something similar to ObjC's NSAutoreleasePool, to be managed
1132 @c with a simple unwind-protect form.
1135 That is fine for the single string defined here, but for every string
1136 option we want to pass, we have to surround the body of
1137 @code{with-foreign-string} with another @code{with-foreign-string}
1138 wrapper, or else do some extremely error-prone pointer manipulation
1139 and size calculation in advance. We could alleviate some of the pain
1140 with a recursively expanding macro, but this would not remove the need
1141 to modify the block every time we want to add an option, anathema as
1142 it is to a modular interface.
1144 Before modifying the code to account for this case, consider the other
1145 reason we can't simply use @code{:string} as the foreign type. In C,
1146 a @code{char *} is a @code{char *}, not necessarily a string. The
1147 option @code{CURLOPT_ERRORBUFFER} accepts a @code{char *}, but does
1148 not expect anything about the data there. However, it does expect
1149 that some @code{libcurl} function we call later can write a C string
1150 of up to 255 characters there. We, the callers of the function, are
1151 expected to read the C string at a later time, exactly the opposite of
1152 what @code{:string} implies.
1154 With the semantics for an input string in mind --- namely, that the
1155 string should be kept around until we @code{curl_easy_cleanup} the
1156 easy handle --- we are ready to extend the Lisp interface:
1159 (defvar *easy-handle-cstrings* (make-hash-table)
1160 "Hashtable of easy handles to lists of C strings that may be
1161 safely freed after the handle is freed.")
1163 (defun make-easy-handle ()
1164 "Answer a new CURL easy interface handle, to which the lifetime
1165 of C strings may be tied. See `add-curl-handle-cstring'."
1166 (let ((easy-handle (curl-easy-init)))
1167 (setf (gethash easy-handle *easy-handle-cstrings*) '())
1170 (defun free-easy-handle (handle)
1171 "Free CURL easy interface HANDLE and any C strings created to
1173 (curl-easy-cleanup handle)
1174 (mapc #'foreign-string-free
1175 (gethash handle *easy-handle-cstrings*))
1176 (remhash handle *easy-handle-cstrings*))
1178 (defun add-curl-handle-cstring (handle cstring)
1179 "Add CSTRING to be freed when HANDLE is, answering CSTRING."
1180 (car (push cstring (gethash handle *easy-handle-cstrings*))))
1184 Here we have redefined the interface to create and free handles, to
1185 associate a list of allocated C strings with each handle while it
1186 exists. The strategy of using different function names to wrap around
1187 simple foreign functions is more common than the solution implemented
1188 earlier with @code{curry-curl-option-setter}, which was to modify the
1189 function name's function slot.@footnote{There are advantages and
1190 disadvantages to each approach; I chose to @code{(setf
1191 symbol-function)} earlier because it entailed generating fewer magic
1194 Incidentally, the next step is to redefine
1195 @code{curry-curl-option-setter} to allocate C strings for the
1196 appropriate length of time, given a Lisp string as the
1197 @code{new-value} argument:
1200 (defun curry-curl-option-setter (function-name option-keyword)
1201 "Wrap the function named by FUNCTION-NAME with a version that
1202 curries the second argument as OPTION-KEYWORD.
1204 This function is intended for use in DEFINE-CURL-OPTION-SETTER."
1205 (setf (symbol-function function-name)
1206 (let ((c-function (symbol-function function-name)))
1207 (lambda (easy-handle new-value)
1208 (funcall c-function easy-handle option-keyword
1209 (if (stringp new-value)
1210 (add-curl-handle-cstring
1212 (foreign-string-alloc new-value))
1217 A quick analysis of the code shows that you need only reevaluate the
1218 @code{curl-option} enumeration definition to take advantage of these
1219 new semantics. Now, for good measure, let's reallocate the handle
1220 with the new functions we just defined, and set its @acronym{URL}:
1223 @sc{cffi-user>} (curl-easy-cleanup *easy-handle*)
1225 @sc{cffi-user>} (setf *easy-handle* (make-easy-handle))
1226 @result{} #<FOREIGN-ADDRESS #x09844EE0>
1227 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1)
1229 @sc{cffi-user>} (set-curl-option-url *easy-handle*
1230 "http://www.cliki.net/CFFI")
1235 For fun, let's inspect the Lisp value of the C string that was created
1236 to hold @code{"@clikicffi{}"}. By virtue of the implementation of
1237 @code{add-curl-handle-cstring}, it should be accessible through the
1241 @sc{cffi-user>} (foreign-string-to-lisp
1242 (car (gethash *easy-handle* *easy-handle-cstrings*)))
1243 @result{} "http://www.cliki.net/CFFI"
1247 Looks like that worked, and @code{libcurl} now knows what
1248 @acronym{URL} we want to retrieve.
1250 Finally, we turn back to the @code{:errorbuffer} option mentioned at
1251 the beginning of this section. Whereas the abstraction added to
1252 support string inputs works fine for cases like @code{CURLOPT_URL}, it
1253 hides the detail of keeping the C string; for @code{:errorbuffer},
1254 however, we need that C string.
1256 In a moment, we'll define something slightly cleaner, but for now,
1257 remember that you can always hack around anything. We're modifying
1258 handle creation, so make sure you free the old handle before
1259 redefining @code{free-easy-handle}.
1262 (defvar *easy-handle-errorbuffers* (make-hash-table)
1263 "Hashtable of easy handles to C strings serving as error
1264 writeback buffers.")
1266 ;;; @lispcmt{An extra byte is very little to pay for peace of mind.}
1267 (defparameter *curl-error-size* 257
1268 "Minimum char[] size used by cURL to report errors.")
1270 (defun make-easy-handle ()
1271 "Answer a new CURL easy interface handle, to which the lifetime
1272 of C strings may be tied. See `add-curl-handle-cstring'."
1273 (let ((easy-handle (curl-easy-init)))
1274 (setf (gethash easy-handle *easy-handle-cstrings*) '())
1275 (setf (gethash easy-handle *easy-handle-errorbuffers*)
1276 (foreign-alloc :char :count *curl-error-size*
1277 :initial-element 0))
1280 (defun free-easy-handle (handle)
1281 "Free CURL easy interface HANDLE and any C strings created to
1283 (curl-easy-cleanup handle)
1284 (foreign-free (gethash handle *easy-handle-errorbuffers*))
1285 (remhash handle *easy-handle-errorbuffers*)
1286 (mapc #'foreign-string-free
1287 (gethash handle *easy-handle-cstrings*))
1288 (remhash handle *easy-handle-cstrings*))
1290 (defun get-easy-handle-error (handle)
1291 "Answer a string containing HANDLE's current error message."
1292 (foreign-string-to-lisp
1293 (gethash handle *easy-handle-errorbuffers*)))
1296 Be sure to once again set the options we've set thus far. You may
1297 wish to define yet another wrapper function to do this.
1300 @node Tutorial-Callbacks
1301 @section Calling Lisp from C
1303 If you have been reading
1304 @uref{http://curl.haxx.se/libcurl/c/curl_easy_setopt.html,,
1305 @code{curl_easy_setopt(3)}}, you should have noticed that some options
1306 accept a function pointer. In particular, we need one function
1307 pointer to set as @code{CURLOPT_WRITEFUNCTION}, to be called by
1308 @code{libcurl} rather than the reverse, in order to receive data as it
1311 A binding writer without the aid of @acronym{FFI} usually approaches
1312 this problem by writing a C function that accepts C data, converts to
1313 the language's internal objects, and calls the callback provided by
1314 the user, again in a reverse of usual practices.
1316 The @cffi{} approach to callbacks precisely mirrors its differences
1317 with the non-@acronym{FFI} approach on the ``calling C from Lisp''
1318 side, which we have dealt with exclusively up to now. That is, you
1319 define a callback function in Lisp using @code{defcallback}, and
1320 @cffi{} effectively creates a C function to be passed as a function
1323 @impnote{This is much trickier than calling C functions from Lisp, as
1324 it literally involves somehow generating a new C function that is as
1325 good as any created by the compiler. Therefore, not all Lisps support
1326 them. @xref{Implementation Support}, for information about @cffi{}
1327 support issues in this and other areas. You may want to consider
1328 changing to a Lisp that supports callbacks in order to continue with
1331 @cindex callback definition
1332 @cindex defining callbacks
1333 Defining a callback is very similar to defining a callout; the main
1334 difference is that we must provide some Lisp forms to be evaluated as
1335 part of the callback. Here is the signature for the function the
1336 @code{:writefunction} option takes:
1340 @var{function}(void *ptr, size_t size, size_t nmemb, void *stream);
1343 @impnote{size_t is almost always an unsigned int. You can get this
1344 and many other types using feature tests for your system by using
1347 The above signature trivially translates into a @cffi{}
1348 @code{defcallback} form, as follows.
1351 ;;; @lispcmt{Alias in case size_t changes.}
1352 (defctype size :unsigned-int)
1354 ;;; @lispcmt{To be set as the CURLOPT_WRITEFUNCTION of every easy handle.}
1355 (defcallback easy-write size ((ptr :pointer) (size size)
1356 (nmemb size) (stream :pointer))
1357 (let ((data-size (* size nmemb)))
1359 ;; @lispcmt{We use the dynamically-bound *easy-write-procedure* to}
1360 ;; @lispcmt{call a closure with useful lexical context.}
1361 (progn (funcall (symbol-value '*easy-write-procedure*)
1362 (foreign-string-to-lisp ptr data-size nil))
1363 data-size) ;@lispcmt{indicates success}
1364 ;; @lispcmt{The WRITEFUNCTION should return something other than the}
1365 ;; @lispcmt{#bytes available to signal an error.}
1366 (error () (if (zerop data-size) 1 0)))))
1369 First, note the correlation of the first few forms, used to declare
1370 the C function's signature, with the signature in C syntax. We
1371 provide a Lisp name for the function, its return type, and a name and
1372 type for each argument.
1374 In the body, we call the dynamically-bound
1375 @code{*easy-write-procedure*} with a ``finished'' translation, of
1376 pulling together the raw data and size into a Lisp string, rather than
1377 deal with the data directly. As part of calling
1378 @code{curl_easy_perform} later, we'll bind that variable to a closure
1379 with more useful lexical bindings than the top-level
1380 @code{defcallback} form.
1382 Finally, we make a halfhearted effort to prevent non-local exits from
1383 unwinding the C stack, covering the most likely case with an
1384 @code{error} handler, which is usually triggered
1385 unexpectedly.@footnote{Unfortunately, we can't protect against
1386 @emph{all} non-local exits, such as @code{return}s and @code{throw}s,
1387 because @code{unwind-protect} cannot be used to ``short-circuit'' a
1388 non-local exit in Common Lisp, due to proposal @code{minimal} in
1389 @uref{http://www.lisp.org/HyperSpec/Issues/iss152-writeup.html,
1390 @acronym{ANSI} issue @sc{Exit-Extent}}. Furthermore, binding an
1391 @code{error} handler prevents higher-up code from invoking restarts
1392 that may be provided under the callback's dynamic context. Such is
1393 the way of compromise.} The reason is that most C code is written to
1394 understand its own idiosyncratic error condition, implemented above in
1395 the case of @code{curl_easy_perform}, and more ``undefined behavior''
1396 can result if we just wipe C stack frames without allowing them to
1397 execute whatever cleanup actions as they like.
1399 Using the @code{CURLoption} enumeration in @file{curl.h} once more, we
1400 can describe the new option by modifying and reevaluating
1401 @code{define-curl-options}.
1404 (define-curl-options curl-option
1405 (long 0 objectpoint 10000 functionpoint 20000 off-t 30000)
1406 (:noprogress long 43)
1408 (:errorbuffer objectpoint 10)
1409 (:url objectpoint 2)
1410 (:writefunction functionpoint 11)) ;@lispcmt{new item here}
1413 Finally, we can use the defined callback and the new
1414 @code{set-curl-option-writefunction} to finish configuring the easy
1415 handle, using the @code{callback} macro to retrieve a @cffi{}
1416 @code{:pointer}, which works like a function pointer in C code.
1419 @sc{cffi-user>} (set-curl-option-writefunction
1420 *easy-handle* (callback easy-write))
1425 @node Tutorial-Completion
1426 @section A complete @acronym{FFI}?
1428 @c TeX goes insane on @uref{@clikicffi{}}
1430 With all options finally set and a medium-level interface developed,
1431 we can finish the definition and retrieve
1432 @uref{http://www.cliki.net/CFFI}, as is done in the tutorial.
1435 (defcfun "curl_easy_perform" curl-code
1436 (handle easy-handle))
1440 @sc{cffi-user>} (with-output-to-string (contents)
1441 (let ((*easy-write-procedure*
1443 (write-string string contents))))
1444 (declare (special *easy-write-procedure*))
1445 (curl-easy-perform *easy-handle*)))
1446 @result{} "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\"
1448 Now fear, comprehensively</P>
1452 Of course, that itself is slightly unwieldy, so you may want to define
1453 a function around it that simply retrieves a @acronym{URL}. I will
1454 leave synthesis of all the relevant @acronym{REPL} forms presented
1455 thus far into a single function as an exercise for the reader.
1457 The remaining sections of this tutorial explore some advanced features
1458 of @cffi{}; the definition of new types will receive special
1459 attention. Some of these features are essential for particular
1460 foreign function calls; some are very helpful when trying to develop a
1461 Lispy interface to C.
1464 @node Tutorial-Types
1465 @section Defining new types
1467 We've occasionally used the @code{defctype} macro in previous sections
1468 as a kind of documentation, much what you'd use @code{typedef} for in
1469 C. We also tried one special kind of type definition, the
1470 @code{defcenum} type. @xref{defcstruct}, for a definition macro that
1471 may come in handy if you need to use C @code{struct}s as data.
1473 @cindex type definition
1474 @cindex data in Lisp and C
1475 @cindex translating types
1476 However, all of these are mostly sugar for the powerful underlying
1477 foreign type interface called @dfn{type translators}. You can easily
1478 define new translators for any simple named foreign type. Since we've
1479 defined the new type @code{curl-code} to use as the return type for
1480 various @code{libcurl} functions, we can use that to directly convert
1481 c@acronym{URL} errors to Lisp errors.
1483 @code{defctype}'s purpose is to define simple @code{typedef}-like
1484 aliases. In order to use @dfn{type translators} we must use the
1485 @code{define-foreign-type} macro. So let's redefine @code{curl-code}
1489 (define-foreign-type curl-code-type ()
1492 (:simple-parser curl-code))
1495 @code{define-foreign-type} is a thin wrapper around @code{defclass}.
1496 For now, all you need to know in the context of this example is that
1497 it does what @code{(defctype curl-code :int)} would do and,
1498 additionally, defines a new class @code{curl-code-type} which we will
1499 take advantage of shortly.
1501 The @code{CURLcode} enumeration seems to follow the typical error code
1502 convention of @samp{0} meaning all is well, and each non-zero integer
1503 indicating a different kind of error. We can apply that trivially to
1504 differentiate between normal exits and error exits.
1507 (define-condition curl-code-error (error)
1508 (($code :initarg :curl-code :reader curl-error-code))
1509 (:report (lambda (c stream)
1510 (format stream "libcurl function returned error ~A"
1511 (curl-error-code c))))
1512 (:documentation "Signalled when a libcurl function answers
1513 a code other than CURLE_OK."))
1515 (defmethod translate-from-foreign (value (type curl-code-type))
1516 "Raise a CURL-CODE-ERROR if VALUE, a curl-code, is non-zero."
1519 (error 'curl-code-error :curl-code value)))
1523 The heart of this translator is new method
1524 @code{translate-from-foreign}. By specializing the @var{type}
1525 parameter on @code{curl-code-type}, we immediately modify the behavior
1526 of every function that returns a @code{curl-code} to pass the result
1527 through this new method.
1529 To see the translator in action, try invoking a function that returns
1530 a @code{curl-code}. You need to reevaluate the respective
1531 @code{defcfun} form so that it picks up the new @code{curl-code}
1535 @sc{cffi-user>} (set-curl-option-nosignal *easy-handle* 1)
1540 As the result was @samp{0}, the new method returned @code{:curle-ok},
1541 just as specified.@footnote{It might be better to return
1542 @code{(values)} than @code{:curle-ok} in real code, but this is good
1543 for illustration.} I will leave disjoining the separate
1544 @code{CURLcode}s into condition types and improving the @code{:report}
1545 function as an exercise for you.
1547 The creation of @code{*easy-handle-cstrings*} and
1548 @code{*easy-handle-errorbuffers*} as properties of @code{easy-handle}s
1549 is a kluge. What we really want is a Lisp structure that stores these
1550 properties along with the C pointer. Unfortunately,
1551 @code{easy-handle} is currently just a fancy name for the foreign type
1552 @code{:pointer}; the actual pointer object varies from Common Lisp
1553 implementation to implementation, needing only to satisfy
1554 @code{pointerp} and be returned from @code{make-pointer} and friends.
1556 One solution that would allow us to define a new Lisp structure to
1557 represent @code{easy-handle}s would be to write a wrapper around every
1558 function that currently takes an @code{easy-handle}; the wrapper would
1559 extract the pointer and pass it to the foreign function. However, we
1560 can use type translators to more elegantly integrate this
1561 ``translation'' into the foreign function calling framework, using
1562 @code{translate-to-foreign}.
1565 (defclass easy-handle ()
1566 ((pointer :initform (curl-easy-init)
1567 :documentation "Foreign pointer from curl_easy_init")
1569 :initform (foreign-alloc :char :count *curl-error-size*
1571 :documentation "C string describing last error")
1572 (c-strings :initform '()
1573 :documentation "C strings set as options"))
1574 (:documentation "I am a parameterization you may pass to
1575 curl-easy-perform to perform a cURL network protocol request."))
1577 (defmethod initialize-instance :after ((self easy-handle) &key)
1578 (set-curl-option-errorbuffer self (slot-value self 'error-buffer)))
1580 (defun add-curl-handle-cstring (handle cstring)
1581 "Add CSTRING to be freed when HANDLE is, answering CSTRING."
1582 (car (push cstring (slot-value handle 'c-strings))))
1584 (defun get-easy-handle-error (handle)
1585 "Answer a string containing HANDLE's current error message."
1586 (foreign-string-to-lisp
1587 (slot-value handle 'error-buffer)))
1589 (defun free-easy-handle (handle)
1590 "Free CURL easy interface HANDLE and any C strings created to
1592 (with-slots (pointer error-buffer c-strings) handle
1593 (curl-easy-cleanup pointer)
1594 (foreign-free error-buffer)
1595 (mapc #'foreign-string-free c-strings)))
1597 (define-foreign-type easy-handle-type ()
1599 (:actual-type :pointer)
1600 (:simple-parser easy-handle))
1602 (defmethod translate-to-foreign (handle (type easy-handle-type))
1603 "Extract the pointer from an easy-HANDLE."
1604 (slot-value handle 'pointer))
1607 While we changed some of the Lisp functions defined earlier to use
1608 @acronym{CLOS} slots rather than hash tables, the foreign functions
1609 work just as well as they did before.
1611 @cindex limitations of type translators
1612 The greatest strength, and the greatest limitation, of the type
1613 translator comes from its generalized interface. As stated
1614 previously, we could define all foreign function calls in terms of the
1615 primitive foreign types provided by @cffi{}. The type translator
1616 interface allows us to cleanly specify the relationship between Lisp
1617 and C data, independent of where it appears in a function call. This
1618 independence comes at a price; for example, it cannot be used to
1619 modify translation semantics based on other arguments to a function
1620 call. In these cases, you should rely on other features of Lisp,
1621 rather than the powerful, yet domain-specific, type translator
1625 @node Tutorial-Conclusion
1626 @section What's next?
1628 @cffi{} provides a rich and powerful foundation for communicating with
1629 foreign libraries; as we have seen, it is up to you to make that
1630 experience a pleasantly Lispy one. This tutorial does not cover all
1631 the features of @cffi{}; please see the rest of the manual for
1632 details. In particular, if something seems obviously missing, it is
1633 likely that either code or a good reason for lack of code is already
1636 @impnote{There are some other things in @cffi{} that might deserve
1637 tutorial sections, such as free-translated-object, or structs. Let us
1638 know which ones you care about.}
1641 @c ===================================================================
1642 @c CHAPTER: Wrapper generators
1644 @node Wrapper generators
1645 @chapter Wrapper generators
1647 @cffi{}'s interface is designed for human programmers, being aimed at
1648 aesthetic as well as technical sophistication. However, there are a
1649 few programs aimed at translating C and C++ header files, or
1650 approximations thereof, into @cffi{} forms constituting a foreign
1651 interface to the symbols in those files.
1653 These wrapper generators are known to support output of @cffi{} forms.
1656 @item @uref{http://www.cliki.net/Verrazano,Verrazano}
1657 Designed specifically for Common Lisp. Uses @acronym{GCC}'s parser
1658 output in @acronym{XML} format to discover functions, variables, and
1659 other header file data. This means you need @acronym{GCC} to generate
1660 forms; on the other hand, the parser employed is mostly compliant with
1663 @item @uref{http://www.cliki.net/SWIG,SWIG}
1664 A foreign interface generator originally designed to generate Python
1665 bindings, it has been ported to many other systems, including @cffi{}
1666 in version 1.3.28. Includes its own C declaration munger, not
1667 intended to be fully-compliant with @acronym{ANSI} C.
1670 First, this manual does not describe use of these other programs; they
1671 have documentation of their own. If you have problems using a
1672 generated interface, please look at the output @cffi{} forms and
1673 verify that they are a correct @cffi{} interface to the library in
1674 question; if they are correct, contact @cffi{} developers with
1675 details, keeping in mind that they communicate in terms of those forms
1676 rather than any particular wrapper generator. Otherwise, contact the
1677 maintainers of the wrapper generator you are using, provided you can
1678 reasonably expect more accuracy from the generator.
1680 When is more accuracy an unreasonable expectation? As described in
1681 the tutorial (@pxref{Tutorial-Abstraction,, Breaking the
1682 abstraction}), the information in C declarations is insufficient to
1683 completely describe every interface. In fact, it is quite common to
1684 run into an interface that cannot be handled automatically, and
1685 generators should be excused from generating a complete interface in
1688 As further described in the tutorial, the thinnest Lisp interface to a
1689 C function is not always the most pleasant one. In many cases, you
1690 will want to manually write a Lispier interface to the C functions
1693 Wrapper generators should be treated as time-savers, not complete
1694 automation of the full foreign interface writing job. Reports of the
1695 amount of work done by generators vary from 30% to 90%. The
1696 incremental development style enabled by @cffi{} generally reduces
1697 this proportion below that for languages like Python.
1699 @c Where I got the above 30-90% figures:
1700 @c 30%: lemonodor's post about SWIG
1701 @c 90%: Balooga on #lisp. He said 99%, but that's probably an
1702 @c exaggeration (leave it to me to pass judgement :)
1706 @c ===================================================================
1707 @c CHAPTER: Foreign Types
1710 @chapter Foreign Types
1712 Foreign types describe how data is translated back and forth between C
1713 and Lisp. @cffi{} provides various built-in types and allows the user to
1719 * Defining Foreign Types::
1720 * Foreign Type Translators::
1721 * Optimizing Type Translators::
1722 * Foreign Structure Types::
1723 * Allocating Foreign Objects::
1727 * convert-from-foreign::
1728 * convert-to-foreign::
1734 @c * define-type-spec-parser::
1735 * define-foreign-type::
1736 * define-parse-method::
1737 @c * explain-foreign-slot-value:
1738 * foreign-bitfield-symbols::
1739 * foreign-bitfield-value::
1740 * foreign-enum-keyword::
1741 * foreign-enum-value::
1742 * foreign-slot-names::
1743 * foreign-slot-offset::
1744 * foreign-slot-pointer::
1745 * foreign-slot-value::
1746 * foreign-type-alignment::
1747 * foreign-type-size::
1748 * free-converted-object::
1749 * free-translated-object::
1750 * translate-from-foreign::
1751 * translate-to-foreign::
1752 * with-foreign-slots::
1755 @node Built-In Types
1756 @section Built-In Types
1759 @ForeignType{:unsigned-char}
1760 @ForeignType{:short}
1761 @ForeignType{:unsigned-short}
1763 @ForeignType{:unsigned-int}
1765 @ForeignType{:unsigned-long}
1766 @ForeignType{:long-long}
1767 @ForeignType{:unsigned-long-long}
1769 These types correspond to the native C integer types according to the
1770 @acronym{ABI} of the Lisp implementation's host system.
1772 @code{:long-long} and @code{:unsigned-long-long} are not supported
1773 natively on all implementations. However, they are emulated by
1774 @code{mem-ref} and @code{mem-set}.
1776 When those types are @strong{not} available, the symbol
1777 @code{cffi-features:no-long-long} is pushed into @code{*features*}.
1779 @ForeignType{:uchar}
1780 @ForeignType{:ushort}
1782 @ForeignType{:ulong}
1783 @ForeignType{:llong}
1784 @ForeignType{:ullong}
1786 For convenience, the above types are provided as shortcuts for
1787 @code{unsigned-char}, @code{unsigned-short}, @code{unsigned-int},
1788 @code{unsigned-long}, @code{long-long} and @code{unsigned-long-long},
1792 @ForeignType{:uint8}
1793 @ForeignType{:int16}
1794 @ForeignType{:uint16}
1795 @ForeignType{:int32}
1796 @ForeignType{:uint32}
1797 @ForeignType{:int64}
1798 @ForeignType{:uint64}
1800 Foreign integer types of specific sizes, corresponding to the C types
1801 defined in @code{stdint.h}.
1803 @c @ForeignType{:size}
1804 @c @ForeignType{:ssize}
1805 @c @ForeignType{:ptrdiff}
1806 @c @ForeignType{:time}
1808 @c Foreign integer types corresponding to the standard C types (without
1809 @c the @code{_t} suffix).
1811 @c @impnote{These are not implemented yet. --luis}
1813 @c @impnote{I'm sure there are more of these that could be useful, let's
1814 @c add any types that can't be defined portably to this list as
1815 @c necessary. --james}
1817 @ForeignType{:float}
1818 @ForeignType{:double}
1820 On all systems, the @code{:float} and @code{:double} types represent a
1821 C @code{float} and @code{double}, respectively. On most but not all
1822 systems, @code{:float} and @code{:double} represent a Lisp
1823 @code{single-float} and @code{double-float}, respectively. It is not
1824 so useful to consider the relationship between Lisp types and C types
1825 as isomorphic, as simply to recognize the relationship, and relative
1826 precision, among each respective category.
1828 @ForeignType{:long-double}
1830 This type is only supported on SCL.
1832 @ForeignType{:pointer &optional type}
1834 A foreign pointer to an object of any type, corresponding to
1835 @code{void *}. You can optionally specify type of pointer
1836 (e.g. @code{(:pointer :char)}). Although @cffi{} won't do anything
1837 with that information yet, it is useful for documentation purposes.
1841 No type at all. Only valid as the return type of a function.
1844 @section Other Types
1846 @cffi{} also provides a few useful types that aren't built-in C
1849 @ForeignType{:string}
1851 The @code{:string} type performs automatic conversion between Lisp and
1852 C strings. Note that, in the case of functions the converted C string
1853 will have dynamic extent (i.e.@: it will be automatically freed after
1854 the foreign function returns).
1856 In addition to Lisp strings, this type will also convert
1857 Lisp arrays of element type @code{(unsigned-byte 8)} and will pass
1858 foreign pointers unmodified.
1860 A method for @ref{free-translated-object} is specialized for this
1861 type. So, for example, foreign strings allocated by this type and
1862 passed to a foreign function will be freed after the function
1866 CFFI> (foreign-funcall "getenv" :string "SHELL" :string)
1867 @result{} "/bin/bash"
1869 CFFI> (with-foreign-string (str "abcdef")
1870 (foreign-funcall "strlen" :string str :int))
1873 CFFI> (let ((str (make-array 4 :element-type '(unsigned-byte 8)
1874 :initial-element 65)))
1875 (foreign-funcall "strlen" :string str :int))
1879 @ForeignType{:string+ptr}
1881 Like @code{:string} but returns a list with two values when convert
1882 from C to Lisp: a Lisp string and the C string's foreign pointer.
1885 CFFI> (foreign-funcall "getenv" :string "SHELL" :string+ptr)
1886 @result{} ("/bin/bash" #.(SB-SYS:INT-SAP #XBFFFFC6F))
1889 @ForeignType{:boolean &optional (base-type :int)}
1891 The @code{:boolean} type converts between a Lisp boolean and a C
1892 boolean. It canonicalizes to @var{base-type} which is @code{:int} by
1896 (convert-to-foreign nil :boolean) @result{} 0
1897 (convert-to-foreign t :boolean) @result{} 1
1898 (convert-from-foreign 0 :boolean) @result{} nil
1899 (convert-from-foreign 1 :boolean) @result{} t
1902 @ForeignType{:wrapper base-type &key to-c from-c}
1904 The @code{:wrapper} type stores two symbols passed to the @var{to-c}
1905 and @var{from-c} arguments. When a value is being translated to or
1906 from C, this type @code{funcall}s the respective symbol.
1908 @code{:wrapper} types will be typedefs for @var{base-type} and will
1909 inherit its translators, if any.
1911 Here's an example of how the @code{:boolean} type could be defined in
1912 terms of @code{:wrapper}.
1915 (defun bool-c-to-lisp (value)
1916 (not (zerop value)))
1918 (defun bool-lisp-to-c (value)
1921 (defctype my-bool (:wrapper :int :from-c bool-c-to-lisp
1922 :to-c bool-lisp-to-c))
1924 (convert-to-foreign nil 'my-bool) @result{} 0
1925 (convert-from-foreign 1 'my-bool) @result{} t
1928 @node Defining Foreign Types
1929 @section Defining Foreign Types
1931 You can define simple C-like @code{typedef}s through the
1932 @code{defctype} macro. Defining a typedef is as simple as giving
1933 @code{defctype} a new name and the name of the type to be wrapped.
1936 ;;; @lispcmt{Define MY-INT as an alias for the built-in type :INT.}
1937 (defctype my-int :int)
1940 With this type definition, one can, for instance, declare arguments to
1941 foreign functions as having the type @code{my-int}, and they will be
1944 @subheading More complex types
1946 @cffi{} offers another way to define types through
1947 @code{define-foreign-type}, a thin wrapper macro around
1948 @code{defclass}. As an example, let's go through the steps needed to
1949 define a @code{(my-string &key encoding)} type. First, we need to
1950 define our type class:
1953 (define-foreign-type my-string-type ()
1954 ((encoding :reader string-type-encoding :initarg :encoding))
1955 (:actual-type :pointer))
1958 The @code{:actual-type} class option tells CFFI that this type will
1959 ultimately be passed to and received from foreign code as a
1960 @code{:pointer}. Now you need to tell CFFI how to parse a type
1961 specification such as @code{(my-string :encoding :utf8)} into an
1962 instance of @code{my-string-type}. We do that with
1963 @code{define-parse-method}:
1966 (define-parse-method my-string (&key (encoding :utf-8))
1967 (make-instance 'my-string-type :encoding encoding))
1970 The next section describes how make this type actually translate
1971 between C and Lisp strings.
1973 @node Foreign Type Translators
1974 @section Foreign Type Translators
1976 Type translators are used to automatically convert Lisp values to or
1977 from foreign values. For example, using type translators, one can
1978 take the @code{my-string} type defined in the previous section and
1979 specify that it should:
1983 convert C strings to Lisp strings;
1985 convert Lisp strings to newly allocated C strings;
1987 free said C strings when they are no longer needed.
1990 In order to tell @cffi{} how to automatically convert Lisp values to
1991 foreign values, define a specialized method for the
1992 @code{translate-to-foreign} generic function:
1995 ;;; @lispcmt{Define a method that converts Lisp strings to C strings.}
1996 (defmethod translate-to-foreign (string (type my-string-type))
1997 (foreign-string-alloc string :encoding (string-type-encoding type)))
2001 From now on, whenever an object is passed as a @code{my-string} to a
2002 foreign function, this method will be invoked to convert the Lisp
2003 value. To perform the inverse operation, which is needed for functions
2004 that return a @code{my-string}, specialize the
2005 @code{translate-from-foreign} generic function in the same manner:
2008 ;;; @lispcmt{Define a method that converts C strings to Lisp strings.}
2009 (defmethod translate-from-foreign (pointer (type my-string-type))
2010 (foreign-string-to-lisp pointer :encoding (string-type-encoding type)))
2014 When a @code{translate-to-foreign} method requires allocation of
2015 foreign memory, you must also define a @code{free-translated-object}
2016 method to free the memory once the foreign object is no longer needed,
2017 otherwise you'll be faced with memory leaks. This generic function is
2018 called automatically by @cffi{} when passing objects to foreign
2019 functions. Let's do that:
2022 ;;; @lispcmt{Free strings allocated by translate-to-foreign.}
2023 (defmethod free-translated-object (pointer (type my-string-type) param)
2024 (declare (ignore param))
2025 (foreign-string-free pointer))
2029 In this specific example, we don't need the @var{param} argument, so
2030 we ignore it. See @ref{free-translated-object}, for an explanation of
2031 its purpose and how you can use it.
2033 A type translator does not necessarily need to convert the value. For
2034 example, one could define a typedef for @code{:pointer} that ensures,
2035 in the @code{translate-to-foreign} method, that the value is not a
2036 null pointer, signalling an error if a null pointer is passed. This
2037 would prevent some pointer errors when calling foreign functions that
2038 cannot handle null pointers.
2040 @strong{Please note:} these methods are meant as extensible hooks
2041 only, and you should not call them directly. Use
2042 @code{convert-to-foreign}, @code{convert-from-foreign} and
2043 @code{free-converted-object} instead.
2045 @xref{Tutorial-Types,, Defining new types}, for another example of
2048 @node Optimizing Type Translators
2049 @section Optimizing Type Translators
2051 @cindex type translators, optimizing
2052 @cindex compiler macros for type translation
2053 @cindex defining type-translation compiler macros
2054 Being based on generic functions, the type translation mechanism
2055 described above can add a bit of overhead. This is usually not
2056 significant, but we nevertheless provide a way of getting rid of the
2057 overhead for the cases where it matters.
2059 A good way to understand this issue is to look at the code generated
2060 by @code{defcfun}. Consider the following example using the previously
2061 defined @code{my-string} type:
2064 CFFI> (macroexpand-1 '(defcfun foo my-string (x my-string)))
2065 ;; (simplified, downcased, etc...)
2067 (multiple-value-bind (#:G2019 #:PARAM3149)
2068 (translate-to-foreign x #<MY-STRING-TYPE @{11ED5A79@}>)
2070 (translate-from-foreign
2071 (foreign-funcall "foo" :pointer #:G2019 :pointer)
2072 #<MY-STRING-TYPE @{11ED5659@}>)
2073 (free-translated-object #:G2019 #<MY-STRING-TYPE @{11ED51A79@}>
2078 In order to get rid of those generic function calls, @cffi{} has
2079 another set of extensible generic functions that provide functionality
2080 similar to @acronym{CL}'s compiler macros:
2081 @code{expand-to-foreign-dyn}, @code{expand-to-foreign} and
2082 @code{expand-from-foreign}. Here's how one could define a
2083 @code{my-boolean} with them:
2086 (define-foreign-type my-boolean-type ()
2089 (:simple-parser my-boolean))
2091 (defmethod expand-to-foreign (value (type my-boolean-type))
2094 (defmethod expand-from-foreign (value (type my-boolean-type))
2095 `(not (zerop ,value)))
2099 And here's what the macroexpansion of a function using this type would
2103 CFFI> (macroexpand-1 '(defcfun bar my-boolean (x my-boolean)))
2104 ;; (simplified, downcased, etc...)
2106 (let ((#:g3182 (if x 1 0)))
2107 (not (zerop (foreign-funcall "bar" :int #:g3182 :int)))))
2111 No generic function overhead.
2113 Let's go back to our @code{my-string} type. The expansion interface
2114 has no equivalent of @code{free-translated-object}; you must instead
2115 define a method on @code{expand-to-foreign-dyn}, the third generic
2116 function in this interface. This is especially useful when you can
2117 allocate something much more efficiently if you know the object has
2118 dynamic extent, as is the case with function calls that don't save the
2119 relevant allocated arguments.
2121 This exactly what we need for the @code{my-string} type:
2124 (defmethod expand-from-foreign (form (type my-string-type))
2125 `(foreign-string-to-lisp ,form))
2127 (defmethod expand-to-foreign-dyn (value var body (type my-string-type))
2128 (let ((encoding (string-type-encoding type)))
2129 `(with-foreign-string (,var ,value :encoding ',encoding)
2134 So let's look at the macro expansion:
2137 CFFI> (macroexpand-1 '(defcfun foo my-string (x my-string)))
2138 ;; (simplified, downcased, etc...)
2140 (with-foreign-string (#:G2021 X :encoding ':utf-8)
2141 (foreign-string-to-lisp
2142 (foreign-funcall "foo" :pointer #:g2021 :pointer))))
2146 Again, no generic function overhead.
2148 @subheading Other details
2150 To short-circuit expansion and use the @code{translate-*} functions
2151 instead, simply call the next method. Return its result in cases
2152 where your method cannot generate an appropriate replacement for it.
2153 This analogous to the @code{&whole form} mechanism compiler macros
2156 The @code{expand-*} methods have precedence over their
2157 @code{translate-*} counterparts and are guaranteed to be used in
2158 @code{defcfun}, @code{foreign-funcall}, @code{defcvar} and
2159 @code{defcallback}. If you define a method on each of the
2160 @code{expand-*} generic functions, you are guaranteed to have full
2161 control over the expressions generated for type translation in these
2164 They may or may not be used in other @cffi{} operators that need to
2165 translate between Lisp and C data; you may only assume that
2166 @code{expand-*} methods will probably only be called during Lisp
2169 @code{expand-to-foreign-dyn} has precedence over
2170 @code{expand-to-foreign} and is only used in @code{defcfun} and
2171 @code{foreign-funcall}, only making sense in those contexts.
2173 @strong{Important note:} this set of generic functions is called at
2174 macroexpansion time. Methods are defined when loaded or evaluated,
2175 not compiled. You are responsible for ensuring that your
2176 @code{expand-*} methods are defined when the @code{foreign-funcall} or
2177 other forms that use them are compiled. One way to do this is to put
2178 the method definitions earlier in the file and inside an appropriate
2179 @code{eval-when} form; another way is to always load a separate Lisp
2180 or @acronym{FASL} file containing your @code{expand-*} definitions
2181 before compiling files with forms that ought to use them. Otherwise,
2182 they will not be found and the runtime translators will be used
2185 @node Foreign Structure Types
2186 @section Foreign Structure Types
2188 For more involved C types than simple aliases to built-in types, such
2189 as you can make with @code{defctype}, @cffi{} allows declaration of
2190 structures and unions with @code{defcstruct} and @code{defcunion}.
2192 For example, consider this fictional C structure declaration holding
2193 some personal information:
2203 The equivalent @code{defcstruct} form follows:
2211 Please note that this interface is only for those that must know about
2212 the values contained in a relevant struct. If the library you are
2213 interfacing returns an opaque pointer that needs only be passed to
2214 other C library functions, by all means just use @code{:pointer} or a
2215 type-safe definition munged together with @code{defctype} and type
2218 @ref{defcstruct} for more details.
2220 @node Allocating Foreign Objects
2221 @section Allocating Foreign Objects
2223 @c I moved this because I moved with-foreign-object to the Pointers
2224 @c chapter, where foreign-alloc is.
2226 @xref{Allocating Foreign Memory}.
2229 @c ===================================================================
2230 @c CONVERT-FROM-FOREIGN
2232 @node convert-from-foreign
2233 @unnumberedsec convert-from-foreign
2235 @Function{convert-from-foreign foreign-value type @res{} value}
2237 @subheading Arguments and Values
2241 The primitive C value as returned from a primitive foreign function or
2242 from @code{convert-to-foreign}.
2245 A @cffi{} type specifier.
2248 The Lisp value translated from @var{foreign-value}.
2251 @subheading Description
2253 This is an external interface to the type translation facility. In
2254 the implementation, all foreign functions are ultimately defined as
2255 type translation wrappers around primitive foreign function
2258 This function is available mostly for inspection of the type
2259 translation process, and possibly optimization of special cases of
2260 your foreign function calls.
2262 Its behavior is better described under @code{translate-from-foreign}'s
2265 @subheading Examples
2268 CFFI-USER> (convert-to-foreign "a boat" :string)
2269 @result{} #<FOREIGN-ADDRESS #x097ACDC0>
2271 CFFI-USER> (convert-from-foreign * :string)
2275 @subheading See Also
2276 @seealso{convert-to-foreign} @*
2277 @seealso{free-converted-object} @*
2278 @seealso{translate-from-foreign}
2281 @c ===================================================================
2282 @c CONVERT-TO-FOREIGN
2284 @node convert-to-foreign
2285 @unnumberedsec convert-to-foreign
2287 @Function{convert-to-foreign value type @res{} foreign-value, alloc-params}
2289 @subheading Arguments and Values
2293 The Lisp object to be translated to a foreign object.
2296 A @cffi{} type specifier.
2299 The primitive C value, ready to be passed to a primitive foreign
2303 Something of a translation state; you must pass it to
2304 @code{free-converted-object} along with the foreign value for that to
2308 @subheading Description
2310 This is an external interface to the type translation facility. In
2311 the implementation, all foreign functions are ultimately defined as
2312 type translation wrappers around primitive foreign function
2315 This function is available mostly for inspection of the type
2316 translation process, and possibly optimization of special cases of
2317 your foreign function calls.
2319 Its behavior is better described under @code{translate-to-foreign}'s
2322 @subheading Examples
2325 CFFI-USER> (convert-to-foreign t :boolean)
2328 CFFI-USER> (convert-to-foreign "hello, world" :string)
2329 @result{} #<FOREIGN-ADDRESS #x097C5F80>
2331 CFFI-USER> (code-char (mem-aref * :char 5))
2335 @subheading See Also
2336 @seealso{convert-from-foreign} @*
2337 @seealso{free-converted-object} @*
2338 @seealso{translate-to-foreign}
2341 @c ===================================================================
2345 @unnumberedsec defbitfield
2347 @Macro{defbitfield name-and-options &body masks}
2349 masks ::= [docstring] @{ (symbol value) @}* @*
2350 name-and-options ::= name | (name &optional (base-type :int))
2352 @subheading Arguments and Values
2356 The name of the new bitfield type.
2359 A documentation string, ignored.
2362 A symbol denoting a foreign type.
2368 An integer representing a bitmask.
2371 @subheading Description
2372 The @code{defbitfield} macro is used to define foreign types that map
2373 lists of symbols to integer values.
2375 If @var{value} is omitted, it will be computed as follows: find the
2376 greatest @var{value} previously used, including those so computed,
2377 with only a single 1-bit in its binary representation (that is, powers
2378 of two), and left-shift it by one. This rule guarantees that a
2379 computed @var{value} cannot clash with previous values, but may clash
2380 with future explicitly specified values.
2382 Symbol lists will be automatically converted to values and vice versa
2383 when being passed as arguments to or returned from foreign functions,
2384 respectively. The same applies to any other situations where an object
2385 of a bitfield type is expected.
2387 Types defined with @code{defbitfield} canonicalize to @var{base-type}
2388 which is @code{:int} by default.
2390 @subheading Examples
2392 (defbitfield open-flags
2394 :wronly ;@lispcmt{#x0001}
2395 :rdwr ;@lispcmt{@dots{}}
2399 ;; @lispcmt{etc@dots{}}
2401 CFFI> (foreign-bitfield-symbols 'open-flags #b1101)
2402 @result{} (:RDONLY :WRONLY :NONBLOCK :APPEND)
2404 CFFI> (foreign-bitfield-value 'open-flags '(:rdwr :creat))
2405 @result{} 514 ; #x0202
2407 (defcfun ("open" unix-open) :int
2410 (mode :uint16)) ; unportable
2412 CFFI> (unix-open "/tmp/foo" '(:wronly :creat) #o644)
2415 ;;; @lispcmt{Consider also the following lispier wrapper around open()}
2416 (defun lispier-open (path mode &rest flags)
2417 (unix-open path flags mode))
2420 @subheading See Also
2421 @seealso{foreign-bitfield-value} @*
2422 @seealso{foreign-bitfield-symbols}
2425 @c ===================================================================
2429 @unnumberedsec defcstruct
2431 @Macro{defcstruct name-and-options &body doc-and-slots @res{} name}
2433 name-and-options ::= structure-name | (structure-name &key size)
2435 doc-and-slots ::= [docstring] @{ (slot-name slot-type &key count offset) @}*
2437 @subheading Arguments and Values
2440 @item structure-name
2441 The name of new structure type.
2444 A documentation string, ignored.
2447 A symbol naming the slot. It must be unique among slot names in this
2451 Use this option to override the size (in bytes) of the struct.
2454 The type specifier for the slot.
2457 Used to declare an array of size @var{count} inside the
2458 structure. Defaults to @code{1} as such an array and a single element
2459 are semantically equivalent.
2462 Overrides the slot's offset. The next slot's offset is calculated
2466 @subheading Description
2467 This defines a new @cffi{} aggregate type akin to C @code{struct}s.
2468 In other words, it specifies that foreign objects of the type
2469 @var{structure-name} are groups of different pieces of data, or
2470 ``slots'', of the @var{slot-type}s, distinguished from each other by
2471 the @var{slot-name}s. Each structure is located in memory at a
2472 position, and the slots are allocated sequentially beginning at that
2473 point in memory (with some padding allowances as defined by the C
2474 @acronym{ABI}, unless otherwise requested by specifying an
2475 @var{offset} from the beginning of the structure (offset 0).
2477 In other words, it is isomorphic to the C @code{struct}, giving
2478 several extra features.
2480 There are two kinds of slots, for the two kinds of @cffi{} types:
2484 Contain a single instance of a type that canonicalizes to a built-in
2485 type, such as @code{:long} or @code{:pointer}. Used for simple
2489 Contain an embedded structure or union, or an array of objects. Used
2490 for aggregate @cffi{} types.
2493 The use of @acronym{CLOS} terminology for the structure-related
2494 features is intentional; structure definitions are very much like
2495 classes with (far) fewer features.
2497 @subheading Examples
2500 "Pointer structure."
2504 CFFI> (with-foreign-object (ptr 'point)
2505 ;; @lispcmt{Initialize the slots}
2506 (setf (foreign-slot-value ptr 'point 'x) 42
2507 (foreign-slot-value ptr 'point 'y) 42)
2508 ;; @lispcmt{Return a list with the coordinates}
2509 (with-foreign-slots ((x y) ptr point)
2515 ;; @lispcmt{Using the :size and :offset options to define a partial structure.}
2516 ;; @lispcmt{(this is useful when you are interested in only a few slots}
2517 ;; @lispcmt{of a big foreign structure)}
2519 (defcstruct (foo :size 32)
2520 "Some struct with 32 bytes."
2521 ; @lispcmt{<16 bytes we don't care about>}
2522 (x :int :offset 16) ; @lispcmt{an int at offset 16}
2523 (y :int) ; @lispcmt{another int at offset 16+sizeof(int)}
2524 ; @lispcmt{<a couple more bytes we don't care about>}
2525 (z :char :offset 24)) ; @lispcmt{a char at offset 24}
2526 ; @lispcmt{<7 more bytes ignored (since size is 32)>}
2528 CFFI> (foreign-type-size 'foo)
2533 ;;; @lispcmt{Using :count to define arrays inside of a struct.}
2534 (defcstruct video_tuner
2535 (name :char :count 32))
2538 @subheading See Also
2539 @seealso{foreign-slot-pointer} @*
2540 @seealso{foreign-slot-value} @*
2541 @seealso{with-foreign-slots}
2544 @c ===================================================================
2548 @unnumberedsec defcunion
2550 @Macro{defcunion name &body doc-and-slots @res{} name}
2552 doc-and-slots ::= [docstring] @{ (slot-name slot-type &key count) @}*
2554 @subheading Arguments and Values
2558 The name of new union type.
2561 A documentation string, ignored.
2564 A symbol naming the slot.
2567 The type specifier for the slot.
2570 Used to declare an array of size @var{count} inside the
2574 @subheading Description
2575 A union is a structure in which all slots have an offset of zero. It
2576 is isomorphic to the C @code{union}. Therefore, you should use the
2577 usual foreign structure operations for accessing a union's slots.
2579 @subheading Examples
2581 (defcunion uint32-bytes
2582 (int-value :unsigned-int)
2583 (bytes :unsigned-char :count 4))
2586 @subheading See Also
2587 @seealso{foreign-slot-pointer} @*
2588 @seealso{foreign-slot-value}
2591 @c ===================================================================
2595 @unnumberedsec defctype
2597 @Macro{defctype name base-type &optional documentation}
2599 @subheading Arguments and Values
2603 The name of the new foreign type.
2606 A symbol or a list defining the new type.
2609 A documentation string, currently ignored.
2612 @subheading Description
2613 The @code{defctype} macro provides a mechanism similar to C's
2614 @code{typedef} to define new types. The new type inherits
2615 @var{base-type}'s translators, if any. There is no way to define
2616 translations for types for types defined with @code{defctype}. For
2617 that, you should use @ref{define-foreign-type}.
2619 @subheading Examples
2621 (defctype my-string :string
2622 "My own string type.")
2624 (defctype long-bools (:boolean :long)
2625 "Booleans that map to C longs.")
2628 @subheading See Also
2629 @seealso{define-foreign-type}
2632 @c ===================================================================
2636 @unnumberedsec defcenum
2638 @Macro{defcenum name-and-options &body enum-list}
2640 enum-list ::= [docstring] @{ keyword | (keyword value) @}*
2641 name-and-options ::= name | (name &optional (base-type :int))
2643 @subheading Arguments and Values
2647 The name of the new enum type.
2650 A documentation string, ignored.
2653 A symbol denoting a foreign type.
2659 An index value for a keyword.
2662 @subheading Description
2663 The @code{defcenum} macro is used to define foreign types that map
2664 keyword symbols to integer values, similar to the C @code{enum} type.
2666 If @var{value} is omitted its value will either be 0, if it's the
2667 first entry, or it it will continue the progression from the last
2670 Keywords will be automatically converted to values and vice-versa when
2671 being passed as arguments to or returned from foreign functions,
2672 respectively. The same applies to any other situations where an object
2673 of an @code{enum} type is expected.
2675 Types defined with @code{defcenum} canonicalize to @var{base-type}
2676 which is @code{:int} by default.
2678 @subheading Examples
2684 CFFI> (foreign-enum-value 'boolean :no)
2694 CFFI> (foreign-enum-keyword 'numbers 2)
2698 @subheading See Also
2699 @seealso{foreign-enum-value} @*
2700 @seealso{foreign-enum-keyword}
2703 @c ===================================================================
2704 @c DEFINE-FOREIGN-TYPE
2706 @node define-foreign-type
2707 @unnumberedsec define-foreign-type
2709 @Macro{define-foreign-type class-name supers slots &rest options @res{} class-name}
2711 options ::= (@code{:actual-type} @var{type}) | @
2712 (@code{:simple-parser} @var{symbol}) | @
2713 @emph{regular defclass option}
2715 @subheading Arguments and Values
2719 A symbol naming the new foreign type class.
2722 A list of symbols naming the super classes.
2725 A list of slot definitions, passed to @code{defclass}.
2728 @subheading Description
2732 The macro @code{define-foreign-type} defines a new class
2733 @var{class-name}. It is a thin wrapper around @code{defclass}. Among
2734 other things, it ensures that @var{class-name} becomes a subclass of
2735 @var{foreign-type}, what you need to know about that is that there's
2736 an initarg @code{:actual-type} which serves the same purpose as
2737 @code{defctype}'s @var{base-type} argument.
2739 @c TODO mention the type translators here
2742 @subheading Examples
2743 Taken from @cffi{}'s @code{:boolean} type definition:
2746 (define-foreign-type :boolean (&optional (base-type :int))
2747 "Boolean type. Maps to an :int by default. Only accepts integer types."
2754 :unsigned-long) base-type)))
2756 CFFI> (canonicalize-foreign-type :boolean)
2758 CFFI> (canonicalize-foreign-type '(:boolean :long))
2760 CFFI> (canonicalize-foreign-type '(:boolean :float))
2761 ;; @lispcmt{@error{} signalled by ECASE.}
2764 @subheading See Also
2765 @seealso{defctype} @*
2766 @seealso{define-parse-method}
2769 @c ===================================================================
2770 @c DEFINE-PARSE-METHOD
2772 @node define-parse-method
2773 @unnumberedsec define-parse-method
2775 @Macro{define-parse-method name lambda-list &body body @res{} name}
2777 @subheading Arguments and Values
2781 A symbol naming the new foreign type.
2784 A lambda list which is the argument list of the new foreign type.
2787 One or more forms that provide a definition of the new foreign type.
2790 @subheading Description
2793 @c TODO: update example. The boolean type is probably a good choice.
2795 @subheading Examples
2796 Taken from @cffi{}'s @code{:boolean} type definition:
2799 (define-foreign-type :boolean (&optional (base-type :int))
2800 "Boolean type. Maps to an :int by default. Only accepts integer types."
2807 :unsigned-long) base-type)))
2809 CFFI> (canonicalize-foreign-type :boolean)
2811 CFFI> (canonicalize-foreign-type '(:boolean :long))
2813 CFFI> (canonicalize-foreign-type '(:boolean :float))
2814 ;; @lispcmt{@error{} signalled by ECASE.}
2817 @subheading See Also
2818 @seealso{define-foreign-type}
2821 @c ===================================================================
2822 @c EXPLAIN-FOREIGN-SLOT-VALUE
2824 @c @node explain-foreign-slot-value
2825 @c @unnumberedsec explain-foreign-slot-value
2826 @c @subheading Syntax
2827 @c @Macro{explain-foreign-slot-value ptr type &rest slot-names}
2829 @c @subheading Arguments and Values
2842 @c @subheading Description
2843 @c This macro translates the slot access that would occur by calling
2844 @c @code{foreign-slot-value} with the same arguments into an equivalent
2845 @c expression in C and prints it to @code{*standard-output*}.
2847 @c @emph{Note: this is not implemented yet.}
2849 @c @subheading Examples
2851 @c CFFI> (explain-foreign-slot-value ptr 'timeval 'tv-secs)
2852 @c @result{} ptr->tv_secs
2854 @c CFFI> (explain-foreign-slot-value emp 'employee 'hire-date 'tv-usecs)
2855 @c @result{} emp->hire_date.tv_usecs
2858 @c @subheading See Also
2861 @c ===================================================================
2862 @c FOREIGN-BITFIELD-SYMBOLS
2864 @node foreign-bitfield-symbols
2865 @unnumberedsec foreign-bitfield-symbols
2867 @Function{foreign-bitfield-symbols type value @res{} symbols}
2869 @subheading Arguments and Values
2879 A potentially shared list of symbols.
2883 @subheading Description
2884 The function @code{foreign-bitfield-symbols} returns a possibly shared
2885 list of symbols that correspond to @var{value} in @var{type}.
2887 @subheading Examples
2894 CFFI> (foreign-bitfield-symbols 'boolean #b101)
2895 @result{} (FLAG-A FLAG-C)
2898 @subheading See Also
2899 @seealso{defbitfield} @*
2900 @seealso{foreign-bitfield-value}
2903 @c ===================================================================
2904 @c FOREIGN-BITFIELD-VALUE
2906 @node foreign-bitfield-value
2907 @unnumberedsec foreign-bitfield-value
2909 @Function{foreign-bitfield-value type symbols @res{} value}
2911 @subheading Arguments and Values
2915 A @code{bitfield} type.
2924 @subheading Description
2925 The function @code{foreign-bitfield-value} returns the @var{value} that
2926 corresponds to the symbols in the @var{symbols} list.
2928 @subheading Examples
2935 CFFI> (foreign-bitfield-value 'flags '(flag-a flag-c))
2939 @subheading See Also
2940 @seealso{defbitfield} @*
2941 @seealso{foreign-bitfield-symbols}
2944 @c ===================================================================
2945 @c FOREIGN-ENUM-KEYWORD
2947 @node foreign-enum-keyword
2948 @unnumberedsec foreign-enum-keyword
2950 @Function{foreign-enum-keyword type value &key errorp @res{} keyword}
2952 @subheading Arguments and Values
2956 An @code{enum} type.
2962 If true (the default), signal an error if @var{value} is not defined
2963 in @var{type}. If false, @code{foreign-enum-keyword} returns
2970 @subheading Description
2971 The function @code{foreign-enum-keyword} returns the keyword symbol
2972 that corresponds to @var{value} in @var{type}.
2974 An error is signaled if @var{type} doesn't contain such @var{value}
2975 and @var{errorp} is true.
2977 @subheading Examples
2983 CFFI> (foreign-enum-keyword 'boolean 1)
2987 @subheading See Also
2988 @seealso{defcenum} @*
2989 @seealso{foreign-enum-value}
2992 @c ===================================================================
2993 @c FOREIGN-ENUM-VALUE
2995 @node foreign-enum-value
2996 @unnumberedsec foreign-enum-value
2998 @Function{foreign-enum-value type keyword &key errorp @res{} value}
3000 @subheading Arguments and Values
3004 An @code{enum} type.
3010 If true (the default), signal an error if @var{keyword} is not
3011 defined in @var{type}. If false, @code{foreign-enum-value} returns
3018 @subheading Description
3019 The function @code{foreign-enum-value} returns the @var{value} that
3020 corresponds to @var{keyword} in @var{type}.
3022 An error is signaled if @var{type} doesn't contain such
3023 @var{keyword}, and @var{errorp} is true.
3025 @subheading Examples
3031 CFFI> (foreign-enum-value 'boolean :yes)
3035 @subheading See Also
3036 @seealso{defcenum} @*
3037 @seealso{foreign-enum-keyword}
3040 @c ===================================================================
3041 @c FOREIGN-SLOT-NAMES
3043 @node foreign-slot-names
3044 @unnumberedsec foreign-slot-names
3046 @Function{foreign-slot-names type @res{} names}
3048 @subheading Arguments and Values
3052 A foreign struct type.
3058 @subheading Description
3059 The function @code{foreign-slot-names} returns a potentially shared
3060 list of slot @var{names} for the given structure @var{type}. This list
3061 has no particular order.
3063 @subheading Examples
3069 CFFI> (foreign-slot-names 'timeval)
3070 @result{} (TV-SECS TV-USECS)
3073 @subheading See Also
3074 @seealso{defcstruct} @*
3075 @seealso{foreign-slot-offset} @*
3076 @seealso{foreign-slot-value} @*
3077 @seealso{foreign-slot-pointer}
3080 @c ===================================================================
3081 @c FOREIGN-SLOT-OFFSET
3083 @node foreign-slot-offset
3084 @unnumberedsec foreign-slot-offset
3086 @Function{foreign-slot-offset type slot-name @res{} offset}
3088 @subheading Arguments and Values
3092 A foreign struct type.
3101 @subheading Description
3102 The function @code{foreign-slot-offset} returns the @var{offset} in
3103 bytes of a slot in a foreign struct type.
3105 @subheading Examples
3111 CFFI> (foreign-slot-offset 'timeval 'tv-secs)
3113 CFFI> (foreign-slot-offset 'timeval 'tv-usecs)
3117 @subheading See Also
3118 @seealso{defcstruct} @*
3119 @seealso{foreign-slot-names} @*
3120 @seealso{foreign-slot-pointer} @*
3121 @seealso{foreign-slot-value}
3124 @c ===================================================================
3125 @c FOREIGN-SLOT-POINTER
3127 @node foreign-slot-pointer
3128 @unnumberedsec foreign-slot-pointer
3130 @Function{foreign-slot-pointer ptr type slot-name @res{} pointer}
3132 @subheading Arguments and Values
3136 A pointer to a structure.
3139 A foreign structure type.
3142 A slot name in the @var{type}.
3145 A pointer to the slot @var{slot-name}.
3148 @subheading Description
3149 Returns a pointer to the location of the slot @var{slot-name} in a
3150 foreign object of type @var{type} at @var{ptr}. The returned pointer
3151 points inside the structure. Both the pointer and the memory it points
3152 to have the same extent as @var{ptr}.
3154 For aggregate slots, this is the same value returned by
3155 @code{foreign-slot-value}.
3157 @subheading Examples
3160 "Pointer structure."
3164 CFFI> (with-foreign-object (ptr 'point)
3165 (foreign-slot-pointer ptr 'point 'x))
3166 @result{} #<FOREIGN-ADDRESS #xBFFF6E60>
3167 ;; @lispcmt{Note: the exact pointer representation varies from lisp to lisp.}
3170 @subheading See Also
3171 @seealso{defcstruct} @*
3172 @seealso{foreign-slot-value} @*
3173 @seealso{foreign-slot-names} @*
3174 @seealso{foreign-slot-offset}
3177 @c ===================================================================
3178 @c FOREIGN-SLOT-VALUE
3180 @node foreign-slot-value
3181 @unnumberedsec foreign-slot-value
3183 @Accessor{foreign-slot-value ptr type slot-name @res{} object}
3185 @subheading Arguments and Values
3189 A pointer to a structure.
3192 A foreign structure type.
3195 A symbol naming a slot in the structure type.
3198 The object contained in the slot specified by @var{slot-name}.
3201 @subheading Description
3202 For simple slots, @code{foreign-slot-value} returns the value of the
3203 object, such as a Lisp integer or pointer. In C, this would be
3204 expressed as @code{ptr->slot}.
3206 For aggregate slots, a pointer inside the structure to the beginning
3207 of the slot's data is returned. In C, this would be expressed as
3208 @code{&ptr->slot}. This pointer and the memory it points to have the
3209 same extent as @var{ptr}.
3211 There are compiler macros for @code{foreign-slot-value} and its
3212 @code{setf} expansion that open code the memory access when
3213 @var{type} and @var{slot-names} are constant at compile-time.
3215 @subheading Examples
3218 "Pointer structure."
3222 CFFI> (with-foreign-object (ptr 'point)
3223 ;; @lispcmt{Initialize the slots}
3224 (setf (foreign-slot-value ptr 'point 'x) 42
3225 (foreign-slot-value ptr 'point 'y) 42)
3226 ;; @lispcmt{Return a list with the coordinates}
3227 (with-foreign-slots ((x y) ptr point)
3232 @subheading See Also
3233 @seealso{defcstruct} @*
3234 @seealso{foreign-slot-names} @*
3235 @seealso{foreign-slot-offset} @*
3236 @seealso{foreign-slot-pointer} @*
3237 @seealso{with-foreign-slots}
3240 @c ===================================================================
3241 @c FOREIGN-TYPE-ALIGNMENT
3243 @node foreign-type-alignment
3244 @unnumberedsec foreign-type-alignment
3246 @c XXX: This is actually a generic function.
3247 @Function{foreign-type-alignment type @res{} alignment}
3249 @subheading Arguments and Values
3259 @subheading Description
3260 The function @code{foreign-type-alignment} returns the
3261 @var{alignment} of @var{type} in bytes.
3263 @subheading Examples
3265 CFFI> (foreign-type-alignment :char)
3267 CFFI> (foreign-type-alignment :short)
3269 CFFI> (foreign-type-alignment :int)
3277 CFFI> (foreign-type-alignment 'foo)
3281 @subheading See Also
3282 @seealso{foreign-type-size}
3285 @c ===================================================================
3286 @c FOREIGN-TYPE-SIZE
3288 @node foreign-type-size
3289 @unnumberedsec foreign-type-size
3291 @c XXX: this is actually a generic function.
3292 @Function{foreign-type-size type @res{} size}
3294 @subheading Arguments and Values
3304 @subheading Description
3305 The function @code{foreign-type-size} return the @var{size} of
3306 @var{type} in bytes. This includes any padding within and following
3307 the in-memory representation as needed to create an array of
3310 @subheading Examples
3316 CFFI> (foreign-type-size :double)
3318 CFFI> (foreign-type-size :char)
3320 CFFI> (foreign-type-size 'foo)
3324 @subheading See Also
3325 @seealso{foreign-type-alignment}
3328 @c ===================================================================
3329 @c FREE-CONVERTED-OBJECT
3331 @node free-converted-object
3332 @unnumberedsec free-converted-object
3334 @Function{free-converted-object foreign-value type params}
3336 @subheading Arguments and Values
3340 The C object to be freed.
3343 A @cffi{} type specifier.
3346 The state returned as the second value from @code{convert-to-foreign};
3347 used to implement the third argument to @code{free-translated-object}.
3350 @subheading Description
3352 The return value is unspecified.
3354 This is an external interface to the type translation facility. In
3355 the implementation, all foreign functions are ultimately defined as
3356 type translation wrappers around primitive foreign function
3359 This function is available mostly for inspection of the type
3360 translation process, and possibly optimization of special cases of
3361 your foreign function calls.
3363 Its behavior is better described under @code{free-translated-object}'s
3366 @subheading Examples
3369 CFFI-USER> (convert-to-foreign "a boat" :string)
3370 @result{} #<FOREIGN-ADDRESS #x097ACDC0>
3372 CFFI-USER> (free-converted-object * :string '(t))
3376 @subheading See Also
3377 @seealso{convert-from-foreign} @*
3378 @seealso{convert-to-foreign} @*
3379 @seealso{free-translated-object}
3382 @c ===================================================================
3383 @c FREE-TRANSLATED-OBJECT
3387 @node free-translated-object
3388 @unnumberedsec free-translated-object
3390 @GenericFunction{free-translated-object value type-name param}
3392 @subheading Arguments and Values
3396 The foreign value returned by @code{translate-to-foreign}.
3399 A symbol naming a foreign type defined by @code{defctype}.
3402 The second value, if any, returned by @code{translate-to-foreign}.
3405 @subheading Description
3406 This generic function may be specialized by user code to perform
3407 automatic deallocation of foreign objects as they are passed to C
3410 Any methods defined on this generic function must EQL-specialize the
3411 @var{type-name} parameter on a symbol defined as a foreign type by
3412 the @code{defctype} macro.
3414 @subheading See Also
3415 @seealso{Foreign Type Translators} @*
3416 @seealso{translate-to-foreign}
3419 @c ===================================================================
3420 @c TRANSLATE-FROM-FOREIGN
3424 @node translate-from-foreign
3425 @unnumberedsec translate-from-foreign
3427 @GenericFunction{translate-from-foreign foreign-value type-name @
3430 @subheading Arguments and Values
3434 The foreign value to convert to a Lisp object.
3437 A symbol naming a foreign type defined by @code{defctype}.
3440 The lisp value to pass in place of @code{foreign-value} to Lisp code.
3443 @subheading Description
3444 This generic function is invoked by @cffi{} to convert a foreign value to
3445 a Lisp value, such as when returning from a foreign function, passing
3446 arguments to a callback function, or accessing a foreign variable.
3448 To extend the @cffi{} type system by performing custom translations, this
3449 method may be specialized by @sc{eql}-specializing @code{type-name} on a
3450 symbol naming a foreign type defined with @code{defctype}. This
3451 method should return the appropriate Lisp value to use in place of the
3454 The results are undefined if the @code{type-name} parameter is
3455 specialized in any way except an @sc{eql} specializer on a foreign type
3456 defined with @code{defctype}. Specifically, translations may not be
3457 defined for built-in types.
3459 @subheading See Also
3460 @seealso{Foreign Type Translators} @*
3461 @seealso{translate-to-foreign} @*
3462 @seealso{free-translated-object}
3465 @c ===================================================================
3466 @c TRANSLATE-TO-FOREIGN
3470 @node translate-to-foreign
3471 @unnumberedsec translate-to-foreign
3473 @GenericFunction{translate-to-foreign lisp-value type-name @
3474 @res{} foreign-value, alloc-param}
3476 @subheading Arguments and Values
3480 The Lisp value to convert to foreign representation.
3483 A symbol naming a foreign type defined by @code{defctype}.
3486 The foreign value to pass in place of @code{lisp-value} to foreign code.
3489 If present, this value will be passed to
3490 @code{free-translated-object}.
3493 @subheading Description
3494 This generic function is invoked by @cffi{} to convert a Lisp value to a
3495 foreign value, such as when passing arguments to a foreign function,
3496 returning a value from a callback, or setting a foreign variable. A
3497 ``foreign value'' is one appropriate for passing to the next-lowest
3498 translator, including the low-level translators that are ultimately
3499 invoked invisibly with @cffi{}.
3501 To extend the @cffi{} type system by performing custom translations, this
3502 method may be specialized by @sc{eql}-specializing @code{type-name} on a
3503 symbol naming a foreign type defined with @code{defctype}. This
3504 method should return the appropriate foreign value to use in place of
3507 In cases where @cffi{} can determine the lifetime of the foreign object
3508 returned by this method, it will invoke @code{free-translated-object}
3509 on the foreign object at the appropriate time. If
3510 @code{translate-to-foreign} returns a second value, it will be passed
3511 as the @code{param} argument to @code{free-translated-object}. This
3512 can be used to establish communication between the allocation and
3513 deallocation methods.
3515 The results are undefined if the @code{type-name} parameter is
3516 specialized in any way except an @sc{eql} specializer on a foreign type
3517 defined with @code{defctype}. Specifically, translations may not be
3518 defined for built-in types.
3520 @subheading See Also
3521 @seealso{Foreign Type Translators} @*
3522 @seealso{translate-from-foreign} @*
3523 @seealso{free-translated-object}
3526 @c ===================================================================
3527 @c WITH-FOREIGN-SLOTS
3529 @node with-foreign-slots
3530 @unnumberedsec with-foreign-slots
3532 @Macro{with-foreign-slots (vars ptr type) &body body}
3534 @subheading Arguments and Values
3541 A foreign pointer to a structure.
3547 A list of forms to be executed.
3550 @subheading Description
3551 The @code{with-foreign-slots} macro creates local symbol macros for
3552 each var in @var{vars} to reference foreign slots in @var{ptr} of
3553 @var{type}. It is similar to Common Lisp's @code{with-slots} macro.
3555 @subheading Examples
3570 CFFI> (with-foreign-object (time :int)
3571 (setf (mem-ref time :int)
3572 (foreign-funcall "time" :pointer (null-pointer) :int))
3573 (foreign-funcall "gmtime" :pointer time tm))
3574 @result{} #<A Mac Pointer #x102A30>
3575 CFFI> (with-foreign-slots ((sec min hour mday mon year) * tm)
3576 (format nil "~A:~A:~A, ~A/~A/~A"
3577 hour min sec (+ 1900 year) mon mday))
3578 @result{} "7:22:47, 2005/8/2"
3581 @subheading See Also
3582 @seealso{defcstruct} @*
3583 @seealso{defcunion} @*
3584 @seealso{foreign-slot-value}
3587 @c ===================================================================
3588 @c CHAPTER: Pointers
3593 All C data in @cffi{} is referenced through pointers. This includes
3594 defined C variables that hold immediate values, and integers.
3596 To see why this is, consider the case of the C integer. It is not
3597 only an arbitrary representation for an integer, congruent to Lisp's
3598 fixnums; the C integer has a specific bit pattern in memory defined by
3599 the C @acronym{ABI}. Lisp has no such constraint on its fixnums;
3600 therefore, it only makes sense to think of fixnums as C integers if
3601 you assume that @cffi{} converts them when necessary, such as when
3602 storing one for use in a C function call, or as the value of a C
3603 variable. This requires defining an area of memory@footnote{The
3604 definition of @dfn{memory} includes the @acronym{CPU} registers.},
3605 represented through an effective address, and storing it there.
3607 Due to this compartmentalization, it only makes sense to manipulate
3608 raw C data in Lisp through pointers to it. For example, while there
3609 may be a Lisp representation of a @code{struct} that is converted to C
3610 at store time, you may only manipulate its raw data through a pointer.
3611 The C compiler does this also, albeit informally.
3614 * Basic Pointer Operations::
3615 * Allocating Foreign Memory::
3616 * Accessing Foreign Memory::
3622 * foreign-symbol-pointer::
3633 * with-foreign-object::
3634 * with-foreign-pointer::
3637 @node Basic Pointer Operations
3638 @section Basic Pointer Operations
3640 Manipulating pointers proper can be accomplished through most of the
3641 other operations defined in the Pointers dictionary, such as
3642 @code{make-pointer}, @code{pointer-address}, and @code{pointer-eq}.
3643 When using them, keep in mind that they merely manipulate the Lisp
3644 representation of pointers, not the values they point to.
3646 @deftp {Lisp Type} foreign-pointer
3647 The pointers' representations differ from implementation to
3648 implementation and have different types. @code{foreign-pointer}
3649 provides a portable type alias to each of these types.
3653 @node Allocating Foreign Memory
3654 @section Allocating Foreign Memory
3656 @cffi{} provides support for stack and heap C memory allocation.
3657 Stack allocation, done with @code{with-foreign-object}, is sometimes
3658 called ``dynamic'' allocation in Lisp, because memory allocated as
3659 such has dynamic extent, much as with @code{let} bindings of special
3662 This should not be confused with what C calls ``dynamic'' allocation,
3663 or that done with @code{malloc} and friends. This sort of heap
3664 allocation is done with @code{foreign-alloc}, creating objects that
3665 exist until freed with @code{foreign-free}.
3668 @node Accessing Foreign Memory
3669 @section Accessing Foreign Memory
3671 When manipulating raw C data, consider that all pointers are pointing
3672 to an array. When you only want one C value, such as a single
3673 @code{struct}, this array only has one such value. It is worthwhile
3674 to remember that everything is an array, though, because this is also
3675 the semantic that C imposes natively.
3677 C values are accessed as the @code{setf}-able places defined by
3678 @code{mem-aref} and @code{mem-ref}. Given a pointer and a @cffi{}
3679 type (@pxref{Foreign Types}), either of these will dereference the
3680 pointer, translate the C data there back to Lisp, and return the
3681 result of said translation, performing the reverse operation when
3682 @code{setf}-ing. To decide which one to use, consider whether you
3683 would use the array index operator @code{[@var{n}]} or the pointer
3684 dereference @code{*} in C; use @code{mem-aref} for array indexing and
3685 @code{mem-ref} for pointer dereferencing.
3688 @c ===================================================================
3692 @unnumberedsec foreign-free
3694 @Function{foreign-free ptr @res{} undefined}
3696 @subheading Arguments and Values
3703 @subheading Description
3704 The @code{foreign-free} function frees a @code{ptr} previously
3705 allocated by @code{foreign-alloc}. The consequences of freeing a given
3706 pointer twice are undefined.
3708 @subheading Examples
3711 CFFI> (foreign-alloc :int)
3712 @result{} #<A Mac Pointer #x1022E0>
3713 CFFI> (foreign-free *)
3717 @subheading See Also
3718 @seealso{foreign-alloc} @*
3719 @seealso{with-foreign-pointer}
3722 @c ===================================================================
3726 @unnumberedsec foreign-alloc
3728 @Function{foreign-alloc type &key initial-element initial-contents (count 1) @
3729 null-terminated-p @res{} pointer}
3731 @subheading Arguments and Values
3737 @item initial-element
3740 @item initial-contents
3744 An integer. Defaults to 1 or the length of @var{initial-contents} if
3747 @item null-terminated-p
3748 A boolean, false by default.
3751 A foreign pointer to the newly allocated memory.
3754 @subheading Description
3755 The @code{foreign-alloc} function allocates enough memory to hold
3756 @var{count} objects of type @var{type} and returns a
3757 @var{pointer}. This memory must be explicitly freed using
3758 @code{foreign-free} once it is no longer needed.
3760 If @var{initial-element} is supplied, it is used to initialize the
3761 @var{count} objects the newly allocated memory holds.
3763 If an @var{initial-contents} sequence is supplied, it must have a
3764 length less than or equal to @var{count} and each of its elements
3765 will be used to initialize the contents of the newly allocated
3768 If @var{count} is omitted and @var{initial-contents} is specified, it
3769 will default to @code{(length @var{initial-contents})}.
3771 @var{initial-element} and @var{initial-contents} are mutually
3774 When @var{null-terminated-p} is true,
3775 @code{(1+ (max @var{count} (length @var{initial-contents})))} elements
3776 are allocated and the last one is set to @code{NULL}. Note that in
3777 this case @var{type} must be a pointer type (ie. a type that
3778 canonicalizes to @code{:pointer}), otherwise an error is signaled.
3780 @subheading Examples
3782 CFFI> (foreign-alloc :char)
3783 @result{} #<A Mac Pointer #x102D80> ; @lispcmt{A pointer to 1 byte of memory.}
3785 CFFI> (foreign-alloc :char :count 20)
3786 @result{} #<A Mac Pointer #x1024A0> ; @lispcmt{A pointer to 20 bytes of memory.}
3788 CFFI> (foreign-alloc :int :initial-element 12)
3789 @result{} #<A Mac Pointer #x1028B0>
3790 CFFI> (mem-ref * :int)
3793 CFFI> (foreign-alloc :int :initial-contents '(1 2 3))
3794 @result{} #<A Mac Pointer #x102950>
3795 CFFI> (loop for i from 0 below 3
3796 collect (mem-aref * :int i))
3799 CFFI> (foreign-alloc :int :initial-contents #(1 2 3))
3800 @result{} #<A Mac Pointer #x102960>
3801 CFFI> (loop for i from 0 below 3
3802 collect (mem-aref * :int i))
3805 ;;; Allocate a char** pointer that points to newly allocated memory
3806 ;;; by the :string type translator for the string "foo".
3807 CFFI> (foreign-alloc :string :initial-element "foo")
3808 @result{} #<A Mac Pointer #x102C40>
3812 ;;; Allocate a null-terminated array of strings.
3813 ;;; (Note: FOREIGN-STRING-TO-LISP returns NIL when passed a null pointer)
3814 CFFI> (foreign-alloc :string
3815 :initial-contents '("foo" "bar" "baz")
3816 :null-terminated-p t)
3817 @result{} #<A Mac Pointer #x102D20>
3818 CFFI> (loop for i from 0 below 4
3819 collect (mem-aref * :string i))
3820 @result{} ("foo" "bar" "baz" NIL)
3823 (foreign-free (mem-aref ** :pointer i)))
3828 @subheading See Also
3829 @seealso{foreign-free} @*
3830 @seealso{with-foreign-object} @*
3831 @seealso{with-foreign-pointer}
3834 @c ===================================================================
3835 @c FOREIGN-SYMBOL-POINTER
3837 @node foreign-symbol-pointer
3838 @unnumberedsec foreign-symbol-pointer
3840 @Function{foreign-symbol-pointer foreign-name &key library @res{} pointer}
3842 @subheading Arguments and Values
3849 A foreign pointer, or @code{nil}.
3852 A Lisp symbol or an instance of @code{foreign-library}.
3855 @subheading Description
3856 The function @code{foreign-symbol-pointer} will return a foreign
3857 pointer corresponding to the foreign symbol denoted by the string
3858 @var{foreign-name}. If a foreign symbol named @var{foreign-name}
3859 doesn't exist, @code{nil} is returned.
3861 ABI name manglings will be performed on @var{foreign-name} by
3862 @code{foreign-symbol-pointer} if necessary. (eg: adding a leading
3863 underscore on darwin/ppc)
3865 @var{library} should name a foreign library as defined by
3866 @code{define-foreign-library}, @code{:default} (which is the default)
3867 or an instance of @code{foreign-library} as returned by
3868 @code{load-foreign-library}.
3870 @strong{Important note:} do not keep these pointers across saved Lisp
3871 cores as the foreign-library may move across sessions.
3873 @subheading Examples
3876 CFFI> (foreign-symbol-pointer "errno")
3877 @result{} #<A Mac Pointer #xA0008130>
3878 CFFI> (foreign-symbol-pointer "strerror")
3879 @result{} #<A Mac Pointer #x9002D0F8>
3880 CFFI> (foreign-funcall-pointer * () :int (mem-ref ** :int) :string)
3881 @result{} "No such file or directory"
3883 CFFI> (foreign-symbol-pointer "inexistent symbol")
3887 @subheading See Also
3891 @c ===================================================================
3895 @unnumberedsec inc-pointer
3897 @Function{inc-pointer pointer offset @res{} new-pointer}
3899 @subheading Arguments and Values
3910 @subheading Description
3911 The function @code{inc-pointer} will return a @var{new-pointer} pointing
3912 @var{offset} bytes past @var{pointer}.
3914 @subheading Examples
3917 CFFI> (foreign-string-alloc "Common Lisp")
3918 @result{} #<A Mac Pointer #x102EA0>
3919 CFFI> (inc-pointer * 7)
3920 @result{} #<A Mac Pointer #x102EA7>
3921 CFFI> (foreign-string-to-lisp *)
3925 @subheading See Also
3926 @seealso{incf-pointer} @*
3927 @seealso{make-pointer} @*
3928 @seealso{pointerp} @*
3929 @seealso{null-pointer} @*
3930 @seealso{null-pointer-p}
3933 @c ===================================================================
3937 @unnumberedsec inc-pointer
3939 @Macro{incf-pointer place &optional (offset 1) @res{} new-pointer}
3941 @subheading Arguments and Values
3945 A @code{setf} place.
3954 @subheading Description
3955 The @code{incf-pointer} macro takes the foreign pointer from
3956 @var{place} and creates a @var{new-pointer} incremented by
3957 @var{offset} bytes and which is stored in @var{place}.
3959 @subheading Examples
3962 CFFI> (defparameter *two-words* (foreign-string-alloc "Common Lisp"))
3963 @result{} *TWO-WORDS*
3964 CFFI> (defparameter *one-word* *two-words*)
3965 @result{} *ONE-WORD*
3966 CFFI> (incf-pointer *one-word* 7)
3967 @result{} #.(SB-SYS:INT-SAP #X00600457)
3968 CFFI> (foreign-string-to-lisp *one-word*)
3970 CFFI> (foreign-string-to-lisp *two-words*)
3971 @result{} "Common Lisp"
3974 @subheading See Also
3975 @seealso{inc-pointer} @*
3976 @seealso{make-pointer} @*
3977 @seealso{pointerp} @*
3978 @seealso{null-pointer} @*
3979 @seealso{null-pointer-p}
3982 @c ===================================================================
3986 @unnumberedsec make-pointer
3988 @Function{make-pointer address @res{} ptr}
3990 @subheading Arguments and Values
4000 @subheading Description
4001 The function @code{make-pointer} will return a foreign pointer
4002 pointing to @var{address}.
4004 @subheading Examples
4007 CFFI> (make-pointer 42)
4008 @result{} #<FOREIGN-ADDRESS #x0000002A>
4011 CFFI> (pointer-address **)
4013 CFFI> (inc-pointer *** -42)
4014 @result{} #<FOREIGN-ADDRESS #x00000000>
4015 CFFI> (null-pointer-p *)
4017 CFFI> (typep ** 'foreign-pointer)
4021 @subheading See Also
4022 @seealso{inc-pointer} @*
4023 @seealso{null-pointer} @*
4024 @seealso{null-pointer-p} @*
4025 @seealso{pointerp} @*
4026 @seealso{pointer-address} @*
4027 @seealso{pointer-eq} @*
4031 @c ===================================================================
4035 @unnumberedsec mem-aref
4037 @Accessor{mem-aref ptr type &optional (index 0)}
4039 (setf (@strong{mem-aref} @emph{ptr type &optional (index 0)) new-value})
4041 @subheading Arguments and Values
4054 A Lisp value compatible with @var{type}.
4057 @subheading Description
4058 The @code{mem-aref} function is similar to @code{mem-ref} but will
4059 automatically calculate the offset from an @var{index}.
4062 (mem-aref ptr type n)
4064 ;; @lispcmt{is identical to:}
4066 (mem-ref ptr type (* n (foreign-type-size type)))
4069 @subheading Examples
4072 CFFI> (with-foreign-string (str "Hello, foreign world!")
4073 (mem-aref str :char 6))
4078 CFFI> (with-foreign-object (array :int 10)
4079 (loop for i below 10
4080 do (setf (mem-aref array :int i) (random 100)))
4081 (loop for i below 10 collect (mem-aref array :int i)))
4082 @result{} (22 7 22 52 69 1 46 93 90 65)
4085 @subheading See Also
4089 @c ===================================================================
4093 @unnumberedsec mem-ref
4095 @Accessor{mem-ref ptr type &optional offset @res{} object}
4097 @subheading Arguments and Values
4107 An integer (in byte units).
4110 The value @var{ptr} points to.
4113 @subheading Description
4114 @subheading Examples
4117 CFFI> (with-foreign-string (ptr "Saluton")
4118 (setf (mem-ref ptr :char 3) (char-code #\a))
4119 (loop for i from 0 below 8
4120 collect (code-char (mem-ref ptr :char i))))
4121 @result{} (#\S #\a #\l #\a #\t #\o #\n #\Null)
4122 CFFI> (setq ptr-to-int (foreign-alloc :int))
4123 @result{} #<A Mac Pointer #x1047D0>
4124 CFFI> (mem-ref ptr-to-int :int)
4126 CFFI> (setf (mem-ref ptr-to-int :int) 1984)
4128 CFFI> (mem-ref ptr-to-int :int)
4132 @subheading See Also
4136 @c ===================================================================
4140 @unnumberedsec null-pointer
4142 @Function{null-pointer @res{} pointer}
4144 @subheading Arguments and Values
4148 A @code{NULL} pointer.
4151 @subheading Description
4152 The function @code{null-pointer} returns a null pointer.
4154 @subheading Examples
4157 CFFI> (null-pointer)
4158 @result{} #<A Null Mac Pointer>
4163 @subheading See Also
4164 @seealso{null-pointer-p} @*
4165 @seealso{make-pointer}
4168 @c ===================================================================
4171 @node null-pointer-p
4172 @unnumberedsec null-pointer-p
4174 @Function{null-pointer-p ptr @res{} boolean}
4176 @subheading Arguments and Values
4180 A foreign pointer that may be a null pointer.
4183 @code{T} or @code{NIL}.
4186 @subheading Description
4187 The function @code{null-pointer-p} returns true if @var{ptr} is a null
4188 pointer and false otherwise.
4190 @subheading Examples
4193 CFFI> (null-pointer-p (null-pointer))
4198 (defun contains-str-p (big little)
4199 (not (null-pointer-p
4200 (foreign-funcall "strstr" :string big :string little :pointer))))
4202 CFFI> (contains-str-p "Popcorns" "corn")
4204 CFFI> (contains-str-p "Popcorns" "salt")
4208 @subheading See Also
4209 @seealso{null-pointer} @*
4213 @c ===================================================================
4217 @unnumberedsec pointerp
4219 @Function{pointerp ptr @res{} boolean}
4221 @subheading Arguments and Values
4225 An object that may be a foreign pointer.
4228 @code{T} or @code{NIL}.
4231 @subheading Description
4232 The function @code{pointerp} returns true if @var{ptr} is a foreign
4233 pointer and false otherwise.
4235 @subheading Implementation-specific Notes
4236 In Allegro CL, foreign pointers are integers thus in this
4237 implementation @code{pointerp} will return true for any ordinary integer.
4239 @subheading Examples
4242 CFFI> (foreign-alloc 32)
4243 @result{} #<A Mac Pointer #x102D20>
4246 CFFI> (pointerp "this is not a pointer")
4250 @subheading See Also
4251 @seealso{make-pointer}
4252 @seealso{null-pointer-p}
4255 @c ===================================================================
4258 @node pointer-address
4259 @unnumberedsec pointer-address
4261 @Function{pointer-address ptr @res{} address}
4263 @subheading Arguments and Values
4273 @subheading Description
4274 The function @code{pointer-address} will return the @var{address} of
4275 a foreign pointer @var{ptr}.
4277 @subheading Examples
4280 CFFI> (pointer-address (null-pointer))
4282 CFFI> (pointer-address (make-pointer 123))
4286 @subheading See Also
4287 @seealso{make-pointer} @*
4288 @seealso{inc-pointer} @*
4289 @seealso{null-pointer} @*
4290 @seealso{null-pointer-p} @*
4291 @seealso{pointerp} @*
4292 @seealso{pointer-eq} @*
4296 @c ===================================================================
4300 @unnumberedsec pointer-eq
4302 @Function{pointer-eq ptr1 ptr2 @res{} boolean}
4304 @subheading Arguments and Values
4312 @code{T} or @code{NIL}.
4315 @subheading Description
4316 The function @code{pointer-eq} returns true if @var{ptr1} and
4317 @var{ptr2} point to the same memory address and false otherwise.
4319 @subheading Implementation-specific Notes
4320 The representation of foreign pointers varies across the various Lisp
4321 implementations as does the behaviour of the built-in Common Lisp
4322 equality predicates. Comparing two pointers that point to the same
4323 address with @code{EQ} Lisps will return true on some Lisps, others require
4324 more general predicates like @code{EQL} or @code{EQUALP} and finally
4325 some will return false using any of these predicates. Therefore, for
4326 portability, you should use @code{POINTER-EQ}.
4328 @subheading Examples
4329 This is an example using @acronym{SBCL}, see the
4330 implementation-specific notes above.
4333 CFFI> (eql (null-pointer) (null-pointer))
4335 CFFI> (pointer-eq (null-pointer) (null-pointer))
4339 @subheading See Also
4340 @seealso{inc-pointer}
4343 @c ===================================================================
4344 @c WITH-FOREIGN-OBJECT
4346 @node with-foreign-object
4347 @unnumberedsec with-foreign-object
4349 @Macro{with-foreign-object (var type &optional count) &body body}
4351 @Macro{with-foreign-objects (bindings) &body body}
4353 bindings ::= @{(var type &optional count)@}*
4355 @subheading Arguments and Values
4362 A foreign type, evaluated.
4368 @subheading Description
4369 The macros @code{with-foreign-object} and @code{with-foreign-objects}
4370 bind @var{var} to a pointer to @var{count} newly allocated objects
4371 of type @var{type} during @var{body}. The buffer has dynamic extent
4372 and may be stack allocated if supported by the host Lisp.
4374 @subheading Examples
4377 CFFI> (with-foreign-object (array :int 10)
4379 (setf (mem-aref array :int i) (random 100)))
4380 (loop for i below 10
4381 collect (mem-aref array :int i)))
4382 @result{} (22 7 22 52 69 1 46 93 90 65)
4385 @subheading See Also
4386 @seealso{foreign-alloc}
4389 @c ===================================================================
4390 @c WITH-FOREIGN-POINTER
4392 @node with-foreign-pointer
4393 @unnumberedsec with-foreign-pointer
4395 @Macro{with-foreign-pointer (var size &optional size-var) &body body}
4397 @subheading Arguments and Values
4408 A list of forms to be executed.
4411 @subheading Description
4412 The @code{with-foreign-pointer} macro, binds @var{var} to @var{size}
4413 bytes of foreign memory during @var{body}. The pointer in @var{var}
4414 is invalid beyond the dynamic extend of @var{body} and may be
4415 stack-allocated if supported by the implementation.
4417 If @var{size-var} is supplied, it will be bound to @var{size} during
4420 @subheading Examples
4423 CFFI> (with-foreign-pointer (string 4 size)
4424 (setf (mem-ref string :char (1- size)) 0)
4425 (lisp-string-to-foreign "Popcorns" string size)
4426 (loop for i from 0 below size
4427 collect (code-char (mem-ref string :char i))))
4428 @result{} (#\P #\o #\p #\Null)
4431 @subheading See Also
4432 @seealso{foreign-alloc} @*
4433 @seealso{foreign-free}
4436 @c ===================================================================
4442 As with many languages, Lisp and C have special support for logical
4443 arrays of characters, going so far as to give them a special name,
4444 ``strings''. In that spirit, @cffi{} provides special support for
4445 translating between Lisp and C strings.
4447 The @code{:string} type and the symbols related below also serve as an
4448 example of what you can do portably with @cffi{}; were it not
4449 included, you could write an equally functional @file{strings.lisp}
4450 without referring to any implementation-specific symbols.
4455 * *default-foreign-encoding*::
4456 * foreign-string-alloc::
4457 * foreign-string-free::
4458 * foreign-string-to-lisp::
4459 * lisp-string-to-foreign::
4460 * with-foreign-string::
4461 * with-foreign-pointer-as-string::
4465 @c ===================================================================
4466 @c *DEFAULT-FOREIGN-ENCODING*
4468 @node *default-foreign-encoding*
4469 @unnumberedsec *default-foreign-encoding*
4472 @Variable{*default-foreign-encoding*}
4474 @subheading Value type
4478 @subheading Initial value
4482 @subheading Description
4484 This special variable holds the default foreign encoding.
4486 @subheading Examples
4489 CFFI> *default-foreign-encoding*
4491 CFFI> (foreign-funcall "strdup" (:string :encoding :utf-16) "foo" :string)
4493 CFFI> (let ((*default-foreign-encoding* :utf-16))
4494 (foreign-funcall "strdup" (:string :encoding :utf-16) "foo" :string))
4498 @subheading See also
4500 @seealso{Other Types} (@code{:string} type) @*
4501 @seealso{foreign-string-alloc} @*
4502 @seealso{foreign-string-to-lisp} @*
4503 @seealso{lisp-string-to-foreign} @*
4504 @seealso{with-foreign-string} @*
4505 @seealso{with-foreign-pointer-as-string}
4508 @c ===================================================================
4509 @c FOREIGN-STRING-ALLOC
4511 @node foreign-string-alloc
4512 @unnumberedsec foreign-string-alloc
4514 @Function{foreign-string-alloc string &key encoding null-terminated-p @
4515 start end @res{} pointer}
4517 @subheading Arguments and Values
4524 Foreign encoding. Defaults to @code{*default-foreign-encoding*}.
4526 @item null-terminated-p
4527 Boolean, defaults to true.
4530 Bounding index designators of @var{string}. 0 and @code{nil}, by
4534 A pointer to the newly allocated foreign string.
4537 @subheading Description
4538 The @code{foreign-string-alloc} function allocates foreign memory
4539 holding a copy of @var{string} converted using the specified
4540 @var{encoding}. @var{Start} specifies an offset into @var{string} and
4541 @var{end} marks the position following the last element of the foreign
4544 This string must be freed with @code{foreign-string-free}.
4546 If @var{null-terminated-p} is false, the string will not be
4549 @subheading Examples
4552 CFFI> (defparameter *str* (foreign-string-alloc "Hello, foreign world!"))
4553 @result{} #<FOREIGN-ADDRESS #x00400560>
4554 CFFI> (foreign-funcall "strlen" :pointer *str* :int)
4558 @subheading See Also
4559 @seealso{foreign-string-free} @*
4560 @seealso{with-foreign-string}
4561 @c @seealso{:string}
4564 @c ===================================================================
4565 @c FOREIGN-STRING-FREE
4567 @node foreign-string-free
4568 @unnumberedsec foreign-string-free
4570 @Function{foreign-string-free pointer}
4572 @subheading Arguments and Values
4576 A pointer to a string allocated by @code{foreign-string-alloc}.
4579 @subheading Description
4580 The @code{foreign-string-free} function frees a foreign string
4581 allocated by @code{foreign-string-alloc}.
4583 @subheading Examples
4585 @subheading See Also
4586 @seealso{foreign-string-alloc}
4589 @c ===================================================================
4590 @c FOREIGN-STRING-TO-LISP
4592 @node foreign-string-to-lisp
4593 @unnumberedsec foreign-string-to-lisp
4595 @Function{foreign-string-to-lisp ptr &optional offset count max-chars @
4596 encoding @res{} string}
4598 @subheading Arguments and Values
4605 An integer greater than or equal to 0. Defauls to 0.
4608 Either @code{nil} (the default), or an integer greater than or equal to 0.
4611 An integer greater than or equal to 0.
4612 @code{(1- array-total-size-limit)}, by default.
4615 Foreign encoding. Defaults to @code{*default-foreign-encoding*}.
4621 @subheading Description
4622 The @code{foreign-string-to-lisp} function converts at most
4623 @var{count} octets from @var{ptr} into a Lisp string, using the
4624 defined @var{encoding}.
4626 If @var{count} is @code{nil} (the default), characters are copied
4627 until @var{max-chars} is reached or a @code{NULL} character is found.
4629 If @var{ptr} is a null pointer, returns @code{nil}.
4631 Note that the @code{:string} type will automatically convert between
4632 Lisp strings and foreign strings.
4634 @subheading Examples
4637 CFFI> (foreign-funcall "getenv" :string "HOME" :pointer)
4638 @result{} #<FOREIGN-ADDRESS #xBFFFFFD5>
4639 CFFI> (foreign-string-to-lisp *)
4640 @result{} "/Users/luis"
4643 @subheading See Also
4644 @seealso{lisp-string-to-foreign} @*
4645 @seealso{foreign-string-alloc}
4646 @c @seealso{:string}
4649 @c ===================================================================
4650 @c LISP-STRING-TO-FOREIGN
4652 @node lisp-string-to-foreign
4653 @unnumberedsec lisp-string-to-foreign
4655 @Function{lisp-string-to-foreign string buffer bufsize &key start @
4656 end offset encoding @res{} buffer}
4658 @subheading Arguments and Values
4671 Bounding index designators of @var{string}. 0 and @code{nil}, by
4675 An integer greater than or equal to 0. Defauls to 0.
4678 Foreign encoding. Defaults to @code{*default-foreign-encoding*}.
4681 @subheading Description
4682 The @code{lisp-string-to-foreign} function copies at most
4683 @var{bufsize}-1 octets from a Lisp @var{string} using the specified
4684 @var{encoding} into @var{buffer}+@var{offset}. The foreign string will
4687 @var{Start} specifies an offset into @var{string} and
4688 @var{end} marks the position following the last element of the foreign
4691 @subheading Examples
4694 CFFI> (with-foreign-pointer-as-string (str 255)
4695 (lisp-string-to-foreign "Hello, foreign world!" str 6))
4699 @subheading See Also
4700 @seealso{foreign-string-alloc} @*
4701 @seealso{foreign-string-to-lisp} @*
4702 @seealso{with-foreign-pointer-as-string}
4705 @c ===================================================================
4706 @c WITH-FOREIGN-STRING
4708 @node with-foreign-string
4709 @unnumberedsec with-foreign-string
4711 @Macro{with-foreign-string (var-or-vars string &rest args) &body body}
4712 @Macro{with-foreign-strings (bindings) &body body}
4714 var-or-vars ::= var | (var &optional octet-size-var)
4715 bindings ::= @{(var-or-vars string &rest args)@}*
4717 @subheading Arguments and Values
4720 @item var, byte-size-var
4727 A list of forms to be executed.
4730 @subheading Description
4731 The @code{with-foreign-string} macro will bind @var{var} to a newly
4732 allocated foreign string containing @var{string}. @var{Args} is passed
4733 to the underlying @code{foreign-string-alloc} call.
4735 If @var{octet-size-var} is provided, it will be bound the length of
4736 foreign string in octets including the null terminator.
4738 @subheading Examples
4741 CFFI> (with-foreign-string (foo "12345")
4742 (foreign-funcall "strlen" :pointer foo :int))
4745 CFFI> (let ((array (coerce #(84 117 114 97 110 103 97)
4746 '(array (unsigned-byte 8)))))
4747 (with-foreign-string (foreign-string array)
4748 (foreign-string-to-lisp foreign-string)))
4752 @subheading See Also
4753 @seealso{foreign-string-alloc} @*
4754 @seealso{with-foreign-pointer-as-string}
4757 @c ===================================================================
4758 @c WITH-FOREIGN-POINTER-AS-STRING
4760 @node with-foreign-pointer-as-string
4761 @unnumberedsec with-foreign-pointer-as-string
4763 @Macro{with-foreign-pointer-as-string (var size &optional size-var @
4764 &rest args) &body body @res{} string}
4766 @subheading Arguments and Values
4776 List of forms to be executed.
4779 @subheading Description
4780 The @code{with-foreign-pointer-as-string} macro is similar to
4781 @code{with-foreign-pointer} except that @var{var} is used as the
4782 returned value of an implicit @code{progn} around @var{body}, after
4783 being converted to a Lisp string using the provided @var{args}.
4785 @subheading Examples
4788 CFFI> (with-foreign-pointer-as-string (str 6 str-size :encoding :ascii)
4789 (lisp-string-to-foreign "Hello, foreign world!" str str-size))
4793 @subheading See Also
4794 @seealso{foreign-string-alloc} @*
4795 @seealso{with-foreign-string}
4798 @c ===================================================================
4799 @c CHAPTER: Variables
4812 @c ===================================================================
4816 @unnumberedsec defcvar
4818 @Macro{defcvar name-and-options type &optional documentation @res{} lisp-name}
4820 @var{name-and-options} ::= name | (name &key read-only (library :default)) @*
4821 @var{name} ::= lisp-name [foreign-name] | foreign-name [lisp-name]
4823 @subheading Arguments and Values
4827 A string denoting a foreign function.
4830 A symbol naming the Lisp function to be created.
4839 A Lisp string; not evaluated.
4842 @subheading Description
4843 The @code{defcvar} macro defines a symbol macro @var{lisp-name} that looks
4844 up @var{foreign-name} and dereferences it acording to @var{type}. It
4845 can also be @code{setf}ed, unless @var{read-only} is true, in which
4846 case an error will be signaled.
4848 When one of @var{lisp-name} or @var{foreign-name} is omitted, the
4849 other is automatically derived using the following rules:
4853 Foreign names are converted to Lisp names by uppercasing, replacing
4854 underscores with hyphens, and wrapping around asterisks.
4856 Lisp names are converted to foreign names by lowercasing, replacing
4857 hyphens with underscores, and removing asterisks, if any.
4860 @subheading Examples
4863 CFFI> (defcvar "errno" :int)
4865 CFFI> (foreign-funcall "strerror" :int *errno* :string)
4866 @result{} "Inappropriate ioctl for device"
4867 CFFI> (setf *errno* 1)
4869 CFFI> (foreign-funcall "strerror" :int *errno* :string)
4870 @result{} "Operation not permitted"
4873 Trying to modify a read-only foreign variable:
4876 CFFI> (defcvar ("errno" +error-number+) :int :read-only t)
4877 @result{} +ERROR-NUMBER+
4878 CFFI> (setf +error-number+ 12)
4879 ;; @lispcmt{@error{} Trying to modify read-only foreign var: +ERROR-NUMBER+.}
4882 @emph{Note that accessing @code{errno} this way won't work with every
4883 C standard library.}
4885 @subheading See Also
4886 @seealso{get-var-pointer}
4889 @c ===================================================================
4892 @node get-var-pointer
4893 @unnumberedsec get-var-pointer
4895 @Function{get-var-pointer symbol @res{} pointer}
4897 @subheading Arguments and Values
4901 A symbol denoting a foreign variable defined with @code{defcvar}.
4907 @subheading Description
4908 The function @code{get-var-pointer} will return a @var{pointer} to the
4909 foreign global variable @var{symbol} previously defined with
4912 @subheading Examples
4915 CFFI> (defcvar "errno" :int :read-only t)
4919 CFFI> (get-var-pointer '*errno*)
4920 @result{} #<A Mac Pointer #xA0008130>
4921 CFFI> (mem-ref * :int)
4925 @subheading See Also
4929 @c ===================================================================
4930 @c CHAPTER: Functions
4936 @c * Defining Foreign Functions::
4937 @c * Calling Foreign Functions::
4943 * foreign-funcall-pointer::
4946 @c @node Calling Foreign Functions
4947 @c @section Calling Foreign Functions
4949 @c @node Defining Foreign Functions
4950 @c @section Defining Foreign Functions
4953 @c ===================================================================
4957 @unnumberedsec defcfun
4959 @Macro{defcfun name-and-options return-type &body arguments [&rest] @
4962 @var{name-and-options} name | (name &key library calling-convention cconv) @*
4963 @var{name} ::= @var{lisp-name} [@var{foreign-name}] | @var{foreign-name} [@var{lisp-name}] @*
4964 @var{arguments} ::= @{ (arg-name arg-type) @}* @*
4966 @subheading Arguments and Values
4970 A string denoting a foreign function.
4973 A symbol naming the Lisp function to be created.
4982 @item calling-convention
4984 One of @code{:cdecl} (default) or @code{stdcall}.
4987 A symbol designating a foreign library.
4990 @subheading Description
4991 The @code{defcfun} macro provides a declarative interface for defining
4992 Lisp functions that call foreign functions.
4994 When one of @var{lisp-name} or @var{foreign-name} is omitted, the
4995 other is automatically derived using the following rules:
4999 Foreign names are converted to Lisp names by uppercasing and replacing
5000 underscores with hyphens.
5002 Lisp names are converted to foreign names by lowercasing and replacing
5003 hyphens with underscores.
5006 If you place the symbol @code{&rest} in the end of the argument list
5007 after the fixed arguments, @code{defcfun} will treat the foreign
5008 function as a @strong{variadic function}. The variadic arguments
5009 should be passed in a way similar to what @code{foreign-funcall} would
5010 expect. Unlike @code{foreign-funcall} though, @code{defcfun} will take
5011 care of doing argument promotion. Note that in this case
5012 @code{defcfun} will generate a Lisp @emph{macro} instead of a
5013 function and will only work for Lisps that support
5014 @code{foreign-funcall.}
5016 @subheading Examples
5019 (defcfun "strlen" :int (n :string))
5021 CFFI> (strlen "123")
5026 (defcfun ("abs" c-abs) :int (n :int))
5032 Variadic function example:
5035 (defcfun "sprintf" :int
5040 CFFI> (with-foreign-pointer-as-string (s 100)
5041 (sprintf s "%c %d %.2f %s" :char 90 :short 42 :float pi
5042 :string "super-locrian"))
5043 @result{} "A 42 3.14 super-locrian"
5046 @subheading See Also
5047 @seealso{foreign-funcall} @*
5048 @seealso{foreign-funcall-pointer}
5051 @c ===================================================================
5054 @node foreign-funcall
5055 @unnumberedsec foreign-funcall
5057 @Macro{foreign-funcall name-and-options &rest arguments @res{} return-value}
5059 arguments ::= @{ arg-type arg @}* [return-type]
5060 name-and-options ::= name | ( name &key library calling-convention cconv)
5062 @subheading Arguments and Values
5072 An argument of type @var{arg-type}.
5075 A foreign type, @code{:void} by default.
5081 A lisp symbol; not evaluated.
5083 @item calling-convention
5085 One of @code{:cdecl} (default) or @code{:stdcall}.
5088 @subheading Description
5089 The @code{foreign-funcall} macro is the main primitive for calling
5092 @emph{Note: The return value of foreign-funcall on functions with a
5093 :void return type is still undefined.}
5095 @subheading Implementation-specific Notes
5098 Corman Lisp does not support @code{foreign-funcall}. On
5099 implementations that @strong{don't} support @code{foreign-funcall}
5100 @code{cffi-features:no-foreign-funcall} will be present in
5101 @code{*features*}. Note: in these Lisps you can still use the
5102 @code{defcfun} interface.
5105 @subheading Examples
5108 CFFI> (foreign-funcall "strlen" :string "foo" :int)
5115 void print_number(int n)
5117 printf("N: %d\n", n);
5122 CFFI> (foreign-funcall "print_number" :int 123456)
5131 CFFI> (foreign-funcall "print_number" :int 123456 :void)
5137 CFFI> (foreign-funcall "printf" :string (format nil "%s: %d.~%")
5138 :string "So long and thanks for all the fish"
5140 @print{} So long and thanks for all the fish: 42.
5144 @subheading See Also
5145 @seealso{defcfun} @*
5146 @seealso{foreign-funcall-pointer}
5149 @c ===================================================================
5150 @c FOREIGN-FUNCALL-POINTER
5152 @node foreign-funcall-pointer
5153 @unnumberedsec foreign-funcall-pointer
5155 @Macro{foreign-funcall pointer options &rest arguments @res{} return-value}
5157 arguments ::= @{ arg-type arg @}* [return-type]
5158 options ::= ( &key calling-convention cconv )
5160 @subheading Arguments and Values
5170 An argument of type @var{arg-type}.
5173 A foreign type, @code{:void} by default.
5178 @item calling-convention
5180 One of @code{:cdecl} (default) or @code{:stdcall}.
5183 @subheading Description
5184 The @code{foreign-funcall} macro is the main primitive for calling
5187 @emph{Note: The return value of foreign-funcall on functions with a
5188 :void return type is still undefined.}
5190 @subheading Implementation-specific Notes
5193 Corman Lisp does not support @code{foreign-funcall}. On
5194 implementations that @strong{don't} support @code{foreign-funcall}
5195 @code{cffi-features:no-foreign-funcall} will be present in
5196 @code{*features*}. Note: in these Lisps you can still use the
5197 @code{defcfun} interface.
5200 @subheading Examples
5203 CFFI> (foreign-funcall-pointer (foreign-symbol-pointer "abs")
5208 @subheading See Also
5209 @seealso{defcfun} @*
5210 @seealso{foreign-funcall}
5213 @c ===================================================================
5214 @c CHAPTER: Libraries
5220 * Defining a library::
5221 * Library definition style::
5225 * close-foreign-library:: Close a foreign library.
5226 * *darwin-framework-directories*:: Search path for Darwin frameworks.
5227 * define-foreign-library:: Explain how to load a foreign library.
5228 * *foreign-library-directories*:: Search path for shared libraries.
5229 * load-foreign-library:: Load a foreign library.
5230 * load-foreign-library-error:: Signalled on failure of its namesake.
5231 * use-foreign-library:: Load a foreign library when needed.
5235 @node Defining a library
5236 @section Defining a library
5238 Almost all foreign code you might want to access exists in some kind
5239 of shared library. The meaning of @dfn{shared library} varies among
5240 platforms, but for our purposes, we will consider it to include
5241 @file{.so} files on @sc{unix}, frameworks on Darwin (and derivatives
5242 like Mac @acronym{OS X}), and @file{.dll} files on Windows.
5244 Bringing one of these libraries into the Lisp image is normally a
5249 Describe to @cffi{} how to load the library at some future point,
5250 depending on platform and other factors, with a
5251 @code{define-foreign-library} top-level form.
5254 Load the library so defined with either a top-level
5255 @code{use-foreign-library} form or by calling the function
5256 @code{load-foreign-library}.
5259 @xref{Tutorial-Loading,, Loading foreign libraries}, for a working
5260 example of the above two steps.
5263 @node Library definition style
5264 @section Library definition style
5266 Looking at the @code{libcurl} library definition presented earlier,
5267 you may ask why we did not simply do this:
5270 (define-foreign-library libcurl
5271 (t (:default "libcurl")))
5275 Indeed, this would work just as well on the computer on which I tested
5276 the tutorial. There are a couple of good reasons to provide the
5277 @file{.so}'s current version number, however. Namely, the versionless
5278 @file{.so} is not packaged on most @sc{unix} systems along with the
5279 actual, fully-versioned library; instead, it is included in the
5280 ``development'' package along with C headers and static @file{.a}
5283 The reason @cffi{} does not try to account for this lies in the
5284 meaning of the version numbers. A full treatment of shared library
5285 versions is beyond this manual's scope; see @ref{Versioning,, Library
5286 interface versions, libtool, @acronym{GNU} Libtool}, for helpful
5287 information for the unfamiliar. For our purposes, consider that a
5288 mismatch between the library version with which you tested and the
5289 installed library version may cause undefined
5290 behavior.@footnote{Windows programmers may chafe at adding a
5291 @sc{unix}-specific clause to @code{define-foreign-library}. Instead,
5292 ask why the Windows solution to library incompatibility is ``include
5293 your own version of every library you use with every program''.}
5295 @impnote{Maybe some notes should go here about OS X, which I know
5296 little about. --stephen}
5299 @c ===================================================================
5300 @c CLOSE-FOREIGN-LIBRARY
5302 @node close-foreign-library
5303 @unnumberedsec close-foreign-library
5305 @Function{close-foreign-library library @res{} success}
5307 @subheading Arguments and Values
5311 A symbol or an instance of @code{foreign-library}.
5317 @subheading Description
5319 Closes @var{library} which can be a symbol designating a library
5320 define through @code{define-foreign-library} or an instance of
5321 @code{foreign-library} as returned by @code{load-foreign-library}.
5323 @c @subheading Examples
5324 @c @xref{Tutorial-Loading,, Loading foreign libraries}.
5326 @subheading See Also
5328 @seealso{define-foreign-library} @*
5329 @seealso{load-foreign-library} @*
5330 @seealso{use-foreign-library}
5333 @c ===================================================================
5334 @c *DARWIN-FRAMEWORK-DIRECTORIES*
5336 @node *darwin-framework-directories*
5337 @unnumberedsec *darwin-framework-directories*
5340 @Variable{*darwin-framework-directories*}
5342 @subheading Value type
5344 A list, in which each element is a string, a pathname, or a simple
5347 @subheading Initial value
5349 A list containing the following, in order: an expression corresponding
5350 to Darwin path @file{~/Library/Frameworks/},
5351 @code{#P"/Library/Frameworks/"}, and
5352 @code{#P"/System/Library/Frameworks/"}.
5354 @subheading Description
5356 The meaning of ``simple Lisp expression'' is explained in
5357 @ref{*foreign-library-directories*}. In contrast to that variable,
5358 this is not a fallback search path; the default value described above
5359 is intended to be a reasonably complete search path on Darwin systems.
5361 @subheading Examples
5364 CFFI> (load-foreign-library '(:framework "OpenGL"))
5365 @result{} #P"/System/Library/Frameworks/OpenGL.framework/OpenGL"
5368 @subheading See also
5370 @seealso{*foreign-library-directories*} @*
5371 @seealso{define-foreign-library}
5374 @c ===================================================================
5375 @c DEFINE-FOREIGN-LIBRARY
5377 @node define-foreign-library
5378 @unnumberedsec define-foreign-library
5382 @Macro{define-foreign-library name-and-options @{ load-clause @}* @res{} name}
5384 name-and-options ::= name | (name &key calling-convention cconv)
5385 load-clause ::= (feature library &key calling-convention cconv)
5387 @subheading Arguments and Values
5394 A feature expression.
5397 A library designator.
5399 @item calling-convention
5401 One of @code{:cdecl} (default) or @code{:stdcall}
5404 @subheading Description
5406 Creates a new library designator called @var{name}. The
5407 @var{load-clause}s describe how to load that designator when passed to
5408 @code{load-foreign-library} or @code{use-foreign-library}.
5410 When trying to load the library @var{name}, the relevant function
5411 searches the @var{load-clause}s in order for the first one where
5412 @var{feature} evaluates to true. That happens for any of the
5413 following situations:@footnote{This is described in
5414 @code{cffi-feature-p} in @file{libraries.lisp}.}
5418 If @var{feature} is a symbol (idiomatically a keyword), a symbol with
5419 the same name, but interned into the @code{cffi-features} package, is
5420 present in @code{common-lisp:*features*}.
5423 If @var{feature} is a list, depending on @code{(first @var{feature})},
5428 All of the feature expressions in @code{(rest @var{feature})} are
5432 At least one of the feature expressions in @code{(rest @var{feature})}
5436 The feature expression @code{(second @var{feature})} is not true.
5440 Finally, if @var{feature} is @code{t}, this @var{load-clause} is
5441 picked unconditionally.
5444 Upon finding the first true @var{feature}, the library loader then
5445 loads the @var{library}. The meaning of ``library designator'' is
5446 described in @ref{load-foreign-library}.
5448 Functions associated to a library defined by
5449 @code{define-foreign-library} (e.g. through @code{defcfun}'s
5450 @code{:library} option, will inherit the library's options. The
5451 precedence is as follows:
5455 @code{defcfun}/@code{foreign-funcall} specific options;
5458 @var{load-clause} options;
5461 global library options (the @var{name-and-options} argument)
5465 @subheading Examples
5467 @xref{Tutorial-Loading,, Loading foreign libraries}.
5470 @subheading See Also
5472 @seealso{close-foreign-library} @*
5473 @seealso{load-foreign-library}
5476 @c ===================================================================
5477 @c *FOREIGN-LIBRARY-DIRECTORIES*
5479 @node *foreign-library-directories*
5480 @unnumberedsec *foreign-library-directories*
5483 @Variable{*foreign-library-directories*}
5485 @subheading Value type
5487 A list, in which each element is a string, a pathname, or a simple
5490 @subheading Initial value
5494 @subheading Description
5496 You should not have to use this variable.
5498 Most, if not all, Lisps supported by @cffi{} have a reasonable default
5499 search algorithm for foreign libraries. For example, Lisps for
5500 @sc{unix} usually call
5501 @uref{http://www.opengroup.org/onlinepubs/009695399/functions/dlopen.html,,
5502 @code{dlopen(3)}}, which in turn looks in the system library
5503 directories. Only if that fails does @cffi{} look for the named
5504 library file in these directories, and load it from there if found.
5506 Thus, this is intended to be a @cffi{}-only fallback to the library
5507 search configuration provided by your operating system. For example,
5508 if you distribute a foreign library with your Lisp package, you can
5509 add the library's containing directory to this list and portably
5510 expect @cffi{} to find it.
5512 A @dfn{simple Lisp expression} is intended to provide functionality
5513 commonly used in search paths such as
5514 @acronym{ASDF}'s@footnote{@xref{Using asdf to load systems,,, asdf,
5515 asdf: another system definition facility}, for information on
5516 @code{asdf:*central-registry*}.}, and is defined recursively as
5517 follows:@footnote{See @code{mini-eval} in @file{libraries.lisp} for
5518 the source of this definition. As is always the case with a Lisp
5519 @code{eval}, it's easier to understand the Lisp definition than the
5524 A list, whose @samp{first} is a function designator, and whose
5525 @samp{rest} is a list of simple Lisp expressions to be evaluated and
5526 passed to the so-designated function. The result is the result of the
5530 A symbol, whose result is its symbol value.
5533 Anything else evaluates to itself.
5537 @subheading Examples
5541 @print{} liblibli.so libli.lisp
5545 In @file{libli.lisp}:
5548 (pushnew #P"/home/sirian/lisp/libli/" *foreign-library-directories*
5551 (load-foreign-library '(:default "liblibli"))
5555 The following example would achieve the same effect:
5558 (pushnew '(merge-pathnames #p"lisp/libli/" (user-homedir-pathname))
5559 *foreign-library-directories*
5561 @result{} ((MERGE-PATHNAMES #P"lisp/libli/" (USER-HOMEDIR-PATHNAME)))
5563 (load-foreign-library '(:default "liblibli"))
5566 @subheading See also
5568 @seealso{*darwin-framework-directories*} @*
5569 @seealso{define-foreign-library}
5572 @c ===================================================================
5573 @c LOAD-FOREIGN-LIBRARY
5575 @node load-foreign-library
5576 @unnumberedsec load-foreign-library
5578 @Function{load-foreign-library library @res{} handler}
5580 @subheading Arguments and Values
5584 A library designator.
5587 An instance of @code{foreign-library}.
5590 @subheading Description
5592 Load the library indicated by @var{library}. A @dfn{library
5593 designator} is defined as follows:
5597 If a symbol, is considered a name previously defined with
5598 @code{define-foreign-library}.
5601 If a string or pathname, passed as a namestring directly to the
5602 implementation's foreign library loader. If that fails, search the
5603 directories in @code{*foreign-library-directories*} with
5604 @code{cl:probe-file}; if found, the absolute path is passed to the
5605 implementation's loader.
5608 If a list, the meaning depends on @code{(first @var{library})}:
5612 The second list element is taken to be a Darwin framework name, which
5613 is then searched in @code{*darwin-framework-directories*}, and loaded
5617 Each remaining list element, itself a library designator, is loaded in
5618 order, until one succeeds.
5621 The name is transformed according to the platform's naming convention
5622 to shared libraries, and the resultant string is loaded as a library
5623 designator. For example, on @sc{unix}, the name is suffixed with
5628 If the load fails, signal a @code{load-foreign-library-error}.
5630 @strong{Please note:} For system libraries, you should not need to
5631 specify the directory containing the library. Each operating system
5632 has its own idea of a default search path, and you should rely on it
5633 when it is reasonable.
5635 @subheading Implementation-specific Notes
5636 On ECL platforms where its dynamic FFI is not supported (ie. when
5637 @code{:dffi} is not present in @code{*features*}),
5638 @code{cffi:load-foreign-library} does not work and you must use ECL's
5639 own @code{ffi:load-foreign-library} with a constant string argument.
5641 @subheading Examples
5643 @xref{Tutorial-Loading,, Loading foreign libraries}.
5645 @subheading See Also
5647 @seealso{close-foreign-library} @*
5648 @seealso{*darwin-framework-directories*} @*
5649 @seealso{define-foreign-library} @*
5650 @seealso{*foreign-library-directories*} @*
5651 @seealso{load-foreign-library-error} @*
5652 @seealso{use-foreign-library}
5655 @c ===================================================================
5656 @c LOAD-FOREIGN-LIBRARY-ERROR
5658 @node load-foreign-library-error
5659 @unnumberedsec load-foreign-library-error
5663 @Condition{load-foreign-library-error}
5665 @subheading Class precedence list
5667 @code{load-foreign-library-error}, @code{error},
5668 @code{serious-condition}, @code{condition}, @code{t}
5670 @subheading Description
5672 Signalled when a foreign library load completely fails. The exact
5673 meaning of this varies depending on the real conditions at work, but
5674 almost universally, the implementation's error message is useless.
5675 However, @cffi{} does provide the useful restarts @code{retry} and
5676 @code{use-value}; invoke the @code{retry} restart to try loading the
5677 foreign library again, or the @code{use-value} restart to try loading
5678 a different foreign library designator.
5680 @subheading See also
5682 @seealso{load-foreign-library}
5685 @c ===================================================================
5686 @c USE-FOREIGN-LIBRARY
5688 @node use-foreign-library
5689 @unnumberedsec use-foreign-library
5693 @Macro{use-foreign-library name}
5695 @subheading Arguments and values
5699 A library designator; unevaluated.
5703 @subheading Description
5705 @xref{load-foreign-library}, for the meaning of ``library
5706 designator''. This is intended to be the top-level form used
5707 idiomatically after a @code{define-foreign-library} form to go ahead
5708 and load the library. @c ; it also sets the ``current foreign library''.
5709 Finally, on implementations where the regular evaluation rule is
5710 insufficient for foreign library loading, it loads it at the required
5711 time.@footnote{Namely, @acronym{CMUCL}. See
5712 @code{use-foreign-library} in @file{libraries.lisp} for details.}
5714 @c current foreign library is a concept created a few hours ago as of
5715 @c this writing. It is not actually used yet, but probably will be.
5717 @subheading Examples
5719 @xref{Tutorial-Loading,, Loading foreign libraries}.
5722 @subheading See also
5724 @seealso{load-foreign-library}
5727 @c ===================================================================
5728 @c CHAPTER: Callbacks
5742 @c ===================================================================
5746 @unnumberedsec callback
5748 @Macro{callback symbol @res{} pointer}
5750 @subheading Arguments and Values
5754 A symbol denoting a callback.
5761 @subheading Description
5762 The @code{callback} macro is analogous to the standard CL special
5763 operator @code{function} and will return a pointer to the callback
5764 denoted by the symbol @var{name}.
5766 @subheading Examples
5769 CFFI> (defcallback sum :int ((a :int) (b :int))
5772 CFFI> (callback sum)
5773 @result{} #<A Mac Pointer #x102350>
5776 @subheading See Also
5777 @seealso{get-callback} @*
5778 @seealso{defcallback}
5781 @c ===================================================================
5785 @unnumberedsec defcallback
5787 @Macro{defcallback name-and-options return-type arguments &body body @res{} name}
5789 name-and-options ::= name | (name &key calling-convention cconv)
5790 arguments ::= (@{ (arg-name arg-type) @}*)
5792 @subheading Arguments and Values
5796 A symbol naming the callback created.
5799 The foreign type for the callback's return value.
5807 @item calling-convention
5809 One of @code{:cdecl} (default) or @code{:stdcall}.
5812 @subheading Description
5813 The macro @code{defcallback} defines a Lisp function the can be called
5814 from C (but not from Lisp). The arguments passed to this function will
5815 be converted to the appropriate Lisp representation and its return
5816 value will be converted to its C representation.
5818 This Lisp function can be accessed by the @code{callback} macro or the
5819 @code{get-callback} function.
5821 @strong{Portability note:} @code{defcallback} will not work correctly
5822 on some Lisps if it's not a top-level form.
5824 @subheading Examples
5827 (defcfun "qsort" :void
5831 (fun-compar :pointer))
5833 (defcallback < :int ((a :pointer) (b :pointer))
5834 (let ((x (mem-ref a :int))
5835 (y (mem-ref b :int)))
5840 CFFI> (with-foreign-object (array :int 10)
5841 ;; @lispcmt{Initialize array.}
5842 (loop for i from 0 and n in '(7 2 10 4 3 5 1 6 9 8)
5843 do (setf (mem-aref array :int i) n))
5844 ;; @lispcmt{Sort it.}
5845 (qsort array 10 (foreign-type-size :int) (callback <))
5846 ;; @lispcmt{Return it as a list.}
5847 (loop for i from 0 below 10
5848 collect (mem-aref array :int i)))
5849 @result{} (1 2 3 4 5 6 7 8 9 10)
5852 @subheading See Also
5853 @seealso{callback} @*
5854 @seealso{get-callback}
5857 @c ===================================================================
5861 @unnumberedsec get-callback
5863 @Accessor{get-callback symbol @res{} pointer}
5865 @subheading Arguments and Values
5869 A symbol denoting a callback.
5875 @subheading Description
5876 This is the functional version of the @code{callback} macro. It
5877 returns a pointer to the callback named by @var{symbol} suitable, for
5878 example, to pass as arguments to foreign functions.
5880 @subheading Examples
5883 CFFI> (defcallback sum :int ((a :int) (b :int))
5886 CFFI> (get-callback 'sum)
5887 @result{} #<A Mac Pointer #x102350>
5890 @subheading See Also
5891 @seealso{callback} @*
5892 @seealso{defcallback}
5895 @c ===================================================================
5896 @c CHAPTER: The Groveller
5899 @chapter The Groveller
5901 @c Manual and software copyright @copyright{} 2005, 2006 Matthew Backes
5902 @c <lucca@@accela.net> and Dan Knapp <dankna@@accela.net>.
5904 @cffi{}-Grovel is a tool which makes it easier to write @cffi{}
5905 declarations for libraries that are implemented in C. That is, it
5906 grovels through the system headers, getting information about types
5907 and structures, so you don't have to. This is especially important
5908 for libraries which are implemented in different ways by different
5909 vendors, such as the @sc{unix}/@sc{posix} functions. The @cffi{}
5910 declarations are usually quite different from platform to platform,
5911 but the information you give to @cffi{}-Grovel is the same. Hence,
5912 much less work is required!
5914 If you use @acronym{ASDF}, @cffi{}-Grovel is integrated, so that it
5915 will run automatically when your system is building. This feature was
5916 inspired by SB-Grovel, a similar @acronym{SBCL}-specific project.
5917 @cffi{}-Grovel can also be used without @acronym{ASDF}.
5919 @section Building FFIs with CFFI-Grovel
5921 @cffi{}-Grovel uses a specification file (*.lisp) describing the
5922 features that need groveling. The C compiler is used to retrieve this
5923 data and write a Lisp file (*.cffi.lisp) which contains the necessary
5924 @cffi{} definitions to access the variables, structures, constants, and
5925 enums mentioned in the specification.
5927 @c This is most similar to the SB-Grovel package, upon which it is
5928 @c based. Unlike SB-Grovel, we do not currently support defining
5929 @c regular foreign functions in the specification file; those are best
5930 @c defined in normal Lisp code.
5932 @cffi{}-Grovel provides an @acronym{ASDF} component for handling the
5933 necessary calls to the C compiler and resulting file management.
5935 @c See the included CFFI-Unix package for an example of how to
5936 @c integrate a specification file with ASDF-built packages.
5939 * Groveller Syntax:: How grovel files should look like.
5940 * Groveller ASDF Integration:: ASDF components for grovel files.
5941 * Groveller Implementation Notes:: Implementation notes.
5944 @node Groveller Syntax
5945 @section Specification File Syntax
5947 The specification files are read by the normal Lisp reader, so they
5948 have syntax very similar to normal Lisp code. In particular,
5949 semicolon-comments and reader-macros will work as expected.
5951 There are several forms recognized by @cffi{}-Grovel:
5953 @deffn {Grovel Form} progn &rest forms
5955 Processes a list of forms. Useful for conditionalizing several
5960 #+cffi-features:freebsd
5962 (constant (ev-enable "EV_ENABLE"))
5963 (constant (ev-disable "EV_DISABLE")))
5966 @deffn {Grovel Form} include &rest files
5968 Include the specified files (specified as strings) in the generated C
5972 @deffn {Grovel Form} in-package symbol
5974 Set the package to be used for the final Lisp output.
5977 @deffn {Grovel Form} ctype lisp-name signedness size-designator
5979 Define a @cffi{} foreign type for the string in @var{size-designator},
5980 e.g. @code{(ctype :pid :unsigned "pid_t")}.
5983 @deffn {Grovel Form} constant (lisp-name &rest c-names) &key documentation optional
5985 Search for the constant named by the first @var{c-name} string found
5986 to be known to the C preprocessor and define it as @var{lisp-name}.
5987 If optional is true, no error will be raised if all the @var{c-names}
5991 @deffn {Grovel Form} define name &optional value
5993 Defines an additional C preprocessor symbol, which is useful for
5994 altering the behavior of included system headers.
5997 @deffn {Grovel Form} flag flag-string
5999 Adds @var{flag-string} to the flags used for the C compiler
6003 @deffn {Grovel Form} cstruct lisp-name c-name slots
6005 Define a @cffi{} foreign struct with the slot data specfied. Slots
6006 are of the form @code{(lisp-name c-name &key type count (signed t))}.
6009 @deffn {Grovel Form} cunion lisp-name c-name slots
6011 Identical to @code{cstruct}, but defines a @cffi{} foreign union.
6014 @deffn {Grovel Form} cstruct-and-class c-name slots
6016 Defines a @cffi{} foreign struct, as with @code{cstruct} and defines a
6017 @acronym{CLOS} class to be used with it. This is useful for mapping
6018 foreign structures to application-layer code that shouldn't need to
6019 worry about memory allocation issues.
6022 @deffn {Grovel Form} cvar namespec type &key read-only
6024 Defines a foreign variable of the specified type, even if that
6025 variable is potentially a C preprocessor pseudo-variable. e.g.
6026 @code{(cvar ("errno" errno) errno-values)}, assuming that errno-values
6027 is an enum or equivalent to type @code{:int}.
6029 The @var{namespec} is similar to the one used in @ref{defcvar}.
6032 @deffn {Grovel Form} cenum name &rest elements
6034 Defines a true C enum, with elements specified as @code{((lisp-name
6035 &rest c-names) &key optional documentation)}.
6038 @deffn {Grovel Form} constantenum name &rest elements
6040 Defines an enumeration of pre-processor constants, with elements
6041 specified as @code{((lisp-name &rest c-names) &key optional
6044 This example defines @code{:af-inet} to represent the value held by
6045 @code{AF_INET} or @code{PF_INET}, whichever the pre-processor finds
6046 first. Similarly for @code{:af-packet}, but no error will be
6047 signalled if the platform supports neither @code{AF_PACKET} nor
6052 (constantenum address-family
6053 ((:af-inet "AF_INET" "PF_INET")
6054 :documentation "IPv4 Protocol family")
6055 ((:af-local "AF_UNIX" "AF_LOCAL" "PF_UNIX" "PF_LOCAL")
6056 :documentation "File domain sockets")
6057 ((:af-inet6 "AF_INET6" "PF_INET6")
6058 :documentation "IPv6 Protocol family")
6059 ((:af-packet "AF_PACKET" "PF_PACKET")
6060 :documentation "Raw packet access"
6065 @c ===================================================================
6066 @c SECTION: Groveller ASDF Integration
6068 @node Groveller ASDF Integration
6069 @section ASDF Integration
6071 An example software project might contain four files; an
6072 @acronym{ASDF} file, a package definition file, an implementation
6073 file, and a @cffi{}-Grovel specification file.
6075 The @acronym{ASDF} file defines the system and its dependencies.
6076 Notice the use of @code{eval-when} to ensure @cffi{}-Grovel is present
6077 and the use of @code{(cffi-grovel:grovel-file name &key cc-flags)}
6078 instead of @code{(:file name)}.
6081 ;;; CFFI-Grovel is needed for processing grovel-file components
6082 (cl:eval-when (:load-toplevel :execute)
6083 (asdf:operate 'asdf:load-op 'cffi-grovel))
6085 (asdf:defsystem example-software
6090 (cffi-grovel:grovel-file "example-grovelling")
6094 The ``package.lisp'' file would contain several @code{defpackage}
6095 forms, to remove circular dependencies and make building the project
6096 easier. Note that you may or may not want to @code{:use} your
6099 @impnote{Mention that it's a not a good idea to :USE when names may
6100 clash with, say, CL symbols.}
6103 (defpackage #:example-internal
6105 (:nicknames #:exampleint))
6107 (defpackage #:example-software
6109 (:use #:cl #:cffi #:exampleint))
6112 The internal package is created by Lisp code output from the C program
6113 written by @cffi{}-Grovel; if your specification file is
6114 exampleint.lisp, the exampleint.cffi.lisp file will contain the
6115 @cffi{} definitions needed by the rest of your project.
6116 @xref{Groveller Syntax}.
6118 @node Groveller Implementation Notes
6119 @section Implementation Notes
6121 @impnote{This info might not be up-to-date.}
6123 For @code{foo-internal.lisp}, the resulting @code{foo-internal.c},
6124 @code{foo-internal}, and @code{foo-internal.cffi.lisp} are all
6125 platform-specific, either because of possible reader-macros in
6126 foo-internal.lisp, or because of varying C environments on the host
6127 system. For this reason, it is not helpful to distribute any of those
6128 files; end users building @cffi{}-Grovel based software will need
6129 @code{cffi}-Grovel anyway.
6131 If you build with multiple architectures in the same directory
6132 (e.g. with NFS/AFS home directories), it is critical to remove these
6133 generated files or the resulting constants will be very incorrect.
6135 @impnote{Maybe we should tag the generated names with something host
6138 @impnote{For now, after some experimentation with @sc{clisp} having no
6139 long-long, it seems appropriate to assert that the generated @code{.c}
6140 files are architecture and operating-system dependent, but
6141 lisp-implementation independent. This way the same @code{.c} file
6142 (and so the same @code{.grovel-tmp.lisp} file) will be shareable
6143 between the implementations running on a given system.}
6145 @c TODO: document the new wrapper stuff.
6148 @c ===================================================================
6149 @c CHAPTER: Limitations
6152 @chapter Limitations
6154 These are @cffi{}'s limitations across all platforms; for information
6155 on the warts on particular Lisp implementations, see
6156 @ref{Implementation Support}.
6160 The tutorial includes a treatment of the primary, intractable
6161 limitation of @cffi{}, or any @acronym{FFI}: that the abstractions
6162 commonly used by C are insufficiently expressive.
6163 @xref{Tutorial-Abstraction,, Breaking the abstraction}, for more
6167 C @code{struct}s cannot be passed by value.
6171 @node Platform-specific features
6172 @appendix Platform-specific features
6174 @cffi{} does some platform tests on loading. The details vary between
6175 Lisps; in fact, the purpose is to unify the list of available platform
6176 features for use elsewhere in the @cffi{} code. These features are
6177 also part of the public interface; see @ref{define-foreign-library}.
6179 The exact meanings of the features follow. Though you will usually
6180 refer to these symbols as keywords, @cffi{} internally views them in
6181 the package @code{cffi-features}.
6184 @item flat-namespace
6185 This Lisp has a flat namespace for foreign symbols meaning that you
6186 won't be able to load two different libraries with homograph functions
6187 and successfully differentiate them through the @code{:library}
6188 option to @code{defcfun}, @code{defcvar}, etc@dots{}
6191 This operating system is Darwin or a derivative thereof, such as
6194 @item no-foreign-funcall
6195 The macro @code{foreign-funcall} is @strong{not} available. On such
6196 platforms, the only way to call a foreign function is through
6197 @code{defcfun}. @xref{foreign-funcall}, and @ref{defcfun}.
6200 The C @code{long long} type is @strong{not} available as a foreign
6204 This Lisp doesn't support the @code{stdcall} calling convention. Note
6205 that it only makes sense to support @code{stdcall} on (32-bit) x86
6209 The underlying @acronym{CPU} architecture is 32-bit PowerPC.
6212 This operating system is a @sc{unix}-like, such as
6213 @acronym{GNU}/Linux, Darwin, or even Cygwin on Lisps that show the
6214 @sc{unix}-like interface provided by Cygwin to Lisp code.
6217 This operating system is Windows.
6220 The underlying @acronym{CPU} architecture is x86, such as on
6221 processors from Intel or @acronym{AMD}.
6229 @item aggregate type
6230 A @cffi{} type for C data defined as an organization of data of simple
6231 type; in structures and unions, which are themselves aggregate types,
6232 they are represented by value.
6235 This has two meanings; in any context, only one makes sense.
6237 When using type translators, the foreign value is the lower-level Lisp
6238 value derived from the object passed to @code{translate-to-foreign}
6239 (@pxref{translate-to-foreign}). This value should be a Lisp number or
6240 a pointer (satisfies @code{pointerp}), and it can be treated like any
6241 general Lisp object; it only completes the transformation to a true
6242 foreign value when passed through low-level code in the Lisp
6243 implementation, such as the foreign function caller or indirect memory
6244 addressing combined with a data move.
6246 In other contexts, this refers to a value accessible by C, but which
6247 may only be accessed through @cffi{} functions. The closest you can
6248 get to such a foreign value is through a pointer Lisp object, which
6249 itself counts as a foreign value in only the previous sense.
6252 A @cffi{} type that is ultimately represented as a builtin type;
6253 @cffi{} only provides extra semantics for Lisp that are invisible to C
6257 @node Comprehensive Index