::cffi::dyncallTop, Main, Index

This namespace contains classes wrapping the dyncall library for calling C functions in shared library. The namespace is automatically loaded with the cffi package.

Classesdyncall, Top, Main, Index

Library [::cffi::dyncall]dyncall, Top, Main, Index

Method summary
constructorConstructor for the class.
destructorDestructor for the class.
addressofReturns the address of a symbol from the loaded library.
functionCreates a Tcl command to invoke a C function in the loaded library.
functionsCreates Tcl commands for multiple C functions within the loaded library.
pathReturns the file system path for the wrapped library or image wrapped by the object.
stdcallCreates a Tcl command to invoke a C function that uses the __stdcall calling convention from the loaded library..
stdcallsCreates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention.

constructor [::cffi::dyncall::Library]Library, Top, Main, Index

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

Library create OBJNAME ?path?
Library new ?path?
Parameters
pathPath to the shared library. If an empty string, the process main executable is wrapped. Optional, default "".
Description

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

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

Return value

Returns the name of the created object.

destructor [::cffi::dyncall::Library]Library, Top, Main, Index

Destroys the object and releases internal resources.

OBJECT destroy
Description

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

addressof [::cffi::dyncall::Library]Library, Top, Main, Index

Returns the address of a symbol from the loaded library.

OBJECT addressof symbol
Parameters
symbolName 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::dyncall::Library]Library, Top, Main, Index

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

OBJECT function fnname fntype parameters
Parameters
fnnameName of the function and optionally, Tcl command.
fntypeThe type definition for the return value from the function.
parametersList of alternating parameter name and type definitions.
Description

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

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

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

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

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

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

Return value

Returns the name of the created Tcl command.

functions [::cffi::dyncall::Library]Library, Top, Main, Index

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

OBJECT functions fnlist
Parameters
fnlistList of function definitions.
Description

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

path [::cffi::dyncall::Library]Library, Top, Main, Index

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

OBJECT 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::dyncall::Library]Library, Top, Main, Index

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

OBJECT stdcall fnname fntype parameters
Parameters
fnnameName of the function and optionally, Tcl command.
fntypeThe type definition for the return value from the function.
parametersList 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::dyncall::Library]Library, Top, Main, Index

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

OBJECT stdcalls fnlist
Parameters
fnlistList of function definitions.
Description

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

Symbols [::cffi::dyncall]dyncall, Top, Main, Index

Method summary
constructorConstructor for the class.
destructorDestructor for the class.
ataddressReturns the name of the symbol at a specified address.
countReturns the number of symbols defined in the library.
indexReturns the name of the symbol at a specified index.

constructor [::cffi::dyncall::Symbols]Symbols, Top, Main, Index

Wraps a shared library / DLL to allow access to its symbols.

Symbols create OBJNAME ?path?
Symbols new ?path?
Parameters
pathPath to the shared library. Optional, default "".
Description

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

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

Objects of this class provide access to the symbols defined in the file without actually loading the file and resolving addresses. They can only therefore be used to search for symbols, locate symbols based on their index, and if the library has been loaded already, based on the symbol address.

An error is raised if the file does not exist or does not contain an exports table.

Return value

Returns the name of the created object.

destructor [::cffi::dyncall::Symbols]Symbols, Top, Main, Index

Destroys the object.

OBJECT destroy
Description

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

ataddress [::cffi::dyncall::Symbols]Symbols, Top, Main, Index

Returns the name of the symbol at a specified address.

OBJECT ataddress addr
Parameters
addrMemory address.
Description

The shared library must have been loaded into the process.

Return value

Returns the name of the symbol at a specified address.

count [::cffi::dyncall::Symbols]Symbols, Top, Main, Index

Returns the number of symbols defined in the library.

OBJECT count
Return value

Returns the number of symbols defined in the library.

index [::cffi::dyncall::Symbols]Symbols, Top, Main, Index

Returns the name of the symbol at a specified index.

OBJECT index index
Parameters
indexIndex into symbol table.
Description

The returned value may be an empty string if there is an entry in the symbol table at that index but no name.

Return value

Returns the name of the symbol at a specified index.

Document generated by Ruff!