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 @dircategory Software development
  41 @direntry
  42 * CFFI Sys spec: (cffi-sys-spec).       CFFI Sys spec.
  43 @end direntry
  44
  45 @titlepage
  46 @title CFFI-SYS Interface Specification
  47 @c @subtitle Version X.X
  48 @c @author James Bielman
  49
  50 @page
  51 @vskip 0pt plus 1filll
  52 @insertcopying
  53 @end titlepage
  54
  55 @contents
  56
  57 @ifnottex
  58 @node Top
  59 @top cffi-sys
  60 @insertcopying
  61 @end ifnottex
  62
  63 @menu
  64 * Introduction::
  65 * Built-In Foreign Types::
  66 * Operations on Foreign Types::
  67 * Basic Pointer Operations::
  68 * Foreign Memory Allocation::
  69 * Memory Access::
  70 * Foreign Function Calling::
  71 * Loading Foreign Libraries::
  72 * Foreign Globals::
  73 * Symbol Index::
  74 @end menu
  75
  76 @node Introduction
  77 @chapter Introduction
  78
  79 @acronym{CFFI}, the Common Foreign Function Interface, purports to be
  80 a portable foreign function interface for Common Lisp.
  81
  82 This specification defines a set of low-level primitives that must be
  83 defined for each Lisp implementation supported by @acronym{CFFI}.
  84 These operators are defined in the @code{CFFI-SYS} package.
  85
  86 The @code{CFFI} package uses the @code{CFFI-SYS} interface
  87 to implement an extensible foreign type system with support for
  88 typedefs, structures, and unions, a declarative interface for
  89 defining foreign function calls, and automatic conversion of
  90 foreign function arguments to/from Lisp types.
  91
  92 Please note the following conventions that apply to everything in
  93 @code{CFFI-SYS}:
  94
  95 @itemize @bullet
  96 @item
  97 Functions in @code{CFFI-SYS} that are low-level versions of functions
  98 exported from the @code{CFFI} package begin with a leading
  99 percent-sign (eg. @code{%mem-ref}).
 100
 101 @item
 102 Where ``foreign type'' is mentioned as the kind of an argument, the
 103 meaning is restricted to that subset of all foreign types defined in
 104 @ref{Built-In Foreign Types}.  Support for higher-level types is
 105 always defined in terms of those lower-level types in @code{CFFI}
 106 proper.
 107 @end itemize
 108
 109
 110 @node Built-In Foreign Types
 111 @chapter Built-In Foreign Types
 112
 113 @deftp {Foreign Type} :char
 114 @deftpx {Foreign Type} :unsigned-char
 115 @deftpx {Foreign Type} :short
 116 @deftpx {Foreign Type} :unsigned-short
 117 @deftpx {Foreign Type} :int
 118 @deftpx {Foreign Type} :unsigned-int
 119 @deftpx {Foreign Type} :long
 120 @deftpx {Foreign Type} :unsigned-long
 121 @deftpx {Foreign Type} :long-long
 122 @deftpx {Foreign Type} :unsigned-long-long
 123 These types correspond to the native C integer types according to the
 124 ABI of the system the Lisp implementation is compiled against.
 125 @end deftp
 126
 127 @deftp {Foreign Type} :int8
 128 @deftpx {Foreign Type} :uint8
 129 @deftpx {Foreign Type} :int16
 130 @deftpx {Foreign Type} :uint16
 131 @deftpx {Foreign Type} :int32
 132 @deftpx {Foreign Type} :uint32
 133 @deftpx {Foreign Type} :int64
 134 @deftpx {Foreign Type} :uint64
 135 Foreign integer types of specific sizes, corresponding to the C types
 136 defined in @code{stdint.h}.
 137 @end deftp
 138
 139 @deftp {Foreign Type} :size
 140 @deftpx {Foreign Type} :ssize
 141 @deftpx {Foreign Type} :ptrdiff
 142 @deftpx {Foreign Type} :time
 143 Foreign integer types corresponding to the standard C types (without
 144 the @code{_t} suffix).
 145 @end deftp
 146
 147 @impnote{I'm sure there are more of these that could be useful, let's
 148 add any types that can't be defined portably to this list as
 149 necessary.}
 150
 151 @deftp {Foreign Type} :float
 152 @deftpx {Foreign Type} :double
 153 The @code{:float} type represents a C @code{float} and a Lisp
 154 @code{single-float}. @code{:double} represents a C @code{double} and a
 155 Lisp @code{double-float}.
 156 @end deftp
 157
 158 @deftp {Foreign Type} :pointer
 159 A foreign pointer to an object of any type, corresponding to
 160 @code{void *}.
 161 @end deftp
 162
 163 @deftp {Foreign Type} :void
 164 No type at all. Only valid as the return type of a function.
 165 @end deftp
 166
 167
 168 @node Operations on Foreign Types
 169 @chapter Operations on Built-in Foreign Types
 170
 171 @defun %foreign-type-size type @result{} size
 172 Return the @var{size}, in bytes, of objects having foreign type
 173 @var{type}. An error is signalled if @var{type} is not a known
 174 built-in foreign type.
 175 @end defun
 176
 177 @defun %foreign-type-alignment type @result{} alignment
 178 Return the default alignment in bytes for structure members of foreign
 179 type @var{type}. An error is signalled if @var{type} is not a known
 180 built-in foreign type.
 181
 182 @impnote{Maybe this should take an optional keyword argument specifying an
 183 alternate alignment system, eg. :mac68k for 68000-compatible alignment
 184 on Darwin.}
 185 @end defun
 186
 187
 188 @node Basic Pointer Operations
 189 @chapter Basic Pointer Operations
 190
 191 @defun pointerp ptr @result{} boolean
 192 Return true if @var{ptr} is a foreign pointer.
 193 @end defun
 194
 195 @defun null-pointer @result{} pointer
 196 Return a null foreign pointer.
 197 @end defun
 198
 199 @defun null-pointer-p ptr @result{} boolean
 200 Return true if @var{ptr} is a null foreign pointer.
 201 @end defun
 202
 203 @defun make-pointer address @result{} pointer
 204 Return a pointer corresponding to the numeric integer @var{address}.
 205 @end defun
 206
 207 @defun inc-pointer ptr offset @result{} pointer
 208 Return the result of numerically incrementing @var{ptr} by @var{offset}.
 209 @end defun
 210
 211
 212 @node Foreign Memory Allocation
 213 @chapter Foreign Memory Allocation
 214
 215 @defun foreign-alloc size @result{} pointer
 216 Allocate @var{size} bytes of foreign-addressable memory and return
 217 a @var{pointer} to the allocated block. An implementation-specific
 218 error is signalled if the memory cannot be allocated.
 219 @end defun
 220
 221 @defun foreign-free ptr @result{} unspecified
 222 Free a pointer @var{ptr} allocated by @code{foreign-alloc}. The
 223 results are undefined if @var{ptr} is used after being freed.
 224 @end defun
 225
 226 @defmac with-foreign-pointer (var size &optional size-var) &body body
 227 Bind @var{var} to a pointer to @var{size} bytes of
 228 foreign-accessible memory during @var{body}.  Both @var{ptr} and the
 229 memory block it points to have dynamic extent and may be stack
 230 allocated if supported by the implementation. If @var{size-var} is
 231 supplied, it will be bound to @var{size} during @var{body}.
 232 @end defmac
 233
 234
 235 @node Memory Access
 236 @chapter Memory Access
 237
 238 @deffn {Accessor} %mem-ref ptr type &optional offset
 239 Dereference a pointer @var{offset} bytes from @var{ptr} to an object
 240 for reading (or writing when used with @code{setf}) of built-in type
 241 @var{type}.
 242 @end deffn
 243
 244 @heading Example
 245
 246 @lisp
 247 ;; An impractical example, since time returns the time as well,
 248 ;; but it demonstrates %MEM-REF. Better (simple) examples wanted!
 249 (with-foreign-pointer (p (foreign-type-size :time))
 250   (foreign-funcall "time" :pointer p :time)
 251   (%mem-ref p :time))
 252 @end lisp
 253
 254
 255 @node Foreign Function Calling
 256 @chapter Foreign Function Calling
 257
 258 @defmac %foreign-funcall name @{arg-type arg@}* &optional result-type @result{} object
 259 @defmacx %foreign-funcall-pointer ptr @{arg-type arg@}* &optional result-type @result{} object
 260 Invoke a foreign function called @var{name} in the foreign source code.
 261
 262 Each @var{arg-type} is a foreign type specifier, followed by
 263 @var{arg}, Lisp data to be converted to foreign data of type
 264 @var{arg-type}.  @var{result-type} is the foreign type of the
 265 function's return value, and is assumed to be @code{:void} if not
 266 supplied.
 267
 268 @code{%foreign-funcall-pointer} takes a pointer @var{ptr} to the
 269 function, as returned by @code{foreign-symbol-pointer}, rather than a
 270 string @var{name}.
 271 @end defmac
 272
 273 @defmac %foreign-funcall-varargs name (@{fixed-type arg@}*) @{vararg-type arg@}* &optional result-type @result{} object
 274 @defmacx %foreign-funcall-varargs-pointer ptr (@{fixed-type arg@}*) @{vararg-type arg@}* &optional result-type @result{} object
 275 Invoke a foreign variadic function called @var{name} in the foreign
 276 source code.
 277
 278 Each @var{fixed-type} and @var{vararg-type} is a foreign type
 279 specifier, followed by @var{arg}, Lisp data to be converted to foreign
 280 data of type @var{arg-type}.  @var{result-type} is the foreign type of
 281 the function's return value, and is assumed to be @code{:void} if not
 282 supplied.
 283
 284 @code{%foreign-funcall-pointer-varargs} takes a pointer @var{ptr} to
 285 the variadic function, as returned by @code{foreign-symbol-pointer},
 286 rather than a string @var{name}.
 287
 288 Both functions have default implementation which call
 289 @code{%foreign-funcall} and @code{%foreign-funcall-pointer}
 290 approprietly.
 291 @end defmac
 292
 293 @heading Examples
 294
 295 @lisp
 296 ;; Calling a standard C library function:
 297 (%foreign-funcall "sqrtf" :float 16.0 :float) @result{} 4.0
 298 @end lisp
 299
 300 @lisp
 301 ;; Dynamic allocation of a buffer and passing to a function:
 302 (with-foreign-ptr (buf 255 buf-size)
 303   (%foreign-funcall "gethostname" :pointer buf :size buf-size :int)
 304   ;; Convert buf to a Lisp string using MAKE-STRING and %MEM-REF or
 305   ;; a portable CFFI function such as CFFI:FOREIGN-STRING-TO-LISP.
 306   )
 307 @end lisp
 308
 309
 310 @node Loading Foreign Libraries
 311 @chapter Loading Foreign Libraries
 312
 313 @defun %load-foreign-library name @result{} unspecified
 314 Load the foreign shared library @var{name}.
 315
 316 @impnote{There is a lot of behavior to decide here.  Currently I lean
 317 toward not requiring NAME to be a full path to the library so
 318 we can search the system library directories (maybe even get
 319 LD_LIBRARY_PATH from the environment) as necessary.}
 320 @end defun
 321
 322
 323 @node Foreign Globals
 324 @chapter Foreign Globals
 325
 326 @defun foreign-symbol-pointer name @result{} pointer
 327 Return a pointer to a foreign symbol @var{name}.
 328 @end defun
 329
 330 @node Symbol Index
 331 @unnumbered Symbol Index
 332 @printindex fn
 333
 334 @bye