[src/trunk]: src/lib/libc/sys Edit - expand descriptions; document data struc...

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

details:   https://anonhg.NetBSD.org/src/rev/14037538ac37
branches:  trunk
changeset: 748526:14037538ac37
user:      dholland <dholland%NetBSD.org@localhost>
date:      Mon Oct 26 05:57:36 2009 +0000

description:
Edit - expand descriptions; document data structures in English rather
than in C; use more markup; make nroff output not exceed 80 columns.

diffstat:

 lib/libc/sys/modctl.2 |  170 +++++++++++++++++++++++++++----------------------
 1 files changed, 95 insertions(+), 75 deletions(-)

diffs (209 lines):

diff -r 75fdc29b4b2f -r 14037538ac37 lib/libc/sys/modctl.2
--- a/lib/libc/sys/modctl.2     Mon Oct 26 04:27:15 2009 +0000
+++ b/lib/libc/sys/modctl.2     Mon Oct 26 05:57:36 2009 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: modctl.2,v 1.1 2009/10/20 04:41:28 jnemeth Exp $
+.\"    $NetBSD: modctl.2,v 1.2 2009/10/26 05:57:36 dholland Exp $
 .\"
 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 19, 2009
+.Dd October 26, 2009
 .Dt MODCTL 2
 .Os
 .Sh NAME
@@ -35,10 +35,10 @@
 .Sh SYNOPSIS
 .In sys/module.h
 .Ft int
-.Fn modctl "int operation" "void * argp"
+.Fn modctl "int operation" "void *argp"
 .Sh DESCRIPTION
 .Fn modctl
-provides for control over modules.
+provides control over loaded kernel modules.
 The argument
 .Fa operation
 is one of
@@ -58,86 +58,106 @@
 Load a module.
 The
 .Fa argp
-should be:
-.Bd -literal
-typedef struct modctl_load {
-        const char *ml_filename;       /* the name/path of the module to load */
-
-#define MODCTL_NO_PROP          0x2    /* don't load \*[Lt]module\*[Gt].prop */
-#define MODCTL_LOAD_FORCE       0x1    /* ignore kernel version mismatch */
-        int ml_flags;
-
-        const char *ml_props;          /* externalised dictionary to pass to module */
-        size_t ml_propslen;            /* length of dictionary */
-} modctl_load_t;
-.Ed
-.Pp
-.Dq ml_props
-may be
-.Dv NULL
-in which case
-.Dq ml_propslen
-must be
-.Dv 0 .
+argument should be a pointer to a
+.Em modctl_load_t
+structure, described below.
 .It Dv MODCTL_UNLOAD
 Unload a module.
-In this case, the
+In this case,
 .Fa argp
-should be a
-.Dq char *
-containing the name of the module to be unloaded.
+should be a string containing the name of the module to be unloaded.
 .It Dv MODCTL_STAT
 Return a list of loaded modules.
 In this case, the
 .Fa argp
-should be a
-.Dq struct iovec .
-The kernel will adjust the
-.Dq iov_len
-paramater to reflect the space required.
+argument should be a
+.Em struct iovec
+pointing to a suitable block of memory.
+The kernel will fill this block with an array of
+.Em modstat_t
+structures, one per loaded module.
+If the block is not large enough, the data returned will be truncated
+to fit.
+The kernel will then update the
+.Fa iov_len
+member of the
+.Em iovec
+to reflect the size of the complete report, regardless of whether this
+is larger or smaller than the size passed in.
+.El
+.Ss Data Types
 The
-.Dq iov_base
-will be a pointer to an array of
-.Dq modstat_t
-truncated to the passed in
-.Dq iov_len .
-.Dq modstat_t
-looks like:
-.Bd -literal
-typedef struct modstat {
-        char            ms_name[MAXMODNAME];
-        char            ms_required[MAXMODNAME * MAXMODDEPS];
-        uint64_t        ms_addr;
-        modsrc_t        ms_source;
-        modclass_t      ms_class;
-        u_int           ms_size;
-        u_int           ms_refcnt;
-        u_int           ms_reserved[4];
-} modstat_t;
-.Ed
+.Em modctl_load_t
+structure used with
+.Dv MODCTL_LOAD
+contains the following elements, which should be filled in by the caller:
+.Bl -tag -width aaaaaaaa
+.It Fa "const char *ml_filename"
+The name/path of the module to load.
+.It Fa "int ml_flags"
+Zero or more of the following flag values:
+.Bl -tag -compact -width "MODCTL_LOAD_FORCE"
+.It Dv MODCTL_NO_PROP
+Don't load \*[Lt]module\*[Gt].prop.
+.It Dv MODCTL_LOAD_FORCE
+Ignore kernel version mismatch.
+.El
+.It Fa "const char *ml_props"
+Externalized proplib dictionary to pass to module.
+.It Fa "size_t ml_propslen"
+Size of the dictionary blob.
+.Fa ml_props
+may be
+.Dv NULL
+in which case
+.Fa ml_propslen
+must be
+.Dv 0 .
+.El
 .Pp
-.Dq modsrc_t
-looks like:
-.Bd -literal
-typedef enum modsrc {
-        MODULE_SOURCE_KERNEL,
-        MODULE_SOURCE_BOOT,
-        MODULE_SOURCE_FILESYS
-} modsrc_t;
-.Ed
-.Pp
-and
-.Dq modclass_t
-looks like:
-.Bd -literal
-typedef enum modclass {
-        MODULE_CLASS_ANY,
-        MODULE_CLASS_MISC,
-        MODULE_CLASS_VFS,
-        MODULE_CLASS_DRIVER,
-        MODULE_CLASS_EXEC
-} modclass_t;
-.Ed
+The
+.Em modstat_t
+structure used with
+.Dv MODCTL_STAT
+contains the following elements, which are filled in by the kernel:
+.Bl -tag -width aaaaaaaa
+.It Fa "char ms_name[MAXMODNAME]"
+The name of the module.
+.It Fa "char ms_required[MAXMODNAME * MAXMODDEPS]"
+The list of modules required by this module.
+.\" as a comma-delimited list of module names.
+.\" XXX can someone confirm this?
+.It Fa "modsrc_t ms_source"
+One of the following enumerated constants:
+.Bl -tag -compact -width "MODULE_SOURCE_FILESYS"
+.It Dv MODULE_SOURCE_KERNEL
+The module is compiled into the kernel.
+.It Dv MODULE_SOURCE_BOOT
+The module was provided by the bootstrap loader.
+.It Dv MODULE_SOURCE_FILESYS
+The module was loaded from the file system.
+.El
+.It Fa "modclass_t ms_class"
+One of the following enumerated constants:
+.Bl -tag -compact -width "MODULE_SOURCE_FILESYS"
+.It Dv MODULE_CLASS_VFS
+File system.
+.It Dv MODULE_CLASS_DRIVER
+Device driver.
+.It Dv MODULE_CLASS_EXEC
+Executable file format.
+.It Dv MODULE_CLASS_MISC
+Miscellaneous.
+.It Dv MODULE_CLASS_ANY
+Any module class.
+.\" XXX: is MODULE_CLASS_ANY ever returned by this interface?
+.El
+.It Fa "uint64_t ms_addr"
+The load address within the kernel.
+.It Fa "u_int ms_size"
+Loaded size of the module.
+.It Fa "u_int ms_refcnt"
+Current number of live references to this module.
 .El
 .Sh RETURN VALUES
 Upon successful completion, the value returned is 0.