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