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 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 . 136.El 137.Pp 138The 139.Em modstat_t 140structure used with 141.Dv MODCTL_STAT 142contains the following elements, which are filled in by the kernel: 143.Bl -tag -width aaaaaaaa 144.It Fa "char ms_name[MAXMODNAME]" 145The name of the module. 146.It Fa "char ms_required[MAXMODNAME * MAXMODDEPS]" 147The list of modules required by this module 148as a comma-delimited list of module names. 149.It Fa "modsrc_t ms_source" 150One of the following enumerated constants: 151.Bl -tag -compact -width "MODULE_SOURCE_FILESYS" 152.It Dv MODULE_SOURCE_KERNEL 153The module is compiled into the kernel. 154.It Dv MODULE_SOURCE_BOOT 155The module was provided by the bootstrap loader. 156.It Dv MODULE_SOURCE_FILESYS 157The module was loaded from the file system. 158.El 159.It Fa "modclass_t ms_class" 160One of the following enumerated constants: 161.Bl -tag -compact -width "MODULE_SOURCE_FILESYS" 162.It Dv MODULE_CLASS_SECMODEL 163Security model. 164.It Dv MODULE_CLASS_VFS 165File system. 166.It Dv MODULE_CLASS_DRIVER 167Device driver. 168.It Dv MODULE_CLASS_EXEC 169Executable file format. 170.It Dv MODULE_CLASS_MISC 171Miscellaneous. 172.It Dv MODULE_CLASS_ANY 173Any module class. 174.\" XXX: is MODULE_CLASS_ANY ever returned by this interface? 175.El 176.It Fa "uint64_t ms_addr" 177The load address within the kernel. 178.It Fa "u_int ms_size" 179Loaded size of the module. 180.It Fa "u_int ms_refcnt" 181Current number of live references to this module. 182.El 183.Sh RETURN VALUES 184Upon successful completion, the value returned is 0. 185.Pp 186Otherwise, a value of \-1 is returned and 187.Va errno 188is set to indicate the error. 189.Sh ERRORS 190.Fn modctl 191will fail if: 192.Bl -tag -width Er 193.It Bq Er EBUSY 194The argument 195.Fa operation 196is 197.Dv MODCTL_UNLOAD 198and the module is in use or the module is compiled into the kernel. 199.It Bq Er EDEADLK 200The argument 201.Fa operation 202is 203.Dv MODCTL_LOAD 204and there is a circular dependency in the module's dependency chain. 205.It Bq Er EEXIST 206The argument 207.Fa operation 208is 209.Dv MODCTL_LOAD 210and the module is already loaded. 211.It Bq Er EFAULT 212A bad address was given for 213.Fa argp . 214.It Bq Er EFBIG 215The argument 216.Fa operation 217is 218.Dv MODCTL_LOAD , 219the specified module resides in the file system, and the module's default 220proplib file was too large. 221.It Bq Er EINVAL 222The argument 223.Fa operation 224is invalid. 225.Pp 226The argument 227.Fa operation 228is 229.Dv MODCTL_LOAD 230and ml_props is not 231.Dv NULL 232and 233.Dq ml_propslen 234is 235.Dv 0 , 236or 237ml_props is 238.Dv NULL 239and 240.Dq ml_propslen 241is not 242.Dv 0 . 243The kernel is unable to internalize the plist. 244Or, there is a problem with the module or \*[Lt]module\*[Gt].plist. 245.It Bq Er EMLINK 246The argument 247.Fa operation 248is 249.Dv MODCTL_LOAD 250and the module has too many dependencies. 251.It Bq Er ENAMETOOLONG 252A module name/path is too long. 253.It Bq Er ENOENT 254The argument 255.Fa operation 256is 257.Dv MODCTL_LOAD 258and the module or a dependency can't be found. 259The argument 260.Fa operation 261is 262.Dv MODCTL_UNLOAD 263and no module by the name of 264.Fa argp 265is loaded. 266.It Bq Er ENOEXEC 267The argument 268.Fa operation 269is 270.Dv MODCTL_LOAD 271and the module is not a valid object for the system. 272.It Bq Er ENOMEM 273There was not enough memory to perform the 274.Fa operation . 275.It Bq Er EPERM 276Not allowed to perform the 277.Fa operation . 278.It Bq Er EPROGMISMATCH 279The argument 280.Fa operation 281is 282.Dv MODCTL_LOAD , 283the 284.Fa ml_flags 285field in the 286.Em modctl_load_t 287structure does not include 288.Dv MODCTL_LOAD_FORCE , 289and the requested module does not match the current kernel's version 290information. 291.El 292.Sh SEE ALSO 293.Xr module 7 , 294.Xr sysctl 7 , 295.Xr module 9 296.Sh HISTORY 297The 298.Fn modctl 299function call first appeared in 300.Nx 5.0 . 301