Mercurial > pub > dyncall > dyncall
view doc/manual/manual_dynload_api.tex @ 533:71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
* integration of aggregate-by-value (struct, union) support patch for x64 (win and sysv)
* windows/x64 asm additions to specify how stack unwinds (help for debuggers, exception handling, etc.)
* see Changelog for details
- new calling convention modes for thiscalls (platform agnostic, was specific before)
* new signature character for platform agnostic thiscalls ('*' / DC_SIGCHAR_CC_THISCALL)
- dcCallF(), dcVCallF(), dcArgF() and dcVArgF():
* added support for aggregates-by-value (wasn't part of patch)
* change that those functions don't implicitly call dcReset() anymore, which was unflexible (breaking change)
- added macros to feature test implementation for aggregate-by-value and syscall support
- changed libdyncall_s.lib and libdyncallback_s.lib order in callback test makefiles, as some toolchains are picky about order
- doc:
* man page updates to describe aggregate interface
* manual overview changes to highlight platforms with aggregate-by-value support
- test/plain: replaced tests w/ old/stale sctruct interface with new aggregate one
author | Tassilo Philipp |
---|---|
date | Thu, 21 Apr 2022 13:35:47 +0200 |
parents | 17287342e273 |
children |
line wrap: on
line source
%////////////////////////////////////////////////////////////////////////////// % % Copyright (c) 2007-2017 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. % %////////////////////////////////////////////////////////////////////////////// \section{\product{Dynload} C library API} See the dynload(3) manpage for more information. %@@@ removed, as manpages are more precise and up to date -------------------> % %The \product{dynload} library encapsulates dynamic loading mechanisms and %gives access to functions in foreign dynamic libraries and code modules. % %\subsection{Loading code} % %\begin{lstlisting}[language=c,label=dl-load] %DLLib* dlLoadLibrary(const char* libpath); %void dlFreeLibrary(void* libhandle); %\end{lstlisting} % %\lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath} %and returns a handle to it for use in \lstinline{dlFreeLibrary} and %\lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath} %argument is valid, and returns a handle to the main executable of the calling code. %Also, searching libraries in library paths (e.g. by just passing the library's leaf %name) should work, however, they are OS specific. Returns a null pointer on error. % %\lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}. % %\subsection{Retrieving functions} % %\begin{lstlisting}[language=c] %void* dlFindSymbol(void* libhandle, const char* symbol); %\end{lstlisting} % %This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the %library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot %be found. The name is specified as it would appear in C source code (mangled if C++, etc.). % %\subsection{Misc functions} %\begin{lstlisting}[language=c] %int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize); %\end{lstlisting} % %This function can be used to get a copy of the path to the library loaded with handle %\lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size %\lstinline{bufSize} (in bytes), to hold the output string. The return value is the size %of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be %looked up. If \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the %path to the library should be in \lstinline{sOut}. If it returns 0, the library name wasn't %able to be found. Please note that this might happen in some rare cases, so make sure to always check. % %\subsection{Symbol iteration} % %\begin{lstlisting}[language=c] %DLSyms* dlSymsInit(const char* libPath); %void dlSymsCleanup(DLSyms* pSyms); %int dlSymsCount(DLSyms* pSyms); %const char* dlSymsName(DLSyms* pSyms, int index); %const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */ %\end{lstlisting} % % %These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made %for symbol name lookups, not to get a symbol's address. For that refer to %\lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer %on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary %to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with %\lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of %symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue} %are used to lookup symbol names using an index or symbol's address, respectively, %returning a null pointer on error. The names are returned as they would appear %in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue} %must point to a loaded symbol. %