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 dynamic
     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 incre-
     mented.  name is a string identifier for the library for use by the  AG_Ob-
     ject(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 message.

     The AG_SymDSO() function tries to resolve the named symbol.  If successful,
     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 re-
     mains valid as long as AG_LockDSO() is in	effect.   AG_SymDSO()  automati-
     cally prepends an underscore to the symbol if required.

     AG_LockDSO() and AG_UnlockDSO() acquire and release the lock protecting the
     list  of loaded libraries and their resolved symbols.  In multithreaded ap-
     plications requiring the ability to unload modules, it is not safe to  ref-
     erence resolved symbols without acquiring this lock.

     The AG_UnloadDSO() function decrements the reference count of the specified
     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  specified
     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+15.1.quarterly>

home | help