Wrappers around dlopen to manage loading shared objects at runtime. More...

#include <freeradius-devel/server/dl_module.h>
#include <freeradius-devel/server/log.h>
#include <freeradius-devel/util/atexit.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/paths.h>
#include <freeradius-devel/util/syserror.h>

Include dependency graph for dl.c:

Go to the source code of this file.

Data Structures
struct	dl_loader_s
	A dynamic loader. More...

struct	dl_symbol_free_s

struct	dl_symbol_init_s

Macros
#define	RTLD_LOCAL (0)

#define	RTLD_NOW (0)

#define	RUNNING_ON_VALGRIND 0

Typedefs
typedef struct dl_symbol_free_s	dl_symbol_free_t
	Symbol dependent free callback.

typedef struct dl_symbol_init_s	dl_symbol_init_t
	Symbol dependent initialisation callback.

Functions
static int	_dl_free (dl_t *dl)
	Free a dl.

static int	_dl_loader_free (dl_loader_t *dl_loader)

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.

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

static int8_t	dl_handle_cmp (void const one, void const two)
	Compare the name of two dl_t.

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

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.

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

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

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

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

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

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.

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.

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

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

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.

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.

static int8_t	dl_symbol_free_cmp (void const one, void const two)

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.

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.

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.

static int8_t	dl_symbol_init_cmp (void const one, void const two)

Variables
static char *	dl_global_libdir = NULL
	Global search path, prepended all dlopen paths.

Detailed Description

Wrappers around dlopen to manage loading shared objects at runtime.

Id: 37717f9f82c82f4dbd6ede12de7e9f66a357e939

Copyright: 2016-2019 The FreeRADIUS server project; 2016-2019 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

Definition in file dl.c.

Data Structure Documentation

◆ dl_loader_s

struct dl_loader_s

A dynamic loader.

Definition at line 81 of file dl.c.

Collaboration diagram for dl_loader_s:

Data Fields
bool	defer_symbol_init	Do not call dl_symbol_init in dl_loader_init.
bool	do_dlclose	dlclose modules when we're done with them.
bool	do_static	Do all symbol resolution using the special RTLD_DEFAULT handle, instead of attempting to load modules using dlopen(). This is useful when FreeRADIUS has been built as a monolithic binary.
char *	lib_dir	Where the libraries live.
fr_dlist_head_t	sym_free	Linked list of symbol free callbacks. Note Is linked list to retain insertion order. We don't expect huge numbers of callbacks so there shouldn't be efficiency issues.
fr_dlist_head_t	sym_init	Linked list of symbol init callbacks. Note Is linked list to retain insertion order. We don't expect huge numbers of callbacks so there shouldn't be efficiency issues.
fr_rb_tree_t *	tree	Tree of shared objects loaded.
void *	uctx	dl private extension data.
bool	uctx_free	Free uctx when dl_loader_t is freed.

◆ dl_symbol_free_s

struct dl_symbol_free_s

Definition at line 69 of file dl.c.

Collaboration diagram for dl_symbol_free_s:

Data Fields
fr_dlist_t	entry	Entry into the list of 'free' symbol callbacks.
dl_unload_t	func	to call when symbol is found in a dl's symbol table.
unsigned int	priority	Call priority.
char const *	symbol	to search for. May be NULL in which case func is always called.
void *	uctx	User data to pass to func.

◆ dl_symbol_init_s

struct dl_symbol_init_s

Definition at line 55 of file dl.c.

Collaboration diagram for dl_symbol_init_s:

Data Fields
fr_dlist_t	entry	Entry into the list of 'init' symbol callbacks.
dl_onload_t	func	to call when symbol is found in a dl's symbol table.
unsigned int	priority	Call priority.
char const *	symbol	to search for. May be NULL in which case func is always called.
void *	uctx	User data to pass to func.

Macro Definition Documentation

◆ RTLD_LOCAL

#define RTLD_LOCAL (0)

Definition at line 47 of file dl.c.

◆ RTLD_NOW

#define RTLD_NOW (0)

Definition at line 44 of file dl.c.

◆ RUNNING_ON_VALGRIND

#define RUNNING_ON_VALGRIND 0

Definition at line 40 of file dl.c.

Typedef Documentation

◆ dl_symbol_free_t

typedef struct dl_symbol_free_s dl_symbol_free_t

Symbol dependent free callback.

Call this function before the dl is unloaded.

Definition at line 68 of file dl.c.

◆ dl_symbol_init_t

typedef struct dl_symbol_init_s dl_symbol_init_t

Symbol dependent initialisation callback.

Call this function when the dl is loaded for the first time.

Definition at line 54 of file dl.c.

Function Documentation

◆ _dl_free()

static int _dl_free ( dl_t * dl )

static

Free a dl.

Close dl's dlhandle, unloading it.

Parameters

[in] dl to close.

Returns: 0.

Definition at line 437 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _dl_loader_free()

static int _dl_loader_free ( dl_loader_t * dl_loader )

static

Definition at line 685 of file dl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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_handle_cmp()

static int8_t dl_handle_cmp	(	void const *	one,
		void const *	two
	)

static

Compare the name of two dl_t.

Definition at line 168 of file dl.c.

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

static int dl_symbol_free	(	dl_loader_t *	dl_loader,
		dl_t const *	dl
	)

static

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

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

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

Parameters

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

Definition at line 279 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_free_cmp()

static int8_t dl_symbol_free_cmp	(	void const *	one,
		void const *	two
	)

static

Definition at line 142 of file dl.c.

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:

◆ dl_symbol_init_cmp()

static int8_t dl_symbol_init_cmp	(	void const *	one,
		void const *	two
	)

static

Definition at line 119 of file dl.c.

Here is the caller graph for this function:

Variable Documentation

◆ dl_global_libdir

char* dl_global_libdir = NULL

static

Global search path, prepended all dlopen paths.

Definition at line 117 of file dl.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dl_loader_s

◆ dl_symbol_free_s

◆ dl_symbol_init_s

Macro Definition Documentation

◆ RTLD_LOCAL

◆ RTLD_NOW

◆ RUNNING_ON_VALGRIND

Typedef Documentation

◆ dl_symbol_free_t

◆ dl_symbol_init_t

Function Documentation

◆ _dl_free()

◆ _dl_loader_free()

◆ dl_by_name()

◆ dl_free()

◆ dl_handle_cmp()

◆ 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()

◆ dl_symbol_free_cb_register()

◆ dl_symbol_free_cb_unregister()

◆ dl_symbol_free_cmp()

◆ dl_symbol_init()

◆ dl_symbol_init_cb_register()

◆ dl_symbol_init_cb_unregister()

◆ dl_symbol_init_cmp()

Variable Documentation

◆ dl_global_libdir