| blob | f0674b552a85a78935276c7b57dca4838811c1b4 |
1 .\" $NetBSD: sysctl.9,v 1.13 2008/11/12 12:35:54 ad Exp $
2 .\"
3 .\" Copyright (c) 2004 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Andrew Brown.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd August 15, 2008
31 .Dt SYSCTL 9
32 .Os
33 .Sh NAME
34 .Nm sysctl
35 .Nd system variable control interfaces
36 .Sh SYNOPSIS
37 .In sys/param.h
38 .In sys/sysctl.h
39 .Pp
40 Primary external interfaces:
41 .Ft void
42 .Fn sysctl_init void
43 .Ft int
44 .Fn sysctl_lock "struct lwp *l" "void *oldp" "size_t savelen"
45 .Ft int
46 .Fn sysctl_dispatch "const int *name" "u_int namelen" "void *oldp" \
47 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
48 "struct lwp *l" "const struct sysctlnode *rnode"
49 .Ft void
50 .Fn sysctl_unlock "struct lwp *l"
51 .Ft int
52 .Fn sysctl_createv "struct sysctllog **log" "int cflags" \
53 "const struct sysctlnode **rnode" "const struct sysctlnode **cnode" \
54 "int flags" "int type" "const char *namep" "const char *desc" \
55 "sysctlfn func" "u_quad_t qv" "void *newp" "size_t newlen" ...
56 .Ft int
57 .Fn sysctl_destroyv "struct sysctlnode *rnode" ...
58 .Ft void
59 .Fn sysctl_free "struct sysctlnode *rnode"
60 .Ft void
61 .Fn sysctl_teardown "struct sysctllog **"
62 .Ft int
63 .Fn old_sysctl "int *name" "u_int namelen" "void *oldp" \
64 "size_t *oldlenp" "void *newp" "size_t newlen" "struct lwp *l"
65 .Pp
66 Core internal functions:
67 .Ft int
68 .Fn sysctl_locate "struct lwp *l" "const int *name" "u_int namelen" \
69 "const struct sysctlnode **rnode" "int *nip"
70 .Ft int
71 .Fn sysctl_lookup "const int *name" "u_int namelen" "void *oldp" \
72 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
73 "struct lwp *l" "const struct sysctlnode *rnode"
74 .Ft int
75 .Fn sysctl_create "const int *name" "u_int namelen" "void *oldp" \
76 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
77 "struct lwp *l" "const struct sysctlnode *rnode"
78 .Ft int
79 .Fn sysctl_destroy "const int *name" "u_int namelen" "void *oldp" \
80 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
81 "struct lwp *l" "const struct sysctlnode *rnode"
82 .Ft int
83 .Fn sysctl_query "const int *name" "u_int namelen" "void *oldp" \
84 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
85 "struct lwp *l" "const struct sysctlnode *rnode"
86 .Pp
87 Simple
88 .Dq helper
89 functions:
90 .Ft int
91 .Fn sysctl_needfunc "const int *name" "u_int namelen" "void *oldp" \
92 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
93 "struct lwp *l" "const struct sysctlnode *rnode"
94 .Ft int
95 .Fn sysctl_notavail "const int *name" "u_int namelen" "void *oldp" \
96 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
97 "struct lwp *l" "const struct sysctlnode *rnode"
98 .Ft int
99 .Fn sysctl_null "const int *name" "u_int namelen" "void *oldp" \
100 "size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \
101 "struct lwp *l" "const struct sysctlnode *rnode"
102 .Sh DESCRIPTION
103 The SYSCTL subsystem instruments a number of kernel tunables and other
104 data structures via a simple MIB-like interface, primarily for
105 consumption by userland programs, but also for use internally by the
106 kernel.
107 .Sh LOCKING
108 All operations on the SYSCTL tree must be protected by acquiring the
109 main SYSCTL lock.
110 The only functions that can be called when the lock is not held are
111 .Fn sysctl_lock ,
112 .Fn sysctl_createv ,
113 .Fn sysctl_destroyv ,
114 and
115 .Fn old_sysctl .
116 All other functions require the tree to be locked.
117 This is to prevent other users of the tree from moving nodes around
118 during an add operation, or from destroying nodes or subtrees that are
119 actively being used.
120 The lock is acquired by calling
121 .Fn sysctl_lock
122 with a pointer to the process's lwp
123 .Fa l
124 .Dv ( NULL
125 may be passed to all functions as the lwp pointer if no lwp is
126 appropriate, though any changes made via
127 .Fn sysctl_create ,
128 .Fn sysctl_destroy ,
129 .Fn sysctl_lookup ,
130 or by any helper function will be done with effective superuser
131 privileges).
132 The
133 .Fa oldp
134 and
135 .Fa savelen
136 arguments are a pointer to and the size of the memory region the
137 caller will be using to collect data from SYSCTL.
138 These may also be
139 .Dv NULL
140 and 0, respectively.
141 .Pp
142 The memory region will be locked via
143 .Fn uvm_vslock
144 if it is a region in userspace.
145 The address and size of the region are recorded so that when the
146 SYSCTL lock is to be released via
147 .Fn sysctl_unlock ,
148 only the lwp pointer
149 .Fa l
150 is required.
151 .Sh LOOKUPS
152 Once the lock has been acquired, it is typical to call
153 .Fn sysctl_dispatch
154 to handle the request.
155 .Fn sysctl_dispatch
156 will examine the contents of
157 .Fa name ,
158 an array of integers at least
159 .Fa namelen
160 long, which is to be located in kernel space, in order to determine
161 which function to call to handle the specific request.
162 .Pp
163 .Fn sysctl_dispatch
164 uses the following algorithm to determine the function to call:
165 .Pp
166 .Bl -bullet
167 .It
168 Scan the tree using
169 .Fn sysctl_locate
170 .It
171 If the node returned has a
172 .Dq helper
173 function, call it
174 .It
175 If the requested node was found but has no function, call
176 .Fn sysctl_lookup
177 .It
178 If the node was not found and
179 .Fa name
180 specifies one of
181 .Fn sysctl_query ,
182 .Fn sysctl_create ,
183 or
184 .Fn sysctl_destroy ,
185 call the appropriate function
186 .It
187 If none of these options applies and no other error was yet recorded,
188 return
189 .Er EOPNOTSUPP
190 .Pp
191 .El
192 The
193 .Fa oldp
194 and
195 .Fa oldlenp
196 arguments to
197 .Fn sysctl_dispatch ,
198 as with all the other core functions, describe an area into which the
199 current or requested value may be copied.
200 .Fa oldp
201 may or may not be a pointer into userspace (as dictated by whether
202 .Fa l
203 is
204 .Dv NULL
205 or not).
206 .Fa oldlenp
207 is a
208 .No non- Ns Dv NULL
209 pointer to a size_t.
210 .Fa newp
211 and
212 .Fa newlen
213 describe an area where the new value for the request may be found;
214 .Fa newp
215 may also be a pointer into userspace.
216 The
217 .Fa oname
218 argument is a
219 .No non- Ns Dv NULL
220 pointer to the base of the request currently
221 being processed.
222 By simple arithmetic on
223 .Fa name ,
224 .Fa namelen ,
225 and
226 .Fa oname ,
227 one can easily determine the entire original request and
228 .Fa namelen
229 values, if needed.
230 The
231 .Fa rnode
232 value, as passed to
233 .Fn sysctl_dispatch
234 represents the root of the tree into which the current request is to
235 be dispatched.
236 If
237 .Dv NULL ,
238 the main tree will be used.
239 .Pp
240 .Fn sysctl_locate
241 scans a tree for the node most specific to a request.
242 If the pointer referenced by
243 .Fa rnode
244 is not
245 .Dv NULL ,
246 the tree indicated is searched, otherwise the main tree
247 will be used.
248 The address of the most relevant node will be returned via
249 .Fa rnode
250 and the number of MIB entries consumed will be returned via
251 .Fa nip ,
252 if it is not
253 .Dv NULL .
254 .Pp
255 The
256 .Fn sysctl_lookup
257 function takes the same arguments as
258 .Fn sysctl_dispatch
259 with the caveat that the value for
260 .Fa namelen
261 must be zero in order to indicate that the node referenced by the
262 .Fa rnode
263 argument is the one to which the lookup is being applied.
264 .Sh CREATION AND DESTRUCTION OF NODES
265 New nodes are created and destroyed by the
266 .Fn sysctl_create
267 and
268 .Fn sysctl_destroy
269 functions.
270 These functions take the same arguments as
271 .Fn sysctl_dispatch
272 with the additional requirement that the
273 .Fa namelen
274 argument must be 1 and the
275 .Fa name
276 argument must point to an integer valued either
277 .Dv CTL_CREATE
278 or
279 .Dv CTL_CREATESYM
280 when creating a new node, or
281 .Dv CTL_DESTROY
282 when destroying
283 a node.
284 The
285 .Fa newp
286 and
287 .Fa newlen
288 arguments should point to a copy of the node to be created or
289 destroyed.
290 If the create or destroy operation was successful, a copy of the node
291 created or destroyed will be placed in the space indicated by
292 .Fa oldp
293 and
294 .Fa oldlenp .
295 If the create operation fails because of a conflict with an existing
296 node, a copy of that node will be returned instead.
297 .Pp
298 In order to facilitate the creation and destruction of nodes from a
299 given tree by kernel subsystems, the functions
300 .Fn sysctl_createv
301 and
302 .Fn sysctl_destroyv
303 are provided.
304 These functions take care of the overhead of filling in the contents
305 of the create or destroy request, dealing with locking, locating the
306 appropriate parent node, etc.
307 .Pp
308 The arguments to
309 .Fn sysctl_createv
310 are used to construct the new node.
311 If the
312 .Fa log
313 argument is not
314 .Dv NULL ,
315 a sysctllog structure will be allocated and the pointer referenced
316 will be changed to address it.
317 The same log may be used for any number of nodes, provided they are
318 all inserted into the same tree.
319 This allows for a series of nodes to be created and later removed from
320 the tree in a single transaction (via
321 .Fn sysctl_teardown )
322 without the need for any record
323 keeping on the caller's part.
324 The
325 .Fa cflags
326 argument is currently unused and must be zero.
327 The
328 .Fa rnode
329 argument must either be
330 .Dv NULL
331 or a valid pointer to a reference to the root of the tree into which
332 the new node must be placed.
333 If it is
334 .Dv NULL ,
335 the main tree will be used.
336 It is illegal for
337 .Fa rnode
338 to refer to a
339 .Dv NULL
340 pointer.
341 If the
342 .Fa cnode
343 argument is not
344 .Dv NULL ,
345 on return it will be adjusted to point to the address of the new node.
346 .Pp
347 The
348 .Fa flags
349 and
350 .Fa type
351 arguments are combined into the
352 .Fa sysctl_flags
353 field, and the current value for
354 .Dv SYSCTL_VERSION
355 is added in.
356 Note: the
357 .Dv CTLFLAG_PERMANENT
358 flag can only be set from SYSCTL setup routines (see
359 .Sx SETUP FUNCTIONS )
360 as called by
361 .Fn sysctl_init .
362 The
363 .Fa namep
364 argument is copied into the
365 .Fa sysctl_name
366 field and must be less than
367 .Dv SYSCTL_NAMELEN
368 characters in length.
369 The string indicated by
370 .Fa desc
371 will be copied if the
372 .Dv CTLFLAG_OWNDESC
373 flag is set, and will be used as the node's description.
374 Note: if
375 .Fn sysctl_destroyv
376 attempts to delete a node that does not own its own description (and
377 is not marked as permanent), but the deletion fails, the description
378 will be copied and
379 .Fn sysctl_destroyv
380 will set the
381 .Dv CTLFLAG_OWNDESC
382 flag.
383 .Pp
384 The
385 .Fa func
386 argument is the name of a
387 .Dq helper
388 function (see
389 .Sx HELPER FUNCTIONS AND MACROS ) .
390 If the
391 .Dv CTLFLAG_IMMEDIATE
392 flag is set, the
393 .Fa qv
394 argument will be interpreted as the initial value for the new
395 .Dq int
396 or
397 .Dq quad
398 node.
399 This flag does not apply to any other type of node.
400 The
401 .Fa newp
402 and
403 .Fa newlen
404 arguments describe the data external to SYSCTL that is to be
405 instrumented.
406 One of
407 .Fa func ,
408 .Fa qv
409 and the
410 .Dv CTLFLAG_IMMEDIATE
411 flag, or
412 .Fa newp
413 and
414 .Fa newlen
415 must be given for nodes that instrument data, otherwise an error is
416 returned.
417 .Pp
418 The remaining arguments are a list of integers specifying the path
419 through the MIB to the node being created.
420 The list must be terminated by the
421 .Dv CTL_EOL
422 value.
423 The penultimate value in the list may be
424 .Dv CTL_CREATE
425 if a dynamic MIB entry is to be made for this node.
426 .Fn sysctl_createv
427 specifically does not support
428 .Dv CTL_CREATESYM ,
429 since setup routines are
430 expected to be able to use the in-kernel
431 .Xr ksyms 4
432 interface to discover the location of the data to be instrumented.
433 If the node to be created matches a node that already exists, a return
434 code of 0 is given, indicating success.
435 .Pp
436 When using
437 .Fn sysctl_destroyv
438 to destroy a given node, the
439 .Fa rnode
440 argument, if not
441 .Dv NULL ,
442 is taken to be the root of the tree from which
443 the node is to be destroyed, otherwise the main tree is used.
444 The rest of the arguments are a list of integers specifying the path
445 through the MIB to the node being destroyed.
446 If the node being destroyed does not exist, a successful return code
447 is given.
448 Nodes marked with the
449 .Dv CTLFLAG_PERMANENT
450 flag cannot be destroyed.
451 .Sh HELPER FUNCTIONS AND MACROS
452 Helper functions are invoked with the same common argument set as
453 .Fn sysctl_dispatch
454 except that the
455 .Fa rnode
456 argument will never be
457 .Dv NULL .
458 It will be set to point to the node that corresponds most closely to
459 the current request.
460 Helpers are forbidden from modifying the node they are passed; they
461 should instead copy the structure if changes are required in order to
462 effect access control or other checks.
463 The
464 .Dq helper
465 prototype and function that needs to ensure that a newly assigned
466 value is within a certain range (presuming external data) would look
467 like the following:
468 .Pp
469 .Bd -literal -offset indent -compact
470 static int sysctl_helper(SYSCTLFN_PROTO);
472 static int
473 sysctl_helper(SYSCTLFN_ARGS)
474 {
475 struct sysctlnode node;
476 int t, error;
478 node = *rnode;
479 node.sysctl_data = \*[Am]t;
480 error = sysctl_lookup(SYSCTLFN_CALL(\*[Am]node));
481 if (error || newp == NULL)
482 return (error);
484 if (t \*[Lt] 0 || t \*[Gt] 20)
485 return (EINVAL);
487 *(int*)rnode-\*[Gt]sysctl_data = t;
488 return (0);
489 }
490 .Ed
491 .Pp
492 The use of the
493 .Dv SYSCTLFN_PROTO ,
494 .Dv SYSCTLFN_ARGS, and
495 .Dv SYSCTLFN_CALL
496 macros ensure that all arguments are passed properly.
497 The single argument to the
498 .Dv SYSCTLFN_CALL
499 macro is the pointer to the node being examined.
500 .Pp
501 Three basic helper functions are available for use.
502 .Fn sysctl_needfunc
503 will emit a warning to the system console whenever it is invoked and
504 provides a simplistic read-only interface to the given node.
505 .Fn sysctl_notavail
506 will forward
507 .Dq queries
508 to
509 .Fn sysctl_query
510 so that subtrees can be discovered, but will return
511 .Er EOPNOTSUPP
512 for any other condition.
513 .Fn sysctl_null
514 specifically ignores any arguments given, sets the value indicated by
515 .Fa oldlenp
516 to zero, and returns success.
517 .Sh SETUP FUNCTIONS
518 Though nodes can be added to the SYSCTL tree at any time, in order to
519 add nodes during the kernel bootstrap phase, a proper
520 .Dq setup
521 function must be used.
522 Setup functions are declared using the
523 .Dv SYSCTL_SETUP
524 macro, which takes the name of the function and a short string
525 description of the function as arguments.
526 .Po
527 See the
528 .Dv SYSCTL_DEBUG_SETUP
529 kernel configuration in
530 .Xr options 4 .
531 .Pc
532 The address of the function is added to a list of functions that
533 .Fn sysctl_init
534 traverses during initialization.
535 .Pp
536 Setup functions do not have to add nodes to the main tree, but can set
537 up their own trees for emulation or other purposes.
538 Emulations that require use of a main tree but with some nodes changed
539 to suit their own purposes can arrange to overlay a sparse private
540 tree onto their main tree by making the
541 .Fa e_sysctlovly
542 member of their struct emul definition point to the overlaid tree.
543 .Pp
544 Setup functions should take care to create all nodes from the root
545 down to the subtree they are creating, since the order in which setup
546 functions are called is arbitrary (the order in which setup functions
547 are called is only determined by the ordering of the object files as
548 passed to the linker when the kernel is built).
549 .Sh MISCELLANEOUS FUNCTIONS
550 .Fn sysctl_init
551 is called early in the kernel bootstrap process.
552 It initializes the SYSCTL lock, calls all the registered setup
553 functions, and marks the tree as permanent.
554 .Pp
555 .Fn sysctl_free
556 will unconditionally delete any and all nodes below the given node.
557 Its intended use is for the deletion of entire trees, not subtrees.
558 If a subtree is to be removed,
559 .Fn sysctl_destroy
560 or
561 .Fn sysctl_destroyv
562 should be used to ensure that nodes not owned by the sub-system being
563 deactivated are not mistakenly destroyed.
564 The SYSCTL lock must be held when calling this function.
565 .Pp
566 .Fn sysctl_teardown
567 unwinds a sysctllog and deletes the nodes in the opposite order in
568 which they were created.
569 .Pp
570 .Fn old_sysctl
571 provides an interface similar to the old SYSCTL implementation, with
572 the exception that access checks on a per-node basis are performed if
573 the
574 .Fa l
575 argument is
576 .No non- Ns Dv NULL .
577 If called with a
578 .Dv NULL
579 argument, the values for
580 .Fa newp
581 and
582 .Fa oldp
583 are interpreted as kernel addresses, and access is performed as for
584 the superuser.
585 .Sh NOTES
586 It is expected that nodes will be added to (or removed from) the tree
587 during the following stages of a machine's lifetime:
588 .Pp
589 .Bl -bullet -compact
590 .It
591 initialization -- when the kernel is booting
592 .It
593 autoconfiguration -- when devices are being probed at boot time
594 .It
595 .Dq plug and play
596 device attachment -- when a PC-Card, USB, or other device is plugged
597 in or attached
598 .It
599 module initialization -- when a module is being loaded
600 .It
601 .Dq run-time
602 -- when a process creates a node via the
603 .Xr sysctl 3
604 interface
605 .El
606 .Pp
607 Nodes marked with
608 .Dv CTLFLAG_PERMANENT
609 can only be added to a tree during the first or initialization phase,
610 and can never be removed.
611 The initialization phase terminates when the main tree's root is
612 marked with the
613 .Dv CTLFLAG_PERMANENT
614 flag.
615 Once the main tree is marked in this manner, no nodes can be added to
616 any tree that is marked with
617 .Dv CTLFLAG_READONLY
618 at its root, and no nodes can be added at all if the main tree's root
619 is so marked.
620 .Pp
621 Nodes added by device drivers, modules, and at device insertion time can
622 be added to (and removed from)
623 .Dq read-only
624 parent nodes.
625 .Pp
626 Nodes created by processes can only be added to
627 .Dq writable
628 parent nodes.
629 See
630 .Xr sysctl 3
631 for a description of the flags that are allowed to be used by
632 when creating nodes.
633 .Sh SEE ALSO
634 .Xr sysctl 3
635 .Sh HISTORY
636 The dynamic SYSCTL implementation first appeared in
637 .Nx 2.0 .
638 .Sh AUTHORS
639 .An Andrew Brown
640 .Aq atatat@NetBSD.org
641 designed and implemented the dynamic SYSCTL implementation.