libnl Documentation

Remarks

Allocation of Caches

Almost all subsystem provide a function to allocate a new cache of some form. The function usually looks like this:

 struct nl_cache *<object name>_alloc_cache(struct nl_handle *handle)

These functions allocate a new cache for the own object type, initializes it properly and updates it to represent the current state of their master, e.g. a link cache would include all links currently configured in the kernel.

Some of the allocation functions may take additional arguments to further specify what will be part of the cache.

All such functions return a newly allocated cache or NULL in case of an error.

Setting of Addresses

 int <object name>_set_addr(struct nl_object *, struct nl_addr *)

All attribute functions avaiable for assigning addresses to objects take a struct nl_addr argument. The provided address object is validated against the address family of the object if known already. The assignment fails if the address families mismatch. In case the address family has not been specified yet, the address family of the new address is elected to be the new requirement.

The function will acquire a new reference on the address object before assignment, the caller is NOT responsible for this.

All functions return 0 on success or a negative error code.

Flags to Character StringTranslations

All functions converting a set of flags to a character string follow the same principles, therefore, the following information applies to all functions convertings flags to a character string and vice versa.

Flags to Character String

 char *<object name>_flags2str(int flags, char *buf, size_t len)

Parameters:

flags	Flags.
buf	Destination buffer.
len	Buffer length.

Converts the specified flags to a character string separated by commas and stores it in the specified destination buffer.

Returns:

The destination buffer

Character String to Flags

 int <object name>_str2flags(const char *name)

Parameters:

name	Name of flag.

Converts the provided character string specifying a flag to the corresponding numeric value.

Returns:

Link flag or a negative value if none was found.

Type to Character String

 char *<object name>_<type>2str(int type, char *buf, size_t len)

Parameters:

type	Type as numeric value
buf	Destination buffer.
len	Buffer length.

Converts an identifier (type) to a character string and stores it in the specified destination buffer.

Returns:

The destination buffer or the type encoded in hexidecimal form if the identifier is unknown.

Character String to Type

 int <object name>_str2<type>(const char *name)

Parameters:

name	Name of identifier (type).

Converts the provided character string specifying a identifier to the corresponding numeric value.

Returns:

Identifier as numeric value or a negative value if none was found.