libkmod-module

libkmod-module — operate on kernel modules

Functions

int kmod_module_new_from_lookup ()
int kmod_module_new_from_name_lookup ()
int kmod_module_new_from_name ()
int kmod_module_new_from_path ()
struct kmod_module * kmod_module_ref ()
struct kmod_module * kmod_module_unref ()
int kmod_module_unref_list ()
int kmod_module_insert_module ()
int kmod_module_probe_insert_module ()
int kmod_module_remove_module ()
struct kmod_module * kmod_module_get_module ()
struct kmod_list * kmod_module_get_dependencies ()
int kmod_module_get_softdeps ()
int kmod_module_get_weakdeps ()
int kmod_module_apply_filter ()
int kmod_module_get_filtered_blacklist ()
const char * kmod_module_get_install_commands ()
const char * kmod_module_get_remove_commands ()
const char * kmod_module_get_name ()
const char * kmod_module_get_options ()
const char * kmod_module_get_path ()
int kmod_module_get_dependency_symbols ()
int kmod_module_dependency_symbol_get_bind ()
uint64_t kmod_module_dependency_symbol_get_crc ()
const char * kmod_module_dependency_symbol_get_symbol ()
void kmod_module_dependency_symbols_free_list ()
struct kmod_list * kmod_module_get_sections ()
unsigned long kmod_module_section_get_address ()
const char * kmod_module_section_get_name ()
void kmod_module_section_free_list ()
int kmod_module_get_symbols ()
uint64_t kmod_module_symbol_get_crc ()
const char * kmod_module_symbol_get_symbol ()
void kmod_module_symbols_free_list ()
int kmod_module_get_versions ()
uint64_t kmod_module_version_get_crc ()
const char * kmod_module_version_get_symbol ()
void kmod_module_versions_free_list ()
int kmod_module_get_info ()
const char * kmod_module_info_get_key ()
const char * kmod_module_info_get_value ()
void kmod_module_info_free_list ()

Types and Values

Description

Wide range of function to operate on kernel modules - loading, unloading, reference counting, retrieving a list of module dependencies and more.

Functions

kmod_module_new_from_lookup ()

int
kmod_module_new_from_lookup (struct kmod_ctx *ctx,
                             const char *given_alias,
                             struct kmod_list **list);

Create a new list of kmod modules using an alias or module name and lookup libkmod's configuration files and indexes in order to find the module. Once it's found in one of the places, it stops searching and create the list of modules that is saved in list .

The search order is: 1. aliases in configuration file; 2. module names in modules.dep index; 3. symbol aliases in modules.symbols index; 4. aliases from install commands; 5. builtin indexes from kernel.

The initial refcount is 1, and needs to be decremented to release the resources of the kmod_module. The returned list must be released by calling kmod_module_unref_list(). Since libkmod keeps track of all kmod_modules created, they are all released upon ctx destruction too. Do not unref ctx before all the desired operations with the returned list are completed.

Parameters

ctx

kmod library context

 

given_alias

alias to look for

 

list

an empty list where to save the list of modules matching given_alias

 

Returns

0 on success or < 0 otherwise. It fails if any of the lookup methods failed, which is basically due to memory allocation fail. If module is not found, it still returns 0, but list is an empty list.

Since: 1


kmod_module_new_from_name_lookup ()

int
kmod_module_new_from_name_lookup (struct kmod_ctx *ctx,
                                  const char *modname,
                                  struct kmod_module **mod);

Lookup by module name, without considering possible aliases. This is similar to kmod_module_new_from_lookup(), but don't consider as source indexes and configurations that work with aliases. When successful, this always resolves to one and only one module.

The search order is: 1. module names in modules.dep index;

  1. builtin indexes from kernel.

The initial refcount is 1, and needs to be decremented to release the resources of the kmod_module. Since libkmod keeps track of all kmod_modules created, they are all released upon ctx destruction too. Do not unref ctx before all the desired operations with the returned list are completed.

Parameters

ctx

kmod library context

 

modname

module name to look for

 

mod

returned module on success

 

Returns

0 on success or < 0 otherwise. It fails if any of the lookup methods failed, which is basically due to memory allocation failure. If module is not found, it still returns 0, but mod is left untouched.

Since: 30


kmod_module_new_from_name ()

int
kmod_module_new_from_name (struct kmod_ctx *ctx,
                           const char *name,
                           struct kmod_module **mod);

Create a new struct kmod_module using the module name. name can not be an alias, file name or anything else; it must be a module name. There's no check if the module exists in the system.

This function is also used internally by many others that return a new struct kmod_module or a new list of modules.

The initial refcount is 1, and needs to be decremented to release the resources of the kmod_module. Since libkmod keeps track of all kmod_modules created, they are all released upon ctx destruction too. Do not unref ctx before all the desired operations with the returned kmod_module are done.

Parameters

ctx

kmod library context

 

name

name of the module

 

mod

where to save the created struct kmod_module

 

Returns

0 on success or < 0 otherwise. It fails if name is not a valid module name or if memory allocation failed.

Since: 1


kmod_module_new_from_path ()

int
kmod_module_new_from_path (struct kmod_ctx *ctx,
                           const char *path,
                           struct kmod_module **mod);

Create a new struct kmod_module using the module path. path must be an existent file within the filesystem and must be accessible to libkmod.

The initial refcount is 1, and needs to be decremented to release the resources of the kmod_module. Since libkmod keeps track of all kmod_modules created, they are all released upon ctx destruction too. Do not unref ctx before all the desired operations with the returned kmod_module are done.

If path is relative, it's treated as relative to the current working directory. Otherwise, give an absolute path.

Parameters

ctx

kmod library context

 

path

path where to find the given module

 

mod

where to save the created struct kmod_module

 

Returns

0 on success or < 0 otherwise. It fails if file does not exist, if it's not a valid file for a kmod_module or if memory allocation failed.

Since: 1


kmod_module_ref ()

struct kmod_module *
kmod_module_ref (struct kmod_module *mod);

Take a reference of the kmod module, incrementing its refcount.

Parameters

mod

kmod module

 

Returns

the passed module with its refcount incremented.

Since: 1


kmod_module_unref ()

struct kmod_module *
kmod_module_unref (struct kmod_module *mod);

Drop a reference of the kmod module. If the refcount reaches zero, its resources are released.

Parameters

mod

kmod module

 

Returns

NULL if mod is NULL or if the module was released. Otherwise it returns the passed mod with its refcount decremented.

Since: 1


kmod_module_unref_list ()

int
kmod_module_unref_list (struct kmod_list *list);

Drop a reference of each kmod module in list and releases the resources taken by the list itself.

Parameters

list

list of kmod modules

 

Returns

0

Since: 1


kmod_module_insert_module ()

int
kmod_module_insert_module (struct kmod_module *mod,
                           unsigned int flags,
                           const char *options);

Insert a module in the kernel. It opens the file pointed by mod , mmap'ing it and passing to kernel.

Parameters

mod

kmod module

 

flags

flags are not passed to the kernel, but instead they dictate the behavior of this function, valid flags kmod_insert

 

options

module's options to pass to the kernel.

 

Returns

0 on success or < 0 on failure. If module is already loaded it returns -EEXIST.

Since: 1


kmod_module_probe_insert_module ()

int
kmod_module_probe_insert_module (struct kmod_module *mod,
                                 unsigned int flags,
                                 const char *extra_options,
                                 int (*run_install) (struct kmod_module *m, const char *cmdline, void *data),
                                 const void *data,
                                 void (*print_action) (struct kmod_module *m, bool install, const char *options));

Insert a module in the kernel resolving dependencies, soft dependencies, install commands and applying blacklist.

If run_install is NULL, this function will fork and exec by calling system(3). Don't pass a NULL argument in run_install if your binary is setuid/setgid (see warning in system(3)). If you need control over the execution of an install command, give a callback function instead.

Parameters

mod

kmod module

 

flags

flags are not passed to the kernel, but instead they dictate the behavior of this function, valid flags are kmod_probe

 

extra_options

module's options to pass to the kernel. It applies only to mod , not to its dependencies.

 

run_install

function to run when mod is backed by an install command.

 

data

data to give back to run_install callback

 

print_action

function to call with the action being taken (install or insmod). It's useful for tools like modprobe when running with verbose output or in dry-run mode.

 

Returns

0 on success, > 0 if stopped by a reason given in flags or < 0 on failure.

Since: 3


kmod_module_remove_module ()

int
kmod_module_remove_module (struct kmod_module *mod,
                           unsigned int flags);

Remove a module from the kernel.

Parameters

mod

kmod module

 

flags

flags used when removing the module, valid flags are kmod_remove

 

Returns

0 on success or < 0 on failure.

Since: 1


kmod_module_get_module ()

struct kmod_module *
kmod_module_get_module (const struct kmod_list *entry);

Get the kmod module of this entry in the list, increasing its refcount. After it's used, unref it. Since the refcount is incremented upon return, you still have to call kmod_module_unref_list() to release the list of kmod modules.

Parameters

entry

an entry in a list of kmod modules.

 

Returns

NULL on failure or the kmod_module contained in this list entry with its refcount incremented.

Since: 1


kmod_module_get_dependencies ()

struct kmod_list *
kmod_module_get_dependencies (const struct kmod_module *mod);

Search the modules.dep index to find the dependencies of the given mod . The result is cached in mod , so subsequent calls to this function will return the already searched list of modules.

Parameters

mod

kmod module

 

Returns

NULL on failure. Otherwise it returns a list of kmod modules that can be released by calling kmod_module_unref_list().

Since: 1


kmod_module_get_softdeps ()

int
kmod_module_get_softdeps (const struct kmod_module *mod,
                          struct kmod_list **pre,
                          struct kmod_list **post);

Get soft dependencies for this kmod module. Soft dependencies come from configuration file and are not cached in mod because it may include dependency cycles that would make we leak kmod_module. Any call to this function will search for this module in configuration, allocate a list and return the result.

Both pre and post are newly created list of kmod_module and should be unreferenced with kmod_module_unref_list().

Parameters

mod

kmod module

 

pre

where to save the list of preceding soft dependencies.

 

post

where to save the list of post soft dependencies.

 

Returns

0 on success or < 0 otherwise.

Since: 2


kmod_module_get_weakdeps ()

int
kmod_module_get_weakdeps (const struct kmod_module *mod,
                          struct kmod_list **weak);

Get weak dependencies for this kmod module. Weak dependencies come from configuration file and are not cached in mod because it may include dependency cycles that would make we leak kmod_module. Any call to this function will search for this module in configuration, allocate a list and return the result.

weak is newly created list of kmod_module and should be unreferenced with kmod_module_unref_list().

Parameters

mod

kmod module

 

weak

where to save the list of weak dependencies.

 

Returns

0 on success or < 0 otherwise.

Since: 33


kmod_module_apply_filter ()

int
kmod_module_apply_filter (const struct kmod_ctx *ctx,
                          enum kmod_filter filter_type,
                          const struct kmod_list *input,
                          struct kmod_list **output);

Given a list input , this function filter it out by the filter mask and save it in output .

Parameters

ctx

kmod library context

 

filter_type

bitmask to filter modules out, valid types are kmod_filter

 

input

list of kmod_module to be filtered

 

output

where to save the new list

 

Returns

0 on success or < 0 otherwise. output is saved with the updated list.

Since: 6


kmod_module_get_filtered_blacklist ()

int
kmod_module_get_filtered_blacklist (const struct kmod_ctx *ctx,
                                    const struct kmod_list *input,
                                    struct kmod_list **output);

kmod_module_get_filtered_blacklist has been deprecated since version 6 and should not be used in newly-written code.

Use kmod_module_apply_filter instead.

This function should not be used. Use kmod_module_apply_filter instead.

Given a list input , this function filter it out with config's blacklist and save it in output .

Parameters

ctx

kmod library context

 

input

list of kmod_module to be filtered with blacklist

 

output

where to save the new list

 

Returns

0 on success or < 0 otherwise. output is saved with the updated list.

Since: 1


kmod_module_get_install_commands ()

const char *
kmod_module_get_install_commands (const struct kmod_module *mod);

Get install commands for this kmod module. Install commands come from the configuration file and are cached in mod . The first call to this function will search for this module in configuration and subsequent calls return the cached string. The install commands are returned as they were in the configuration, concatenated by ';'. No other processing is made in this string.

Parameters

mod

kmod module

 

Returns

a string with all install commands separated by semicolons. This string is owned by mod , do not free it.

Since: 1


kmod_module_get_remove_commands ()

const char *
kmod_module_get_remove_commands (const struct kmod_module *mod);

Get remove commands for this kmod module. Remove commands come from the configuration file and are cached in mod . The first call to this function will search for this module in configuration and subsequent calls return the cached string. The remove commands are returned as they were in the configuration, concatenated by ';'. No other processing is made in this string.

Parameters

mod

kmod module

 

Returns

a string with all remove commands separated by semicolons. This string is owned by mod , do not free it.

Since: 1


kmod_module_get_name ()

const char *
kmod_module_get_name (const struct kmod_module *mod);

Get the name of this kmod module. Name is always available, independently if it was created by kmod_module_new_from_name() or another function and it's always normalized (dashes are replaced with underscores).

Parameters

mod

kmod module

 

Returns

the name of this kmod module.

Since: 1


kmod_module_get_options ()

const char *
kmod_module_get_options (const struct kmod_module *mod);

Get options of this kmod module. Options come from the configuration file and are cached in mod . The first call to this function will search for this module in configuration and subsequent calls return the cached string.

Parameters

mod

kmod module

 

Returns

a string with all the options separated by spaces. This string is owned by mod , do not free it.

Since: 1


kmod_module_get_path ()

const char *
kmod_module_get_path (const struct kmod_module *mod);

Get the path of this kmod module. If this kmod module was not created by path, it can search the modules.dep index in order to find out the module under context's dirname.

Parameters

mod

kmod module

 

Returns

the path of this kmod module or NULL if such information is not available.

Since: 1


kmod_module_get_dependency_symbols ()

int
kmod_module_get_dependency_symbols (const struct kmod_module *mod,
                                    struct kmod_list **list);

Get a list of entries in ELF section ".symtab" or "__ksymtab_strings".

The structure contained in this list is internal to libkmod and its fields can be obtainsed by calling kmod_module_dependency_symbol_get_crc() and kmod_module_dependency_symbol_get_symbol().

After use, free the list by calling kmod_module_dependency_symbols_free_list().

Parameters

mod

kmod module

 

list

where to return list of module dependency_symbols

 

Returns

0 on success or < 0 otherwise.

Since: 3


kmod_module_dependency_symbol_get_bind ()

int
kmod_module_dependency_symbol_get_bind
                               (const struct kmod_list *entry);

Get the bind type of a kmod module dependency_symbol.

Parameters

entry

a list entry representing a kmod module dependency_symbol

 

Returns

the bind of this kmod module dependency_symbol on success, or < 0 on failure. Valid bind types are kmod_symbol_bind.

Since: 3


kmod_module_dependency_symbol_get_crc ()

uint64_t
kmod_module_dependency_symbol_get_crc (const struct kmod_list *entry);

Get the crc of a kmod module dependency_symbol.

Parameters

entry

a list entry representing a kmod module dependency_symbol

 

Returns

the crc of this kmod module dependency_symbol if available, otherwise default to 0.

Since: 3


kmod_module_dependency_symbol_get_symbol ()

const char *
kmod_module_dependency_symbol_get_symbol
                               (const struct kmod_list *entry);

Get the dependency symbol of a kmod module

Parameters

entry

a list entry representing a kmod module dependency_symbols

 

Returns

the symbol of this kmod module dependency_symbols on success or NULL on failure. The string is owned by the dependency_symbols, do not free it.

Since: 3


kmod_module_dependency_symbols_free_list ()

void
kmod_module_dependency_symbols_free_list
                               (struct kmod_list *list);

Release the resources taken by list

Parameters

list

kmod module dependency_symbols list

 

Since: 3


kmod_module_get_sections ()

struct kmod_list *
kmod_module_get_sections (const struct kmod_module *mod);

Get a list of kmod sections of this mod , as returned by the kernel.

The structure contained in this list is internal to libkmod and its fields can be obtained by calling kmod_module_section_get_name() and kmod_module_section_get_address().

After use, free the list by calling kmod_module_section_free_list().

Parameters

mod

kmod module

 

Returns

a new list of kmod module sections on success or NULL on failure.

Since: 1


kmod_module_section_get_address ()

unsigned long
kmod_module_section_get_address (const struct kmod_list *entry);

Get the address of a kmod module section.

Parameters

entry

a list entry representing a kmod module section

 

Returns

the address of this kmod module section on success or ULONG_MAX on failure.

Since: 1


kmod_module_section_get_name ()

const char *
kmod_module_section_get_name (const struct kmod_list *entry);

Get the name of a kmod module section.

Parameters

entry

a list entry representing a kmod module section

 

Returns

the name of this kmod module section on success or NULL on failure. The string is owned by the section, do not free it.

Since: 1


kmod_module_section_free_list ()

void
kmod_module_section_free_list (struct kmod_list *list);

Release the resources taken by list

Parameters

list

kmod module section list

 

Since: 1


kmod_module_get_symbols ()

int
kmod_module_get_symbols (const struct kmod_module *mod,
                         struct kmod_list **list);

Get a list of entries in ELF section ".symtab" or "__ksymtab_strings".

The structure contained in this list is internal to libkmod and its fields can be obtainsed by calling kmod_module_symbol_get_crc() and kmod_module_symbol_get_symbol().

After use, free the list by calling kmod_module_symbols_free_list().

Parameters

mod

kmod module

 

list

where to return list of module symbols

 

Returns

0 on success or < 0 otherwise.

Since: 3


kmod_module_symbol_get_crc ()

uint64_t
kmod_module_symbol_get_crc (const struct kmod_list *entry);

Get the crc of a kmod module symbol.

Parameters

entry

a list entry representing a kmod module symbol

 

Returns

the crc of this kmod module symbol if available, otherwise default to 0.

Since: 3


kmod_module_symbol_get_symbol ()

const char *
kmod_module_symbol_get_symbol (const struct kmod_list *entry);

Get the symbol of a kmod module symbols.

Parameters

entry

a list entry representing a kmod module symbols

 

Returns

the symbol of this kmod module symbols on success or NULL on failure. The string is owned by the symbols, do not free it.

Since: 3


kmod_module_symbols_free_list ()

void
kmod_module_symbols_free_list (struct kmod_list *list);

Release the resources taken by list

Parameters

list

kmod module symbols list

 

Since: 3


kmod_module_get_versions ()

int
kmod_module_get_versions (const struct kmod_module *mod,
                          struct kmod_list **list);

Get a list of entries in ELF section "__versions".

The structure contained in this list is internal to libkmod and its fields can be obtainsed by calling kmod_module_version_get_crc() and kmod_module_version_get_symbol().

After use, free the list by calling kmod_module_versions_free_list().

Parameters

mod

kmod module

 

list

where to return list of module versions

 

Returns

0 on success or < 0 otherwise.

Since: 2


kmod_module_version_get_crc ()

uint64_t
kmod_module_version_get_crc (const struct kmod_list *entry);

Get the crc of a kmod module version.

Parameters

entry

a list entry representing a kmod module version

 

Returns

the crc of this kmod module version if available, otherwise default to 0.

Since: 2


kmod_module_version_get_symbol ()

const char *
kmod_module_version_get_symbol (const struct kmod_list *entry);

Get the symbol of a kmod module versions.

Parameters

entry

a list entry representing a kmod module versions

 

Returns

the symbol of this kmod module versions on success or NULL on failure. The string is owned by the versions, do not free it.

Since: 2


kmod_module_versions_free_list ()

void
kmod_module_versions_free_list (struct kmod_list *list);

Release the resources taken by list

Parameters

list

kmod module versions list

 

Since: 2


kmod_module_get_info ()

int
kmod_module_get_info (const struct kmod_module *mod,
                      struct kmod_list **list);

Get a list of entries in ELF section ".modinfo", these contain alias, license, depends, vermagic and other keys with respective values. If the module is signed (CONFIG_MODULE_SIG), information about the module signature is included as well: signer, sig_key and sig_hashalgo.

The structure contained in this list is internal to libkmod and its fields can be obtainsed by calling kmod_module_info_get_key() and kmod_module_info_get_value().

After use, free the list by calling kmod_module_info_free_list().

Parameters

mod

kmod module

 

list

where to return list of module information

 

Returns

number of entries in list on success or < 0 otherwise.

Since: 2


kmod_module_info_get_key ()

const char *
kmod_module_info_get_key (const struct kmod_list *entry);

Get the key of a kmod module info.

Parameters

entry

a list entry representing a kmod module info

 

Returns

the key of this kmod module info on success or NULL on failure. The string is owned by the info, do not free it.

Since: 2


kmod_module_info_get_value ()

const char *
kmod_module_info_get_value (const struct kmod_list *entry);

Get the value of a kmod module info.

Parameters

entry

a list entry representing a kmod module info

 

Returns

the value of this kmod module info on success or NULL on failure. The string is owned by the info, do not free it.

Since: 2


kmod_module_info_free_list ()

void
kmod_module_info_free_list (struct kmod_list *list);

Release the resources taken by list

Parameters

list

kmod module info list

 

Since: 2

Types and Values

struct kmod_module

struct kmod_module;

Opaque object representing a module.


enum kmod_insert

Insertion flags, used by kmod_module_insert_module().

Members

KMOD_INSERT_FORCE_VERMAGIC

ignore kernel version magic

 

KMOD_INSERT_FORCE_MODVERSION

ignore symbol version hashes

 

enum kmod_probe

Bitmask which defines the behaviour of kmod_module_probe_insert_module().

Members

KMOD_PROBE_FORCE_VERMAGIC

ignore kernel version magic

 

KMOD_PROBE_FORCE_MODVERSION

ignore symbol version hashes

 

KMOD_PROBE_IGNORE_COMMAND

ignore install commands and softdeps configured in the system

 

KMOD_PROBE_IGNORE_LOADED

do not check whether the module is already live in the kernel or not

 

KMOD_PROBE_DRY_RUN

dry run, do not insert module, just call the associated callback function

 

KMOD_PROBE_FAIL_ON_LOADED

probe will fail if KMOD_PROBE_IGNORE_LOADED is not specified and the module is already live in the kernel

 

KMOD_PROBE_APPLY_BLACKLIST_ALL

prior to probe, apply KMOD_FILTER_BLACKLIST filter to this module and its dependencies. If any of them are blacklisted and the blacklisted module is not live in the kernel, the function returns early with thus enum

 

KMOD_PROBE_APPLY_BLACKLIST

probe will return early with this enum, if the module is blacklisted

 

KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY

probe will return early with this enum, if the module is an alias and is blacklisted

 

enum kmod_remove

Removal flags, used by kmod_module_remove_module().

Members

KMOD_REMOVE_FORCE

force remove module regardless if it's still in use by a kernel subsystem or other process; passed directly to the kernel

 

KMOD_REMOVE_NOWAIT

always set, pass O_NONBLOCK to delete_module(2); passed directly to the kernel

 

KMOD_REMOVE_NOLOG

when module removal fails, do not log anything; not passed to the kernel

 

enum kmod_filter

Bitmask defining what gets filtered out, used by kmod_module_apply_filter().

Members

KMOD_FILTER_BLACKLIST

filter modules in blacklist out

 

KMOD_FILTER_BUILTIN

filter builtin modules out

 

enum kmod_symbol_bind

The symbol bind type, see kmod_module_dependency_symbol_get_bind().

Members

KMOD_SYMBOL_NONE

no or unknown symbol type

 

KMOD_SYMBOL_LOCAL

local symbol, accessible only within the module

 

KMOD_SYMBOL_GLOBAL

global symbol, accessible by all modules

 

KMOD_SYMBOL_WEAK

weak symbol, a lower precedence global symbols

 

KMOD_SYMBOL_UNDEF

undefined or not yet resolved symbol