libkmod

libkmod — libkmod context

Functions

struct kmod_ctx * kmod_new ()
struct kmod_ctx * kmod_ref ()
struct kmod_ctx * kmod_unref ()
int kmod_load_resources ()
void kmod_unload_resources ()
int kmod_validate_resources ()
int kmod_dump_index ()
void kmod_set_log_priority ()
int kmod_get_log_priority ()
void kmod_set_log_fn ()
void * kmod_get_userdata ()
void kmod_set_userdata ()
const char * kmod_get_dirname ()

Types and Values

Description

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

Functions

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.

Parameters

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.

 

Returns

a new kmod library context

Since: 1


kmod_ref ()

struct kmod_ctx *
kmod_ref (struct kmod_ctx *ctx);

Take a reference of the kmod library context.

Parameters

ctx

kmod library context

 

Returns

the passed kmod library context

Since: 1


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.

Parameters

ctx

kmod library context

 

Returns

the passed kmod library context or NULL if it's freed

Since: 1


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

Parameters

ctx

kmod library context

 

Returns

0 on success or < 0 otherwise.

Since: 1


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

Parameters

ctx

kmod library context

 

Returns

0 on success or < 0 otherwise.

Since: 1


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.

Parameters

ctx

kmod library context

 

Returns

the resources state, valid states are kmod_resources.

Since: 3


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.

Parameters

ctx

kmod library context

 

type

index to dump, valid indexes are kmod_index

 

fd

file descriptor to dump index to

 

Returns

0 on success or < 0 otherwise.

Since: 4


kmod_set_log_priority ()

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

Set the current logging priority, as defined in syslog.h(0P). The value controls which messages are logged.

Parameters

ctx

kmod library context

 

priority

the new logging priority

 

Since: 1


kmod_get_log_priority ()

int
kmod_get_log_priority (const struct kmod_ctx *ctx);

Get the current logging priority, as defined in syslog.h(0P).

Parameters

ctx

kmod library context

 

Returns

the current logging priority

Since: 1


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.

Parameters

ctx

kmod library context

 

log_fn

function to be called for logging messages

 

data

data to pass to log function

 

Since: 1


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.

Parameters

ctx

kmod library context

 

Returns

stored userdata

Since: 1


kmod_set_userdata ()

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

Store custom userdata in the library context.

Parameters

ctx

kmod library context

 

userdata

data pointer

 

Since: 1


kmod_get_dirname ()

const char *
kmod_get_dirname (const struct kmod_ctx *ctx);

Retrieve the absolute path used for linux modules in this context. The path is computed from the arguments to kmod_new().

Parameters

ctx

kmod library context

 

Since: 22

Types and Values

struct kmod_ctx

struct kmod_ctx;

Opaque object representing the library context.


enum kmod_resources

The validity state of the current libkmod resources, returned by kmod_validate_resources().

Members

KMOD_RESOURCES_OK

resources are valid

 

KMOD_RESOURCES_MUST_RELOAD

resources are not valid; to resolve call kmod_unload_resources() and kmod_load_resources()

 

KMOD_RESOURCES_MUST_RECREATE

resources are not valid; to resolve ctx must be re-created.

 

enum kmod_index

The (module) index type, used by kmod_dump_index().

Members

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

 

_KMOD_INDEX_PAD

DO NOT USE; padding to make sure enum is not mapped to char