The FreeRADIUS server  $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
dl_module.h File Reference

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_tdl_loader_from_module_loader (dl_module_loader_t *dl_module_loader)
 
dl_module_tdl_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_tdl_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
a964289e86fedacdc49444884ccca8e838c5ff2b

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 const *_CONST 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; \
}
static char const * name

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

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

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]parentThe dl_module_t of the parent module, e.g. rlm_sql for rlm_sql_postgresql.
[in]nameof the module e.g. sql for rlm_sql.
[in]typeUsed 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.