1.\" $NetBSD: modctl.2,v 1.11 2015/05/09 08:10:01 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 May 9, 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.El 186.Sh RETURN VALUES 187Upon successful completion, the value returned is 0. 188.Pp 189Otherwise, a value of \-1 is returned and 190.Va errno 191is set to indicate the error. 192.Sh ERRORS 193.Fn modctl 194will fail if: 195.Bl -tag -width Er 196.It Bq Er EBUSY 197The argument 198.Fa operation 199is 200.Dv MODCTL_UNLOAD 201and the module is in use or the module is compiled into the kernel. 202.It Bq Er EDEADLK 203The argument 204.Fa operation 205is 206.Dv MODCTL_LOAD 207and there is a circular dependency in the module's dependency chain. 208.It Bq Er EEXIST 209The argument 210.Fa operation 211is 212.Dv MODCTL_LOAD 213and the module is already loaded. 214.It Bq Er EFAULT 215A bad address was given for 216.Fa argp . 217.It Bq Er EFBIG 218The argument 219.Fa operation 220is 221.Dv MODCTL_LOAD , 222the specified module resides in the file system, and the module's default 223proplib file was too large. 224.It Bq Er EINVAL 225The argument 226.Fa operation 227is invalid. 228.Pp 229The argument 230.Fa operation 231is 232.Dv MODCTL_LOAD 233and ml_props is not 234.Dv NULL 235and 236.Dq ml_propslen 237is 238.Dv 0 , 239or 240ml_props is 241.Dv NULL 242and 243.Dq ml_propslen 244is not 245.Dv 0 . 246The kernel is unable to internalize the plist. 247Or, there is a problem with the module or \*[Lt]module\*[Gt].plist. 248.It Bq Er EMLINK 249The argument 250.Fa operation 251is 252.Dv MODCTL_LOAD 253and the module has too many dependencies. 254.It Bq Er ENAMETOOLONG 255A module name/path is too long. 256.It Bq Er ENOENT 257The argument 258.Fa operation 259is 260.Dv MODCTL_LOAD 261and the module or a dependency can't be found. 262The argument 263.Fa operation 264is 265.Dv MODCTL_UNLOAD 266and no module by the name of 267.Fa argp 268is loaded. 269.It Bq Er ENOEXEC 270The argument 271.Fa operation 272is 273.Dv MODCTL_LOAD 274and the module is not a valid object for the system. 275Most likely, one or more undefined symbols could not be resolved by the 276in-kernel linker. 277.It Bq Er ENOMEM 278There was not enough memory to perform the 279.Fa operation . 280.It Bq Er EPERM 281Not allowed to perform the 282.Fa operation . 283.It Bq Er EPROGMISMATCH 284The argument 285.Fa operation 286is 287.Dv MODCTL_LOAD , 288the 289.Fa ml_flags 290field in the 291.Em modctl_load_t 292structure does not include 293.Dv MODCTL_LOAD_FORCE , 294and the requested module does not match the current kernel's version 295information. 296.El 297.Sh SEE ALSO 298.Xr module 7 , 299.Xr sysctl 7 , 300.Xr module 9 301.Sh HISTORY 302The 303.Fn modctl 304function call first appeared in 305.Nx 5.0 . 306