1.\" $NetBSD: modctl.2,v 1.12 2015/11/04 04:31:53 pgoyette 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 November 4, 2015 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 41provides control over loaded kernel modules. 42The argument 43.Fa operation 44is one of 45.Dv MODCTL_LOAD , 46.Dv MODCTL_UNLOAD , 47.Dv MODCTL_STAT , 48or 49.Dv MODCTL_EXISTS . 50The argument 51.Fa argp 52depends on the 53.Fa operation 54to be performed. 55.Pp 56Operations are: 57.Bl -tag -width MODCTL_UNLOAD 58.It Dv MODCTL_LOAD 59Load a module. 60The 61.Fa argp 62argument should be a pointer to a 63.Em modctl_load_t 64structure, described below. 65.It Dv MODCTL_UNLOAD 66Unload a module. 67In this case, 68.Fa argp 69should be a string containing the name of the module to be unloaded. 70.It Dv MODCTL_STAT 71Return a list of loaded modules. 72In this case, the 73.Fa argp 74argument should be a 75.Em struct iovec 76pointing to a suitable block of memory. 77The kernel will fill this block with an array of 78.Em modstat_t 79structures, one per loaded module. 80If the block is not large enough, the data returned will be truncated 81to fit. 82The kernel will then update the 83.Fa iov_len 84member of the 85.Em iovec 86to reflect the size of the complete report, regardless of whether this 87is larger or smaller than the size passed in. 88.It Dv MODCTL_EXISTS 89Test to see if the kernel was compiled with 90.Dq options MODULAR 91and whether or 92not modules may be loaded at the moment. 93In this case, 94.Fa argp 95should be an integer. 96It should be 97.Dq 0 98to test if a user can load a module via 99.Dv MODCTL_LOAD , 100or it should be 101.Dq 1 102to test if the system can autoload modules. 103Note that this 104test does not consider the sysctl 105.Li kern.module.autoload . 106.El 107.Ss Data Types 108The 109.Em modctl_load_t 110structure used with 111.Dv MODCTL_LOAD 112contains the following elements, which should be filled in by the caller: 113.Bl -tag -width aaaaaaaa 114.It Fa "const char *ml_filename" 115The name/path of the module to load. 116.It Fa "int ml_flags" 117Zero or more of the following flag values: 118.Bl -tag -compact -width "MODCTL_LOAD_FORCE" 119.It Dv MODCTL_NO_PROP 120Don't load 121.Ao module Ac Ns Pa .plist . 122.It Dv MODCTL_LOAD_FORCE 123Ignore kernel version mismatch. 124.El 125.It Fa "const char *ml_props" 126Externalized proplib dictionary to pass to module. 127.It Fa "size_t ml_propslen" 128Size of the dictionary blob. 129.Fa ml_props 130may be 131.Dv NULL 132in which case 133.Fa ml_propslen 134must be 135.Dv 0 . 136An upper limit of 4096 bytes is imposed on the value of ml_propslen. 137Attempting to load a proplib dictionary larger than this size will return 138.Er ENOMEM . 139.El 140.Pp 141The 142.Em modstat_t 143structure used with 144.Dv MODCTL_STAT 145contains the following elements, which are filled in by the kernel: 146.Bl -tag -width aaaaaaaa 147.It Fa "char ms_name[MAXMODNAME]" 148The name of the module. 149.It Fa "char ms_required[MAXMODNAME * MAXMODDEPS]" 150The list of modules required by this module 151as a comma-delimited list of module names. 152.It Fa "modsrc_t ms_source" 153One of the following enumerated constants: 154.Bl -tag -compact -width "MODULE_SOURCE_FILESYS" 155.It Dv MODULE_SOURCE_KERNEL 156The module is compiled into the kernel. 157.It Dv MODULE_SOURCE_BOOT 158The module was provided by the bootstrap loader. 159.It Dv MODULE_SOURCE_FILESYS 160The module was loaded from the file system. 161.El 162.It Fa "modclass_t ms_class" 163One of the following enumerated constants: 164.Bl -tag -compact -width "MODULE_SOURCE_FILESYS" 165.It Dv MODULE_CLASS_SECMODEL 166Security model. 167.It Dv MODULE_CLASS_VFS 168File system. 169.It Dv MODULE_CLASS_DRIVER 170Device driver. 171.It Dv MODULE_CLASS_EXEC 172Executable file format. 173.It Dv MODULE_CLASS_MISC 174Miscellaneous. 175.It Dv MODULE_CLASS_ANY 176Any module class. 177.\" XXX: is MODULE_CLASS_ANY ever returned by this interface? 178.El 179.It Fa "uint64_t ms_addr" 180The load address within the kernel. 181.It Fa "u_int ms_size" 182Loaded size of the module. 183.It Fa "u_int ms_refcnt" 184Current number of live references to this module. 185.It Fa "u_int ms_flags" 186The module's flags: 187.Bl -tag -compact -width "MODFLAG_AUTO_LOADED" 188.It Dv MODFLAG_MUST_FORCE 189The "force" flag must be specified to reload this module. 190.It Dv MODFLAG_AUTO_LOADED 191The module was auto-loaded by the operating system. 192.El 193.El 194.Sh RETURN VALUES 195Upon successful completion, the value returned is 0. 196.Pp 197Otherwise, a value of \-1 is returned and 198.Va errno 199is set to indicate the error. 200.Sh ERRORS 201.Fn modctl 202will fail if: 203.Bl -tag -width Er 204.It Bq Er EBUSY 205The argument 206.Fa operation 207is 208.Dv MODCTL_UNLOAD 209and the module is in use or the module is compiled into the kernel. 210.It Bq Er EDEADLK 211The argument 212.Fa operation 213is 214.Dv MODCTL_LOAD 215and there is a circular dependency in the module's dependency chain. 216.It Bq Er EEXIST 217The argument 218.Fa operation 219is 220.Dv MODCTL_LOAD 221and the module is already loaded. 222.It Bq Er EFAULT 223A bad address was given for 224.Fa argp . 225.It Bq Er EFBIG 226The argument 227.Fa operation 228is 229.Dv MODCTL_LOAD , 230the specified module resides in the file system, and the module's default 231proplib file was too large. 232.It Bq Er EINVAL 233The argument 234.Fa operation 235is invalid. 236.Pp 237The argument 238.Fa operation 239is 240.Dv MODCTL_LOAD 241and ml_props is not 242.Dv NULL 243and 244.Dq ml_propslen 245is 246.Dv 0 , 247or 248ml_props is 249.Dv NULL 250and 251.Dq ml_propslen 252is not 253.Dv 0 . 254The kernel is unable to internalize the plist. 255Or, there is a problem with the module or \*[Lt]module\*[Gt].plist. 256.It Bq Er EMLINK 257The argument 258.Fa operation 259is 260.Dv MODCTL_LOAD 261and the module has too many dependencies. 262.It Bq Er ENAMETOOLONG 263A module name/path is too long. 264.It Bq Er ENOENT 265The argument 266.Fa operation 267is 268.Dv MODCTL_LOAD 269and the module or a dependency can't be found. 270The argument 271.Fa operation 272is 273.Dv MODCTL_UNLOAD 274and no module by the name of 275.Fa argp 276is loaded. 277.It Bq Er ENOEXEC 278The argument 279.Fa operation 280is 281.Dv MODCTL_LOAD 282and the module is not a valid object for the system. 283Most likely, one or more undefined symbols could not be resolved by the 284in-kernel linker. 285.It Bq Er ENOMEM 286There was not enough memory to perform the 287.Fa operation . 288.It Bq Er EPERM 289Not allowed to perform the 290.Fa operation . 291.It Bq Er EPROGMISMATCH 292The argument 293.Fa operation 294is 295.Dv MODCTL_LOAD , 296the 297.Fa ml_flags 298field in the 299.Em modctl_load_t 300structure does not include 301.Dv MODCTL_LOAD_FORCE , 302and the requested module does not match the current kernel's version 303information. 304.El 305.Sh SEE ALSO 306.Xr module 7 , 307.Xr sysctl 7 , 308.Xr module 9 309.Sh HISTORY 310The 311.Fn modctl 312function call first appeared in 313.Nx 5.0 . 314