external/cffi.darcs/doc/cffi-sys-spec.texinfo

   1 \input texinfo   @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename cffi-sys.info
   4 @settitle CFFI-SYS Interface Specification
   5
   6 @c Show types in the same index as the functions.
   7 @synindex tp fn
   8
   9 @copying
  10 Copyright @copyright{} 2005-2006, James Bielman  <jamesjb at jamesjb.com>
  11
  12 @quotation
  13 Permission is hereby granted, free of charge, to any person
  14 obtaining a copy of this software and associated documentation
  15 files (the ``Software''), to deal in the Software without
  16 restriction, including without limitation the rights to use, copy,
  17 modify, merge, publish, distribute, sublicense, and/or sell copies
  18 of the Software, and to permit persons to whom the Software is
  19 furnished to do so, subject to the following conditions:
  20
  21 The above copyright notice and this permission notice shall be
  22 included in all copies or substantial portions of the Software.
  23
  24 @sc{The software is provided ``as is'', without warranty of any kind,
  25 express or implied, including but not limited to the warranties of
  26 merchantability, fitness for a particular purpose and
  27 noninfringement.  In no event shall the authors or copyright
  28 holders be liable for any claim, damages or other liability,
  29 whether in an action of contract, tort or otherwise, arising from,
  30 out of or in connection with the software or the use or other
  31 dealings in the software.}
  32 @end quotation
  33 @end copying
  34
  35 @macro impnote {text}
  36 @emph{Implementor's note: \text\}
  37 @end macro
  38 @c %**end of header
  39
  40 @titlepage
  41 @title CFFI-SYS Interface Specification
  42 @c @subtitle Version X.X
  43 @c @author James Bielman
  44
  45 @page
  46 @vskip 0pt plus 1filll
  47 @insertcopying
  48 @end titlepage
  49
  50 @contents
  51
  52 @ifnottex
  53 @node Top
  54 @top cffi-sys
  55 @insertcopying
  56 @end ifnottex
  57
  58 @menu
  59 * Introduction::
  60 * Built-In Foreign Types::
  61 * Operations on Foreign Types::
  62 * Basic Pointer Operations::
  63 * Foreign Memory Allocation::
  64 * Memory Access::
  65 * Foreign Function Calling::
  66 * Loading Foreign Libraries::
  67 * Foreign Globals::
  68 * Symbol Index::
  69 @end menu
  70
  71 @node Introduction
  72 @chapter Introduction
  73
  74 @acronym{CFFI}, the Common Foreign Function Interface, purports to be
  75 a portable foreign function interface for Common Lisp.
  76
  77 This specification defines a set of low-level primitives that must be
  78 defined for each Lisp implementation supported by @acronym{CFFI}.
  79 These operators are defined in the @code{CFFI-SYS} package.
  80
  81 The @code{CFFI} package uses the @code{CFFI-SYS} interface
  82 to implement an extensible foreign type system with support for
  83 typedefs, structures, and unions, a declarative interface for
  84 defining foreign function calls, and automatic conversion of
  85 foreign function arguments to/from Lisp types.
  86
  87 Please note the following conventions that apply to everything in
  88 @code{CFFI-SYS}:
  89
  90 @itemize @bullet
  91 @item
  92 Functions in @code{CFFI-SYS} that are low-level versions of functions
  93 exported from the @code{CFFI} package begin with a leading
  94 percent-sign (eg. @code{%mem-ref}).
  95
  96 @item
  97 Where ``foreign type'' is mentioned as the kind of an argument, the
  98 meaning is restricted to that subset of all foreign types defined in
  99 @ref{Built-In Foreign Types}.  Support for higher-level types is
 100 always defined in terms of those lower-level types in @code{CFFI}
 101 proper.
 102 @end itemize
 103
 104
 105 @node Built-In Foreign Types
 106 @chapter Built-In Foreign Types
 107
 108 @deftp {Foreign Type} :char
 109 @deftpx {Foreign Type} :unsigned-char
 110 @deftpx {Foreign Type} :short
 111 @deftpx {Foreign Type} :unsigned-short
 112 @deftpx {Foreign Type} :int
 113 @deftpx {Foreign Type} :unsigned-int
 114 @deftpx {Foreign Type} :long
 115 @deftpx {Foreign Type} :unsigned-long
 116 @deftpx {Foreign Type} :long-long
 117 @deftpx {Foreign Type} :unsigned-long-long
 118 These types correspond to the native C integer types according to the
 119 ABI of the system the Lisp implementation is compiled against.
 120 @end deftp
 121
 122 @deftp {Foreign Type} :int8
 123 @deftpx {Foreign Type} :uint8
 124 @deftpx {Foreign Type} :int16
 125 @deftpx {Foreign Type} :uint16
 126 @deftpx {Foreign Type} :int32
 127 @deftpx {Foreign Type} :uint32
 128 @deftpx {Foreign Type} :int64
 129 @deftpx {Foreign Type} :uint64
 130 Foreign integer types of specific sizes, corresponding to the C types
 131 defined in @code{stdint.h}.
 132 @end deftp
 133
 134 @deftp {Foreign Type} :size
 135 @deftpx {Foreign Type} :ssize
 136 @deftpx {Foreign Type} :ptrdiff
 137 @deftpx {Foreign Type} :time
 138 Foreign integer types corresponding to the standard C types (without
 139 the @code{_t} suffix).
 140 @end deftp
 141
 142 @impnote{I'm sure there are more of these that could be useful, let's
 143 add any types that can't be defined portably to this list as
 144 necessary.}
 145
 146 @deftp {Foreign Type} :float
 147 @deftpx {Foreign Type} :double
 148 The @code{:float} type represents a C @code{float} and a Lisp
 149 @code{single-float}. @code{:double} represents a C @code{double} and a
 150 Lisp @code{double-float}.
 151 @end deftp
 152
 153 @deftp {Foreign Type} :pointer
 154 A foreign pointer to an object of any type, corresponding to
 155 @code{void *}.
 156 @end deftp
 157
 158 @deftp {Foreign Type} :void
 159 No type at all. Only valid as the return type of a function.
 160 @end deftp
 161
 162
 163 @node Operations on Foreign Types
 164 @chapter Operations on Built-in Foreign Types
 165
 166 @defun %foreign-type-size type @result{} size
 167 Return the @var{size}, in bytes, of objects having foreign type
 168 @var{type}. An error is signalled if @var{type} is not a known
 169 built-in foreign type.
 170 @end defun
 171
 172 @defun %foreign-type-alignment type @result{} alignment
 173 Return the default alignment in bytes for structure members of foreign
 174 type @var{type}. An error is signalled if @var{type} is not a known
 175 built-in foreign type.
 176
 177 @impnote{Maybe this should take an optional keyword argument specifying an
 178 alternate alignment system, eg. :mac68k for 68000-compatible alignment
 179 on Darwin.}
 180 @end defun
 181
 182
 183 @node Basic Pointer Operations
 184 @chapter Basic Pointer Operations
 185
 186 @defun pointerp ptr @result{} boolean
 187 Return true if @var{ptr} is a foreign pointer.
 188 @end defun
 189
 190 @defun null-pointer @result{} pointer
 191 Return a null foreign pointer.
 192 @end defun
 193
 194 @defun null-pointer-p ptr @result{} boolean
 195 Return true if @var{ptr} is a null foreign pointer.
 196 @end defun
 197
 198 @defun make-pointer address @result{} pointer
 199 Return a pointer corresponding to the numeric integer @var{address}.
 200 @end defun
 201
 202 @defun inc-pointer ptr offset @result{} pointer
 203 Return the result of numerically incrementing @var{ptr} by @var{offset}.
 204 @end defun
 205
 206
 207 @node Foreign Memory Allocation
 208 @chapter Foreign Memory Allocation
 209
 210 @defun foreign-alloc size @result{} pointer
 211 Allocate @var{size} bytes of foreign-addressable memory and return
 212 a @var{pointer} to the allocated block. An implementation-specific
 213 error is signalled if the memory cannot be allocated.
 214 @end defun
 215
 216 @defun foreign-free ptr @result{} unspecified
 217 Free a pointer @var{ptr} allocated by @code{foreign-alloc}. The
 218 results are undefined if @var{ptr} is used after being freed.
 219 @end defun
 220
 221 @defmac with-foreign-pointer (var size &optional size-var) &body body
 222 Bind @var{var} to a pointer to @var{size} bytes of
 223 foreign-accessible memory during @var{body}.  Both @var{ptr} and the
 224 memory block it points to have dynamic extent and may be stack
 225 allocated if supported by the implementation. If @var{size-var} is
 226 supplied, it will be bound to @var{size} during @var{body}.
 227 @end defmac
 228
 229
 230 @node Memory Access
 231 @chapter Memory Access
 232
 233 @deffn {Accessor} %mem-ref ptr type &optional offset
 234 Dereference a pointer @var{offset} bytes from @var{ptr} to an object
 235 for reading (or writing when used with @code{setf}) of built-in type
 236 @var{type}.
 237 @end deffn
 238
 239 @heading Example
 240
 241 @lisp
 242 ;; An impractical example, since time returns the time as well,
 243 ;; but it demonstrates %MEM-REF. Better (simple) examples wanted!
 244 (with-foreign-pointer (p (foreign-type-size :time))
 245   (foreign-funcall "time" :pointer p :time)
 246   (%mem-ref p :time))
 247 @end lisp
 248
 249
 250 @node Foreign Function Calling
 251 @chapter Foreign Function Calling
 252
 253 @defmac %foreign-funcall name @{arg-type arg@}* &optional result-type @result{} object
 254 @defmacx %foreign-funcall-pointer ptr @{arg-type arg@}* &optional result-type @result{} object
 255 Invoke a foreign function called @var{name} in the foreign source code.
 256
 257 Each @var{arg-type} is a foreign type specifier, followed by
 258 @var{arg}, Lisp data to be converted to foreign data of type
 259 @var{arg-type}.  @var{result-type} is the foreign type of the
 260 function's return value, and is assumed to be @code{:void} if not
 261 supplied.
 262
 263 @code{%foreign-funcall-pointer} takes a pointer @var{ptr} to the
 264 function, as returned by @code{foreign-symbol-pointer}, rather than a
 265 string @var{name}.
 266 @end defmac
 267
 268 @heading Examples
 269
 270 @lisp
 271 ;; Calling a standard C library function:
 272 (%foreign-funcall "sqrtf" :float 16.0 :float) @result{} 4.0
 273 @end lisp
 274
 275 @lisp
 276 ;; Dynamic allocation of a buffer and passing to a function:
 277 (with-foreign-ptr (buf 255 buf-size)
 278   (%foreign-funcall "gethostname" :pointer buf :size buf-size :int)
 279   ;; Convert buf to a Lisp string using MAKE-STRING and %MEM-REF or
 280   ;; a portable CFFI function such as CFFI:FOREIGN-STRING-TO-LISP.
 281   )
 282 @end lisp
 283
 284
 285 @node Loading Foreign Libraries
 286 @chapter Loading Foreign Libraries
 287
 288 @defun %load-foreign-library name @result{} unspecified
 289 Load the foreign shared library @var{name}.
 290
 291 @impnote{There is a lot of behavior to decide here.  Currently I lean
 292 toward not requiring NAME to be a full path to the library so
 293 we can search the system library directories (maybe even get
 294 LD_LIBRARY_PATH from the environment) as necessary.}
 295 @end defun
 296
 297
 298 @node Foreign Globals
 299 @chapter Foreign Globals
 300
 301 @defun foreign-symbol-pointer name @result{} pointer
 302 Return a pointer to a foreign symbol @var{name}.
 303 @end defun
 304
 305 @node Symbol Index
 306 @unnumbered Symbol Index
 307 @printindex fn
 308
 309 @bye