(index ("foreign-code" 0) ("foreign-value" 396) ("foreign-declare" 716) ("define-foreign-type" 857) ("foreign-type-size" 2003) ("define-foreign-variable" 2415) ("foreign-lambda" 3997) ("foreign-lambda*" 4316) ("foreign-safe-lambda" 5065) ("foreign-safe-lambda*" 5309) ("foreign-primitive" 5607))
(def (sig (syntax "(foreign-code STRING ...)" (id foreign-code))) (p "Executes the embedded C/C++ code " (tt "STRING ...") ", which should be a sequence of C statements, which are executed and return an unspecified result.") (highlight scheme "(foreign-code \"doSomeInitStuff();\")     =>  #<unspecified>") (p "Code wrapped inside " (tt "foreign-code") " may not invoke callbacks into Scheme."))
(def (sig (syntax "(foreign-value CODE TYPE)" (id foreign-value))) (p "Evaluates the embedded C/C++ expression " (tt "CODE") " (which may be a string or symbol), returning a value of type given in the foreign-type specifier " (tt "TYPE") ".") (highlight scheme "(print (foreign-value \"my_version_string\" c-string))"))
(def (sig (syntax "(foreign-declare STRING ...)" (id foreign-declare))) (p "Include given strings verbatim into header of generated file."))
(def (sig (syntax "(define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])" (id define-foreign-type))) (p "Defines an alias for " (tt "TYPE") " with the name " (tt "NAME") " (a symbol). " (tt "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 " (tt "ARGCONVERT") " and " (tt "RETCONVERT") " should evaluate to procedures that map argument- and result-values to a value that can be transformed to " (tt "TYPE") ":") (highlight scheme "(define-foreign-type char-vector \n  nonnull-c-string\n  (compose list->string vector->list)\n  (compose list->vector string->list) )\n\n(define strlen\n  (foreign-lambda int \"strlen\" char-vector) )\n\n(strlen '#(#\\a #\\b #\\c))                      ==> 3\n\n(define memset\n  (foreign-lambda char-vector \"memset\" char-vector char int) )\n\n(memset '#(#_ #_ #_) #\\X 3)                ==> #(#\\X #\\X #\\X)") (p "Foreign type-definitions are only visible in the compilation-unit in which they are defined, so use " (tt "include") " to use the same definitions in multiple files."))
(def (sig (syntax "(foreign-type-size TYPE)" (id foreign-type-size))) (p "Returns the size of the storage required to hold values of the given foreign type " (tt "TYPE") ". This is basically equivalent to") (highlight scheme "(foreign-value \"sizeof(TYPE)\" size_t)") (p "but also handles user-defined types and allows \"TYPE\" to be a string, which will be given literally to the " (tt "sizeof") " operator."))
(def (sig (syntax "(define-foreign-variable NAME TYPE [STRING])" (id define-foreign-variable))) (p "Defines a foreign variable of name " (tt "NAME") " (a symbol). " (tt "STRING") " should be the real name of a foreign variable or parameterless macro. If " (tt "STRING") " is not given, then the variable name " (tt "NAME") " will be converted to a string and used instead. All references and assignments (via " (tt "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 " (tt "STRING") " can name an arbitrary C expression. If no assignments are performed, then " (tt "STRING") " doesn't even have to specify an lvalue. See that " (tt "define-foreign-variable") " will not generate C declarations or memory allocation code; use it to include references to variables in external C code. To actually create Scheme variables visible from C, use " (tt "define-external") " (see the Manual section on " (int-link "/man/4/Callbacks" "Callbacks") "). For example, the following code:") (highlight scheme "(import foreign)\n(define-foreign-variable x double \"var_x\")\n(print x)") (p "will not work, because a reference to " (tt "var_x") " will be inserted in the C code, but no declaration will be included (this can be easily verified by translating the program into C with " (tt "csc -t program.scm") "). Changing the second line to " (tt "(define-external x double 0.5)") " will work (and the value 0.5 will be printed)."))
(def (sig (syntax "(foreign-lambda RETURNTYPE NAME ARGTYPE ...)" (id foreign-lambda))) (p "Represents a binding to an external routine. This form can be used in the position of an ordinary " (tt "lambda") " expression. " (tt "NAME") " specifies the name of the external procedure and should be a string or a symbol."))
(def (sig (syntax "(foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)" (id foreign-lambda*))) (p "Similar to " (tt "foreign-lambda") ", but instead of generating code to call an external function, the body of the C procedure is directly given in " (tt "STRING ...") ":") (highlight scheme "(define my-strlen\n  (foreign-lambda* int ((c-string str))\n    \"int n = 0;\n     while(*(str++)) ++n;\n     C_return(n);\") )\n\n(my-strlen \"one two three\")             ==> 13") (p "For obscure technical reasons you should use the " (tt "C_return") " macro instead of the normal " (tt "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."))
(def (sig (syntax "(foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)" (id foreign-safe-lambda))) (p "This is similar to " (tt "foreign-lambda") ", but also allows the called function to call Scheme functions. See " (int-link "Callbacks") "."))
(def (sig (syntax "(foreign-safe-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)" (id foreign-safe-lambda*))) (p "This is similar to " (tt "foreign-lambda*") ", but also allows the called function to call Scheme functions and allocate Scheme data-objects. See " (int-link "Callbacks") "."))
(def (sig (syntax "(foreign-primitive [RETURNTYPE] ((ARGTYPE VARIABLE) ...) STRING ...)" (id foreign-primitive))) (p "This is also similar to " (tt "foreign-lambda*") " but the code will be executed in a " (i "primitive") " CPS context, which means it will not actually return, but call its continuation on exit. This means that code inside this form may allocate Scheme data on the C stack (the " (i "nursery") ") with " (tt "C_alloc") " (see below). You can return multiple values inside the body of the " (tt "foreign-primitive") " form by using the following C code:") (highlight scheme "C_word av[N + 2] = { C_SCHEME_UNDEFINED, C_k, X1, ... };\nC_values(N + 2, av);") (p "where " (tt "N") " is the number of values to be returned, and " (tt "X1, ...") " are the results, which should be Scheme data objects. When returning multiple values, the return-type should be omitted.  Of course, if you have to dynamically compute the values, you do not have to use C's array initialization syntax, but you can just assign them one by one.") (p "Returning just a single value can still be done via the " (tt "C_return(...)") " macro."))
