Module Name: src Committed By: dholland Date: Mon Oct 26 05:57:36 UTC 2009
Modified Files: src/lib/libc/sys: modctl.2 Log Message: Edit - expand descriptions; document data structures in English rather than in C; use more markup; make nroff output not exceed 80 columns. To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/lib/libc/sys/modctl.2 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/libc/sys/modctl.2 diff -u src/lib/libc/sys/modctl.2:1.1 src/lib/libc/sys/modctl.2:1.2 --- src/lib/libc/sys/modctl.2:1.1 Tue Oct 20 04:41:28 2009 +++ src/lib/libc/sys/modctl.2 Mon Oct 26 05:57:36 2009 @@ -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 -.Pp -.Dq modsrc_t -looks like: -.Bd -literal -typedef enum modsrc { - MODULE_SOURCE_KERNEL, - MODULE_SOURCE_BOOT, - MODULE_SOURCE_FILESYS -} modsrc_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 -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.