cffi(3tcl)

NAME
cffi - Commands in namespace cffi

SYNOPSIS
alias subcommand ...
alias body alias_name
alias clear
alias define name definition
alias define aliasdefs
alias delete pattern
alias list ?pattern?
alias load alias_set
call fnptr ?args?
callback subcommand ...
callback free cb
callback new protoname cmdprefix error_value
enum subcommand ...
enum clear
enum define enumname enumdefs
enum delete pattern
enum flags enumname membernames
enum list pattern
enum mask enumname membernames
enum members enumname
enum name enumname membervalue ?default?
enum sequence enumname membernames ?start?
enum unmask enumname mask
enum value enumname membername ?default?
help subcommand ...
help function FUNCNAME
help functions ?FUNCPATTERN?
limits type
memory subcommand ...
memory allocate sizespec ?tag?
memory fill pointer bytevalue count ?offset?
memory free pointer
memory frombinary bin_value ?tag?
memory fromstring value ?encoding?
memory get pointer typespec ?index?
memory get! pointer typespec ?index?
memory new typespec initializer ?tag?
memory set pointer typespec value ?index?
memory set! pointer typespec value ?index?
memory tobinary pointer size ?offset?
memory tobinary! pointer size ?offset?
memory tostring pointer ?encoding? ?offset?
memory tostring! pointer ?encoding? ?offset?
pkgconfig subcommand ...
pkgconfig get key
pkgconfig list
pointer subcommand ...
pointer address pointer
pointer cast pointer ?TAG?
pointer castable subtag supertag
pointer castables
pointer check pointer
pointer counted pointer
pointer dispose pointer
pointer isnull pointer
pointer isvalid pointer
pointer list ?args?
pointer make address ?tag?
pointer safe pointer
pointer tag pointer
prototype subcommand ...
prototype delete pattern
prototype function name fntype parameters
prototype list ?pattern?
prototype stdcall name fntype parameters
type subcommand ...
type count type
type info typedecl ?parse_mode?
type size type
Struct create OBJNAME definition ?args?
Struct new definition ?args?
OBJECT allocate ?count?
OBJECT describe
OBJECT fieldpointer pointer fieldname ?tag? ?index?
OBJECT free pointer
OBJECT frombinary bin_value
OBJECT fromnative pointer ?index?
OBJECT fromnative! pointer ?index?
OBJECT getnative pointer fieldname ?index?
OBJECT getnative! pointer fieldname ?index?
OBJECT getnativefields pointer fieldnames ?index?
OBJECT getnativefields! pointer fieldnames ?index?
OBJECT info
OBJECT name
OBJECT new ?initval?
OBJECT setnative pointer fieldname value ?index?
OBJECT setnative! pointer fieldname value ?index?
OBJECT tobinary dict_value
OBJECT tonative pointer initializer ?index?
OBJECT tonative! pointer initializer ?index?
Wrapper create OBJNAME path
Wrapper new path
OBJECT destroy
OBJECT addressof symbol
OBJECT function fnname fntype parameters
OBJECT functions fnlist
OBJECT path
OBJECT stdcall fnname fntype parameters
OBJECT stdcalls fnlist

::CFFI

This is the reference for commands in the cffi namespace. See the Start page [URL: cffi.html] for an introductory usage guide. See Concepts for a mapping of C types and program elements to the script level.

The package is loaded in standard fashion with package require:

    package require cffi

COMMANDS

    alias (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    body
        Returns the resolved body of an alias.

    clear
        Deletes all aliases from the interpreter.

    define
        Defines one or more type aliases.

    delete
        Deletes aliases matching a pattern.

    list
        Returns a list of aliases that match the specified pattern.

    load
        Loads predefined type aliases.

Refer to the documentation of each subcommand for details.

    alias body (::cffi)

Returns the resolved body of an alias.

Parameters

    alias_name
        Name of alias to be retrieved.

Description

The alias must be one defined in the current scope.

Return value

Returns the resolved body of an alias.

    alias clear (::cffi)

Deletes all aliases from the interpreter

    alias define (::cffi)

Defines one or more type aliases.
    alias define aliasdefs

Parameters

    aliasdefs
        Dictionary mapping alias names to their definition.

    definition
        Definition for the alias.

    name
        Name for type alias. Must begin with an alphabetic character and may contain alphanumerics and underscore.

Description

Given two arguments, creates an alias of the given name for passed definition. If a single argument is provided, it must be a dictionary mapping alias names to their definitions.

An error will be raised if an alias name matches a built-in type or if an alias of that name already exists with a different definition in the same scope.

The definition may itself be based on an existing alias. In this case the existing alias is immediately resolved and expanded as part of the definition so further changes to it are not reflected in the alias being defined.

See Type aliases for more on type aliases.

    alias delete (::cffi)

Deletes aliases matching a pattern.

Parameters

    pattern
        Pattern to match against aliases.

Description

The command deletes all aliases whose name matches the specified pattern. The conditions for matching the pattern are:

•   the tail of the pattern must match the tail of the alias name using Tcl's glob pattern matching rules.

•   the scope component of the alias name must match exactly.

    alias list (::cffi)

Returns a list of aliases that match the specified pattern.

Parameters

    pattern
        Pattern to match against aliases. Optional, default *.

Description

The command returns the alias names that match the specified pattern. The conditions for matching the pattern are:

•   the tail of the pattern must match the tail of the alias name using Tcl's glob pattern matching rules.

•   the scope component of the alias name must match exactly.

Return value

Returns a list of aliases that match the specified pattern.

    alias load (::cffi)

Loads predefined type aliases.

Parameters

    alias_set
        The alias set to load.

Description

The aliases are loaded into the calling scope.

The possible values of $alias_set are C, win32 (Windows only), or posix (platform dependent).

The C predefined alias set includes _Bool, bool, int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t size_t ssize_t

The win32 predefined alias set includes BOOL BOOLEAN BYTE CHAR DWORD DWORDLONG DWORD_PTR HALF_PTR HANDLE INT INT_PTR LONG LONGLONG LONG_PTR LPARAM LPVOID LRESULT SHORT SIZE_T SSIZE_T UCHAR UINT UINT_PTR ULONG ULONGLONG ULONG_PTR USHORT WORD WPARAM

The posix alias set is platform dependent. In POSIX compliant environments, it includes blkcnt_t blksize_t clock_t dev_t fsblkcnt_t fsfilcnt_t gid_t id_t ino_t key_t mode_t nlink_t off_t pid_t size_t ssize_t suseconds_t time_t uid_t. On Windows, it only includes dev_t ino_t off_t time_t.

    call (::cffi)

Invokes a C function through a function pointer.

Parameters

    fnptr
        A pointer value tagged with a prototype

    args
        Additional arguments to pass to the C function.

Description

The passed pointer $fnptr tag must corresponding to a function prototype defined through the prototype function or prototype stdcall commands.

Return value

Returns the value returned by the invoked C function.

    callback (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    free
        Frees a callback pointer.

    new Wraps a script level command into a C function.

Refer to the documentation of each subcommand for details.

    callback free (::cffi)

Frees a callback pointer

Parameters

    cb  A function pointer allocated with callback new

    callback new (::cffi)

Wraps a script level command into a C function

Parameters

    protoname
        The name of a prototype created through the prototype function or prototype stdcall commands.

    cmdprefix
        The command prefix that should be invoked when the created C function is called.

    error_value
        Not documented.

    error_result
        The value that should be returned if the command prefix raises an exception. This is optional if the function prototype specifies the void return type.

Description

The returned function pointer can be invoked through the call command but the common usage is for it to be passed to a C function that takes a callback function as an argument.

Invoking the function pointer will result in $cmdprefix being called with the additional arguments passed in the invocation. These must match the parameter types of the prototype specified in the callback definition.

The type declarations in a prototypes used for callbacks have certain restrictions. These arise because the "data flow" is now from script to the C shared library.

The parameter and return type are restricted to be scalar values and strings.

•   The out, inout and retval annotations are not permitted. This means any values to be returned to the shared library must be through explicit raw pointers.

•   All pointer type declarations must have the unsafe annotation. Other pointer safety annotations counted, dispose, disposeonsuccess cannot be specified.

•   The value checking annotations zero, nonzero, positive and nonnegative cannot be specified for the prototype return type.

•   The error handling annotations errno, winerror, lasterror and onerror cannot be specified.

•   The storeonerror and storealways annotations cannot be specified.

When $cmdprefix is called from a C function as a callback, it is executed in the Tcl context from which the C function was called and thus has access to the script level local variables etc.

When no longer needed, the callback should be freed with the callback free command.

Return value

Returns a callback function pointer that can be called from C native code.

    enum (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    clear
        Deletes all enumerations from the interpreter.

    define
        Defines a new enumeration.

    delete
        Deletes enumerations.

    flags
        Defines an enumeration as bit flags.

    list
        Lists enumerations.

    mask
        Returns an integer mask formed by bitwise OR-ing the passed enumeration members.

    members
        Returns a dictionary containing the members in an enumeration.

    name
        Returns the symbolic name of a value in an enumeration.

    sequence
        Defines an enumeration with consecutive member values.

    unmask
        Returns a list of enumeration member names corresponding to the bits set in $mask. enumeration members.

    value
        Returns the value of an enumeration member.

Refer to the documentation of each subcommand for details.

    enum clear (::cffi)

Deletes all enumerations from the interpreter

    enum define (::cffi)

Defines a new enumeration.

Parameters

    enumname
        Name of the enumeration.

    enumdefs
        Dictionary of enumeration member names to their values.

Description

Parameter declarations can reference the enumeration to indicate that the corresponding symbol names are acceptible as arguments and will be replaced by the corresponding value in the function call. Enumeration member values must be integers.

    enum delete (::cffi)

Deletes enumerations.

Parameters

    pattern
        Pattern to match.

Description

The command deletes all enumerations whose name matches the specified pattern. The conditions for matching the pattern are:

•   the tail of the pattern must match the tail of the enumeration name using Tcl's glob pattern matching rules.

•   the scope component of the enumeration name must match exactly.

    enum flags (::cffi)

Defines an enumeration as bit flags

Parameters

    enumname
        Name of the enumeration.

    membernames
        List of names of the enumeration members.

Description

For example,

    enum flags E {A B C}

would define an enumeration with A, B, C values being 1, 2 and 4.

    enum list (::cffi)

Lists enumerations.

Parameters

    pattern
        Pattern to match.

Description

The command returns the names of all enumerations whose name matches the specified pattern. The conditions for matching the pattern are:

•   the tail of the pattern must match the tail of the enumeration name using Tcl's glob pattern matching rules.

•   the scope component of the enumeration name must match exactly.

    enum mask (::cffi)

Returns an integer mask formed by bitwise OR-ing the passed enumeration members

Parameters

    enumname
        Name of the enumeration in the current scope

    membernames
        List of member names and integer values.

Return value

Returns an integer mask formed by bitwise OR-ing the passed enumeration members

See also

enum unmask

    enum members (::cffi)

Returns a dictionary containing the members in an enumeration.

Parameters

    enumname
        Name of the enumeration whose elements are to be returned.

Return value

Returns a dictionary containing the members in an enumeration.

    enum name (::cffi)

Returns the symbolic name of a value in an enumeration.

Parameters

    enumname
        Name of the enumeration.

    membervalue
        Value of an enumeration member.

    default
        Value to be returned if the member value is not found.

Description

The command will raise an error if $membervalue is not present in the enumeration and no default is provided, or if $enumname is itself undefined.

Return value

Returns the symbolic name of a value in an enumeration.

    enum sequence (::cffi)

Defines an enumeration with consecutive member values

Parameters

    enumname
        Name of the enumeration.

    membernames
        List of names of the enumeration members.

    start
        Value of first enumeration member. Optional, default 0.

Description

Each element of $membernames should have one or two elements, the first being the name of the member and the second, if present, being its value.If the second element is not present, the member is assigned a value one greater than the previous value assigned. The first member is assigned value 0 if it has no explicit assigned value.

The $start parameter is present for backward compatibility and indicates the first value to be assigned to the sequence. For future compatibility, the two-element form for the first enum member should be used instead if a starting value other than the default zero is desired.

    enum unmask (::cffi)

Returns a list of enumeration member names corresponding to the bits set in $mask. enumeration members

Parameters

    enumname
        Name of the enumeration.

    mask
        Integer bit mask value.

Description

The last element of the returned list is $mask itself. Generally, the enumeration should consist of values that do not have overlapping bits set (commonly a single bit is set in each member value). This is not enforced but results might not be as expected if this condition is not met.

Return value

Returns a list of enumeration member names corresponding to the bits set in $mask. enumeration members

See also

enum mask

    enum value (::cffi)

Returns the value of an enumeration member

Parameters

    enumname
        Name of the enumeration.

    membername
        Name of the enumeration member to retrieve.

    default
        Default value to be returned if the membername is not found.

Description

The command will raise an error if $membername is not present in the enumeration and no default is provided, or if $enumname is itself undefined.

Return value

Returns the value of an enumeration member

    help (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    function
        Returns a string describing the syntax for a CFFI wrapped function.

    functions
        Returns a list of CFFI-wrapped functions matching the pattern FUNCPATTERN

Refer to the documentation of each subcommand for details.

    help function (::cffi)

Returns a string describing the syntax for a CFFI wrapped function

Parameters

    FUNCNAME
        Name of a wrapped function.

Return value

Returns a string describing the syntax for a CFFI wrapped function

    help functions (::cffi)

Returns a list of CFFI-wrapped functions matching the pattern FUNCPATTERN

Parameters

    FUNCPATTERN
        Glob pattern to match. Optional, default *.

Description

Note that like Tcl's info commands the pattern is interpreted relative to the current namespace. So for example, to obtain the list of commands within a namespace, the namespace must also be included in the pattern. For example,

    cffi::help functions ::libzip::*

Return value

Returns a list of CFFI-wrapped functions matching the pattern FUNCPATTERN

    limits (::cffi)

Get the lower and upper limits for an integral base type

Parameters

    type
        The base type.

Return value

Returns a pair containing the minimum and maximum values for the specified type.

    memory (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    allocate
        Allocates memory of the specified size.

    fill
        Fills memory with a specified value.

    free
        Frees the memory referenced by the passed pointer.

    frombinary
        Allocates memory and copied the passed Tcl binary string into it.

    fromstring
        Allocates memory and stores a Tcl string in it in the specified encoding.

    get Converts a native value in memory into a Tcl script level value.

    get!
        Converts a value as per a type specification and stores it in memory in native form.

    new Allocates memory for a type and initializes it.

    set Converts a value as per a type specification and stores it in memory in native form.

    set!
        Converts a value as per a type specification and stores it in memory in native form.

    tobinary
        Returns the content of a memory block as a Tcl binary string.

    tobinary!
        Returns the content of a memory block as a Tcl binary string.

    tostring
        Returns the content of a memory block as a Tcl string.

    tostring!
        Returns the content of a memory block as a Tcl string.

Refer to the documentation of each subcommand for details.

    memory allocate (::cffi)

Allocates memory of the specified size

Parameters

    sizespec
        Requested size of memory block. This may be specified either as an integer value or a type specification.

    tag Tag for the returned pointer. Optional, default "".

Description

The returned memory must be eventually freed by calling memory free.

Return value

Returns a safe pointer to the allocated memory.

See also

memory new, memory free

    memory fill (::cffi)

Fills memory with a specified value

Parameters

    pointer
        Safe pointer to memory.

    bytevalue
        A value in the range 0-255

    count
        Number of bytes to be fill.

    offset
        Offset from $pointer of area to fill. May be negative for unsafe pointers. Optional, default 0.

    memory free (::cffi)

Frees the memory referenced by the passed pointer

Parameters

    pointer
        Safe pointer to memory to free.

Description

The memory must have been allocated using memory allocate, memory frombinary, memory fromstring or one of the methods of a Struct object. Null pointers are silently ignored.

See also

memory allocate

    memory frombinary (::cffi)

Allocates memory and copied the passed Tcl binary string into it.

Parameters

    bin_value
        A Tcl binary value.

    tag Tag for the returned pointer. Optional, default "".

Description

The returned memory must be eventually freed by calling memory free.

Return value

Returns a safe pointer to the allocated memory.

See also

memory tobinary, memory tobinary!

    memory fromstring (::cffi)

Allocates memory and stores a Tcl string in it in the specified encoding.

Parameters

    value
        Tcl string value.

    encoding
        The encoding to use for conversion. If unspecified or the empty string, the system encoding is used. Optional, default "".

Description

The returned memory must be eventually freed by calling memory free.

Return value

Returns a safe pointer to the allocated memory.

See also

memory tostring, memory tostring!

    memory get (::cffi)

Converts a native value in memory into a Tcl script level value

Parameters

    pointer
        Base address of memory location. The pointer must be a safe pointer but the tag is immaterial.

    typespec
        Type specification to use for conversion.

    index
        The index in memory from which value is to be retrieved. Care must be taken this is within bounds of the allocated space. Optional, default 0.

Description

The command converts the data at a memory location into a Tcl script object as per the type specification $typespec. The memory address of the data is given by $pointer if $index is unspecified or 0. Otherwise $index is treated as an index into an array based at $pointer whose elements are of the type defined by $typespec and memory address used is that of the slot given by $index. For example, if $typespec is int and $index is 2, the memory address from which the value is read is at byte offset 8 assuming ints occupy 4 bytes. If $typespec is int[3], then the size of the type specification is 12, and an index of 2 will correspond to a byte offset of 24, not 8. Be aware of these semantics when reading arrays using non-0 indices.

See also

memory get!, memory set

    memory get! (::cffi)

Converts a value as per a type specification and stores it in memory in native form

Parameters

    pointer
        Base address of memory location. The pointer is not checked for validity.

    typespec
        Type specification to use for conversion.

    index
        The index in memory from which value is to be retrieved. Care must be taken this is within bounds of the allocated space. Optional, default 0.

Description

This command is identical to the memory get command except that it does not require $pointer to be a safe pointer. See the documentation of that command for details.

See also

memory get, memory set

    memory new (::cffi)

Allocates memory for a type and initializes it.

Parameters

    typespec
        A type declaration.

    initializer
        The type-specific value to use to initialize allocated memory.

    tag The optional tag for the returned pointer. Optional, default "".

Description

The $typespec argument may be any type specificiation. If an array is specified of a larger size than the number of elements in $initializer, the remaining elements are zeroed out.

The returned memory must be eventually freed by calling memory free.

Return value

Returns a safe pointer to the allocated memory.

See also

memory allocate, memory free

    memory set (::cffi)

Converts a value as per a type specification and stores it in memory in native form

Parameters

    pointer
        Base address of memory location. The pointer must be a safe pointer but the tag is immaterial.

    typespec
        Type specification.

    value
        The script level value to be stored.

    index
        The index in memory at which the value is to be stored. Care must be taken this is within bounds of the allocated space. Optional, default 0.

Description

The command converts $value into the native form corresponding to the type specification $typespec. If $index is unspecified or 0, the native value is stored at the memory address given by $pointer. Otherwise $index is the treated as an index into an array whose elements are of the type defined by $typespec and the value is stored in the slot given by $index. For example, if $typespec is int and $index is 2, the memory address at which the value is written is at byte offset 8 assuming ints occupy 4 bytes. If $typespec is int[3], then the size of the type specification is 12, and an index of 2 will correspond to a byte offset of 24, not 8. Be aware of these semantics when writing arrays to non-0 indices to avoid memory corruption.

See also

memory get, memory set!

    memory set! (::cffi)

Converts a value as per a type specification and stores it in memory in native form

Parameters

    pointer
        Base address of memory location. The pointer is not checked for validity.

    typespec
        Type specification.

    value
        The script level value to be stored.

    index
        The index in memory at which the value is to be stored. Care must be taken this is within bounds of the allocated space. Optional, default 0.

Description

This command is identical to the memory set command except that it does not require $pointer to be a safe pointer. See the documentation of that command for details.

See also

memory get, memory set

    memory tobinary (::cffi)

Returns the content of a memory block as a Tcl binary string.

Parameters

    pointer
        Safe pointer to memory.

    size
        Number of bytes to copy from the memory block.

    offset
        Offset from $pointer of area to value. May be negative for unsafe pointers. Optional, default 0.

Return value

Returns the content of a memory block as a Tcl binary string.

See also

memory tobinary!, memory frombinary

    memory tobinary! (::cffi)

Returns the content of a memory block as a Tcl binary string.

Parameters

    pointer
        Pointer to memory.

    size
        Number of bytes to copy from the memory block.

    offset
        Offset from $pointer of area to value. May be negative for unsafe pointers. Optional, default 0.

Description

Unlike the memory tobinary method, this does not check the validity of $pointer and should be used with care.

Return value

Returns the content of a memory block as a Tcl binary string.

See also

memory tobinary, memory frombinary

    memory tostring (::cffi)

Returns the content of a memory block as a Tcl string.

Parameters

    pointer
        Safe pointer to memory.

    encoding
        The encoding to use for conversion. If unspecified or the empty string, the system encoding is used. Optional, default "".

    offset
        Offset from $pointer of area to value. May be negative for unsafe pointers. Optional, default 0.

Return value

Returns the content of a memory block as a Tcl string.

See also

memory tostring!, memory fromstring

    memory tostring! (::cffi)

Returns the content of a memory block as a Tcl string.

Parameters

    pointer
        Pointer to memory.

    encoding
        The encoding to use for conversion. If unspecified or the empty string, the system encoding is used. Optional, default "".

    offset
        Offset from $pointer of area to value. May be negative for unsafe pointers. Optional, default 0.

Description

Unlike the memory tostring method, this does not check the validity of $pointer and should be used with care.

Return value

Returns the content of a memory block as a Tcl string.

See also

memory tostring!, memory fromstring

    pkgconfig (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    get Gets the value of a configuration key.

    list
        Returns the list of keys containing information about the package configuration.

Refer to the documentation of each subcommand for details.

    pkgconfig get (::cffi)

Gets the value of a configuration key.

Parameters

    key One of the keys returned by pkgconfig list command.

Description

The following keys are supported.

    backend
        Returns libffi or dyncall indicating the backend FFI library in use.

    version
        The package version.

    compiler
        Identifies the compiler used to build the extension.

    pkgconfig list (::cffi)

Returns the list of keys containing information about the package configuration.

Return value

Returns the list of keys containing information about the package configuration.

    pointer (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    address
        Returns the address component of the pointer.

    cast
        Casts a pointer to a new tag.

    castable
        Specifies that pointers with tag $subtag are acceptable in declarations that require $supertag.

    castables
        Returns a list of tags that have been marked as castable with the pointer castable command..

    check
        Validates a pointer and raise an exception if invalid.

    counted
        Registers a pointer as a counted pointer.

    dispose
        Unregisters a safe or counted pointer.

    isnull
        Returns true if the pointer is a NULL pointer, false otherwise.

    isvalid
        Validates a pointer.

    list
        Returns a list of registered pointers optionally filtered by a tag.

    make
        Return a pointer for a memory address.

    safe
        Registers a pointer as a safe uncounted pointer.

    tag Returns the pointer tag.

Refer to the documentation of each subcommand for details.

    pointer address (::cffi)

Returns the address component of the pointer.

Parameters

    pointer
        Pointer whose address component is to be returned.

Return value

Returns the address component of the pointer.

    pointer cast (::cffi)

Casts a pointer to a new tag.

Parameters

    pointer
        Pointer to be cast.

    tag New tag to apply. This will be qualified with the current scope if not fully qualified.

Description

The cast will fail if the TAG is not castable to or from the pointer's tag. See Casting pointers.

If TAG is not specified, any existing tag is removed from the pointer (effectively marking it as a void* pointer).

Return value

Returns a pointer with the same address and new tag

    pointer castable (::cffi)

Specifies that pointers with tag $subtag are acceptable in declarations that require $supertag.

Parameters

    subtag
        Tag which is to be marked as acceptable wherever $supertag is expected. Will be qualified with current scope if necessary.

    supertag
        Tag which should accept $subtag tagged pointers. Will be qualified with current scope if necessary.

Description

See Casting pointers for more information.

    pointer castables (::cffi)

Returns a list of tags that have been marked as castable with the pointer castable command..

Return value

Returns a list of tags that have been marked as castable with the pointer castable command..

    pointer check (::cffi)

Validates a pointer and raise an exception if invalid.

Parameters

    pointer
        Pointer to be validated.

Description

For a pointer to be treated as valid,

•   it must not be NULL

•   it must be registered

•   if it is tagged, the tag must be the same as that of the registration.

If any of the above conditions is not met, an error exception is raised. Note that if $pointer is untagged, the tag of the registration is not checked.

See Pointers for more on pointer safety and registration.

    pointer counted (::cffi)

Registers a pointer as a counted pointer

Parameters

    pointer
        Pointer to be registered.

Description

A counted pointer may be registered multiple times. An error is raised if the pointer is NULL or already registered as an uncounted pointer.

See Pointers for more on counted pointers and registration.

    pointer dispose (::cffi)

Unregisters a safe or counted pointer

Parameters

    pointer
        Pointer to be unregistered.

Description

Note that the command only unregisters the pointer. It does not do anything in terms of releases any resources associated with the pointer.

An error is raised if the pointer is not registered unless it is a null pointer in which case it is ignored without error.

See Pointers for more on pointer safety and registration.

    pointer isnull (::cffi)

Returns true if the pointer is a NULL pointer, false otherwise.

Parameters

    pointer
        Pointer to be checked.

Return value

Returns true if the pointer is a NULL pointer, false otherwise.

    pointer isvalid (::cffi)

Validates a pointer.

Parameters

    pointer
        Pointer to be validated.

Description

For a pointer to be treated as valid,

•   it must not be NULL

•   it must be registered

•   if it is tagged, the tag must be the same as that of the registration.

Return a boolean true value if all the above conditions are met, otherwise false.

See Pointers for more on pointer safety and registration.

    pointer list (::cffi)

Returns a list of registered pointers optionally filtered by a tag.

Parameters

    args
        If specified, must be a single argument which is a tag. Only pointers matching the tag are returned.

Return value

Returns a list of registered pointers optionally filtered by a tag.

    pointer make (::cffi)

Return a pointer for a memory address

Parameters

    address
        Memory address as a positive integer.

    tag If not fully qualified, this will be qualified with the current namespace name.

Description

The returned pointer is not registered as safe. The caller can use the pointer safe command to mark it as such if so desired.

    pointer safe (::cffi)

Registers a pointer as a safe uncounted pointer.

Parameters

    pointer
        Pointer to be registered.

Description

It is not an error if the pointer is already registered. However, it is an error if the pointer is already registered with a different tag.

See Pointers for more on pointer safety and registration.

    pointer tag (::cffi)

Returns the pointer tag

Parameters

    pointer
        Pointer whose tag is to be returned.

Description

An empty string is returned if the pointer is not tagged.

See Pointers for more on pointer tags.

Return value

Returns the pointer tag

    prototype (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    delete
        Deletes prototypes matching a pattern.

    function
        Defines a function prototype for calling a function using the default C calling convention.

    list
        Returns a list of prototypes matching the specified pattern.

    stdcall
        Defines a function prototype for calling a function using the stdcall calling convention.

Refer to the documentation of each subcommand for details.

    prototype delete (::cffi)

Deletes prototypes matching a pattern.

Parameters

    pattern
        Pattern to match.

Description

The pattern matching algorithm is the same as that of Tcl's string match command. It is not an error if the pattern does not match any prototypes.

    prototype function (::cffi)

Defines a function prototype for calling a function using the default C calling convention.

Parameters

    name
        Name for the prototype. Must begin with an alphabetic character and may contain alphanumerics and underscore.

    fntype
        The type definition for the return value from the function.

    parameters
        List of alternating parameter name and type definitions.

Description

The $fntype and $parameters take the same form and have the same semantics as described for the ::cffi::Wrapper.function method for defining functions. However, unlike that method, this command does not create a command for invoking a C function. It only defines a prototype that can then be used in conjunction with a C function address to invoke that function.

See Prototypes and function pointers for more details.

See also

::cffi::Wrapper.function

    prototype list (::cffi)

Returns a list of prototypes matching the specified pattern.

Parameters

    pattern
        Pattern to match. Optional, default *.

Description

The pattern matching algorithm is the same as that of Tcl's string match command.

Return value

Returns a list of prototypes matching the specified pattern.

    prototype stdcall (::cffi)

Defines a function prototype for calling a function using the stdcall calling convention.

Parameters

    name
        Name for the prototype. Must begin with an alphabetic character and may contain alphanumerics and underscore.

    fntype
        The type definition for the return value from the function.

    parameters
        List of alternating parameter name and type definitions.

Description

The $fntype and $parameters take the same form and have the same semantics as described for the ::cffi::Wrapper.stdcall method for defining functions. However, unlike that method, this command does not create a command for invoking a C function. It only defines a prototype that can then be used in conjunction with a C function address to invoke that function.

See Prototypes and function pointers for more details.

See also

::cffi::Wrapper.stdcall

    type (::cffi)

A command ensemble.

Description

The ensemble supports the following subcommands:

    count
        Returns the count of elements in an array type.

    info
        Returns a dictionary containing various information about a type declaration.

    size
        Returns the size of a type in terms of the number of bytes of memory occupied by that type.

Refer to the documentation of each subcommand for details.

    type count (::cffi)

Returns the count of elements in an array type

Parameters

    type
        A type definition or alias.

Description

A return value of 0 indicates the type is not an array.

Return value

Returns the count of elements in an array type

    type info (::cffi)

Returns a dictionary containing various information about a type declaration

Parameters

    typedecl
        A type declaration.

    parse_mode
        One of param, return, field. Optional, default "".

Description

The type is parsed as a parameter type declaration, a function return type declaration or a structure field type declaration depending on the $parse_mode argument. If this is unspecified or an empty string, it is parsed in generic fashion and no context-specific validation is done.

The returned dictionary contains the following keys:

    Alignment
        The memory alignment needed for a value of that type.

    BaseSize
        The number of bytes to store a single value of the type when the type is an array. For scalars, same as Size.

    Count
        0 for scalar values, else indicates the type is an array with that number of elements.

    Size
        The number of bytes of memory needed to store a value of that type.

    Definition
        The type declaration after applying any defaults. For type aliases, this is the resolved type definition.

Return value

Returns a dictionary containing various information about a type declaration

    type size (::cffi)

Returns the size of a type in terms of the number of bytes of memory occupied by that type.

Parameters

    type
        A type definition or alias.

Description

In the case of array types, the size includes the size of the entire array and not the size of a single element.

Return value

Returns the size of a type in terms of the number of bytes of memory occupied by that type.

CLASSES

    Struct (::cffi)

Method summary

    constructor
        Constructor for the class.

    allocate
        Allocates memory for one or more C structs.

    describe
        Returns a human-readable description of the C struct definition.

    fieldpointer
        Returns a pointer corresponding to the address of a field within a native structure.

    free
        Frees memory that was allocated for a native C struct.

    frombinary
        Decodes a Tcl binary string containing a native C struct into a Tcl dictionary.

    fromnative
        Decodes native C struct(s) in memory into a Tcl dictionary.

    fromnative!
        Decodes native C struct(s) in memory into a Tcl dictionary.

    getnative
        Returns the value of a field in a native structure in memory.

    getnative!
        Returns the value of a field in a native structure in memory.

    getnativefields
        Retrieve values of multiple fields from a native struct in memory.

    getnativefields!
        Retrieve values of multiple fields from a native struct in memory.

    info
        Returns a dictionary containing information about the struct layout.

    name
        Returns the name of the struct.

    new Allocates and initializes a native struct in memory.

    setnative
        Sets the value of a field in a native structure in memory.

    setnative!
        Sets the value of a field in a native structure in memory.

    tobinary
        Encodes the Tcl representation of a C struct value into a Tcl binary string.

    tonative
        Writes the Tcl dictionary representation of a C struct value to memory in native form.

    tonative!
        Writes the Tcl dictionary representation of a C struct value to memory in native form.

    constructor (::cffi::Struct)

Constructs a script level object that maps to a C struct definition.
    Struct new definition ?args?

Parameters

    definition
        Defines the layout and type of the C struct fields.

    args
        Options. Currently the only option is -clear

Description

The created object can be used to pass arguments to and from functions, allocate memory, encode and decode native C structs in memory etc.

The $definition argument is a dictionary mapping field names to the corresponding types. See Structs for more information.

The name of the created struct is the same as the name of the returned object without the initial :: global namespace qualifier. This name can be retrieved with the name method and is used to identify the struct when tagging pointers and for typing function parameters and nested struct fields.

If the -clear option is present, the memory of structures of this type is cleared before the field values are initialized. In this case, missing field values in a struct value will not result in an error being raised even if no default annotation is included for the field. This also effectively provides a default zero value for all fields.

    allocate (::cffi::Struct)

Allocates memory for one or more C structs.

Parameters

    count
        Number of structs to allocate. Optional, default 1.

Description

The allocated memory is not initialized even if the struct definition includes the -clear option.

It must be freed by calling the free method.

Return value

Returns a safe pointer to the allocated memory tagged with the struct name.

    describe (::cffi::Struct)

Returns a human-readable description of the C struct definition.

Description

This is primarily for debugging and troubleshooting purposes.

Return value

Returns a human-readable description of the C struct definition.

    fieldpointer (::cffi::Struct)

Returns a pointer corresponding to the address of a field within a native structure

Parameters

    pointer
        Pointer to memory allocated for the C struct or array. Must be a safe pointer tagged with the struct name.

    fieldname
        Name of the field.

    tag Tag for the returned pointer. Optional, default "".

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

Description

Note the returned pointer is not registered as a safe pointer.

Return value

Returns a pointer corresponding to the address of a field within a native structure

    free (::cffi::Struct)

Frees memory that was allocated for a native C struct.

Parameters

    pointer
        A pointer returned by allocate

    frombinary (::cffi::Struct)

Decodes a Tcl binary string containing a native C struct into a Tcl dictionary.

Parameters

    bin_value
        A Tcl binary value containing the C struct.

Return value

Returns the dictionary representation.

    fromnative (::cffi::Struct)

Decodes native C struct(s) in memory into a Tcl dictionary.

Parameters

    pointer
        Safe pointer to the C struct or array of structs in memory.

    index
        The index position at which the struct is to be written. Note this interpreted as an index into an array of structs, not as a byte offset into memory. Optional, default 0.

Description

The decoded dictionary or dictionaries are keyed by the field names of the struct.

Return value

Returns a dictionary of the decoded struct.

See also

fromnative!, tonative, frombinary

    fromnative! (::cffi::Struct)

Decodes native C struct(s) in memory into a Tcl dictionary.

Parameters

    pointer
        Safe or unsafe pointer to the C struct or array of structs in memory.

    index
        The index position at which the struct is to be written. Note this interpreted as an index into an array of structs, not as a byte offset into memory. Optional, default 0.

Description

The decoded dictionary or dictionaries are keyed by the field names of the struct.

Return value

Returns a dictionary of the decoded struct.

See also

fromnative, tonative, frombinary

    getnative (::cffi::Struct)

Returns the value of a field in a native structure in memory

Parameters

    pointer
        Safe pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    fieldname
        Name of the field.

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

Description

In the case of fields of type pointer, the returned pointer is registered as a safe pointer unless the field was marked with the unsafe annotation.

Return value

Returns the value of a field in a native structure in memory

    getnative! (::cffi::Struct)

Returns the value of a field in a native structure in memory

Parameters

    pointer
        Safe or unsafe pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    fieldname
        Name of the field.

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

Description

In the case of fields of type pointer, the returned pointer is registered as a safe pointer unless the field was marked with the unsafe annotation.

Return value

Returns the value of a field in a native structure in memory

    getnativefields (::cffi::Struct)

Retrieve values of multiple fields from a native struct in memory.

Parameters

    pointer
        Pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    fieldnames
        List of field names.

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

Return value

Returns a list of field values in the same order as $fieldnames

    getnativefields! (::cffi::Struct)

Retrieve values of multiple fields from a native struct in memory.

Parameters

    pointer
        Safe or unsafe pointer to memory allocated for the C struct. Must be tagged with the struct name.

    fieldnames
        List of field names.

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

Return value

Returns a list of field values in the same order as $fieldnames

    info (::cffi::Struct)

Returns a dictionary containing information about the struct layout

Description

The returned dictionary has the following fields:

    Size
        Size of the struct.

    Alignment
        Struct alignment.

    Fields
        Dictionary of fields keyed by field name. The value is another nested dictionary with keys Size, Offset, and Definition containing the size, offset in struct, and type definition of the field.

Return value

Returns a dictionary containing information about the struct layout

    name (::cffi::Struct)

Returns the name of the struct.

Description

Note the name of the struct is different from the name of the object name.

Return value

Returns the name of the struct.

    new (::cffi::Struct)

Allocates and initializes a native struct in memory.

Parameters

    initval
        Initial value for the struct as a dictionary mapping field names to values. Optional, default "".

Description

If no argument is supplied or fields are missing, defaults from the struct definition are used for initialization. An error is raised if any fields are not defaulted.

The allocated memory must be freed by calling the free method for the struct.

Return value

Returns a safe pointer to the allocated memory tagged with the struct name.

    setnative (::cffi::Struct)

Sets the value of a field in a native structure in memory

Parameters

    pointer
        Safe pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    fieldname
        Name of the field.

    value
        Value to store in the field.

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

    setnative! (::cffi::Struct)

Sets the value of a field in a native structure in memory

Parameters

    pointer
        Safe or unsafe pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    fieldname
        Name of the field.

    value
        Value to store in the field.

    index
        If present, $pointer is interpreted as pointing to an array of structs and this is the index into that array. Optional, default 0.

    tobinary (::cffi::Struct)

Encodes the Tcl representation of a C struct value into a Tcl binary string.

Parameters

    dict_value
        A Tcl dictionary representation of a C struct value.

Return value

Returns the binary string containing the native C struct.

    tonative (::cffi::Struct)

Writes the Tcl dictionary representation of a C struct value to memory in native form.

Parameters

    pointer
        Safe pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    initializer
        The Tcl dictionary value.

    index
        The index position at which the struct is to be written. Note this interpreted as an index into an array of structs, not as a byte offset into memory. Optional, default 0.

See also

tonative!, fromnative, tobinary

    tonative! (::cffi::Struct)

Writes the Tcl dictionary representation of a C struct value to memory in native form.

Parameters

    pointer
        Safe or unsafe pointer to memory allocated for the C struct or array. Must be tagged with the struct name.

    initializer
        The Tcl dictionary value.

    index
        The index position at which the struct is to be written. Note this interpreted as an index into an array of structs, not as a byte offset into memory. Optional, default 0.

See also

tonative, fromnative, tobinary

    Wrapper (::cffi)

Method summary

    constructor
        Constructor for the class.

    destructor
        Destructor for the class.

    addressof
        Returns the address of a symbol from the loaded library.

    function
        Creates a Tcl command to invoke a C function in the loaded library.

    functions
        Creates Tcl commands for multiple C functions within the loaded library.

    path
        Returns the file system path for the wrapped library or image wrapped by the object.

    stdcall
        Creates a Tcl command to invoke a C function that uses the __stdcall calling convention from the loaded library..

    stdcalls
        Creates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention.

    constructor (::cffi::Wrapper)

Wraps a shared library / DLL, loading it in the process.
    Wrapper new path

Parameters

    path
        Path to the shared library.

Description

It is strongly recommended that the path to the shared library be specified as an absolute path. Otherwise, it is located in a system-specific manner involving operating system version, environment variables, registry settings (on Windows), phase of the moon etc.. This is not advisable for both reliability and security reasons.

When no longer needed, the object can be deleted in the usual manner (via rename to an empty string) or by invoking its destroy method.

Return value

Returns the name of the created object.

    destructor (::cffi::Wrapper)

Destroys the object and releases internal resources.

Description

The managed library may be unloaded if there is nothing else holding a reference to it.

    addressof (::cffi::Wrapper)

Returns the address of a symbol from the loaded library.

Parameters

    symbol
        Name of the symbol.

Description

The command will raise an error if the symbol is not found.

Return value

Returns the address of a symbol from the loaded library.

    function (::cffi::Wrapper)

Creates a Tcl command to invoke a C function in the loaded library.

Parameters

    fnname
        Name of the function and optionally, Tcl command.

    fntype
        The type definition for the return value from the function.

    parameters
        List of alternating parameter name and type definitions.

Description

The command creates a Tcl command corresponding to a C function contained in the library. The function must be one that follows the default C calling convention (See Calling conventions).

The $fnname argument is a one or two element list, the first being the name of the C function and the second, if present, being the name of the corresponding Tcl command. The latter defaults to the former if unspecified. Unless fully qualified, the command is created in the namespace from which it is called.

The return type of the C function is specified through the $fntype argument which should be a type declaration.

The $parameters argument is a list of alternating parameter names and type declarations that describe the parameters of the C function. The parameter name is only used to construct error messages while the latter determines how arguments are converted and passed to the C function.

The return type as well as parameter type declarations may have annotations that control semantics and behavior with respect to how values are passed and converted between Tcl and C. See Functions for details of these.

The command will raise an error if the function identified by $cname is not found in the loaded DLL.

Return value

Returns the name of the created Tcl command.

    functions (::cffi::Wrapper)

Creates Tcl commands for multiple C functions within the loaded library.

Parameters

    fnlist
        List of function definitions.

Description

This is a wrapper around the function method that provides some syntactic sugar for defining multiple functions. The $fnlist argument is a flat (not nested) list of function name, return type and parameter list in the same form as described for the function method.

    path (::cffi::Wrapper)

Returns the file system path for the wrapped library or image wrapped by the object.

Description

The returned path may be or may not be normalized and may be in native form or Tcl's canonical form. If no path argument was provided to the constructor, an empty string may be returned on some platforms.

Return value

Returns the file system path for the wrapped library or image wrapped by the object.

    stdcall (::cffi::Wrapper)

Creates a Tcl command to invoke a C function that uses the __stdcall calling convention from the loaded library..

Parameters

    fnname
        Name of the function and optionally, Tcl command.

    fntype
        The type definition for the return value from the function.

    parameters
        List of alternating parameter name and type definitions.

Description

The command creates a Tcl command corresponding to a C function contained in the library. The function must be one that follows the __stdcall calling convention (See Calling conventions). The only platform where this differs from the C calling convention is 32-bit Windows. On other platforms, this method is a synonym for function.

See function for other details.

Return value

Returns the name of the created Tcl command.

    stdcalls (::cffi::Wrapper)

Creates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention.

Parameters

    fnlist
        List of function definitions.

Description

This is a wrapper around the stdcall method that provides some syntactic sugar for defining multiple functions. The $fnlist argument is a flat (not nested) list of function name, return type and parameter list in the same form as described for the stdcall method.