lib/libc/sys/modctl.2

   1 .\"     $NetBSD: modctl.2,v 1.9 2012/08/07 01:19:05 jnemeth Exp $
   2 .\"
   3 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd August 3, 2012
  28 .Dt MODCTL 2
  29 .Os
  30 .Sh NAME
  31 .Nm modctl
  32 .Nd module control
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In sys/module.h
  37 .Ft int
  38 .Fn modctl "int operation" "void *argp"
  39 .Sh DESCRIPTION
  40 .Fn modctl
  41 provides control over loaded kernel modules.
  42 The argument
  43 .Fa operation
  44 is one of
  45 .Dv MODCTL_LOAD ,
  46 .Dv MODCTL_UNLOAD ,
  47 .Dv MODCTL_STAT ,
  48 or
  49 .Dv MODCTL_EXISTS .
  50 The argument
  51 .Fa argp
  52 depends on the
  53 .Fa operation
  54 to be performed.
  55 .Pp
  56 Operations are:
  57 .Bl -tag -width MODCTL_UNLOAD
  58 .It Dv MODCTL_LOAD
  59 Load a module.
  60 The
  61 .Fa argp
  62 argument should be a pointer to a
  63 .Em modctl_load_t
  64 structure, described below.
  65 .It Dv MODCTL_UNLOAD
  66 Unload a module.
  67 In this case,
  68 .Fa argp
  69 should be a string containing the name of the module to be unloaded.
  70 .It Dv MODCTL_STAT
  71 Return a list of loaded modules.
  72 In this case, the
  73 .Fa argp
  74 argument should be a
  75 .Em struct iovec
  76 pointing to a suitable block of memory.
  77 The kernel will fill this block with an array of
  78 .Em modstat_t
  79 structures, one per loaded module.
  80 If the block is not large enough, the data returned will be truncated
  81 to fit.
  82 The kernel will then update the
  83 .Fa iov_len
  84 member of the
  85 .Em iovec
  86 to reflect the size of the complete report, regardless of whether this
  87 is larger or smaller than the size passed in.
  88 .It Dv MODCTL_EXISTS
  89 Test to see if the kernel was compiled with
  90 .Dq options MODULAR
  91 and whether or
  92 not modules may be loaded at the moment.
  93 In this case,
  94 .Fa argp
  95 should be an integer.
  96 It should be
  97 .Dq 0
  98 to test if a user can load a module via
  99 .Dv MODCTL_LOAD ,
 100 or it should be
 101 .Dq 1
 102 to test if the system can autoload modules.
 103 Note that this
 104 test does not consider the sysctl
 105 .Li kern.module.autoload .
 106 .El
 107 .Ss Data Types
 108 The
 109 .Em modctl_load_t
 110 structure used with
 111 .Dv MODCTL_LOAD
 112 contains the following elements, which should be filled in by the caller:
 113 .Bl -tag -width aaaaaaaa
 114 .It Fa "const char *ml_filename"
 115 The name/path of the module to load.
 116 .It Fa "int ml_flags"
 117 Zero or more of the following flag values:
 118 .Bl -tag -compact -width "MODCTL_LOAD_FORCE"
 119 .It Dv MODCTL_NO_PROP
 120 Don't load
 121 .Ao module Ac Ns Pa .plist .
 122 .It Dv MODCTL_LOAD_FORCE
 123 Ignore kernel version mismatch.
 124 .El
 125 .It Fa "const char *ml_props"
 126 Externalized proplib dictionary to pass to module.
 127 .It Fa "size_t ml_propslen"
 128 Size of the dictionary blob.
 129 .Fa ml_props
 130 may be
 131 .Dv NULL
 132 in which case
 133 .Fa ml_propslen
 134 must be
 135 .Dv 0 .
 136 .El
 137 .Pp
 138 The
 139 .Em modstat_t
 140 structure used with
 141 .Dv MODCTL_STAT
 142 contains the following elements, which are filled in by the kernel:
 143 .Bl -tag -width aaaaaaaa
 144 .It Fa "char ms_name[MAXMODNAME]"
 145 The name of the module.
 146 .It Fa "char ms_required[MAXMODNAME * MAXMODDEPS]"
 147 The list of modules required by this module
 148 as a comma-delimited list of module names.
 149 .It Fa "modsrc_t ms_source"
 150 One of the following enumerated constants:
 151 .Bl -tag -compact -width "MODULE_SOURCE_FILESYS"
 152 .It Dv MODULE_SOURCE_KERNEL
 153 The module is compiled into the kernel.
 154 .It Dv MODULE_SOURCE_BOOT
 155 The module was provided by the bootstrap loader.
 156 .It Dv MODULE_SOURCE_FILESYS
 157 The module was loaded from the file system.
 158 .El
 159 .It Fa "modclass_t ms_class"
 160 One of the following enumerated constants:
 161 .Bl -tag -compact -width "MODULE_SOURCE_FILESYS"
 162 .It Dv MODULE_CLASS_SECMODEL
 163 Security model.
 164 .It Dv MODULE_CLASS_VFS
 165 File system.
 166 .It Dv MODULE_CLASS_DRIVER
 167 Device driver.
 168 .It Dv MODULE_CLASS_EXEC
 169 Executable file format.
 170 .It Dv MODULE_CLASS_MISC
 171 Miscellaneous.
 172 .It Dv MODULE_CLASS_ANY
 173 Any module class.
 174 .\" XXX: is MODULE_CLASS_ANY ever returned by this interface?
 175 .El
 176 .It Fa "uint64_t ms_addr"
 177 The load address within the kernel.
 178 .It Fa "u_int ms_size"
 179 Loaded size of the module.
 180 .It Fa "u_int ms_refcnt"
 181 Current number of live references to this module.
 182 .El
 183 .Sh RETURN VALUES
 184 Upon successful completion, the value returned is 0.
 185 .Pp
 186 Otherwise, a value of \-1 is returned and
 187 .Va errno
 188 is set to indicate the error.
 189 .Sh ERRORS
 190 .Fn modctl
 191 will fail if:
 192 .Bl -tag -width Er
 193 .It Bq Er EBUSY
 194 The argument
 195 .Fa operation
 196 is
 197 .Dv MODCTL_UNLOAD
 198 and the module is in use or the module is compiled into the kernel.
 199 .It Bq Er EDEADLK
 200 The argument
 201 .Fa operation
 202 is
 203 .Dv MODCTL_LOAD
 204 and there is a circular dependency in the module's dependency chain.
 205 .It Bq Er EEXIST
 206 The argument
 207 .Fa operation
 208 is
 209 .Dv MODCTL_LOAD
 210 and the module is already loaded.
 211 .It Bq Er EFAULT
 212 A bad address was given for
 213 .Fa argp .
 214 .It Bq Er EFBIG
 215 The argument
 216 .Fa operation
 217 is
 218 .Dv MODCTL_LOAD ,
 219 the specified module resides in the file system, and the module's default
 220 proplib file was too large.
 221 .It Bq Er EINVAL
 222 The argument
 223 .Fa operation
 224 is invalid.
 225 .Pp
 226 The argument
 227 .Fa operation
 228 is
 229 .Dv MODCTL_LOAD
 230 and ml_props is not
 231 .Dv NULL
 232 and
 233 .Dq ml_propslen
 234 is
 235 .Dv 0 ,
 236 or
 237 ml_props is
 238 .Dv NULL
 239 and
 240 .Dq ml_propslen
 241 is not
 242 .Dv 0 .
 243 The kernel is unable to internalize the plist.
 244 Or, there is a problem with the module or \*[Lt]module\*[Gt].plist.
 245 .It Bq Er EMLINK
 246 The argument
 247 .Fa operation
 248 is
 249 .Dv MODCTL_LOAD
 250 and the module has too many dependencies.
 251 .It Bq Er ENAMETOOLONG
 252 A module name/path is too long.
 253 .It Bq Er ENOENT
 254 The argument
 255 .Fa operation
 256 is
 257 .Dv MODCTL_LOAD
 258 and the module or a dependency can't be found.
 259 The argument
 260 .Fa operation
 261 is
 262 .Dv MODCTL_UNLOAD
 263 and no module by the name of
 264 .Fa argp
 265 is loaded.
 266 .It Bq Er ENOEXEC
 267 The argument
 268 .Fa operation
 269 is
 270 .Dv MODCTL_LOAD
 271 and the module is not a valid object for the system.
 272 .It Bq Er ENOMEM
 273 There was not enough memory to perform the
 274 .Fa operation .
 275 .It Bq Er EPERM
 276 Not allowed to perform the
 277 .Fa operation .
 278 .It Bq Er EPROGMISMATCH
 279 The argument
 280 .Fa operation
 281 is
 282 .Dv MODCTL_LOAD ,
 283 the
 284 .Fa ml_flags
 285 field in the
 286 .Em modctl_load_t
 287 structure does not include
 288 .Dv MODCTL_LOAD_FORCE ,
 289 and the requested module does not match the current kernel's version
 290 information.
 291 .El
 292 .Sh SEE ALSO
 293 .Xr module 7 ,
 294 .Xr sysctl 7 ,
 295 .Xr module 9
 296 .Sh HISTORY
 297 The
 298 .Fn modctl
 299 function call first appeared in
 300 .Nx 5.0 .