2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008,
4 @c 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Foreign Function Interface
8 @section Foreign Function Interface
9 @cindex foreign function interface
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.
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
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.
27 * Foreign Pointers:: Accessing global variables.
28 * Dynamic FFI:: Calling arbitrary C functions.
32 @node Foreign Libraries
33 @subsection Foreign Libraries
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'.
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.
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.}
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.
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
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}.
82 @var{library} should not contain an extension such as @code{.so}. The
83 correct file name extension for the host operating system is provided
84 automatically, according to libltdl's rules (@pxref{Libltdl interface,
85 lt_dlopenext, @code{lt_dlopenext}, libtool, Shared Library Support for
88 When @var{library} is omitted, a @dfn{global symbol handle} is returned. This
89 handle provides access to the symbols available to the program at run-time,
90 including those exported by the program itself and the shared libraries already
94 @deffn {Scheme Procedure} dynamic-object? obj
95 @deffnx {C Function} scm_dynamic_object_p (obj)
96 Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
100 @deffn {Scheme Procedure} dynamic-unlink dobj
101 @deffnx {C Function} scm_dynamic_unlink (dobj)
102 Unlink the indicated object file from the application. The
103 argument @var{dobj} must have been obtained by a call to
104 @code{dynamic-link}. After @code{dynamic-unlink} has been
105 called on @var{dobj}, its content is no longer accessible.
109 (define libgl-obj (dynamic-link "libGL"))
111 @result{} #<dynamic-object "libGL">
112 (dynamic-unlink libGL-obj)
114 @result{} #<dynamic-object "libGL" (unlinked)>
117 As you can see, after calling @code{dynamic-unlink} on a dynamically
118 linked library, it is marked as @samp{(unlinked)} and you are no longer
119 able to use it with @code{dynamic-call}, etc. Whether the library is
120 really removed from you program is system-dependent and will generally
121 not happen when some other parts of your program still use it.
123 When dynamic linking is disabled or not supported on your system,
124 the above functions throw errors, but they are still available.
127 @node Foreign Functions
128 @subsection Foreign Functions
130 The most natural thing to do with a dynamic library is to grovel around
131 in it for a function pointer: a @dfn{foreign function}.
132 @code{dynamic-func} exists for that purpose.
134 @deffn {Scheme Procedure} dynamic-func name dobj
135 @deffnx {C Function} scm_dynamic_func (name, dobj)
136 Return a ``handle'' for the func @var{name} in the shared object referred to
137 by @var{dobj}. The handle can be passed to @code{dynamic-call} to
138 actually call the function.
140 Regardless whether your C compiler prepends an underscore @samp{_} to the global
141 names in a program, you should @strong{not} include this underscore in
142 @var{name} since it will be added automatically when necessary.
145 Guile has static support for calling functions with no arguments,
148 @deffn {Scheme Procedure} dynamic-call func dobj
149 @deffnx {C Function} scm_dynamic_call (func, dobj)
150 Call the C function indicated by @var{func} and @var{dobj}.
151 The function is passed no arguments and its return value is
152 ignored. When @var{function} is something returned by
153 @code{dynamic-func}, call that function and ignore @var{dobj}.
154 When @var{func} is a string , look it up in @var{dynobj}; this
157 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
161 @code{dynamic-call} is not very powerful. It is mostly intended to be
162 used for calling specially written initialization functions that will
163 then add new primitives to Guile. For example, we do not expect that you
164 will dynamically link @file{libX11} with @code{dynamic-link} and then
165 construct a beautiful graphical user interface just by using
166 @code{dynamic-call}. Instead, the usual way would be to write a special
167 Guile-to-X11 glue library that has intimate knowledge about both Guile
168 and X11 and does whatever is necessary to make them inter-operate
169 smoothly. This glue library could then be dynamically linked into a
170 vanilla Guile interpreter and activated by calling its initialization
171 function. That function would add all the new types and primitives to
172 the Guile interpreter that it has to offer.
174 (There is actually another, better option: simply to create a
175 @file{libX11} wrapper in Scheme via the dynamic FFI. @xref{Dynamic FFI},
176 for more information.)
178 Given some set of C extensions to Guile, the next logical step is to
179 integrate these glue libraries into the module system of Guile so that
180 you can load new primitives into a running system just as you can load
183 @deffn {Scheme Procedure} load-extension lib init
184 @deffnx {C Function} scm_load_extension (lib, init)
185 Load and initialize the extension designated by LIB and INIT.
186 When there is no pre-registered function for LIB/INIT, this is
190 (dynamic-call INIT (dynamic-link LIB))
193 When there is a pre-registered function, that function is called
196 Normally, there is no pre-registered function. This option exists
197 only for situations where dynamic linking is unavailable or unwanted.
198 In that case, you would statically link your program with the desired
199 library, and register its init function right after Guile has been
202 As for @code{dynamic-link}, @var{lib} should not contain any suffix such
203 as @code{.so} (@pxref{Foreign Libraries, dynamic-link}). It
204 should also not contain any directory components. Libraries that
205 implement Guile Extensions should be put into the normal locations for
206 shared libraries. We recommend to use the naming convention
207 @file{libguile-bla-blum} for a extension related to a module @code{(bla
210 The normal way for a extension to be used is to write a small Scheme
211 file that defines a module, and to load the extension into this
212 module. When the module is auto-loaded, the extension is loaded as
216 (define-module (bla blum))
218 (load-extension "libguile-bla-blum" "bla_init_blum")
223 @subsection C Extensions
225 The most interesting application of dynamically linked libraries is
226 probably to use them for providing @emph{compiled code modules} to
227 Scheme programs. As much fun as programming in Scheme is, every now and
228 then comes the need to write some low-level C stuff to make Scheme even
231 Not only can you put these new primitives into their own module (see the
232 previous section), you can even put them into a shared library that is
233 only then linked to your running Guile image when it is actually
236 An example will hopefully make everything clear. Suppose we want to
237 make the Bessel functions of the C library available to Scheme in the
238 module @samp{(math bessel)}. First we need to write the appropriate
239 glue code to convert the arguments and return values of the functions
240 from Scheme to C and back. Additionally, we need a function that will
241 add them to the set of Guile primitives. Because this is just an
242 example, we will only implement this for the @code{j0} function.
246 #include <libguile.h>
251 return scm_from_double (j0 (scm_to_double (x, "j0")));
257 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
261 We can already try to bring this into action by manually calling the low
262 level functions for performing dynamic linking. The C source file needs
263 to be compiled into a shared library. Here is how to do it on
264 GNU/Linux, please refer to the @code{libtool} documentation for how to
265 create dynamically linkable libraries portably.
268 gcc -shared -o libbessel.so -fPIC bessel.c
274 (define bessel-lib (dynamic-link "./libbessel.so"))
275 (dynamic-call "init_math_bessel" bessel-lib)
277 @result{} 0.223890779141236
280 The filename @file{./libbessel.so} should be pointing to the shared
281 library produced with the @code{gcc} command above, of course. The
282 second line of the Guile interaction will call the
283 @code{init_math_bessel} function which in turn will register the C
284 function @code{j0_wrapper} with the Guile interpreter under the name
285 @code{j0}. This function becomes immediately available and we can call
288 Fun, isn't it? But we are only half way there. This is what
289 @code{apropos} has to say about @code{j0}:
293 @print{} (guile-user): j0 #<primitive-procedure j0>
296 As you can see, @code{j0} is contained in the root module, where all
297 the other Guile primitives like @code{display}, etc live. In general,
298 a primitive is put into whatever module is the @dfn{current module} at
299 the time @code{scm_c_define_gsubr} is called.
301 A compiled module should have a specially named @dfn{module init
302 function}. Guile knows about this special name and will call that
303 function automatically after having linked in the shared library. For
304 our example, we replace @code{init_math_bessel} with the following code in
309 init_math_bessel (void *unused)
311 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
312 scm_c_export ("j0", NULL);
316 scm_init_math_bessel_module ()
318 scm_c_define_module ("math bessel", init_math_bessel, NULL);
322 The general pattern for the name of a module init function is:
323 @samp{scm_init_}, followed by the name of the module where the
324 individual hierarchical components are concatenated with underscores,
325 followed by @samp{_module}.
327 After @file{libbessel.so} has been rebuilt, we need to place the shared
328 library into the right place.
330 Once the module has been correctly installed, it should be possible to
334 guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
335 guile> (use-modules (math bessel))
338 guile> (apropos "j0")
339 @print{} (math bessel): j0 #<primitive-procedure j0>
345 @node Modules and Extensions
346 @subsection Modules and Extensions
348 The new primitives that you add to Guile with @code{scm_c_define_gsubr}
349 (@pxref{Primitive Procedures}) or with any of the other mechanisms are
350 placed into the module that is current when the
351 @code{scm_c_define_gsubr} is executed. Extensions loaded from the REPL,
352 for example, will be placed into the @code{(guile-user)} module, if the
353 REPL module was not changed.
355 To define C primitives within a specific module, the simplest way is:
358 (define-module (foo bar))
359 (load-extension "foobar-c-code" "foo_bar_init")
363 When loaded with @code{(use-modules (foo bar))}, the
364 @code{load-extension} call looks for the @file{foobar-c-code.so} (etc)
365 object file in Guile's @code{extensiondir}, which is usually a
366 subdirectory of the @code{libdir}. For example, if your libdir is
367 @file{/usr/lib}, the @code{extensiondir} for the Guile @value{EFFECTIVE-VERSION}.@var{x}
368 series will be @file{/usr/lib/guile/@value{EFFECTIVE-VERSION}/}.
370 The extension path includes the major and minor version of Guile (the
371 ``effective version''), because Guile guarantees compatibility within a
372 given effective version. This allows you to install different versions
373 of the same extension for different versions of Guile.
375 If the extension is not found in the @code{extensiondir}, Guile will
376 also search the standard system locations, such as @file{/usr/lib} or
377 @file{/usr/local/lib}. It is preferable, however, to keep your extension
378 out of the system library path, to prevent unintended interference with
379 other dynamically-linked C libraries.
381 If someone installs your module to a non-standard location then the
382 object file won't be found. You can address this by inserting the
383 install location in the @file{foo/bar.scm} file. This is convenient
384 for the user and also guarantees the intended object is read, even if
385 stray older or newer versions are in the loader's path.
387 The usual way to specify an install location is with a @code{prefix}
388 at the configure stage, for instance @samp{./configure prefix=/opt}
389 results in library files as say @file{/opt/lib/foobar-c-code.so}.
390 When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU
391 Autoconf Manual}), the library location is in a @code{libdir}
392 variable. Its value is intended to be expanded by @command{make}, and
393 can by substituted into a source file like @file{foo.scm.in}
396 (define-module (foo bar))
397 (load-extension "XXextensiondirXX/foobar-c-code" "foo_bar_init")
401 with the following in a @file{Makefile}, using @command{sed}
402 (@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
406 sed 's|XXextensiondirXX|$(libdir)/guile/@value{EFFECTIVE-VERSION}|' <foo.scm.in >foo.scm
409 The actual pattern @code{XXextensiondirXX} is arbitrary, it's only something
410 which doesn't otherwise occur. If several modules need the value, it
411 can be easier to create one @file{foo/config.scm} with a define of the
412 @code{extensiondir} location, and use that as required.
415 (define-module (foo config))
416 (define-public foo-config-extensiondir "XXextensiondirXX"")
419 Such a file might have other locations too, for instance a data
420 directory for auxiliary files, or @code{localedir} if the module has
421 its own @code{gettext} message catalogue
422 (@pxref{Internationalization}).
424 It will be noted all of the above requires that the Scheme code to be
425 found in @code{%load-path} (@pxref{Load Paths}). Presently it's left up
426 to the system administrator or each user to augment that path when
427 installing Guile modules in non-default locations. But having reached
428 the Scheme code, that code should take care of hitting any of its own
432 @node Foreign Pointers
433 @subsection Foreign Pointers
435 The previous sections have shown how Guile can be extended at runtime by
436 loading compiled C extensions. This approach is all well and good, but
437 wouldn't it be nice if we didn't have to write any C at all? This
438 section takes up the problem of accessing C values from Scheme, and the
439 next discusses C functions.
442 * Foreign Types:: Expressing C types in Scheme.
443 * Foreign Variables:: Pointers to C symbols.
444 * Void Pointers and Byte Access:: Pointers into the ether.
445 * Foreign Structs:: Packing and unpacking structs.
449 @subsubsection Foreign Types
451 The first impedance mismatch that one sees between C and Scheme is that
452 in C, the storage locations (variables) are typed, but in Scheme types
453 are associated with values, not variables. @xref{Values and Variables}.
455 So when describing a C function or a C structure so that it can be
456 accessed from Scheme, the data types of the parameters or fields must be
459 These ``C type values'' may be constructed using the constants and
460 procedures from the @code{(system foreign)} module, which may be loaded
464 (use-modules (system foreign))
467 @code{(system foreign)} exports a number of values expressing the basic
470 @defvr {Scheme Variable} int8
471 @defvrx {Scheme Variable} uint8
472 @defvrx {Scheme Variable} uint16
473 @defvrx {Scheme Variable} int16
474 @defvrx {Scheme Variable} uint32
475 @defvrx {Scheme Variable} int32
476 @defvrx {Scheme Variable} uint64
477 @defvrx {Scheme Variable} int64
478 @defvrx {Scheme Variable} float
479 @defvrx {Scheme Variable} double
480 These values represent the C numeric types of the specified sizes and
484 In addition there are some convenience bindings for indicating types of
485 platform-dependent size:
487 @defvr {Scheme Variable} int
488 @defvrx {Scheme Variable} unsigned-int
489 @defvrx {Scheme Variable} long
490 @defvrx {Scheme Variable} unsigned-long
491 @defvrx {Scheme Variable} size_t
492 @defvrx {Scheme Variable} ssize_t
493 @defvrx {Scheme Variable} ptrdiff_t
494 Values exported by the @code{(system foreign)} module, representing C
495 numeric types. For example, @code{long} may be @code{equal?} to
496 @code{int64} on a 64-bit platform.
499 @defvr {Scheme Variable} void
500 The @code{void} type. It can be used as the first argument to
501 @code{pointer->procedure} to wrap a C function that returns nothing.
504 In addition, the symbol @code{*} is used by convention to denote pointer
505 types. Procedures detailed in the following sections, such as
506 @code{pointer->procedure}, accept it as a type descriptor.
508 @node Foreign Variables
509 @subsubsection Foreign Variables
511 Pointers to variables in the current address space may be looked up
512 dynamically using @code{dynamic-pointer}.
514 @deffn {Scheme Procedure} dynamic-pointer name dobj
515 @deffnx {C Function} scm_dynamic_pointer (name, dobj)
516 Return a ``wrapped pointer'' for the symbol @var{name} in the shared
517 object referred to by @var{dobj}. The returned pointer points to a C
520 Regardless whether your C compiler prepends an underscore @samp{_} to the global
521 names in a program, you should @strong{not} include this underscore in
522 @var{name} since it will be added automatically when necessary.
525 For example, currently Guile has a variable, @code{scm_numptob}, as part
526 of its API. It is declared as a C @code{long}. So, to create a handle
527 pointing to that foreign value, we do:
530 (use-modules (system foreign))
531 (define numptob (dynamic-pointer "scm_numptob" (dynamic-link)))
533 @result{} #<pointer 0x7fb35b1b4688>
536 (The next section discusses ways to dereference pointers.)
538 A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C
541 @deffn {Scheme Procedure} pointer-address pointer
542 @deffnx {C Function} scm_pointer_address (pointer)
543 Return the numerical value of @var{pointer}.
546 (pointer-address numptob)
547 @result{} 139984413364296 ; YMMV
551 @deffn {Scheme Procedure} make-pointer address [finalizer]
552 Return a foreign pointer object pointing to @var{address}. If
553 @var{finalizer} is passed, it should be a pointer to a one-argument C
554 function that will be called when the pointer object becomes
558 @deffn {Scheme Procedure} pointer? obj
559 Return @code{#t} if @var{obj} is a pointer object, @code{#f} otherwise.
562 @defvr {Scheme Variable} %null-pointer
563 A foreign pointer whose value is 0.
566 @deffn {Scheme Procedure} null-pointer? pointer
567 Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise.
570 For the purpose of passing SCM values directly to foreign functions, and
571 allowing them to return SCM values, Guile also supports some unsafe
574 @deffn {Scheme Procedure} scm->pointer scm
575 Return a foreign pointer object with the @code{object-address}
579 @deffn {Scheme Procedure} pointer->scm pointer
580 Unsafely cast @var{pointer} to a Scheme object.
584 Sometimes you want to give C extensions access to the dynamic FFI. At
585 that point, the names get confusing, because ``pointer'' can refer to a
586 @code{SCM} object that wraps a pointer, or to a @code{void*} value. We
587 will try to use ``pointer object'' to refer to Scheme objects, and
588 ``pointer value'' to refer to @code{void *} values.
590 @deftypefn {C Function} SCM scm_from_pointer (void *ptr, void (*finalizer) (void*))
591 Create a pointer object from a pointer value.
593 If @var{finalizer} is non-null, Guile arranges to call it on the pointer
594 value at some point after the pointer object becomes collectable.
597 @deftypefn {C Function} void* scm_to_pointer (SCM obj)
598 Unpack the pointer value from a pointer object.
601 @node Void Pointers and Byte Access
602 @subsubsection Void Pointers and Byte Access
604 Wrapped pointers are untyped, so they are essentially equivalent to C
605 @code{void} pointers. As in C, the memory region pointed to by a
606 pointer can be accessed at the byte level. This is achieved using
607 @emph{bytevectors} (@pxref{Bytevectors}). The @code{(rnrs bytevectors)}
608 module contains procedures that can be used to convert byte sequences to
609 Scheme objects such as strings, floating point numbers, or integers.
611 @deffn {Scheme Procedure} pointer->bytevector pointer len [offset [uvec_type]]
612 @deffnx {C Function} scm_pointer_to_bytevector (pointer, len, offset, uvec_type)
613 Return a bytevector aliasing the @var{len} bytes pointed to by
616 The user may specify an alternate default interpretation for the memory
617 by passing the @var{uvec_type} argument, to indicate that the memory is
618 an array of elements of that type. @var{uvec_type} should be something
619 that @code{array-type} would return, like @code{f32} or @code{s16}.
621 When @var{offset} is passed, it specifies the offset in bytes relative
622 to @var{pointer} of the memory region aliased by the returned
625 Mutating the returned bytevector mutates the memory pointed to by
626 @var{pointer}, so buckle your seatbelts.
629 @deffn {Scheme Procedure} bytevector->pointer bv [offset]
630 @deffnx {C Function} scm_bytevector_to_pointer (bv, offset)
631 Return a pointer pointer aliasing the memory pointed to by @var{bv} or
632 @var{offset} bytes after @var{bv} when @var{offset} is passed.
635 In addition to these primitives, convenience procedures are available:
637 @deffn {Scheme Procedure} dereference-pointer pointer
638 Assuming @var{pointer} points to a memory region that holds a pointer,
642 @deffn {Scheme Procedure} string->pointer string [encoding]
643 Return a foreign pointer to a nul-terminated copy of @var{string} in the
644 given @var{encoding}, defaulting to the current locale encoding. The C
645 string is freed when the returned foreign pointer becomes unreachable.
647 This is the Scheme equivalent of @code{scm_to_stringn}.
650 @deffn {Scheme Procedure} pointer->string pointer [length] [encoding]
651 Return the string representing the C string pointed to by @var{pointer}.
652 If @var{length} is omitted or @code{-1}, the string is assumed to be
653 nul-terminated. Otherwise @var{length} is the number of bytes in memory
654 pointed to by @var{pointer}. The C string is assumed to be in the given
655 @var{encoding}, defaulting to the current locale encoding.
657 This is the Scheme equivalent of @code{scm_from_stringn}.
660 @cindex wrapped pointer types
661 Most object-oriented C libraries use pointers to specific data
662 structures to identify objects. It is useful in such cases to reify the
663 different pointer types as disjoint Scheme types. The
664 @code{define-wrapped-pointer-type} macro simplifies this.
666 @deffn {Scheme Syntax} define-wrapped-pointer-type type-name pred wrap unwrap print
667 Define helper procedures to wrap pointer objects into Scheme objects
668 with a disjoint type. Specifically, this macro defines:
671 @item @var{pred}, a predicate for the new Scheme type;
672 @item @var{wrap}, a procedure that takes a pointer object and returns an
673 object that satisfies @var{pred};
674 @item @var{unwrap}, which does the reverse.
677 @var{wrap} preserves pointer identity, for two pointer objects @var{p1}
678 and @var{p2} that are @code{equal?}, @code{(eq? (@var{wrap} @var{p1})
679 (@var{wrap} @var{p2})) @result{} #t}.
681 Finally, @var{print} should name a user-defined procedure to print such
682 objects. The procedure is passed the wrapped object and a port to write
685 For example, assume we are wrapping a C library that defines a type,
686 @code{bottle_t}, and functions that can be passed @code{bottle_t *}
687 pointers to manipulate them. We could write:
690 (define-wrapped-pointer-type bottle
692 wrap-bottle unwrap-bottle
694 (format p "#<bottle of ~a ~x>"
696 (pointer-address (unwrap-bottle b)))))
699 ;; Wrapper for `bottle_t *grab (void)'.
700 (let ((grab (pointer->procedure '*
701 (dynamic-func "grab_bottle" libbottle)
704 "Return a new bottle."
705 (wrap-bottle (grab)))))
707 (define bottle-contents
708 ;; Wrapper for `const char *bottle_contents (bottle_t *)'.
709 (let ((contents (pointer->procedure '*
710 (dynamic-func "bottle_contents"
714 "Return the contents of B."
715 (pointer->string (contents (unwrap-bottle b))))))
717 (write (grab-bottle))
718 @result{} #<bottle of Ch@^ateau Haut-Brion 803d36>
721 In this example, @code{grab-bottle} is guaranteed to return a genuine
722 @code{bottle} object satisfying @code{bottle?}. Likewise,
723 @code{bottle-contents} errors out when its argument is not a genuine
724 @code{bottle} object.
727 Going back to the @code{scm_numptob} example above, here is how we can
728 read its value as a C @code{long} integer:
731 (use-modules (rnrs bytevectors))
733 (bytevector-uint-ref (pointer->bytevector numptob (sizeof long))
734 0 (native-endianness)
739 If we wanted to corrupt Guile's internal state, we could set
740 @code{scm_numptob} to another value; but we shouldn't, because that
741 variable is not meant to be set. Indeed this point applies more widely:
742 the C API is a dangerous place to be. Not only might setting a value
743 crash your program, simply accessing the data pointed to by a dangling
744 pointer or similar can prove equally disastrous.
746 @node Foreign Structs
747 @subsubsection Foreign Structs
749 Finally, one last note on foreign values before moving on to actually
750 calling foreign functions. Sometimes you need to deal with C structs,
751 which requires interpreting each element of the struct according to the
752 its type, offset, and alignment. Guile has some primitives to support
755 @deffn {Scheme Procedure} sizeof type
756 @deffnx {C Function} scm_sizeof (type)
757 Return the size of @var{type}, in bytes.
759 @var{type} should be a valid C type, like @code{int}.
760 Alternately @var{type} may be the symbol @code{*}, in which
761 case the size of a pointer is returned. @var{type} may
762 also be a list of types, in which case the size of a
763 @code{struct} with ABI-conventional packing is returned.
766 @deffn {Scheme Procedure} alignof type
767 @deffnx {C Function} scm_alignof (type)
768 Return the alignment of @var{type}, in bytes.
770 @var{type} should be a valid C type, like @code{int}.
771 Alternately @var{type} may be the symbol @code{*}, in which
772 case the alignment of a pointer is returned. @var{type} may
773 also be a list of types, in which case the alignment of a
774 @code{struct} with ABI-conventional packing is returned.
777 Guile also provides some convenience methods to pack and unpack foreign
778 pointers wrapping C structs.
780 @deffn {Scheme Procedure} make-c-struct types vals
781 Create a foreign pointer to a C struct containing @var{vals} with types
784 @var{vals} and @code{types} should be lists of the same length.
787 @deffn {Scheme Procedure} parse-c-struct foreign types
788 Parse a foreign pointer to a C struct, returning a list of values.
790 @code{types} should be a list of C types.
793 For example, to create and parse the equivalent of a @code{struct @{
794 int64_t a; uint8_t b; @}}:
797 (parse-c-struct (make-c-struct (list int64 uint8)
803 As yet, Guile only has convenience routines to support
804 conventionally-packed structs. But given the @code{bytevector->pointer}
805 and @code{pointer->bytevector} routines, one can create and parse
806 tightly packed structs and unions by hand. See the code for
807 @code{(system foreign)} for details.
811 @subsection Dynamic FFI
813 Of course, the land of C is not all nouns and no verbs: there are
814 functions too, and Guile allows you to call them.
816 @deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types
817 @deffnx {C Procedure} scm_pointer_to_procedure (return_type, func_ptr, arg_types)
818 Make a foreign function.
820 Given the foreign void pointer @var{func_ptr}, its argument and
821 return types @var{arg_types} and @var{return_type}, return a
822 procedure that will pass arguments to the foreign function
823 and return appropriate values.
825 @var{arg_types} should be a list of foreign types.
826 @code{return_type} should be a foreign type. @xref{Foreign Types}, for
827 more information on foreign types.
830 Here is a better definition of @code{(math bessel)}:
833 (define-module (math bessel)
834 #:use-module (system foreign)
837 (define libm (dynamic-link "libm"))
840 (pointer->procedure double
841 (dynamic-func "j0" libm)
845 That's it! No C at all.
847 Numeric arguments and return values from foreign functions are
848 represented as Scheme values. For example, @code{j0} in the above
849 example takes a Scheme number as its argument, and returns a Scheme
852 Pointers may be passed to and returned from foreign functions as well.
853 In that case the type of the argument or return value should be the
854 symbol @code{*}, indicating a pointer. For example, the following
855 code makes @code{memcpy} available to Scheme:
859 (let ((this (dynamic-link)))
860 (pointer->procedure '*
861 (dynamic-func "memcpy" this)
862 (list '* '* size_t))))
865 To invoke @code{memcpy}, one must pass it foreign pointers:
868 (use-modules (rnrs bytevectors))
871 (u8-list->bytevector '(0 1 2 3 4 5 6 7)))
873 (bytevector->pointer src-bits))
875 (bytevector->pointer (make-bytevector 16 0)))
877 (memcpy dest src (bytevector-length src-bits))
879 (bytevector->u8-list (pointer->bytevector dest 16))
880 @result{} (0 1 2 3 4 5 6 7 0 0 0 0 0 0 0 0)
883 One may also pass structs as values, passing structs as foreign
884 pointers. @xref{Foreign Structs}, for more information on how to express
885 struct types and struct values.
887 ``Out'' arguments are passed as foreign pointers. The memory pointed to
888 by the foreign pointer is mutated in place.
892 ;; time_t tv_sec; /* seconds */
893 ;; suseconds_t tv_usec; /* microseconds */
895 ;; assuming fields are of type "long"
898 (let ((f (pointer->procedure
900 (dynamic-func "gettimeofday" (dynamic-link))
902 (tv-type (list long long)))
904 (let* ((timeval (make-c-struct tv-type (list 0 0)))
905 (ret (f timeval %null-pointer)))
907 (apply values (parse-c-struct timeval tv-type))
908 (error "gettimeofday returned an error" ret))))))
915 As you can see, this interface to foreign functions is at a very low,
916 somewhat dangerous level@footnote{A contribution to Guile in the form of
917 a high-level FFI would be most welcome.}.
920 The FFI can also work in the opposite direction: making Scheme
921 procedures callable from C. This makes it possible to use Scheme
922 procedures as ``callbacks'' expected by C function.
924 @deffn {Scheme Procedure} procedure->pointer return-type proc arg-types
925 @deffnx {C Function} scm_procedure_to_pointer (return_type, proc, arg_types)
926 Return a pointer to a C function of type @var{return-type}
927 taking arguments of types @var{arg-types} (a list) and
928 behaving as a proxy to procedure @var{proc}. Thus
929 @var{proc}'s arity, supported argument types, and return
930 type should match @var{return-type} and @var{arg-types}.
933 As an example, here's how the C library's @code{qsort} array sorting
934 function can be made accessible to Scheme (@pxref{Array Sort Function,
935 @code{qsort},, libc, The GNU C Library Reference Manual}):
939 (let ((qsort (pointer->procedure void
940 (dynamic-func "qsort"
942 (list '* size_t size_t '*))))
944 ;; Sort bytevector BV in-place according to comparison
945 ;; procedure COMPARE.
946 (let ((ptr (procedure->pointer int
948 ;; X and Y are pointers so,
949 ;; for convenience, dereference
950 ;; them before calling COMPARE.
951 (compare (dereference-uint8* x)
952 (dereference-uint8* y)))
954 (qsort (bytevector->pointer bv)
955 (bytevector-length bv) 1 ;; we're sorting bytes
958 (define (dereference-uint8* ptr)
959 ;; Helper function: dereference the byte pointed to by PTR.
960 (let ((b (pointer->bytevector ptr 1)))
961 (bytevector-u8-ref b 0)))
964 ;; An unsorted array of bytes.
965 (u8-list->bytevector '(7 1 127 3 5 4 77 2 9 0)))
968 (qsort! bv (lambda (x y) (- x y)))
970 ;; Let's see what the sorted array looks like:
971 (bytevector->u8-list bv)
972 @result{} (0 1 2 3 4 5 7 9 77 127)
977 Note that @code{procedure->pointer} is not supported (and not defined)
978 on a few exotic architectures. Thus, user code may need to check
979 @code{(defined? 'procedure->pointer)}. Nevertheless, it is available on
980 many architectures, including (as of libffi 3.0.9) x86, ia64, SPARC,
981 PowerPC, ARM, and MIPS, to name a few.
984 @c TeX-master: "guile.texi"