# ::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 create OBJNAME ?path?
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.

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

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

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

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

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

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

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

OBJECT stdcalls fnlist

##### 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 create OBJNAME ?path?
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.

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

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

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

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