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 <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_inst_cache_t
	Make data to instance name resolution more efficient. More...
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. More...
static int	_dl_module_instance_data_free (void *data)
static int	_dl_module_instance_free (dl_module_inst_t *dl_inst)
	Free a module instance, removing it from the instance tree. More...
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. More...
static int	dl_dict_autoload (dl_t const *module, void *symbol, void *user_ctx)
	Wrapper to log errors. More...
static int	dl_dict_enum_autoload (dl_t const *module, void *symbol, void *user_ctx)
	Wrapper to log errors. More...
dl_loader_t *	dl_loader_from_module_loader (dl_module_loader_t *dl_module_l)
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...
static int8_t	dl_module_cmp (void const *one, void const *two)
int	dl_module_conf_parse (dl_module_inst_t *dl_inst, CONF_SECTION *conf)
static void	dl_module_detach_parent (dl_module_inst_t *dl_inst)
	Detach the shallowest parent first. More...
static int8_t	dl_module_inst_data_cmp (void const *one, void const *two)
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 *mod_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...
static void	dl_module_instance_data_alloc (dl_module_inst_t *dl_inst, dl_module_t const *module)
	Allocate module instance data, and parse the module's configuration. 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 *dl_inst, 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...
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. More...
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. 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)
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. More...

Variables
static _Thread_local dl_module_inst_cache_t	dl_inst_cache
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. More...
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

11671f5e962fdb53289587721defa3607be2b2a9

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_inst_cache_t

struct dl_module_inst_cache_t

Make data to instance name resolution more efficient.

Definition at line 57 of file dl_module.c.

Collaboration diagram for dl_module_inst_cache_t:

Data Fields
void *	data	Module's data.
dl_module_inst_t *	inst	Instance wrapper struct.

dl_module_loader_s

struct dl_module_loader_s

Wrapper struct around dl_loader_t.

Provides space to store instance data.

Definition at line 46 of file dl_module.c.

Collaboration diagram for dl_module_loader_s:

Data Fields
dl_loader_t *	dl_loader
fr_rb_tree_t *	inst_data_tree
fr_rb_tree_t *	module_tree

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

Here is the call graph for this function:

_dl_module_instance_data_free()

static int _dl_module_instance_data_free ( void *  data )

static

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

static int _dl_module_instance_free ( dl_module_inst_t *  dl_inst )

static

Free a module instance, removing it from the instance tree.

Also decrements the reference count of the module potentially unloading it.

Parameters

[in]

dl_inst

to free.

Returns

0.

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

static int _dl_module_loader_free ( dl_module_loader_t *  dl_module_l )

static

Definition at line 615 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 681 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 693 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 669 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 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_cmp()

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

static

Definition at line 84 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_detach_parent()

static void dl_module_detach_parent ( dl_module_inst_t *  dl_inst )

static

Detach the shallowest parent first.

Definition at line 269 of file dl_module.c.

Here is the caller graph for this function:

dl_module_inst_data_cmp()

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

static

Definition at line 74 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_data_alloc()

static void dl_module_instance_data_alloc ( dl_module_inst_t *  dl_inst, dl_module_t const *  module  )

static

Allocate module instance data, and parse the module's configuration.

Parameters

[in]	dl_inst	to allocate this instance data in.
[in]	module	to alloc instance data for.

Definition at line 305 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_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 161 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 105 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:

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

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

dl_inst_cache

_Thread_local dl_module_inst_cache_t dl_inst_cache

static

Definition at line 62 of file dl_module.c.

dl_module_loader

dl_module_loader_t* dl_module_loader

static

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