dyncall library - C foreign function interface dyncall library: home - news - download - source/repository - bindings - documentation - license - credits - showcase/users - contact University of Göttingen 3ds Max, Maya Plugin Development - Potion Studios


Dyncall C library API

The library provides low-level functionality to make foreign function calls from different run-time environments. The flexibility is constrained by the set of supported types. C interface style conventions

This manual and the dyncall library’s C interface "dyncall.h" use the following C source code style.

Subject C symbol Details Example

Types DC<type name> lower-case DCint, DCfloat, DClong, …
Structures DC<structure name> camel-case DCCallVM
Functions dc<function name> camel-case dcNewCallVM, dcArgInt, …
Table 10: C interface conventions

Supported C/C++ argument and return types

Type alias C/C++ data type

DCbool _Bool, bool
DCchar char
DCshort short
DCint int
DClong long
DClonglong long long
DCfloat float
DCdouble double
DCpointer void*
DCvoid void
Table 11: Supported C/C++ argument and return types

Call Virtual Machine - CallVM

This CallVM is the main entry to the functionality of the library. Types

typedef void DCCallVM; /* abstract handle */

The CallVM is a state machine that manages all aspects of a function call from configuration, argument passing up the actual function call on the processor.


DCCallVM* dcNewCallVM (DCsize size); 
void      dcFree(DCCallVM* vm);

dcNewCallVM creates a new CallVM object, where size specifies the max size of the internal stack that will be allocated and used to bind arguments to. Use dcFree to destroy the CallVM object.

This will allocate memory using the system allocators or custom ones provided custom dcAllocMem and dcFreeMem macros are defined to override the default behaviour. See dyncall_alloc.h for defails.

Error Reporting

DCint dcGetError(DCCallVM* vm);

Returns the most recent error state code out of the following: Errors

Constant Description

DC_ERROR_NONE No error occured.
DC_ERROR_UNSUPPORTED_MODE Unsupported mode, caused by dcMode()
Table 12: CallVM calling convention modes


void dcMode (DCCallVM* vm, DCint mode);

Sets the calling convention to use. Note that some mode/platform combination don’t make any sense (e.g. using a PowerPC calling convention on a MIPS platform) and are silently ignored. Modes

Constant Description

DC_CALL_C_DEFAULT C default function call for current platform
DC_CALL_C_ELLIPSIS C ellipsis function call (named arguments (before ’...’))
DC_CALL_C_ELLIPSIS_VARARGS C ellipsis function call (variable/unnamed arguments (after ’...’))
DC_CALL_C_X86_CDECL C x86 platforms standard call
DC_CALL_C_X86_WIN32_STD C x86 Windows standard call
DC_CALL_C_X86_WIN32_FAST_MS C x86 Windows Microsoft fast call
DC_CALL_C_X86_WIN32_FAST_GNU C x86 Windows GCC fast call
DC_CALL_C_X86_WIN32_THIS_MS C x86 Windows Microsoft this call
DC_CALL_C_X86_WIN32_THIS_GNU alias for DC_CALL_C_X86_CDECL (GNU thiscalls identical to cdecl)
DC_CALL_C_X86_PLAN9 C x86 Plan9 call
DC_CALL_C_X64_WIN64 C x64 Windows standard call
DC_CALL_C_X64_SYSV C x64 System V standard call
DC_CALL_C_PPC32_DARWIN C ppc32 Mac OS X standard call
DC_CALL_C_PPC32_SYSV C ppc32 SystemV standard call
DC_CALL_C_PPC64 C ppc64 SystemV standard call
DC_CALL_C_ARM_ARM C arm call (arm mode)
DC_CALL_C_ARM_THUMB C arm call (thumb mode)
DC_CALL_C_ARM_ARM_EABI C arm eabi call (arm mode)
DC_CALL_C_ARM_THUMB_EABI C arm eabi call (thumb mode)
DC_CALL_C_ARM_ARMHF C arm call (arm hardfloat - e.g. raspberry pi)
DC_CALL_C_ARM64 C arm64 call (AArch64)
DC_CALL_C_MIPS32_EABI C mips32 eabi call
DC_CALL_C_MIPS32_PSPSDK alias for DC_CALL_C_MIPS32_EABI (deprecated)
DC_CALL_C_MIPS32_O32 C mips32 o32 call
DC_CALL_C_MIPS64_N64 C mips64 n64 call
DC_CALL_C_MIPS64_N32 C mips64 n32 call
DC_CALL_C_SPARC32 C sparc32 call
DC_CALL_C_SPARC64 C sparc64 call
DC_CALL_SYS_DEFAULT C default syscall for current platform
DC_CALL_SYS_X86_INT80H_BSD C syscall for x86 BSD platforms
DC_CALL_SYS_X86_INT80H_LINUX C syscall for x86 Linux
DC_CALL_SYS_X64_SYSCALL_SYSV C syscall for x64 System V platforms
DC_CALL_SYS_PPC32 C syscall for ppc32
DC_CALL_SYS_PPC64 C syscall for ppc64
Table 13: CallVM calling convention modes

DC_CALL_C_DEFAULT is the default standard C call on the target platform. It uses the standard C calling convention. DC_CALL_C_ELLIPSIS is used for C ellipsis calls which allow to build up a variable argument list. On many platforms, there is only one C calling convention. The X86 platform provides a rich family of different calling conventions.

Machine state reset

void dcReset(DCCallVM* vm);

Resets the internal stack of arguments and prepares it for a new call. This function should be called after setting the call mode (using dcMode), but prior to binding arguments to the CallVM (except for when setting mode DC_SIGCHAR_CC_ELLIPSIS_VARARGS, which is used prior to binding varargs of variadic functions). Use it also when reusing a CallVM, as arguments don’t get flushed automatically after a function call invocation.
Note: you should also call this function after initial creation of the a CallVM object, as dcNewCallVM doesn’t do this, implicitly.

Argument binding

void dcArgBool    (DCCallVM* vm, DCbool     arg); 
void dcArgChar    (DCCallVM* vm, DCchar     arg); 
void dcArgShort   (DCCallVM* vm, DCshort    arg); 
void dcArgInt     (DCCallVM* vm, DCint      arg); 
void dcArgLong    (DCCallVM* vm, DClong     arg); 
void dcArgLongLong(DCCallVM* vm, DClonglong arg); 
void dcArgFloat   (DCCallVM* vm, DCfloat    arg); 
void dcArgDouble  (DCCallVM* vm, DCdouble   arg); 
void dcArgPointer (DCCallVM* vm, DCpointer  arg);

Used to bind arguments of the named types to the CallVM object. Arguments should be bound in left-to-right order regarding the C function prototype.

Call invocation

DCvoid     dcCallVoid    (DCCallVM* vm, DCpointer funcptr); 
DCbool     dcCallBool    (DCCallVM* vm, DCpointer funcptr); 
DCchar     dcCallChar    (DCCallVM* vm, DCpointer funcptr); 
DCshort    dcCallShort   (DCCallVM* vm, DCpointer funcptr); 
DCint      dcCallInt     (DCCallVM* vm, DCpointer funcptr); 
DClong     dcCallLong    (DCCallVM* vm, DCpointer funcptr); 
DClonglong dcCallLongLong(DCCallVM* vm, DCpointer funcptr); 
DCfloat    dcCallFloat   (DCCallVM* vm, DCpointer funcptr); 
DCdouble   dcCallDouble  (DCCallVM* vm, DCpointer funcptr); 
DCpointer  dcCallPointer (DCCallVM* vm, DCpointer funcptr);

Calls the function specified by funcptr with the arguments bound to the CallVM and returns. Use the function that corresponds to the dynamically called function’s return value.

After the invocation of the foreign function call, the argument values are still bound and a second call using the same arguments can be issued. If you need to clear the argument bindings, you have to reset the CallVM.

Formatted argument binding and calls (ANSI C ellipsis interface)

void dcArgF  (DCCallVM* vm, const DCsigchar* signature, ...); 
void dcVArgF (DCCallVM* vm, const DCsigchar* signature, va_list args); 
void dcCallF (DCCallVM* vm, DCValue* result, DCpointer funcptr, 
              const DCsigchar* signature, ...); 
void dcVCallF(DCCallVM* vm, DCValue* result, DCpointer funcptr, 
              const DCsigchar* signature, va_list args);

These functions can be used to operate dyncall via a printf-style functional interface, using a signature string encoding the argument types and return type (and optionally also the calling convention used). dcArgF() and dcVArgF() just bind arguments to the DCCallVM object, so any return value specified in the signature is ignored. dcCallF() and dcVCallF() also take a function pointer to call after binding the arguments. The return value will be stored in what result points to. For more information about the signature format, refer to 2.