Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dynload(3)	       FreeBSD Library Functions Manual		    dynload(3)

NAME
     dynload --	encapsulates dynamic loading mechanisms	and gives access to
     functions in foreign dynamic libraries and	code modules.

SYNOPSIS
     #include <dynload.h>

     DLLib *
     dlLoadLibrary(const char *	libpath);

     void
     dlFreeLibrary(DLLib * pLib);

     void *
     dlFindSymbol(DLLib	* pLib,	const char * pSymbolName);

     int
     dlGetLibraryPath(DLLib * pLib, char * sOut, int bufSize);

     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);

DESCRIPTION
     The dynload library provides an interface to load foreign dynamic li-
     braries and access	to their symbols.

     dlLoadLibrary() loads a dynamic library at	libpath	and returns a handle
     to	it for use in dlFreeLibrary() and dlFindSymbol() calls.	Passing	a null
     pointer for the 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, how-
     ever, they	are OS specific. The libPath argument is expected to be	UTF-8
     encoded. Returns a	null pointer on	error.

     dlFreeLibrary() frees the loaded library with handle pLib.

     dlFindSymbol() returns a pointer to a symbol with name pSymbolName	in the
     library with handle pLib, or returns a null pointer if the	symbol cannot
     be	found. The name	is specified as	it would appear	in C source code (man-
     gled if C++, etc.).

     dlGetLibraryPath()	can be used to get a copy of the path to the library
     loaded with handle	pLib.  The parameter sOut is a pointer to a buffer of
     size bufSize (in bytes), to hold the output string	(UTF-8 encoded). 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 bufSize >= re-
     turn value	>= 1, a	null-terminted string with the path to the library
     should be in 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. Passing a null pointer as pLib returns the path to
     the executable (not guaranteed to be absolute - if	it isn't it's relative
     to	the working directory the process was started in, not the current
     one).

     The dlSyms* 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 symbols' addresses. For that refer to dlFindSymbol().
     dlSymsInit() will return a	handle (or null	pointer	on error) to the
     shared object specified by	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 dlSymsCleanup().	 dlSymsCount() returns the
     number of symbols in the shared object, dlSymsName() and
     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 dlSymsNameFromValue()	must point to a	loaded
     symbol.

BUGS
     dlGetLibraryPath()	is not thread-safe on Darwin (macOS, iOS, ...) and
     OpenBSD.

     dlSymsInit() is not thread-safe on	Darwin.

     dlGetLibraryPath()	will not work on the following platforms when the li-
     brary in question doesn't have the	(default) _init() and _fini() symbols
     exported (rare, but possible): Haiku (all versions), OpenBSD < 3.7, Net-
     BSD < 5.1,	FreeBSD	< 4.8

     Getting the executable's path by passing NULL in pLib to
     dlGetLibraryPath()	fails on the following platforms: Haiku	(all ver-
     sions), OpenBSD < 3.7, NetBSD < 5.1, FreeBSD < 4.8

CONFORMING TO
     The dynload library conforms to c99.

SEE ALSO
     dyncall(3), dyncallback(3)	and the	dyncall	manual (available in HTML and
     PDF format) for more information.

AUTHORS
     Daniel Adler <dadler@uni-goettingen.de>
     Tassilo Philipp <tphilipp@potion-studios.com>

			       November	30, 2020

NAME | SYNOPSIS | DESCRIPTION | BUGS | CONFORMING TO | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dynload&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help