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_instance_s
	A module/inst tuple. More...

struct	dl_module_s

struct	module_detach_ctx_t

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_instance_s	dl_module_inst_t

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

typedef int(*	module_detach_t) (module_detach_ctx_t const *inst)
	Module detach callback. 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 const *	dl_module (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_conf_parse (dl_module_inst_t dl_inst, CONF_SECTION conf)

char const *	dl_module_inst_name_from_conf (CONF_SECTION *conf)
	Avoid boilerplate when setting the module instance name. More...

int	dl_module_instance (TALLOC_CTX ctx, dl_module_inst_t out, dl_module_inst_t const parent, dl_module_type_t type, char const name, char const inst_name)
	Load a module and parse its CONF_SECTION in one operation. More...

dl_module_inst_t const *	dl_module_instance_by_cs (CONF_SECTION const *cs)
	Lookup a dl_module_inst_t via a config section. More...

dl_module_inst_t const *	dl_module_instance_by_data (void const *data)
	Lookup a dl_module_inst_t via instance data. More...

char const *	dl_module_instance_name_by_data (void const *data)
	Lookup instance name via instance data. More...

void *	dl_module_instance_symbol (dl_module_inst_t const instance, char const sym_name)
	Retrieve a public symbol from a module using dlsym. More...

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

void *	dl_module_parent_data_by_child_data (void const *data)
	A convenience function for returning a parent's private data. More...

dl_module_inst_t const *	dl_module_parent_instance (dl_module_inst_t const *child)
	Lookup a module's parent. 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: 619b6a5e9bb7e92b75c07caefef4428b865be05f

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 133 of file dl_module.h.

Data Fields
	DL_MODULE_COMMON

◆ dl_module_instance_s

struct dl_module_instance_s

A module/inst tuple.

Used to pass data back from dl_module_instance_parse_func

Definition at line 162 of file dl_module.h.

Collaboration diagram for dl_module_instance_s:

Data Fields
CONF_SECTION *_CONST	conf	Module's instance configuration.
void *_CONST	data	Module instance's parsed configuration.
bool _CONST	detached	Whether the detach function has been called.
dl_module_t const *_CONST	module	Module.
char const *_CONST	name	Instance name.
dl_module_inst_t const *_CONST	parent	Parent module's instance (if any).

◆ dl_module_s

struct dl_module_s

Definition at line 142 of file dl_module.h.

Collaboration diagram for dl_module_s:

Data Fields
dl_module_common_t const *_CONST	common	Symbol exported by the module, containing its public functions, name and behaviour control flags.
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.
bool _CONST	in_tree
dl_module_t const *_CONST	parent	of this module.
dl_module_type_t _CONST	type	of this module.

◆ module_detach_ctx_t

struct module_detach_ctx_t

Definition at line 86 of file dl_module.h.

Collaboration diagram for module_detach_ctx_t:

Data Fields
dl_module_inst_t const *	inst

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;          \
                size_t                          inst_size;      \
                char const                      *inst_type;     \
                conf_parser_t const             *config;        \
                dl_module_onload_t              onload;         \
                dl_module_unload_t              unload;         \
                module_detach_t                 detach;         \
        }

Common fields for the interface struct modules export.

Definition at line 119 of file dl_module.h.

◆ DL_PRIORITY_BOOTSTRAP

#define DL_PRIORITY_BOOTSTRAP 10

Callback priority for bootstrap callback.

Definition at line 82 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 78 of file dl_module.h.

◆ DL_PRIORITY_DICT_ATTR

#define DL_PRIORITY_DICT_ATTR 29

Callback priority for attribute resolution.

Definition at line 79 of file dl_module.h.

◆ DL_PRIORITY_DICT_ENUM

#define DL_PRIORITY_DICT_ENUM 28

Callback priority for enum resolution.

Definition at line 80 of file dl_module.h.

◆ DL_PRIORITY_LIB

#define DL_PRIORITY_LIB 20

Callback priority for library config.

Definition at line 81 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 65 of file dl_module.h.

Typedef Documentation

◆ dl_module_inst_t

typedef struct dl_module_instance_s dl_module_inst_t

Definition at line 1 of file dl_module.h.

◆ 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 108 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 114 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 114 of file dl_module.h.

◆ module_detach_t

typedef int(* module_detach_t) (module_detach_ctx_t const *inst)

Module detach callback.

Is called just before the server exits, and after re-instantiation on HUP, to free the old module instance.

Detach should close all handles associated with the module instance, and free any memory allocated during instantiate.

Parameters

[in] inst to free.

Returns

0 on success.
-1 if detach failed.

Definition at line 103 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 67 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 662 of file dl_module.c.

◆ dl_module()

dl_module_t const* dl_module	(	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.

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 382 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_module_conf_parse()

int dl_module_conf_parse	(	dl_module_inst_t *	dl_inst,
		CONF_SECTION *	conf
	)

Definition at line 594 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_module_inst_name_from_conf()

char const* dl_module_inst_name_from_conf ( CONF_SECTION * conf )

Avoid boilerplate when setting the module instance name.

Definition at line 584 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_module_instance()

int dl_module_instance	(	TALLOC_CTX *	ctx,
		dl_module_inst_t **	out,
		dl_module_inst_t const *	parent,
		dl_module_type_t	type,
		char const *	mod_name,
		char const *	inst_name
	)

Load a module and parse its CONF_SECTION in one operation.

When this instance is no longer needed, it should be freed with talloc_free(). When all instances of a particular module are unloaded, the dl handle will be closed, unloading the module.

Parameters

[in]	ctx	to allocate structures in.
[out]	out	where to write our dl_module_inst_t containing the module handle and instance.
[in]	parent	of module instance.
[in]	type	of module to load.
[in]	mod_name	of the module to load .e.g. 'udp' for 'proto_radius_udp' if the parent were 'proto_radius'.
[in]	inst_name	The name of the instance .e.g. 'sql_aws_dc01'

Returns

0 on success.
-1 on failure.

Definition at line 552 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_module_instance_by_cs()

dl_module_inst_t const* dl_module_instance_by_cs ( CONF_SECTION const * cs )

Lookup a dl_module_inst_t via a config section.

Definition at line 227 of file dl_module.c.

Here is the call graph for this function:

◆ dl_module_instance_by_data()

dl_module_inst_t const* dl_module_instance_by_data ( void const * data )

Lookup a dl_module_inst_t via instance data.

Definition at line 215 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_module_instance_name_by_data()

char const* dl_module_instance_name_by_data ( void const * data )

Lookup instance name via instance data.

Definition at line 235 of file dl_module.c.

Here is the call graph for this function:

◆ dl_module_instance_symbol()

void* dl_module_instance_symbol	(	dl_module_inst_t const *	dl_inst,
		char const *	sym_name
	)

Retrieve a public symbol from a module using dlsym.

Convenience function to lookup/return public symbols from modules loaded with dl_module_instance.

Parameters

[in]	dl_inst	Instance who's module we're looking for the symbol in.
[in]	sym_name	to lookup.

Returns

Pointer to the public data structure.
- NULL if no matching symbol was found.

Definition at line 526 of file dl_module.c.

◆ 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 706 of file dl_module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dl_module_parent_data_by_child_data()

void* dl_module_parent_data_by_child_data ( void const * data )

A convenience function for returning a parent's private data.

Parameters

[in] data Private instance data for child.

Returns

Parent's private instance data.
NULL if no parent

Definition at line 252 of file dl_module.c.

Here is the call graph for this function:

◆ dl_module_parent_instance()

dl_module_inst_t const* dl_module_parent_instance ( dl_module_inst_t const * child )

Lookup a module's parent.

Definition at line 207 of file dl_module.c.

Here is the caller graph for this function:

◆ dl_module_search_path()

char const* dl_module_search_path ( void )

Definition at line 657 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 66 of file dl_module.c.

◆ dl_module_type_prefix_len

size_t dl_module_type_prefix_len

extern

Definition at line 72 of file dl_module.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dl_module_common_t

◆ dl_module_instance_s

◆ dl_module_s

◆ module_detach_ctx_t

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_inst_t

◆ dl_module_loader_t

◆ dl_module_onload_t

◆ dl_module_t

◆ dl_module_unload_t

◆ module_detach_t

Enumeration Type Documentation

◆ dl_module_type_t

Function Documentation

◆ dl_loader_from_module_loader()

◆ dl_module()

◆ dl_module_conf_parse()

◆ dl_module_inst_name_from_conf()

◆ dl_module_instance()

◆ dl_module_instance_by_cs()

◆ dl_module_instance_by_data()

◆ dl_module_instance_name_by_data()

◆ dl_module_instance_symbol()

◆ dl_module_loader_init()

◆ dl_module_parent_data_by_child_data()

◆ dl_module_parent_instance()

◆ dl_module_search_path()

Variable Documentation

◆ dl_module_type_prefix

◆ dl_module_type_prefix_len