::cffiTop, Main, Index
This is the reference for commands in the cffi namespace. See the Start page 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
CommandsTop, Main, Index
alias [::cffi]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Returns the resolved body of an alias. | |
| Deletes all aliases from the interpreter. | |
| Defines one or more type aliases. | |
| Deletes aliases matching a pattern. | |
| Returns a list of aliases that match the specified pattern. | |
| Loads predefined type aliases. |
Refer to the documentation of each subcommand for details.
alias body [::cffi]Top, Main, Index
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]Top, Main, Index
Deletes all aliases from the interpreter
alias define [::cffi]Top, Main, Index
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]Top, Main, Index
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]Top, Main, Index
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 the pattern's scope exactly. If the pattern does not include a scope, the caller's scope is assumed.
Return value
Returns a list of aliases that match the specified pattern.
alias load [::cffi]Top, Main, Index
Loads predefined type aliases.
Parameters
alias_set | The alias set to load. |
Description
The aliases are loaded into the ::cffi::c scope. Since this scope is also searched when looking up aliases, the aliases defined by this command is available in all namespace without explicit qualification.
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.
arena [::cffi]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Allocates memory in the current arena frame in the memory arena. | |
| Allocates memory in the current arena for a type and initializes it. | |
| Pops the current frame from the memory arena. | |
| Pushes a new stack frame on the memory arena. |
Refer to the documentation of each subcommand for details.
arena allocate [::cffi]Top, Main, Index
Allocates memory in the current arena frame in the memory arena.
Parameters
sizespec | Requested size of memory block. This may be specified either as an integer value or a type specification (optional) |
tag | Tag for returned pointer. Optional, default "". |
Description
The allocated memory will stay allocated until the frame is destroyed with arena popframe. The size $sizespec may be specified as a positive integer or a CFFI type declaration in which case the memory allocated is that of the type's size.
Return value
Returns a safe pointer to the allocation.
See also
arena new [::cffi]Top, Main, Index
Allocates memory in the current arena 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 will be freed when the arena frame is freed with arena popframe.
Return value
Returns a safe pointer to the allocated memory.
See also
arena popframe [::cffi]Top, Main, Index
Pops the current frame from the memory arena.
Description
All allocations from the popped frame are freed and pointers to these unregistered.
arena pushframe [::cffi]Top, Main, Index
Pushes a new stack frame on the memory arena.
arena pushframe size ?tag?
Parameters
sizespec | Requested size of memory block. This may be specified either as an integer value or a type specification (optional) |
tag | Tag for returned pointer if $size is specified (optional) |
Description
The command allocate a new frame in the memory arena stack. All allocations from this frame will stay valid only until the corresponding call to arena popframe.
If no arguments are specified, the command initializes an empty frame. Otherwise it allocates storage of $sizespec bytes within the new frame and returns a pointer to it. The size $sizespec may be specified as a positive integer or a CFFI type declaration in which case the memory allocated is that of the type's size.
Return value
Returns an empty string if not arguments were specified or a safe pointer.
See also
arena allocate, arena popframe
call [::cffi]Top, Main, Index
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]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Frees a callback pointer. | |
| Wraps a script level command into a C function. |
Refer to the documentation of each subcommand for details.
callback free [::cffi]Top, Main, Index
Frees a callback pointer
Parameters
cb | A function pointer allocated with callback new |
callback new [::cffi]Top, Main, Index
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 | 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,inoutandretvalannotations 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,disposeonsuccesscannot be specified. - The value checking annotations
zero,nonzero,positiveandnonnegativecannot be specified for the prototype return type. - The error handling annotations
errno,winerror,lasterrorandonerrorcannot be specified. - The
storeonerrorandstorealwaysannotations 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]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Defines a new enumeration and alias of the same name. | |
| Deletes all enumerations from the interpreter. | |
| Defines a new enumeration. | |
| Deletes enumerations. | |
| Defines an enumeration as bit flags. | |
| Lists enumerations. | |
| Returns an integer mask formed by bitwise OR-ing the passed enumeration members. | |
| Returns a dictionary containing the members in an enumeration. | |
| Returns the symbolic name of a value in an enumeration. | |
| Returns a list containing the names of members in an enumeration. | |
| Defines an enumeration with consecutive member values. | |
Returns a list of enumeration member names corresponding to the bits set in $mask. | |
| Returns the value of an enumeration member. |
Refer to the documentation of each subcommand for details.
enum alias [::cffi]Top, Main, Index
Defines a new enumeration and alias of the same name
Parameters
enumname | Name of the enumeration. |
enumdefs | Dictionary of enumeration member names to their values. |
typedecl | The type to be used for the alias. Should have an integer base type and may contain other attributes except enum. |
Description
The created alias has the same qualified name as the enum and has the corresponding enum attribute.
Return value
Returns the fully qualified enumeration name.
enum clear [::cffi]Top, Main, Index
Deletes all enumerations from the interpreter
enum define [::cffi]Top, Main, Index
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.
Return value
Returns the fully qualified enumeration name.
enum delete [::cffi]Top, Main, Index
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]Top, Main, Index
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.
Return value
Returns the fully qualified enumeration name.
enum list [::cffi]Top, Main, Index
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]Top, Main, Index
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 members [::cffi]Top, Main, Index
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]Top, Main, Index
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 names [::cffi]Top, Main, Index
Returns a list containing the names of members in an enumeration.
Parameters
enumname | Name of the enumeration whose element names are to be returned. |
Return value
Returns a list containing the names of members in an enumeration.
enum sequence [::cffi]Top, Main, Index
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.
Return value
Returns the fully qualified enumeration name.
enum unmask [::cffi]Top, Main, Index
Returns a list of enumeration member names corresponding to the bits set in $mask.
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.
See also
enum value [::cffi]Top, Main, Index
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]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Returns a string describing an alias definition. | |
| Returns a string describing an enum definition. | |
| Returns a string describing the syntax and parameter definitions for a CFFI wrapped function. | |
Returns a list of CFFI-wrapped functions matching the pattern PATTERN. | |
| Returns a string describing field types in a Struct. | |
| Returns a string describing field types in a Union. |
Refer to the documentation of each subcommand for details.
help alias [::cffi]Top, Main, Index
Returns a string describing an alias definition.
Parameters
NAME | Name of a alias |
Return value
Returns a string describing an alias definition.
help enum [::cffi]Top, Main, Index
Returns a string describing an enum definition.
Parameters
NAME | Name of a enum |
Return value
Returns a string describing an enum definition.
help function [::cffi]Top, Main, Index
Returns a string describing the syntax and parameter definitions for a CFFI wrapped function.
Parameters
NAME | Name of a wrapped function. |
Return value
Returns a string describing the syntax and parameter definitions for a CFFI wrapped function.
help functions [::cffi]Top, Main, Index
Returns a list of CFFI-wrapped functions matching the pattern PATTERN.
Parameters
PATTERN | 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 PATTERN.
help struct [::cffi]Top, Main, Index
Returns a string describing field types in a Struct.
Parameters
NAME | Name of a Struct |
Return value
Returns a string describing field types in a Struct.
help union [::cffi]Top, Main, Index
Returns a string describing field types in a Union.
Parameters
NAME | Name of a Union |
Return value
Returns a string describing field types in a Union.
limits [::cffi]Top, Main, Index
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]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Allocates memory of the specified size. | |
| Fills memory with a specified value. | |
| Frees the memory referenced by the passed pointer. | |
| Allocates memory and copied the passed Tcl binary string into it. | |
| Allocates memory and stores a Tcl string in it in the specified encoding. | |
| Allocates memory and stores a Tcl string as a sequence of Tcl_UniChars. | |
| Allocates memory and stores a Tcl string as a sequence of winchars. | |
| Converts a native value in memory into a Tcl script level value. | |
| Converts a native value in memory into a Tcl script level value. | |
| Allocates memory for a type and initializes it. | |
| Converts a value as per a type specification and stores it in memory in native form. | |
| Converts a value as per a type specification and stores it in memory in native form. | |
| Returns the content of a memory block as a Tcl binary string. | |
| Returns the content of a memory block as a Tcl binary string. | |
| Returns the content of a memory block as a Tcl string. | |
| Returns the content of a memory block as a Tcl string. | |
| Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string. | |
| Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string. | |
| Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string. | |
| Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string. |
Refer to the documentation of each subcommand for details.
memory allocate [::cffi]Top, Main, Index
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 fill [::cffi]Top, Main, Index
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]Top, Main, Index
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 frombinary [::cffi]Top, Main, Index
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]Top, Main, Index
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 fromunistring [::cffi]Top, Main, Index
Allocates memory and stores a Tcl string as a sequence of Tcl_UniChars.
Parameters
value | Tcl string value. |
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 tounistring, memory tounistring!
memory fromwinstring [::cffi]Top, Main, Index
Allocates memory and stores a Tcl string as a sequence of winchars.
Parameters
value | Tcl string value. |
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 towinstring, memory towinstring!
memory get [::cffi]Top, Main, Index
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! [::cffi]Top, Main, Index
Converts a native value in memory into a Tcl script level value
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 new [::cffi]Top, Main, Index
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 set [::cffi]Top, Main, Index
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 set! [::cffi]Top, Main, Index
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 tobinary [::cffi]Top, Main, Index
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]Top, Main, Index
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]Top, Main, Index
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]Top, Main, Index
Returns the content of a memory block as a Tcl string.
Parameters
pointer | Pointer to memory. Need not be a safe pointer. |
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. 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
memory tounistring [::cffi]Top, Main, Index
Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.
Parameters
pointer | Safe pointer to memory. |
offset | Offset in Tcl_UniChar units from $pointer of area to value. May be negative for unsafe pointers. Optional, default 0. |
Return value
Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.
See also
memory tounistring!, memory fromunistring
memory tounistring! [::cffi]Top, Main, Index
Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.
Parameters
pointer | Pointer to memory. Need not be a safe pointer. |
offset | Offset in Tcl_UniChar units from $pointer of area to value. May be negative. Optional, default 0. |
Return value
Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.
See also
memory tounistring, memory fromunistring
memory towinstring [::cffi]Top, Main, Index
Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.
Parameters
pointer | Safe pointer to memory. |
offset | Offset in WCHAR units from $pointer of area to value. May be negative for unsafe pointers. Optional, default 0. |
Return value
Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.
See also
memory towinstring!, memory fromwinstring
memory towinstring! [::cffi]Top, Main, Index
Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.
Parameters
pointer | Pointer to memory. Need not be a safe pointer. |
offset | Offset in WCHAR units from $pointer of area to value. May be negative. Optional, default 0. |
Return value
Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.
See also
memory towinstring!, memory fromwinstring
pkgconfig [::cffi]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Gets the value of a configuration key. | |
| Returns the list of keys containing information about the package configuration. |
Refer to the documentation of each subcommand for details.
pkgconfig get [::cffi]Top, Main, Index
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]Top, Main, Index
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]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Returns the address component of the pointer. | |
| Casts a pointer to a new tag. | |
Specifies that pointers with tag $subtag are acceptable in declarations that require $supertag. | |
| Returns a list of tags that have been marked as castable with the pointer castable command.. | |
| Validates a pointer and raise an exception if invalid. | |
| Compares if two pointers are the same. | |
| Registers a pointer as a counted pointer. | |
| Unregisters a safe or counted pointer. | |
| Returns a dictionary containing registration information about a pointer. | |
| Unregisters a safe, counted or pinned pointer irrespective its reference count. | |
| Returns true if the pointer is a NULL pointer, false otherwise. | |
| Validates a pointer. | |
| Returns a list of registered pointers optionally filtered by a tag. | |
| Return a pointer for a memory address. | |
| Pins a pointer as permanently safe. | |
| Registers a pointer as a safe uncounted pointer. | |
| Returns the pointer tag. | |
| Makes pointers with the specified tag uncastable to another type. |
Refer to the documentation of each subcommand for details.
pointer address [::cffi]Top, Main, Index
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]Top, Main, Index
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. In addition, the cast will fail if the pointer is registered as a safe pointer and the pointer's tag is not castable to the tag in the registration.
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]Top, Main, Index
Specifies that pointers with tag $subtag are acceptable in declarations that require $supertag.
Parameters
subtags | List of tags which are 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]Top, Main, Index
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]Top, Main, Index
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 or implicitly castable to it.
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 compare [::cffi]Top, Main, Index
Compares if two pointers are the same
Parameters
ptr1 | The first pointer to compare. |
ptr2 | The second pointer to compare. |
Return value
Returns 1 if both address and tag components match, -1 if address matches but tags are different and 0 otherwise.
pointer counted [::cffi]Top, Main, Index
Registers a pointer as a counted pointer
Parameters
pointer | Pointer to be registered. |
Description
In the case that the pointer is already registered, behavior depends on the existing registration:
- If the pointer is already registered as a pinned pointer, the command has no effect.
- If the pointer is already registered as a counted pointer, the command has no effect if the tag is the same as the registered tag or can be implicitly cast to it. Otherwise the registered tag is replaced.
- If the pointer is registered as an uncounted pointer, the registration, including tag, is overwritten as a counted pointer with a reference count of 1.
In the case that the pointer is registered with a different tag, if the pointer tag cannot be implicitly cast to the registered tag, the registered tag is replaced by the pointer tag.
See Pointers for more on counted pointers and registration.
Return value
Returns the registered pointer.
pointer dispose [::cffi]Top, Main, Index
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 info [::cffi]Top, Main, Index
Returns a dictionary containing registration information about a pointer.
Parameters
pointer | Pointer for which registration information is required. |
Description
The returned dictionary always contains the keys Tag containing the pointer tag and Registration containing one of the values none, safe, pinned or counted. If the Registration value is not unregistered, the dictionary contains the additional keys RegisteredTag, holding the tag of the pointer in the registry, and Match which may have one of the values exact, derived or mismatch.
Return value
Returns a dictionary containing registration information about a pointer.
pointer invalidate [::cffi]Top, Main, Index
Unregisters a safe, counted or pinned pointer irrespective its reference count.
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.
The command differs from pointer dispose in that
- it unregisters a counted pointer even if its reference count was greater than 1.
- it unregisters pinned pointers
- it does not raise an error for null pointers
See Pointers for more on pointer safety and registration.
pointer isnull [::cffi]Top, Main, Index
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]Top, Main, Index
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 or implicitly castable to it.
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]Top, Main, Index
Returns a list of registered pointers optionally filtered by a tag.
Parameters
tag | If specified, only pointers matching the tag are returned. If tag is the empty string, only pointers without a tag are returned. |
Return value
Returns a list of registered pointers optionally filtered by a tag.
pointer make [::cffi]Top, Main, Index
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. An empty tag is treated as if it was unspecified. |
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 pin [::cffi]Top, Main, Index
Pins a pointer as permanently safe.
Parameters
pointer | Pointer to be pinned. This may or may not be already registered. |
Description
Once a pointer is pinned, it is unaffected by any pointer safe, pointer counted or pointer dispose calls. It can however be invalidated by pointer invalidate.
A pinned pointer has no associated tag even if the passed pointer has one. It will thus match any pointer with the same address component irrespective of the tag. The primary use of pinned pointers is to deal with "pseudo handles" in the Windows API.
Return value
Returns $pointer itself.
pointer safe [::cffi]Top, Main, Index
Registers a pointer as a safe uncounted pointer.
Parameters
pointer | Pointer to be registered. |
Description
In the case that the pointer is already registered, behavior depends on the existing registration:
- If the pointer is already registered as a pinned pointer, the command has no effect.
- If the pointer is already registered as a safe (uncounted) pointer the command has no effect if the tag is the same as the registered tag or can be implicitly cast to it. Otherwise the registered tag is replaced.
- If the pointer is registered as a counted pointer, the registration, including tag, is overwritten.
See Pointers for more on pointer safety and registration.
Return value
Returns the registered pointer.
pointer tag [::cffi]Top, Main, Index
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
pointer uncastable [::cffi]Top, Main, Index
Makes pointers with the specified tag uncastable to another type
Parameters
tag | A pointer tag Pointers tagged with $tag will no longer be castable to other tags that were configured with the pointer castables command. |
prototype [::cffi]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Deletes prototypes matching a pattern. | |
| Defines a function prototype for calling a function using the default C calling convention. | |
| Returns a list of prototypes matching the specified pattern. | |
| 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]Top, Main, Index
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]Top, Main, Index
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 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
prototype list [::cffi]Top, Main, Index
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]Top, Main, Index
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 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
savederrors [::cffi]Top, Main, Index
Return errno and GetLastError() values from the last CFFI call annotated with saveerrors.
Description
For functions annotated with saveerrors, CFFI internally saves the errno and (on Windows) GetLastError() values. The savederrors command retrieves these as a pair with the first element being the saved errno value and the second the GetLastError() result. The latter is always 0 on non-Windows platforms.
type [::cffi]Top, Main, Index
A command ensemble.
Description
The ensemble supports the following subcommands:
| Returns the count of elements in an array type. | |
| Converts the native binary value to its script level representation. | |
| Returns a dictionary containing various information about a type declaration. | |
| Returns the size of a type in terms of the number of bytes of memory occupied by that type. | |
| Converts a script level value to a native representation. |
Refer to the documentation of each subcommand for details.
type count [::cffi]Top, Main, Index
Returns the count of elements in an array type
Parameters
type | A type definition or alias. |
Description
A return value of -1 indicates the type is not an array.
Return value
Returns the count of elements in an array type
type frombinary [::cffi]Top, Main, Index
Converts the native binary value to its script level representation.
Parameters
typespec | A type declaration. |
value | The native binary value. |
Description
The $typespec argument may be any type specification.
Return value
Returns the script level representation of the value.
See also
type info [::cffi]Top, Main, Index
Returns a dictionary containing various information about a type declaration
Parameters
typedecl | A type declaration. |
-parsemode MODE | One of param, return, field. |
-vlacount VLACOUNT | Number of elements in variable size array. |
Description
The type is parsed as a parameter type declaration, a function return type declaration or a structure field type declaration depending on the -parsemode option. If this is unspecified or an empty string, it is parsed in generic fashion and no context-specific validation is done.
The option -vlacount must be specified if the type is variable length array or a struct that contains a variable length array
The returned dictionary contains the following keys:
| The memory alignment needed for a value of that type. | |
The number of bytes to store a single value of the type when the type is an array. For scalars, same as Size. | |
-1 for scalar values, else indicates the type is an array with that number of elements. | |
| The number of bytes of memory needed to store a value of that type. | |
| 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]Top, Main, Index
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. |
-vlacount VLACOUNT | Number of elements in variable size array. |
Description
In the case of array types, the size includes the size of the entire array and not the size of a single element.
The option -vlacount must be specified if the type is variable length array or a struct that contains a variable length array
Return value
Returns the size of a type in terms of the number of bytes of memory occupied by that type.
type tobinary [::cffi]Top, Main, Index
Converts a script level value to a native representation.
Parameters
typespec | A type declaration. |
value | The script level value. |
Description
The $typespec argument must not have a string or variable size component. If an array is specified of a larger size than the number of elements in $value, the remaining elements are zeroed out.
Return value
Returns a Tcl binary containing the native representation.
See also
ClassesTop, Main, Index
Interface [::cffi]Top, Main, Index
Method summary
| Constructor for the class. | |
Returns the id for the interface as passed via the -id option in the interface definition. | |
| Creates Tcl commands wrapping the C functions comprising an interface. | |
| Creates Tcl commands corresponding to the C functions comprising an interface. |
constructor [::cffi::Interface]Interface, Top, Main, Index
Defines an interface consisting of method definitions.
Interface new ?args?
Parameters
-id ID | An id to be associated with the interface. This is for the caller's use and CFFI does not make any use of it. For COM, this can be used to associate the GUID or IID for the interface. Defaults to the empty string. |
-inherit BASEINTERFACE | If specified, the interface inherits methods from BASEINTERFACE. An empty value for BASEINTERFACE is treated as though the option was not specified. |
Description
See Interfaces for more information.
id [::cffi::Interface]Interface, Top, Main, Index
Returns the id for the interface as passed via the -id option in the interface definition.
Return value
Returns the id for the interface as passed via the -id option in the interface definition.
methods [::cffi::Interface]Interface, Top, Main, Index
Creates Tcl commands wrapping the C functions comprising an interface.
Parameters
methodlist | List of function definitions. |
-disposemethod METHODNAMDE | The name of the method, if any, whose implicit pointer parameter should be annotated with dispose. |
Description
The C functions in the wrapper are presumed to be using the _cdecl calling convention. The created commands are of the form INTERFACENAME.METHODNAME. The first argument to each is typed as pointer.INTERFACENAME.
The order of the methods in $methodlist must be the same as that in the corresponding C interface. All functions in the interface are expected to have a pointer to the interface as the first parameter.
The $methodlist argument is a flat (not nested) list of function name, return type and parameter list in the same form as described for the ::cffi::Wrapper::function method except that the first parameter in the C function, the pointer to the object, should not be included.
See also
stdmethods [::cffi::Interface]Interface, Top, Main, Index
Creates Tcl commands corresponding to the C functions comprising an interface.
Parameters
methodlist | List of function definitions. |
-disposemethod METHODNAMDE | The name of the method, if any, whose implicit pointer parameter should be annotated with dispose. |
Description
The C functions are presumed to be using the _stdcall calling convention. The created commands are of the form INTERFACENAME.METHODNAME. The first argument to each is typed as pointer.INTERFACENAME.
The order of the methods in $methodlist must be the same as that in the corresponding C interface. All functions in the interface are expected to have a pointer to the interface as the first parameter.
The $methodlist argument is a flat (not nested) list of function name, return type and parameter list in the same form as described for the ::cffi::Wrapper::function method except that the first parameter in the C function, the pointer to the object, should not be included.
See also
Struct [::cffi]Top, Main, Index
Method summary
| Constructor for the class. | |
| Allocates memory for one or more C structs. | |
| Returns a human-readable description of the C struct definition. | |
| Returns a pointer corresponding to the address of a field within a native structure. | |
| Frees memory that was allocated for a native C struct. | |
| Decodes a Tcl binary string containing a native C struct into a Tcl dictionary. | |
| Decodes native C struct(s) in memory into a Tcl dictionary. | |
| Decodes native C struct(s) in memory into a Tcl dictionary. | |
| Returns the value of a field in a native structure in memory. | |
| Returns the value of a field in a native structure in memory. | |
| Retrieve values of multiple fields from a native struct in memory. | |
| Retrieve values of multiple fields from a native struct in memory. | |
| Returns a dictionary containing information about the struct layout. | |
| Returns the name of the struct. | |
| Allocates and initializes a native struct in memory. | |
| Sets the value of a field in a native structure in memory. | |
| Sets the value of a field in a native structure in memory. | |
| Returns the size of the struct. | |
| Encodes the Tcl representation of a C struct value into a Tcl binary string. | |
| Writes the Tcl dictionary representation of a C struct value to memory in native form. | |
| Writes the Tcl dictionary representation of a C struct value to memory in native form. |
constructor [::cffi::Struct]Struct, Top, Main, Index
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. |
-clear | Clears memory at initialization. See below. |
-pack PACKVALUE | Changes alignment and padding used for fields. See Structs. |
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 Packed 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]Struct, Top, Main, Index
Allocates memory for one or more C structs.
Parameters
-count COUNT | Number of structs to allocate. |
-vlacount VLACOUNT | Number of elements in variable size array. |
Description
Unlike in the new method, the allocated memory is not initialized. This is the case even if the struct definition includes the -clear option.
The option -vlacount must be specified if the struct contains a field that is a variable length array (VLA) or a nested struct that contains a VLA. VLACOUNT is then length of that array.
The allocate memory must be freed by calling the free method of the struct.
Return value
Returns a safe pointer to the allocated memory tagged with the struct name.
describe [::cffi::Struct]Struct, Top, Main, Index
Returns a human-readable description of the C struct definition.
Description
This is primarily for debugging and troubleshooting purposes. Note the returned information will not take into account the variable components of the struct if any.
Return value
Returns a human-readable description of the C struct definition.
fieldpointer [::cffi::Struct]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. 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]Struct, Top, Main, Index
Frees memory that was allocated for a native C struct.
Parameters
pointer | A pointer returned by allocate |
frombinary [::cffi::Struct]Struct, Top, Main, Index
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]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. Optional, default 0. |
Description
The decoded dictionary or dictionaries are keyed by the field names of the struct. For fields containing variable length arrays, the field holding the length of the array must be explicitly specified and cannot be defaulted.
Return value
Returns a dictionary of the decoded struct.
See also
fromnative!, tonative, frombinary
fromnative! [::cffi::Struct]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. Optional, default 0. |
Description
The decoded dictionary or dictionaries are keyed by the field names of the struct. For fields containing variable length arrays, the field holding the length of the array must be explicitly specified and cannot be defaulted.
Return value
Returns a dictionary of the decoded struct.
See also
fromnative, tonative, frombinary
getnative [::cffi::Struct]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. 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]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. 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]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. Optional, default 0. |
Return value
Returns a list of field values in the same order as $fieldnames
getnativefields! [::cffi::Struct]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. Optional, default 0. |
Return value
Returns a list of field values in the same order as $fieldnames
info [::cffi::Struct]Struct, Top, Main, Index
Returns a dictionary containing information about the struct layout
Parameters
-vlacount VLACOUNT | Number of elements in variable size array. |
Description
The returned dictionary has the following fields:
| Size of the struct. | |
| Struct alignment. | |
| 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. |
The option -vlacount must be specified if the struct contains a field that is a variable length array (VLA) or a nested struct that contains a VLA. VLACOUNT is then length of that array.
Return value
Returns a dictionary containing information about the struct layout
name [::cffi::Struct]Struct, Top, Main, Index
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]Struct, Top, Main, Index
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 unless the -clear option was specified for the Struct. In that case missing fields without defaults are filled with zeroes.
For fields containing variable length arrays, the field holding the length of the array must be explicitly specified and cannot be 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]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. Optional, default 0. |
Description
The field being set must not be a variable sized field, or field holding a count for a variable sized field; otherwise, an error is raised.
setnative! [::cffi::Struct]Struct, Top, Main, Index
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. For variable sized structs index must be 0 or unspecified. Optional, default 0. |
Description
The field being set must not be a variable sized field, or field holding a count for a variable sized field; otherwise, an error is raised.
size [::cffi::Struct]Struct, Top, Main, Index
Returns the size of the struct.
Parameters
-vlacount VLACOUNT | Number of elements in variable size array. |
Description
The option -vlacount must be specified if the struct contains a field that is a variable length array (VLA) or a nested struct that contains a VLA. VLACOUNT is then length of that array.
Return value
Returns the size of the struct.
tobinary [::cffi::Struct]Struct, Top, Main, Index
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]Struct, Top, Main, Index
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. |
Description
The method raises an error if the struct is variable size.
See also
tonative!, fromnative, tobinary
tonative! [::cffi::Struct]Struct, Top, Main, Index
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. |
Description
The method raises an error if the struct is variable size.
See also
tonative, fromnative, tobinary
Union [::cffi]Top, Main, Index
Method summary
| Constructor for the class. | |
| Returns a field from a native union. | |
| Returns a human-readable description of the C union definition. | |
| Returns a union in native form with the specified field value. | |
| Returns a dictionary containing information about the info layout. | |
| Returns the name of the struct. | |
| Returns the size of the union. |
constructor [::cffi::Union]Union, Top, Main, Index
Constructs a script level object that maps to a C union definition.
Union 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 manipulate native C unions.
The $definition argument is a dictionary mapping field names to the corresponding types. This has the same syntax as Structs.
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 unions of this type is cleared before the field values are initialized.
decode [::cffi::Union]Union, Top, Main, Index
Returns a field from a native union.
Parameters
field | The field within the union that should be retrieved. |
uvalue | The opaque union in native form. |
Return value
Returns a field from a native union.
See also
describe [::cffi::Union]Union, Top, Main, Index
Returns a human-readable description of the C union definition.
Description
This is primarily for debugging and troubleshooting purposes.
Return value
Returns a human-readable description of the C union definition.
encode [::cffi::Union]Union, Top, Main, Index
Returns a union in native form with the specified field value.
Parameters
field | The field within the union that should be set. |
value | The value of the field. |
Return value
Returns a union in native form with the specified field value.
See also
info [::cffi::Union]Union, Top, Main, Index
Returns a dictionary containing information about the info layout
Description
The returned dictionary has the following fields:
| Size of the struct. | |
| Struct alignment. | |
| 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. |
Other fields may be present and should be ignored.
Return value
Returns a dictionary containing information about the info layout
name [::cffi::Union]Union, Top, Main, Index
Returns the name of the struct.
Description
Note the name of the struct may be different from the name of the object command.
Return value
Returns the name of the struct.
size [::cffi::Union]Union, Top, Main, Index
Returns the size of the union.
Return value
Returns the size of the union.
Wrapper [::cffi]Top, Main, Index
Method summary
| Constructor for the class. | |
| Destructor for the class. | |
| Returns the address of a symbol from the loaded library. | |
| Creates a Tcl command to invoke a C function in the loaded library. | |
| Creates Tcl commands for multiple C functions within the loaded library. | |
| Returns the file system path for the wrapped library or image wrapped by the object. | |
Creates a Tcl command to invoke a C function that uses the __stdcall calling convention from the loaded library.. | |
Creates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention. |
constructor [::cffi::Wrapper]Wrapper, Top, Main, Index
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]Wrapper, Top, Main, Index
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]Wrapper, Top, Main, Index
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]Wrapper, Top, Main, Index
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. See syntax.
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. See syntax.
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]Wrapper, Top, Main, Index
Creates Tcl commands for multiple C functions within the loaded library.
Parameters
fnlist | List of function definitions. |
-ignoremissing | Do not raise an error if a function is not found. |
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.
If a function is not found, the command will raise an error but those functions that are found will be defined. The error can be completely suppressed with the -ignoremissing option.
If the function name element is #, the triple is ignored, effectively being considered a comment.
path [::cffi::Wrapper]Wrapper, Top, Main, Index
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]Wrapper, Top, Main, Index
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]Wrapper, Top, Main, Index
Creates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention.
Parameters
fnlist | List of function definitions. |
-ignoremissing | Do not raise an error if a function is not found. |
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.
If a function is not found, the command will raise an error but those functions that are found will be defined. The error can be completely suppressed with the -ignoremissing option.
If the function name element is #, the triple is ignored, effectively being considered a comment.