view release on metacpan or  search on metacpan

dyncall/doc/manual/manual_dyncall_api.tex  view on Meta::CPAN

%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007,2010-2022 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.\\