::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
| 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::dyncall::Library]Library, Top, Main, Index
Wraps a shared library / DLL, loading it in the process.
Library new ?path?
Parameters
path | Path 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.
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.
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::dyncall::Library]Library, Top, Main, Index
Creates a Tcl command to invoke a C function in the loaded library.
Parameters
fnname | Name of the function and optionally, Tcl command. |
fntype | The type definition for the return value from the function. |
parameters | List of alternating parameter name and type definitions. |
Description
The command creates a Tcl command corresponding to a C function contained in the library. The function must be one that follows the default C calling convention (See Calling conventions).
The $fnname argument is a one or two element list, the first being the name of the C function and the second, if present, being the name of the corresponding Tcl command. The latter defaults to the former if unspecified. Unless fully qualified, the command is created in the namespace from which it is called.
The return type of the C function is specified through the $fntype argument which should be a type declaration.
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.
Parameters
fnlist | List of function definitions. |
Description
This is a wrapper around the function method that provides some syntactic sugar for defining multiple functions. The $fnlist argument is a flat (not nested) list of function name, return type and parameter list in the same form as described for the function method.
path [::cffi::dyncall::Library]Library, Top, Main, Index
Returns the file system path for the wrapped library or image wrapped by the object.
Description
The returned path may be or may not be normalized and may be in native form or Tcl's canonical form. If no path argument was provided to the constructor, an empty string may be returned on some platforms.
Return value
Returns the file system path for the wrapped library or image wrapped by the object.
stdcall [::cffi::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..
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::dyncall::Library]Library, Top, Main, Index
Creates Tcl commands for multiple C functions within the loaded library that all use the __stdcall calling convention.
Parameters
fnlist | List of function definitions. |
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
| constructor | Constructor for the class. |
| destructor | Destructor for the class. |
| ataddress | Returns the name of the symbol at a specified address. |
| count | Returns the number of symbols defined in the library. |
| index | Returns 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 new ?path?
Parameters
path | Path 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.
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.
Parameters
addr | Memory 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.
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.
Parameters
index | Index 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.