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 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 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
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}
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.
103 (define libgl-obj (dynamic-link "libGL"))
105 @result{} #<dynamic-object "libGL">
106 (dynamic-unlink libGL-obj)
108 @result{} #<dynamic-object "libGL" (unlinked)>
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
115 not happen when some other parts of your program still use it.
117 When dynamic linking is disabled or not supported on your system,
118 the above functions throw errors, but they are still available.
121 @node Foreign Functions
122 @subsection Foreign Functions
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.
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.
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.
139 Guile has static support for calling functions with no arguments,
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
151 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
154 Interrupts are deferred while the C function is executing (with
155 @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
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
164 Guile-to-X11 glue library that has intimate knowledge about both Guile
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
167 vanilla Guile interpreter and activated by calling its initialization
168 function. That function would add all the new types and primitives to
169 the Guile interpreter that it has to offer.
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.)
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
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
187 (dynamic-call INIT (dynamic-link LIB))
190 When there is a pre-registered function, that function is called
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
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)'.
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
212 (define-module (bla blum))
214 (load-extension "libguile-bla-blum" "bla_init_blum")
219 @subsection C Extensions
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
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
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.
242 #include <libguile.h>
247 return scm_from_double (j0 (scm_to_double (x, "j0")));
253 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
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.
264 gcc -shared -o libbessel.so -fPIC bessel.c
270 (define bessel-lib (dynamic-link "./libbessel.so"))
271 (dynamic-call "init_math_bessel" bessel-lib)
273 @result{} 0.223890779141236
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
284 Fun, isn't it? But we are only half way there. This is what
285 @code{apropos} has to say about @code{j0}:
289 @print{} (guile-user): j0 #<primitive-procedure j0>
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.
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
305 init_math_bessel (void *unused)
307 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
308 scm_c_export ("j0", NULL);
312 scm_init_math_bessel_module ()
314 scm_c_define_module ("math bessel", init_math_bessel, NULL);
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}.
323 After @file{libbessel.so} has been rebuilt, we need to place the shared
324 library into the right place.
326 Once the module has been correctly installed, it should be possible to
330 guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
331 guile> (use-modules (math bessel))
334 guile> (apropos "j0")
335 @print{} (math bessel): j0 #<primitive-procedure j0>
341 @node Modules and Extensions
342 @subsection Modules and Extensions
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.
351 To define C primitives within a specific module, the simplest way is:
354 (define-module (foo bar))
355 (load-extension "foobar-c-code" "foo_bar_init")
359 When loaded with @code{(use-modules (foo bar))}, the
360 @code{load-extension} call looks for the @file{foobar-c-code.so} (etc)
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/}.
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.
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.
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.
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}
392 (define-module (foo bar))
393 (load-extension "XXextensiondirXX/foobar-c-code" "foo_bar_init")
397 with the following in a @file{Makefile}, using @command{sed}
398 (@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
402 sed 's|XXextensiondirXX|$(libdir)/guile/2.0|' <foo.scm.in >foo.scm
405 The actual pattern @code{XXextensiondirXX} is arbitrary, it's only something
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
408 @code{extensiondir} location, and use that as required.
411 (define-module (foo config))
412 (define-public foo-config-extensiondir "XXextensiondirXX"")
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}).
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.
428 @node Foreign Pointers
429 @subsection Foreign Pointers
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.
438 * Foreign Types:: Expressing C types in Scheme.
439 * Foreign Variables:: Pointers to C symbols.
440 * Void Pointers and Byte Access:: Pointers into the ether.
441 * Foreign Structs:: Packing and unpacking structs.
445 @subsubsection Foreign Types
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}.
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
455 These ``C type values'' may be constructed using the constants and
456 procedures from the @code{(system foreign)} module, which may be loaded
460 (use-modules (system foreign))
463 @code{(system foreign)} exports a number of values expressing the basic
466 @defvr {Scheme Variable} int8
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
474 @defvrx {Scheme Variable} float
475 @defvrx {Scheme Variable} double
476 These values represent the C numeric types of the specified sizes and
480 In addition there are some convenience bindings for indicating types of
481 platform-dependent size:
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.
493 @defvr {Scheme Variable} void
494 The @code{void} type. It can be used as the first argument to
495 @code{pointer->procedure} to wrap a C function that returns nothing.
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.
502 @node Foreign Variables
503 @subsubsection Foreign Variables
505 Pointers to variables in the current address space may be looked up
506 dynamically using @code{dynamic-pointer}.
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
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.
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:
524 (use-modules (system foreign))
525 (define numptob (dynamic-pointer "scm_numptob" (dynamic-link)))
527 @result{} #<pointer 0x7fb35b1b4688>
530 (The next section discusses ways to dereference pointers.)
532 A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C
535 @deffn {Scheme Procedure} pointer-address pointer
536 @deffnx {C Function} scm_pointer_address pointer
537 Return the numerical value of @var{pointer}.
540 (pointer-address numptob)
541 @result{} 139984413364296 ; YMMV
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
552 @deffn {Scheme Procedure} pointer? obj
553 Return @code{#t} if @var{obj} is a pointer object, @code{#f} otherwise.
556 @defvr {Scheme Variable} %null-pointer
557 A foreign pointer whose value is 0.
560 @deffn {Scheme Procedure} null-pointer? pointer
561 Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise.
565 @node Void Pointers and Byte Access
566 @subsubsection Void Pointers and Byte Access
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
573 Scheme objects such as strings, floating point numbers, or integers.
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
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}
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
591 Mutating the returned bytevector mutates the memory pointed to by
592 @var{pointer}, so buckle your seatbelts.
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.
601 In addition to these primitives, convenience procedures are available:
603 @deffn {Scheme Procedure} dereference-pointer pointer
604 Assuming @var{pointer} points to a memory region that holds a pointer,
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.
613 This is the Scheme equivalent of @code{scm_to_locale_string}.
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.
621 This is the Scheme equivalent of @code{scm_from_locale_string}.
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.
630 @deffn {Scheme Syntax} define-wrapped-pointer-type pred wrap unwrap print
631 Define helper procedures to wrap pointer objects into Scheme objects
632 with a disjoint type. Specifically, this macro defines:
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.
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}.
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
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:
654 (define-wrapped-pointer-type bottle?
655 wrap-bottle unwrap-bottle
657 (format p "#<bottle of ~a ~x>"
659 (pointer-address (unwrap-foo b)))))
662 ;; Wrapper for `bottle_t *grab (void)'.
663 (let ((grab (pointer->procedure '*
664 (dynamic-func "grab_bottle" libbottle)
667 "Return a new bottle."
668 (wrap-bottle (grab)))))
670 (define bottle-contents
671 ;; Wrapper for `const char *bottle_contents (bottle_t *)'.
672 (let ((contents (pointer->procedure '*
673 (dynamic-func "bottle_contents"
677 "Return the contents of B."
678 (pointer->string (contents (unwrap-bottle b))))))
680 (write (grab-bottle))
681 @result{} #<bottle of Ch@^ateau Haut-Brion 803d36>
684 In this example, @code{grab-bottle} is guaranteed to return a genuine
685 @code{bottle} object satisfying @code{bottle?}. Likewise,
686 @code{bottle-contents} errors out when its argument is not a genuine
687 @code{bottle} object.
690 Going back to the @code{scm_numptob} example above, here is how we can
691 read its value as a C @code{long} integer:
694 (use-modules (rnrs bytevectors))
696 (bytevector-uint-ref (pointer->bytevector numptob (sizeof long))
697 0 (native-endianness)
702 If we wanted to corrupt Guile's internal state, we could set
703 @code{scm_numptob} to another value; but we shouldn't, because that
704 variable is not meant to be set. Indeed this point applies more widely:
705 the C API is a dangerous place to be. Not only might setting a value
706 crash your program, simply accessing the data pointed to by a dangling
707 pointer or similar can prove equally disastrous.
709 @node Foreign Structs
710 @subsubsection Foreign Structs
712 Finally, one last note on foreign values before moving on to actually
713 calling foreign functions. Sometimes you need to deal with C structs,
714 which requires interpreting each element of the struct according to the
715 its type, offset, and alignment. Guile has some primitives to support
718 @deffn {Scheme Procedure} sizeof type
719 @deffnx {C Function} scm_sizeof type
720 Return the size of @var{type}, in bytes.
722 @var{type} should be a valid C type, like @code{int}.
723 Alternately @var{type} may be the symbol @code{*}, in which
724 case the size of a pointer is returned. @var{type} may
725 also be a list of types, in which case the size of a
726 @code{struct} with ABI-conventional packing is returned.
729 @deffn {Scheme Procedure} alignof type
730 @deffnx {C Function} scm_alignof type
731 Return the alignment of @var{type}, in bytes.
733 @var{type} should be a valid C type, like @code{int}.
734 Alternately @var{type} may be the symbol @code{*}, in which
735 case the alignment of a pointer is returned. @var{type} may
736 also be a list of types, in which case the alignment of a
737 @code{struct} with ABI-conventional packing is returned.
740 Guile also provides some convenience methods to pack and unpack foreign
741 pointers wrapping C structs.
743 @deffn {Scheme Procedure} make-c-struct types vals
744 Create a foreign pointer to a C struct containing @var{vals} with types
747 @var{vals} and @code{types} should be lists of the same length.
750 @deffn {Scheme Procedure} parse-c-struct foreign types
751 Parse a foreign pointer to a C struct, returning a list of values.
753 @code{types} should be a list of C types.
756 For example, to create and parse the equivalent of a @code{struct @{
757 int64_t a; uint8_t b; @}}:
760 (parse-c-struct (make-c-struct (list int64 uint8)
766 As yet, Guile only has convenience routines to support
767 conventionally-packed structs. But given the @code{bytevector->foreign}
768 and @code{foreign->bytevector} routines, one can create and parse
769 tightly packed structs and unions by hand. See the code for
770 @code{(system foreign)} for details.
774 @subsection Dynamic FFI
776 Of course, the land of C is not all nouns and no verbs: there are
777 functions too, and Guile allows you to call them.
779 @deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types
780 @deffnx {C Procedure} scm_pointer_to_procedure return_type func_ptr arg_types
781 Make a foreign function.
783 Given the foreign void pointer @var{func_ptr}, its argument and
784 return types @var{arg_types} and @var{return_type}, return a
785 procedure that will pass arguments to the foreign function
786 and return appropriate values.
788 @var{arg_types} should be a list of foreign types.
789 @code{return_type} should be a foreign type. @xref{Foreign Types}, for
790 more information on foreign types.
793 Here is a better definition of @code{(math bessel)}:
796 (define-module (math bessel)
797 #:use-module (system foreign)
800 (define libm (dynamic-link "libm"))
803 (pointer->procedure double
804 (dynamic-func "j0" libm)
808 That's it! No C at all.
810 Numeric arguments and return values from foreign functions are
811 represented as Scheme values. For example, @code{j0} in the above
812 example takes a Scheme number as its argument, and returns a Scheme
815 Pointers may be passed to and returned from foreign functions as well.
816 In that case the type of the argument or return value should be the
817 symbol @code{*}, indicating a pointer. For example, the following
818 code makes @code{memcpy} available to Scheme:
822 (let ((this (dynamic-link)))
823 (pointer->procedure '*
824 (dynamic-func "memcpy" this)
825 (list '* '* size_t))))
828 To invoke @code{memcpy}, one must pass it foreign pointers:
831 (use-modules (rnrs bytevectors))
834 (u8-list->bytevector '(0 1 2 3 4 5 6 7)))
836 (bytevector->pointer src-bits))
838 (bytevector->pointer (make-bytevector 16 0)))
840 (memcpy dest src (bytevector-length src-bits))
842 (bytevector->u8-list (pointer->bytevector dest 16))
843 @result{} (0 1 2 3 4 5 6 7 0 0 0 0 0 0 0 0)
846 One may also pass structs as values, passing structs as foreign
847 pointers. @xref{Foreign Structs}, for more information on how to express
848 struct types and struct values.
850 ``Out'' arguments are passed as foreign pointers. The memory pointed to
851 by the foreign pointer is mutated in place.
855 ;; time_t tv_sec; /* seconds */
856 ;; suseconds_t tv_usec; /* microseconds */
858 ;; assuming fields are of type "long"
861 (let ((f (pointer->procedure
863 (dynamic-func "gettimeofday" (dynamic-link))
865 (tv-type (list long long)))
867 (let* ((timeval (make-c-struct tv-type (list 0 0)))
868 (ret (f timeval %null-pointer)))
870 (apply values (parse-c-struct timeval tv-type))
871 (error "gettimeofday returned an error" ret))))))
878 As you can see, this interface to foreign functions is at a very low,
879 somewhat dangerous level@footnote{A contribution to Guile in the form of
880 a high-level FFI would be most welcome.}.
883 The FFI can also work in the opposite direction: making Scheme
884 procedures callable from C. This makes it possible to use Scheme
885 procedures as ``callbacks'' expected by C function.
887 @deffn {Scheme Procedure} procedure->pointer return-type proc arg-types
888 @deffnx {C Function} scm_procedure_to_pointer (return_type, proc, arg_types)
889 Return a pointer to a C function of type @var{return-type}
890 taking arguments of types @var{arg-types} (a list) and
891 behaving as a proxy to procedure @var{proc}. Thus
892 @var{proc}'s arity, supported argument types, and return
893 type should match @var{return-type} and @var{arg-types}.
896 As an example, here's how the C library's @code{qsort} array sorting
897 function can be made accessible to Scheme (@pxref{Array Sort Function,
898 @code{qsort},, libc, The GNU C Library Reference Manual}):
902 (let ((qsort (pointer->procedure void
903 (dynamic-func "qsort"
905 (list '* size_t size_t '*))))
907 ;; Sort bytevector BV in-place according to comparison
908 ;; procedure COMPARE.
909 (let ((ptr (procedure->pointer int
911 ;; X and Y are pointers so,
912 ;; for convenience, dereference
913 ;; them before calling COMPARE.
914 (compare (dereference-uint8* x)
915 (dereference-uint8* y)))
917 (qsort (bytevector->pointer bv)
918 (bytevector-length bv) 1 ;; we're sorting bytes
921 (define (dereference-uint8* ptr)
922 ;; Helper function: dereference the byte pointed to by PTR.
923 (let ((b (pointer->bytevector ptr 1)))
924 (bytevector-u8-ref b 0)))
927 ;; An unsorted array of bytes.
928 (u8-list->bytevector '(7 1 127 3 5 4 77 2 9 0)))
931 (qsort! bv (lambda (x y) (- x y)))
933 ;; Let's see what the sorted array looks like:
934 (bytevector->u8-list bv)
935 @result{} (0 1 2 3 4 5 7 9 77 127)
940 Note that @code{procedure->pointer} is not supported (and not defined)
941 on a few exotic architectures. Thus, user code may need to check
942 @code{(defined? 'procedure->pointer)}. Nevertheless, it is available on
943 many architectures, including (as of libffi 3.0.9) x86, ia64, SPARC,
944 PowerPC, ARM, and MIPS, to name a few.
947 @c TeX-master: "guile.texi"