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