NetBSD/lib/libdm/dm.3

.\"     $NetBSD: dm.3,v 1.1 2011/02/08 03:20:15 haad 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 Januar, 22
.Dt DM 3
.Os
.Sh NAME
.Nm libdm
.Nd device-mapper access manipulation library
.Sh LIBRARY
.Lb libdm
.Sh SYNOPSIS
.In libdm.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 have it's 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
logical device depends.
.Vt libdm_target_t
which is received from kernel as list of available targets for use .
.Vt libdm_iter_t
which is used as itteration counter for array entries in task structure.
.Pp
Every object attribute in libdm can be set and get by appropriate routines,
therofore there is always set and get routine.
.Pp
.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 function return
.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 receive 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 device for commands which need to have dm device identifier.
Device-mapper later uses device name to lookup device from list of all devices.
Get routine will fetch device name from task dictionary.
.Pp
.Fn libdm_task_set_uuid
and
.Fn libdm_task_get_uuid
Set uuid of device for commands which need to have dm device identifier.
Device-mapper later uses device uuid to lookup device from list of all devices.
Get routine will fetch device uuid from 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 dm device identifier.
Device-mapper later uses device minor number to lookup device from list of all devices.
Get routine will fetch device minor number from task dictionary.
.Pp
.Fn libdm_task_set_flags
and
.Fn libdm_task_get_flags
Set/Fetch device status flags from task dictionary.
.Pp
.Fn libdm_task_get_open_num
Fetch number of opened devices from kernel and return them as
.Rt count .
.Pp
.Fn libdm_task_get_target_num
Fetch number of opened devices from kernel and return them as
.Rt count .
.Pp
.Fn libdm_task_get_cmd_version
Get dm driver in kernel version and set is as array
.Fa uint32_t *ver
with
.Fa size
size.
.Fn libdm_task_set_cmd
and
.Fn libdm_task_get_cmd
Adds and fetches cmd structure from
.Vt libdm_task_t .
.Vt libdm_cmd_t
is container used to carry information specific for particular command.
cmd is ususaly set before libdm_task_run is used and is get from task structure
after task run was called.
.Ss LIBDM TASK CMD
The
.Fn libdm_cmd_create
will allocate cmd structure which can be later put in to the task.
.Pp
.Fn libdm_cmd_destroy
will deallocate cmd strucute previously allocated.
.Pp
.Fn libdm_cmd_set_table
Will load and fetch device mapping table from dm device. Table is usually
loaded to device during initial device creation or device resizing.
.Pp
Because libdm_cmd is and array of structures all _get routines needs an
iterator to work. For every entry we can have more than one.
.Fn libdm_cmd_get_table
When user creates task with  "status" command kernel sends cmd with 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 task with  "info" command kernel sends cmd with information
about dm device to user.
.Pp
.Fn libdm_cmd_get_deps
When user creates task with  "deps" command kernel sends cmd with array of
physical devices atatched to dm device.
.Pp
Usually device has more than one table entry in device command. Therefore cmd
iterators are needed for
.Vt libdm_cmd_t
they can be created by
.Fn libdm_cmd_iter_create
routine.
.SS LIBDM CMD TABLE
Device table decribe logical mapping between dm device and physical devices.
Every table has logical block start, table length (in disk blocks), target
used by table, physical device and offset on it. Physical device and offset
on it are parameters which are target specific and are passed down to target
as param string.
.Pp
.Fn
.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
Sets start table from
.Fa start
value to
.Fa libdm_table
argument. Get routine will get table start from kernel received in
.Vt libdm_table .
.Pp
.Fn libdm_table_set_length
and
.Fn libdm_table_get_length
Sets table length from
.Fa length
value to
.Fa libdm_table
argument. Get routine will get table length from kernel received in
.Vt libdm_table .
.Pp
.Fn libdm_table_set_target
and
.Fn libdm_table_get_target
Sets target name from
.Fa target
value to
.Fa libdm_table
argument. Target must be actually present in kernel otherwise libdm_task_run
will fail. Get routine will get table entry target from kernel received in
.Vt libdm_table .
.Pp
.Fn libdm_table_set_params
and
.Fn libdm_table_get_params
Set table target parameter string from
.Fa params
arrgument value to
.Fa libdm_table .
This is later in kernel passed to target init routine.
Get routine will get table parameter string from kernel received in
.Vt libdm_table .
.Pp
.Fn libdm_table_get_status
 Get table status which can be Active/Inactive which tells if this table
is actually used or not .
.Pp
.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
return pointer to string with available target name.
.Pp
.Fn lobdm_target_get_version
Sets argument
.Fa ver[3]
to a in kernel loaded target version.
.Pp
.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.
.Pp
.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 device name.
.Pp
.Sh RETURN VALUES
Upon success all described functions return zero or non NULL pointer.
Otherwise, an error number will be returned to indicate the error.
.Pp
.Sh SEE ALSO
.Xr dm 4
.Sh HISTORY
The
.Nm
was written and contributed to
.Nx
by Adam Hamsik and first appeared in
.Nx 6.0 .