[src/trunk]: src Improve a bit.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4a83daddc976
branches:  trunk
changeset: 761812:4a83daddc976
user:      wiz <wiz%NetBSD.org@localhost>
date:      Tue Feb 08 09:49:07 2011 +0000

description:
Improve a bit.

diffstat:

 lib/libdm/dm.3     |  172 ++++++++++++++++++++++++++++------------------------
 sbin/dmctl/dmctl.8 |   18 +++--
 2 files changed, 102 insertions(+), 88 deletions(-)

diffs (truncated from 388 to 300 lines):

diff -r 18312c1f7e10 -r 4a83daddc976 lib/libdm/dm.3
--- a/lib/libdm/dm.3    Tue Feb 08 09:35:32 2011 +0000
+++ b/lib/libdm/dm.3    Tue Feb 08 09:49:07 2011 +0000
@@ -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.
+which is used as iteration counter for array entries in the 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
+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.
+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 and array of structures all _get routines needs an
-iterator to work. For every entry we can have more than one.
+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.