From: Emil Velikov Date: Mon, 2 Sep 2024 22:20:18 +0000 (+0100) Subject: libkmod/docs: move libkmod(-core) section to the header X-Git-Tag: v34~444 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=480e0d40070dbca0307f5b759a27621588d28c82;p=thirdparty%2Fkmod.git libkmod/docs: move libkmod(-core) 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.c b/libkmod/libkmod.c index 86025514..d7e8d3fd 100644 --- a/libkmod/libkmod.c +++ b/libkmod/libkmod.c @@ -28,14 +28,6 @@ #define KMOD_LRU_MAX (128) #define _KMOD_INDEX_MODULES_SIZE KMOD_INDEX_MODULES_BUILTIN + 1 -/** - * SECTION:libkmod - * @short_description: libkmod context - * - * The context contains the default values for the library user, - * and is passed to all library operations. - */ - static const struct { const char *fn; const char *prefix; @@ -56,11 +48,6 @@ static const char *const default_config_paths[] = { NULL }; -/** - * kmod_ctx: - * - * Opaque object representing the library context. - */ struct kmod_ctx { int refcount; int log_priority; @@ -136,14 +123,6 @@ static void log_filep(void *data, vfprintf(fp, format, args); } - -/** - * kmod_get_dirname: - * @ctx: kmod library context - * - * Retrieve the absolute path used for linux modules in this context. The path - * is computed from the arguments to kmod_new(). - */ KMOD_EXPORT const char *kmod_get_dirname(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -152,15 +131,6 @@ KMOD_EXPORT const char *kmod_get_dirname(const struct kmod_ctx *ctx) return ctx->dirname; } -/** - * kmod_get_userdata: - * @ctx: kmod library context - * - * Retrieve stored data pointer from library context. This might be useful - * to access from callbacks. - * - * Returns: stored userdata - */ KMOD_EXPORT void *kmod_get_userdata(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -168,13 +138,6 @@ KMOD_EXPORT void *kmod_get_userdata(const struct kmod_ctx *ctx) return (void *)ctx->userdata; } -/** - * kmod_set_userdata: - * @ctx: kmod library context - * @userdata: data pointer - * - * Store custom @userdata in the library context. - */ KMOD_EXPORT void kmod_set_userdata(struct kmod_ctx *ctx, const void *userdata) { if (ctx == NULL) @@ -252,28 +215,6 @@ static enum kmod_file_compression_type get_kernel_compression(struct kmod_ctx *c return KMOD_FILE_COMPRESSION_NONE; } -/** - * kmod_new: - * @dirname: what to consider as linux module's directory, if NULL - * defaults to $MODULE_DIRECTORY/`uname -r`. If it's relative, - * it's treated as relative to the current working directory. - * Otherwise, give an absolute dirname. - * @config_paths: ordered array of paths (directories or files) where - * to load from user-defined configuration parameters such as - * alias, blacklists, commands (install, remove). If NULL - * defaults to /etc/modprobe.d, /run/modprobe.d, - * /usr/local/lib/modprobe.d, DISTCONFDIR/modprobe.d, and - * /lib/modprobe.d. Give an empty vector if configuration should - * not be read. This array must be null terminated. - * - * Create kmod library context. This reads the kmod configuration - * and fills in the default values. - * - * The initial refcount is 1, and needs to be decremented to - * release the resources of the kmod library context. - * - * Returns: a new kmod library context - */ KMOD_EXPORT struct kmod_ctx *kmod_new(const char *dirname, const char * const *config_paths) { @@ -329,14 +270,6 @@ fail: return NULL; } -/** - * kmod_ref: - * @ctx: kmod library context - * - * Take a reference of the kmod library context. - * - * Returns: the passed kmod library context - */ KMOD_EXPORT struct kmod_ctx *kmod_ref(struct kmod_ctx *ctx) { if (ctx == NULL) @@ -345,15 +278,6 @@ KMOD_EXPORT struct kmod_ctx *kmod_ref(struct kmod_ctx *ctx) return ctx; } -/** - * kmod_unref: - * @ctx: kmod library context - * - * Drop a reference of the kmod library context. If the refcount - * reaches zero, the resources of the context will be released. - * - * Returns: the passed kmod library context or NULL if it's freed - */ KMOD_EXPORT struct kmod_ctx *kmod_unref(struct kmod_ctx *ctx) { if (ctx == NULL) @@ -374,16 +298,6 @@ KMOD_EXPORT struct kmod_ctx *kmod_unref(struct kmod_ctx *ctx) return NULL; } -/** - * kmod_set_log_fn: - * @ctx: kmod library context - * @log_fn: function to be called for logging messages - * @data: data to pass to log function - * - * The built-in logging writes to stderr. It can be - * overridden by a custom function, to plug log messages - * into the user's logging functionality. - */ KMOD_EXPORT void kmod_set_log_fn(struct kmod_ctx *ctx, void (*log_fn)(void *data, int priority, const char *file, @@ -398,12 +312,6 @@ KMOD_EXPORT void kmod_set_log_fn(struct kmod_ctx *ctx, INFO(ctx, "custom logging function %p registered\n", log_fn); } -/** - * kmod_get_log_priority: - * @ctx: kmod library context - * - * Returns: the current logging priority - */ KMOD_EXPORT int kmod_get_log_priority(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -411,14 +319,6 @@ KMOD_EXPORT int kmod_get_log_priority(const struct kmod_ctx *ctx) return ctx->log_priority; } -/** - * kmod_set_log_priority: - * @ctx: kmod library context - * @priority: the new logging priority - * - * Set the current logging priority. The value controls which messages - * are logged. - */ KMOD_EXPORT void kmod_set_log_priority(struct kmod_ctx *ctx, int priority) { if (ctx == NULL) @@ -828,18 +728,6 @@ static bool is_cache_invalid(const char *path, unsigned long long stamp) return false; } -/** - * kmod_validate_resources: - * @ctx: kmod library context - * - * Check if indexes and configuration files changed on disk and the current - * context is not valid anymore. - * - * Returns: KMOD_RESOURCES_OK if resources are still valid, - * KMOD_RESOURCES_MUST_RELOAD if it's sufficient to call - * kmod_unload_resources() and kmod_load_resources() or - * KMOD_RESOURCES_MUST_RECREATE if @ctx must be re-created. - */ KMOD_EXPORT int kmod_validate_resources(struct kmod_ctx *ctx) { struct kmod_list *l; @@ -871,21 +759,6 @@ KMOD_EXPORT int kmod_validate_resources(struct kmod_ctx *ctx) return KMOD_RESOURCES_OK; } -/** - * kmod_load_resources: - * @ctx: kmod library context - * - * Load indexes and keep them open in @ctx. This way it's faster to lookup - * information within the indexes. If this function is not called before a - * search, the necessary index is always opened and closed. - * - * If user will do more than one or two lookups, insertions, deletions, most - * likely it's good to call this function first. Particularly in a daemon like - * udev that on boot issues hundreds of calls to lookup the index, calling - * this function will speedup the searches. - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_load_resources(struct kmod_ctx *ctx) { int ret = 0; @@ -926,21 +799,6 @@ KMOD_EXPORT int kmod_load_resources(struct kmod_ctx *ctx) return ret; } -/** - * kmod_unload_resources: - * @ctx: kmod library context - * - * Unload all the indexes. This will free the resources to maintain the index - * open and all subsequent searches will need to open and close the index. - * - * User is free to call kmod_load_resources() and kmod_unload_resources() as - * many times as wanted during the lifecycle of @ctx. For example, if a daemon - * knows that when starting up it will lookup a lot of modules, it could call - * kmod_load_resources() and after the first burst of searches is gone, it - * could free the resources by calling kmod_unload_resources(). - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT void kmod_unload_resources(struct kmod_ctx *ctx) { size_t i; @@ -957,23 +815,6 @@ KMOD_EXPORT void kmod_unload_resources(struct kmod_ctx *ctx) } } -/** - * kmod_dump_index: - * @ctx: kmod library context - * @type: index to dump, valid indexes are - * KMOD_INDEX_MODULES_DEP: index of module dependencies; - * KMOD_INDEX_MODULES_ALIAS: index of module aliases; - * KMOD_INDEX_MODULES_SYMBOL: index of symbol aliases; - * KMOD_INDEX_MODULES_BUILTIN_ALIAS: index of builtin module aliases. - * KMOD_INDEX_MODULES_BUILTIN: index of builtin module. - * @fd: file descriptor to dump index to - * - * Dump index to file descriptor. Note that this function doesn't use stdio.h - * so call fflush() before calling this function to be sure data is written in - * order. - * - * Returns: 0 on success or < 0 otherwise. - */ KMOD_EXPORT int kmod_dump_index(struct kmod_ctx *ctx, enum kmod_index type, int fd) { diff --git a/libkmod/libkmod.h b/libkmod/libkmod.h index 947a4bbc..3a699914 100644 --- a/libkmod/libkmod.h +++ b/libkmod/libkmod.h @@ -16,33 +16,110 @@ extern "C" { #endif +/** + * SECTION:libkmod + * @short_description: libkmod context + * + * The context contains the default values for the library user, + * and is passed to all library operations. + */ + /* * kmod_ctx * * library user context - reads the config and system * environment, user variables, allows custom logging */ + +/** + * kmod_ctx: + * + * Opaque object representing the library context. + */ struct kmod_ctx; + +/** + * kmod_new: + * @dirname: what to consider as linux module's directory, if NULL + * defaults to $MODULE_DIRECTORY/`uname -r`. If it's relative, + * it's treated as relative to the current working directory. + * Otherwise, give an absolute dirname. + * @config_paths: ordered array of paths (directories or files) where + * to load from user-defined configuration parameters such as + * alias, blacklists, commands (install, remove). If NULL + * defaults to /etc/modprobe.d, /run/modprobe.d, + * /usr/local/lib/modprobe.d, DISTCONFDIR/modprobe.d, and + * /lib/modprobe.d. Give an empty vector if configuration should + * not be read. This array must be null terminated. + * + * Create kmod library context. This reads the kmod configuration + * and fills in the default values. + * + * The initial refcount is 1, and needs to be decremented to + * release the resources of the kmod library context. + * + * Returns: a new kmod library context + */ struct kmod_ctx *kmod_new(const char *dirname, const char * const *config_paths); + +/** + * kmod_ref: + * @ctx: kmod library context + * + * Take a reference of the kmod library context. + * + * Returns: the passed kmod library context + */ struct kmod_ctx *kmod_ref(struct kmod_ctx *ctx); + +/** + * kmod_unref: + * @ctx: kmod library context + * + * Drop a reference of the kmod library context. If the refcount + * reaches zero, the resources of the context will be released. + * + * Returns: the passed kmod library context or NULL if it's freed + */ struct kmod_ctx *kmod_unref(struct kmod_ctx *ctx); -void kmod_set_log_fn(struct kmod_ctx *ctx, - void (*log_fn)(void *log_data, - int priority, const char *file, int line, - const char *fn, const char *format, - va_list args), - const void *data); -int kmod_get_log_priority(const struct kmod_ctx *ctx); -void kmod_set_log_priority(struct kmod_ctx *ctx, int priority); -void *kmod_get_userdata(const struct kmod_ctx *ctx); -void kmod_set_userdata(struct kmod_ctx *ctx, const void *userdata); -const char *kmod_get_dirname(const struct kmod_ctx *ctx); /* * Management of libkmod's resources */ + +/** + * kmod_load_resources: + * @ctx: kmod library context + * + * Load indexes and keep them open in @ctx. This way it's faster to lookup + * information within the indexes. If this function is not called before a + * search, the necessary index is always opened and closed. + * + * If user will do more than one or two lookups, insertions, deletions, most + * likely it's good to call this function first. Particularly in a daemon like + * udev that on boot issues hundreds of calls to lookup the index, calling + * this function will speedup the searches. + * + * Returns: 0 on success or < 0 otherwise. + */ int kmod_load_resources(struct kmod_ctx *ctx); + +/** + * kmod_unload_resources: + * @ctx: kmod library context + * + * Unload all the indexes. This will free the resources to maintain the index + * open and all subsequent searches will need to open and close the index. + * + * User is free to call kmod_load_resources() and kmod_unload_resources() as + * many times as wanted during the lifecycle of @ctx. For example, if a daemon + * knows that when starting up it will lookup a lot of modules, it could call + * kmod_load_resources() and after the first burst of searches is gone, it + * could free the resources by calling kmod_unload_resources(). + * + * Returns: 0 on success or < 0 otherwise. + */ void kmod_unload_resources(struct kmod_ctx *ctx); enum kmod_resources { @@ -50,6 +127,19 @@ enum kmod_resources { KMOD_RESOURCES_MUST_RELOAD = 1, KMOD_RESOURCES_MUST_RECREATE = 2, }; + +/** + * kmod_validate_resources: + * @ctx: kmod library context + * + * Check if indexes and configuration files changed on disk and the current + * context is not valid anymore. + * + * Returns: KMOD_RESOURCES_OK if resources are still valid, + * KMOD_RESOURCES_MUST_RELOAD if it's sufficient to call + * kmod_unload_resources() and kmod_load_resources() or + * KMOD_RESOURCES_MUST_RECREATE if @ctx must be re-created. + */ int kmod_validate_resources(struct kmod_ctx *ctx); enum kmod_index { @@ -61,9 +151,92 @@ enum kmod_index { /* Padding to make sure enum is not mapped to char */ _KMOD_INDEX_PAD = 1U << 31, }; + +/** + * kmod_dump_index: + * @ctx: kmod library context + * @type: index to dump, valid indexes are + * KMOD_INDEX_MODULES_DEP: index of module dependencies; + * KMOD_INDEX_MODULES_ALIAS: index of module aliases; + * KMOD_INDEX_MODULES_SYMBOL: index of symbol aliases; + * KMOD_INDEX_MODULES_BUILTIN_ALIAS: index of builtin module aliases. + * KMOD_INDEX_MODULES_BUILTIN: index of builtin module. + * @fd: file descriptor to dump index to + * + * Dump index to file descriptor. Note that this function doesn't use stdio.h + * so call fflush() before calling this function to be sure data is written in + * order. + * + * Returns: 0 on success or < 0 otherwise. + */ int kmod_dump_index(struct kmod_ctx *ctx, enum kmod_index type, int fd); +/** + * kmod_set_log_priority: + * @ctx: kmod library context + * @priority: the new logging priority + * + * Set the current logging priority. The value controls which messages + * are logged. + */ +void kmod_set_log_priority(struct kmod_ctx *ctx, int priority); + +/** + * kmod_get_log_priority: + * @ctx: kmod library context + * + * Returns: the current logging priority + */ +int kmod_get_log_priority(const struct kmod_ctx *ctx); + +/** + * kmod_set_log_fn: + * @ctx: kmod library context + * @log_fn: function to be called for logging messages + * @data: data to pass to log function + * + * The built-in logging writes to stderr. It can be + * overridden by a custom function, to plug log messages + * into the user's logging functionality. + */ +void kmod_set_log_fn(struct kmod_ctx *ctx, + void (*log_fn)(void *log_data, + int priority, const char *file, int line, + const char *fn, const char *format, + va_list args), + const void *data); + +/** + * kmod_set_userdata: + * @ctx: kmod library context + * @userdata: data pointer + * + * Store custom @userdata in the library context. + */ +void kmod_set_userdata(struct kmod_ctx *ctx, const void *userdata); + +/** + * kmod_get_userdata: + * @ctx: kmod library context + * + * Retrieve stored data pointer from library context. This might be useful + * to access from callbacks. + * + * Returns: stored userdata + */ +void *kmod_get_userdata(const struct kmod_ctx *ctx); + +/** + * kmod_get_dirname: + * @ctx: kmod library context + * + * Retrieve the absolute path used for linux modules in this context. The path + * is computed from the arguments to kmod_new(). + */ +const char *kmod_get_dirname(const struct kmod_ctx *ctx); + + /** * SECTION:libkmod-list