api-foreign.texi 37 KB

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