From: Emil Velikov Date: Mon, 2 Sep 2024 22:20:18 +0000 (+0100) Subject: libkmod/docs: move libkmod-module section to the header X-Git-Tag: v34~445 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=63aea7f1822217e0deeb9536194cfdc234edb71d;p=thirdparty%2Fkmod.git libkmod/docs: move libkmod-module section to the header In part to ease my life as I'm going through (shortly) and updating the log. In part so that developers how don't install the gtk-doc html pages, still have the information at hand. While here, sort the API akin to the HTML documentation. Signed-off-by: Emil Velikov Link: https://github.com/kmod-project/kmod/pull/94 Signed-off-by: Lucas De Marchi --- diff --git a/libkmod/libkmod-module.c b/libkmod/libkmod-module.c index 9cfc8017..2d3e47a9 100644 --- a/libkmod/libkmod-module.c +++ b/libkmod/libkmod-module.c @@ -27,22 +27,12 @@ #include "libkmod.h" #include "libkmod-internal.h" -/** - * SECTION:libkmod-module - * @short_description: operate on kernel modules - */ - enum kmod_module_builtin { KMOD_MODULE_BUILTIN_UNKNOWN, KMOD_MODULE_BUILTIN_NO, KMOD_MODULE_BUILTIN_YES, }; -/** - * kmod_module: - * - * Opaque object representing a module. - */ struct kmod_module { struct kmod_ctx *ctx; char *hashkey; @@ -287,28 +277,6 @@ static int kmod_module_new(struct kmod_ctx *ctx, const char *key, return 0; } -/** - * kmod_module_new_from_name: - * @ctx: kmod library context - * @name: name of the module - * @mod: where to save the created struct kmod_module - * - * 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. - * - * Returns: 0 on success or < 0 otherwise. It fails if name is not a valid - * module name or if memory allocation failed. - */ KMOD_EXPORT int kmod_module_new_from_name(struct kmod_ctx *ctx, const char *name, struct kmod_module **mod) @@ -346,27 +314,6 @@ int kmod_module_new_from_alias(struct kmod_ctx *ctx, const char *alias, return 0; } -/** - * kmod_module_new_from_path: - * @ctx: kmod library context - * @path: path where to find the given module - * @mod: where to save the created struct kmod_module - * - * 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. - * - * 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_EXPORT int kmod_module_new_from_path(struct kmod_ctx *ctx, const char *path, struct kmod_module **mod) @@ -431,16 +378,6 @@ KMOD_EXPORT int kmod_module_new_from_path(struct kmod_ctx *ctx, return 0; } -/** - * kmod_module_unref: - * @mod: kmod module - * - * Drop a reference of the kmod module. If the refcount reaches zero, its - * resources are released. - * - * Returns: NULL if @mod is NULL or if the module was released. Otherwise it - * returns the passed @mod with its refcount decremented. - */ KMOD_EXPORT struct kmod_module *kmod_module_unref(struct kmod_module *mod) { if (mod == NULL) @@ -464,14 +401,6 @@ KMOD_EXPORT struct kmod_module *kmod_module_unref(struct kmod_module *mod) return NULL; } -/** - * kmod_module_ref: - * @mod: kmod module - * - * Take a reference of the kmod module, incrementing its refcount. - * - * Returns: the passed @module with its refcount incremented. - */ KMOD_EXPORT struct kmod_module *kmod_module_ref(struct kmod_module *mod) { if (mod == NULL) @@ -503,33 +432,6 @@ static int __kmod_module_new_from_lookup(struct kmod_ctx *ctx, const lookup_func return 0; } -/** - * kmod_module_new_from_lookup: - * @ctx: kmod library context - * @given_alias: alias to look for - * @list: an empty list where to save the list of modules matching - * @given_alias - * - * 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. - * - * 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_EXPORT int kmod_module_new_from_lookup(struct kmod_ctx *ctx, const char *given_alias, struct kmod_list **list) @@ -574,30 +476,6 @@ KMOD_EXPORT int kmod_module_new_from_lookup(struct kmod_ctx *ctx, return err; } -/** - * kmod_module_new_from_name_lookup: - * @ctx: kmod library context - * @modname: module name to look for - * @mod: returned module on success - * - * 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; - * 2. 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. - * - * 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. - */ KMOD_EXPORT int kmod_module_new_from_name_lookup(struct kmod_ctx *ctx, const char *modname, struct kmod_module **mod) @@ -631,15 +509,6 @@ KMOD_EXPORT int kmod_module_new_from_name_lookup(struct kmod_ctx *ctx, return err; } -/** - * kmod_module_unref_list: - * @list: list of kmod modules - * - * Drop a reference of each kmod module in @list and releases the resources - * taken by the list itself. - * - * Returns: 0 - */ KMOD_EXPORT int kmod_module_unref_list(struct kmod_list *list) { for (; list != NULL; list = kmod_list_remove(list)) @@ -648,20 +517,6 @@ KMOD_EXPORT int kmod_module_unref_list(struct kmod_list *list) return 0; } -/** - * kmod_module_get_filtered_blacklist: - * @ctx: kmod library context - * @input: list of kmod_module to be filtered with blacklist - * @output: where to save the new list - * - * 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. - * - * Returns: 0 on success or < 0 otherwise. @output is saved with the updated - * list. - */ KMOD_EXPORT int kmod_module_get_filtered_blacklist(const struct kmod_ctx *ctx, const struct kmod_list *input, struct kmod_list **output) @@ -688,17 +543,6 @@ static const struct kmod_list *module_get_dependencies_noref(const struct kmod_m return mod->dep; } -/** - * kmod_module_get_dependencies: - * @mod: kmod module - * - * 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. - * - * Returns: NULL on failure. Otherwise it returns a list of kmod modules - * that can be released by calling kmod_module_unref_list(). - */ KMOD_EXPORT struct kmod_list *kmod_module_get_dependencies(const struct kmod_module *mod) { struct kmod_list *l, *l_new, *list_new = NULL; @@ -726,18 +570,6 @@ fail: return NULL; } -/** - * kmod_module_get_module: - * @entry: an entry in a list of kmod modules. - * - * 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. - * - * Returns: NULL on failure or the kmod_module contained in this list entry - * with its refcount incremented. - */ KMOD_EXPORT struct kmod_module *kmod_module_get_module(const struct kmod_list *entry) { if (entry == NULL) @@ -746,16 +578,6 @@ KMOD_EXPORT struct kmod_module *kmod_module_get_module(const struct kmod_list *e return kmod_module_ref(entry->data); } -/** - * kmod_module_get_name: - * @mod: kmod module - * - * 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). - * - * Returns: the name of this kmod module. - */ KMOD_EXPORT const char *kmod_module_get_name(const struct kmod_module *mod) { if (mod == NULL) @@ -764,17 +586,6 @@ KMOD_EXPORT const char *kmod_module_get_name(const struct kmod_module *mod) return mod->name; } -/** - * kmod_module_get_path: - * @mod: kmod module - * - * 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. - * - * Returns: the path of this kmod module or NULL if such information is not - * available. - */ KMOD_EXPORT const char *kmod_module_get_path(const struct kmod_module *mod) { char *line; @@ -803,21 +614,6 @@ KMOD_EXPORT const char *kmod_module_get_path(const struct kmod_module *mod) extern long delete_module(const char *name, unsigned int flags); -/** - * kmod_module_remove_module: - * @mod: kmod module - * @flags: flags used when removing the module. - * KMOD_REMOVE_FORCE: force remove module regardless if it's still in - * use by a kernel subsystem or other process; passed directly to Linux kernel - * KMOD_REMOVE_NOWAIT: is always enforced, causing us to pass O_NONBLOCK to - * delete_module(2). - * KMOD_REMOVE_NOLOG: when module removal fails, do not log anything as the - * caller may want to handle retries and log when appropriate. - * - * Remove a module from Linux kernel. - * - * Returns: 0 on success or < 0 on failure. - */ KMOD_EXPORT int kmod_module_remove_module(struct kmod_module *mod, unsigned int flags) { @@ -922,21 +718,6 @@ static int do_init_module(struct kmod_module *mod, unsigned int flags, return err; } -/** - * kmod_module_insert_module: - * @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. - * - * Insert a module in Linux kernel. It opens the file pointed by @mod, - * mmap'ing it and passing to kernel. - * - * Returns: 0 on success or < 0 on failure. If module is already loaded it - * returns -EEXIST. - */ KMOD_EXPORT int kmod_module_insert_module(struct kmod_module *mod, unsigned int flags, const char *options) @@ -990,21 +771,6 @@ static bool module_is_blacklisted(struct kmod_module *mod) return false; } -/** - * kmod_module_apply_filter - * @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 - * - * Given a list @input, this function filter it out by the filter mask - * and save it in @output. - * - * Returns: 0 on success or < 0 otherwise. @output is saved with the updated - * list. - */ KMOD_EXPORT int kmod_module_apply_filter(const struct kmod_ctx *ctx, enum kmod_filter filter_type, const struct kmod_list *input, @@ -1282,48 +1048,6 @@ static int kmod_module_get_probe_list(struct kmod_module *mod, return err; } -/** - * kmod_module_probe_insert_module: - * @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. - * - * 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. - * - * Returns: 0 on success, > 0 if stopped by a reason given in @flags or < 0 on - * failure. - */ KMOD_EXPORT int kmod_module_probe_insert_module(struct kmod_module *mod, unsigned int flags, const char *extra_options, int (*run_install)(struct kmod_module *m, @@ -1448,17 +1172,6 @@ finish_module: return err; } -/** - * kmod_module_get_options: - * @mod: kmod module - * - * 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. - * - * Returns: a string with all the options separated by spaces. This string is - * owned by @mod, do not free it. - */ KMOD_EXPORT const char *kmod_module_get_options(const struct kmod_module *mod) { if (mod == NULL) @@ -1520,20 +1233,6 @@ failed: return NULL; } -/** - * kmod_module_get_install_commands: - * @mod: kmod module - * - * 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. - * - * Returns: a string with all install commands separated by semicolons. This - * string is owned by @mod, do not free it. - */ KMOD_EXPORT const char *kmod_module_get_install_commands(const struct kmod_module *mod) { if (mod == NULL) @@ -1594,23 +1293,6 @@ static struct kmod_list *lookup_dep(struct kmod_ctx *ctx, const char * const * a return ret; } -/** - * kmod_module_get_softdeps: - * @mod: kmod module - * @pre: where to save the list of preceding soft dependencies. - * @post: where to save the list of post soft dependencies. - * - * 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(). - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_module_get_softdeps(const struct kmod_module *mod, struct kmod_list **pre, struct kmod_list **post) @@ -1649,22 +1331,6 @@ KMOD_EXPORT int kmod_module_get_softdeps(const struct kmod_module *mod, return 0; } -/* - * kmod_module_get_weakdeps: - * @mod: kmod module - * @weak: where to save the list of weak dependencies. - * - * 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(). - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_module_get_weakdeps(const struct kmod_module *mod, struct kmod_list **weak) { @@ -1699,20 +1365,6 @@ KMOD_EXPORT int kmod_module_get_weakdeps(const struct kmod_module *mod, return 0; } -/** - * kmod_module_get_remove_commands: - * @mod: kmod module - * - * 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. - * - * Returns: a string with all remove commands separated by semicolons. This - * string is owned by @mod, do not free it. - */ KMOD_EXPORT const char *kmod_module_get_remove_commands(const struct kmod_module *mod) { if (mod == NULL) @@ -2124,19 +1776,6 @@ static void kmod_module_section_free(struct kmod_module_section *section) free(section); } -/** - * kmod_module_get_sections: - * @mod: kmod module - * - * 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(). - * - * Returns: a new list of kmod module sections on success or NULL on failure. - */ KMOD_EXPORT struct kmod_list *kmod_module_get_sections(const struct kmod_module *mod) { char dname[PATH_MAX]; @@ -2217,17 +1856,6 @@ fail: return NULL; } -/** - * kmod_module_section_get_module_name: - * @entry: a list entry representing a kmod module section - * - * Get the name of a kmod module section. - * - * After use, free the @list by calling kmod_module_section_free_list(). - * - * 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. - */ KMOD_EXPORT const char *kmod_module_section_get_name(const struct kmod_list *entry) { struct kmod_module_section *section; @@ -2239,17 +1867,6 @@ KMOD_EXPORT const char *kmod_module_section_get_name(const struct kmod_list *ent return section->name; } -/** - * kmod_module_section_get_address: - * @entry: a list entry representing a kmod module section - * - * Get the address of a kmod module section. - * - * After use, free the @list by calling kmod_module_section_free_list(). - * - * Returns: the address of this kmod module section on success or ULONG_MAX - * on failure. - */ KMOD_EXPORT unsigned long kmod_module_section_get_address(const struct kmod_list *entry) { struct kmod_module_section *section; @@ -2261,12 +1878,6 @@ KMOD_EXPORT unsigned long kmod_module_section_get_address(const struct kmod_list return section->address; } -/** - * kmod_module_section_free_list: - * @list: kmod module section list - * - * Release the resources taken by @list - */ KMOD_EXPORT void kmod_module_section_free_list(struct kmod_list *list) { while (list) { @@ -2394,24 +2005,6 @@ list_error: return NULL; } -/** - * kmod_module_get_info: - * @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() - * - * 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(). - * - * Returns: number of entries in @list on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_module_get_info(const struct kmod_module *mod, struct kmod_list **list) { struct kmod_elf *elf; @@ -2521,15 +2114,6 @@ list_error: return ret; } -/** - * kmod_module_info_get_key: - * @entry: a list entry representing a kmod module info - * - * Get the key of 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_EXPORT const char *kmod_module_info_get_key(const struct kmod_list *entry) { struct kmod_module_info *info; @@ -2541,15 +2125,6 @@ KMOD_EXPORT const char *kmod_module_info_get_key(const struct kmod_list *entry) return info->key; } -/** - * kmod_module_info_get_value: - * @entry: a list entry representing a kmod module info - * - * Get the value of 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. - */ KMOD_EXPORT const char *kmod_module_info_get_value(const struct kmod_list *entry) { struct kmod_module_info *info; @@ -2561,12 +2136,6 @@ KMOD_EXPORT const char *kmod_module_info_get_value(const struct kmod_list *entry return info->value; } -/** - * kmod_module_info_free_list: - * @list: kmod module info list - * - * Release the resources taken by @list - */ KMOD_EXPORT void kmod_module_info_free_list(struct kmod_list *list) { while (list) { @@ -2599,20 +2168,6 @@ static void kmod_module_version_free(struct kmod_module_version *version) free(version); } -/** - * kmod_module_get_versions: - * @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() - * - * Get a list of entries in ELF section "__versions". - * - * After use, free the @list by calling kmod_module_versions_free_list(). - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_module_get_versions(const struct kmod_module *mod, struct kmod_list **list) { struct kmod_elf *elf; @@ -2662,15 +2217,6 @@ list_error: return ret; } -/** - * kmod_module_version_get_symbol: - * @entry: a list entry representing a kmod module versions - * - * Get the symbol of 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_EXPORT const char *kmod_module_version_get_symbol(const struct kmod_list *entry) { struct kmod_module_version *version; @@ -2682,14 +2228,6 @@ KMOD_EXPORT const char *kmod_module_version_get_symbol(const struct kmod_list *e return version->symbol; } -/** - * kmod_module_version_get_crc: - * @entry: a list entry representing a kmod module version - * - * Get the crc of a kmod module version. - * - * Returns: the crc of this kmod module version if available, otherwise default to 0. - */ KMOD_EXPORT uint64_t kmod_module_version_get_crc(const struct kmod_list *entry) { struct kmod_module_version *version; @@ -2701,12 +2239,6 @@ KMOD_EXPORT uint64_t kmod_module_version_get_crc(const struct kmod_list *entry) return version->crc; } -/** - * kmod_module_versions_free_list: - * @list: kmod module versions list - * - * Release the resources taken by @list - */ KMOD_EXPORT void kmod_module_versions_free_list(struct kmod_list *list) { while (list) { @@ -2739,20 +2271,6 @@ static void kmod_module_symbol_free(struct kmod_module_symbol *symbol) free(symbol); } -/** - * kmod_module_get_symbols: - * @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() - * - * Get a list of entries in ELF section ".symtab" or "__ksymtab_strings". - * - * After use, free the @list by calling kmod_module_symbols_free_list(). - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_module_get_symbols(const struct kmod_module *mod, struct kmod_list **list) { struct kmod_elf *elf; @@ -2802,15 +2320,6 @@ list_error: return ret; } -/** - * kmod_module_symbol_get_symbol: - * @entry: a list entry representing a kmod module symbols - * - * Get the symbol of 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_EXPORT const char *kmod_module_symbol_get_symbol(const struct kmod_list *entry) { struct kmod_module_symbol *symbol; @@ -2822,14 +2331,6 @@ KMOD_EXPORT const char *kmod_module_symbol_get_symbol(const struct kmod_list *en return symbol->symbol; } -/** - * kmod_module_symbol_get_crc: - * @entry: a list entry representing a kmod module symbol - * - * Get the crc of a kmod module symbol. - * - * Returns: the crc of this kmod module symbol if available, otherwise default to 0. - */ KMOD_EXPORT uint64_t kmod_module_symbol_get_crc(const struct kmod_list *entry) { struct kmod_module_symbol *symbol; @@ -2841,12 +2342,6 @@ KMOD_EXPORT uint64_t kmod_module_symbol_get_crc(const struct kmod_list *entry) return symbol->crc; } -/** - * kmod_module_symbols_free_list: - * @list: kmod module symbols list - * - * Release the resources taken by @list - */ KMOD_EXPORT void kmod_module_symbols_free_list(struct kmod_list *list) { while (list) { @@ -2881,21 +2376,6 @@ static void kmod_module_dependency_symbol_free(struct kmod_module_dependency_sym free(dependency_symbol); } -/** - * kmod_module_get_dependency_symbols: - * @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() - * - * 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(). - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_module_get_dependency_symbols(const struct kmod_module *mod, struct kmod_list **list) { struct kmod_elf *elf; @@ -2947,15 +2427,6 @@ list_error: return ret; } -/** - * kmod_module_dependency_symbol_get_symbol: - * @entry: a list entry representing a kmod module dependency_symbols - * - * Get the dependency symbol of a kmod module - * - * 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_EXPORT const char *kmod_module_dependency_symbol_get_symbol(const struct kmod_list *entry) { struct kmod_module_dependency_symbol *dependency_symbol; @@ -2967,14 +2438,6 @@ KMOD_EXPORT const char *kmod_module_dependency_symbol_get_symbol(const struct km return dependency_symbol->symbol; } -/** - * kmod_module_dependency_symbol_get_crc: - * @entry: a list entry representing a kmod module dependency_symbol - * - * Get the crc of a kmod module dependency_symbol. - * - * Returns: the crc of this kmod module dependency_symbol if available, otherwise default to 0. - */ KMOD_EXPORT uint64_t kmod_module_dependency_symbol_get_crc(const struct kmod_list *entry) { struct kmod_module_dependency_symbol *dependency_symbol; @@ -2986,15 +2449,6 @@ KMOD_EXPORT uint64_t kmod_module_dependency_symbol_get_crc(const struct kmod_lis return dependency_symbol->crc; } -/** - * kmod_module_dependency_symbol_get_bind: - * @entry: a list entry representing a kmod module dependency_symbol - * - * Get the bind type of a kmod module dependency_symbol. - * - * Returns: the bind of this kmod module dependency_symbol on success - * or < 0 on failure. - */ KMOD_EXPORT int kmod_module_dependency_symbol_get_bind(const struct kmod_list *entry) { struct kmod_module_dependency_symbol *dependency_symbol; @@ -3006,12 +2460,6 @@ KMOD_EXPORT int kmod_module_dependency_symbol_get_bind(const struct kmod_list *e return dependency_symbol->bind; } -/** - * kmod_module_dependency_symbols_free_list: - * @list: kmod module dependency_symbols list - * - * Release the resources taken by @list - */ KMOD_EXPORT void kmod_module_dependency_symbols_free_list(struct kmod_list *list) { while (list) { diff --git a/libkmod/libkmod.h b/libkmod/libkmod.h index b008af78..947a4bbc 100644 --- a/libkmod/libkmod.h +++ b/libkmod/libkmod.h @@ -293,37 +293,166 @@ bool kmod_config_iter_next(struct kmod_config_iter *iter); */ void kmod_config_iter_free_iter(struct kmod_config_iter *iter); + +/** + * SECTION:libkmod-module + * @short_description: operate on kernel modules + */ + /* * kmod_module * * Operate on kernel modules */ + +/** + * kmod_module: + * + * Opaque object representing a module. + */ struct kmod_module; -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); + +/** + * kmod_module_new_from_lookup: + * @ctx: kmod library context + * @given_alias: alias to look for + * @list: an empty list where to save the list of modules matching + * @given_alias + * + * 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. + * + * 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. + */ int kmod_module_new_from_lookup(struct kmod_ctx *ctx, const char *given_alias, struct kmod_list **list); + +/** + * kmod_module_new_from_name_lookup: + * @ctx: kmod library context + * @modname: module name to look for + * @mod: returned module on success + * + * 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; + * 2. 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. + * + * 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. + */ int kmod_module_new_from_name_lookup(struct kmod_ctx *ctx, const char *modname, struct kmod_module **mod); -int kmod_module_new_from_loaded(struct kmod_ctx *ctx, - struct kmod_list **list); +/** + * kmod_module_new_from_name: + * @ctx: kmod library context + * @name: name of the module + * @mod: where to save the created struct kmod_module + * + * 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. + * + * Returns: 0 on success or < 0 otherwise. It fails if name is not a valid + * module name or if memory allocation failed. + */ +int kmod_module_new_from_name(struct kmod_ctx *ctx, const char *name, + struct kmod_module **mod); + +/** + * kmod_module_new_from_path: + * @ctx: kmod library context + * @path: path where to find the given module + * @mod: where to save the created struct kmod_module + * + * 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. + * + * 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. + */ +int kmod_module_new_from_path(struct kmod_ctx *ctx, const char *path, + struct kmod_module **mod); + + +/** + * kmod_module_ref: + * @mod: kmod module + * + * Take a reference of the kmod module, incrementing its refcount. + * + * Returns: the passed @module with its refcount incremented. + */ struct kmod_module *kmod_module_ref(struct kmod_module *mod); + +/** + * kmod_module_unref: + * @mod: kmod module + * + * Drop a reference of the kmod module. If the refcount reaches zero, its + * resources are released. + * + * Returns: NULL if @mod is NULL or if the module was released. Otherwise it + * returns the passed @mod with its refcount decremented. + */ struct kmod_module *kmod_module_unref(struct kmod_module *mod); -int kmod_module_unref_list(struct kmod_list *list); -struct kmod_module *kmod_module_get_module(const struct kmod_list *entry); +/** + * kmod_module_unref_list: + * @list: list of kmod modules + * + * Drop a reference of each kmod module in @list and releases the resources + * taken by the list itself. + * + * Returns: 0 + */ +int kmod_module_unref_list(struct kmod_list *list); -/* Removal flags */ -enum kmod_remove { - KMOD_REMOVE_FORCE = O_TRUNC, - KMOD_REMOVE_NOWAIT = O_NONBLOCK, /* always set */ - /* libkmod-only defines, not passed to kernel */ - KMOD_REMOVE_NOLOG = 1, -}; /* Insertion flags */ enum kmod_insert { @@ -352,9 +481,66 @@ enum kmod_filter { KMOD_FILTER_BUILTIN = 0x00002, }; -int kmod_module_remove_module(struct kmod_module *mod, unsigned int flags); +/** + * kmod_module_insert_module: + * @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. + * + * Insert a module in Linux kernel. It opens the file pointed by @mod, + * mmap'ing it and passing to kernel. + * + * Returns: 0 on success or < 0 on failure. If module is already loaded it + * returns -EEXIST. + */ int kmod_module_insert_module(struct kmod_module *mod, unsigned int flags, const char *options); + +/** + * kmod_module_probe_insert_module: + * @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. + * + * 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. + * + * Returns: 0 on success, > 0 if stopped by a reason given in @flags or < 0 on + * failure. + */ int kmod_module_probe_insert_module(struct kmod_module *mod, unsigned int flags, const char *extra_options, int (*run_install)(struct kmod_module *m, @@ -363,70 +549,461 @@ int kmod_module_probe_insert_module(struct kmod_module *mod, void (*print_action)(struct kmod_module *m, bool install, const char *options)); +/* Removal flags */ +enum kmod_remove { + KMOD_REMOVE_FORCE = O_TRUNC, + KMOD_REMOVE_NOWAIT = O_NONBLOCK, /* always set */ + /* libkmod-only defines, not passed to kernel */ + KMOD_REMOVE_NOLOG = 1, +}; + +/** + * kmod_module_remove_module: + * @mod: kmod module + * @flags: flags used when removing the module. + * KMOD_REMOVE_FORCE: force remove module regardless if it's still in + * use by a kernel subsystem or other process; passed directly to Linux kernel + * KMOD_REMOVE_NOWAIT: is always enforced, causing us to pass O_NONBLOCK to + * delete_module(2). + * KMOD_REMOVE_NOLOG: when module removal fails, do not log anything as the + * caller may want to handle retries and log when appropriate. + * + * Remove a module from Linux kernel. + * + * Returns: 0 on success or < 0 on failure. + */ +int kmod_module_remove_module(struct kmod_module *mod, unsigned int flags); + -const char *kmod_module_get_name(const struct kmod_module *mod); -const char *kmod_module_get_path(const struct kmod_module *mod); -const char *kmod_module_get_options(const struct kmod_module *mod); -const char *kmod_module_get_install_commands(const struct kmod_module *mod); -const char *kmod_module_get_remove_commands(const struct kmod_module *mod); +/** + * kmod_module_get_module: + * @entry: an entry in a list of kmod modules. + * + * 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. + * + * Returns: NULL on failure or the kmod_module contained in this list entry + * with its refcount incremented. + */ +struct kmod_module *kmod_module_get_module(const struct kmod_list *entry); + +/** + * kmod_module_get_dependencies: + * @mod: kmod module + * + * 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. + * + * Returns: NULL on failure. Otherwise it returns a list of kmod modules + * that can be released by calling kmod_module_unref_list(). + */ struct kmod_list *kmod_module_get_dependencies(const struct kmod_module *mod); + +/** + * kmod_module_get_softdeps: + * @mod: kmod module + * @pre: where to save the list of preceding soft dependencies. + * @post: where to save the list of post soft dependencies. + * + * 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(). + * + * Returns: 0 on success or < 0 otherwise. + */ int kmod_module_get_softdeps(const struct kmod_module *mod, struct kmod_list **pre, struct kmod_list **post); + +/* + * kmod_module_get_weakdeps: + * @mod: kmod module + * @weak: where to save the list of weak dependencies. + * + * 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(). + * + * Returns: 0 on success or < 0 otherwise. + */ int kmod_module_get_weakdeps(const struct kmod_module *mod, struct kmod_list **weak); -int kmod_module_get_filtered_blacklist(const struct kmod_ctx *ctx, - const struct kmod_list *input, - struct kmod_list **output) __attribute__ ((deprecated)); + +/** + * kmod_module_apply_filter + * @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 + * + * Given a list @input, this function filter it out by the filter mask + * and save it in @output. + * + * Returns: 0 on success or < 0 otherwise. @output is saved with the updated + * list. + */ int kmod_module_apply_filter(const struct kmod_ctx *ctx, enum kmod_filter filter_type, const struct kmod_list *input, struct kmod_list **output); +/** + * kmod_module_get_filtered_blacklist: + * @ctx: kmod library context + * @input: list of kmod_module to be filtered with blacklist + * @output: where to save the new list + * + * 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. + * + * Returns: 0 on success or < 0 otherwise. @output is saved with the updated + * list. + */ +int kmod_module_get_filtered_blacklist(const struct kmod_ctx *ctx, + const struct kmod_list *input, + struct kmod_list **output) __attribute__ ((deprecated)); +/** + * kmod_module_get_install_commands: + * @mod: kmod module + * + * 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. + * + * Returns: a string with all install commands separated by semicolons. This + * string is owned by @mod, do not free it. + */ +const char *kmod_module_get_install_commands(const struct kmod_module *mod); -/* - * Information regarding "live information" from module's state, as returned - * by kernel +/** + * kmod_module_get_remove_commands: + * @mod: kmod module + * + * 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. + * + * Returns: a string with all remove commands separated by semicolons. This + * string is owned by @mod, do not free it. */ +const char *kmod_module_get_remove_commands(const struct kmod_module *mod); -enum kmod_module_initstate { - KMOD_MODULE_BUILTIN = 0, - KMOD_MODULE_LIVE, - KMOD_MODULE_COMING, - KMOD_MODULE_GOING, - /* Padding to make sure enum is not mapped to char */ - _KMOD_MODULE_PAD = 1U << 31, -}; -const char *kmod_module_initstate_str(enum kmod_module_initstate state); -int kmod_module_get_initstate(const struct kmod_module *mod); -int kmod_module_get_refcnt(const struct kmod_module *mod); -struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod); +/** + * kmod_module_get_name: + * @mod: kmod module + * + * 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). + * + * Returns: the name of this kmod module. + */ +const char *kmod_module_get_name(const struct kmod_module *mod); + +/** + * kmod_module_get_options: + * @mod: kmod module + * + * 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. + * + * Returns: a string with all the options separated by spaces. This string is + * owned by @mod, do not free it. + */ +const char *kmod_module_get_options(const struct kmod_module *mod); + +/** + * kmod_module_get_path: + * @mod: kmod module + * + * 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. + * + * Returns: the path of this kmod module or NULL if such information is not + * available. + */ +const char *kmod_module_get_path(const struct kmod_module *mod); + + +/** + * kmod_module_get_dependency_symbols: + * @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() + * + * 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(). + * + * Returns: 0 on success or < 0 otherwise. + */ +int kmod_module_get_dependency_symbols(const struct kmod_module *mod, struct kmod_list **list); + +/** + * kmod_module_dependency_symbol_get_bind: + * @entry: a list entry representing a kmod module dependency_symbol + * + * Get the bind type of a kmod module dependency_symbol. + * + * Returns: the bind of this kmod module dependency_symbol on success + * or < 0 on failure. + */ +int kmod_module_dependency_symbol_get_bind(const struct kmod_list *entry); + +/** + * kmod_module_dependency_symbol_get_crc: + * @entry: a list entry representing a kmod module dependency_symbol + * + * Get the crc of a kmod module dependency_symbol. + * + * Returns: the crc of this kmod module dependency_symbol if available, otherwise default to 0. + */ +uint64_t kmod_module_dependency_symbol_get_crc(const struct kmod_list *entry); + +/** + * kmod_module_dependency_symbol_get_symbol: + * @entry: a list entry representing a kmod module dependency_symbols + * + * Get the dependency symbol of a kmod module + * + * 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. + */ +const char *kmod_module_dependency_symbol_get_symbol(const struct kmod_list *entry); + +/** + * kmod_module_dependency_symbols_free_list: + * @list: kmod module dependency_symbols list + * + * Release the resources taken by @list + */ +void kmod_module_dependency_symbols_free_list(struct kmod_list *list); + + +/** + * kmod_module_get_sections: + * @mod: kmod module + * + * 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(). + * + * Returns: a new list of kmod module sections on success or NULL on failure. + */ struct kmod_list *kmod_module_get_sections(const struct kmod_module *mod); -const char *kmod_module_section_get_name(const struct kmod_list *entry); + +/** + * kmod_module_section_get_address: + * @entry: a list entry representing a kmod module section + * + * Get the address of a kmod module section. + * + * After use, free the @list by calling kmod_module_section_free_list(). + * + * Returns: the address of this kmod module section on success or ULONG_MAX + * on failure. + */ unsigned long kmod_module_section_get_address(const struct kmod_list *entry); + +/** + * kmod_module_section_get_module_name: + * @entry: a list entry representing a kmod module section + * + * Get the name of a kmod module section. + * + * After use, free the @list by calling kmod_module_section_free_list(). + * + * 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. + */ +const char *kmod_module_section_get_name(const struct kmod_list *entry); + +/** + * kmod_module_section_free_list: + * @list: kmod module section list + * + * Release the resources taken by @list + */ void kmod_module_section_free_list(struct kmod_list *list); -long kmod_module_get_size(const struct kmod_module *mod); +/** + * kmod_module_get_symbols: + * @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() + * + * Get a list of entries in ELF section ".symtab" or "__ksymtab_strings". + * + * After use, free the @list by calling kmod_module_symbols_free_list(). + * + * Returns: 0 on success or < 0 otherwise. + */ +int kmod_module_get_symbols(const struct kmod_module *mod, struct kmod_list **list); + +/** + * kmod_module_symbol_get_crc: + * @entry: a list entry representing a kmod module symbol + * + * Get the crc of a kmod module symbol. + * + * Returns: the crc of this kmod module symbol if available, otherwise default to 0. + */ +uint64_t kmod_module_symbol_get_crc(const struct kmod_list *entry); + +/** + * kmod_module_symbol_get_symbol: + * @entry: a list entry representing a kmod module symbols + * + * Get the symbol of 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. + */ +const char *kmod_module_symbol_get_symbol(const struct kmod_list *entry); + +/** + * kmod_module_symbols_free_list: + * @list: kmod module symbols list + * + * Release the resources taken by @list + */ +void kmod_module_symbols_free_list(struct kmod_list *list); + /* * Information retrieved from ELF headers and sections */ +/** + * kmod_module_get_versions: + * @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() + * + * Get a list of entries in ELF section "__versions". + * + * After use, free the @list by calling kmod_module_versions_free_list(). + * + * Returns: 0 on success or < 0 otherwise. + */ +int kmod_module_get_versions(const struct kmod_module *mod, struct kmod_list **list); + +/** + * kmod_module_version_get_crc: + * @entry: a list entry representing a kmod module version + * + * Get the crc of a kmod module version. + * + * Returns: the crc of this kmod module version if available, otherwise default to 0. + */ +uint64_t kmod_module_version_get_crc(const struct kmod_list *entry); + +/** + * kmod_module_version_get_symbol: + * @entry: a list entry representing a kmod module versions + * + * Get the symbol of 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. + */ +const char *kmod_module_version_get_symbol(const struct kmod_list *entry); + +/** + * kmod_module_versions_free_list: + * @list: kmod module versions list + * + * Release the resources taken by @list + */ +void kmod_module_versions_free_list(struct kmod_list *list); + + +/** + * kmod_module_get_info: + * @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() + * + * 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(). + * + * Returns: number of entries in @list on success or < 0 otherwise. + */ int kmod_module_get_info(const struct kmod_module *mod, struct kmod_list **list); + +/** + * kmod_module_info_get_key: + * @entry: a list entry representing a kmod module info + * + * Get the key of 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. + */ const char *kmod_module_info_get_key(const struct kmod_list *entry); + +/** + * kmod_module_info_get_value: + * @entry: a list entry representing a kmod module info + * + * Get the value of 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. + */ const char *kmod_module_info_get_value(const struct kmod_list *entry); -void kmod_module_info_free_list(struct kmod_list *list); -int kmod_module_get_versions(const struct kmod_module *mod, struct kmod_list **list); -const char *kmod_module_version_get_symbol(const struct kmod_list *entry); -uint64_t kmod_module_version_get_crc(const struct kmod_list *entry); -void kmod_module_versions_free_list(struct kmod_list *list); +/** + * kmod_module_info_free_list: + * @list: kmod module info list + * + * Release the resources taken by @list + */ +void kmod_module_info_free_list(struct kmod_list *list); -int kmod_module_get_symbols(const struct kmod_module *mod, struct kmod_list **list); -const char *kmod_module_symbol_get_symbol(const struct kmod_list *entry); -uint64_t kmod_module_symbol_get_crc(const struct kmod_list *entry); -void kmod_module_symbols_free_list(struct kmod_list *list); enum kmod_symbol_bind { KMOD_SYMBOL_NONE = '\0', @@ -436,11 +1013,30 @@ enum kmod_symbol_bind { KMOD_SYMBOL_UNDEF = 'U' }; -int kmod_module_get_dependency_symbols(const struct kmod_module *mod, struct kmod_list **list); -const char *kmod_module_dependency_symbol_get_symbol(const struct kmod_list *entry); -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); -void kmod_module_dependency_symbols_free_list(struct kmod_list *list); + +int kmod_module_new_from_loaded(struct kmod_ctx *ctx, + struct kmod_list **list); + +/* + * Information regarding "live information" from module's state, as returned + * by kernel + */ + +enum kmod_module_initstate { + KMOD_MODULE_BUILTIN = 0, + KMOD_MODULE_LIVE, + KMOD_MODULE_COMING, + KMOD_MODULE_GOING, + /* Padding to make sure enum is not mapped to char */ + _KMOD_MODULE_PAD = 1U << 31, +}; +const char *kmod_module_initstate_str(enum kmod_module_initstate state); +int kmod_module_get_initstate(const struct kmod_module *mod); +long kmod_module_get_size(const struct kmod_module *mod); +int kmod_module_get_refcnt(const struct kmod_module *mod); +struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod); + + #ifdef __cplusplus } /* extern "C" */