Module Name: src
Committed By: wiz
Date: Tue Feb 8 09:49:08 UTC 2011
Modified Files:
src/lib/libdm: dm.3
Log Message:
Improve a bit.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/lib/libdm/dm.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libdm/dm.3
diff -u src/lib/libdm/dm.3:1.1 src/lib/libdm/dm.3:1.2
--- src/lib/libdm/dm.3:1.1 Tue Feb 8 03:20:15 2011
+++ src/lib/libdm/dm.3 Tue Feb 8 09:49:07 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: dm.3,v 1.1 2011/02/08 03:20:15 haad Exp $
+.\" $NetBSD: dm.3,v 1.2 2011/02/08 09:49:07 wiz Exp $
.\"
.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -26,7 +26,7 @@
.\" 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
+.Dd January 22, 2011
.Dt DM 3
.Os
.Sh NAME
@@ -127,7 +127,7 @@
.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.
+Every object in libdm has its own create and destroy routine.
.Bl -bullet -offset indent -compact
.It
libdm_task_t
@@ -140,15 +140,14 @@
Except
.Vt libdm_dev_t
which is received from kernel as list of physical devices on which
-logical device depends.
+the logical device depends.
.Vt libdm_target_t
-which is received from kernel as list of available targets for use .
+which is received from kernel as list of available targets to 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.
+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
@@ -158,7 +157,7 @@
.Fa command
is
.Dv NULL ,
-libdm_task_t is not created and function return
+libdm_task_t is not created and the function returns
.Dv NULL .
.Pp
.Fn libdm_task_destroy
@@ -170,7 +169,7 @@
.Fn libdm_task_run
Sends created
.Fa libdm_task
-to kernel and receive new one as reply.
+to kernel and receives new one as reply.
.Pp
List of attributes avaialable in
.Vt libdm_task_t :
@@ -185,99 +184,109 @@
.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.
+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 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.
+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 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.
+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 task dictionary.
+Set/fetch device status flags from the task dictionary.
.Pp
.Fn libdm_task_get_open_num
-Fetch number of opened devices from kernel and return them as
+Fetch number of opened devices from the 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
+Fetch number of opened devices from the 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
+Get the version of the dm driver in the kernel as array
.Fa uint32_t *ver
-with
-.Fa size
-size.
+of size
+.Fa size .
.Fn libdm_task_set_cmd
and
.Fn libdm_task_get_cmd
-Adds and fetches cmd structure from
+Add and fetch 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.
+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
-will allocate cmd structure which can be later put in to the task.
+function will allocate a cmd structure which can later be put in
+to the task.
.Pp
.Fn libdm_cmd_destroy
-will deallocate cmd strucute previously allocated.
+will deallocate a previously allocated cmd structure.
.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.
+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 user creates task with "status" command kernel sends cmd with table in it.
+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.
+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.
+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 task with "deps" command kernel sends cmd with array of
-physical devices atatched to dm device.
+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 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
+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
-routine.
+function.
.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
+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
@@ -293,32 +302,37 @@
.Fn libdm_table_set_start
and
.Fn libdm_table_get_start
-Sets start table from
+Set start table from
.Fa start
value to
.Fa libdm_table
-argument. Get routine will get table start from kernel received in
+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
-Sets table length from
+Set table length from
.Fa length
value to
.Fa libdm_table
-argument. Get routine will get table length from kernel received in
+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
-Sets target name from
+Set 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
+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
@@ -326,16 +340,15 @@
.Fn libdm_table_get_params
Set table target parameter string from
.Fa params
-arrgument value to
+argument 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
+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 which tells if this table
-is actually used or not .
-.Pp
+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
@@ -343,13 +356,12 @@
with libdm_cmd_iter iterator.
.Pp
.Fn libdm_target_get_name
-return pointer to string with available target 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.
-.Pp
+to a in-kernel loaded target version.
.Ss LIBDM_DEV
.Fn libdm_dev_destroy
Destroy device received from
@@ -362,18 +374,17 @@
.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
+change the device name.
.Sh RETURN VALUES
-Upon success all described functions return zero or non NULL pointer.
+Upon success, all described functions return zero or
+.Pf non- Dv NULL
+pointer.
Otherwise, an error number will be returned to indicate the error.
-.Pp
.Sh SEE ALSO
.Xr dm 4
.Sh HISTORY
@@ -381,6 +392,7 @@
.Nm
was written and contributed to
.Nx
-by Adam Hamsik and first appeared in
+by
+.An Adam Hamsik
+and first appeared in
.Nx 6.0 .
-
