From: Lucas De Marchi Date: Sat, 14 Jan 2012 14:09:34 +0000 (-0200) Subject: Update documentation with recent changes X-Git-Tag: v4~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2f47c7fae9be6d786eabf89ee4dc6585e779b641;p=thirdparty%2Fkmod.git Update documentation with recent changes --- diff --git a/libkmod/docs/libkmod-docs.xml b/libkmod/docs/libkmod-docs.xml index 20f07c57..8a8f139e 100644 --- a/libkmod/docs/libkmod-docs.xml +++ b/libkmod/docs/libkmod-docs.xml @@ -14,6 +14,7 @@ libkmod + diff --git a/libkmod/docs/libkmod-sections.txt b/libkmod/docs/libkmod-sections.txt index afce8994..445206c8 100644 --- a/libkmod/docs/libkmod-sections.txt +++ b/libkmod/docs/libkmod-sections.txt @@ -26,6 +26,21 @@ kmod_list_next kmod_list_prev +
+libkmod-config +kmod_config_iter +kmod_config_get_blacklists +kmod_config_get_install_commands +kmod_config_get_remove_commands +kmod_config_get_aliases +kmod_config_get_options +kmod_config_get_softdeps +kmod_config_iter_get_key +kmod_config_iter_get_value +kmod_config_iter_next +kmod_config_iter_free_iter +
+
libkmod-module kmod_module diff --git a/libkmod/libkmod-config.c b/libkmod/libkmod-config.c index c69da1cb..c1da16fc 100644 --- a/libkmod/libkmod-config.c +++ b/libkmod/libkmod-config.c @@ -986,6 +986,23 @@ static struct kmod_config_iter *kmod_config_iter_new(const struct kmod_ctx* ctx, return iter; } +/** + * SECTION:libkmod-config + * @short_description: retrieve current libkmod configuration + */ + +/** + * kmod_config_get_blacklists: + * @ctx: kmod library context + * + * Retrieve an iterator to deal with the blacklist maintained inside the + * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and + * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must + * be made to initialize the iterator and check if it's valid. + * + * Returns: a new iterator over the blacklists or %NULL on failure. Free it + * with kmod_config_iter_free_iter(). + */ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_blacklists(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -994,6 +1011,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_blacklists(const struct kmo return kmod_config_iter_new(ctx, CONFIG_TYPE_BLACKLIST); } +/** + * kmod_config_get_install_commands: + * @ctx: kmod library context + * + * Retrieve an iterator to deal with the install commands maintained inside the + * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and + * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must + * be made to initialize the iterator and check if it's valid. + * + * Returns: a new iterator over the install commands or %NULL on failure. Free + * it with kmod_config_iter_free_iter(). + */ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_install_commands(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -1002,6 +1031,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_install_commands(const stru return kmod_config_iter_new(ctx, CONFIG_TYPE_INSTALL); } +/** + * kmod_config_get_remove_commands: + * @ctx: kmod library context + * + * Retrieve an iterator to deal with the remove commands maintained inside the + * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and + * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must + * be made to initialize the iterator and check if it's valid. + * + * Returns: a new iterator over the remove commands or %NULL on failure. Free + * it with kmod_config_iter_free_iter(). + */ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_remove_commands(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -1010,6 +1051,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_remove_commands(const struc return kmod_config_iter_new(ctx, CONFIG_TYPE_REMOVE); } +/** + * kmod_config_get_aliases: + * @ctx: kmod library context + * + * Retrieve an iterator to deal with the aliases maintained inside the + * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and + * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must + * be made to initialize the iterator and check if it's valid. + * + * Returns: a new iterator over the aliases or %NULL on failure. Free it with + * kmod_config_iter_free_iter(). + */ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_aliases(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -1018,6 +1071,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_aliases(const struct kmod_c return kmod_config_iter_new(ctx, CONFIG_TYPE_ALIAS); } +/** + * kmod_config_get_options: + * @ctx: kmod library context + * + * Retrieve an iterator to deal with the options maintained inside the + * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and + * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must + * be made to initialize the iterator and check if it's valid. + * + * Returns: a new iterator over the options or %NULL on failure. Free it with + * kmod_config_iter_free_iter(). + */ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_options(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -1026,6 +1091,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_options(const struct kmod_c return kmod_config_iter_new(ctx, CONFIG_TYPE_OPTION); } +/** + * kmod_config_get_softdeps: + * @ctx: kmod library context + * + * Retrieve an iterator to deal with the softdeps maintained inside the + * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and + * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must + * be made to initialize the iterator and check if it's valid. + * + * Returns: a new iterator over the softdeps or %NULL on failure. Free it with + * kmod_config_iter_free_iter(). + */ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_softdeps(const struct kmod_ctx *ctx) { if (ctx == NULL) @@ -1034,6 +1111,16 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_softdeps(const struct kmod_ return kmod_config_iter_new(ctx, CONFIG_TYPE_SOFTDEP); } +/** + * kmod_config_iter_get_key: + * @iter: iterator over a certain configuration + * + * When using a new allocated iterator, user must perform a call to + * kmod_config_iter_next() to initialize iterator's position and check if it's + * valid. + * + * Returns: the key of the current configuration pointed by @iter. + */ KMOD_EXPORT const char *kmod_config_iter_get_key(const struct kmod_config_iter *iter) { if (iter == NULL || iter->curr == NULL) @@ -1042,6 +1129,16 @@ KMOD_EXPORT const char *kmod_config_iter_get_key(const struct kmod_config_iter * return iter->get_key(iter->curr); } +/** + * kmod_config_iter_get_value: + * @iter: iterator over a certain configuration + * + * When using a new allocated iterator, user must perform a call to + * kmod_config_iter_next() to initialize iterator's position and check if it's + * valid. + * + * Returns: the value of the current configuration pointed by @iter. + */ KMOD_EXPORT const char *kmod_config_iter_get_value(const struct kmod_config_iter *iter) { const char *s; @@ -1063,6 +1160,18 @@ KMOD_EXPORT const char *kmod_config_iter_get_value(const struct kmod_config_iter return s; } +/** + * kmod_config_iter_next: + * @iter: iterator over a certain configuration + * + * Make @iter point to the next item of a certain configuration. It's an + * automatically recycling iterator. When it reaches the end, false is + * returned; then if user wants to iterate again, it's sufficient to call this + * function once more. + * + * Returns: true if next position of @iter is valid or false if its end is + * reached. + */ KMOD_EXPORT bool kmod_config_iter_next(struct kmod_config_iter *iter) { if (iter == NULL) @@ -1078,6 +1187,12 @@ KMOD_EXPORT bool kmod_config_iter_next(struct kmod_config_iter *iter) return iter->curr != NULL; } +/** + * kmod_config_iter_free_iter: + * @iter: iterator over a certain configuration + * + * Free resources used by the iterator. + */ KMOD_EXPORT void kmod_config_iter_free_iter(struct kmod_config_iter *iter) { free(iter->data); diff --git a/libkmod/libkmod.c b/libkmod/libkmod.c index 30f9da95..896efb98 100644 --- a/libkmod/libkmod.c +++ b/libkmod/libkmod.c @@ -183,13 +183,16 @@ static char *get_kernel_release(const char *dirname) /** * kmod_new: * @dirname: what to consider as linux module's directory, if NULL - * defaults to $rootprefix/lib/modules/`uname -r`. + * defaults to $rootprefix/lib/modules/`uname -r`. If it's relative, + * it's treated as relative to current 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 /run/modprobe.d, /etc/modprobe.d and - * $rootprefix/lib/modprobe.d. Give an empty vector if configuration should - * not be read. This array must be null terminated. + * $rootprefix/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.