3.2.1 Wrapping a C Function

As seen in See A Simple Example, wrapping a C function using G-Wrap’s high-level functions is relatively simple. Essentially, it boils down to a call to the wrap-function! GOOPS method.

method: wrap-function! (wrapset <gw-wrapset>) . args

Add the C function described by args to the list of functions to be wrapped by wrapset. The arguments in args must contain the following named parameters (see (ice-9 optargs) in The GNU Guile Reference Manual):

#:name

the symbol which should be bound to the wrapped function in Scheme at runtime.

#:returns

the symbol naming the G-Wrap wrapped type of the C function result.

#:c-name

a string giving the C function’s name.

#:arguments

a list of the C function’s arguments where each element is of the form (more details below).

#:description

a string describing the function; this string may contain Texinfo markup.

The argument list which is passed as the #:arguments named parameter consists of a list of argument specifiers. Each argument specifier is itself a two-element list where:

• the first element is a type specifier;
• the second element is a symbol that names the parameter.

The type specifier may in turn be one of the following:

• a symbol naming a wrapped type;
• a list containing a symbol naming a wrapped type and type qualifier (in G-Wrap’s code, this is usually referred to as a typespec, although this name is quite unfortunate); the type qualifier may be one of:

  in

  if the parameter in question is an input parameter;

  out

  if the parameter in question is an output parameter;

  caller-owned

  if the parameter in question is a C pointer that points to memory controlled by the caller;

  callee-owned

  if the parameter in question is a C pointer that points to memory whose control is passed to the callee (FIXME: give an example);

  null-ok

  if the Scheme input parameter is to be converted to a C pointer, then let G-Wrap know that #f is a valid value for this parameter; #f will translate to the NULL pointer in C;

  aggregated

  if the parameter in question points to a C object that is aggregated by the object returned by the function being wrapped (more on this below). By object returned, we mean a wrapped C pointer or WCP (see Wrapping a C Pointer Type) that is either the return value or an out argument.

To illustrate this, here is an example of a valid argument description list (type mchars will be detailed later on, see C Types Provided in the Standard Wrapset):

'(((mchars null-ok caller-owned) input-string)
  (long input-integer)
  ((double out) output-floating-point))

Examples of valid usage patterns of wrap-function! are available in See Creating a Wrapper Module.