libkmod-module

## libkmod-module libkmod-module — operate on kernel modules |

## Synopsis

    struct              kmod_module;
    int                 kmod_module_new_from_lookup         (struct kmod_ctx *ctx,
                                                             const char *given_alias,
                                                             struct kmod_list **list);
    int                 kmod_module_new_from_name           (struct kmod_ctx *ctx,
                                                             const char *name,
                                                             struct kmod_module **mod);
    int                 kmod_module_new_from_path           (struct kmod_ctx *ctx,
                                                             const char *path,
                                                             struct kmod_module **mod);
    struct kmod_module * kmod_module_ref                    (struct kmod_module *mod);
    struct kmod_module * kmod_module_unref                  (struct kmod_module *mod);
    int                 kmod_module_unref_list              (struct kmod_list *list);
    int                 kmod_module_insert_module           (struct kmod_module *mod,
                                                             unsigned int flags,
                                                             const char *options);
    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));
    int                 kmod_module_remove_module           (struct kmod_module *mod,
                                                             unsigned int flags);
    struct kmod_module * kmod_module_get_module             (const struct kmod_list *entry);
    struct kmod_list *  kmod_module_get_dependencies        (const struct kmod_module *mod);
    int                 kmod_module_get_softdeps            (const struct kmod_module *mod,
                                                             struct kmod_list **pre,
                                                             struct kmod_list **post);
    int                 kmod_module_apply_filter            (const struct kmod_ctx *ctx,
                                                             enum kmod_filter filter_type,
                                                             const struct kmod_list *input,
                                                             struct kmod_list **output);
    int                 kmod_module_get_filtered_blacklist  (const struct kmod_ctx *ctx,
                                                             const struct kmod_list *input,
                                                             struct kmod_list **output);
    const char *        kmod_module_get_install_commands    (const struct kmod_module *mod);
    const char *        kmod_module_get_remove_commands     (const struct kmod_module *mod);
    const char *        kmod_module_get_name                (const struct kmod_module *mod);
    const char *        kmod_module_get_options             (const struct kmod_module *mod);
    const char *        kmod_module_get_path                (const struct kmod_module *mod);
    int                 kmod_module_get_dependency_symbols  (const struct kmod_module *mod,
                                                             struct kmod_list **list);
    int                 kmod_module_dependency_symbol_get_bind
                                                            (const struct kmod_list *entry);
    uint64_t            kmod_module_dependency_symbol_get_crc
                                                            (const struct kmod_list *entry);
    const char *        kmod_module_dependency_symbol_get_symbol
                                                            (const struct kmod_list *entry);
    void                kmod_module_dependency_symbols_free_list
                                                            (struct kmod_list *list);
    struct kmod_list *  kmod_module_get_sections            (const struct kmod_module *mod);
    void                kmod_module_section_free_list       (struct kmod_list *list);
    unsigned long       kmod_module_section_get_address     (const struct kmod_list *entry);
    const char *        kmod_module_section_get_name        (const struct kmod_list *entry);
    int                 kmod_module_get_symbols             (const struct kmod_module *mod,
                                                             struct kmod_list **list);
    uint64_t            kmod_module_symbol_get_crc          (const struct kmod_list *entry);
    const char *        kmod_module_symbol_get_symbol       (const struct kmod_list *entry);
    void                kmod_module_symbols_free_list       (struct kmod_list *list);
    int                 kmod_module_get_versions            (const struct kmod_module *mod,
                                                             struct kmod_list **list);
    uint64_t            kmod_module_version_get_crc         (const struct kmod_list *entry);
    const char *        kmod_module_version_get_symbol      (const struct kmod_list *entry);
    void                kmod_module_versions_free_list      (struct kmod_list *list);
    int                 kmod_module_get_info                (const struct kmod_module *mod,
                                                             struct kmod_list **list);
    void                kmod_module_info_free_list          (struct kmod_list *list);
    const char *        kmod_module_info_get_key            (const struct kmod_list *entry);
    const char *        kmod_module_info_get_value          (const struct kmod_list *entry);

## Description

## Details

### struct kmod_module

    struct kmod_module;

Opaque object representing a module.

### 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 in modules.alias index.

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.

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

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

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

### 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 with in 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.

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

### kmod_module_ref ()

    struct kmod_module * kmod_module_ref                    (struct kmod_module *mod);

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

`mod` : | kmod module
Returns : | the passed `module` with its refcount incremented.

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

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

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

`list` : | list of kmod modules

### kmod_module_insert_module ()

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

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

`mod` : | kmod module
`flags` : | flags are not passed to Linux Kernel, but instead they dictate the behavior of this function, valid flags are KMOD_INSERT_FORCE_VERMAGIC: ignore kernel version magic; KMOD_INSERT_FORCE_MODVERSION: ignore symbol version hashes.
`options` : | module's options to pass to Linux Kernel.
Returns : | 0 on success or < 0 on failure. If module is already loaded it returns -EEXIST.

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

`mod` : | kmod module
`flags` : | flags are not passed to Linux Kernel, but instead they dictate the behavior of this function, valid flags are KMOD_PROBE_FORCE_VERMAGIC: ignore kernel version magic; KMOD_PROBE_FORCE_MODVERSION: ignore symbol version hashes; KMOD_PROBE_IGNORE_COMMAND: whether the probe should ignore install commands and softdeps configured in the system; KMOD_PROBE_IGNORE_LOADED: do not check whether the module is already live in kernel or not; KMOD_PROBE_DRY_RUN: dry run, do not insert module, just call the associated callback function; KMOD_PROBE_FAIL_ON_LOADED: if KMOD_PROBE_IGNORE_LOADED is not specified and the module is already live in kernel, the function will fail if this flag is specified; KMOD_PROBE_APPLY_BLACKLIST_ALL: probe will apply KMOD_FILTER_BLACKLIST filter to this module and its dependencies. If any of the dependencies (or the module) is blacklisted, the probe will fail, unless the blacklisted module is already live in kernel; KMOD_PROBE_APPLY_BLACKLIST: probe will fail if the module is blacklisted; KMOD_PROBE_APPLY_BLACKLIST_ALIAS_ONLY: probe will fail if the module is an alias and is blacklisted.
`extra_options` : | module's options to pass to Linux 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.

### kmod_module_remove_module ()

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

Remove a module from Linux kernel.

`mod` : | kmod module
`flags` : | flags to pass to Linux kernel when removing the module, valid flags are KMOD_REMOVE_FORCE: force remove module regardless if it's still in use by a kernel subsystem or other process; KMOD_REMOVE_NOWAIT: return immediately. It will fail if the module is in using and KMOD_REMOVE_FORCE is not specified. If this module is in use by any kernel subsystem or process, not using this flag will cause the call to block indefinitely, until the module is not in use anymore. Always use this flag, it's deprecated not using it and the default behavior might change in future to always set it.
Returns : | 0 on success or < 0 on failure.

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

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

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

`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()`.

### 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()`.

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

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

`ctx` : | kmod library context
`filter_type` : | bitmask to filter modules out, valid types are KMOD_FILTER_BLACKLIST: filter modules in blacklist out; KMOD_FILTER_BUILTIN: filter builtin modules out.
`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.

### 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);

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

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

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

`mod` : | kmod module
Returns : | a string with all install commands separated by semicolons. This string is owned by `mod`, do not free it.

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

`mod` : | kmod module
Returns : | a string with all remove commands separated by semicolons. This string is owned by `mod`, do not free it.

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

`mod` : | kmod module
Returns : | the name of this kmod module.

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

`mod` : | kmod module
Returns : | a string with all the options separated by spaces. This string is owned by `mod`, do not free it.

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

`mod` : | kmod module
Returns : | the path of this kmod module or NULL if such information is not available.

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

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

`mod` : | kmod module
`list` : | where to return list of module dependency_symbols. Use `kmod_module_dependency_symbol_get_symbol()` and `kmod_module_dependency_symbol_get_crc()`. Release this list with `kmod_module_dependency_symbols_free_list()`
Returns : | 0 on success or < 0 otherwise.

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

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

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

`entry` : | a list entry representing a kmod module dependency_symbol
Returns : | the crc of this kmod module dependency_symbol on success or NULL on failure. The string is owned by the dependency_symbol, do not free it.

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

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

### kmod_module_dependency_symbols_free_list ()

    void                kmod_module_dependency_symbols_free_list
                                                            (struct kmod_list *list);

Release the resources taken by `list`

`list` : | kmod module dependency_symbols list

### 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 Linux Kernel. The structure contained in this list is internal to libkmod and their 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()`.

`mod` : | kmod module
Returns : | a new list of kmod module sections on success or NULL on failure.

### kmod_module_section_free_list ()

    void                kmod_module_section_free_list       (struct kmod_list *list);

Release the resources taken by `list`

`list` : | kmod module section list

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

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

`entry` : | a list entry representing a kmod module section
Returns : | the address of this kmod module section on success or ULONG_MAX on failure.

### kmod_module_section_get_name ()

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

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

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

`mod` : | kmod module
`list` : | where to return list of module symbols. Use `kmod_module_symbol_get_symbol()` and `kmod_module_symbol_get_crc()`. Release this list with `kmod_module_symbols_free_list()`
Returns : | 0 on success or < 0 otherwise.

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

`entry` : | a list entry representing a kmod module symbol
Returns : | the crc of this kmod module symbol on success or NULL on failure. The string is owned by the symbol, do not free it.

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

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

### kmod_module_symbols_free_list ()

    void                kmod_module_symbols_free_list       (struct kmod_list *list);

Release the resources taken by `list`

`list` : | kmod module symbols list

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

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

`mod` : | kmod module
`list` : | where to return list of module versions. Use `kmod_module_version_get_symbol()` and `kmod_module_version_get_crc()`. Release this list with `kmod_module_versions_free_list()`
Returns : | 0 on success or < 0 otherwise.

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

`entry` : | a list entry representing a kmod module version
Returns : | the crc of this kmod module version on success or NULL on failure. The string is owned by the version, do not free it.

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

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

### kmod_module_versions_free_list ()

    void                kmod_module_versions_free_list      (struct kmod_list *list);

Release the resources taken by `list`

`list` : | kmod module versions list

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

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

`mod` : | kmod module
`list` : | where to return list of module information. Use `kmod_module_info_get_key()` and `kmod_module_info_get_value()`. Release this list with `kmod_module_info_free_list()`
Returns : | 0 on success or < 0 otherwise.

### kmod_module_info_free_list ()

    void                kmod_module_info_free_list          (struct kmod_list *list);

Release the resources taken by `list`

`list` : | kmod module info list

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

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

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

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