| DM(3) | Library Functions Manual | DM(3) | 
dm —
#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);
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_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_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.
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_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_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.
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.
NULL pointer. Otherwise, an error number will be
  returned to indicate the error.
dm was written and contributed to
  NetBSD by Adam Hamsik and
  first appeared in NetBSD 6.0.
| January 22, 2016 | NetBSD 9.3 |