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>