\"     $NetBSD: dm.3,v 1.7 2022/09/10 12:14:17 rillig 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 available 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 libdm_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 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.