cffi(3tcl)

💖 cffi(3tcl) — Tcl CFFI package, bestie edition 💖

🌸 NAME 🌸

cffi — Commands in namespace cffi.

✨ SYNOPSIS ✨

okay bestie, here’s the whole command menu verbatim, no cap:

alias subcommand ...
alias body alias_name
alias clear
alias define name definition
alias define aliasdefs
alias delete pattern
alias list ?pattern?
alias load alias_set
arena subcommand ...
arena allocate sizespec ?tag?
arena new typespec initializer ?tag?
arena popframe
arena pushframe ?size?
arena pushframe size ?tag?
call fnptr ?args?
callback subcommand ...
callback free cb
callback new protoname cmdprefix error_value
enum subcommand ...
enum alias enumname enumdefs typedecl
enum clear
enum define enumname enumdefs
enum delete pattern
enum flags enumname membernames
enum list pattern
enum mask enumname membernames
enum members enumname
enum name enumname membervalue ?default?
enum names enumname
enum sequence enumname membernames ?start?
enum unmask enumname mask
enum value enumname membername ?default?
help subcommand ...
help alias NAME
help enum NAME
help function NAME
help functions ?PATTERN?
help struct NAME
help union NAME
limits type
memory subcommand ...
memory allocate sizespec ?tag?
memory fill pointer bytevalue count ?offset?
memory free pointer
memory frombinary bin_value ?tag?
memory fromstring value ?encoding?
memory fromunistring value
memory fromwinstring value
memory get pointer typespec ?index?
memory get! pointer typespec ?index?
memory new typespec initializer ?tag?
memory set pointer typespec value ?index?
memory set! pointer typespec value ?index?
memory tobinary pointer size ?offset?
memory tobinary! pointer size ?offset?
memory tostring pointer ?encoding? ?offset?
memory tostring! pointer ?encoding? ?offset?
memory tounistring pointer ?offset?
memory tounistring! pointer ?offset?
memory towinstring pointer ?offset?
memory towinstring! pointer ?offset?
pkgconfig subcommand ...
pkgconfig get key
pkgconfig list
pointer subcommand ...
pointer address pointer
pointer cast pointer ?TAG?
pointer castable subtags supertag
pointer castables
pointer check pointer
pointer compare ptr1 ptr2
pointer counted pointer
pointer dispose pointer
pointer info pointer
pointer invalidate pointer
pointer isnull pointer
pointer isvalid pointer
pointer list ?tag?
pointer make address ?tag?
pointer pin pointer
pointer safe pointer
pointer tag pointer
pointer uncastable tag
prototype subcommand ...
prototype delete pattern
prototype function name fntype parameters
prototype list ?pattern?
prototype stdcall name fntype parameters
savederrors
type subcommand ...
type count type
type frombinary typespec value
type info typedecl ?args?
type size type ?args?
type tobinary typespec value
Interface create OBJNAME ?args?
Interface new ?args?
INTERFACEOBJ id
INTERFACEOBJ methods methodlist ?args?
INTERFACEOBJ stdmethods methodlist ?args?
Struct create OBJNAME definition ?args?
Struct new definition ?args?
STRUCTOBJ allocate ?args?
STRUCTOBJ describe
STRUCTOBJ fieldpointer pointer fieldname ?tag? ?index?
STRUCTOBJ free pointer
STRUCTOBJ frombinary bin_value
STRUCTOBJ fromnative pointer ?index?
STRUCTOBJ fromnative! pointer ?index?
STRUCTOBJ getnative pointer fieldname ?index?
STRUCTOBJ getnative! pointer fieldname ?index?
STRUCTOBJ getnativefields pointer fieldnames ?index?
STRUCTOBJ getnativefields! pointer fieldnames ?index?
STRUCTOBJ info ?args?
STRUCTOBJ name
STRUCTOBJ new ?initval?
STRUCTOBJ setnative pointer fieldname value ?index?
STRUCTOBJ setnative! pointer fieldname value ?index?
STRUCTOBJ size ?args?
STRUCTOBJ tobinary dict_value
STRUCTOBJ tonative pointer initializer ?index?
STRUCTOBJ tonative! pointer initializer ?index?
Union create OBJNAME definition ?args?
Union new definition ?args?
UNIONOBJ decode field uvalue
UNIONOBJ describe
UNIONOBJ encode field value
UNIONOBJ info
UNIONOBJ name
UNIONOBJ size
Wrapper create OBJNAME path
Wrapper new path
WRAPPEROBJ destroy
WRAPPEROBJ addressof symbol
WRAPPEROBJ function fnname fntype parameters
WRAPPEROBJ functions fnlist ?args?
WRAPPEROBJ path
WRAPPEROBJ stdcall fnname fntype parameters
WRAPPEROBJ stdcalls fnlist ?args?

🦋 ::CFFI 🦋

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

The package is loaded in standard fashion with package require:

package require cffi

🛠️ COMMANDS 🛠️

🎀 alias (::cffi) 🎀

A command ensemble.

alias subcommand ...

Description

The ensemble supports the following subcommands:

body — Returns the resolved body of an alias.
clear — Deletes all aliases from the interpreter.
define — Defines one or more type aliases.
delete — Deletes aliases matching a pattern.
list — Returns a list of aliases that match the specified pattern.
load — Loads predefined type aliases.

Refer to the documentation of each subcommand for details.

💅 alias body (::cffi) 💅

Returns the resolved body of an alias.

alias body alias_name

Parameters

alias_name — Name of alias to be retrieved.

Description

The alias must be one defined in the current scope.

Return value

Returns the resolved body of an alias.

🧹 alias clear (::cffi) 🧹

Deletes all aliases from the interpreter.

alias clear

🪄 alias define (::cffi) 🪄

Defines one or more type aliases.

alias define name definition
alias define aliasdefs

Parameters

aliasdefs — Dictionary mapping alias names to their definition.
definition — Definition for the alias.
name — Name for type alias. Must begin with an alphabetic character and may contain alphanumerics and underscore.

Description

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

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

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

See Type aliases for more on type aliases.

🗑️ alias delete (::cffi) 🗑️

Deletes aliases matching a pattern.

alias delete pattern

Parameters

pattern — Pattern to match against aliases.

Description

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

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

📋 alias list (::cffi) 📋

Returns a list of aliases that match the specified pattern.

alias list ?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) 📦

Loads predefined type aliases.

alias load alias_set

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 are available in all namespaces 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) 🏟️

A command ensemble.

arena subcommand ...

Description

The ensemble supports the following subcommands:

allocate — Allocates memory in the current arena frame in the memory arena.
new — Allocates memory in the current arena for a type and initializes it.
popframe — Pops the current frame from the memory arena.
pushframe — Pushes a new stack frame on the memory arena.

Refer to the documentation of each subcommand for details.

🧱 arena allocate (::cffi) 🧱

Allocates memory in the current arena frame in the memory arena.

arena allocate sizespec ?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. 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

🌱 arena new (::cffi) 🌱

Allocates memory in the current arena for a type and initializes it.

arena new typespec initializer ?tag?

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 can be, like, any type specification, bestie. And if an array is specified with a larger size than the number of elements in $initializer, the leftover elements are zeroed out. No cap. 🫶

The returned memory gets freed when the arena frame is freed with arena popframe. Periodt.

🎁 Return value 🎁

Returns a safe pointer to the allocated memory. Slay.

👀 See also 👀

arena allocate — yes, it's pointing back at itself, iconic behavior honestly. 💀

🫧 arena popframe (::cffi) 🫧

Pops the current frame from the memory arena.

arena popframe

💖 Description 💖

All allocations from the popped frame are freed, and pointers to these are unregistered. Clean sweep, no leftovers. ✨

🧚 arena pushframe (::cffi) 🧚

Pushes a new stack frame on the memory arena.

arena pushframe ?size?
arena pushframe size ?tag?

🧾 Parameters 🧾

sizespec — requested size of the memory block. This may be specified either as an integer value or a type specification (optional).
tag — tag for the returned pointer if $size is specified (optional).

🌸 Description 🌸

This command allocates a new frame in the memory arena stack. All allocations from this frame stay valid only until the corresponding call to arena popframe. Like, do not forget the pop, bestie. 😭

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 as a CFFI type declaration — in which case the memory allocated is that of the type's size. 🎀

🎁 Return value 🎁

Returns an empty string if no arguments were specified, or a safe pointer. 💖

👀 See also 👀

arena allocate, arena popframe.

📞 call (::cffi) 📞

Invokes a C function through a function pointer.

call fnptr ?args?

🧾 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 correspond to a function prototype defined through the prototype function or prototype stdcall commands. That's the vibe check it has to pass. ✨

🎁 Return value 🎁

Returns the value returned by the invoked C function. Main character return value energy. 👑

🦋 callback (::cffi) 🦋

A command ensemble.

callback subcommand ...

🌈 Description 🌈

The ensemble supports these subcommands:

free — frees a callback pointer.
new — wraps a script level command into a C function.

Refer to the documentation of each subcommand for details. 💅

🧽 callback free (::cffi) 🧽

Frees a callback pointer.

callback free cb

🧾 Parameters 🧾

cb — a function pointer allocated with callback new.

🪄 callback new (::cffi) 🪄

Wraps a script level command into a C function.

callback new protoname cmdprefix error_value

🧾 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. Very "pass the aux" of it all. 🎧

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. No improvising, bestie. 🙈

The type declarations in prototypes used for callbacks have certain restrictions. These arise because the "data flow" is now from script to the C shared library. It's giving reverse directions. 🌀

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

The out, inout and retval annotations are not permitted. This means any values to be returned to the shared library must be through explicit raw pointers.
All pointer type declarations must have the unsafe annotation. Other pointer safety annotations counted, dispose, disposeonsuccess cannot be specified.
The value checking annotations zero, nonzero, positive and nonnegative cannot be specified for the prototype return type.
The error handling annotations errno, winerror, lasterror and onerror cannot be specified.
The storeonerror and storealways annotations cannot be specified.

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

When no longer needed, the callback should be freed with the callback free command. Do not leave it lying around like a read receipt. 😭

🎁 Return value 🎁

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

🔮 enum (::cffi) 🔮

A command ensemble.

enum subcommand ...

🌟 Description 🌟

The ensemble supports these subcommands:

alias — defines a new enumeration and alias of the same name.
clear — deletes all enumerations from the interpreter.
define — defines a new enumeration.
delete — deletes enumerations.
flags — defines an enumeration as bit flags.
list — lists enumerations.
mask — returns an integer mask formed by bitwise OR-ing the passed enumeration members.
members — returns a dictionary containing the members in an enumeration.
name — returns the symbolic name of a value in an enumeration.
names — returns a list containing the names of members in an enumeration.
sequence — defines an enumeration with consecutive member values.
unmask — returns a list of enumeration member names corresponding to the bits set in $mask.
value — returns the value of an enumeration member.

Refer to the documentation of each subcommand for details. 🫶

🏷️ enum alias (::cffi) 🏷️

Defines a new enumeration and alias of the same name.

enum alias enumname enumdefs typedecl

🧾 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. Matching set, cute. 🎀

🎁 Return value 🎁

Returns the fully qualified enumeration name. ✨

🧹 enum clear (::cffi) 🧹

Deletes all enumerations from the interpreter.

enum clear

🧱 enum define (::cffi) 🧱

Defines a new enumeration.

enum define enumname enumdefs

🧾 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 acceptable as arguments and will be replaced by the corresponding value in the function call. Enumeration member values must be integers. No fanciness, just numbers. 🔢

🎁 Return value 🎁

Returns the fully qualified enumeration name. 💜

🗑️ enum delete (::cffi) 🗑️

Deletes enumerations.

enum delete pattern

🧾 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.

So it's globby at the end, exact at the front. Respect the structure, bestie. 🧚

🚩 enum flags (::cffi) 🚩

Defines an enumeration as bit flags.

enum flags enumname membernames

🧾 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. Bit math, but make it fashion. 💅

🎁 Return value 🎁

Returns the fully qualified enumeration name. ⭐

📋 enum list (::cffi) 📋

Lists enumerations.

enum list pattern

🧾 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.

Same matching rules as delete. Consistency ate. 🍓

🎭 enum mask (::cffi) 🎭

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

enum mask enumname membernames

🧾 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. Bitwise OR is literally the moment. 🔥

👀 See also 👀

enum unmask.

🧺 enum members (::cffi) 🧺

Returns a dictionary containing the members in an enumeration.

enum members enumname

🧾 Parameters 🧾

enumname — name of the enumeration whose elements are to be returned.

🎁 Return value 🎁

Returns a dictionary containing the members in an enumeration. Dictionary delivery service. 🎁

🏷️ enum name (::cffi) 🏷️

Returns the symbolic name of a value in an enumeration.

enum name enumname membervalue ?default?

🧾 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. So like, have a backup plan or catch the error. 😭

🎁 Return value 🎁

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

📛 enum names (::cffi) 📛

Returns a list containing the names of members in an enumeration.

enum names enumname

🧾 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. Name drop, but organized. ✨

🔢 enum sequence (::cffi) 🔢

Defines an enumeration with consecutive member values.

enum sequence enumname membernames ?start?

🧾 Parameters 🧾

enumname — name of the enumeration.
membernames — list of names of the enumeration members.
start — the value of the first enumeration member. Optional, default 0. 🌸

Description

Every element of $membernames should hold one or two things: the first is the member's name, and the second — if it's even there — is its value. If that second element is missing, the member just gets a value one greater than whatever the previous member got. And the very first member gets assigned 0 if you never gave it an explicit value. Cute and predictable, honestly. ✨

$start is only hanging around for backward compatibility, bestie — it's how you say which value the sequence starts at. But for future compatibility, if you want a starting value that isn't the default zero, use the two-element form for the first enum member instead. iykyk. 💅

Return value

Returns the fully qualified enumeration name. 🎀

✨ enum unmask ✨

Gives you back a list of enumeration member names matching whichever bits are set in $mask. It's giving reverse-engineering but make it fashion. 🔍

enum unmask enumname mask

Parameters

enumname — name of the enumeration.
mask — integer bit mask value.

Description

Heads up: the last element of the returned list is $mask itself. 🫶 Generally your enumeration should be made of values that don't have overlapping bits set (the usual vibe is a single bit set per member value). This isn't enforced — nothing's gonna stop you — but the results might not be what you expected if that condition isn't met. You've been warned, babe. 💀

Return value

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

See also

enum mask

✨ enum value ✨

Hands you the value of a single enumeration member. Simple, iconic, does exactly what it says. ⭐

enum value enumname membername ?default?

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

This one raises an error 😭 if $membername isn't present in the enumeration and you didn't provide a default — or if $enumname itself is undefined. No default, no vibes.

Return value

Returns the value of an enumeration member.

✨ help ✨

A command ensemble, bestie. A whole little family of helpers. 🎀

help subcommand ...

Description

The ensemble supports these subcommands:

alias — returns a string describing an alias definition.
enum — returns a string describing an enum definition.
function — returns a string describing the syntax and parameter definitions for a CFFI wrapped function.
functions — returns a list of CFFI-wrapped functions matching the pattern PATTERN.
struct — returns a string describing field types in a Struct.
union — returns a string describing field types in a Union.

Refer to the documentation of each subcommand for the details. 💖

✨ help alias ✨

Returns a string describing an alias definition.

help alias NAME

Parameters

NAME — name of a alias.

Return value

Returns a string describing an alias definition.

✨ help enum ✨

Returns a string describing an enum definition.

help enum NAME

Parameters

NAME — name of a enum.

Return value

Returns a string describing an enum definition.

✨ help function ✨

Returns a string describing the syntax and parameter definitions for a CFFI wrapped function.

help function NAME

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 ✨

Returns a list of CFFI-wrapped functions matching the pattern PATTERN. It's basically a roster of your wrapped functions. 📋

help functions ?PATTERN?

Parameters

PATTERN — glob pattern to match. Optional, default *.

Description

Important lil note: just like Tcl's info commands, the pattern is interpreted relative to the current namespace. So if you want the list of commands inside a namespace, you gotta include the namespace in the pattern too. Like this:

cffi::help functions ::libzip::*

That's the move. 🫶

Return value

Returns a list of CFFI-wrapped functions matching the pattern PATTERN.

✨ help struct ✨

Returns a string describing field types in a Struct.

help struct NAME

Parameters

NAME — name of a Struct.

Return value

Returns a string describing field types in a Struct.

✨ help union ✨

Returns a string describing field types in a Union.

help union NAME

Parameters

NAME — name of a Union.

Return value

Returns a string describing field types in a Union.

✨ limits ✨

Gets you the lower and upper limits for an integral base type. No more guessing, no more vibes-based arithmetic. 🔢

limits type

Parameters

type — the base type.

Return value

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

✨ memory ✨

Another command ensemble — and honestly this one is the whole memory-management main character. 👑

memory subcommand ...

Description

The ensemble supports these subcommands:

allocate — allocates memory of the specified size.
fill — fills memory with a specified value.
free — frees the memory referenced by the passed pointer.
frombinary — allocates memory and copied the passed Tcl binary string into it.
fromstring — allocates memory and stores a Tcl string in it in the specified encoding.
fromunistring — allocates memory and stores a Tcl string as a sequence of Tcl_UniChars.
fromwinstring — allocates memory and stores a Tcl string as a sequence of winchars.
get — converts a native value in memory into a Tcl script level value.
get! — converts a native value in memory into a Tcl script level value.
new — allocates memory for a type and initializes it.
set — converts a value as per a type specification and stores it in memory in native form.
set! — converts a value as per a type specification and stores it in memory in native form.
tobinary — returns the content of a memory block as a Tcl binary string.
tobinary! — returns the content of a memory block as a Tcl binary string.
tostring — returns the content of a memory block as a Tcl string.
tostring! — returns the content of a memory block as a Tcl string.
tounistring — returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.
tounistring! — returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.
towinstring — returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.
towinstring! — 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 ✨

Allocates memory of the specified size. Fresh block, who dis. 🧚

memory allocate sizespec ?tag?

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. Don't forget, or that's a leak, bestie. 😭

Return value

Returns a safe pointer to the allocated memory.

See also

memory new, memory free

✨ memory fill ✨

Fills memory with a specified value.

memory fill pointer bytevalue count ?offset?

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 ✨

Frees the memory referenced by the passed pointer. The cleanup era. 🧹

memory free pointer

Parameters

pointer — safe pointer to memory to free.

Description

That 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 — no drama, no error, just vibes. 🦋

See also

memory allocate

✨ memory frombinary ✨

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

memory frombinary bin_value ?tag?

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 ✨

Allocates memory and stores a Tcl string in it, using the encoding you specify.

memory fromstring value ?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 ✨

Allocates memory and stores a Tcl string as a sequence of Tcl_UniChars.

memory fromunistring value

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 ✨

Allocates memory and stores a Tcl string as a sequence of winchars.

memory fromwinstring value

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 ✨

Converts a native value sitting in memory into a Tcl script level value. Glow-up: native edition. 🦋

memory get pointer typespec ?index?

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 — where in memory you're reading from, bestie. Care must be taken this is within bounds of the allocated space. Optional, default 0.

✏️ Description

This 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 the memory address used is that of the slot given by $index.

Okay so the offset math, because this is the part where people get humbled 😭 — 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. But ✨careful✨: if $typespec is int[3], then the size of the type specification is 12, and an index of 2 will correspond to a byte offset of 24, not 8. Be aware of these semantics when reading arrays using non-0 indices.

👀 See also

memory get!, memory set

🫶 `memory get!` (::cffi)

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

memory get! pointer typespec ?index?

Parameters

pointer — base address of the memory location. The pointer is not checked for validity. 💀
typespec — the type specification to use for conversion.
index — the index in memory from which the value is to be retrieved. Care must be taken this is within bounds of the allocated space. Optional, default 0.

✏️ Description

This command is literally 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 the details, bestie 🧚

👀 See also

memory get, memory set

🌸 `memory new` (::cffi)

Allocates memory for a type and initializes it. It's giving "birth of an object" energy 🎀

memory new typespec initializer ?tag?

Parameters

typespec — a type declaration.
initializer — the type-specific value to use to initialize the allocated memory.
tag — the optional tag for the returned pointer. Optional, default "".

✏️ Description

The $typespec argument may be any type specification. 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. Yes bestie, you have to clean up after yourself, no cap 🫶

📦 Return value

Returns a safe pointer to the allocated memory. ✨

👀 See also

memory allocate, memory free

💜 `memory set` (::cffi)

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

memory set pointer typespec value ?index?

Parameters

pointer — base address of the memory location. The pointer must be a safe pointer but the tag is immaterial.
typespec — the 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 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.

The math, again, because it do be like that 😭 — 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. But 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. 💀 No fr, that one's serious.

👀 See also

memory get, memory set!

🦋 `memory set!` (::cffi)

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

memory set! pointer typespec value ?index?

Parameters

pointer — base address of the memory location. The pointer is not checked for validity.
typespec — the type specification.
value — the script level value to be stored.
index — the index in memory at which the value is to be stored. Care must be taken this is within bounds of the allocated space. Optional, default 0.

✏️ Description

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

👀 See also

memory get, memory set

🍓 `memory tobinary` (::cffi)

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

memory tobinary pointer size ?offset?

Parameters

pointer — safe pointer to memory.
size — number of bytes to copy from the memory block.
offset — offset from $pointer of the area to value. <italian>May be negative for unsafe pointers.</italian> Optional, default 0.

📦 Return value

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

👀 See also

memory tobinary!, memory frombinary

🔥 `memory tobinary!` (::cffi)

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

memory tobinary! pointer size ?offset?

Parameters

pointer — pointer to memory.
size — number of bytes to copy from the memory block.
offset — offset from $pointer of the 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. 🙈 You've been warned, bestie.

📦 Return value

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

👀 See also

memory tobinary, memory frombinary

🎀 `memory tostring` (::cffi)

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

memory tostring pointer ?encoding? ?offset?

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 the area to value. May be negative for unsafe pointers. Optional, default 0.

📦 Return value

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

👀 See also

memory tostring!, memory fromstring

🧚 `memory tostring!` (::cffi)

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

memory tostring! pointer ?encoding? ?offset?

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 the 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)

Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string. Unicode girlie era 🦋

memory tounistring pointer ?offset?

Parameters

pointer — safe pointer to memory.
offset — offset in Tcl_UniChar units from $pointer of the 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)

Returns the content of a memory block containing a nul-terminated sequence of Tcl_UniChars as a Tcl string.

memory tounistring! pointer ?offset?

Parameters

pointer — pointer to memory. Need not be a safe pointer.
offset — offset in Tcl_UniChar units from $pointer of the 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)

Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.

memory towinstring pointer ?offset?

Parameters

pointer — safe pointer to memory.
offset — offset in WCHAR units from $pointer of the 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)

Returns the content of a memory block containing a nul-terminated sequence of winchars as a Tcl string.

memory towinstring! pointer ?offset?

Parameters

pointer — pointer to memory. Need not be a safe pointer.
offset — offset in WCHAR units from $pointer of the 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)

A command ensemble. Like, a little command family reunion 🎀

pkgconfig subcommand ...

✏️ Description

The ensemble supports the following subcommands:

get — gets the value of a configuration key.
list — returns the list of keys containing information about the package configuration.

Refer to the documentation of each subcommand for details 🫶

🔍 `pkgconfig get` (::cffi)

Gets the value of a configuration key.

pkgconfig get key

Parameters

key — one of the keys returned by the pkgconfig list command.

✏️ Description

The following keys are supported. Iconic lineup honestly ✨

backend — returns libffi or dyncall, indicating the backend FFI library in use.
version — the package version.
compiler — identifies the compiler used to build the extension.

📋 `pkgconfig list` (::cffi)

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

pkgconfig list

📦 Return value

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

🌈 `pointer` (::cffi)

A command ensemble.

pointer subcommand ...

✏️ Description

okay so the ensemble supports these subcommands, bestie — here's the whole lineup ✨

address — gives you back the address component of the pointer.
cast — casts a pointer to a new tag.
castable — says that pointers tagged $subtag are acceptable in declarations that require $supertag.
castables — returns a list of tags that have been marked as castable with the pointer castable command..
check — validates a pointer and raises an exception if it's invalid.
compare — compares if two pointers are the same.
counted — registers a pointer as a counted pointer.
dispose — unregisters a safe or counted pointer.
info — returns a dictionary containing registration information about a pointer.
invalidate — unregisters a safe, counted or pinned pointer irrespective its reference count.
isnull — returns true if the pointer is a NULL pointer, false otherwise.
isvalid — validates a pointer.
list — returns a list of registered pointers optionally filtered by a tag.
make — return a pointer for a memory address.
pin — pins a pointer as permanently safe.
safe — registers a pointer as a safe uncounted pointer.
tag — returns the pointer tag.
uncastable — makes pointers with the specified tag uncastable to another type.

Refer to the documentation of each subcommand for details 💖

pointer address (::cffi)

Returns the address component of the pointer.

pointer address pointer

Parameters

pointer — Pointer whose address component is to be returned.

Return value

Returns the address component of the pointer. that's it, that's the whole vibe 🎀

pointer cast (::cffi)

Casts a pointer to a new tag.

pointer cast pointer ?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

heads up bestie — 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). lowkey a glow-down but ok 🫶

Return value

Returns a pointer with the same address and new tag

pointer castable (::cffi)

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

pointer castable subtags 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. iykyk 💅

pointer castables (::cffi)

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

pointer castables

Return value

Returns a list of tags that have been marked as castable with the pointer castable command.. (yes, same sentence twice, she said what she said 💀)

pointer check (::cffi)

Validates a pointer and raise an exception if invalid.

pointer check pointer

Parameters

pointer — Pointer to be validated.

Description

for a pointer to be treated as valid, all three of these have to hit:

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)

Compares if two pointers are the same

pointer compare ptr1 ptr2

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. three whole moods fr fr 😭

pointer counted (::cffi)

Registers a pointer as a counted pointer

pointer 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)

Unregisters a safe or counted pointer

pointer dispose 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. like, it's uninviting them from the group chat, not deleting their whole existence, ok? 💅

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)

Returns a dictionary containing registration information about a pointer.

pointer info 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)

Unregisters a safe, counted or pinned pointer irrespective its reference count.

pointer invalidate 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.

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)

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

pointer isnull pointer

Parameters

pointer — Pointer to be checked.

Return value

Returns true if the pointer is a NULL pointer, false otherwise. simple. iconic. no notes 🎀

pointer isvalid (::cffi)

Validates a pointer.

pointer isvalid 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)

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

pointer list ?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)

Return a pointer for a memory address.

pointer make address ?tag?

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. ngl that's your job, not hers 🫶

pointer pin (::cffi)

Pins a pointer as permanently safe.

pointer pin pointer

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)

Registers a pointer as a safe uncounted pointer.

pointer safe 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)

Returns the pointer tag

pointer tag pointer

✨ Parameters ✨

pointer — the pointer whose tag you wanna get back, bestie.

💖 Description 💖

If that pointer isn't tagged? You just get an empty string. No drama, no error, just "". 💅

Peep Pointers for the full tea on pointer tags.

🎀 Return value 🎀

Returns the pointer tag. That's it, that's the whole vibe.

🚫 pointer uncastable (::cffi)

Makes pointers rockin' a specific tag uncastable to any other type.

pointer uncastable tag

Parameters

tag — a pointer tag. Any pointer tagged with $tag will no longer be castable to other tags that were set up with the pointer castables command. Locked in. 🔒

🧬 prototype (::cffi)

It's a command ensemble, babes.

prototype subcommand ...

Description

This ensemble comes with the following subcommands:

delete — nukes prototypes matching a pattern.
function — defines a function prototype for calling a function using the default C calling convention.
list — hands back a list of prototypes matching the pattern you gave.
stdcall — defines a function prototype for calling a function using the stdcall calling convention.

Go read each subcommand's own docs for the deets. 📖

🗑️ prototype delete (::cffi)

Deletes prototypes matching a pattern. Bye bestie 👋

prototype delete pattern

Parameters

pattern — the pattern to match.

Description

The pattern matching algorithm is the exact same one Tcl's string match command uses. And no cap: it is not an error if the pattern doesn't match any prototypes. Zero matches? Zero problems. 🫶

🎯 prototype function (::cffi)

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

prototype function name fntype parameters

Parameters

name — the name for the prototype. It must begin with an alphabetic character, and it may contain alphanumerics and underscore.
fntype — the type definition for the return value from the function.
parameters — a list of alternating parameter name and type definitions.

Description

The $fntype and $parameters take the same form and have the same semantics as described for the ::cffi::Wrapper.function method for defining functions. But here's the plot twist 👀 — unlike that method, this command does not create a command for invoking a C function. It only defines a prototype that you can then use together with a C function address to invoke that function. Prototype now, call later. ✨

See Prototypes and function pointers for more details.

📋 prototype list (::cffi)

Returns a list of prototypes matching the specified pattern.

prototype list ?pattern?

Parameters

pattern — the pattern to match. Optional, defaults to *.

Description

Same pattern matching algorithm as Tcl's string match command. Consistent queen. 👑

Return value

Returns a list of prototypes matching the specified pattern.

🪟 prototype stdcall (::cffi)

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

prototype stdcall name fntype parameters

Parameters

name — the 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 — a list of alternating parameter name and type definitions.

Description

The $fntype and $parameters take the same form and have the same semantics as described for the ::cffi::Wrapper.stdcall method for defining functions. But again — unlike that method, this command does not create a command for invoking a C function. It just defines a prototype, which you then pair up with a C function address to invoke that function. 💅

See Prototypes and function pointers for more details.

💾 savederrors (::cffi)

Returns the errno and GetLastError() values from the last CFFI call that was annotated with saveerrors.

savederrors

Description

For functions annotated with saveerrors, CFFI internally saves the errno and (on Windows) the GetLastError() values. This savederrors command retrieves them as a pair — first element is the saved errno value, second is the GetLastError() result. Heads up: that second one is always 0 on non-Windows platforms. 🪟➡️🚫

🔮 type (::cffi)

Another command ensemble, because CFFI loves a good ensemble.

type subcommand ...

Description

The ensemble supports these subcommands:

count — returns the count of elements in an array type.
frombinary — converts the native binary value to its script level representation.
info — returns a dictionary stuffed with various information about a type declaration.
size — returns the size of a type in terms of the number of bytes of memory that type occupies.
tobinary — converts a script level value to a native representation.

Check each subcommand's own docs for the details. 🧚

🔢 type count (::cffi)

Returns the count of elements in an array type.

type count type

Parameters

type — a type definition or alias.

Description

A return value of -1 means the type is not an array. So if you see -1, that's your sign, bestie. 🙈

Return value

Returns the count of elements in an array type.

🧪 type frombinary (::cffi)

Converts the native binary value to its script level representation.

type frombinary typespec value

Parameters

typespec — a type declaration.
value — the native binary value.

Description

The $typespec argument may be any type specification. No restrictions, go off. 🔥

Return value

Returns the script level representation of the value.

🔍 type info (::cffi)

Returns a dictionary containing various information about a type declaration.

type info typedecl ?args?

Parameters

typedecl — a type declaration.
-parsemode MODE — one of param, return, field.
-vlacount VLACOUNT — number of elements in variable size array.

Description

The type gets parsed as a parameter type declaration, a function return type declaration, or a structure field type declaration — depends on the -parsemode option. If that's unspecified or an empty string, it's parsed in a generic fashion and no context-specific validation is done at all. Freestyle mode. 💃

The option -vlacount must be specified if the type is a variable length array, or a struct that contains a variable length array.

The returned dictionary has these keys:

Alignment — the memory alignment needed for a value of that type.
BaseSize — the number of bytes to store a single value of the type when the type is an array. For scalars, same as Size.
Count — -1 for scalar values, otherwise it means the type is an array with that number of elements.
Size — the number of bytes of memory needed to store a value of that type.
Definition — the type declaration after applying any defaults. For type aliases, this is the resolved type definition.

Return value

Returns a dictionary containing various information about a type declaration.

📏 type size (::cffi)

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

type size type ?args?

Parameters

type — a type definition or alias.
-vlacount VLACOUNT — number of elements in variable size array.

Description

For array types, the size includes the size of the entire array — not just a single element. The whole thing, bestie. 🫶

The option -vlacount must be specified if the type is a 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)

Converts a script level value to a native representation.

type tobinary typespec value

Parameters

typespec — a type declaration.
value — the script level value.

Description

The $typespec argument must not have a string or variable size component. And if an array is specified that's a larger size than the number of elements in $value, the remaining elements get zeroed out. Padding with zeros, iconic behaviour honestly. ✨

Return value

Returns a Tcl binary containing the native representation.

🌈 CLASSES 🌈

🏛️ Interface (::cffi)

Method summary

constructor — constructor for the class.
id — returns the id for the interface as passed via the -id option in the interface definition.
methods — creates Tcl commands wrapping the C functions comprising an interface.
stdmethods — creates Tcl commands corresponding to the C functions comprising an interface.

🧚 constructor (::cffi::Interface)

Defines an interface consisting of method definitions.

Interface create OBJNAME ?args?
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, you can use this 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 at all.

Description

See Interfaces for more information. 📚

🆔 id (::cffi::Interface)

Returns the id for the interface as passed via the -id option in the interface definition.

INTERFACEOBJ id

Return value

Returns the id for the interface as passed via the -id option in the interface definition.

🛠️ methods (::cffi::Interface)

Creates Tcl commands wrapping the C functions comprising an interface.

INTERFACEOBJ methods methodlist ?args?

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 one is typed as pointer.INTERFACENAME. 👑

The order of the methods in $methodlist must be the same as that in the corresponding C interface. And every function in the interface is expected to have a pointer to the interface as its first parameter. No skipping, no reordering, fr fr. 🚨

The $methodlist argument is a flat (not nested) list of function name, return type and parameter list — same form as described for the ::cffi::Wrapper::function method, except the first parameter in the C function, the pointer to the object, should not be included. Like, don't double up on the pointer, bestie 🫶

stdmethods (`::cffi::Interface`)

Makes Tcl commands for all the C functions that make up an interface. Basically a whole squad of commands, one per function ✨

INTERFACEOBJ stdmethods methodlist ?args?

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

These C functions are presumed to be using the _stdcall calling convention. The commands it creates look like INTERFACENAME.METHODNAME, and the first argument to each one is typed as pointer.INTERFACENAME.

Heads up: the order of the methods in $methodlist must be the same as that in the corresponding C interface. And all functions in the interface are expected to have a pointer to the interface as the first parameter — no exceptions, it's giving rules 📋

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.

👑 Struct (`::cffi`) 👑

Method summary

constructor — constructor for the class.
allocate — allocates memory for one or more C structs.
describe — returns a human-readable description of the C struct definition.
fieldpointer — returns a pointer corresponding to the address of a field within a native structure.
free — frees memory that was allocated for a native C struct.
frombinary — decodes a Tcl binary string containing a native C struct into a Tcl dictionary.
fromnative — decodes native C struct(s) in memory into a Tcl dictionary.
fromnative! — decodes native C struct(s) in memory into a Tcl dictionary.
getnative — returns the value of a field in a native structure in memory.
getnative! — returns the value of a field in a native structure in memory.
getnativefields — retrieve values of multiple fields from a native struct in memory.
getnativefields! — retrieve values of multiple fields from a native struct in memory.
info — returns a dictionary containing information about the struct layout.
name — returns the name of the struct.
new — allocates and initializes a native struct in memory.
setnative — sets the value of a field in a native structure in memory.
setnative! — sets the value of a field in a native structure in memory.
size — returns the size of the struct.
tobinary — encodes the Tcl representation of a C struct value into a Tcl binary string.
tonative — writes the Tcl dictionary representation of a C struct value to memory in native form.
tonative! — writes the Tcl dictionary representation of a C struct value to memory in native form.

🌸 constructor (`::cffi::Struct`)

Builds a script-level object that maps to a C struct definition. Iconic behaviour, honestly 💅

Struct create OBJNAME definition ?args?
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 object it makes can pass arguments to and from functions, allocate memory, encode and decode native C structs in memory, etc. A whole little multi-tool 🧰

The $definition argument is a dictionary mapping field names to the corresponding types. See Packed structs for more info.

The name of the created struct is the same as the name of the returned object without the initial :: global namespace qualifier. You can grab that name with the name method, and it's what gets 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 that case, missing field values in a struct value will not raise an error, even if there's no default annotation on the field. It also effectively gives you a default zero value for all fields. Zeroes for days ✨

🌈 allocate (`::cffi::Struct`)

Allocates memory for one or more C structs.

STRUCTOBJ allocate ?args?

Parameters

-count COUNT — number of structs to allocate.
-vlacount VLACOUNT — number of elements in variable size array.

Description

Unlike the new method, the allocated memory is not initialized. That's true even if the struct definition includes the -clear option. No hand-holding here 😌

You must specify the -vlacount option if the struct contains a field that is a variable length array (VLA), or a nested struct that contains a VLA. VLACOUNT is then the length of that array.

The allocated memory must be freed by calling the free method of the struct. Don't leave it hanging, bestie — that's a leak 😭

Return value

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

🦋 describe (`::cffi::Struct`)

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

STRUCTOBJ describe

Description

This is mainly for debugging and troubleshooting purposes. Note the returned info will not take into account the variable components of the struct, if any. So like, it's the vibe of the struct, not the whole truth 🙈

Return value

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

🎀 fieldpointer (`::cffi::Struct`)

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

STRUCTOBJ fieldpointer pointer fieldname ?tag? ?index?

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. Lowkey important, ngl 👀

Return value

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

💜 free (`::cffi::Struct`)

Frees memory that was allocated for a native C struct.

STRUCTOBJ free pointer

Parameters

pointer — a pointer returned by allocate.

🍓 frombinary (`::cffi::Struct`)

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

STRUCTOBJ frombinary bin_value

Parameters

bin_value — a Tcl binary value containing the C struct.

Return value

Returns the dictionary representation.

⭐ fromnative (`::cffi::Struct`)

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

STRUCTOBJ fromnative pointer ?index?

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 is 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. No vibes-based guessing allowed 🚫

Return value

Returns a dictionary of the decoded struct.

🔥 fromnative! (`::cffi::Struct`)

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

STRUCTOBJ fromnative! pointer ?index?

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

Return value

Returns a dictionary of the decoded struct.

💖 getnative (`::cffi::Struct`)

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

STRUCTOBJ getnative pointer fieldname ?index?

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. Safety first 🛡️

Return value

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

🧚 getnative! (`::cffi::Struct`)

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

STRUCTOBJ getnative! pointer fieldname ?index?

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.

🌸 `getnativefields` (::cffi::Struct) 🌸

Bestie, this one's the bulk grab — pull a whole handful of field values out of a native struct in memory all at once instead of doing them one by one. Iconic efficiency 💅

STRUCTOBJ getnativefields pointer fieldnames ?index?

Parameters 🎀

pointer — Pointer to memory allocated for the C struct or array. It must be tagged with the struct name, no cap.
fieldnames — List of field names. Yep, a list. Give it a list.
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. Same order, always — she's consistent 💖

🦋 `getnativefields!` (::cffi::Struct) 🦋

Same group-chat energy as above but the unsafe version — she does not check your pointer for you. Live dangerously, bestie 😭

STRUCTOBJ getnativefields! pointer fieldnames ?index?

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) 🔍

The gossip session about your struct's layout — where every field actually sits in memory 👑

STRUCTOBJ info ?args?

Parameters 🎀

-vlacount VLACOUNT — Number of elements in variable size array.

Description 💜

The returned dictionary has the following fields:

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

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) 🎀

Just tells you the struct's name. Short and sweet, main character energy 🫶

STRUCTOBJ name

Description 💜

Note the name of the struct is different from the name of the object name. They're two different girlies, don't confuse them 💅

Return value ✨

Returns the name of the struct.

🌈 `new` (::cffi::Struct) 🌈

Manifesting a brand new native struct in memory, fully allocated and initialized ✨

STRUCTOBJ new ?initval?

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. Don't ghost your malloc, bestie, that's a memory leak 💀

Return value ✨

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

💜 `setnative` (::cffi::Struct) 💜

Write a single field value straight into a native struct in memory. One field. Very demure 🎀

STRUCTOBJ setnative pointer fieldname value ?index?

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. She said what she said 🚫

🔥 `setnative!` (::cffi::Struct) 🔥

The unsafe twin — same set-a-field job, but with a safe or unsafe pointer. Chaos permitted 🙈

STRUCTOBJ setnative! pointer fieldname value ?index?

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) 🦋

How big is she? Struct size, retrieved 🌸

STRUCTOBJ size ?args?

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) 🎁

Takes your cute little Tcl dict of a struct value and squishes it into a raw Tcl binary string 🧚

STRUCTOBJ tobinary dict_value

Parameters 🎀

dict_value — A Tcl dictionary representation of a C struct value.

Return value ✨

Returns the binary string containing the native C struct.

💖 `tonative` (::cffi::Struct) 💖

Writes the Tcl dictionary representation of a C struct value to memory in native form. The write-to-memory glow-up ✨

STRUCTOBJ tonative pointer initializer ?index?

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. Sorry babe, VLAs don't get this 💀

See also 🌈

tonative!, fromnative, tobinary

⭐ `tonative!` (::cffi::Struct) ⭐

Same as above but she's the unsafe one — safe or unsafe pointer, your call, your responsibility 😌

STRUCTOBJ tonative! pointer initializer ?index?

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) 👑

Method summary 💅

constructor — Constructor for the class.
decode — Returns a field from a native union.
describe — Returns a human-readable description of the C union definition.
encode — Returns a union in native form with the specified field value.
info — Returns a dictionary containing information about the info layout.
name — Returns the name of the struct.
size — Returns the size of the union.

🧚 `constructor` (::cffi::Union) 🧚

Builds a script-level object that maps to a C union definition. Union era 💐

Union create OBJNAME definition ?args?
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) 🌸

Pulls a field out of a native union. Reverse of encode, bestie 💖

UNIONOBJ decode field uvalue

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 🌈

encode

🎀 `describe` (::cffi::Union) 🎀

Gives you a human-readable description of the C union definition. She's explaining herself 💅

UNIONOBJ describe

Description 💜

This is primarily for debugging and troubleshooting purposes.

Return value ✨

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

🔥 `encode` (::cffi::Union) 🔥

Hands you back a union in native form with the field value you specified all set and slayed ✨

UNIONOBJ encode 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 🌈

decode

🦋 `info` (::cffi::Union) 🦋

Returns a dictionary containing information about the info layout. The union's whole vibe, documented 📋

UNIONOBJ info

Description 💜

The returned dictionary has the following fields:

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

Other fields may be present and should be ignored. Mind your business on those ones 🙈

Return value ✨

Returns a dictionary containing information about the info layout.

💜 `name` (::cffi::Union) 💜

Returns the name of the struct. Yes, again. She's consistent 🫶

UNIONOBJ name

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) 🌈

Size of the union. That's it, that's the method 💐

UNIONOBJ size

Return value ✨

Returns the size of the union.

🦋 Wrapper (::cffi) 🦋

okay bestie, this is the wrapper class itself — the icon that wraps a shared library / DLL and loads it right into the process. 💅

✨ Method summary ✨

constructor — Constructor for the class.
destructor — Destructor for the class.
addressof — Returns the address of a symbol from the loaded library.
function — Creates a Tcl command to invoke a C function in the loaded library.
functions — Creates Tcl commands for multiple C functions within the loaded library.
path — Returns the file system path for the wrapped library or image wrapped by the object.
stdcall — Creates a Tcl command to invoke a C function that uses the __stdcall calling convention from the loaded library..
stdcalls — Creates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention.

🧸 constructor (::cffi::Wrapper) 🧸

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

Wrapper create OBJNAME path
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. Bestie, do not play with this one. Otherwise, it is located in a system-specific manner involving operating system version, environment variables, registry settings (on Windows), phase of the moon etc.. This is not advisable for both reliability and security reasons.

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

⭐ Return value

Returns the name of the created object.

💀 destructor (::cffi::Wrapper) 💀

Destroys the object and releases internal resources.

WRAPPEROBJ destroy

🫶 Description

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

🎀 addressof (::cffi::Wrapper) 🎀

Returns the address of a symbol from the loaded library.

WRAPPEROBJ addressof symbol

🌸 Parameters

symbol — Name of the symbol.

💖 Description

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

⭐ Return value

Returns the address of a symbol from the loaded library.

🔥 function (::cffi::Wrapper) 🔥

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

WRAPPEROBJ function fnname fntype parameters

🌸 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) 🌈

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

WRAPPEROBJ functions fnlist ?args?

🌸 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) 🦋

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

WRAPPEROBJ path

💖 Description

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

⭐ Return value

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

💜 stdcall (::cffi::Wrapper) 💜

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

WRAPPEROBJ stdcall fnname fntype parameters

🌸 Parameters

fnname — Name of the function and optionally, Tcl command.
fntype — The type definition for the return value from the function.
parameters — List of alternating parameter name and type definitions.

💖 Description

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

See function for other details.

⭐ Return value

Returns the name of the created Tcl command.

🍓 stdcalls (::cffi::Wrapper) 🍓

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

WRAPPEROBJ stdcalls fnlist ?args?

🌸 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.

that’s the Wrapper class wrapped up, bestie 💖 signed off from cffi 2.0.3, the cffi(3tcl) source page, and its footer date doing its little timestamp thing 💅✨

📦 where this page comes from

nixpkgs unstable: cffi 2.0.3
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms