First pass at a manpage for modctl(2) (hi ad!).


(jnemeth)

.\"	$NetBSD: modctl.2,v 1.1 2009/10/20 04:41:28 jnemeth Exp $
.\"
.\" Copyright (c) 2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" 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 October 19, 2009
.Dt MODCTL 2
.Os
.Sh NAME
.Nm modctl
.Nd module control
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/module.h
.Ft int
.Fn modctl "int operation" "void * argp"
.Sh DESCRIPTION
.Fn modctl
provides for control over modules.
The argument
.Fa operation
is one of
.Dv MODCTL_LOAD ,
.Dv MODCTL_UNLOAD ,
or
.Dv MODCTL_STAT .
The argument
.Fa argp
depends on the
.Fa operation
to be performed.
.Pp
Operations are:
.Bl -tag -width MODCTL_UNLOAD
.It Dv MODCTL_LOAD
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 .
.It Dv MODCTL_UNLOAD
Unload a module.
In this case, the
.Fa argp
should be a
.Dq char *
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.
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
.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
.El
.Sh RETURN VALUES
Upon successful completion, the value returned is 0.
.Pp
Otherwise, a value of \-1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn modctl
will fail if:
.Bl -tag -width Er
.It Bq Er EBUSY
The argument
.Fa operation
is
.Dv MODCTL_UNLOAD
and the module is in use or the module is compiled into the kernel.
.It Bq Er EDEADLK
The argument
.Fa operation
is
.Dv MODCTL_LOAD
and there is a circular dependency in the module's dependency chain.
.It Bq Er EEXIST
The argument
.Fa operation
is
.Dv MODCTL_LOAD
and the module is already loaded.
.It Bq Er EFAULT
A bad address was given for
.Fa argp .
.It Bq Er EINVAL
The argument
.Fa operation
is invalid.
.Pp
The argument
.Fa operation
is
.Dv MODCTL_LOAD
and ml_props is not
.Dv NULL
and
.Dq ml_propslen
is
.Dv 0 ,
or
ml_props is
.Dv NULL
and
.Dq ml_propslen
is not
.Dv 0 .
The kernel is unable to internalize the plist.
Or, there is a problem with the module or \*[Lt]module\*[Gt].prop.
.It Bq Er EMLINK
The argument
.Fa operation
is
.Dv MODCTL_LOAD
and the module has too many dependencies.
.It Bq Er ENAMETOOLONG
A module name/path is too long.
.It Bq Er ENOENT
The argument
.Fa operation
is
.Dv MODCTL_LOAD
and the module or a dependency can't be found.
The argument
.Fa operation
is
.Dv MODCTL_UNLOAD
and no module by the name of
.Fa argp
is loaded.
.It Bq Er ENOEXEC
The argument
.Fa operation
is
.Dv MODCTL_LOAD
and the module is not a valid object for the system.
.It Bq Er ENOMEM
There was not enough memory to perform the
.Fa operation .
.It Bq Er EPERM
Not allowed to perform the
.Fa operation .
.El
.Sh HISTORY
The
.Fn modctl
function call first appeared in
.Nx 5.0 .