397 lines
12 KiB
Groff
397 lines
12 KiB
Groff
.\" $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 .
|