1.0.37.49: add :ABORT to SOCKET-CLOSE
[sbcl.git] / contrib / sb-grovel / sb-grovel.texinfo
1 @node sb-grovel
2 @section sb-grovel
3 @cindex Foreign Function Interface, generation
4
5 The @code{sb-grovel} module helps in generation of foreign function
6 interfaces. It aids in extracting constants' values from the C
7 compiler and in generating SB-ALIEN structure and union types,
8 @pxref{Defining Foreign Types}.
9
10 The ASDF(@uref{http://www.cliki.net/ASDF}) component type
11 GROVEL-CONSTANTS-FILE has its PERFORM
12 @c @xref for PERFORM when asdf manual is included?
13 operation defined to write out a C source file, compile it, and run
14 it.  The output from this program is Lisp, which is then itself
15 compiled and loaded.
16
17 sb-grovel is used in a few contributed modules, and it is currently
18 compatible only to SBCL. However, if you want to use it, here are a
19 few directions.
20
21 @subsection Using sb-grovel in your own ASDF system
22
23 @enumerate
24
25 @item
26 Create a Lisp package for the foreign constants/functions to go into.
27
28 @item
29 Make your system depend on the 'sb-grovel system.
30
31 @item
32 Create a grovel-constants data file - for an example, see
33 example-constants.lisp in the contrib/sb-grovel/ directory in the SBCL
34 source distribution.
35
36 @item
37 Add it as a component in your system. e.g.
38
39 @lisp
40 (eval-when (:compile-toplevel :load-toplevel :execute)
41   (require :sb-grovel))
42
43 (defpackage :example-package.system
44             (:use :cl :asdf :sb-grovel :sb-alien))
45
46 (in-package :example-package.system)
47             
48 (defsystem example-system
49     :depends-on (sb-grovel)
50     :components
51     ((:module "sbcl"
52               :components
53               ((:file "defpackage")
54                (grovel-constants-file "example-constants"
55                                       :package :example-package)))))
56 @end lisp
57
58 Make sure to specify the package you chose in step 1
59
60 @item
61 Build stuff.
62
63 @end enumerate
64
65 @subsection Contents of a grovel-constants-file
66
67 The grovel-constants-file, typically named @code{constants.lisp},
68 comprises lisp expressions describing the foreign things that you want
69 to grovel for. A @code{constants.lisp} file contains two sections:
70
71 @itemize
72 @item
73 a list of headers to include in the C program, for example:
74 @lisp
75 ("sys/types.h" "sys/socket.h" "sys/stat.h" "unistd.h" "sys/un.h"
76  "netinet/in.h" "netinet/in_systm.h" "netinet/ip.h" "net/if.h"
77  "netdb.h" "errno.h" "netinet/tcp.h" "fcntl.h" "signal.h" )
78 @end lisp
79
80 @item
81 A list of sb-grovel clauses describing the things you want to grovel
82 from the C compiler, for example:
83 @lisp
84 ((:integer af-local
85            #+(or sunos solaris) "AF_UNIX"
86            #-(or sunos solaris) "AF_LOCAL"
87            "Local to host (pipes and file-domain).")
88  (:structure stat ("struct stat"
89                    (integer dev "dev_t" "st_dev")
90                    (integer atime "time_t" "st_atime")))
91  (:function getpid ("getpid" int )))
92 @end lisp
93 @end itemize
94
95 There are two types of things that sb-grovel can sensibly extract from
96 the C compiler: constant integers and structure layouts. It is also
97 possible to define foreign functions in the constants.lisp file, but
98 these definitions don't use any information from the C program; they
99 expand directly to @code{sb-alien:define-alien-routine}
100 (@pxref{The define-alien-routine Macro}) forms.
101
102 Here's how to use the grovel clauses:
103
104 @itemize
105 @item
106 @code{:integer} - constant expressions in C. Used in this form:
107 @lisp
108  (:integer lisp-variable-name "C expression" &optional doc export)
109 @end lisp
110
111 @code{"C expression"} will be typically be the name of a constant. But
112 other forms are possible.
113
114 @item
115 @code{:enum}
116 @lisp
117  (:enum lisp-type-name ((lisp-enumerated-name c-enumerated-name) ...)))
118 @end lisp
119
120 An @code{sb-alien:enum} type with name @code{lisp-type-name} will be defined.
121 The symbols are the @code{lisp-enumerated-name}s, and the values
122 are grovelled from the @code{c-enumerated-name}s.
123
124 @item
125 @code{:structure} - alien structure definitions look like this:
126 @lisp
127  (:structure lisp-struct-name ("struct c_structure"
128                                (type-designator lisp-element-name
129                                 "c_element_type" "c_element_name"
130                                 :distrust-length nil)
131                                ; ...
132                                ))
133 @end lisp
134
135 @code{type-designator} is a reference to a type whose size (and type
136 constraints) will be groveled for. sb-grovel accepts a form of type
137 designator that doesn't quite conform to either lisp nor sb-alien's
138 type specifiers. Here's a list of type designators that sb-grovel
139 currently accepts:
140 @itemize
141 @item
142 @code{integer} - a C integral type; sb-grovel will infer the exact
143 type from size information extracted from the C program. All common C
144 integer types can be grovelled for with this type designator, but it
145 is not possible to grovel for bit fields yet.
146
147 @item
148 @code{(unsigned n)} - an unsigned integer variable that is @code{n}
149 bytes long. No size information from the C program will be used.
150 @item
151 @code{(signed n)} - an signed integer variable that is @code{n} bytes
152 long. No size information from the C program will be used.
153
154 @item
155 @code{c-string} - an array of @code{char} in the structure. sb-grovel
156 will use the array's length from the C program, unless you pass it the
157 @code{:distrust-length} keyword argument with non-@code{nil} value
158 (this might be required for structures such as solaris's @code{struct
159 dirent}).
160
161 @item
162 @code{c-string-pointer} - a pointer to a C string, corresponding to
163 the @code{sb-alien:c-string} type (@pxref{Foreign Type Specifiers}).
164 @item
165 @code{(array alien-type)} - An array of the previously-declared alien
166 type. The array's size will be determined from the output of the C
167 program and the alien type's size.
168 @item
169 @code{(array alien-type n)} - An array of the previously-declared alien
170 type. The array's size will be assumed as being @code{n}.
171 @end itemize
172
173
174 Note that @code{c-string} and @code{c-string-pointer} do not have the
175 same meaning. If you declare that an element is of type
176 @code{c-string}, it will be treated as if the string is a part of the
177 structure, whereas if you declare that the element is of type
178 @code{c-string-pointer}, a @emph{pointer to a string} will be the
179 structure member.
180
181 @item
182 @code{:function} - alien function definitions are similar to
183 @code{define-alien-routine} definitions, because they expand to such
184 forms when the lisp program is loaded. @xref{Foreign Function Calls}.
185
186 @lisp
187 (:function lisp-function-name ("alien_function_name" alien-return-type
188                                                      (argument alien-type)
189                                                      (argument2 alien-type)))
190 @end lisp
191 @end itemize
192
193
194 @subsection Programming with sb-grovel's structure types
195
196 Let us assume that you have a grovelled structure definition:
197 @lisp
198  (:structure mystruct ("struct my_structure"
199                        (integer myint "int" "st_int")
200                        (c-string mystring "char[]" "st_str")))
201 @end lisp
202
203 What can you do with it? Here's a short interface document:
204
205 @itemize
206 @item
207 Creating and destroying objects:
208 @itemize
209 @item
210 Function @code{(allocate-mystruct)} - allocates an object of type @code{mystruct}and
211 returns a system area pointer to it.
212 @item
213 Function @code{(free-mystruct var)} - frees the alien object pointed to by
214 @var{var}.
215 @item
216 Macro @code{(with-mystruct var ((member init) [...]) &body body)} -
217 allocates an object of type @code{mystruct} that is valid in
218 @var{body}. If @var{body} terminates or control unwinds out of
219 @var{body}, the object pointed to by @var{var} will be deallocated.
220 @end itemize
221
222 @item
223 Accessing structure members:
224 @itemize
225 @item
226 @code{(mystruct-myint var)} and @code{(mystruct-mystring var)} return
227 the value of the respective fields in @code{mystruct}.
228 @item
229 @code{(setf (mystruct-myint var) new-val)} and
230 @code{(setf (mystruct-mystring var) new-val)} sets the value of the respective
231 structure member to the value of @var{new-val}. Notice that in
232 @code{(setf (mystruct-mystring var) new-val)}'s case, new-val is a lisp
233 string.
234 @end itemize
235 @end itemize
236
237 @subsubsection Traps and Pitfalls
238 Basically, you can treat functions and data structure definitions that
239 sb-grovel spits out as if they were alien routines and types. This has
240 a few implications that might not be immediately obvious (especially
241 if you have programmed in a previous version of sb-grovel that didn't
242 use alien types):
243
244 @itemize
245 @item
246 You must take care of grovel-allocated structures yourself. They are
247 alien types, so the garbage collector will not collect them when you
248 drop the last reference.
249
250 @item
251 If you use the @code{with-mystruct} macro, be sure that no references
252 to the variable thus allocated leaks out. It will be deallocated when
253 the block exits.
254 @end itemize