dl_module.c File Reference

Wrappers around dlopen to manage loading modules at runtime. More...

#include <freeradius-devel/server/dl_module.h>
#include <freeradius-devel/server/log.h>
#include <freeradius-devel/server/global_lib.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/dl.h>
#include <freeradius-devel/util/syserror.h>
#include <pthread.h>
#include <ctype.h>
#include <unistd.h>

Include dependency graph for dl_module.c:

Go to the source code of this file.

Data Structures
struct	dl_module_loader_s
	Wrapper struct around dl_loader_t. More...

Macros
#define	_DL_MODULE_PRIVATE   1
#define	DL_INIT_CHECK   fr_assert(dl_module_loader)

Functions
static int	_dl_module_free (dl_module_t *dl_module)
	Decrement the reference count of the dl, eventually freeing it.
static int	_dl_module_loader_free (dl_module_loader_t *dl_module_l)
static int	dl_dict_attr_autoload (dl_t const *module, void *symbol, void *user_ctx)
	Wrapper to log errors.
static int	dl_dict_autoload (dl_t const *module, void *symbol, void *user_ctx)
	Wrapper to log errors.
static int	dl_dict_enum_autoload (dl_t const *module, void *symbol, void *user_ctx)
	Wrapper to log errors.
dl_loader_t *	dl_loader_from_module_loader (dl_module_loader_t *dl_module_l)
dl_module_t *	dl_module_alloc (dl_module_t const *parent, char const *name, dl_module_type_t type)
	Load a module library using dlopen() or return a previously loaded module from the cache.
static int8_t	dl_module_cmp (void const *one, void const *two)
int	dl_module_free (dl_module_t *dl_module)
	Free a dl_module (when there are no more references to it)
dl_module_loader_t *	dl_module_loader_init (char const *lib_dir)
	Initialise structures needed by the dynamic linker.
static int	dl_module_magic_verify (dl_module_common_t const *module)
	Check if the magic number in the module matches the one in the library.
static int	dl_module_onload_func (dl_t const *dl, UNUSED void *symbol, UNUSED void *ctx)
	Call the load() function in a module's exported structure.
static dl_module_t const *	dl_module_root (dl_module_t const *child)
	Find the module's shallowest parent, or the child if no parents are found.
static char const *	dl_module_root_prefix_str (dl_module_t const *module)
	Return the prefix string for the deepest module.
char const *	dl_module_search_path (void)
static void	dl_module_unload_func (dl_t const *dl, UNUSED void *symbol, UNUSED void *ctx)
	Call the unload() function in a module's exported structure.

Variables
static dl_module_loader_t *	dl_module_loader
fr_table_num_sorted_t const	dl_module_type_prefix []
	Name prefixes matching the types of loadable module.
size_t	dl_module_type_prefix_len = NUM_ELEMENTS(dl_module_type_prefix)

Detailed Description

Wrappers around dlopen to manage loading modules at runtime.

Id

742541762963c4cfc46f723070b93ccf301f9c36

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_module.c.

---

Data Structure Documentation

dl_module_loader_s

struct dl_module_loader_s

Wrapper struct around dl_loader_t.

Provides space to store instance data.

Definition at line 47 of file dl_module.c.

Collaboration diagram for dl_module_loader_s:

Data Fields
dl_loader_t *	dl_loader	A list of loaded libraries, and symbol to callback mappings.
pthread_mutex_t	lock	Protects the module tree when multiple threads are loading modules simultaneously.
fr_rb_tree_t *	module_tree	Module's dl handles.

Macro Definition Documentation

_DL_MODULE_PRIVATE

#define _DL_MODULE_PRIVATE   1

Definition at line 27 of file dl_module.c.

DL_INIT_CHECK

#define DL_INIT_CHECK   fr_assert(dl_module_loader)

Definition at line 41 of file dl_module.c.

Function Documentation

_dl_module_free()

static int _dl_module_free ( dl_module_t *  dl_module )

static

Decrement the reference count of the dl, eventually freeing it.

Definition at line 226 of file dl_module.c.

Here is the call graph for this function:

_dl_module_loader_free()

static int _dl_module_loader_free ( dl_module_loader_t *  dl_module_l )

static

Definition at line 432 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_dict_attr_autoload()

static int dl_dict_attr_autoload ( dl_t const *  module, void *  symbol, void *  user_ctx  )

static

Wrapper to log errors.

Definition at line 507 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_dict_autoload()

static int dl_dict_autoload ( dl_t const *  module, void *  symbol, void *  user_ctx  )

static

Wrapper to log errors.

Definition at line 519 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_dict_enum_autoload()

static int dl_dict_enum_autoload ( dl_t const *  module, void *  symbol, void *  user_ctx  )

static

Wrapper to log errors.

Definition at line 495 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_loader_from_module_loader()

dl_loader_t * dl_loader_from_module_loader

(

dl_module_loader_t *

dl_module_l

)

Definition at line 488 of file dl_module.c.

dl_module_alloc()

dl_module_t * dl_module_alloc	(	dl_module_t const *	parent,
		char const *	name,
		dl_module_type_t	type
	)

Load a module library using dlopen() or return a previously loaded module from the cache.

When the dl_module_t is no longer used, talloc_free() may be used to free it.

When all references to the original dlhandle are freed, dlclose() will be called on the dlhandle to unload the module.

Note

This function is threadsafe. Multiple callers may attempt to load the same module at the same time, and the module will only be loaded once, and will not be freed until all callers have released their references to it. This is useful for dynamic/runtime loading of modules.

Parameters

[in]	parent	The dl_module_t of the parent module, e.g. rlm_sql for rlm_sql_postgresql.
[in]	name	of the module e.g. sql for rlm_sql.
[in]	type	Used to determine module name prefixes. Must be one of: DL_MODULE_TYPE_MODULE DL_MODULE_TYPE_PROTO DL_MODULE_TYPE_SUBMODULE

Returns

• Module handle holding dlhandle, and module's public interface structure.
• NULL if module couldn't be loaded, or some other error occurred.

Definition at line 315 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_module_cmp()

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

static

Definition at line 65 of file dl_module.c.

Here is the caller graph for this function:

dl_module_free()

int dl_module_free

(

dl_module_t *

dl_module

)

Free a dl_module (when there are no more references to it)

Decrement the reference count for a module, freeing it and unloading the module if there are no more references.

Note

This must be used to free modules, not talloc_free().

Returns

• 0 on success.
• -1 if the module wasn't freed. This likely means there are more ferences held to it.

Definition at line 281 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_module_loader_init()

dl_module_loader_t * dl_module_loader_init

(

char const *

lib_dir

)

Initialise structures needed by the dynamic linker.

Definition at line 532 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_module_magic_verify()

static int dl_module_magic_verify ( dl_module_common_t const *  module )

static

Check if the magic number in the module matches the one in the library.

This is used to detect potential ABI issues caused by running with modules which were built for a different version of the server.

Parameters

[in]

module

Common fields from module's exported interface struct.

Returns

• 0 on success.
• -1 if prefix mismatch.
• -2 if version mismatch.
• -3 if commit mismatch.

Definition at line 180 of file dl_module.c.

dl_module_onload_func()

static int dl_module_onload_func ( dl_t const *  dl, UNUSED void *  symbol, UNUSED void *  ctx  )

static

Call the load() function in a module's exported structure.

Parameters

[in]	dl	to call the load function for.
[in]	symbol	UNUSED.
[in]	ctx	UNUSED.

Returns

• 0 on success.
• -1 on failure.

Definition at line 124 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_module_root()

static dl_module_t const * dl_module_root ( dl_module_t const *  child )

static

Find the module's shallowest parent, or the child if no parents are found.

Parameters

[in]

child

to locate the root for.

Returns

• The module's shallowest parent.
• NULL on error.

Definition at line 84 of file dl_module.c.

Here is the caller graph for this function:

dl_module_root_prefix_str()

static char const * dl_module_root_prefix_str ( dl_module_t const *  module )

inlinestatic

Return the prefix string for the deepest module.

This is useful for submodules which don't have a prefix of their own. In this case we need to use the prefix of the shallowest module, which will be a proto or rlm module.

Parameters

[in]

module

to get the prefix for.

Returns

The prefix string for the shallowest module.

Definition at line 108 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_module_search_path()

char const * dl_module_search_path

(

void

)

Definition at line 483 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

dl_module_unload_func()

static void dl_module_unload_func ( dl_t const *  dl, UNUSED void *  symbol, UNUSED void *  ctx  )

static

Call the unload() function in a module's exported structure.

Parameters

[in]	dl	to call the unload function for.
[in]	symbol	UNUSED.
[in]	ctx	UNUSED.

Definition at line 157 of file dl_module.c.

Here is the caller graph for this function:

Variable Documentation

dl_module_loader

dl_module_loader_t* dl_module_loader

static

Definition at line 53 of file dl_module.c.

dl_module_type_prefix

fr_table_num_sorted_t const dl_module_type_prefix[]

Initial value:

= {
        { L(""),        DL_MODULE_TYPE_SUBMODULE        },
        { L("process"), DL_MODULE_TYPE_PROCESS          },
        { L("proto"),   DL_MODULE_TYPE_PROTO            },
        { L("rlm"),     DL_MODULE_TYPE_MODULE           }
}

Name prefixes matching the types of loadable module.

Definition at line 57 of file dl_module.c.

dl_module_type_prefix_len

size_t dl_module_type_prefix_len = NUM_ELEMENTS(dl_module_type_prefix)

Definition at line 63 of file dl_module.c.