2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @section GH: A Portable C to Scheme Interface
12 @cindex gh - reference manual
14 This chapter shows how to use the GH interface to call Guile from your
15 application's C code, and to add new Scheme level procedures to Guile
16 whose behaviour is specified by application specific code written in C.
18 Note, however, that the GH interface is now deprecated, and developers
19 are encouraged to switch to using the scm interface instead. Therefore,
20 for each GH feature, this chapter also documents how to achieve
21 the same result using the scm interface.
24 * GH deprecation:: Why the GH interface is now deprecated.
25 * Transitioning away from GH::
27 * Data types and constants defined by GH::
28 * Starting and controlling the interpreter::
30 * Executing Scheme code::
31 * Defining new Scheme procedures in C::
32 * Converting data between C and Scheme::
34 * Equality predicates::
35 * Memory allocation and garbage collection::
36 * Calling Scheme procedures from C::
41 @subsection Why the GH Interface is Now Deprecated
43 Historically, the GH interface was the product of a practical problem
44 and a neat idea. The practical problem was that the interface of the
45 @code{scm_} functions with which Guile itself was written (inherited
46 from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
47 details of the internal data representation that it was extremely
48 difficult to write a Guile extension using these functions. The neat
49 idea was to define a high level language extension interface in such a
50 way that other extension language projects, not just Guile, would be
51 able to provide an implementation of that interface; then applications
52 using this interface could be compiled with whichever of the various
53 available implementations they chose. So the GH interface was created,
54 and advertised both as the recommended interface for application
55 developers wishing to use Guile, and as a portable high level interface
56 that could theoretically be implemented by other extension language
59 Time passed, and various things changed. Crucially, an enormous number
60 of improvements were made to the @code{scm_} interface that Guile itself
61 uses in its implementation, with the result that it is now both easy and
62 comfortable to write a Guile extension with this interface. At the same
63 time, the contents of the GH interface were somewhat neglected by the
64 core Guile developers, such that some key operations --- such as smob
65 creation and management --- are simply not possible using GH alone.
66 Finally, the idea of multiple implementations of the GH interface did
67 not really crystallize (apart, I believe, from a short lived
68 implementation by the MzScheme project).
70 For all these reasons, the Guile developers have decided to deprecate
71 the GH interface --- which means that support for GH will be completely
72 removed after the next few releases --- and to focus only on the
73 @code{scm_} interface, with additions to ensure that it is as easy to
74 use in all respects as GH was.
76 It remains an open question whether a deep kind of interface portability
77 would be useful for extension language-based applications, and it may
78 still be an interesting project to attempt to define a corresponding
79 GH-like interface, but the Guile developers no longer plan to try to do
80 this as part of the core Guile project.
82 @node Transitioning away from GH
83 @subsection Transitioning away from GH
85 The following table summarizes how to transition from the GH to the
86 scm interface. The replacements that are recommended are not always
87 completely equivalent to the GH functionality that they should
88 replace. Therefore, you should read the reference documentation of
89 the replacements carefully if you are not yet familiar with them.
93 Use @code{#include <libguile.h>} instead of @code{#include
96 @item Compiling and Linking
97 Use @code{guile-config} to pick up the flags required to compile C or
98 C++ code that uses @code{libguile}, like so
101 $(CC) -o prog.o -c prog.c `guile-config compile`
104 If you are using libtool to link your executables, just use
105 @code{-lguile} in your link command. Libtool will expand this into
106 the needed linker options automatically. If you are not using
107 libtool, use the @code{guile-config} program to query the needed
108 options explicitly. A linker command like
111 $(CC) -o prog prog.o `guile-config link`
114 should be all that is needed. To link shared libraries that will be
115 used as Guile Extensions, use libtool to control both the compilation
118 @item The @code{SCM} type
119 No change: the scm interface also uses this type to represent an
120 arbitrary Scheme value.
122 @item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
125 @item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
128 @item @code{gh_enter}
129 Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile}
130 has a slightly different calling convention from @code{gh_enter}:
131 @code{scm_boot_guile}, and the main program function that you specify
132 for @code{scm_boot_guile} to call, both take an additional @var{closure}
133 parameter. @ref{Guile Initialization Functions} for more details.
136 Use @code{scm_shell} instead.
139 Use @code{scm_init_guile} instead.
141 @item @code{gh_catch}
142 Use @code{scm_internal_catch} instead.
144 @item @code{gh_eval_str}
145 Use @code{scm_c_eval_string} instead.
147 @item @code{gh_eval_str_with_catch}
148 Use @code{scm_c_eval_string} together with @code{scm_internal_catch}
151 @item @code{gh_eval_str_with_standard_handler}
152 Use @code{scm_c_eval_string} together with @code{scm_internal_catch}
153 and @code{scm_handle_by_message_no_exit} instead.
155 @item @code{gh_eval_str_with_stack_saving_handler}
156 Use @code{scm_c_eval_string} together with
157 @code{scm_internal_stack_catch} and
158 @code{scm_handle_by_message_no_exit} instead.
160 @item @code{gh_eval_file} or @code{gh_load}
161 Use @code{scm_c_primitive_load} instead.
163 @item @code{gh_eval_file_with_catch}
164 Use @code{scm_c_primitive_load} together with
165 @code{scm_internal_catch} instead.
167 @item @code{gh_eval_file_with_standard_handler}
168 Use @code{scm_c_primitive_load} together with
169 @code{scm_internal_catch} and @code{scm_handle_by_message_no_exit}
172 @item @code{gh_new_procedure}
173 @itemx @code{gh_new_procedure0_0}
174 @itemx @code{gh_new_procedure0_1}
175 @itemx @code{gh_new_procedure0_2}
176 @itemx @code{gh_new_procedure1_0}
177 @itemx @code{gh_new_procedure1_1}
178 @itemx @code{gh_new_procedure1_2}
179 @itemx @code{gh_new_procedure2_0}
180 @itemx @code{gh_new_procedure2_1}
181 @itemx @code{gh_new_procedure2_2}
182 @itemx @code{gh_new_procedure3_0}
183 @itemx @code{gh_new_procedure4_0}
184 @itemx @code{gh_new_procedure5_0}
185 Use @code{scm_c_define_gsubr} instead, but note that the arguments are
186 in a different order: for @code{scm_c_define_gsubr} the C function
187 pointer is the last argument. @ref{A Sample Guile Extension} for an
190 @item @code{gh_defer_ints} and @code{gh_allow_ints}
191 Use @code{SCM_CRITICAL_SECTION_START} and
192 @code{SCM_CRITICAL_SECTION_END} instead. Note that these macros are
193 used without parentheses, as in @code{SCM_DEFER_INTS;}.
195 @item @code{gh_bool2scm}
196 Use @code{scm_from_bool} instead.
198 @item @code{gh_int2scm}
199 Use @code{scm_from_int} instead.
201 @item @code{gh_ulong2scm}
202 Use @code{scm_from_ulong} instead.
204 @item @code{gh_long2scm}
205 Use @code{scm_from_long} instead.
207 @item @code{gh_double2scm}
208 Use @code{scm_make_real} instead.
210 @item @code{gh_char2scm}
211 Use @code{SCM_MAKE_CHAR} instead.
213 @item @code{gh_str2scm}
214 Use @code{scm_from_locale_stringn} instead.
216 @item @code{gh_str02scm}
217 Use @code{scm_from_locale_string} instead.
219 @item @code{gh_set_substr}
220 Use @code{scm_string_copy_x}.
222 @item @code{gh_symbol2scm}
223 Use @code{scm_from_locale_symbol} instead.
225 @item @code{gh_ints2scm}
226 @itemx @code{gh_doubles2scm}
227 @itemx @code{gh_chars2byvect}
228 @itemx @code{gh_shorts2svect}
229 @itemx @code{gh_longs2ivect}
230 @itemx @code{gh_ulongs2uvect}
231 @itemx @code{gh_floats2fvect}
232 @itemx @code{gh_doubles2dvect}
233 Use the uniform numeric vector function, @xref{Uniform Numeric
236 @item @code{gh_scm2bool}
237 Use @code{scm_is_true} or @code{scm_to_bool} instead.
239 @item @code{gh_scm2int}
240 Use @code{scm_to_int} instead.
242 @item @code{gh_scm2ulong}
243 Use @code{scm_to_ulong} instead.
245 @item @code{gh_scm2long}
246 Use @code{scm_to_long} instead.
248 @item @code{gh_scm2double}
249 Use @code{scm_to_double} instead.
251 @item @code{gh_scm2char}
252 Use @code{scm_to_char} instead.
254 @item @code{gh_scm2newstr}
255 Use @code{scm_to_locale_string} or similar instead.
257 @item @code{gh_get_substr}
258 Use @code{scm_c_substring} together with @code{scm_to_locale_string}
261 @item @code{gh_symbol2newstr}
262 Use @code{scm_symbol_to_string} together with @code{scm_to_locale_string} or similar instead.
264 @item @code{gh_scm2chars}
265 Use @code{scm_from_locale_string} (or similar) or the uniform numeric
266 vector functions (@pxref{Uniform Numeric Vectors}) instead.
268 @item @code{gh_scm2shorts}
269 @itemx @code{gh_scm2longs}
270 @itemx @code{gh_scm2floats}
271 @itemx @code{gh_scm2doubles}
272 Use the uniform numeric vector function, @xref{Uniform Numeric
275 @item @code{gh_boolean_p}
276 Use @code{scm_is_bool} instead.
278 @item @code{gh_symbol_p}
279 Use @code{scm_is_symbol} instead.
281 @item @code{gh_char_p}
282 Replace @code{gh_char_p (@var{obj})} with
284 scm_is_true (scm_char_p (@var{obj}))
287 @item @code{gh_vector_p}
288 Replace @code{gh_vector_p (@var{obj})} with
290 scm_is_true (scm_vector_p (@var{obj}))
293 @item @code{gh_pair_p}
294 Replace @code{gh_pair_p (@var{obj})} with
296 scm_is_true (scm_pair_p (@var{obj}))
299 @item @code{gh_number_p}
300 Use @code{scm_is_number} instead.
302 @item @code{gh_string_p}
303 Use @code{scm_is_string} instead.
305 @item @code{gh_procedure_p}
306 Replace @code{gh_procedure_p (@var{obj})} by
308 scm_is_true (scm_procedure_p (@var{obj}))
311 @item @code{gh_list_p}
312 Replace @code{gh_list_p (@var{obj})} with
314 scm_is_true (scm_list_p (@var{obj}))
317 @item @code{gh_inexact_p}
318 Replace @code{gh_inexact_p (@var{obj})} with
320 scm_is_true (scm_inexact_p (@var{obj}))
323 @item @code{gh_exact_p}
324 Replace @code{gh_exact_p (@var{obj})} with
326 scm_is_true (scm_exact_p (@var{obj}))
330 Use @code{scm_is_eq} instead.
332 @item @code{gh_eqv_p}
333 Replace @code{gh_eqv_p (@var{x}, @var{y})} with
335 scm_is_true (scm_eqv_p (@var{x}, @var{y}))
338 @item @code{gh_equal_p}
339 Replace @code{gh_equal_p (@var{x}, @var{y})} with
341 scm_is_true (scm_equal_p (@var{x}, @var{y}))
344 @item @code{gh_string_equal_p}
345 Replace @code{gh_string_equal_p (@var{x}, @var{y})} with
347 scm_is_true (scm_string_equal_p (@var{x}, @var{y}))
350 @item @code{gh_null_p}
351 Use @code{scm_is_null} instead.
354 Use @code{scm_not} instead.
356 @item @code{gh_make_string}
357 Use @code{scm_make_string} instead.
359 @item @code{gh_string_length}
360 Use @code{scm_string_length} instead.
362 @item @code{gh_string_ref}
363 Use @code{scm_string_ref} instead.
365 @item @code{gh_string_set_x}
366 Use @code{scm_string_set_x} instead.
368 @item @code{gh_substring}
369 Use @code{scm_substring} instead.
371 @item @code{gh_string_append}
372 Use @code{scm_string_append} instead.
375 Use @code{scm_cons} instead.
377 @item @code{gh_car} and @code{gh_cdr}
378 Use @code{scm_car} and @code{scm_cdr} instead.
380 @item @code{gh_cxxr} and @code{gh_cxxxr}
381 (Where each x is either @samp{a} or @samp{d}.) Use the corresponding
382 @code{scm_cxxr} or @code{scm_cxxxr} function instead.
384 @item @code{gh_set_car_x} and @code{gh_set_cdr_x}
385 Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
388 Use @code{scm_list_n} instead.
390 @item @code{gh_length}
391 Replace @code{gh_length (@var{lst})} with
393 scm_to_size_t (scm_length (@var{lst}))
396 @item @code{gh_append}
397 Use @code{scm_append} instead.
399 @item @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
400 Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by
402 scm_append (scm_list_n (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
405 @item @code{gh_reverse}
406 Use @code{scm_reverse} instead.
408 @item @code{gh_list_tail} and @code{gh_list_ref}
409 Use @code{scm_list_tail} and @code{scm_list_ref} instead.
411 @item @code{gh_memq}, @code{gh_memv} and @code{gh_member}
412 Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
414 @item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
415 Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
417 @item @code{gh_make_vector}
418 Use @code{scm_make_vector} instead.
420 @item @code{gh_vector} or @code{gh_list_to_vector}
421 Use @code{scm_vector} instead.
423 @item @code{gh_vector_ref} and @code{gh_vector_set_x}
424 Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
426 @item @code{gh_vector_length}
427 Use @code{scm_c_vector_length} instead.
429 @item @code{gh_uniform_vector_length}
430 Use @code{scm_c_uniform_vector_length} instead.
432 @item @code{gh_uniform_vector_ref}
433 Use @code{scm_c_uniform_vector_ref} instead.
435 @item @code{gh_vector_to_list}
436 Use @code{scm_vector_to_list} instead.
438 @item @code{gh_apply}
439 Use @code{scm_apply_0} instead.
441 @item @code{gh_call0}
442 @itemx @code{gh_call1}
443 @itemx @code{gh_call2}
444 @itemx @code{gh_call3}
445 Use @code{scm_call_0}, @code{scm_call_1}, etc instead.
447 @item @code{gh_display}
448 @itemx @code{gh_write}
449 @itemx @code{gh_newline}
450 Use @code{scm_display (obj, scm_current_output_port ())} instead, etc.
452 @item @code{gh_lookup}
453 Use @code{scm_variable_ref (scm_c_lookup (name))} instead.
455 @item @code{gh_module_lookup}
456 Use @code{scm_variable_ref (scm_c_module_lookup (module, name))} instead.
460 @node GH preliminaries
461 @subsection GH preliminaries
463 To use gh, you must have the following toward the beginning of your C
466 #include <guile/gh.h>
470 When you link, you will have to add at least @code{-lguile} to the list
471 of libraries. If you are using more of Guile than the basic Scheme
472 interpreter, you will have to add more libraries.
476 @node Data types and constants defined by GH
477 @subsection Data types and constants defined by GH
479 The following C constants and data types are defined in gh:
481 @code{SCM} is a C data type used to store all Scheme data, no matter what the
482 Scheme type. Values are converted between C data types and the SCM type
483 with utility functions described below (@pxref{Converting data between C
484 and Scheme}). [FIXME: put in references to Jim's essay and so forth.]
486 @defvr Constant SCM_BOOL_T
487 @defvrx Constant SCM_BOOL_F
488 The @emph{Scheme} values returned by many boolean procedures in
491 This can cause confusion because they are different from 0 and 1. In
492 testing a boolean function in libguile programming, you must always make
493 sure that you check the spec: @code{gh_} and @code{scm_} functions will
494 usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C
495 functions usually can be tested against 0 and 1, so programmers' fingers
496 tend to just type @code{if (boolean_function()) @{ ... @}}
499 @defvr Constant SCM_UNSPECIFIED
500 This is a SCM value that is not the same as any legal Scheme value. It
501 is the value that a Scheme function returns when its specification says
502 that its return value is unspecified.
505 @defvr Constant SCM_UNDEFINED
506 This is another SCM value that is not the same as any legal Scheme
507 value. It is the value used to mark variables that do not yet have a
508 value, and it is also used in C to terminate functions with variable
509 numbers of arguments, such as @code{gh_list()}.
513 @node Starting and controlling the interpreter
514 @subsection Starting and controlling the interpreter
515 @cindex libguile - start interpreter
517 In almost every case, your first @code{gh_} call will be:
519 @deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})())
520 Starts up a Scheme interpreter with all the builtin Scheme primitives.
521 @code{gh_enter()} never exits, and the user's code should all be in the
522 @code{@var{main_prog}()} function. @code{argc} and @code{argv} will be
523 passed to @var{main_prog}.
525 @deftypefun void main_prog (int @var{argc}, char *@var{argv}[])
526 This is the user's main program. It will be invoked by
527 @code{gh_enter()} after Guile has been started up.
530 Note that you can use @code{gh_repl} inside @code{gh_enter} (in other
531 words, inside the code for @code{main-prog}) if you want the program to
532 be controlled by a Scheme read-eval-print loop.
535 @cindex read eval print loop -- from the gh_ interface
536 @cindex REPL -- from the gh_ interface
537 A convenience routine which enters the Guile interpreter with the
538 standard Guile read-eval-print loop (@dfn{REPL}) is:
540 @deftypefun void gh_repl (int @var{argc}, char *@var{argv}[])
541 Enters the Scheme interpreter giving control to the Scheme REPL.
542 Arguments are processed as if the Guile program @file{guile} were being
545 Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter},
546 since any Guile interpreter calls are meaningless unless they happen in
547 the context of the interpreter.
549 Also note that when you use @code{gh_repl}, your program will be
550 controlled by Guile's REPL (which is written in Scheme and has many
551 useful features). Use straight C code inside @code{gh_enter} if you
552 want to maintain execution control in your C program.
555 You will typically use @code{gh_enter} and @code{gh_repl} when you
556 want a Guile interpreter enhanced by your own libraries, but otherwise
557 quite normal. For example, to build a Guile--derived program that
558 includes some random number routines @dfn{GSL} (GNU Scientific Library),
559 you would write a C program that looks like this:
562 #include <guile/gh.h>
565 /* random number suite */
566 SCM gw_ran_seed(SCM s)
568 gsl_ran_seed(gh_scm2int(s));
569 return SCM_UNSPECIFIED;
576 x = gh_ulong2scm(gsl_ran_random());
584 x = gh_double2scm(gsl_ran_uniform());
589 return gh_double2scm(gsl_ran_max());
595 /* random number suite */
596 gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
597 gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
598 gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
599 gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
603 main_prog (int argc, char *argv[])
611 main (int argc, char *argv[])
613 gh_enter (argc, argv, main_prog);
617 Then, supposing the C program is in @file{guile-gsl.c}, you could
618 compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}.
620 The resulting program @file{guile-gsl} would have new primitive
621 procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth.
625 @subsection Error messages
626 @cindex libguile - error messages
627 @cindex error messages in libguile
629 [FIXME: need to fill this based on Jim's new mechanism]
632 @node Executing Scheme code
633 @subsection Executing Scheme code
634 @cindex libguile - executing Scheme
635 @cindex executing Scheme
637 Once you have an interpreter running, you can ask it to evaluate Scheme
638 code. There are two calls that implement this:
640 @deftypefun SCM gh_eval_str (char *@var{scheme_code})
641 This asks the interpreter to evaluate a single string of Scheme code,
642 and returns the result of the last expression evaluated.
644 Note that the line of code in @var{scheme_code} must be a well formed
645 Scheme expression. If you have many lines of code before you balance
646 parentheses, you must either concatenate them into one string, or use
647 @code{gh_eval_file()}.
650 @deftypefun SCM gh_eval_file (char *@var{fname})
651 @deftypefunx SCM gh_load (char *@var{fname})
652 @code{gh_eval_file} is completely analogous to @code{gh_eval_str()},
653 except that a whole file is evaluated instead of a string.
654 @code{gh_eval_file} returns @code{SCM_UNSPECIFIED}.
656 @code{gh_load} is identical to @code{gh_eval_file} (it's a macro that
657 calls @code{gh_eval_file} on its argument). It is provided to start
658 making the @code{gh_} interface match the R5RS Scheme procedures
663 @node Defining new Scheme procedures in C
664 @subsection Defining new Scheme procedures in C
665 @cindex libguile - new procedures
666 @cindex new procedures
667 @cindex procedures, new
668 @cindex new primitives
669 @cindex primitives, new
671 The real interface between C and Scheme comes when you can write new
672 Scheme procedures in C. This is done through the routine
675 @deftypefn {Libguile high} SCM gh_new_procedure (char *@var{proc_name}, SCM (*@var{fn})(), int @var{n_required_args}, int @var{n_optional_args}, int @var{restp})
676 @code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name
677 will be @var{proc_name}, it will be implemented by the C function
678 (*@var{fn})(), it will take at least @var{n_required_args} arguments,
679 and at most @var{n_optional_args} extra arguments.
681 When the @var{restp} parameter is 1, the procedure takes a final
682 argument: a list of remaining parameters.
684 @code{gh_new_procedure} returns an SCM value representing the procedure.
686 The C function @var{fn} should have the form
687 @deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args})
688 The arguments are all passed as SCM values, so the user will have to use
689 the conversion functions to convert to standard C types.
691 Examples of C functions used as new Scheme primitives can be found in
692 the sample programs @code{learn0} and @code{learn1}.
697 @strong{Rationale:} this is the correct way to define new Scheme
698 procedures in C. The ugly mess of arguments is required because of how
699 C handles procedures with variable numbers of arguments.
701 @strong{NB:} what about documentation strings?
704 There are several important considerations to be made when writing the C
705 routine @code{(*fn)()}.
707 First of all the C routine has to return type @code{SCM}.
709 Second, all arguments passed to the C function will be of type
712 Third: the C routine is now subject to Scheme flow control, which means
713 that it could be interrupted at any point, and then reentered. This
714 means that you have to be very careful with operations such as
715 allocating memory, modifying static data @dots{}
717 Fourth: to get around the latter issue, you can use
718 @code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}.
721 @defmac GH_DEFER_INTS
722 @defmacx GH_ALLOW_INTS
723 These macros disable and re-enable Scheme's flow control. They
727 @c [??? have to do this right; maybe using subsections, or maybe creating a
728 @c section called Flow control issues...]
730 @c [??? Go into exhaustive detail with examples of the various possible
731 @c combinations of required and optional args...]
734 @node Converting data between C and Scheme
735 @subsection Converting data between C and Scheme
736 @cindex libguile - converting data
737 @cindex data conversion
738 @cindex converting data
740 Guile provides mechanisms to convert data between C and Scheme. This
741 allows new builtin procedures to understand their arguments (which are
742 of type @code{SCM}) and return values of type @code{SCM}.
751 @subsubsection C to Scheme
753 @deftypefun SCM gh_bool2scm (int @var{x})
754 Returns @code{#f} if @var{x} is zero, @code{#t} otherwise.
757 @deftypefun SCM gh_ulong2scm (unsigned long @var{x})
758 @deftypefunx SCM gh_long2scm (long @var{x})
759 @deftypefunx SCM gh_double2scm (double @var{x})
760 @deftypefunx SCM gh_char2scm (char @var{x})
761 Returns a Scheme object with the value of the C quantity @var{x}.
764 @deftypefun SCM gh_str2scm (char *@var{s}, int @var{len})
765 Returns a new Scheme string with the (not necessarily null-terminated) C
769 @deftypefun SCM gh_str02scm (char *@var{s})
770 Returns a new Scheme string with the null-terminated C string @var{s}
774 @deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len})
775 Copy @var{len} characters at @var{src} into the @emph{existing} Scheme
776 string @var{dst}, starting at @var{start}. @var{start} is an index into
777 @var{dst}; zero means the beginning of the string.
779 If @var{start} + @var{len} is off the end of @var{dst}, signal an
783 @deftypefun SCM gh_symbol2scm (char *@var{name})
784 Given a null-terminated string @var{name}, return the symbol with that
788 @deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n})
789 @deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n})
790 Make a scheme vector containing the @var{n} ints or doubles at memory
794 @deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n})
795 @deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n})
796 @deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n})
797 @deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n})
798 @deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n})
799 @deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n})
800 Make a scheme uniform vector containing the @var{n} chars, shorts,
801 longs, unsigned longs, floats or doubles at memory location @var{dptr}.
807 @subsubsection Scheme to C
809 @deftypefun int gh_scm2bool (SCM @var{obj})
810 @deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj})
811 @deftypefunx long gh_scm2long (SCM @var{obj})
812 @deftypefunx double gh_scm2double (SCM @var{obj})
813 @deftypefunx int gh_scm2char (SCM @var{obj})
814 These routines convert the Scheme object to the given C type.
817 @deftypefun {char *} gh_scm2newstr (SCM @var{str}, size_t *@var{lenp})
818 Given a Scheme string @var{str}, return a pointer to a new copy of its
819 contents, followed by a null byte. If @var{lenp} is non-null, set
820 @code{*@var{lenp}} to the string's length.
822 This function uses malloc to obtain storage for the copy; the caller is
823 responsible for freeing it.
825 Note that Scheme strings may contain arbitrary data, including null
826 characters. This means that null termination is not a reliable way to
827 determine the length of the returned value. However, the function
828 always copies the complete contents of @var{str}, and sets @var{*lenp}
829 to the true length of the string (when @var{lenp} is non-null).
833 @deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp)
834 Copy @var{len} characters at @var{start} from the Scheme string
835 @var{src} to memory at @var{dst}. @var{start} is an index into
836 @var{src}; zero means the beginning of the string. @var{dst} has
837 already been allocated by the caller.
839 If @var{start} + @var{len} is off the end of @var{src}, signal an
843 @deftypefun {char *} gh_symbol2newstr (SCM @var{sym}, int *@var{lenp})
844 Takes a Scheme symbol and returns a string of the form
845 @code{"'symbol-name"}. If @var{lenp} is non-null, the string's length
846 is returned in @code{*@var{lenp}}.
848 This function uses malloc to obtain storage for the returned string; the
849 caller is responsible for freeing it.
852 @deftypefun {char *} gh_scm2chars (SCM @var{vector}, chars *@var{result})
853 @deftypefunx {short *} gh_scm2shorts (SCM @var{vector}, short *@var{result})
854 @deftypefunx {long *} gh_scm2longs (SCM @var{vector}, long *@var{result})
855 @deftypefunx {float *} gh_scm2floats (SCM @var{vector}, float *@var{result})
856 @deftypefunx {double *} gh_scm2doubles (SCM @var{vector}, double *@var{result})
857 Copy the numbers in @var{vector} to the array pointed to by @var{result}
858 and return it. If @var{result} is NULL, allocate a double array large
861 @var{vector} can be an ordinary vector, a weak vector, or a signed or
862 unsigned uniform vector of the same type as the result array. For
863 chars, @var{vector} can be a string or substring. For floats and
864 doubles, @var{vector} can contain a mix of inexact and integer values.
866 If @var{vector} is of unsigned type and contains values too large to fit
867 in the signed destination array, those values will be wrapped around,
868 that is, data will be copied as if the destination array was unsigned.
872 @node Type predicates
873 @subsection Type predicates
875 These C functions mirror Scheme's type predicate procedures with one
876 important difference. The C routines return C boolean values (0 and 1)
877 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
879 The Scheme notational convention of putting a @code{?} at the end of
880 predicate procedure names is mirrored in C by placing @code{_p} at the
881 end of the procedure. For example, @code{(pair? ...)} maps to
882 @code{gh_pair_p(...)}.
884 @deftypefun int gh_boolean_p (SCM @var{val})
885 Returns 1 if @var{val} is a boolean, 0 otherwise.
888 @deftypefun int gh_symbol_p (SCM @var{val})
889 Returns 1 if @var{val} is a symbol, 0 otherwise.
892 @deftypefun int gh_char_p (SCM @var{val})
893 Returns 1 if @var{val} is a char, 0 otherwise.
896 @deftypefun int gh_vector_p (SCM @var{val})
897 Returns 1 if @var{val} is a vector, 0 otherwise.
900 @deftypefun int gh_pair_p (SCM @var{val})
901 Returns 1 if @var{val} is a pair, 0 otherwise.
904 @deftypefun int gh_procedure_p (SCM @var{val})
905 Returns 1 if @var{val} is a procedure, 0 otherwise.
908 @deftypefun int gh_list_p (SCM @var{val})
909 Returns 1 if @var{val} is a list, 0 otherwise.
912 @deftypefun int gh_inexact_p (SCM @var{val})
913 Returns 1 if @var{val} is an inexact number, 0 otherwise.
916 @deftypefun int gh_exact_p (SCM @var{val})
917 Returns 1 if @var{val} is an exact number, 0 otherwise.
921 @node Equality predicates
922 @subsection Equality predicates
924 These C functions mirror Scheme's equality predicate procedures with one
925 important difference. The C routines return C boolean values (0 and 1)
926 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
928 The Scheme notational convention of putting a @code{?} at the end of
929 predicate procedure names is mirrored in C by placing @code{_p} at the
930 end of the procedure. For example, @code{(equal? ...)} maps to
931 @code{gh_equal_p(...)}.
933 @deftypefun int gh_eq_p (SCM x, SCM y)
934 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
935 @code{eq?} predicate, 0 otherwise.
938 @deftypefun int gh_eqv_p (SCM x, SCM y)
939 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
940 @code{eqv?} predicate, 0 otherwise.
943 @deftypefun int gh_equal_p (SCM x, SCM y)
944 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
945 @code{equal?} predicate, 0 otherwise.
948 @deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2})
949 Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise.
952 @deftypefun int gh_null_p (SCM @var{l})
953 Returns 1 if @var{l} is an empty list or pair; 0 otherwise.
957 @node Memory allocation and garbage collection
958 @subsection Memory allocation and garbage collection
960 @c [FIXME: flesh this out with some description of garbage collection in
963 @c @deftypefun SCM gh_mkarray (int size)
964 @c Allocate memory for a Scheme object in a garbage-collector-friendly
969 @node Calling Scheme procedures from C
970 @subsection Calling Scheme procedures from C
972 Many of the Scheme primitives are available in the @code{gh_}
973 interface; they take and return objects of type SCM, and one could
974 basically use them to write C code that mimics Scheme code.
976 I will list these routines here without much explanation, since what
977 they do is the same as documented in @ref{Standard procedures, R5RS, ,
978 r5rs, R5RS}. But I will point out that when a procedure takes a
979 variable number of arguments (such as @code{gh_list}), you should pass
980 the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
982 @deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
983 Corresponds to the Scheme @code{(define name val)}: it binds a value to
984 the given name (which is a C string). Returns the new object.
987 @heading Pairs and lists
989 @deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b})
990 @deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
991 These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
992 ...)} procedures. Note that @code{gh_list()} is a C macro that invokes
996 @deftypefun SCM gh_car (SCM @var{obj})
997 @deftypefunx SCM gh_cdr (SCM @var{obj})
1000 @deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj})
1001 These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{}
1004 @deftypefun SCM gh_set_car_x (SCM @var{pair}, SCM @var{value})
1005 Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to
1006 the Scheme procedure @code{(set-car! ...)}.
1009 @deftypefun SCM gh_set_cdr_x (SCM @var{pair}, SCM @var{value})
1010 Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to
1011 the Scheme procedure @code{(set-cdr! ...)}.
1014 @deftypefun {unsigned long} gh_length (SCM @var{ls})
1015 Returns the length of the list.
1018 @deftypefun SCM gh_append (SCM @var{args})
1019 @deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2})
1020 @deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3})
1021 @deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4})
1022 @code{gh_append()} takes @var{args}, which is a list of lists
1023 @code{(list1 list2 ...)}, and returns a list containing all the elements
1024 of the individual lists.
1026 A typical invocation of @code{gh_append()} to append 5 lists together
1029 gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
1032 The functions @code{gh_append2()}, @code{gh_append2()},
1033 @code{gh_append3()} and @code{gh_append4()} are convenience routines to
1034 make it easier for C programs to form the list of lists that goes as an
1035 argument to @code{gh_append()}.
1038 @deftypefun SCM gh_reverse (SCM @var{ls})
1039 Returns a new list that has the same elements as @var{ls} but in the
1040 reverse order. Note that this is implemented as a macro which calls
1041 @code{scm_reverse()}.
1044 @deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k})
1045 Returns the sublist of @var{ls} with the last @var{k} elements.
1048 @deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k})
1049 Returns the @var{k}th element of the list @var{ls}.
1052 @deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls})
1053 @deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls})
1054 @deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls})
1055 These functions return the first sublist of @var{ls} whose CAR is
1056 @var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and
1057 @code{(member x ls)}, and hence use (respectively) @code{eq?},
1058 @code{eqv?} and @code{equal?} to do comparisons.
1060 If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not
1061 the empty list) is returned.
1063 Note that these functions are implemented as macros which call
1064 @code{scm_memq()}, @code{scm_memv()} and @code{scm_member()}
1068 @deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist})
1069 @deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist})
1070 @deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist})
1071 These functions search an @dfn{association list} (list of pairs)
1072 @var{alist} for the first pair whose CAR is @var{x}, and they return
1075 If no pair in @var{alist} has @var{x} as its CAR, the value
1076 @code{SCM_BOOL_F} (not the empty list) is returned.
1078 Note that these functions are implemented as macros which call
1079 @code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()}
1086 @c @deftypefun SCM gh_symbol (SCM str, SCM len)
1087 @c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len)
1088 @c Takes the given string @var{str} of length @var{len} and returns a
1089 @c symbol corresponding to that string.
1095 @deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill})
1096 @deftypefunx SCM gh_vector (SCM @var{ls})
1097 @deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i})
1098 @deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val})
1099 @deftypefunx {unsigned long} gh_vector_length (SCM @var{v})
1100 @deftypefunx SCM gh_list_to_vector (SCM @var{ls})
1101 These correspond to the Scheme @code{(make-vector n fill)},
1102 @code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i
1103 value)} @code{(vector-length v)} @code{(list->vector ls)} procedures.
1105 The correspondence is not perfect for @code{gh_vector}: this routine
1106 takes a list @var{ls} instead of the individual list elements, thus
1107 making it identical to @code{gh_list_to_vector}.
1109 There is also a difference in gh_vector_length: the value returned is a
1110 C @code{unsigned long} instead of an SCM object.
1116 @c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym})
1117 @c Make the C function @var{fn} available to Scheme programs. The function
1118 @c will be bound to the symbol @var{sym}. The arguments @var{req},
1119 @c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The
1120 @c function must take @var{req} required arguments and may take @var{opt}
1121 @c optional arguments. Any optional arguments which are not supplied by
1122 @c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is
1123 @c non-zero, it means that @var{fn} may be called with an arbitrary number
1124 @c of arguments, and that any extra arguments supplied by the caller will
1125 @c be passed to @var{fn} as a list. The @var{restp} argument is exactly
1126 @c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention.
1128 @c For example, the procedure @code{read-line}, which takes optional
1129 @c @var{port} and @var{handle-delim} arguments, would be declared like so:
1132 @c SCM scm_read_line (SCM port, SCM handle_delim);
1133 @c gh_make_subr (scm_read_line, 0, 2, 0, "read-line");
1136 @c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that
1137 @c there are no required arguments, so @code{read-line} may be called
1138 @c without any arguments at all. The @var{opt} argument is 2, to indicate
1139 @c that both the @var{port} and @var{handle_delim} arguments to
1140 @c @code{scm_read_line} are optional, and will be bound to
1141 @c @code{SCM_UNSPECIFIED} if the calling program does not supply them.
1142 @c Because the @var{restp} argument is 0, this function may not be called
1143 @c with more than two arguments.
1146 @deftypefun SCM gh_apply (SCM proc, SCM args)
1147 Call the Scheme procedure @var{proc}, with the elements of @var{args} as
1148 arguments. @var{args} must be a proper list.
1151 @deftypefun SCM gh_call0 (SCM proc)
1152 @deftypefunx SCM gh_call1 (SCM proc, SCM arg)
1153 @deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
1154 @deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
1155 Call the Scheme procedure @var{proc} with no arguments
1156 (@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can
1157 get the same effect by wrapping the arguments up into a list, and
1158 calling @code{gh_apply}; Guile provides these functions for convenience.
1162 @deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler)
1163 @deftypefunx SCM gh_throw (SCM key, SCM args)
1164 Corresponds to the Scheme @code{catch} and @code{throw} procedures,
1165 which in Guile are provided as primitives.
1168 @c [FIXME: must add the I/O section in gscm.h]
1170 @deftypefun SCM gh_is_eq (SCM a, SCM b)
1171 @deftypefunx SCM gh_is_eqv (SCM a, SCM b)
1172 @deftypefunx SCM gh_is_equal (SCM a, SCM b)
1173 These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?}
1177 @deftypefun int gh_obj_length (SCM @var{obj})
1178 Returns the raw object length.
1181 @heading Data lookup
1183 For now I just include Tim Pierce's comments from the @file{gh_data.c}
1184 file; it should be organized into a documentation of the two functions
1188 /* Data lookups between C and Scheme
1190 Look up a symbol with a given name, and return the object to which
1191 it is bound. gh_lookup examines the Guile top level, and
1192 gh_module_lookup checks the module name space specified by the
1195 The return value is the Scheme object to which SNAME is bound, or
1196 SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
1197 should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be
1198 bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference?