DM(3) | Library Functions Manual | DM(3)

# NAME

`dm` —
device-mapper access manipulation library

# LIBRARY

Device Mapper Library (libdm, -ldm)

# SYNOPSIS

`#include <dm.h>`

void
`libdm_iter_destroy`(libdm_iter_t libdm_iter);

int
`libdm_task_run`(libdm_task_t *libdm_task);

libdm_task_t
`libdm_task_create`(const char *command);

void
`libdm_task_destroy`(libdm_task_t libdm_task);

int
`libdm_task_set_name`(const char *name, libdm_task_t libdm_task);

char *
`libdm_task_get_name`(libdm_task_t libdm_task);

int
`libdm_task_set_uuid`(const char *uuid, libdm_task_t libdm_task);

char *
`libdm_task_get_uuid`(libdm_task_t libdm_task);

char *
`libdm_task_get_command`(libdm_task_t libdm_task);

int32_t
`libdm_task_get_cmd_version`(libdm_task_t libdm_task, uint32_t *ver, size_t size);

int
`libdm_task_set_minor`(uint32_t minor, libdm_task_t libdm_task);

uint32_t
`libdm_task_get_minor`(libdm_task_t libdm_task);

int
`libdm_task_set_flags`(uint32_t flags, libdm_task_t libdm_task);

uint32_t
`libdm_task_get_flags`(libdm_task_t libdm_task);

uint32_t
`libdm_task_get_target_num`(libdm_task_t libdm_task);

int32_t
`libdm_task_get_open_num`(libdm_task_t libdm_task);

uint32_t
`libdm_task_get_event_num`(libdm_task_t libdm_task);

int
`libdm_task_set_cmd`(libdm_cmd_t libdm_cmd, libdm_task_t libdm_task);

libdm_cmd_t
`libdm_task_get_cmd`(libdm_task_t libdm_task);

libdm_cmd_t
`libdm_cmd_create`(void);

void
`libdm_cmd_destroy`(libdm_cmd_t libdm_cmd);

libdm_iter_t
`libdm_cmd_iter_create`(libdm_cmd_t libdm_cmd);

int
`libdm_cmd_set_table`(libdm_table_t libdm_table, libdm_cmd_t libdm_cmd);

libdm_table_t
`libdm_cmd_get_table`(libdm_iter_t iter);

libdm_target_t
`libdm_cmd_get_target`(libdm_iter_t iter);

libdm_dev_t
`libdm_cmd_get_dev`(libdm_iter_t iter);

uint64_t
`libdm_cmd_get_deps`(libdm_iter_t libdm_iter);

libdm_table_t
`libdm_table_create`(void);

void
`libdm_table_destroy`(libdm_table_t libdm_table);

int
`libdm_table_set_start`(uint64_t start, libdm_table_t libdm_table);

uint64_t
`libdm_table_get_start`(libdm_table_t libdm_table);

int
`libdm_table_set_length`(uint64_t length, libdm_table_t libdm_table);

uint64_t
`libdm_table_get_length`(libdm_table_t libdm_table);

int
`libdm_table_set_target`(const char *name, libdm_table_t libdm_table);

char *
`libdm_table_get_target`(libdm_table_t libdm_table);

int
`libdm_table_set_params`(const char *params, libdm_table_t libdm_table);

char *
`libdm_table_get_params`(libdm_table_t libdm_table);

int32_t
`libdm_table_get_status`(libdm_table_t libdm_table);

void
`libdm_target_destroy`(libdm_target_t libdm_target);

char *
`libdm_target_get_name`(libdm_target_t libdm_target);

int32_t
`libdm_target_get_version`(libdm_target_t libdm_target, uint32_t *ver, size_t size);

void
`libdm_dev_destroy`(libdm_dev_t libdm_dev);

char *
`libdm_dev_get_name`(libdm_dev_t libdm_dev);

uint32_t
`libdm_dev_get_minor`(libdm_dev_t libdm_dev);

int
`libdm_dev_set_newname`(const char *newname, libdm_cmd_t libdm_cmd);

# DESCRIPTION

Every object in libdm has its own create and destroy routine.

- libdm_task_t
- libdm_cmd_t
- libdm_table_t

Except libdm_dev_t which is received from kernel as list of physical devices on which the logical device depends. libdm_target_t which is received from kernel as list of available targets to use. libdm_iter_t which is used as iteration counter for array entries in the task structure.

Every object attribute in libdm can be set and gotten by appropriate routines, therefore there always are set and get routines.

## LIBDM TASK

The `libdm_task_create`() function creates a libdm task dictionary with command string set to command. If command is `NULL`, libdm_task_t is not created and the function returns `NULL`.

`libdm_task_destroy`() free all memory allocated to libdm_task by `libdm_task_create`().

`libdm_task_run`() Sends created libdm_task to kernel and receives new one as reply.

List of attributes avaialable in libdm_task_t:

Attribute | Description | Mode
`DM_IOCTL_OPEN` | Device open-count | Read-Only
`DM_IOCTL_MINOR` | Device minor number | Read-Write
`DM_IOCTL_NAME` | Device name | Read-Write
`DM_IOCTL_UUID` | Device uuid | Read-Write
`DM_IOCTL_TARGET_COUNT` | Number of table entries | Read-Only
`DM_IOCTL_FLAGS` | Device status flags | Read-Write

`libdm_task_set_name`() and `libdm_task_get_name`() Set name of the device for commands which need to have a dm device identifier. The device-mapper later uses the device name to look up the device from the list of all devices. The get routine will fetch the device name from the task dictionary.

`libdm_task_set_uuid`() and `libdm_task_get_uuid`() Set uuid of device for commands which need to have a dm device identifier. The device-mapper later uses the device uuid to look up the device from the list of all devices. The get routine will fetch the device uuid from the task dictionary.

`libdm_task_set_minor`() and `libdm_task_get_minor`() Set minor device number of device for commands which need to have a dm device identifier. The device-mapper later uses the device minor number to look up the device from the list of all devices. The get routine will fetch the device minor number from the task dictionary.

`libdm_task_set_flags`() and `libdm_task_get_flags`() Set/fetch device status flags from the task dictionary.

`libdm_task_get_open_num`() Fetch number of opened devices from the kernel and return them as count.

`libdm_task_get_target_num`() Fetch number of opened devices from the kernel and return them as count.

`libdm_task_get_cmd_version`() Get the version of the dm driver in the kernel as array uint32_t *ver of size size. `libdm_task_set_cmd`() and `libdm_task_get_cmd`() Add and fetch cmd structure from libdm_task_t. libdm_cmd_t is the container used to carry information specific for the particular command. cmd is usually set before libdm_task_run is used and is taken from the task structure after the task run was called.

## LIBDM TASK CMD

The `libdm_cmd_create`() function will allocate a cmd structure which can later be put in to the task.

`libdm_cmd_destroy`() will deallocate a previously allocated cmd structure.

`libdm_cmd_set_table`() Will load and fetch the device mapping table from the dm device. The table is usually loaded to the device during initial device creation or device resizing.

Because libdm_cmd is an array of structures, all _get routines need an iterator to work. For every entry we can have more than one. `libdm_cmd_get_table`() When the user creates a task with the "status" command, the kernel sends cmd with a table in it.

`libdm_cmd_get_target`() Get mapping target description from cmd. Target contains target_name and target_version.

`libdm_cmd_get_dev`() When user creates a task with the "info" command, the kernel sends cmd with information about dm device to user.

`libdm_cmd_get_deps`() When user creates a task with the "deps" command, the kernel sends cmd with an array of physical devices attached to the dm device.

Usually the device has more than one table entry in the device command. Therefore cmd iterators are needed for libdm_cmd_t; they can be created by the `libdm_cmd_iter_create`() function.

## LIBDM CMD TABLE

A device table describes the logical mapping between the dm device and physical devices. Every table has the logical block start, the table length (in disk blocks), the target used by table, the physical device, and the offset on it. The physical device and the offset on it are parameters which are target specific and are passed down to the target as param string.

Example device table entry

`0 1024 linear /dev/wd1a 384`

Attribute | Description
`DM_TABLE_TYPE` | Used device mapper target
`DM_TABLE_START` | Device Logical start block
`DM_TABLE_STAT` | Is 1 if this is current active table
`DM_TABLE_LENGTH` | Logical length described by table
`DM_TABLE_PARAMS` | Params passed down to target

`libdm_table_set_start`() and `libdm_table_get_start`() Set start table from start value to libdm_table argument. Get routine will get the table start from kernel as libdm_table.

`libdm_table_set_length`() and `libdm_table_get_length`() Set table length from length value to libdm_table argument. Get routine will get the table length from kernel as libdm_table.

`libdm_table_set_target`() and `libdm_table_get_target`() Set target name from target value to libdm_table argument. The target must be actually present in the kernel, otherwise `libdm_task_run`() will fail. Get routine will get the table entry target from kernel as libdm_table.

`libdm_table_set_params`() and `libdm_table_get_params`() Set table target parameter string from params argument to libdm_table. This is later in the kernel passed to the target init routine. Get routine will get the table parameter string from kernel as libdm_table.

`libdm_table_get_status`() Get table status which can be Active/Inactive. This tells if this table is actually used or not.

## LIBDM_TARGET

`libdm_target_destroy`() Destroy target received from libdm_cmd with libdm_cmd_iter iterator.

`libdm_target_get_name`() returns pointer to a string with available target name.

`lobdm_target_get_version`() Sets argument ver[3] to a in-kernel loaded target version.

## LIBDM_DEV

`libdm_dev_destroy`() Destroy device received from libdm_cmd with libdm_cmd_iter iterator.

`libdm_dev_get_name`() Return pointer to a string with underlying device name from libdm_dev_t

`libdm_dev_get_minor`() Return underlying device minor number.

## MISC

`libdm_dev_set_newname`() This routine will set new dm device name attribute to newname. User must then called libdm_task_run on this task to change the device name.

# RETURN VALUES

Upon success, all described functions return zero or non-`NULL` pointer. Otherwise, an error number will be returned to indicate the error.

# SEE ALSO

dm(4)

# HISTORY

The `dm` was written and contributed to NetBSD by Adam Hamsik and first appeared in NetBSD 6.0.

January 22, 2016 | NetBSD 9.1