Wrappers around dlopen. More...

#include <freeradius-devel/util/dlist.h>
#include <freeradius-devel/util/rb.h>
#include <freeradius-devel/util/talloc.h>
#include <freeradius-devel/util/version.h>
#include <stdbool.h>

Include dependency graph for dl.h:

Go to the source code of this file.

Data Structures
struct	dl_s
	Module handle. More...

Macros
#define	DL_EXTENSION ".so"

Typedefs
typedef struct dl_loader_s	dl_loader_t

typedef int(*	dl_onload_t) (dl_t const module, void symbol, void *user_ctx)
	Callback to call when a module is first loaded. More...

typedef struct dl_s	dl_t
	Module handle. More...

typedef void(*	dl_unload_t) (dl_t const module, void symbol, void *user_ctx)
	Callback when a module is destroyed. More...

Functions
dl_t *	dl_by_name (dl_loader_t dl_loader, char const name, void *uctx, bool uctx_free))
	Search for a dl's shared object in various locations. More...

int	dl_free (dl_t const *dl)
	"free" a dl handle, possibly actually freeing it, and unloading the library More...

void	dl_loader_debug (dl_loader_t *dl)
	Called from a debugger to print information about a dl_loader. More...

dl_loader_t *	dl_loader_init (TALLOC_CTX ctx, void uctx, bool uctx_free, bool defer_symbol_init)
	Initialise structures needed by the dynamic linker. More...

bool	dl_loader_set_static (dl_loader_t *dl_loader, bool do_static)
	Runtime override for doing static or dynamic module loading. More...

void *	dl_loader_uctx (dl_loader_t *dl_loader)
	Retrieve the uctx from a dl_loader. More...

void *	dl_open_by_sym (char const *sym_name, int flags)
	Utility function to dlopen the library containing a particular symbol. More...

int	dl_search_global_path_set (char const *lib_dir)
	Set the global library path. More...

char const *	dl_search_path (dl_loader_t *dl_loader)
	Return current library path. More...

int	dl_search_path_append (dl_loader_t dl_loader, char const lib_dir)
	Append a new search path component to the library search path. More...

int	dl_search_path_prepend (dl_loader_t dl_loader, char const lib_dir)
	Append a new search path component to the library search path. More...

int	dl_search_path_set (dl_loader_t dl_loader, char const lib_dir)
	Set the current library path. More...

int	dl_symbol_free_cb_register (dl_loader_t dl_loader, unsigned int priority, char const symbol, dl_unload_t func, void *ctx)
	Register a callback to execute when a dl with a particular symbol is unloaded. More...

void	dl_symbol_free_cb_unregister (dl_loader_t dl_loader, char const symbol, dl_unload_t func)
	Unregister an callback that was to be executed when a dl was unloaded. More...

int	dl_symbol_init (dl_loader_t dl_loader, dl_t const dl)
	Walk over the registered init callbacks, searching for the symbols they depend on. More...

int	dl_symbol_init_cb_register (dl_loader_t dl_loader, unsigned int priority, char const symbol, dl_onload_t func, void *ctx)
	Register a callback to execute when a dl with a particular symbol is first loaded. More...

void	dl_symbol_init_cb_unregister (dl_loader_t dl_loader, char const symbol, dl_onload_t func)
	Unregister an callback that was to be executed when a dl was first loaded. More...

Detailed Description

Wrappers around dlopen.

Id: 7ab8dc5798d5af68d350a761ceea9882bcd3e355

Copyright: 2016 The FreeRADIUS server project

Definition in file dl.h.

Data Structure Documentation

◆ dl_s

struct dl_s

Module handle.

Contains module's dlhandle, and the functions it exports.

Definition at line 58 of file dl.h.

Collaboration diagram for dl_s:

Data Fields
void *	handle	Handle returned by dlopen.
bool	in_tree	Whether this dl is registered in the dl_tree.
dl_loader_t *	loader	Loader that owns this dl.
char const *	name	Name of the module e.g. sql.
fr_rb_node_t	node	Entry in the rbtree module handles.
void *	uctx	API client's opaque data.
bool	uctx_free	Free opaque data on dl_t free (usually false).

Macro Definition Documentation

◆ DL_EXTENSION

#define DL_EXTENSION ".so"

Definition at line 49 of file dl.h.

Typedef Documentation

◆ dl_loader_t

typedef struct dl_loader_s dl_loader_t

Definition at line 1 of file dl.h.

◆ dl_onload_t

typedef int(* dl_onload_t) (dl_t const *module, void *symbol, void *user_ctx)

Callback to call when a module is first loaded.

Parameters

[in]	module	being loaded.
[in]	symbol	which, if present, will trigger this callback.
[in]	user_ctx	passed to dl_loader_init_register.

Returns

0 on success.
-1 on failure

Definition at line 79 of file dl.h.

◆ dl_t

typedef struct dl_s dl_t

Module handle.

Contains module's dlhandle, and the functions it exports.

◆ dl_unload_t

typedef void(* dl_unload_t) (dl_t const *module, void *symbol, void *user_ctx)

Callback when a module is destroyed.

Parameters

[in]	module	being loaded.
[in]	symbol	which, if present, will trigger this callback.
[in]	user_ctx	passed to dl_loader_init_register

Definition at line 88 of file dl.h.

Function Documentation

◆ dl_by_name()

dl_t* dl_by_name	(	dl_loader_t *	dl_loader,
		char const *	name,
		void *	uctx,
		bool	uctx_free
	)

Search for a dl's shared object in various locations.

Note: You must call dl_symbol_init when ready to call autoloader callbacks.

Parameters

[in]	dl_loader	Tree of dynamically loaded libraries, and callbacks.
[in]	name	of library to load. May be a relative path.
[in]	uctx	Data to store within the dl_t.
[in]	uctx_free	talloc_free the passed in uctx data if this dl_t is freed.

Returns

A new dl_t on success, or a pointer to an existing one with the reference count increased.
NULL on error.

Definition at line 470 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_free()

int dl_free ( dl_t const * dl )

"free" a dl handle, possibly actually freeing it, and unloading the library

This function should be used to explicitly free a dl.

Because dls are reference counted, it may not actually free the memory or unload the library, but it will reduce the reference count.

Returns

0 if the dl was actually freed.
>0 the number of remaining references.

Definition at line 678 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_loader_debug()

void dl_loader_debug ( dl_loader_t * dl )

Called from a debugger to print information about a dl_loader.

Definition at line 962 of file dl.c.

◆ dl_loader_init()

dl_loader_t* dl_loader_init	(	TALLOC_CTX *	ctx,
		void *	uctx,
		bool	uctx_free,
		bool	defer_symbol_init
	)

Initialise structures needed by the dynamic linker.

Parameters

[in]	ctx	To bind lifetime of dl_loader_t too.
[in]	uctx	API client opaque data to store in dl_loader_t.
[in]	uctx_free	Call talloc_free() on uctx when the dl_loader_t is freed.
[in]	defer_symbol_init	If true, it is up to the caller to call dl_symbol_init after calling dl_by_name. This prevents any of the registered callbacks from executing until dl_symbol_init is called explicitly.

Definition at line 885 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_loader_set_static()

bool dl_loader_set_static	(	dl_loader_t *	dl_loader,
		bool	do_static
	)

Runtime override for doing static or dynamic module loading.

Parameters

[in]	dl_loader	to configure.
[in]	do_static	If true, all dlopen calls result in a reference to RTLD_DEFAULT being returned which allows all the dynamic loading infrastructure to worth correctly with a monolithic binary.

Returns: The previous value of do_static

Definition at line 950 of file dl.c.

◆ dl_loader_uctx()

void* dl_loader_uctx ( dl_loader_t * dl_loader )

Retrieve the uctx from a dl_loader.

Definition at line 868 of file dl.c.

◆ dl_open_by_sym()

void* dl_open_by_sym	(	char const *	sym_name,
		int	flags
	)

Utility function to dlopen the library containing a particular symbol.

Note: Not really part of our 'dl' API, just a convenience function.

Parameters

[in]	sym_name	to resolve.
[in]	flags	to pass to dlopen.

Returns

NULL on error.
A new handle on success.

Definition at line 186 of file dl.c.

Here is the caller graph for this function:

◆ dl_search_global_path_set()

int dl_search_global_path_set ( char const * lib_dir )

Set the global library path.

Parameters

[in] lib_dir ":" separated list of paths to search for libraries in.

Returns

0 on success.
-1 on failure.

Definition at line 768 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_search_path()

char const* dl_search_path ( dl_loader_t * dl_loader )

Return current library path.

Definition at line 729 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_search_path_append()

int dl_search_path_append	(	dl_loader_t *	dl_loader,
		char const *	lib_dir
	)

Append a new search path component to the library search path.

Parameters

[in]	dl_loader	to add search path component for.
[in]	lib_dir	to add. Does not require a ":" prefix.

Returns

0 on success.
-1 on failure.

Definition at line 843 of file dl.c.

◆ dl_search_path_prepend()

int dl_search_path_prepend	(	dl_loader_t *	dl_loader,
		char const *	lib_dir
	)

Append a new search path component to the library search path.

Parameters

[in]	dl_loader	to add search path component for.
[in]	lib_dir	to add. Does not require a ":" prefix.

Returns

0 on success.
-1 on failure.

Definition at line 813 of file dl.c.

Here is the caller graph for this function:

◆ dl_search_path_set()

int dl_search_path_set	(	dl_loader_t *	dl_loader,
		char const *	lib_dir
	)

Set the current library path.

Parameters

[in]	dl_loader	to add search path component for.
[in]	lib_dir	A ":" separated list of paths to search for libraries in.

Definition at line 788 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_symbol_free_cb_register()

int dl_symbol_free_cb_register	(	dl_loader_t *	dl_loader,
		unsigned int	priority,
		char const *	symbol,
		dl_unload_t	func,
		void *	uctx
	)

Register a callback to execute when a dl with a particular symbol is unloaded.

Note: Will replace ctx data for callbacks with the same symbol/func.

Parameters

[in]	dl_loader	Tree of dynamically loaded libraries, and callbacks.
[in]	priority	Execution priority. Callbacks with a higher priority get called first.
[in]	symbol	that determines whether func should be called. "<modname>_" is added as a prefix to the symbol. The prefix is added because some dls are loaded with RTLD_GLOBAL into the global symbol space, so the symbols they export must be unique. May be NULL to always call the function.
[in]	func	to register. Called then dl is unloaded.
[in]	uctx	to pass to func.

Returns

0 on success (or already registered).
-1 on failure.

Definition at line 384 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_symbol_free_cb_unregister()

void dl_symbol_free_cb_unregister	(	dl_loader_t *	dl_loader,
		char const *	symbol,
		dl_unload_t	func
	)

Unregister an callback that was to be executed when a dl was unloaded.

Parameters

[in]	dl_loader	Tree of dynamically loaded libraries, and callbacks.
[in]	symbol	the callback is attached to.
[in]	func	the callback.

Definition at line 419 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_symbol_init()

int dl_symbol_init	(	dl_loader_t *	dl_loader,
		dl_t const *	dl
	)

Walk over the registered init callbacks, searching for the symbols they depend on.

Allows code outside of the dl API to register initialisation functions that get executed depending on whether the dl exports a particular symbol.

This cuts down the amount of boilerplate code in 'mod_load' functions.

Parameters

[in]	dl_loader	Tree of dynamically loaded libraries, and callbacks.
[in]	dl	to search for symbols in.

Returns

0 continue walking.
-1 error.

Definition at line 233 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_symbol_init_cb_register()

int dl_symbol_init_cb_register	(	dl_loader_t *	dl_loader,
		unsigned int	priority,
		char const *	symbol,
		dl_onload_t	func,
		void *	uctx
	)

Register a callback to execute when a dl with a particular symbol is first loaded.

Note: Will replace ctx data for callbacks with the same symbol/func.

Parameters

[in]	dl_loader	Tree of dynamically loaded libraries, and callbacks.
[in]	priority	Execution priority. Callbacks with a higher priority get called first.
[in]	symbol	that determines whether func should be called. "<modname>_" is added as a prefix to the symbol. The prefix is added because some dls are loaded with RTLD_GLOBAL into the global symbol space, so the symbols they export must be unique. May be NULL to always call the function.
[in]	func	to register. Called when dl is loaded.
[in]	uctx	to pass to func.

Returns

0 on success (or already registered).
-1 on failure.

Definition at line 321 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_symbol_init_cb_unregister()

void dl_symbol_init_cb_unregister	(	dl_loader_t *	dl_loader,
		char const *	symbol,
		dl_onload_t	func
	)

Unregister an callback that was to be executed when a dl was first loaded.

Parameters

[in]	dl_loader	Tree of dynamically loaded libraries, and callbacks.
[in]	symbol	the callback is attached to.
[in]	func	the callback.

Definition at line 355 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ dl_s

Macro Definition Documentation

◆ DL_EXTENSION

Typedef Documentation

◆ dl_loader_t

◆ dl_onload_t

◆ dl_t

◆ dl_unload_t

Function Documentation

◆ dl_by_name()

◆ dl_free()

◆ dl_loader_debug()

◆ dl_loader_init()

◆ dl_loader_set_static()

◆ dl_loader_uctx()

◆ dl_open_by_sym()

◆ dl_search_global_path_set()

◆ dl_search_path()

◆ dl_search_path_append()

◆ dl_search_path_prepend()

◆ dl_search_path_set()

◆ dl_symbol_free_cb_register()

◆ dl_symbol_free_cb_unregister()

◆ dl_symbol_init()

◆ dl_symbol_init_cb_register()

◆ dl_symbol_init_cb_unregister()