Commit | Line | Data |
---|---|---|
726b8ba3 AW |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
1f4f7674 LC |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, |
4 | @c 2009, 2010, 2011 Free Software Foundation, Inc. | |
726b8ba3 AW |
5 | @c See the file guile.texi for copying conditions. |
6 | ||
726b8ba3 AW |
7 | @node Foreign Function Interface |
8 | @section Foreign Function Interface | |
9 | @cindex foreign function interface | |
10 | @cindex ffi | |
11 | ||
12 | The more one hacks in Scheme, the more one realizes that there are | |
13 | actually two computational worlds: one which is warm and alive, that | |
14 | land of parentheses, and one cold and dead, the land of C and its ilk. | |
15 | ||
16 | But yet we as programmers live in both worlds, and Guile itself is half | |
17 | implemented in C. So it is that Guile's living half pays respect to its | |
18 | dead counterpart, via a spectrum of interfaces to C ranging from dynamic | |
19 | loading of Scheme primitives to dynamic binding of stock C library | |
0b9bdb1b | 20 | procedures. |
726b8ba3 AW |
21 | |
22 | @menu | |
23 | * Foreign Libraries:: Dynamically linking to libraries. | |
24 | * Foreign Functions:: Simple calls to C procedures. | |
25 | * C Extensions:: Extending Guile in C with loadable modules. | |
26 | * Modules and Extensions:: Loading C extensions into modules. | |
71725997 AW |
27 | * Foreign Pointers:: Accessing global variables. |
28 | * Dynamic FFI:: Calling arbitrary C functions. | |
726b8ba3 AW |
29 | @end menu |
30 | ||
31 | ||
32 | @node Foreign Libraries | |
33 | @subsection Foreign Libraries | |
34 | ||
35 | Most modern Unices have something called @dfn{shared libraries}. This | |
36 | ordinarily means that they have the capability to share the executable | |
37 | image of a library between several running programs to save memory and | |
38 | disk space. But generally, shared libraries give a lot of additional | |
39 | flexibility compared to the traditional static libraries. In fact, | |
40 | calling them `dynamic' libraries is as correct as calling them `shared'. | |
41 | ||
42 | Shared libraries really give you a lot of flexibility in addition to the | |
43 | memory and disk space savings. When you link a program against a shared | |
44 | library, that library is not closely incorporated into the final | |
45 | executable. Instead, the executable of your program only contains | |
46 | enough information to find the needed shared libraries when the program | |
47 | is actually run. Only then, when the program is starting, is the final | |
48 | step of the linking process performed. This means that you need not | |
49 | recompile all programs when you install a new, only slightly modified | |
50 | version of a shared library. The programs will pick up the changes | |
51 | automatically the next time they are run. | |
52 | ||
53 | Now, when all the necessary machinery is there to perform part of the | |
54 | linking at run-time, why not take the next step and allow the programmer | |
55 | to explicitly take advantage of it from within his program? Of course, | |
56 | many operating systems that support shared libraries do just that, and | |
57 | chances are that Guile will allow you to access this feature from within | |
58 | your Scheme programs. As you might have guessed already, this feature | |
59 | is called @dfn{dynamic linking}.@footnote{Some people also refer to the | |
60 | final linking stage at program startup as `dynamic linking', so if you | |
61 | want to make yourself perfectly clear, it is probably best to use the | |
62 | more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit | |
63 | in his libtool documentation.} | |
64 | ||
65 | We titled this section ``foreign libraries'' because although the name | |
66 | ``foreign'' doesn't leak into the API, the world of C really is foreign | |
67 | to Scheme -- and that estrangement extends to components of foreign | |
68 | libraries as well, as we see in future sections. | |
69 | ||
70 | @deffn {Scheme Procedure} dynamic-link [library] | |
71 | @deffnx {C Function} scm_dynamic_link (library) | |
72 | Find the shared library denoted by @var{library} (a string) and link it | |
73 | into the running Guile application. When everything works out, return a | |
74 | Scheme object suitable for representing the linked object file. | |
75 | Otherwise an error is thrown. How object files are searched is system | |
76 | dependent. | |
77 | ||
78 | Normally, @var{library} is just the name of some shared library file | |
79 | that will be searched for in the places where shared libraries usually | |
80 | reside, such as in @file{/usr/lib} and @file{/usr/local/lib}. | |
81 | ||
82 | When @var{library} is omitted, a @dfn{global symbol handle} is returned. This | |
83 | handle provides access to the symbols available to the program at run-time, | |
84 | including those exported by the program itself and the shared libraries already | |
85 | loaded. | |
86 | @end deffn | |
87 | ||
88 | @deffn {Scheme Procedure} dynamic-object? obj | |
89 | @deffnx {C Function} scm_dynamic_object_p (obj) | |
90 | Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} | |
91 | otherwise. | |
92 | @end deffn | |
93 | ||
94 | @deffn {Scheme Procedure} dynamic-unlink dobj | |
95 | @deffnx {C Function} scm_dynamic_unlink (dobj) | |
96 | Unlink the indicated object file from the application. The | |
97 | argument @var{dobj} must have been obtained by a call to | |
98 | @code{dynamic-link}. After @code{dynamic-unlink} has been | |
99 | called on @var{dobj}, its content is no longer accessible. | |
100 | @end deffn | |
101 | ||
102 | @smallexample | |
71725997 AW |
103 | (define libgl-obj (dynamic-link "libGL")) |
104 | libgl-obj | |
105 | @result{} #<dynamic-object "libGL"> | |
106 | (dynamic-unlink libGL-obj) | |
107 | libGL-obj | |
108 | @result{} #<dynamic-object "libGL" (unlinked)> | |
726b8ba3 AW |
109 | @end smallexample |
110 | ||
111 | As you can see, after calling @code{dynamic-unlink} on a dynamically | |
112 | linked library, it is marked as @samp{(unlinked)} and you are no longer | |
113 | able to use it with @code{dynamic-call}, etc. Whether the library is | |
114 | really removed from you program is system-dependent and will generally | |
71725997 | 115 | not happen when some other parts of your program still use it. |
726b8ba3 AW |
116 | |
117 | When dynamic linking is disabled or not supported on your system, | |
118 | the above functions throw errors, but they are still available. | |
119 | ||
120 | ||
121 | @node Foreign Functions | |
122 | @subsection Foreign Functions | |
123 | ||
43cd9cec AW |
124 | The most natural thing to do with a dynamic library is to grovel around |
125 | in it for a function pointer: a @dfn{foreign function}. | |
126 | @code{dynamic-func} exists for that purpose. | |
127 | ||
726b8ba3 AW |
128 | @deffn {Scheme Procedure} dynamic-func name dobj |
129 | @deffnx {C Function} scm_dynamic_func (name, dobj) | |
130 | Return a ``handle'' for the func @var{name} in the shared object referred to | |
131 | by @var{dobj}. The handle can be passed to @code{dynamic-call} to | |
132 | actually call the function. | |
133 | ||
134 | Regardless whether your C compiler prepends an underscore @samp{_} to the global | |
135 | names in a program, you should @strong{not} include this underscore in | |
136 | @var{name} since it will be added automatically when necessary. | |
137 | @end deffn | |
138 | ||
43cd9cec AW |
139 | Guile has static support for calling functions with no arguments, |
140 | @code{dynamic-call}. | |
141 | ||
726b8ba3 AW |
142 | @deffn {Scheme Procedure} dynamic-call func dobj |
143 | @deffnx {C Function} scm_dynamic_call (func, dobj) | |
144 | Call the C function indicated by @var{func} and @var{dobj}. | |
145 | The function is passed no arguments and its return value is | |
146 | ignored. When @var{function} is something returned by | |
147 | @code{dynamic-func}, call that function and ignore @var{dobj}. | |
148 | When @var{func} is a string , look it up in @var{dynobj}; this | |
149 | is equivalent to | |
150 | @smallexample | |
151 | (dynamic-call (dynamic-func @var{func} @var{dobj}) #f) | |
152 | @end smallexample | |
153 | ||
154 | Interrupts are deferred while the C function is executing (with | |
155 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
156 | @end deffn | |
157 | ||
43cd9cec AW |
158 | @code{dynamic-call} is not very powerful. It is mostly intended to be |
159 | used for calling specially written initialization functions that will | |
160 | then add new primitives to Guile. For example, we do not expect that you | |
161 | will dynamically link @file{libX11} with @code{dynamic-link} and then | |
162 | construct a beautiful graphical user interface just by using | |
163 | @code{dynamic-call}. Instead, the usual way would be to write a special | |
71725997 | 164 | Guile-to-X11 glue library that has intimate knowledge about both Guile |
43cd9cec AW |
165 | and X11 and does whatever is necessary to make them inter-operate |
166 | smoothly. This glue library could then be dynamically linked into a | |
726b8ba3 | 167 | vanilla Guile interpreter and activated by calling its initialization |
43cd9cec | 168 | function. That function would add all the new types and primitives to |
726b8ba3 AW |
169 | the Guile interpreter that it has to offer. |
170 | ||
43cd9cec AW |
171 | (There is actually another, better option: simply to create a |
172 | @file{libX11} wrapper in Scheme via the dynamic FFI. @xref{Dynamic FFI}, | |
173 | for more information.) | |
726b8ba3 | 174 | |
43cd9cec AW |
175 | Given some set of C extensions to Guile, the next logical step is to |
176 | integrate these glue libraries into the module system of Guile so that | |
177 | you can load new primitives into a running system just as you can load | |
178 | new Scheme code. | |
726b8ba3 AW |
179 | |
180 | @deffn {Scheme Procedure} load-extension lib init | |
181 | @deffnx {C Function} scm_load_extension (lib, init) | |
182 | Load and initialize the extension designated by LIB and INIT. | |
183 | When there is no pre-registered function for LIB/INIT, this is | |
184 | equivalent to | |
185 | ||
186 | @lisp | |
187 | (dynamic-call INIT (dynamic-link LIB)) | |
188 | @end lisp | |
189 | ||
190 | When there is a pre-registered function, that function is called | |
191 | instead. | |
192 | ||
193 | Normally, there is no pre-registered function. This option exists | |
194 | only for situations where dynamic linking is unavailable or unwanted. | |
195 | In that case, you would statically link your program with the desired | |
196 | library, and register its init function right after Guile has been | |
197 | initialized. | |
198 | ||
199 | LIB should be a string denoting a shared library without any file type | |
200 | suffix such as ".so". The suffix is provided automatically. It | |
201 | should also not contain any directory components. Libraries that | |
202 | implement Guile Extensions should be put into the normal locations for | |
203 | shared libraries. We recommend to use the naming convention | |
204 | libguile-bla-blum for a extension related to a module `(bla blum)'. | |
205 | ||
206 | The normal way for a extension to be used is to write a small Scheme | |
207 | file that defines a module, and to load the extension into this | |
208 | module. When the module is auto-loaded, the extension is loaded as | |
209 | well. For example, | |
210 | ||
211 | @lisp | |
212 | (define-module (bla blum)) | |
213 | ||
214 | (load-extension "libguile-bla-blum" "bla_init_blum") | |
215 | @end lisp | |
216 | @end deffn | |
217 | ||
218 | @node C Extensions | |
219 | @subsection C Extensions | |
220 | ||
221 | The most interesting application of dynamically linked libraries is | |
222 | probably to use them for providing @emph{compiled code modules} to | |
223 | Scheme programs. As much fun as programming in Scheme is, every now and | |
224 | then comes the need to write some low-level C stuff to make Scheme even | |
225 | more fun. | |
226 | ||
227 | Not only can you put these new primitives into their own module (see the | |
228 | previous section), you can even put them into a shared library that is | |
229 | only then linked to your running Guile image when it is actually | |
230 | needed. | |
231 | ||
232 | An example will hopefully make everything clear. Suppose we want to | |
233 | make the Bessel functions of the C library available to Scheme in the | |
234 | module @samp{(math bessel)}. First we need to write the appropriate | |
235 | glue code to convert the arguments and return values of the functions | |
236 | from Scheme to C and back. Additionally, we need a function that will | |
237 | add them to the set of Guile primitives. Because this is just an | |
238 | example, we will only implement this for the @code{j0} function. | |
239 | ||
240 | @smallexample | |
241 | #include <math.h> | |
242 | #include <libguile.h> | |
243 | ||
244 | SCM | |
245 | j0_wrapper (SCM x) | |
246 | @{ | |
247 | return scm_from_double (j0 (scm_to_double (x, "j0"))); | |
248 | @} | |
249 | ||
250 | void | |
251 | init_math_bessel () | |
252 | @{ | |
253 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
254 | @} | |
255 | @end smallexample | |
256 | ||
257 | We can already try to bring this into action by manually calling the low | |
258 | level functions for performing dynamic linking. The C source file needs | |
259 | to be compiled into a shared library. Here is how to do it on | |
260 | GNU/Linux, please refer to the @code{libtool} documentation for how to | |
261 | create dynamically linkable libraries portably. | |
262 | ||
263 | @smallexample | |
264 | gcc -shared -o libbessel.so -fPIC bessel.c | |
265 | @end smallexample | |
266 | ||
267 | Now fire up Guile: | |
268 | ||
269 | @lisp | |
270 | (define bessel-lib (dynamic-link "./libbessel.so")) | |
271 | (dynamic-call "init_math_bessel" bessel-lib) | |
272 | (j0 2) | |
273 | @result{} 0.223890779141236 | |
274 | @end lisp | |
275 | ||
276 | The filename @file{./libbessel.so} should be pointing to the shared | |
277 | library produced with the @code{gcc} command above, of course. The | |
278 | second line of the Guile interaction will call the | |
279 | @code{init_math_bessel} function which in turn will register the C | |
280 | function @code{j0_wrapper} with the Guile interpreter under the name | |
281 | @code{j0}. This function becomes immediately available and we can call | |
282 | it from Scheme. | |
283 | ||
284 | Fun, isn't it? But we are only half way there. This is what | |
285 | @code{apropos} has to say about @code{j0}: | |
286 | ||
287 | @smallexample | |
288 | (apropos "j0") | |
289 | @print{} (guile-user): j0 #<primitive-procedure j0> | |
290 | @end smallexample | |
291 | ||
292 | As you can see, @code{j0} is contained in the root module, where all | |
293 | the other Guile primitives like @code{display}, etc live. In general, | |
294 | a primitive is put into whatever module is the @dfn{current module} at | |
295 | the time @code{scm_c_define_gsubr} is called. | |
296 | ||
297 | A compiled module should have a specially named @dfn{module init | |
298 | function}. Guile knows about this special name and will call that | |
299 | function automatically after having linked in the shared library. For | |
300 | our example, we replace @code{init_math_bessel} with the following code in | |
301 | @file{bessel.c}: | |
302 | ||
303 | @smallexample | |
304 | void | |
305 | init_math_bessel (void *unused) | |
306 | @{ | |
307 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
308 | scm_c_export ("j0", NULL); | |
309 | @} | |
310 | ||
311 | void | |
312 | scm_init_math_bessel_module () | |
313 | @{ | |
314 | scm_c_define_module ("math bessel", init_math_bessel, NULL); | |
315 | @} | |
316 | @end smallexample | |
317 | ||
318 | The general pattern for the name of a module init function is: | |
319 | @samp{scm_init_}, followed by the name of the module where the | |
320 | individual hierarchical components are concatenated with underscores, | |
321 | followed by @samp{_module}. | |
322 | ||
323 | After @file{libbessel.so} has been rebuilt, we need to place the shared | |
324 | library into the right place. | |
325 | ||
326 | Once the module has been correctly installed, it should be possible to | |
327 | use it like this: | |
328 | ||
329 | @smallexample | |
330 | guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module") | |
331 | guile> (use-modules (math bessel)) | |
332 | guile> (j0 2) | |
333 | 0.223890779141236 | |
334 | guile> (apropos "j0") | |
335 | @print{} (math bessel): j0 #<primitive-procedure j0> | |
336 | @end smallexample | |
337 | ||
338 | That's it! | |
339 | ||
726b8ba3 AW |
340 | |
341 | @node Modules and Extensions | |
342 | @subsection Modules and Extensions | |
343 | ||
344 | The new primitives that you add to Guile with @code{scm_c_define_gsubr} | |
345 | (@pxref{Primitive Procedures}) or with any of the other mechanisms are | |
346 | placed into the module that is current when the | |
347 | @code{scm_c_define_gsubr} is executed. Extensions loaded from the REPL, | |
348 | for example, will be placed into the @code{(guile-user)} module, if the | |
349 | REPL module was not changed. | |
350 | ||
351 | To define C primitives within a specific module, the simplest way is: | |
352 | ||
353 | @example | |
354 | (define-module (foo bar)) | |
355 | (load-extension "foobar-c-code" "foo_bar_init") | |
356 | @end example | |
357 | ||
e5f7f675 | 358 | @cindex extensiondir |
726b8ba3 AW |
359 | When loaded with @code{(use-modules (foo bar))}, the |
360 | @code{load-extension} call looks for the @file{foobar-c-code.so} (etc) | |
e5f7f675 AW |
361 | object file in Guile's @code{extensiondir}, which is usually a |
362 | subdirectory of the @code{libdir}. For example, if your libdir is | |
363 | @file{/usr/lib}, the @code{extensiondir} for the Guile 2.0.@var{x} | |
364 | series will be @file{/usr/lib/guile/2.0/}. | |
365 | ||
366 | The extension path includes the major and minor version of Guile (the | |
367 | ``effective version''), because Guile guarantees compatibility within a | |
368 | given effective version. This allows you to install different versions | |
369 | of the same extension for different versions of Guile. | |
370 | ||
371 | If the extension is not found in the @code{extensiondir}, Guile will | |
372 | also search the standard system locations, such as @file{/usr/lib} or | |
373 | @file{/usr/local/lib}. It is preferable, however, to keep your extension | |
374 | out of the system library path, to prevent unintended interference with | |
375 | other dynamically-linked C libraries. | |
726b8ba3 AW |
376 | |
377 | If someone installs your module to a non-standard location then the | |
378 | object file won't be found. You can address this by inserting the | |
379 | install location in the @file{foo/bar.scm} file. This is convenient | |
380 | for the user and also guarantees the intended object is read, even if | |
381 | stray older or newer versions are in the loader's path. | |
382 | ||
383 | The usual way to specify an install location is with a @code{prefix} | |
384 | at the configure stage, for instance @samp{./configure prefix=/opt} | |
385 | results in library files as say @file{/opt/lib/foobar-c-code.so}. | |
386 | When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU | |
387 | Autoconf Manual}), the library location is in a @code{libdir} | |
388 | variable. Its value is intended to be expanded by @command{make}, and | |
389 | can by substituted into a source file like @file{foo.scm.in} | |
390 | ||
391 | @example | |
392 | (define-module (foo bar)) | |
e5f7f675 | 393 | (load-extension "XXextensiondirXX/foobar-c-code" "foo_bar_init") |
726b8ba3 AW |
394 | @end example |
395 | ||
396 | @noindent | |
397 | with the following in a @file{Makefile}, using @command{sed} | |
398 | (@pxref{Top, , Introduction, sed, SED, A Stream Editor}), | |
399 | ||
400 | @example | |
401 | foo.scm: foo.scm.in | |
e5f7f675 | 402 | sed 's|XXextensiondirXX|$(libdir)/guile/2.0|' <foo.scm.in >foo.scm |
726b8ba3 AW |
403 | @end example |
404 | ||
e5f7f675 | 405 | The actual pattern @code{XXextensiondirXX} is arbitrary, it's only something |
726b8ba3 AW |
406 | which doesn't otherwise occur. If several modules need the value, it |
407 | can be easier to create one @file{foo/config.scm} with a define of the | |
e5f7f675 | 408 | @code{extensiondir} location, and use that as required. |
726b8ba3 AW |
409 | |
410 | @example | |
411 | (define-module (foo config)) | |
e5f7f675 | 412 | (define-public foo-config-extensiondir "XXextensiondirXX"") |
726b8ba3 AW |
413 | @end example |
414 | ||
415 | Such a file might have other locations too, for instance a data | |
416 | directory for auxiliary files, or @code{localedir} if the module has | |
417 | its own @code{gettext} message catalogue | |
418 | (@pxref{Internationalization}). | |
419 | ||
726b8ba3 AW |
420 | It will be noted all of the above requires that the Scheme code to be |
421 | found in @code{%load-path} (@pxref{Build Config}). Presently it's | |
422 | left up to the system administrator or each user to augment that path | |
423 | when installing Guile modules in non-default locations. But having | |
424 | reached the Scheme code, that code should take care of hitting any of | |
425 | its own private files etc. | |
426 | ||
726b8ba3 | 427 | |
71725997 AW |
428 | @node Foreign Pointers |
429 | @subsection Foreign Pointers | |
430 | ||
431 | The previous sections have shown how Guile can be extended at runtime by | |
432 | loading compiled C extensions. This approach is all well and good, but | |
433 | wouldn't it be nice if we didn't have to write any C at all? This | |
434 | section takes up the problem of accessing C values from Scheme, and the | |
435 | next discusses C functions. | |
436 | ||
437 | @menu | |
b9264dc5 | 438 | * Foreign Types:: Expressing C types in Scheme. |
183a2a22 | 439 | * Foreign Variables:: Pointers to C symbols. |
b9264dc5 AW |
440 | * Void Pointers and Byte Access:: Pointers into the ether. |
441 | * Foreign Structs:: Packing and unpacking structs. | |
71725997 AW |
442 | @end menu |
443 | ||
444 | @node Foreign Types | |
445 | @subsubsection Foreign Types | |
446 | ||
447 | The first impedance mismatch that one sees between C and Scheme is that | |
448 | in C, the storage locations (variables) are typed, but in Scheme types | |
449 | are associated with values, not variables. @xref{Values and Variables}. | |
450 | ||
183a2a22 LC |
451 | So when describing a C function or a C structure so that it can be |
452 | accessed from Scheme, the data types of the parameters or fields must be | |
453 | passed explicitly. | |
71725997 AW |
454 | |
455 | These ``C type values'' may be constructed using the constants and | |
456 | procedures from the @code{(system foreign)} module, which may be loaded | |
457 | like this: | |
458 | ||
459 | @example | |
460 | (use-modules (system foreign)) | |
461 | @end example | |
462 | ||
463 | @code{(system foreign)} exports a number of values expressing the basic | |
464 | C types: | |
465 | ||
b9264dc5 | 466 | @defvr {Scheme Variable} int8 |
71725997 AW |
467 | @defvrx {Scheme Variable} uint8 |
468 | @defvrx {Scheme Variable} uint16 | |
469 | @defvrx {Scheme Variable} int16 | |
470 | @defvrx {Scheme Variable} uint32 | |
471 | @defvrx {Scheme Variable} int32 | |
472 | @defvrx {Scheme Variable} uint64 | |
473 | @defvrx {Scheme Variable} int64 | |
b9264dc5 AW |
474 | @defvrx {Scheme Variable} float |
475 | @defvrx {Scheme Variable} double | |
183a2a22 LC |
476 | These values represent the C numeric types of the specified sizes and |
477 | signednesses. | |
71725997 AW |
478 | @end defvr |
479 | ||
480 | In addition there are some convenience bindings for indicating types of | |
481 | platform-dependent size: | |
482 | ||
483 | @defvr {Scheme Variable} int | |
484 | @defvrx {Scheme Variable} unsigned-int | |
485 | @defvrx {Scheme Variable} long | |
486 | @defvrx {Scheme Variable} unsigned-long | |
487 | @defvrx {Scheme Variable} size_t | |
488 | Values exported by the @code{(system foreign)} module, representing C | |
489 | numeric types. For example, @code{long} may be @code{equal?} to | |
490 | @code{int64} on a 64-bit platform. | |
491 | @end defvr | |
492 | ||
183a2a22 LC |
493 | @defvr {Scheme Variable} void |
494 | The @code{void} type. It can be used as the first argument to | |
2ee07358 | 495 | @code{pointer->procedure} to wrap a C function that returns nothing. |
183a2a22 LC |
496 | @end defvr |
497 | ||
1f4f7674 LC |
498 | In addition, the symbol @code{*} is used by convention to denote pointer |
499 | types. Procedures detailed in the following sections, such as | |
500 | @code{pointer->procedure}, accept it as a type descriptor. | |
501 | ||
71725997 AW |
502 | @node Foreign Variables |
503 | @subsubsection Foreign Variables | |
504 | ||
e5f7f675 AW |
505 | Pointers to variables in the current address space may be looked up |
506 | dynamically using @code{dynamic-pointer}. | |
726b8ba3 | 507 | |
183a2a22 LC |
508 | @deffn {Scheme Procedure} dynamic-pointer name dobj |
509 | @deffnx {C Function} scm_dynamic_pointer (name, dobj) | |
510 | Return a ``wrapped pointer'' for the symbol @var{name} in the shared | |
511 | object referred to by @var{dobj}. The returned pointer points to a C | |
512 | object. | |
726b8ba3 | 513 | |
726b8ba3 AW |
514 | Regardless whether your C compiler prepends an underscore @samp{_} to the global |
515 | names in a program, you should @strong{not} include this underscore in | |
516 | @var{name} since it will be added automatically when necessary. | |
517 | @end deffn | |
518 | ||
71725997 AW |
519 | For example, currently Guile has a variable, @code{scm_numptob}, as part |
520 | of its API. It is declared as a C @code{long}. So, to create a handle | |
521 | pointing to that foreign value, we do: | |
522 | ||
523 | @example | |
524 | (use-modules (system foreign)) | |
183a2a22 | 525 | (define numptob (dynamic-pointer "scm_numptob" (dynamic-link))) |
71725997 | 526 | numptob |
e5f7f675 | 527 | @result{} #<pointer 0x7fb35b1b4688> |
71725997 AW |
528 | @end example |
529 | ||
e5f7f675 AW |
530 | (The next section discusses ways to dereference pointers.) |
531 | ||
b9264dc5 | 532 | A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C |
183a2a22 | 533 | pointer. |
b9264dc5 | 534 | |
183a2a22 LC |
535 | @deffn {Scheme Procedure} pointer-address pointer |
536 | @deffnx {C Function} scm_pointer_address pointer | |
537 | Return the numerical value of @var{pointer}. | |
b9264dc5 AW |
538 | |
539 | @example | |
183a2a22 LC |
540 | (pointer-address numptob) |
541 | @result{} 139984413364296 ; YMMV | |
b9264dc5 AW |
542 | @end example |
543 | @end deffn | |
544 | ||
183a2a22 LC |
545 | @deffn {Scheme Procedure} make-pointer address [finalizer] |
546 | Return a foreign pointer object pointing to @var{address}. If | |
547 | @var{finalizer} is passed, it should be a pointer to a one-argument C | |
548 | function that will be called when the pointer object becomes | |
549 | unreachable. | |
550 | @end deffn | |
b9264dc5 | 551 | |
6e097560 LC |
552 | @deffn {Scheme Procedure} pointer? obj |
553 | Return @code{#t} if @var{obj} is a pointer object, @code{#f} otherwise. | |
554 | @end deffn | |
555 | ||
183a2a22 LC |
556 | @defvr {Scheme Variable} %null-pointer |
557 | A foreign pointer whose value is 0. | |
558 | @end defvr | |
b9264dc5 | 559 | |
183a2a22 LC |
560 | @deffn {Scheme Procedure} null-pointer? pointer |
561 | Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise. | |
b9264dc5 AW |
562 | @end deffn |
563 | ||
b9264dc5 AW |
564 | |
565 | @node Void Pointers and Byte Access | |
566 | @subsubsection Void Pointers and Byte Access | |
567 | ||
183a2a22 LC |
568 | Wrapped pointers are untyped, so they are essentially equivalent to C |
569 | @code{void} pointers. As in C, the memory region pointed to by a | |
570 | pointer can be accessed at the byte level. This is achieved using | |
571 | @emph{bytevectors} (@pxref{Bytevectors}). The @code{(rnrs bytevector)} | |
572 | module contains procedures that can be used to convert byte sequences to | |
e5f7f675 | 573 | Scheme objects such as strings, floating point numbers, or integers. |
71725997 | 574 | |
183a2a22 LC |
575 | @deffn {Scheme Procedure} pointer->bytevector pointer len [offset [uvec_type]] |
576 | @deffnx {C Function} scm_foreign_to_bytevector pointer len offset uvec_type | |
577 | Return a bytevector aliasing the @var{len} bytes pointed to by | |
578 | @var{pointer}. | |
71725997 AW |
579 | |
580 | The user may specify an alternate default interpretation for | |
581 | the memory by passing the @var{uvec_type} argument, to indicate | |
582 | that the memory is an array of elements of that type. | |
583 | @var{uvec_type} should be something that | |
584 | @code{uniform-vector-element-type} would return, like @code{f32} | |
585 | or @code{s16}. | |
586 | ||
183a2a22 LC |
587 | When @var{offset} is passed, it specifies the offset in bytes relative |
588 | to @var{pointer} of the memory region aliased by the returned | |
589 | bytevector. | |
71725997 AW |
590 | |
591 | Mutating the returned bytevector mutates the memory pointed to by | |
183a2a22 | 592 | @var{pointer}, so buckle your seatbelts. |
71725997 AW |
593 | @end deffn |
594 | ||
183a2a22 LC |
595 | @deffn {Scheme Procedure} bytevector->pointer bv [offset] |
596 | @deffnx {C Function} scm_bytevector_to_pointer bv offset | |
597 | Return a pointer pointer aliasing the memory pointed to by @var{bv} or | |
598 | @var{offset} bytes after @var{bv} when @var{offset} is passed. | |
599 | @end deffn | |
71725997 | 600 | |
183a2a22 | 601 | In addition to these primitives, convenience procedures are available: |
b9264dc5 | 602 | |
183a2a22 LC |
603 | @deffn {Scheme Procedure} dereference-pointer pointer |
604 | Assuming @var{pointer} points to a memory region that holds a pointer, | |
605 | return this pointer. | |
71725997 AW |
606 | @end deffn |
607 | ||
fa2a89a6 LC |
608 | @deffn {Scheme Procedure} string->pointer string |
609 | Return a foreign pointer to a nul-terminated copy of @var{string} in the | |
610 | current locale encoding. The C string is freed when the returned | |
611 | foreign pointer becomes unreachable. | |
612 | ||
613 | This is the Scheme equivalent of @code{scm_to_locale_string}. | |
614 | @end deffn | |
615 | ||
616 | @deffn {Scheme Procedure} pointer->string pointer | |
617 | Return the string representing the C nul-terminated string | |
618 | pointed to by @var{pointer}. The C string is assumed to be | |
619 | in the current locale encoding. | |
620 | ||
621 | This is the Scheme equivalent of @code{scm_from_locale_string}. | |
622 | @end deffn | |
623 | ||
1f4f7674 LC |
624 | @cindex wrapped pointer types |
625 | Most object-oriented C libraries use pointers to specific data | |
626 | structures to identify objects. It is useful in such cases to reify the | |
627 | different pointer types as disjoint Scheme types. The | |
628 | @code{define-wrapped-pointer-type} macro simplifies this. | |
629 | ||
de6fb187 | 630 | @deffn {Scheme Syntax} define-wrapped-pointer-type type-name pred wrap unwrap print |
1f4f7674 LC |
631 | Define helper procedures to wrap pointer objects into Scheme objects |
632 | with a disjoint type. Specifically, this macro defines: | |
633 | ||
634 | @itemize | |
635 | @item @var{pred}, a predicate for the new Scheme type; | |
636 | @item @var{wrap}, a procedure that takes a pointer object and returns an | |
637 | object that satisfies @var{pred}; | |
638 | @item @var{unwrap}, which does the reverse. | |
639 | @end itemize | |
640 | ||
641 | @var{wrap} preserves pointer identity, for two pointer objects @var{p1} | |
642 | and @var{p2} that are @code{equal?}, @code{(eq? (@var{wrap} @var{p1}) | |
643 | (@var{wrap} @var{p2})) @result{} #t}. | |
644 | ||
645 | Finally, @var{print} should name a user-defined procedure to print such | |
646 | objects. The procedure is passed the wrapped object and a port to write | |
647 | to. | |
648 | ||
649 | For example, assume we are wrapping a C library that defines a type, | |
650 | @code{bottle_t}, and functions that can be passed @code{bottle_t *} | |
651 | pointers to manipulate them. We could write: | |
652 | ||
653 | @example | |
de6fb187 LC |
654 | (define-wrapped-pointer-type bottle |
655 | bottle? | |
1f4f7674 LC |
656 | wrap-bottle unwrap-bottle |
657 | (lambda (b p) | |
658 | (format p "#<bottle of ~a ~x>" | |
659 | (bottle-contents b) | |
660 | (pointer-address (unwrap-foo b))))) | |
661 | ||
662 | (define grab-bottle | |
663 | ;; Wrapper for `bottle_t *grab (void)'. | |
664 | (let ((grab (pointer->procedure '* | |
665 | (dynamic-func "grab_bottle" libbottle) | |
666 | '()))) | |
667 | (lambda () | |
668 | "Return a new bottle." | |
669 | (wrap-bottle (grab))))) | |
670 | ||
671 | (define bottle-contents | |
672 | ;; Wrapper for `const char *bottle_contents (bottle_t *)'. | |
673 | (let ((contents (pointer->procedure '* | |
674 | (dynamic-func "bottle_contents" | |
675 | libbottle) | |
676 | '(*)))) | |
677 | (lambda (b) | |
678 | "Return the contents of B." | |
679 | (pointer->string (contents (unwrap-bottle b)))))) | |
680 | ||
681 | (write (grab-bottle)) | |
682 | @result{} #<bottle of Ch@^ateau Haut-Brion 803d36> | |
683 | @end example | |
684 | ||
685 | In this example, @code{grab-bottle} is guaranteed to return a genuine | |
686 | @code{bottle} object satisfying @code{bottle?}. Likewise, | |
687 | @code{bottle-contents} errors out when its argument is not a genuine | |
688 | @code{bottle} object. | |
689 | @end deffn | |
690 | ||
183a2a22 LC |
691 | Going back to the @code{scm_numptob} example above, here is how we can |
692 | read its value as a C @code{long} integer: | |
693 | ||
694 | @example | |
695 | (use-modules (rnrs bytevectors)) | |
696 | ||
697 | (bytevector-uint-ref (pointer->bytevector numptob (sizeof long)) | |
698 | 0 (native-endianness) | |
699 | (sizeof long)) | |
700 | @result{} 8 | |
701 | @end example | |
702 | ||
703 | If we wanted to corrupt Guile's internal state, we could set | |
704 | @code{scm_numptob} to another value; but we shouldn't, because that | |
705 | variable is not meant to be set. Indeed this point applies more widely: | |
706 | the C API is a dangerous place to be. Not only might setting a value | |
707 | crash your program, simply accessing the data pointed to by a dangling | |
708 | pointer or similar can prove equally disastrous. | |
71725997 | 709 | |
b9264dc5 AW |
710 | @node Foreign Structs |
711 | @subsubsection Foreign Structs | |
71725997 | 712 | |
b9264dc5 AW |
713 | Finally, one last note on foreign values before moving on to actually |
714 | calling foreign functions. Sometimes you need to deal with C structs, | |
715 | which requires interpreting each element of the struct according to the | |
716 | its type, offset, and alignment. Guile has some primitives to support | |
717 | this. | |
718 | ||
719 | @deffn {Scheme Procedure} sizeof type | |
720 | @deffnx {C Function} scm_sizeof type | |
721 | Return the size of @var{type}, in bytes. | |
722 | ||
723 | @var{type} should be a valid C type, like @code{int}. | |
724 | Alternately @var{type} may be the symbol @code{*}, in which | |
725 | case the size of a pointer is returned. @var{type} may | |
726 | also be a list of types, in which case the size of a | |
727 | @code{struct} with ABI-conventional packing is returned. | |
728 | @end deffn | |
71725997 | 729 | |
b9264dc5 AW |
730 | @deffn {Scheme Procedure} alignof type |
731 | @deffnx {C Function} scm_alignof type | |
732 | Return the alignment of @var{type}, in bytes. | |
733 | ||
734 | @var{type} should be a valid C type, like @code{int}. | |
735 | Alternately @var{type} may be the symbol @code{*}, in which | |
736 | case the alignment of a pointer is returned. @var{type} may | |
737 | also be a list of types, in which case the alignment of a | |
738 | @code{struct} with ABI-conventional packing is returned. | |
71725997 AW |
739 | @end deffn |
740 | ||
b9264dc5 AW |
741 | Guile also provides some convenience methods to pack and unpack foreign |
742 | pointers wrapping C structs. | |
71725997 | 743 | |
b9264dc5 AW |
744 | @deffn {Scheme Procedure} make-c-struct types vals |
745 | Create a foreign pointer to a C struct containing @var{vals} with types | |
746 | @code{types}. | |
747 | ||
748 | @var{vals} and @code{types} should be lists of the same length. | |
749 | @end deffn | |
750 | ||
751 | @deffn {Scheme Procedure} parse-c-struct foreign types | |
752 | Parse a foreign pointer to a C struct, returning a list of values. | |
753 | ||
754 | @code{types} should be a list of C types. | |
755 | @end deffn | |
756 | ||
757 | For example, to create and parse the equivalent of a @code{struct @{ | |
758 | int64_t a; uint8_t b; @}}: | |
71725997 AW |
759 | |
760 | @example | |
b9264dc5 AW |
761 | (parse-c-struct (make-c-struct (list int64 uint8) |
762 | (list 300 43)) | |
763 | (list int64 uint8)) | |
764 | @result{} (300 43) | |
71725997 | 765 | @end example |
71725997 | 766 | |
b9264dc5 AW |
767 | As yet, Guile only has convenience routines to support |
768 | conventionally-packed structs. But given the @code{bytevector->foreign} | |
769 | and @code{foreign->bytevector} routines, one can create and parse | |
770 | tightly packed structs and unions by hand. See the code for | |
771 | @code{(system foreign)} for details. | |
71725997 | 772 | |
726b8ba3 AW |
773 | |
774 | @node Dynamic FFI | |
775 | @subsection Dynamic FFI | |
776 | ||
71725997 AW |
777 | Of course, the land of C is not all nouns and no verbs: there are |
778 | functions too, and Guile allows you to call them. | |
779 | ||
2ee07358 LC |
780 | @deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types |
781 | @deffnx {C Procedure} scm_pointer_to_procedure return_type func_ptr arg_types | |
71725997 AW |
782 | Make a foreign function. |
783 | ||
784 | Given the foreign void pointer @var{func_ptr}, its argument and | |
785 | return types @var{arg_types} and @var{return_type}, return a | |
786 | procedure that will pass arguments to the foreign function | |
787 | and return appropriate values. | |
788 | ||
789 | @var{arg_types} should be a list of foreign types. | |
b9264dc5 AW |
790 | @code{return_type} should be a foreign type. @xref{Foreign Types}, for |
791 | more information on foreign types. | |
71725997 AW |
792 | @end deffn |
793 | ||
b9264dc5 | 794 | Here is a better definition of @code{(math bessel)}: |
726b8ba3 | 795 | |
b9264dc5 AW |
796 | @example |
797 | (define-module (math bessel) | |
798 | #:use-module (system foreign) | |
799 | #:export (j0)) | |
71725997 | 800 | |
b9264dc5 | 801 | (define libm (dynamic-link "libm")) |
71725997 | 802 | |
b9264dc5 | 803 | (define j0 |
2ee07358 LC |
804 | (pointer->procedure double |
805 | (dynamic-func "j0" libm) | |
806 | (list double))) | |
b9264dc5 | 807 | @end example |
71725997 | 808 | |
b9264dc5 | 809 | That's it! No C at all. |
71725997 | 810 | |
b9264dc5 AW |
811 | Numeric arguments and return values from foreign functions are |
812 | represented as Scheme values. For example, @code{j0} in the above | |
813 | example takes a Scheme number as its argument, and returns a Scheme | |
814 | number. | |
71725997 | 815 | |
b9264dc5 AW |
816 | Pointers may be passed to and returned from foreign functions as well. |
817 | In that case the type of the argument or return value should be the | |
818 | symbol @code{*}, indicating a pointer. For example, the following | |
819 | code makes @code{memcpy} available to Scheme: | |
71725997 | 820 | |
b9264dc5 AW |
821 | @example |
822 | (define memcpy | |
823 | (let ((this (dynamic-link))) | |
2ee07358 LC |
824 | (pointer->procedure '* |
825 | (dynamic-func "memcpy" this) | |
826 | (list '* '* size_t)))) | |
b9264dc5 AW |
827 | @end example |
828 | ||
829 | To invoke @code{memcpy}, one must pass it foreign pointers: | |
830 | ||
831 | @example | |
07d22c02 | 832 | (use-modules (rnrs bytevectors)) |
71725997 | 833 | |
183a2a22 LC |
834 | (define src-bits |
835 | (u8-list->bytevector '(0 1 2 3 4 5 6 7))) | |
b9264dc5 | 836 | (define src |
183a2a22 | 837 | (bytevector->pointer src-bits)) |
b9264dc5 | 838 | (define dest |
183a2a22 | 839 | (bytevector->pointer (make-bytevector 16 0))) |
71725997 | 840 | |
183a2a22 | 841 | (memcpy dest src (bytevector-length src-bits)) |
b9264dc5 | 842 | |
183a2a22 | 843 | (bytevector->u8-list (pointer->bytevector dest 16)) |
b9264dc5 AW |
844 | @result{} (0 1 2 3 4 5 6 7 0 0 0 0 0 0 0 0) |
845 | @end example | |
846 | ||
847 | One may also pass structs as values, passing structs as foreign | |
848 | pointers. @xref{Foreign Structs}, for more information on how to express | |
849 | struct types and struct values. | |
850 | ||
851 | ``Out'' arguments are passed as foreign pointers. The memory pointed to | |
852 | by the foreign pointer is mutated in place. | |
71725997 AW |
853 | |
854 | @example | |
b9264dc5 AW |
855 | ;; struct timeval @{ |
856 | ;; time_t tv_sec; /* seconds */ | |
857 | ;; suseconds_t tv_usec; /* microseconds */ | |
858 | ;; @}; | |
859 | ;; assuming fields are of type "long" | |
860 | ||
861 | (define gettimeofday | |
2ee07358 | 862 | (let ((f (pointer->procedure |
b9264dc5 AW |
863 | int |
864 | (dynamic-func "gettimeofday" (dynamic-link)) | |
865 | (list '* '*))) | |
866 | (tv-type (list long long))) | |
867 | (lambda () | |
868 | (let* ((timeval (make-c-struct tv-type (list 0 0))) | |
869 | (ret (f timeval %null-pointer))) | |
870 | (if (zero? ret) | |
871 | (apply values (parse-c-struct timeval tv-type)) | |
872 | (error "gettimeofday returned an error" ret)))))) | |
873 | ||
874 | (gettimeofday) | |
875 | @result{} 1270587589 | |
876 | @result{} 499553 | |
71725997 AW |
877 | @end example |
878 | ||
b9264dc5 | 879 | As you can see, this interface to foreign functions is at a very low, |
33186356 LC |
880 | somewhat dangerous level@footnote{A contribution to Guile in the form of |
881 | a high-level FFI would be most welcome.}. | |
882 | ||
883 | @cindex callbacks | |
884 | The FFI can also work in the opposite direction: making Scheme | |
885 | procedures callable from C. This makes it possible to use Scheme | |
886 | procedures as ``callbacks'' expected by C function. | |
887 | ||
888 | @deffn {Scheme Procedure} procedure->pointer return-type proc arg-types | |
889 | @deffnx {C Function} scm_procedure_to_pointer (return_type, proc, arg_types) | |
890 | Return a pointer to a C function of type @var{return-type} | |
891 | taking arguments of types @var{arg-types} (a list) and | |
892 | behaving as a proxy to procedure @var{proc}. Thus | |
893 | @var{proc}'s arity, supported argument types, and return | |
894 | type should match @var{return-type} and @var{arg-types}. | |
895 | @end deffn | |
896 | ||
897 | As an example, here's how the C library's @code{qsort} array sorting | |
898 | function can be made accessible to Scheme (@pxref{Array Sort Function, | |
899 | @code{qsort},, libc, The GNU C Library Reference Manual}): | |
900 | ||
901 | @example | |
902 | (define qsort! | |
2ee07358 LC |
903 | (let ((qsort (pointer->procedure void |
904 | (dynamic-func "qsort" | |
905 | (dynamic-link)) | |
906 | (list '* size_t size_t '*)))) | |
33186356 LC |
907 | (lambda (bv compare) |
908 | ;; Sort bytevector BV in-place according to comparison | |
909 | ;; procedure COMPARE. | |
910 | (let ((ptr (procedure->pointer int | |
911 | (lambda (x y) | |
912 | ;; X and Y are pointers so, | |
913 | ;; for convenience, dereference | |
914 | ;; them before calling COMPARE. | |
915 | (compare (dereference-uint8* x) | |
916 | (dereference-uint8* y))) | |
917 | (list '* '*)))) | |
918 | (qsort (bytevector->pointer bv) | |
919 | (bytevector-length bv) 1 ;; we're sorting bytes | |
920 | ptr))))) | |
921 | ||
922 | (define (dereference-uint8* ptr) | |
923 | ;; Helper function: dereference the byte pointed to by PTR. | |
924 | (let ((b (pointer->bytevector ptr 1))) | |
925 | (bytevector-u8-ref b 0))) | |
926 | ||
927 | (define bv | |
928 | ;; An unsorted array of bytes. | |
929 | (u8-list->bytevector '(7 1 127 3 5 4 77 2 9 0))) | |
930 | ||
931 | ;; Sort BV. | |
932 | (qsort! bv (lambda (x y) (- x y))) | |
933 | ||
934 | ;; Let's see what the sorted array looks like: | |
935 | (bytevector->u8-list bv) | |
936 | @result{} (0 1 2 3 4 5 7 9 77 127) | |
937 | @end example | |
938 | ||
939 | And voil@`a! | |
940 | ||
941 | Note that @code{procedure->pointer} is not supported (and not defined) | |
942 | on a few exotic architectures. Thus, user code may need to check | |
943 | @code{(defined? 'procedure->pointer)}. Nevertheless, it is available on | |
944 | many architectures, including (as of libffi 3.0.9) x86, ia64, SPARC, | |
945 | PowerPC, ARM, and MIPS, to name a few. | |
71725997 | 946 | |
726b8ba3 AW |
947 | @c Local Variables: |
948 | @c TeX-master: "guile.texi" | |
949 | @c End: |