1.7 Functions

define C-variable

Definition macro

Summary

Describes C variables to the c-ffi.

Signature

define C-variable getter-name :: c-type 
  #key setter c-name import: boolean
end [C-variable]

Arguments

getter-name: A Dylan variable name.
c-type: A Dylan name.
setter: #f or a Dylan variable name.
c-name: A string constant.
import: #f or #t.

Library

c-ffi

Module

c-ffi

Description

Describes C variables to the C-FFI. It defines a getter and setter function for accessing the variable's value. The c-name keyword argument is required and gives the C name of the variable to be accessed. The setter keyword allows you to specify the name of the setter function, or if a setter function is to be defined at all. If setter is #f, no setter function will be defined.

The import: option indicates if the C variable must be imported from another .dll or not. #t indicates it is in another .dll and must be imported, #f means that it is not to be imported. Whether the variable has to be imported from another .dll or not is determined by which Dylan project the C source files are part of. If they are in the same project as the C-variable definition then the value of "import:" should be #f as the definition and variable will be linked into the same .dll. If the definition is in a different project from the C source files then they will be in separate .dlls and import: needs to be #t. The default value is #f.

For integer, float, or pointer-typed C variables the representation is clear and unambiguous. For C struct or union typed variables the translation is not so simple. A C union or struct has no direct representation in Dylan. You may only have a reference to the C object in Dylan through a <c-pointer> object. For this reason, define c-variable is not permitted for variables with C aggregate types. Use Define C-address for those variables.

Example:

? define C-variable process-count :: <C-int>, 
    c-name: "process_count" end;

? process-count();
57

? process-count() := 0;
0

? process-count();
0

? define C-variable machine-name-1 :: <C-char*>, 
    c-name: "MachineName";
end;

? machine-name-1();
#{<C-char*> #xaaabc00}

In C and other static languages what is known as a variable is a named allocation of memory. To access a global C variable from Dylan it is occasionally necessary to get a handle to the location where that variable is kept. The define C-address macro can be used for this purpose.