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

#include <freeradius-devel/server/cf_parse.h>
#include <freeradius-devel/util/dl.h>
#include <freeradius-devel/util/rb.h>
#include <freeradius-devel/util/version.h>

Include dependency graph for dl_module.h:

Go to the source code of this file.

Data Structures
struct	dl_module_common_t
	Fields common to all types of loadable modules. More...

struct	dl_module_s

Macros
#define	_CONST const

#define	DL_EXTENSION ".so"

#define	DL_MODULE_COMMON
	Common fields for the interface struct modules export. More...

#define	DL_PRIORITY_BOOTSTRAP 10
	Callback priority for bootstrap callback. More...

#define	DL_PRIORITY_DICT 30
	Callback priorities. More...

#define	DL_PRIORITY_DICT_ATTR 29
	Callback priority for attribute resolution. More...

#define	DL_PRIORITY_DICT_ENUM 28
	Callback priority for enum resolution. More...

#define	DL_PRIORITY_LIB 20
	Callback priority for library config. More...

#define	MODULE_MAGIC_INIT RADIUSD_MAGIC_NUMBER
	Stop people using different module/library/server versions together. More...

Typedefs
typedef struct dl_module_loader_s	dl_module_loader_t

typedef int(*	dl_module_onload_t) (void)
	Callback to call when a module is first loaded. More...

typedef struct dl_module_s	dl_module_t
	Module handle. More...

typedef void(*	dl_module_unload_t) (void)
	Callback when a module is destroyed. More...

Enumerations
enum	dl_module_type_t { DL_MODULE_TYPE_MODULE = 0 , DL_MODULE_TYPE_PROTO , DL_MODULE_TYPE_PROCESS , DL_MODULE_TYPE_SUBMODULE }

Functions
dl_loader_t *	dl_loader_from_module_loader (dl_module_loader_t *dl_module_loader)

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. More...

int	dl_module_free (dl_module_t *dl_module)
	Free a dl_module (when there are no more references to it) More...

dl_module_loader_t *	dl_module_loader_init (char const *lib_dir)
	Initialise structures needed by the dynamic linker. More...

char const *	dl_module_search_path (void)

Variables
fr_table_num_sorted_t const	dl_module_type_prefix []
	Name prefixes matching the types of loadable module. More...

size_t	dl_module_type_prefix_len

Detailed Description

Wrappers around dlopen to manage loading modules at runtime.

Id: edfd9405472ea657c557139f2c8791fd1dc62b9c

Copyright: 2016-2019 The FreeRADIUS server project

Definition in file dl_module.h.

Data Structure Documentation

◆ dl_module_common_t

struct dl_module_common_t

Fields common to all types of loadable modules.

Definition at line 108 of file dl_module.h.

Data Fields
	DL_MODULE_COMMON

◆ dl_module_s

struct dl_module_s

Definition at line 117 of file dl_module.h.

Collaboration diagram for dl_module_s:

Data Fields
CONF_SECTION *_CONST	conf	The module's global configuration (as opposed to the instance, configuration). May be NULL.
dl_t *_CONST	dl	Dynamic loader handle.
dl_module_common_t *	exported	Symbol exported by the module, containing its public functions, name and behaviour control flags.
bool _CONST	in_tree
dl_module_loader_t *_CONST	loader	Loader that owns this dl.
char const *_CONST	name	Name of the module. The name passed to dl_module_alloc.
dl_module_t const *_CONST	parent	of this module.
unsigned int	refs	Number of references to this module. This is maintained as a separate counter (instead of using talloc refs) because it needs to be thread safe. The talloc code accesses the chunk after calling the destructor, so we can't lock the loader mutex inside the destructor and expect things to work correctly.
dl_module_type_t _CONST	type	of this module.

Macro Definition Documentation

◆ _CONST

#define _CONST const

Definition at line 47 of file dl_module.h.

◆ DL_EXTENSION

#define DL_EXTENSION ".so"

Definition at line 57 of file dl_module.h.

◆ DL_MODULE_COMMON

#define DL_MODULE_COMMON

Value:

        struct { \
                uint64_t                        magic;          \
                char const                      *name;          \
                dl_module_onload_t              onload;         \
                dl_module_unload_t              unload;         \
        }

Common fields for the interface struct modules export.

These are just enough for the loader to be able to load and unload the module.

Definition at line 98 of file dl_module.h.

◆ DL_PRIORITY_BOOTSTRAP

#define DL_PRIORITY_BOOTSTRAP 10

Callback priority for bootstrap callback.

Definition at line 80 of file dl_module.h.

◆ DL_PRIORITY_DICT

#define DL_PRIORITY_DICT 30

Callback priorities.

The higher the priority, the earlier in callback gets called. Callback priority for dictionary autoloading

Definition at line 76 of file dl_module.h.

◆ DL_PRIORITY_DICT_ATTR

#define DL_PRIORITY_DICT_ATTR 29

Callback priority for attribute resolution.

Definition at line 77 of file dl_module.h.

◆ DL_PRIORITY_DICT_ENUM

#define DL_PRIORITY_DICT_ENUM 28

Callback priority for enum resolution.

Definition at line 78 of file dl_module.h.

◆ DL_PRIORITY_LIB

#define DL_PRIORITY_LIB 20

Callback priority for library config.

Definition at line 79 of file dl_module.h.

◆ MODULE_MAGIC_INIT

#define MODULE_MAGIC_INIT RADIUSD_MAGIC_NUMBER

Stop people using different module/library/server versions together.

Definition at line 63 of file dl_module.h.

Typedef Documentation

◆ dl_module_loader_t

typedef struct dl_module_loader_s dl_module_loader_t

Definition at line 1 of file dl_module.h.

◆ dl_module_onload_t

typedef int(* dl_module_onload_t) (void)

Callback to call when a module is first loaded.

Definition at line 87 of file dl_module.h.

◆ dl_module_t

typedef struct dl_module_s dl_module_t

Module handle.

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

Definition at line 92 of file dl_module.h.

◆ dl_module_unload_t

typedef void(* dl_module_unload_t) (void)

Callback when a module is destroyed.

Definition at line 92 of file dl_module.h.

Enumeration Type Documentation

◆ dl_module_type_t

enum dl_module_type_t

Enumerator
DL_MODULE_TYPE_MODULE	Standard loadable module.
DL_MODULE_TYPE_PROTO	Protocol module.
DL_MODULE_TYPE_PROCESS	protocol processor.
DL_MODULE_TYPE_SUBMODULE	Driver (or method in the case of EAP)

Definition at line 65 of file dl_module.h.

Function Documentation

◆ dl_loader_from_module_loader()

dl_loader_t* dl_loader_from_module_loader ( dl_module_loader_t * dl_module_loader )

Definition at line 486 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_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 530 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 481 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ dl_module_type_prefix

fr_table_num_sorted_t const dl_module_type_prefix[]

extern

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

extern

Definition at line 63 of file dl_module.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dl_module_common_t

◆ dl_module_s

Macro Definition Documentation

◆ _CONST

◆ DL_EXTENSION

◆ DL_MODULE_COMMON

◆ DL_PRIORITY_BOOTSTRAP

◆ DL_PRIORITY_DICT

◆ DL_PRIORITY_DICT_ATTR

◆ DL_PRIORITY_DICT_ENUM

◆ DL_PRIORITY_LIB

◆ MODULE_MAGIC_INIT

Typedef Documentation

◆ dl_module_loader_t

◆ dl_module_onload_t

◆ dl_module_t

◆ dl_module_unload_t

Enumeration Type Documentation

◆ dl_module_type_t

Function Documentation

◆ dl_loader_from_module_loader()

◆ dl_module_alloc()

◆ dl_module_free()

◆ dl_module_loader_init()

◆ dl_module_search_path()

Variable Documentation

◆ dl_module_type_prefix

◆ dl_module_type_prefix_len