libkmod

## libkmod libkmod — libkmod context |

## Synopsis

    struct              kmod_ctx;
    struct kmod_ctx *   kmod_new                            (const char *dirname,
                                                             const char * const *config_paths);
    struct kmod_ctx *   kmod_ref                            (struct kmod_ctx *ctx);
    struct kmod_ctx *   kmod_unref                          (struct kmod_ctx *ctx);
    int                 kmod_load_resources                 (struct kmod_ctx *ctx);
    void                kmod_unload_resources               (struct kmod_ctx *ctx);
    int                 kmod_validate_resources             (struct kmod_ctx *ctx);
    int                 kmod_dump_index                     (struct kmod_ctx *ctx,
                                                             enum kmod_index type,
                                                             int fd);
    void                kmod_set_log_priority               (struct kmod_ctx *ctx,
                                                             int priority);
    int                 kmod_get_log_priority               (const 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);
    void *              kmod_get_userdata                   (const struct kmod_ctx *ctx);
    void                kmod_set_userdata                   (struct kmod_ctx *ctx,
                                                             const void *userdata);

## Description

The context contains the default values for the library user, and is passed to all library operations.

## Details

### struct kmod_ctx

    struct kmod_ctx;

Opaque object representing the library context.

### kmod_new ()

    struct kmod_ctx *   kmod_new                            (const char *dirname,
                                                             const char * const *config_paths);

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.

`dirname` : | what to consider as linux module's directory, if NULL defaults to /lib/modules/`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 /run/modprobe.d, /etc/modprobe.d and /lib/modprobe.d. Give an empty vector if configuration should not be read. This array must be null terminated.
Returns : | a new kmod library context

### kmod_ref ()

    struct kmod_ctx *   kmod_ref                            (struct kmod_ctx *ctx);

Take a reference of the kmod library context.

`ctx` : | kmod library context
Returns : | the passed kmod library context

### kmod_unref ()

    struct kmod_ctx *   kmod_unref                          (struct kmod_ctx *ctx);

Drop a reference of the kmod library context. If the refcount reaches zero, the resources of the context will be released.

`ctx` : | kmod library context
Returns : | the passed kmod library context or NULL if it's freed

### kmod_load_resources ()

    int                 kmod_load_resources                 (struct kmod_ctx *ctx);

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 bootup issues hundreds of calls to lookup the index, calling this function will speedup the searches.

`ctx` : | kmod library context
Returns : | 0 on success or < 0 otherwise.

### kmod_unload_resources ()

    void                kmod_unload_resources               (struct kmod_ctx *ctx);

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

`ctx` : | kmod library context
Returns : | 0 on success or < 0 otherwise.

### kmod_validate_resources ()

    int                 kmod_validate_resources             (struct kmod_ctx *ctx);

Check if indexes and configuration files changed on disk and the current context is not valid anymore.

`ctx` : | kmod library context
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_dump_index ()

    int                 kmod_dump_index                     (struct kmod_ctx *ctx,
                                                             enum kmod_index type,
                                                             int fd);

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.

`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: index of builtin module.
`fd` : | file descriptor to dump index to
Returns : | 0 on success or < 0 otherwise.

### kmod_set_log_priority ()

    void                kmod_set_log_priority               (struct kmod_ctx *ctx,
                                                             int priority);

Set the current logging priority. The value controls which messages are logged.

`ctx` : | kmod library context
`priority` : | the new logging priority

### kmod_get_log_priority ()

    int                 kmod_get_log_priority               (const struct kmod_ctx *ctx);

`ctx` : | kmod library context
Returns : | the current logging priority

### kmod_set_log_fn ()

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

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.

`ctx` : | kmod library context
`log_fn` : | function to be called for logging messages
`data` : | data to pass to log function

### kmod_get_userdata ()

    void *              kmod_get_userdata                   (const struct kmod_ctx *ctx);

Retrieve stored data pointer from library context. This might be useful to access from callbacks.

`ctx` : | kmod library context
Returns : | stored userdata

### kmod_set_userdata ()

    void                kmod_set_userdata                   (struct kmod_ctx *ctx,
                                                             const void *userdata);

Store custom `userdata` in the library context.

`ctx` : | kmod library context
`userdata` : | data pointer