::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

Commandscffi, Top, Main, Index

alias body [::cffi]cffi, Top, Main, Index

Returns the resolved body of an alias.

alias body alias_name
Parameters
alias_nameName of alias to be retrieved.
Return value

Returns the resolved body of an alias.

alias define [::cffi]cffi, Top, Main, Index

Defines a new enumeration.

alias define enumname numdefs
Parameters
enumnameName of the enumeration.
numdefsNot documented.
enumdefsDictionary of enumeration symbol 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.

alias delete [::cffi]cffi, Top, Main, Index

Deletes enumerations.

alias delete pattern
Parameters
patternA glob-style pattern.
Description

The command deletes all enumerations whose name matches the specified pattern.

alias entries [::cffi]cffi, Top, Main, Index

Returns a dictionary containing the definitions in an enumerations.

alias entries enumname
Parameters
enumnameName of the enumeration whose elements are to be returned.
Return value

Returns a dictionary containing the definitions in an enumerations.

alias list [::cffi]cffi, Top, Main, Index

Lists enumerations.

alias list pattern
Parameters
patternA glob-style pattern.
Description

The command returns names of all enumerations with names matching the specified pattern.

alias load [::cffi]cffi, Top, Main, Index

Loads predefined type aliases.

alias load alias_set
Parameters
alias_setThe alias set to load.
Description

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

The C predefined alias set includes int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t size_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 LPSTR LPVOID LPWSTR 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]cffi, Top, Main, Index

Invokes a C function through a function pointer.

call fnptr ?args?
Parameters
fnptrA pointer value tagged with a prototype
argsAdditional 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.

memory allocate [::cffi]cffi, Top, Main, Index

Allocates memory of the specified size

memory allocate size ?tag?
Parameters
sizeRequested size of memory block.
tagTag 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 free

memory free [::cffi]cffi, Top, Main, Index

Frees the memory referenced by the passed pointer

memory free pointer
Parameters
pointerSafe pointer to memory to free.
Description

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

See also

memory allocate

memory frombinary [::cffi]cffi, Top, Main, Index

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

memory frombinary bin_value ?tag?
Parameters
bin_valueA Tcl binary value.
tagTag 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]cffi, Top, Main, Index

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

memory fromstring value ?encoding?
Parameters
valueTcl string value.
encodingThe 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 set [::cffi]cffi, Top, Main, Index

Sets the memory locations to a specified value

memory set pointer bytevalue count
Parameters
pointerSafe pointer to memory.
bytevalueA value in the range 0-255
countNumber of bytes to be set.

memory tobinary [::cffi]cffi, Top, Main, Index

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

memory tobinary pointer size
Parameters
pointerSafe pointer to memory.
sizeNumber of bytes to copy from the memory block.
Return value

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

See also

memory tobinary!, memory frombinary

memory tobinary! [::cffi]cffi, Top, Main, Index

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

memory tobinary! pointer size
Parameters
pointerPointer to memory.
sizeNumber of bytes to copy from the memory block.
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]cffi, Top, Main, Index

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

memory tostring pointer ?encoding?
Parameters
pointerSafe pointer to memory.
encodingThe encoding to use for conversion. If unspecified or the empty string, the system encoding is used. Optional, default "".
Return value

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

See also

memory tostring!, memory fromstring

memory tostring! [::cffi]cffi, Top, Main, Index

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

memory tostring! pointer ?encoding?
Parameters
pointerPointer to memory.
encodingThe encoding to use for conversion. If unspecified or the empty string, the system encoding is used. Optional, default "".
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

pointer address [::cffi]cffi, Top, Main, Index

Returns the address component of the pointer.

pointer address pointer
Parameters
pointerPointer whose address component is to be returned.
Return value

Returns the address component of the pointer.

pointer check [::cffi]cffi, Top, Main, Index

Validates a pointer and raise an exception if invalid.

pointer check pointer
Parameters
pointerPointer 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]cffi, Top, Main, Index

Registers a pointer as a counted pointer

pointer counted pointer
Parameters
pointerPointer 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]cffi, Top, Main, Index

Unregisters a safe or counted pointer

pointer dispose pointer
Parameters
pointerPointer 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.

See Pointers for more on pointer safety and registration.

pointer isnull [::cffi]cffi, Top, Main, Index

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

pointer isnull pointer
Parameters
pointerPointer to be checked.
Return value

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

pointer isvalid [::cffi]cffi, Top, Main, Index

Validates a pointer.

pointer isvalid pointer
Parameters
pointerPointer 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]cffi, Top, Main, Index

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

pointer list ?args?
Parameters
argsIf 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 safe [::cffi]cffi, Top, Main, Index

Registers a pointer as a safe uncounted pointer

pointer safe pointer
Parameters
pointerPointer to be registered.
Description

An error is raised if the pointer is already registered or is a NULL pointer.

See Pointers for more on pointer safety and registration.

pointer tag [::cffi]cffi, Top, Main, Index

Returns the pointer tag

pointer tag pointer
Parameters
pointerPointer 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 delete [::cffi]cffi, Top, Main, Index

Deletes prototypes matching a pattern.

prototype delete pattern
Parameters
patternPattern 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]cffi, Top, Main, Index

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

prototype function name fntype parameters
Parameters
nameName for the prototype. Must begin with an alphabetic character and may contain alphanumerics and underscore.
fntypeThe type definition for the return value from the function.
parametersList 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 dyncall::Library.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

dyncall::Library.function

prototype list [::cffi]cffi, Top, Main, Index

Returns a list of prototypes matching the specified pattern.

prototype list ?pattern?
Parameters
patternPattern 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]cffi, Top, Main, Index

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

prototype stdcall name fntype parameters
Parameters
nameName for the prototype. Must begin with an alphabetic character and may contain alphanumerics and underscore.
fntypeThe type definition for the return value from the function.
parametersList 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 dyncall::Library.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

dyncall::Library.stdcall

type count [::cffi]cffi, Top, Main, Index

Returns the count of elements in an array type

type count type
Parameters
typeA 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]cffi, Top, Main, Index

Returns a dictionary containing various information about a type declaration

type info typedecl ?parse_mode?
Parameters
typedeclA type declaration.
parse_modeOne 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:

alignmentThe memory alignment needed for a value of that type.
count0 for scalar values, else indicates the type is an array with that number of elements.
sizeThe number of bytes of memory needed to store a value of that type.
definitionThe 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]cffi, Top, Main, Index

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

type size type
Parameters
typeA 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.

Classescffi, Top, Main, Index

Struct [::cffi]cffi, Top, Main, Index

Method summary
constructorConstructor for the class.
allocateAllocates memory for one or more C structs.
describeReturns a human-readable description of the C struct definition.
freeFrees memory that was allocated for a native C struct.
frombinaryDecodes a Tcl binary string containing a native C struct into a Tcl dictionary.
fromnativeDecodes native C struct(s) in memory into a Tcl dictionary.
infoReturns a dictionary containing information about the struct layout.
nameReturns the name of the struct.
tobinaryEncodes the Tcl representation of a C struct value into a Tcl binary string.
tonativeWrites the Tcl dictionary representation of a C struc 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 create OBJNAME definition
Struct new definition
Parameters
definitionDefines the layout and type of the C struct fields.
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.

allocate [::cffi::Struct]Struct, Top, Main, Index

Allocates memory for one or more C structs.

OBJECT allocate ?count?
Parameters
countNumber of structs to allocate. Optional, default 1.
Description

The returned memory is not initialized.

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]Struct, Top, Main, Index

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

OBJECT describe
Description

This is primarily for debugging and troubleshooting purposes.

Return value

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

free [::cffi::Struct]Struct, Top, Main, Index

Frees memory that was allocated for a native C struct.

OBJECT free pointer
Parameters
pointerA 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.

OBJECT frombinary bin_value
Parameters
bin_valueA 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.

OBJECT fromnative pointer ?index?
Parameters
pointerSafe pointer to the C struct or array of structs in memory.
indexThe 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

tonative, frombinary

info [::cffi::Struct]Struct, Top, Main, Index

Returns a dictionary containing information about the struct layout

OBJECT info
Description

The returned dictionary has the following fields:

sizeSize of the struct.
alignmentStruct alignment.
fieldsDictionary 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]Struct, Top, Main, Index

Returns the name of the struct.

OBJECT name
Description

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

Return value

Returns the name of the struct.

tobinary [::cffi::Struct]Struct, Top, Main, Index

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

OBJECT tobinary dict_value
Parameters
dict_valueA 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 struc value to memory in native form.

OBJECT tonative pointer initializer ?index?
Parameters
pointerPointer to memory allocated for the C struct or array. Must be tagged with the struct name.
initializerThe Tcl dictionary value.
indexThe 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

fromnative, tobinary

Document generated by Ruff!