GopherProxy

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