[BACK]Return to dm.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libdm

Annotation of src/lib/libdm/dm.3, Revision 1.5

1.5     ! wiz         1: .\"     $NetBSD: dm.3,v 1.4 2011/02/28 23:23:08 haad Exp $
1.1       haad        2: .\"
                      3: .\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Adam Hamsik.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     21: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     28: .\" POSSIBILITY OF SUCH DAMAGE.
1.2       wiz        29: .Dd January 22, 2011
1.1       haad       30: .Dt DM 3
                     31: .Os
                     32: .Sh NAME
1.4       haad       33: .Nm dm
1.1       haad       34: .Nd device-mapper access manipulation library
                     35: .Sh LIBRARY
                     36: .Lb libdm
                     37: .Sh SYNOPSIS
                     38: .In libdm.h
                     39: .Ft void
                     40: .Fn libdm_iter_destroy "libdm_iter_t libdm_iter"
                     41: .Ft int
                     42: .Fn libdm_task_run "libdm_task_t *libdm_task"
                     43: .Ft libdm_task_t
                     44: .Fn libdm_task_create "const char *command"
                     45: .Ft void
                     46: .Fn libdm_task_destroy "libdm_task_t libdm_task"
                     47: .Ft int
                     48: .Fn libdm_task_set_name "const char *name" "libdm_task_t libdm_task"
                     49: .Ft char *
                     50: .Fn libdm_task_get_name "libdm_task_t libdm_task"
                     51: .Ft int
                     52: .Fn libdm_task_set_uuid "const char *uuid" "libdm_task_t libdm_task"
                     53: .Ft char *
                     54: .Fn libdm_task_get_uuid "libdm_task_t libdm_task"
                     55: .Ft char *
                     56: .Fn libdm_task_get_command "libdm_task_t libdm_task"
                     57: .Ft int32_t
                     58: .Fn libdm_task_get_cmd_version "libdm_task_t libdm_task" "uint32_t *ver" "size_t size"
                     59: .Ft int
                     60: .Fn libdm_task_set_minor "uint32_t minor" "libdm_task_t libdm_task"
                     61: .Ft uint32_t
                     62: .Fn libdm_task_get_minor "libdm_task_t libdm_task"
                     63: .Ft int
                     64: .Fn libdm_task_set_flags "uint32_t flags" "libdm_task_t libdm_task"
                     65: .Ft uint32_t
                     66: .Fn libdm_task_get_flags "libdm_task_t libdm_task"
                     67: .Ft uint32_t
                     68: .Fn libdm_task_get_target_num "libdm_task_t libdm_task"
                     69: .Ft int32_t
                     70: .Fn libdm_task_get_open_num "libdm_task_t libdm_task"
                     71: .Ft uint32_t
                     72: .Fn libdm_task_get_event_num "libdm_task_t libdm_task"
                     73: .Ft int
                     74: .Fn libdm_task_set_cmd "libdm_cmd_t libdm_cmd" "libdm_task_t libdm_task"
                     75: .Ft libdm_cmd_t
                     76: .Fn libdm_task_get_cmd "libdm_task_t libdm_task"
                     77: .Ft libdm_cmd_t
                     78: .Fn libdm_cmd_create "void"
                     79: .Ft void
                     80: .Fn libdm_cmd_destroy "libdm_cmd_t libdm_cmd"
                     81: .Ft libdm_iter_t
                     82: .Fn libdm_cmd_iter_create "libdm_cmd_t libdm_cmd"
                     83: .Ft int
                     84: .Fn libdm_cmd_set_table "libdm_table_t libdm_table" "libdm_cmd_t libdm_cmd"
                     85: .Ft libdm_table_t
                     86: .Fn libdm_cmd_get_table "libdm_iter_t iter"
                     87: .Ft libdm_target_t
                     88: .Fn libdm_cmd_get_target "libdm_iter_t iter"
                     89: .Ft libdm_dev_t
                     90: .Fn libdm_cmd_get_dev "libdm_iter_t iter"
                     91: .Ft uint64_t
                     92: .Fn libdm_cmd_get_deps "libdm_iter_t libdm_iter"
                     93: .Ft libdm_table_t
                     94: .Fn libdm_table_create "void"
                     95: .Ft void
                     96: .Fn libdm_table_destroy "libdm_table_t libdm_table"
                     97: .Ft int
                     98: .Fn libdm_table_set_start "uint64_t start" "libdm_table_t libdm_table"
                     99: .Ft uint64_t
                    100: .Fn libdm_table_get_start "libdm_table_t libdm_table"
                    101: .Ft int
                    102: .Fn libdm_table_set_length "uint64_t length" "libdm_table_t libdm_table"
                    103: .Ft uint64_t
                    104: .Fn libdm_table_get_length "libdm_table_t libdm_table"
                    105: .Ft int
                    106: .Fn libdm_table_set_target "const char *name" "libdm_table_t libdm_table"
                    107: .Ft char *
                    108: .Fn libdm_table_get_target "libdm_table_t libdm_table"
                    109: .Ft int
1.4       haad      110: .Fn libdm_table_set_params "const char *params" "libdm_table_t libdm_table"
1.1       haad      111: .Ft char *
1.4       haad      112: .Fn libdm_table_get_params "libdm_table_t libdm_table"
1.1       haad      113: .Ft int32_t
                    114: .Fn libdm_table_get_status "libdm_table_t libdm_table"
                    115: .Ft void
                    116: .Fn libdm_target_destroy "libdm_target_t libdm_target"
                    117: .Ft char *
                    118: .Fn libdm_target_get_name "libdm_target_t libdm_target"
                    119: .Ft int32_t
                    120: .Fn libdm_target_get_version "libdm_target_t libdm_target" "uint32_t *ver" "size_t size"
                    121: .Ft void
                    122: .Fn libdm_dev_destroy "libdm_dev_t libdm_dev"
                    123: .Ft char *
                    124: .Fn libdm_dev_get_name "libdm_dev_t libdm_dev"
                    125: .Ft uint32_t
                    126: .Fn libdm_dev_get_minor "libdm_dev_t libdm_dev"
                    127: .Ft int
                    128: .Fn libdm_dev_set_newname "const char *newname" "libdm_cmd_t libdm_cmd"
                    129: .Sh DESCRIPTION
1.2       wiz       130: Every object in libdm has its own create and destroy routine.
1.1       haad      131: .Bl -bullet -offset indent -compact
                    132: .It
                    133: libdm_task_t
                    134: .It
                    135: libdm_cmd_t
                    136: .It
                    137: libdm_table_t
                    138: .El
                    139: .Pp
                    140: Except
                    141: .Vt libdm_dev_t
                    142: which is received from kernel as list of physical devices on which
1.2       wiz       143: the logical device depends.
1.1       haad      144: .Vt libdm_target_t
1.2       wiz       145: which is received from kernel as list of available targets to use.
1.1       haad      146: .Vt libdm_iter_t
1.2       wiz       147: which is used as iteration counter for array entries in the task structure.
1.1       haad      148: .Pp
1.2       wiz       149: Every object attribute in libdm can be set and gotten by appropriate routines,
                    150: therefore there always are set and get routines.
1.1       haad      151: .Ss LIBDM TASK
                    152: The
                    153: .Fn libdm_task_create
                    154: function creates a libdm task dictionary with command string set to
                    155: .Fa command .
                    156: If
                    157: .Fa command
                    158: is
                    159: .Dv NULL ,
1.2       wiz       160: libdm_task_t is not created and the function returns
1.1       haad      161: .Dv NULL .
                    162: .Pp
                    163: .Fn libdm_task_destroy
                    164: free all memory allocated to
                    165: .Fa libdm_task
                    166: by
                    167: .Fn libdm_task_create .
                    168: .Pp
                    169: .Fn libdm_task_run
                    170: Sends created
                    171: .Fa libdm_task
1.2       wiz       172: to kernel and receives new one as reply.
1.1       haad      173: .Pp
                    174: List of attributes avaialable in
                    175: .Vt libdm_task_t :
                    176: .Bl -column -offset indent "DM_IOCTL_TARGET_COUNT" "Number of table entries" "XXX"
                    177: .It Sy Attribute Ta Sy Description Ta Sy Mode
                    178: .It Li DM_IOCTL_OPEN Ta Device open-count Ta Read-Only
                    179: .It Li DM_IOCTL_MINOR Ta Device minor number Ta Read-Write
                    180: .It Li DM_IOCTL_NAME Ta Device name Ta Read-Write
                    181: .It Li DM_IOCTL_UUID Ta Device uuid Ta Read-Write
                    182: .It Li DM_IOCTL_TARGET_COUNT Ta Number of table entries Ta Read-Only
                    183: .\".It Li DM_IOCTL_EVENT Ta Not implemented Ta not imp
                    184: .It Li DM_IOCTL_FLAGS Ta Device status flags Ta Read-Write
                    185: .El
                    186: .Pp
                    187: .Fn libdm_task_set_name
                    188: and
                    189: .Fn libdm_task_get_name
1.2       wiz       190: Set name of the device for commands which need to have a dm device
                    191: identifier.
                    192: The device-mapper later uses the device name to look up the device
                    193: from the list of all devices.
                    194: The get routine will fetch the device name from the task dictionary.
1.1       haad      195: .Pp
                    196: .Fn libdm_task_set_uuid
                    197: and
                    198: .Fn libdm_task_get_uuid
1.2       wiz       199: Set uuid of device for commands which need to have a dm device
                    200: identifier.
                    201: The device-mapper later uses the device uuid to look up the device
                    202: from the list of all devices.
                    203: The get routine will fetch the device uuid from the task dictionary.
1.1       haad      204: .Pp
                    205: .Fn libdm_task_set_minor
                    206: and
                    207: .Fn libdm_task_get_minor
1.2       wiz       208: Set minor device number of device for commands which need to have
                    209: a dm device identifier.
                    210: The device-mapper later uses the device minor number to look up
                    211: the device from the list of all devices.
                    212: The get routine will fetch the device minor number from the task
                    213: dictionary.
1.1       haad      214: .Pp
                    215: .Fn libdm_task_set_flags
                    216: and
                    217: .Fn libdm_task_get_flags
1.2       wiz       218: Set/fetch device status flags from the task dictionary.
1.1       haad      219: .Pp
                    220: .Fn libdm_task_get_open_num
1.5     ! wiz       221: Fetch number of opened devices from the kernel and return them as count.
1.1       haad      222: .Pp
                    223: .Fn libdm_task_get_target_num
1.5     ! wiz       224: Fetch number of opened devices from the kernel and return them as count.
1.1       haad      225: .Pp
                    226: .Fn libdm_task_get_cmd_version
1.2       wiz       227: Get the version of the dm driver in the kernel as array
1.1       haad      228: .Fa uint32_t *ver
1.2       wiz       229: of size
                    230: .Fa size .
1.1       haad      231: .Fn libdm_task_set_cmd
                    232: and
                    233: .Fn libdm_task_get_cmd
1.2       wiz       234: Add and fetch cmd structure from
1.1       haad      235: .Vt libdm_task_t .
                    236: .Vt libdm_cmd_t
1.2       wiz       237: is the container used to carry information specific for the particular
                    238: command.
                    239: cmd is usually set before libdm_task_run is used and is taken from
                    240: the task structure after the task run was called.
1.1       haad      241: .Ss LIBDM TASK CMD
                    242: The
                    243: .Fn libdm_cmd_create
1.2       wiz       244: function will allocate a cmd structure which can later be put in
                    245: to the task.
1.1       haad      246: .Pp
                    247: .Fn libdm_cmd_destroy
1.2       wiz       248: will deallocate a previously allocated cmd structure.
1.1       haad      249: .Pp
                    250: .Fn libdm_cmd_set_table
1.2       wiz       251: Will load and fetch the device mapping table from the dm device.
                    252: The table is usually loaded to the device during initial device
                    253: creation or device resizing.
                    254: .Pp
                    255: Because libdm_cmd is an array of structures, all _get routines need an
                    256: iterator to work.
                    257: For every entry we can have more than one.
1.1       haad      258: .Fn libdm_cmd_get_table
1.2       wiz       259: When the user creates a task with the "status" command, the kernel
                    260: sends cmd with a table in it.
1.1       haad      261: .Pp
                    262: .Fn libdm_cmd_get_target
1.2       wiz       263: Get mapping target description from cmd.
                    264: Target contains target_name and target_version.
1.1       haad      265: .Pp
                    266: .Fn libdm_cmd_get_dev
1.2       wiz       267: When user creates a task with the "info" command, the kernel sends
                    268: cmd with information about dm device to user.
1.1       haad      269: .Pp
                    270: .Fn libdm_cmd_get_deps
1.2       wiz       271: When user creates a task with the "deps" command, the kernel sends
                    272: cmd with an array of physical devices attached to the dm device.
1.1       haad      273: .Pp
1.2       wiz       274: Usually the device has more than one table entry in the device command.
                    275: Therefore cmd iterators are needed for
                    276: .Vt libdm_cmd_t ;
                    277: they can be created by the
1.1       haad      278: .Fn libdm_cmd_iter_create
1.2       wiz       279: function.
1.3       njoly     280: .Ss LIBDM CMD TABLE
1.2       wiz       281: A device table describes the logical mapping between the dm device and
                    282: physical devices.
                    283: Every table has the logical block start, the table length (in disk
                    284: blocks), the target used by table, the physical device, and the
                    285: offset on it.
                    286: The physical device and the offset on it are parameters which are
                    287: target specific and are passed down to the target as param string.
1.1       haad      288: .Pp
                    289: Example device table entry
                    290: .Dl 0 1024 linear /dev/wd1a 384
                    291: .Bl -column -offset indent "DM_TABLE_LENGTH" "Number of table entries"
                    292: .It Sy Attribute Ta Sy Description
                    293: .It Li DM_TABLE_TYPE Ta Used device mapper target
                    294: .It Li DM_TABLE_START Ta Device Logical start block
                    295: .It Li DM_TABLE_STAT Ta Is 1 if this is current active table
                    296: .It Li DM_TABLE_LENGTH Ta Logical length described by table
                    297: .It Li DM_TABLE_PARAMS Ta Params passed down to target
                    298: .El
                    299: .Pp
                    300: .Fn libdm_table_set_start
                    301: and
                    302: .Fn libdm_table_get_start
1.2       wiz       303: Set start table from
1.1       haad      304: .Fa start
                    305: value to
                    306: .Fa libdm_table
1.2       wiz       307: argument.
                    308: Get routine will get the table start from kernel as
1.1       haad      309: .Vt libdm_table .
                    310: .Pp
                    311: .Fn libdm_table_set_length
                    312: and
                    313: .Fn libdm_table_get_length
1.2       wiz       314: Set table length from
1.1       haad      315: .Fa length
                    316: value to
                    317: .Fa libdm_table
1.2       wiz       318: argument.
                    319: Get routine will get the table length from kernel as
1.1       haad      320: .Vt libdm_table .
                    321: .Pp
                    322: .Fn libdm_table_set_target
                    323: and
                    324: .Fn libdm_table_get_target
1.2       wiz       325: Set target name from
1.1       haad      326: .Fa target
                    327: value to
                    328: .Fa libdm_table
1.2       wiz       329: argument.
                    330: The target must be actually present in the kernel, otherwise
                    331: .Fn libdm_task_run
                    332: will fail.
                    333: Get routine will get the table entry target from kernel as
1.1       haad      334: .Vt libdm_table .
                    335: .Pp
                    336: .Fn libdm_table_set_params
                    337: and
                    338: .Fn libdm_table_get_params
                    339: Set table target parameter string from
                    340: .Fa params
1.2       wiz       341: argument to
1.1       haad      342: .Fa libdm_table .
1.2       wiz       343: This is later in the kernel passed to the target init routine.
                    344: Get routine will get the table parameter string from kernel as
1.1       haad      345: .Vt libdm_table .
                    346: .Pp
                    347: .Fn libdm_table_get_status
1.2       wiz       348: Get table status which can be Active/Inactive.
                    349: This tells if this table is actually used or not.
1.1       haad      350: .Ss LIBDM_TARGET
                    351: .Fn libdm_target_destroy
                    352: Destroy target received from
                    353: .Vt libdm_cmd
                    354: with libdm_cmd_iter iterator.
                    355: .Pp
                    356: .Fn libdm_target_get_name
1.2       wiz       357: returns pointer to a string with available target name.
1.1       haad      358: .Pp
                    359: .Fn lobdm_target_get_version
                    360: Sets argument
                    361: .Fa ver[3]
1.2       wiz       362: to a in-kernel loaded target version.
1.1       haad      363: .Ss LIBDM_DEV
                    364: .Fn libdm_dev_destroy
                    365: Destroy device received from
                    366: .Vt libdm_cmd
                    367: with libdm_cmd_iter iterator.
                    368: .Pp
                    369: .Fn libdm_dev_get_name
                    370: Return pointer to a string with underlying device name from
                    371: .Vt libdm_dev_t
                    372: .Pp
                    373: .Fn libdm_dev_get_minor
                    374: Return underlying device minor number.
                    375: .Ss MISC
                    376: .Fn libdm_dev_set_newname
                    377: This routine will set new dm device name attribute to
                    378: .Fa newname .
                    379: User must then called libdm_task_run on this task to
1.2       wiz       380: change the device name.
1.1       haad      381: .Sh RETURN VALUES
1.2       wiz       382: Upon success, all described functions return zero or
                    383: .Pf non- Dv NULL
                    384: pointer.
1.1       haad      385: Otherwise, an error number will be returned to indicate the error.
                    386: .Sh SEE ALSO
                    387: .Xr dm 4
                    388: .Sh HISTORY
                    389: The
                    390: .Nm
                    391: was written and contributed to
                    392: .Nx
1.2       wiz       393: by
                    394: .An Adam Hamsik
                    395: and first appeared in
1.1       haad      396: .Nx 6.0 .

CVSweb <webmaster@jp.NetBSD.org>