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