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