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.