# Accessing external objects

## foreign-code

     [syntax] (foreign-code STRING ...)

Executes the embedded C/C++ code `STRING ...`, which should be a sequence of C statements, which are executed and return an unspecified result.

    (foreign-code "doSomeInitStuff();")     =>  #<unspecified>

Code wrapped inside `foreign-code` may not invoke callbacks into Scheme.

## foreign-value

     [syntax] (foreign-value CODE TYPE)

Evaluates the embedded C/C++ expression `CODE` (which may be a string or symbol), returning a value of type given in the foreign-type specifier `TYPE`.

    (print (foreign-value "my_version_string" c-string))

## foreign-declare

     [syntax] (foreign-declare STRING ...)

Include given strings verbatim into header of generated file.

## define-foreign-type

     [syntax] (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])

Defines an alias for `TYPE` with the name `NAME` (a symbol). `TYPE` may be a type-specifier or a string naming a C type. The namespace of foreign type specifiers is separate from the normal Scheme namespace. The optional arguments `ARGCONVERT` and `RETCONVERT` should evaluate to procedures that map argument- and result-values to a value that can be transformed to `TYPE`:

    (define-foreign-type char-vector
      nonnull-c-string
      (compose list->string vector->list)
      (compose list->vector string->list) )

    (define strlen
      (foreign-lambda int "strlen" char-vector) )

    (strlen '#(#\a #\b #\c))                      ==> 3

    (define memset
      (foreign-lambda char-vector "memset" char-vector char int) )

    (memset '#(#_ #_ #_) #\X 3)                ==> #(#\X #\X #\X)

Foreign type-definitions are only visible in the compilation-unit in which they are defined, so use `include` to use the same definitions in multiple files.

## define-foreign-variable

     [syntax] (define-foreign-variable NAME TYPE [STRING])

Defines a foreign variable of name `NAME` (a symbol). `STRING` should be the real name of a foreign variable or parameterless macro. If `STRING` is not given, then the variable name `NAME` will be converted to a string and used instead. All references and assignments (via `set!`) are modified to correctly convert values between Scheme and C representation. This foreign variable can only be accessed in the current compilation unit, but the name can be lexically shadowed. Note that `STRING` can name an arbitrary C expression. If no assignments are performed, then `STRING` doesn't even have to specify an lvalue.

## foreign-lambda

     [syntax] (foreign-lambda RETURNTYPE NAME ARGTYPE ...)

Represents a binding to an external routine. This form can be used in the position of an ordinary `lambda` expression. `NAME` specifies the name of the external procedure and should be a string or a symbol.

## foreign-lambda*

     [syntax] (foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)

Similar to `foreign-lambda`, but instead of generating code to call an external function, the body of the C procedure is directly given in `STRING ...`:

    (define my-strlen
      (foreign-lambda* int ((c-string str))
        "int n = 0;
         while(*(str++)) ++n;
         C_return(n);") )

    (my-strlen "one two three")             ==> 13

For obscure technical reasons you should use the `C_return` macro instead of the normal `return` statement to return a result from the foreign lambda body as some cleanup code has to be run before execution commences in the calling code.

## foreign-safe-lambda

     [syntax] (foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)

This is similar to `foreign-lambda`, but also allows the called function to call Scheme functions and allocate Scheme data-objects. See Callbacks.

## foreign-safe-lambda*

     [syntax] (foreign-safe-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)

This is similar to `foreign-lambda*`, but also allows the called function to call Scheme functions and allocate Scheme data-objects. See Callbacks.

## foreign-primitive

     [syntax] (foreign-primitive [RETURNTYPE] ((ARGTYPE VARIABLE) ...) STRING ...)

This is also similar to `foreign-lambda*` but the code will be executed in a primitive CPS context, which means it will not actually return, but call it's continuation on exit. This means that code inside this form may allocate Scheme data on the C stack (the nursery) with `C_alloc` (see below). If the `RETURNTYPE` is omitted it defaults to `void`. You can return multiple values inside the body of the `foreign-primitive` form by calling this C function:

    C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...)

where `N` is the number of values to be returned, and `X1, ...` are the results, which should be Scheme data objects. When returning multiple values, the return-type should be omitted.

Previous: Interface to external functions and variables
Next: Foreign type specifiers