Mercurial > pub > dyncall > dyncall
view doc/manual/manual_dyncall_api.tex @ 526:93628a1eaed4
tests: integrate new tests into makefiles, some cleanups
author | Tassilo Philipp |
---|---|
date | Thu, 14 Apr 2022 10:06:58 +0200 |
parents | 17287342e273 |
children | 71c884e610f0 |
line wrap: on
line source
%////////////////////////////////////////////////////////////////////////////// % % Copyright (c) 2007,2010 Daniel Adler <dadler@uni-goettingen.de>, % Tassilo Philipp <tphilipp@potion-studios.com> % % Permission to use, copy, modify, and distribute this software for any % purpose with or without fee is hereby granted, provided that the above % copyright notice and this permission notice appear in all copies. % % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. % %////////////////////////////////////////////////////////////////////////////// \clearpage \section{\emph{Dyncall} C library API} See the dyncall(3) manpage for more information. %@@@ removed, as manpages are more precise and up to date -------------------> %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. % %\paragraph{C interface style conventions} % %This manual and the \product{dyncall} library's C interface {\tt "dyncall.h"} %use the following C source code style. % % %\begin{table}[h] %\begin{center} %\begin{tabular*}{0.8\textwidth}{llll} %Subject & C symbol & Details & Example \\ %\hline %Types & {\tt DC\group{type name}} & lower-case & \capi{DCint}, \capi{DCfloat}, \capi{DClong}, \ldots\\ %Structures & {\tt DC\group{structure name}} & camel-case & \capi{DCCallVM}\\ %Functions & {\tt dc\group{function name}} & camel-case & \capi{dcNewCallVM}, \capi{dcArgInt}, \ldots\\ % & {\tt dcb\group{function name}} & & \capi{dcbNewCallback}, \ldots\\ % & {\tt dl\group{function name}} & & \capi{dlLoadLibrary}, \ldots\\ %\end{tabular*} %\caption{C interface conventions} %\label{sourcecode} %\end{center} %\end{table} % %\subsection{Supported C/C++ argument and return types} % %\begin{table}[h] %\begin{center} %\begin{tabular*}{0.75\textwidth}{ll} %Type alias & C/C++ data type\\ %\hline %DCbool & \_Bool, bool\\ %DCchar & char, unsigned char\\ %DCshort & short, unsigned short\\ %DCint & int, unsigned char\\ %DClong & long, unsigned char\\ %DClonglong & long long, unsigned char\\ %DCfloat & float\\ %DCdouble & double\\ %DCpointer & void*\\ %DCvoid & void\\ %\em{...} & \em{aggregates (struct, union)} %\end{tabular*} %\caption{Supported C/C++ argument and return types} %\label{types} %\end{center} %\end{table} % %\pagebreak % %\subsection{Call Virtual Machine - CallVM} % %This \emph{CallVM} is the main entry to the functionality of the library. % %\paragraph{Types} % %\begin{lstlisting}[language=c] %typedef void DCCallVM; /* abstract handle */ %\end{lstlisting} % %\paragraph{Details} %The \emph{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. % %\subsection{Allocation} % %\paragraph{Functions} % %\begin{lstlisting}[language=c] %DCCallVM* dcNewCallVM (DCsize size); %void dcFree(DCCallVM* vm); %\end{lstlisting} % %\lstinline{dcNewCallVM} creates a new \emph{CallVM} object, where %\lstinline{size} specifies the max size of the internal stack that will be %allocated and used to bind arguments to. Use \lstinline{dcFree} to %destroy the \emph{CallVM} object.\\ %\\ %This will allocate memory using the system allocators or custom ones provided %custom \capi{dcAllocMem} and \capi{dcFreeMem} macros are defined to override the %default behaviour. See \capi{dyncall\_alloc.h} for defails. % % %\subsection{Error Reporting} % %\paragraph{Function} % %\begin{lstlisting}[language=c] %DCint dcGetError(DCCallVM* vm); %\end{lstlisting} % %Returns the most recent error state code out of the following: % %\paragraph{Errors} % %\begin{table}[h] %\begin{center} %\begin{tabular*}{0.95\textwidth}{ll} %Constant & Description\\ %\hline %\lstinline@DC_ERROR_NONE@ & No error occured. \\ %\lstinline@DC_ERROR_UNSUPPORTED_MODE@ & Unsupported mode, caused by \lstinline@dcMode()@ \\ %\end{tabular*} %\caption{CallVM calling convention modes} %\label{errorcodes} %\end{center} %\end{table} % %\pagebreak % %\subsection{Configuration} % %\paragraph{Function} % %\begin{lstlisting}[language=c] %void dcMode (DCCallVM* vm, DCint mode); %\end{lstlisting} % %Sets the calling convention to use. See dyncall.h for a list of available %modes. 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. % % %\subsection{Machine state reset} % %\begin{lstlisting}[language=c] %void dcReset(DCCallVM* vm); %\end{lstlisting} % %Resets the internal stack of arguments and prepares it for a new call. This %function should be called after setting the initial/main call mode (using %dcMode()), but prior to binding arguments to the CallVM (sometimes dcMode() %calls are needed after pushing some args, e.g. 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. % % %\subsection{Argument binding} % %\paragraph{Functions} % %\begin{lstlisting}[language=c] %void dcArgBool (DCCallVM*, DCbool); %void dcArgChar (DCCallVM*, DCchar); %void dcArgShort (DCCallVM*, DCshort); %void dcArgInt (DCCallVM*, DCint); %void dcArgLong (DCCallVM*, DClong); %void dcArgLongLong(DCCallVM*, DClonglong); %void dcArgFloat (DCCallVM*, DCfloat); %void dcArgDouble (DCCallVM*, DCdouble); %void dcArgPointer (DCCallVM*, DCpointer); %void dcArgAggr (DCCallVM*, const DCaggr*, const void*); %\end{lstlisting} % %\paragraph{Details} % %Used to bind arguments of the named types to the CallVM object. %Arguments should be bound in \emph{left-to-right} order regarding the C %function prototype.\\ %\\ %See the dyncall(3) manpage for more information. % % %\subsection{Call invocation} % %\paragraph{Functions} % %\begin{lstlisting}[language=c] %DCvoid dcCallVoid (DCCallVM*, DCpointer); %DCbool dcCallBool (DCCallVM*, DCpointer); %DCchar dcCallChar (DCCallVM*, DCpointer); %DCshort dcCallShort (DCCallVM*, DCpointer); %DCint dcCallInt (DCCallVM*, DCpointer); %DClong dcCallLong (DCCallVM*, DCpointer); %DClonglong dcCallLongLong(DCCallVM*, DCpointer); %DCfloat dcCallFloat (DCCallVM*, DCpointer); %DCdouble dcCallDouble (DCCallVM*, DCpointer); %DCpointer dcCallPointer (DCCallVM*, DCpointer); %DCpointer dcCallAggr(DCCallVM*, DCpointer, const DCaggr*, DCpointer); %void dcBeginCallAggr(DCCallVM*, const DCaggr*); %\end{lstlisting} % %\paragraph{Details} %Calls the function specified by \emph{funcptr} with the arguments bound to %the \emph{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 \emph{CallVM}.\\ %\\ %See the dyncall(3) manpage for more information. % %\subsection{Formatted argument binding and calls (ANSI C ellipsis interface)} % %\paragraph{Functions} % %\begin{lstlisting}[language=c] %void dcArgF (DCCallVM*, const DCsigchar*, ...); %void dcVArgF (DCCallVM*, const DCsigchar*, va_list); %void dcCallF (DCCallVM*, DCValue*, DCpointer, const DCsigchar*, ...); %void dcVCallF(DCCallVM*, DCValue*, DCpointer, const DCsigchar*, va_list); %\end{lstlisting} % %\paragraph{Details} % %These functions can be used to operate \product{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). %\capi{dcArgF()} and \capi{dcVArgF()} just bind arguments to the \capi{DCCallVM} %object, so any return value specified in the signature is ignored. \capi{dcCallF()} %and \capi{dcVCallF()} also take a function pointer to call after binding the arguments. %The return value will be stored in what \lstinline{result} points to. %For more information about the signature format, refer to \ref{sigchar}. %