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

FreeBSD Manual Pages

  
 
  

home | help 
AG_DSO(3)		    Library Functions Manual		     AG_DSO(3)

NAME
       AG_DSO -- agar portable dynamic linker interface

SYNOPSIS
       #include	<agar/core.h>

DESCRIPTION
       AG_DSO  provides	a cross-platform interface for loading code from a dy-
       namic library file into the current process's address space,  resolving
       symbols defined by the library, and unloading the library.

INTERFACE
       AG_DSO *	AG_LoadDSO(const char *name, const char	*path, Uint flags)

       int AG_SymDSO(AG_DSO *dso, const	char *symbol, void **rv)

       void AG_LockDSO(void)

       void AG_UnlockDSO(void)

       int AG_UnloadDSO(AG_DSO *dso)

       AG_DSO *	AG_LookupDSO(const char	*name)

       The  AG_LoadDSO()  function loads the dynamic library file at path into
       the current process's address space.  If	the library has	 already  been
       loaded,	the  existing  AG_DSO  structure is returned and its reference
       count incremented.  name	is a string identifier for the library for use
       by the AG_Object(3) system independently	of the file location.  If  the
       library	was loaded successfully, a pointer to the new AG_DSO structure
       is returned.  If	an error has occurred return NULL with an  error  mes-
       sage.

       The  AG_SymDSO()	 function  tries to resolve the	named symbol.  If suc-
       cessful,	the value is returned into rv and 0 is	returned.   Otherwise,
       -1  is  returned	and an error message is	set.  Under threads, the value
       returned	into rv	remains	valid as long as AG_LockDSO()  is  in  effect.
       AG_SymDSO()  automatically  prepends an underscore to the symbol	if re-
       quired.

       AG_LockDSO() and	AG_UnlockDSO() acquire and release the lock protecting
       the list	of loaded libraries and	their  resolved	 symbols.   In	multi-
       threaded	 applications  requiring  the ability to unload	modules, it is
       not safe	to reference resolved symbols without acquiring	this lock.

       The AG_UnloadDSO() function decrements the reference count of the spec-
       ified AG_DSO object.  If	it reaches zero, the library is	 removed  from
       the process's address space.

       AG_LookupDSO() searches the list	of currently loaded DSOs by the	speci-
       fied name.  If no match is found, NULL is returned.

STRUCTURE DATA
       For the AG_DSO structure:

       char name[AG_DSO_NAME_MAX]   Platform-independent name for this module.
       char path[AG_PATHNAME_MAX]   Full path to dynamic library file.
       TAILQ(AG_DSOSym)	syms	    List of previously resolved	symbols

       For the AG_DSOSym structure:

       char *sym  Symbol name
       char *p	  Resolved address

EXAMPLES
       The following code fragments loads a DSO	and resolves a symbol from it:

	     AG_DSO *dso;
	     void *pMySymbol;

	     if	((dso =	AG_LoadDSO("my_dso", 0)) == NULL) {
		     AG_FatalError();
	     }
	     if	(AG_SymDSO(dso,	"my_symbol", &pMySymbol) == 0) {
		     Verbose("Resolved \"my_symbol\" address: %p\n",
			 pMySymbol);
	     } else {
		     Verbose("Could not	resolve	\"my_symbol\"\n");
	     }
	     AG_UnloadDSO(dso);

SEE ALSO
       AG_DataSource(3), AG_Intro(3)

HISTORY
       The AG_DSO interface first appeared in Agar 1.3.3.

Agar 1.7		       December	21, 2022		     AG_DSO(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_DSO&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help