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, |
8cdb03c2 | 4 | @c 2009, 2010, 2011, 2012, 2013 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 | |
726b8ba3 AW |
159 | @end deffn |
160 | ||
43cd9cec AW |
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 | |
71725997 | 167 | Guile-to-X11 glue library that has intimate knowledge about both Guile |
43cd9cec AW |
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 | |
726b8ba3 | 170 | vanilla Guile interpreter and activated by calling its initialization |
43cd9cec | 171 | function. That function would add all the new types and primitives to |
726b8ba3 AW |
172 | the Guile interpreter that it has to offer. |
173 | ||
43cd9cec AW |
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.) | |
726b8ba3 | 177 | |
43cd9cec AW |
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 | |
181 | new Scheme code. | |
726b8ba3 AW |
182 | |
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 | |
187 | equivalent to | |
188 | ||
189 | @lisp | |
190 | (dynamic-call INIT (dynamic-link LIB)) | |
191 | @end lisp | |
192 | ||
193 | When there is a pre-registered function, that function is called | |
194 | instead. | |
195 | ||
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 | |
200 | initialized. | |
201 | ||
fba502db LC |
202 | As for @code{dynamic-link}, @var{lib} should not contain any suffix such |
203 | as @code{.so} (@pxref{Foreign Libraries, dynamic-link}). It | |
726b8ba3 AW |
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 | |
fba502db LC |
207 | @file{libguile-bla-blum} for a extension related to a module @code{(bla |
208 | blum)}. | |
726b8ba3 AW |
209 | |
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 | |
213 | well. For example, | |
214 | ||
215 | @lisp | |
216 | (define-module (bla blum)) | |
217 | ||
218 | (load-extension "libguile-bla-blum" "bla_init_blum") | |
219 | @end lisp | |
220 | @end deffn | |
221 | ||
222 | @node C Extensions | |
223 | @subsection C Extensions | |
224 | ||
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 | |
229 | more fun. | |
230 | ||
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 | |
234 | needed. | |
235 | ||
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. | |
243 | ||
244 | @smallexample | |
245 | #include <math.h> | |
246 | #include <libguile.h> | |
247 | ||
248 | SCM | |
249 | j0_wrapper (SCM x) | |
250 | @{ | |
251 | return scm_from_double (j0 (scm_to_double (x, "j0"))); | |
252 | @} | |
253 | ||
254 | void | |
255 | init_math_bessel () | |
256 | @{ | |
257 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
258 | @} | |
259 | @end smallexample | |
260 | ||
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. | |
266 | ||
267 | @smallexample | |
268 | gcc -shared -o libbessel.so -fPIC bessel.c | |
269 | @end smallexample | |
270 | ||
271 | Now fire up Guile: | |
272 | ||
273 | @lisp | |
274 | (define bessel-lib (dynamic-link "./libbessel.so")) | |
275 | (dynamic-call "init_math_bessel" bessel-lib) | |
276 | (j0 2) | |
277 | @result{} 0.223890779141236 | |
278 | @end lisp | |
279 | ||
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 | |
286 | it from Scheme. | |
287 | ||
288 | Fun, isn't it? But we are only half way there. This is what | |
289 | @code{apropos} has to say about @code{j0}: | |
290 | ||
291 | @smallexample | |
292 | (apropos "j0") | |
293 | @print{} (guile-user): j0 #<primitive-procedure j0> | |
294 | @end smallexample | |
295 | ||
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. | |
300 | ||
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 | |
305 | @file{bessel.c}: | |
306 | ||
307 | @smallexample | |
308 | void | |
309 | init_math_bessel (void *unused) | |
310 | @{ | |
311 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
312 | scm_c_export ("j0", NULL); | |
313 | @} | |
314 | ||
315 | void | |
316 | scm_init_math_bessel_module () | |
317 | @{ | |
318 | scm_c_define_module ("math bessel", init_math_bessel, NULL); | |
319 | @} | |
320 | @end smallexample | |
321 | ||
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}. | |
326 | ||
327 | After @file{libbessel.so} has been rebuilt, we need to place the shared | |
328 | library into the right place. | |
329 | ||
330 | Once the module has been correctly installed, it should be possible to | |
331 | use it like this: | |
332 | ||
333 | @smallexample | |
334 | guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module") | |
335 | guile> (use-modules (math bessel)) | |
336 | guile> (j0 2) | |
337 | 0.223890779141236 | |
338 | guile> (apropos "j0") | |
339 | @print{} (math bessel): j0 #<primitive-procedure j0> | |
340 | @end smallexample | |
341 | ||
342 | That's it! | |
343 | ||
726b8ba3 AW |
344 | |
345 | @node Modules and Extensions | |
346 | @subsection Modules and Extensions | |
347 | ||
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. | |
354 | ||
355 | To define C primitives within a specific module, the simplest way is: | |
356 | ||
357 | @example | |
358 | (define-module (foo bar)) | |
359 | (load-extension "foobar-c-code" "foo_bar_init") | |
360 | @end example | |
361 | ||
e5f7f675 | 362 | @cindex extensiondir |
726b8ba3 AW |
363 | When loaded with @code{(use-modules (foo bar))}, the |
364 | @code{load-extension} call looks for the @file{foobar-c-code.so} (etc) | |
e5f7f675 AW |
365 | object file in Guile's @code{extensiondir}, which is usually a |
366 | subdirectory of the @code{libdir}. For example, if your libdir is | |
4b93693d AW |
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}/}. | |
e5f7f675 AW |
369 | |
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. | |
374 | ||
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. | |
726b8ba3 AW |
380 | |
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. | |
386 | ||
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} | |
394 | ||
395 | @example | |
396 | (define-module (foo bar)) | |
e5f7f675 | 397 | (load-extension "XXextensiondirXX/foobar-c-code" "foo_bar_init") |
726b8ba3 AW |
398 | @end example |
399 | ||
400 | @noindent | |
401 | with the following in a @file{Makefile}, using @command{sed} | |
402 | (@pxref{Top, , Introduction, sed, SED, A Stream Editor}), | |
403 | ||
404 | @example | |
405 | foo.scm: foo.scm.in | |
4b93693d | 406 | sed 's|XXextensiondirXX|$(libdir)/guile/@value{EFFECTIVE-VERSION}|' <foo.scm.in >foo.scm |
726b8ba3 AW |
407 | @end example |
408 | ||
e5f7f675 | 409 | The actual pattern @code{XXextensiondirXX} is arbitrary, it's only something |
726b8ba3 AW |
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 | |
e5f7f675 | 412 | @code{extensiondir} location, and use that as required. |
726b8ba3 AW |
413 | |
414 | @example | |
415 | (define-module (foo config)) | |
e5f7f675 | 416 | (define-public foo-config-extensiondir "XXextensiondirXX"") |
726b8ba3 AW |
417 | @end example |
418 | ||
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}). | |
423 | ||
726b8ba3 | 424 | It will be noted all of the above requires that the Scheme code to be |
0740cb49 AW |
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 | |
429 | private files etc. | |
726b8ba3 | 430 | |
726b8ba3 | 431 | |
71725997 AW |
432 | @node Foreign Pointers |
433 | @subsection Foreign Pointers | |
434 | ||
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. | |
440 | ||
441 | @menu | |
b9264dc5 | 442 | * Foreign Types:: Expressing C types in Scheme. |
183a2a22 | 443 | * Foreign Variables:: Pointers to C symbols. |
b9264dc5 AW |
444 | * Void Pointers and Byte Access:: Pointers into the ether. |
445 | * Foreign Structs:: Packing and unpacking structs. | |
71725997 AW |
446 | @end menu |
447 | ||
448 | @node Foreign Types | |
449 | @subsubsection Foreign Types | |
450 | ||
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}. | |
454 | ||
183a2a22 LC |
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 | |
457 | passed explicitly. | |
71725997 AW |
458 | |
459 | These ``C type values'' may be constructed using the constants and | |
460 | procedures from the @code{(system foreign)} module, which may be loaded | |
461 | like this: | |
462 | ||
463 | @example | |
464 | (use-modules (system foreign)) | |
465 | @end example | |
466 | ||
467 | @code{(system foreign)} exports a number of values expressing the basic | |
468 | C types: | |
469 | ||
b9264dc5 | 470 | @defvr {Scheme Variable} int8 |
71725997 AW |
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 | |
b9264dc5 AW |
478 | @defvrx {Scheme Variable} float |
479 | @defvrx {Scheme Variable} double | |
183a2a22 LC |
480 | These values represent the C numeric types of the specified sizes and |
481 | signednesses. | |
71725997 AW |
482 | @end defvr |
483 | ||
484 | In addition there are some convenience bindings for indicating types of | |
485 | platform-dependent size: | |
486 | ||
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 | |
3a3bea72 MW |
492 | @defvrx {Scheme Variable} ssize_t |
493 | @defvrx {Scheme Variable} ptrdiff_t | |
71725997 AW |
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. | |
497 | @end defvr | |
498 | ||
183a2a22 LC |
499 | @defvr {Scheme Variable} void |
500 | The @code{void} type. It can be used as the first argument to | |
2ee07358 | 501 | @code{pointer->procedure} to wrap a C function that returns nothing. |
183a2a22 LC |
502 | @end defvr |
503 | ||
1f4f7674 LC |
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. | |
507 | ||
71725997 AW |
508 | @node Foreign Variables |
509 | @subsubsection Foreign Variables | |
510 | ||
e5f7f675 AW |
511 | Pointers to variables in the current address space may be looked up |
512 | dynamically using @code{dynamic-pointer}. | |
726b8ba3 | 513 | |
183a2a22 LC |
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 | |
518 | object. | |
726b8ba3 | 519 | |
726b8ba3 AW |
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. | |
523 | @end deffn | |
524 | ||
71725997 AW |
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: | |
528 | ||
529 | @example | |
530 | (use-modules (system foreign)) | |
183a2a22 | 531 | (define numptob (dynamic-pointer "scm_numptob" (dynamic-link))) |
71725997 | 532 | numptob |
e5f7f675 | 533 | @result{} #<pointer 0x7fb35b1b4688> |
71725997 AW |
534 | @end example |
535 | ||
e5f7f675 AW |
536 | (The next section discusses ways to dereference pointers.) |
537 | ||
b9264dc5 | 538 | A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C |
183a2a22 | 539 | pointer. |
b9264dc5 | 540 | |
183a2a22 | 541 | @deffn {Scheme Procedure} pointer-address pointer |
5f6ffd66 | 542 | @deffnx {C Function} scm_pointer_address (pointer) |
183a2a22 | 543 | Return the numerical value of @var{pointer}. |
b9264dc5 AW |
544 | |
545 | @example | |
183a2a22 LC |
546 | (pointer-address numptob) |
547 | @result{} 139984413364296 ; YMMV | |
b9264dc5 AW |
548 | @end example |
549 | @end deffn | |
550 | ||
183a2a22 LC |
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 | |
555 | unreachable. | |
556 | @end deffn | |
b9264dc5 | 557 | |
6e097560 LC |
558 | @deffn {Scheme Procedure} pointer? obj |
559 | Return @code{#t} if @var{obj} is a pointer object, @code{#f} otherwise. | |
560 | @end deffn | |
561 | ||
183a2a22 LC |
562 | @defvr {Scheme Variable} %null-pointer |
563 | A foreign pointer whose value is 0. | |
564 | @end defvr | |
b9264dc5 | 565 | |
183a2a22 LC |
566 | @deffn {Scheme Procedure} null-pointer? pointer |
567 | Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise. | |
b9264dc5 AW |
568 | @end deffn |
569 | ||
148c3317 AW |
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 | |
572 | casting operators. | |
573 | ||
574 | @deffn {Scheme Procedure} scm->pointer scm | |
575 | Return a foreign pointer object with the @code{object-address} | |
576 | of @var{scm}. | |
577 | @end deffn | |
578 | ||
579 | @deffn {Scheme Procedure} pointer->scm pointer | |
580 | Unsafely cast @var{pointer} to a Scheme object. | |
581 | Cross your fingers! | |
582 | @end deffn | |
583 | ||
467be245 AW |
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. | |
589 | ||
590 | @deftypefn {C Function} SCM scm_from_pointer (void *ptr, void (*finalizer) (void*)) | |
591 | Create a pointer object from a pointer value. | |
592 | ||
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. | |
595 | @end deftypefn | |
596 | ||
597 | @deftypefn {C Function} void* scm_to_pointer (SCM obj) | |
598 | Unpack the pointer value from a pointer object. | |
599 | @end deftypefn | |
b9264dc5 AW |
600 | |
601 | @node Void Pointers and Byte Access | |
602 | @subsubsection Void Pointers and Byte Access | |
603 | ||
183a2a22 LC |
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 bytevector)} | |
608 | module contains procedures that can be used to convert byte sequences to | |
e5f7f675 | 609 | Scheme objects such as strings, floating point numbers, or integers. |
71725997 | 610 | |
183a2a22 | 611 | @deffn {Scheme Procedure} pointer->bytevector pointer len [offset [uvec_type]] |
7cc8ef62 | 612 | @deffnx {C Function} scm_pointer_to_bytevector (pointer, len, offset, uvec_type) |
183a2a22 LC |
613 | Return a bytevector aliasing the @var{len} bytes pointed to by |
614 | @var{pointer}. | |
71725997 AW |
615 | |
616 | The user may specify an alternate default interpretation for | |
617 | the memory by passing the @var{uvec_type} argument, to indicate | |
618 | that the memory is an array of elements of that type. | |
619 | @var{uvec_type} should be something that | |
620 | @code{uniform-vector-element-type} would return, like @code{f32} | |
621 | or @code{s16}. | |
622 | ||
183a2a22 LC |
623 | When @var{offset} is passed, it specifies the offset in bytes relative |
624 | to @var{pointer} of the memory region aliased by the returned | |
625 | bytevector. | |
71725997 AW |
626 | |
627 | Mutating the returned bytevector mutates the memory pointed to by | |
183a2a22 | 628 | @var{pointer}, so buckle your seatbelts. |
71725997 AW |
629 | @end deffn |
630 | ||
183a2a22 | 631 | @deffn {Scheme Procedure} bytevector->pointer bv [offset] |
5f6ffd66 | 632 | @deffnx {C Function} scm_bytevector_to_pointer (bv, offset) |
183a2a22 LC |
633 | Return a pointer pointer aliasing the memory pointed to by @var{bv} or |
634 | @var{offset} bytes after @var{bv} when @var{offset} is passed. | |
635 | @end deffn | |
71725997 | 636 | |
183a2a22 | 637 | In addition to these primitives, convenience procedures are available: |
b9264dc5 | 638 | |
183a2a22 LC |
639 | @deffn {Scheme Procedure} dereference-pointer pointer |
640 | Assuming @var{pointer} points to a memory region that holds a pointer, | |
641 | return this pointer. | |
71725997 AW |
642 | @end deffn |
643 | ||
c6b08d21 | 644 | @deffn {Scheme Procedure} string->pointer string [encoding] |
fa2a89a6 | 645 | Return a foreign pointer to a nul-terminated copy of @var{string} in the |
c6b08d21 AW |
646 | given @var{encoding}, defaulting to the current locale encoding. The C |
647 | string is freed when the returned foreign pointer becomes unreachable. | |
fa2a89a6 | 648 | |
c6b08d21 | 649 | This is the Scheme equivalent of @code{scm_to_stringn}. |
fa2a89a6 LC |
650 | @end deffn |
651 | ||
c6b08d21 AW |
652 | @deffn {Scheme Procedure} pointer->string pointer [length] [encoding] |
653 | Return the string representing the C string pointed to by @var{pointer}. | |
654 | If @var{length} is omitted or @code{-1}, the string is assumed to be | |
655 | nul-terminated. Otherwise @var{length} is the number of bytes in memory | |
656 | pointed to by @var{pointer}. The C string is assumed to be in the given | |
657 | @var{encoding}, defaulting to the current locale encoding. | |
fa2a89a6 | 658 | |
c6b08d21 | 659 | This is the Scheme equivalent of @code{scm_from_stringn}. |
fa2a89a6 LC |
660 | @end deffn |
661 | ||
1f4f7674 LC |
662 | @cindex wrapped pointer types |
663 | Most object-oriented C libraries use pointers to specific data | |
664 | structures to identify objects. It is useful in such cases to reify the | |
665 | different pointer types as disjoint Scheme types. The | |
666 | @code{define-wrapped-pointer-type} macro simplifies this. | |
667 | ||
de6fb187 | 668 | @deffn {Scheme Syntax} define-wrapped-pointer-type type-name pred wrap unwrap print |
1f4f7674 LC |
669 | Define helper procedures to wrap pointer objects into Scheme objects |
670 | with a disjoint type. Specifically, this macro defines: | |
671 | ||
672 | @itemize | |
673 | @item @var{pred}, a predicate for the new Scheme type; | |
674 | @item @var{wrap}, a procedure that takes a pointer object and returns an | |
675 | object that satisfies @var{pred}; | |
676 | @item @var{unwrap}, which does the reverse. | |
677 | @end itemize | |
678 | ||
679 | @var{wrap} preserves pointer identity, for two pointer objects @var{p1} | |
680 | and @var{p2} that are @code{equal?}, @code{(eq? (@var{wrap} @var{p1}) | |
681 | (@var{wrap} @var{p2})) @result{} #t}. | |
682 | ||
683 | Finally, @var{print} should name a user-defined procedure to print such | |
684 | objects. The procedure is passed the wrapped object and a port to write | |
685 | to. | |
686 | ||
687 | For example, assume we are wrapping a C library that defines a type, | |
688 | @code{bottle_t}, and functions that can be passed @code{bottle_t *} | |
689 | pointers to manipulate them. We could write: | |
690 | ||
691 | @example | |
de6fb187 LC |
692 | (define-wrapped-pointer-type bottle |
693 | bottle? | |
1f4f7674 LC |
694 | wrap-bottle unwrap-bottle |
695 | (lambda (b p) | |
696 | (format p "#<bottle of ~a ~x>" | |
697 | (bottle-contents b) | |
aed9483b | 698 | (pointer-address (unwrap-bottle b))))) |
1f4f7674 LC |
699 | |
700 | (define grab-bottle | |
701 | ;; Wrapper for `bottle_t *grab (void)'. | |
702 | (let ((grab (pointer->procedure '* | |
703 | (dynamic-func "grab_bottle" libbottle) | |
704 | '()))) | |
705 | (lambda () | |
706 | "Return a new bottle." | |
707 | (wrap-bottle (grab))))) | |
708 | ||
709 | (define bottle-contents | |
710 | ;; Wrapper for `const char *bottle_contents (bottle_t *)'. | |
711 | (let ((contents (pointer->procedure '* | |
712 | (dynamic-func "bottle_contents" | |
713 | libbottle) | |
714 | '(*)))) | |
715 | (lambda (b) | |
716 | "Return the contents of B." | |
717 | (pointer->string (contents (unwrap-bottle b)))))) | |
718 | ||
719 | (write (grab-bottle)) | |
720 | @result{} #<bottle of Ch@^ateau Haut-Brion 803d36> | |
721 | @end example | |
722 | ||
723 | In this example, @code{grab-bottle} is guaranteed to return a genuine | |
724 | @code{bottle} object satisfying @code{bottle?}. Likewise, | |
725 | @code{bottle-contents} errors out when its argument is not a genuine | |
726 | @code{bottle} object. | |
727 | @end deffn | |
728 | ||
183a2a22 LC |
729 | Going back to the @code{scm_numptob} example above, here is how we can |
730 | read its value as a C @code{long} integer: | |
731 | ||
732 | @example | |
733 | (use-modules (rnrs bytevectors)) | |
734 | ||
735 | (bytevector-uint-ref (pointer->bytevector numptob (sizeof long)) | |
736 | 0 (native-endianness) | |
737 | (sizeof long)) | |
738 | @result{} 8 | |
739 | @end example | |
740 | ||
741 | If we wanted to corrupt Guile's internal state, we could set | |
742 | @code{scm_numptob} to another value; but we shouldn't, because that | |
743 | variable is not meant to be set. Indeed this point applies more widely: | |
744 | the C API is a dangerous place to be. Not only might setting a value | |
745 | crash your program, simply accessing the data pointed to by a dangling | |
746 | pointer or similar can prove equally disastrous. | |
71725997 | 747 | |
b9264dc5 AW |
748 | @node Foreign Structs |
749 | @subsubsection Foreign Structs | |
71725997 | 750 | |
b9264dc5 AW |
751 | Finally, one last note on foreign values before moving on to actually |
752 | calling foreign functions. Sometimes you need to deal with C structs, | |
753 | which requires interpreting each element of the struct according to the | |
754 | its type, offset, and alignment. Guile has some primitives to support | |
755 | this. | |
756 | ||
757 | @deffn {Scheme Procedure} sizeof type | |
5f6ffd66 | 758 | @deffnx {C Function} scm_sizeof (type) |
b9264dc5 AW |
759 | Return the size of @var{type}, in bytes. |
760 | ||
761 | @var{type} should be a valid C type, like @code{int}. | |
762 | Alternately @var{type} may be the symbol @code{*}, in which | |
763 | case the size of a pointer is returned. @var{type} may | |
764 | also be a list of types, in which case the size of a | |
765 | @code{struct} with ABI-conventional packing is returned. | |
766 | @end deffn | |
71725997 | 767 | |
b9264dc5 | 768 | @deffn {Scheme Procedure} alignof type |
5f6ffd66 | 769 | @deffnx {C Function} scm_alignof (type) |
b9264dc5 AW |
770 | Return the alignment of @var{type}, in bytes. |
771 | ||
772 | @var{type} should be a valid C type, like @code{int}. | |
773 | Alternately @var{type} may be the symbol @code{*}, in which | |
774 | case the alignment of a pointer is returned. @var{type} may | |
775 | also be a list of types, in which case the alignment of a | |
776 | @code{struct} with ABI-conventional packing is returned. | |
71725997 AW |
777 | @end deffn |
778 | ||
b9264dc5 AW |
779 | Guile also provides some convenience methods to pack and unpack foreign |
780 | pointers wrapping C structs. | |
71725997 | 781 | |
b9264dc5 AW |
782 | @deffn {Scheme Procedure} make-c-struct types vals |
783 | Create a foreign pointer to a C struct containing @var{vals} with types | |
784 | @code{types}. | |
785 | ||
786 | @var{vals} and @code{types} should be lists of the same length. | |
787 | @end deffn | |
788 | ||
789 | @deffn {Scheme Procedure} parse-c-struct foreign types | |
790 | Parse a foreign pointer to a C struct, returning a list of values. | |
791 | ||
792 | @code{types} should be a list of C types. | |
793 | @end deffn | |
794 | ||
795 | For example, to create and parse the equivalent of a @code{struct @{ | |
796 | int64_t a; uint8_t b; @}}: | |
71725997 AW |
797 | |
798 | @example | |
b9264dc5 AW |
799 | (parse-c-struct (make-c-struct (list int64 uint8) |
800 | (list 300 43)) | |
801 | (list int64 uint8)) | |
802 | @result{} (300 43) | |
71725997 | 803 | @end example |
71725997 | 804 | |
b9264dc5 | 805 | As yet, Guile only has convenience routines to support |
5ad85ba1 DH |
806 | conventionally-packed structs. But given the @code{bytevector->pointer} |
807 | and @code{pointer->bytevector} routines, one can create and parse | |
b9264dc5 AW |
808 | tightly packed structs and unions by hand. See the code for |
809 | @code{(system foreign)} for details. | |
71725997 | 810 | |
726b8ba3 AW |
811 | |
812 | @node Dynamic FFI | |
813 | @subsection Dynamic FFI | |
814 | ||
71725997 AW |
815 | Of course, the land of C is not all nouns and no verbs: there are |
816 | functions too, and Guile allows you to call them. | |
817 | ||
2ee07358 | 818 | @deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types |
5f6ffd66 | 819 | @deffnx {C Procedure} scm_pointer_to_procedure (return_type, func_ptr, arg_types) |
71725997 AW |
820 | Make a foreign function. |
821 | ||
822 | Given the foreign void pointer @var{func_ptr}, its argument and | |
823 | return types @var{arg_types} and @var{return_type}, return a | |
824 | procedure that will pass arguments to the foreign function | |
825 | and return appropriate values. | |
826 | ||
827 | @var{arg_types} should be a list of foreign types. | |
b9264dc5 AW |
828 | @code{return_type} should be a foreign type. @xref{Foreign Types}, for |
829 | more information on foreign types. | |
71725997 AW |
830 | @end deffn |
831 | ||
b9264dc5 | 832 | Here is a better definition of @code{(math bessel)}: |
726b8ba3 | 833 | |
b9264dc5 AW |
834 | @example |
835 | (define-module (math bessel) | |
836 | #:use-module (system foreign) | |
837 | #:export (j0)) | |
71725997 | 838 | |
b9264dc5 | 839 | (define libm (dynamic-link "libm")) |
71725997 | 840 | |
b9264dc5 | 841 | (define j0 |
2ee07358 LC |
842 | (pointer->procedure double |
843 | (dynamic-func "j0" libm) | |
844 | (list double))) | |
b9264dc5 | 845 | @end example |
71725997 | 846 | |
b9264dc5 | 847 | That's it! No C at all. |
71725997 | 848 | |
b9264dc5 AW |
849 | Numeric arguments and return values from foreign functions are |
850 | represented as Scheme values. For example, @code{j0} in the above | |
851 | example takes a Scheme number as its argument, and returns a Scheme | |
852 | number. | |
71725997 | 853 | |
b9264dc5 AW |
854 | Pointers may be passed to and returned from foreign functions as well. |
855 | In that case the type of the argument or return value should be the | |
856 | symbol @code{*}, indicating a pointer. For example, the following | |
857 | code makes @code{memcpy} available to Scheme: | |
71725997 | 858 | |
b9264dc5 AW |
859 | @example |
860 | (define memcpy | |
861 | (let ((this (dynamic-link))) | |
2ee07358 LC |
862 | (pointer->procedure '* |
863 | (dynamic-func "memcpy" this) | |
864 | (list '* '* size_t)))) | |
b9264dc5 AW |
865 | @end example |
866 | ||
867 | To invoke @code{memcpy}, one must pass it foreign pointers: | |
868 | ||
869 | @example | |
07d22c02 | 870 | (use-modules (rnrs bytevectors)) |
71725997 | 871 | |
183a2a22 LC |
872 | (define src-bits |
873 | (u8-list->bytevector '(0 1 2 3 4 5 6 7))) | |
b9264dc5 | 874 | (define src |
183a2a22 | 875 | (bytevector->pointer src-bits)) |
b9264dc5 | 876 | (define dest |
183a2a22 | 877 | (bytevector->pointer (make-bytevector 16 0))) |
71725997 | 878 | |
183a2a22 | 879 | (memcpy dest src (bytevector-length src-bits)) |
b9264dc5 | 880 | |
183a2a22 | 881 | (bytevector->u8-list (pointer->bytevector dest 16)) |
b9264dc5 AW |
882 | @result{} (0 1 2 3 4 5 6 7 0 0 0 0 0 0 0 0) |
883 | @end example | |
884 | ||
885 | One may also pass structs as values, passing structs as foreign | |
886 | pointers. @xref{Foreign Structs}, for more information on how to express | |
887 | struct types and struct values. | |
888 | ||
889 | ``Out'' arguments are passed as foreign pointers. The memory pointed to | |
890 | by the foreign pointer is mutated in place. | |
71725997 AW |
891 | |
892 | @example | |
b9264dc5 AW |
893 | ;; struct timeval @{ |
894 | ;; time_t tv_sec; /* seconds */ | |
895 | ;; suseconds_t tv_usec; /* microseconds */ | |
896 | ;; @}; | |
897 | ;; assuming fields are of type "long" | |
898 | ||
899 | (define gettimeofday | |
2ee07358 | 900 | (let ((f (pointer->procedure |
b9264dc5 AW |
901 | int |
902 | (dynamic-func "gettimeofday" (dynamic-link)) | |
903 | (list '* '*))) | |
904 | (tv-type (list long long))) | |
905 | (lambda () | |
906 | (let* ((timeval (make-c-struct tv-type (list 0 0))) | |
907 | (ret (f timeval %null-pointer))) | |
908 | (if (zero? ret) | |
909 | (apply values (parse-c-struct timeval tv-type)) | |
910 | (error "gettimeofday returned an error" ret)))))) | |
911 | ||
912 | (gettimeofday) | |
913 | @result{} 1270587589 | |
914 | @result{} 499553 | |
71725997 AW |
915 | @end example |
916 | ||
b9264dc5 | 917 | As you can see, this interface to foreign functions is at a very low, |
33186356 LC |
918 | somewhat dangerous level@footnote{A contribution to Guile in the form of |
919 | a high-level FFI would be most welcome.}. | |
920 | ||
921 | @cindex callbacks | |
922 | The FFI can also work in the opposite direction: making Scheme | |
923 | procedures callable from C. This makes it possible to use Scheme | |
924 | procedures as ``callbacks'' expected by C function. | |
925 | ||
926 | @deffn {Scheme Procedure} procedure->pointer return-type proc arg-types | |
927 | @deffnx {C Function} scm_procedure_to_pointer (return_type, proc, arg_types) | |
928 | Return a pointer to a C function of type @var{return-type} | |
929 | taking arguments of types @var{arg-types} (a list) and | |
930 | behaving as a proxy to procedure @var{proc}. Thus | |
931 | @var{proc}'s arity, supported argument types, and return | |
932 | type should match @var{return-type} and @var{arg-types}. | |
933 | @end deffn | |
934 | ||
935 | As an example, here's how the C library's @code{qsort} array sorting | |
936 | function can be made accessible to Scheme (@pxref{Array Sort Function, | |
937 | @code{qsort},, libc, The GNU C Library Reference Manual}): | |
938 | ||
939 | @example | |
940 | (define qsort! | |
2ee07358 LC |
941 | (let ((qsort (pointer->procedure void |
942 | (dynamic-func "qsort" | |
943 | (dynamic-link)) | |
944 | (list '* size_t size_t '*)))) | |
33186356 LC |
945 | (lambda (bv compare) |
946 | ;; Sort bytevector BV in-place according to comparison | |
947 | ;; procedure COMPARE. | |
948 | (let ((ptr (procedure->pointer int | |
949 | (lambda (x y) | |
950 | ;; X and Y are pointers so, | |
951 | ;; for convenience, dereference | |
952 | ;; them before calling COMPARE. | |
953 | (compare (dereference-uint8* x) | |
954 | (dereference-uint8* y))) | |
955 | (list '* '*)))) | |
956 | (qsort (bytevector->pointer bv) | |
957 | (bytevector-length bv) 1 ;; we're sorting bytes | |
958 | ptr))))) | |
959 | ||
960 | (define (dereference-uint8* ptr) | |
961 | ;; Helper function: dereference the byte pointed to by PTR. | |
962 | (let ((b (pointer->bytevector ptr 1))) | |
963 | (bytevector-u8-ref b 0))) | |
964 | ||
965 | (define bv | |
966 | ;; An unsorted array of bytes. | |
967 | (u8-list->bytevector '(7 1 127 3 5 4 77 2 9 0))) | |
968 | ||
969 | ;; Sort BV. | |
970 | (qsort! bv (lambda (x y) (- x y))) | |
971 | ||
972 | ;; Let's see what the sorted array looks like: | |
973 | (bytevector->u8-list bv) | |
974 | @result{} (0 1 2 3 4 5 7 9 77 127) | |
975 | @end example | |
976 | ||
977 | And voil@`a! | |
978 | ||
979 | Note that @code{procedure->pointer} is not supported (and not defined) | |
980 | on a few exotic architectures. Thus, user code may need to check | |
981 | @code{(defined? 'procedure->pointer)}. Nevertheless, it is available on | |
982 | many architectures, including (as of libffi 3.0.9) x86, ia64, SPARC, | |
983 | PowerPC, ARM, and MIPS, to name a few. | |
71725997 | 984 | |
726b8ba3 AW |
985 | @c Local Variables: |
986 | @c TeX-master: "guile.texi" | |
987 | @c End: |