Dyn::Call - Architecture-, OS- and Compiler-agnostic Function Call Semantics
use Dyn::Call qw[:all]; # ... my $cvm = dcNewCallVM( 1024 ); dcMode( $cvm, 0 ); dcReset( $cvm ); dcArgInt( $cvm, 5 ); dcArgInt( $cvm, 6 ); dcCallInt( $cvm, $ptr ); # '5 + 6 == 11';
Dyn::Call wraps the dyncall CallVM; a state machine which provides low-level functionality to make foreign function calls from different run-time environments. The flexibility is constrained by the set of supported types.
dyncall
Everything listed here may be imported by name, with the given import tag or with the :all tag.
:all
These functions effect the CallVM which manages all aspects of a function call from configuration, argument passing up the actual function call on the processor.
You may import functions here by name or with the :callvm tag.
:callvm
dcNewCallVM( ... )
my $cvm = dcNewCallVM( 1024 );
This function 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. You must use dcFree( ... ) to properly destroy the CallVM object.
CallVM
size
dcFree( ... )
Expected parameters include:
Returns a new CallVM object on success.
Destroy a CallVM instance.
dcFree( $cvm );
vm
Dyn::Call
dcGetError( ... )
Returns the most recent error state code.
my $error = dcGetError( $cvm );
Possible error states are listed below.
dcMode( ... )
Sets the calling convention to use.
dcMode( $cvm, DC_CALL_C_DEFAULT );
Note that some mode/platform combinations don't make any sense (e.g. using a PowerPC calling convention on a MIPS platform) and are silently ignored.
mode
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.
DC_CALL_C_DEFAULT
DC_CALL_C_ELLIPSIS
dcReset( ... )
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 Dyn::Call VM (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 Dyn::Call VM, as arguments don't get flushed automatically after a function call invocation.
DC_SIGCHAR_CC_ELLIPSIS_VARARGS
Note: you should also call this function after initial creation of the a Dyn::Call object, as dcNewCallVM( ... ) doesn't do this, implicitly.
These functions are used to bind arguments of the named types to the CallVM object. Arguments should be bound in left-to-right order regarding the C style function prototype.
These functions may be imported by name or with the :bind tag.
:bind
dcArgBool( ... )
Pushes a boolean value onto the argument stack.
dcArgBool( $cvm, 1 ); # or 0, of course
arg
dcArgChar( ... )
Pushes a char value onto the argument stack.
dcArgChar( $cvm, 'a' );
dcArgShort( ... )
Pushes a short integer value onto the argument stack.
dcArgShort( $cvm, -500 );
dcArgInt( ... )
Pushes an integer value onto the argument stack.
dcArgInt( $cvm, -500 );
dcArgLong( ... )
Pushes a long integer value onto the argument stack.
dcArgLong( $cvm, -2147483647 );
dcArgLongLong( ... )
Pushes a long long integer value onto the argument stack.
dcArgLongLong( $cvm, -9223372036854775807 );
dcArgFloat( ... )
Pushes a single-precision floating point value onto the argument stack.
dcArgFloat( $cvm, 3.14 );
dcArgDouble( ... )
Pushes a double-precision floating point value onto the argument stack.
dcArgDouble( $cvm, 3.14 );
dcArgPointer( ... )
Pushes a pointer (void *) value onto the argument stack.
void *
dcArgPointer( $cvm, $struct );
dcArgString( ... )
Pushes a string (char *) value onto the argument stack.
char *
dcArgString( $cvm, 'John' );
These functions call 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.
funcptr
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.
These functions may be imported by name or with the :call tag.
:call
dcCallVoid( ... )
Invokes the function with a the expectations of void return value.
dcCallBool( ... )
Invokes the function with the expectations of a boolean return value.
my $tf = dcCallBool( $cvm, $funcptr );
dcCallChar( ... )
Invokes the function with the expectations of a char return value.
my $char = dcCallChar( $cvm, $funcptr );
dcCallShort( ... )
Invokes the function with the expectations of a short return value.
my $ret = dcCallShort( $cvm, $funcptr );
dcCallInt( ... )
Invokes the function with the expectations of a integer return value.
my $sum = dcCallInt( $cvm, $funcptr );
dcCallLong( ... )
Invokes the function with the expectations of a long return value.
my $val1 = dcCallLong( $cvm, $funcptr );
dcCallLongLong( ... )
Invokes the function with the expectations of a long long return value.
my $val2 = dcCallLongLong( $cvm, $funcptr );
dcCallFloat( ... )
Invokes the function with the expectations of a float return value.
my $f = dcCallFloat( $cvm, $funcptr );
dcCallDouble( ... )
Invokes the function with the expectations of a double return value.
my $num = dcCallDouble( $cvm, $funcptr );
dcCallPointer( ... )
Invokes the function with a the expectations of a pointer (void *) return value.
my $ptr = dcCallPointer( $cvm, $funcptr );
dcCallString( ... )
Invokes the function with a string (const char *) return value.
const char *
my $str = dcCallString( $cvm, $funcptr );
These functions aide in computing the size of a structure. They may be imported by name or with the :struct tag.
:struct
dcNewStruct( ... )
Creates a new DCstruct.
DCstruct
my $struct = dcNewStruct( 4, DEFAULT_ALIGNMENT );
fieldCount
alignment
dcStructField( ... )
Adds a new field to the structure.
dcStructField( $struct, DC_SIGCHAR_INT, DEFAULT_ALIGNMENT, 1 );
struct
type
arrayLength
dcSubStruct( ... )
Nests a structure inside of another.
dcSubStruct( $struct, 1, DEFAULT_ALIGNMENT, 1 );
These values are returned by dcGetError( ... ) and include:
DC_ERROR_NONE
DC_ERROR_UNSUPPORTED_MODE
You may set the calling convention to use with dcMode( ... ).
DC_CALL_C_ELLIPSIS_VARARGS
DC_CALL_C_X86_CDECL
DC_CALL_C_X86_WIN32_STD
DC_CALL_C_X86_WIN32_FAST_MS
DC_CALL_C_X86_WIN32_FAST_GNU
DC_CALL_C_X86_WIN32_THIS_MS
DC_CALL_C_X86_WIN32_THIS_GNU
DC_CALL_C_X86_PLAN9
DC_CALL_C_X64_WIN64
DC_CALL_C_X64_SYSV
DC_CALL_C_PPC32_DARWIN
DC_CALL_C_PPC32_OSX
DC_CALL_C_PPC32_SYSV
DC_CALL_C_PPC32_LINUX
DC_CALL_C_PPC64
DC_CALL_C_PPC64_LINUX
DC_CALL_C_ARM_ARM
DC_CALL_C_ARM_THUMB
DC_CALL_C_ARM_ARM_EABI
DC_CALL_C_ARM_THUMB_EABI
DC_CALL_C_ARM_ARMHF
DC_CALL_C_ARM64
DC_CALL_C_MIPS32_EABI
DC_CALL_C_MIPS32_PSPSDK
DC_CALL_C_MIPS32_O32
DC_CALL_C_MIPS64_N64
DC_CALL_C_MIPS64_N32
DC_CALL_C_SPARC32
DC_CALL_C_SPARC64
DC_CALL_SYS_DEFAULT
DC_CALL_SYS_X86_INT80H_BSD
DC_CALL_SYS_X86_INT80H_LINUX
DC_CALL_SYS_X64_SYSCALL_SYSV
DC_CALL_SYS_PPC32
DC_CALL_SYS_PPC64
DC_SIGCHAR_VOID
DC_SIGCHAR_BOOL
DC_SIGCHAR_CHAR
DC_SIGCHAR_UCHAR
DC_SIGCHAR_SHORT
DC_SIGCHAR_USHORT
DC_SIGCHAR_INT
DC_SIGCHAR_UINT
DC_SIGCHAR_LONG
DC_SIGCHAR_ULONG
DC_SIGCHAR_LONGLONG
DC_SIGCHAR_ULONGLONG
DC_SIGCHAR_FLOAT
DC_SIGCHAR_DOUBLE
DC_SIGCHAR_POINTER
DC_SIGCHAR_STRING
DC_SIGCHAR_STRUCT
DC_SIGCHAR_ENDARG
DC_SIGCHAR_CC_PREFIX
DC_SIGCHAR_CC_DEFAULT
DC_SIGCHAR_CC_ELLIPSIS
DC_SIGCHAR_CC_CDECL
DC_SIGCHAR_CC_STDCALL
DC_SIGCHAR_CC_FASTCALL_MS
DC_SIGCHAR_CC_FASTCALL_GNU
DC_SIGCHAR_CC_THISCALL_MS
DC_SIGCHAR_CC_THISCALL_GNU
thiscall
cdecl
DC_SIGCHAR_CC_ARM_ARM
DC_SIGCHAR_CC_ARM_THUMB
DC_SIGCHAR_CC_SYSCALL
DEFAULT_ALIGNMENT
See Dyn::Call::Pointer for a list of direct memory manipulation functions which may be imported with the :memory tag.
:memory
The dyncall library runs on many different platforms and operating systems (including Windows, Linux, OpenBSD, FreeBSD, macOS, DragonFlyBSD, NetBSD, Plan9, iOS, Haiku, Nintendo DS, Playstation Portable, Solaris, Minix, Raspberry Pi, ReactOS, etc.) and processors (x86, x64, arm (arm & thumb mode), arm64, mips, mips64, ppc32, ppc64, sparc, sparc64, etc.).
Copyright (C) Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.
Sanko Robinson <sanko@cpan.org>
To install Affix, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Affix
CPAN shell
perl -MCPAN -e shell install Affix
For more information on module installation, please visit the detailed CPAN module installation guide.