.\"     $NetBSD: dm.3,v 1.6 2016/01/22 22:12:40 dholland Exp $
.\"
.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Adam Hamsik.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.Dd January 22, 2016
.Dt DM 3
.Os
.Sh NAME
.Nm dm
.Nd device-mapper access manipulation library
.Sh LIBRARY
.Lb libdm
.Sh SYNOPSIS
.In dm.h
.Ft void
.Fn libdm_iter_destroy "libdm_iter_t libdm_iter"
.Ft int
.Fn libdm_task_run "libdm_task_t *libdm_task"
.Ft libdm_task_t
.Fn libdm_task_create "const char *command"
.Ft void
.Fn libdm_task_destroy "libdm_task_t libdm_task"
.Ft int
.Fn libdm_task_set_name "const char *name" "libdm_task_t libdm_task"
.Ft char *
.Fn libdm_task_get_name "libdm_task_t libdm_task"
.Ft int
.Fn libdm_task_set_uuid "const char *uuid" "libdm_task_t libdm_task"
.Ft char *
.Fn libdm_task_get_uuid "libdm_task_t libdm_task"
.Ft char *
.Fn libdm_task_get_command "libdm_task_t libdm_task"
.Ft int32_t
.Fn libdm_task_get_cmd_version "libdm_task_t libdm_task" "uint32_t *ver" "size_t size"
.Ft int
.Fn libdm_task_set_minor "uint32_t minor" "libdm_task_t libdm_task"
.Ft uint32_t
.Fn libdm_task_get_minor "libdm_task_t libdm_task"
.Ft int
.Fn libdm_task_set_flags "uint32_t flags" "libdm_task_t libdm_task"
.Ft uint32_t
.Fn libdm_task_get_flags "libdm_task_t libdm_task"
.Ft uint32_t
.Fn libdm_task_get_target_num "libdm_task_t libdm_task"
.Ft int32_t
.Fn libdm_task_get_open_num "libdm_task_t libdm_task"
.Ft uint32_t
.Fn libdm_task_get_event_num "libdm_task_t libdm_task"
.Ft int
.Fn libdm_task_set_cmd "libdm_cmd_t libdm_cmd" "libdm_task_t libdm_task"
.Ft libdm_cmd_t
.Fn libdm_task_get_cmd "libdm_task_t libdm_task"
.Ft libdm_cmd_t
.Fn libdm_cmd_create "void"
.Ft void
.Fn libdm_cmd_destroy "libdm_cmd_t libdm_cmd"
.Ft libdm_iter_t
.Fn libdm_cmd_iter_create "libdm_cmd_t libdm_cmd"
.Ft int
.Fn libdm_cmd_set_table "libdm_table_t libdm_table" "libdm_cmd_t libdm_cmd"
.Ft libdm_table_t
.Fn libdm_cmd_get_table "libdm_iter_t iter"
.Ft libdm_target_t
.Fn libdm_cmd_get_target "libdm_iter_t iter"
.Ft libdm_dev_t
.Fn libdm_cmd_get_dev "libdm_iter_t iter"
.Ft uint64_t
.Fn libdm_cmd_get_deps "libdm_iter_t libdm_iter"
.Ft libdm_table_t
.Fn libdm_table_create "void"
.Ft void
.Fn libdm_table_destroy "libdm_table_t libdm_table"
.Ft int
.Fn libdm_table_set_start "uint64_t start" "libdm_table_t libdm_table"
.Ft uint64_t
.Fn libdm_table_get_start "libdm_table_t libdm_table"
.Ft int
.Fn libdm_table_set_length "uint64_t length" "libdm_table_t libdm_table"
.Ft uint64_t
.Fn libdm_table_get_length "libdm_table_t libdm_table"
.Ft int
.Fn libdm_table_set_target "const char *name" "libdm_table_t libdm_table"
.Ft char *
.Fn libdm_table_get_target "libdm_table_t libdm_table"
.Ft int
.Fn libdm_table_set_params "const char *params" "libdm_table_t libdm_table"
.Ft char *
.Fn libdm_table_get_params "libdm_table_t libdm_table"
.Ft int32_t
.Fn libdm_table_get_status "libdm_table_t libdm_table"
.Ft void
.Fn libdm_target_destroy "libdm_target_t libdm_target"
.Ft char *
.Fn libdm_target_get_name "libdm_target_t libdm_target"
.Ft int32_t
.Fn libdm_target_get_version "libdm_target_t libdm_target" "uint32_t *ver" "size_t size"
.Ft void
.Fn libdm_dev_destroy "libdm_dev_t libdm_dev"
.Ft char *
.Fn libdm_dev_get_name "libdm_dev_t libdm_dev"
.Ft uint32_t
.Fn libdm_dev_get_minor "libdm_dev_t libdm_dev"
.Ft int
.Fn libdm_dev_set_newname "const char *newname" "libdm_cmd_t libdm_cmd"
.Sh DESCRIPTION
Every object in libdm has its own create and destroy routine.
.Bl -bullet -offset indent -compact
.It
libdm_task_t
.It
libdm_cmd_t
.It
libdm_table_t
.El
.Pp
Except
.Vt libdm_dev_t
which is received from kernel as list of physical devices on which
the logical device depends.
.Vt libdm_target_t
which is received from kernel as list of available targets to use.
.Vt libdm_iter_t
which is used as iteration counter for array entries in the task structure.
.Pp
Every object attribute in libdm can be set and gotten by appropriate routines,
therefore there always are set and get routines.
.Ss LIBDM TASK
The
.Fn libdm_task_create
function creates a libdm task dictionary with command string set to
.Fa command .
If
.Fa command
is
.Dv NULL ,
libdm_task_t is not created and the function returns
.Dv NULL .
.Pp
.Fn libdm_task_destroy
free all memory allocated to
.Fa libdm_task
by
.Fn libdm_task_create .
.Pp
.Fn libdm_task_run
Sends created
.Fa libdm_task
to kernel and receives new one as reply.
.Pp
List of attributes avaialable in
.Vt libdm_task_t :
.Bl -column -offset indent "DM_IOCTL_TARGET_COUNT" "Number of table entries" "XXX"
.It Sy Attribute Ta Sy Description Ta Sy Mode
.It Li DM_IOCTL_OPEN Ta Device open-count Ta Read-Only
.It Li DM_IOCTL_MINOR Ta Device minor number Ta Read-Write
.It Li DM_IOCTL_NAME Ta Device name Ta Read-Write
.It Li DM_IOCTL_UUID Ta Device uuid Ta Read-Write
.It Li DM_IOCTL_TARGET_COUNT Ta Number of table entries Ta Read-Only
.\".It Li DM_IOCTL_EVENT Ta Not implemented Ta not imp
.It Li DM_IOCTL_FLAGS Ta Device status flags Ta Read-Write
.El
.Pp
.Fn libdm_task_set_name
and
.Fn 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.
.Pp
.Fn libdm_task_set_uuid
and
.Fn 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.
.Pp
.Fn libdm_task_set_minor
and
.Fn 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.
.Pp
.Fn libdm_task_set_flags
and
.Fn libdm_task_get_flags
Set/fetch device status flags from the task dictionary.
.Pp
.Fn libdm_task_get_open_num
Fetch number of opened devices from the kernel and return them as count.
.Pp
.Fn libdm_task_get_target_num
Fetch number of opened devices from the kernel and return them as count.
.Pp
.Fn libdm_task_get_cmd_version
Get the version of the dm driver in the kernel as array
.Fa uint32_t *ver
of size
.Fa size .
.Fn libdm_task_set_cmd
and
.Fn libdm_task_get_cmd
Add and fetch cmd structure from
.Vt libdm_task_t .
.Vt 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.
.Ss LIBDM TASK CMD
The
.Fn libdm_cmd_create
function will allocate a cmd structure which can later be put in
to the task.
.Pp
.Fn libdm_cmd_destroy
will deallocate a previously allocated cmd structure.
.Pp
.Fn 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.
.Pp
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.
.Fn libdm_cmd_get_table
When the user creates a task with the "status" command, the kernel
sends cmd with a table in it.
.Pp
.Fn libdm_cmd_get_target
Get mapping target description from cmd.
Target contains target_name and target_version.
.Pp
.Fn libdm_cmd_get_dev
When user creates a task with the "info" command, the kernel sends
cmd with information about dm device to user.
.Pp
.Fn 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.
.Pp
Usually the device has more than one table entry in the device command.
Therefore cmd iterators are needed for
.Vt libdm_cmd_t ;
they can be created by the
.Fn libdm_cmd_iter_create
function.
.Ss 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.
.Pp
Example device table entry
.Dl 0 1024 linear /dev/wd1a 384
.Bl -column -offset indent "DM_TABLE_LENGTH" "Number of table entries"
.It Sy Attribute Ta Sy Description
.It Li DM_TABLE_TYPE Ta Used device mapper target
.It Li DM_TABLE_START Ta Device Logical start block
.It Li DM_TABLE_STAT Ta Is 1 if this is current active table
.It Li DM_TABLE_LENGTH Ta Logical length described by table
.It Li DM_TABLE_PARAMS Ta Params passed down to target
.El
.Pp
.Fn libdm_table_set_start
and
.Fn libdm_table_get_start
Set start table from
.Fa start
value to
.Fa libdm_table
argument.
Get routine will get the table start from kernel as
.Vt libdm_table .
.Pp
.Fn libdm_table_set_length
and
.Fn libdm_table_get_length
Set table length from
.Fa length
value to
.Fa libdm_table
argument.
Get routine will get the table length from kernel as
.Vt libdm_table .
.Pp
.Fn libdm_table_set_target
and
.Fn libdm_table_get_target
Set target name from
.Fa target
value to
.Fa libdm_table
argument.
The target must be actually present in the kernel, otherwise
.Fn libdm_task_run
will fail.
Get routine will get the table entry target from kernel as
.Vt libdm_table .
.Pp
.Fn libdm_table_set_params
and
.Fn libdm_table_get_params
Set table target parameter string from
.Fa params
argument to
.Fa 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
.Vt libdm_table .
.Pp
.Fn libdm_table_get_status
Get table status which can be Active/Inactive.
This tells if this table is actually used or not.
.Ss LIBDM_TARGET
.Fn libdm_target_destroy
Destroy target received from
.Vt libdm_cmd
with libdm_cmd_iter iterator.
.Pp
.Fn libdm_target_get_name
returns pointer to a string with available target name.
.Pp
.Fn lobdm_target_get_version
Sets argument
.Fa ver[3]
to a in-kernel loaded target version.
.Ss LIBDM_DEV
.Fn libdm_dev_destroy
Destroy device received from
.Vt libdm_cmd
with libdm_cmd_iter iterator.
.Pp
.Fn libdm_dev_get_name
Return pointer to a string with underlying device name from
.Vt libdm_dev_t
.Pp
.Fn libdm_dev_get_minor
Return underlying device minor number.
.Ss MISC
.Fn libdm_dev_set_newname
This routine will set new dm device name attribute to
.Fa newname .
User must then called libdm_task_run on this task to
change the device name.
.Sh RETURN VALUES
Upon success, all described functions return zero or
.Pf non- Dv NULL
pointer.
Otherwise, an error number will be returned to indicate the error.
.Sh SEE ALSO
.Xr dm 4
.Sh HISTORY
The
.Nm
was written and contributed to
.Nx
by
.An Adam Hamsik
and first appeared in
.Nx 6.0 .