1 .\" $NetBSD: sysctl.3,v 1.200 2010/03/22 19:30:54 joerg Exp $
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)sysctl.3 8.4 (Berkeley) 5/9/95
32 .Dd September 26, 2009
38 .Nm sysctlgetmibinfo ,
40 .Nd get or set system information
47 .Fn sysctl "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" \
48 "const void *newp" "size_t newlen"
50 .Fn sysctlbyname "const char *sname" "void *oldp" "size_t *oldlenp" \
51 "const void *newp" "size_t newlen"
53 .Fn sysctlgetmibinfo "const char *sname" "int *name" "u_int *namelenp" \
54 "char *cname" "size_t *csz" "struct sysctlnode **rnode" "int v"
56 .Fn sysctlnametomib "const char *sname" "int *name" "size_t *namelenp"
60 function retrieves system information and allows processes with
61 appropriate privileges to set system information.
62 The information available from
64 consists of integers, strings, and tables.
65 Information may be retrieved and set from the command interface
70 Unless explicitly noted below,
72 returns a consistent snapshot of the data requested.
73 Consistency is obtained by locking the destination
74 buffer into memory so that the data may be copied out without blocking.
77 are serialized to avoid deadlock.
79 The state is described using a ``Management Information Base'' (MIB)
84 length array of integers.
88 function accepts a string representation of a MIB entry and internally
89 maps it to the appropriate numeric MIB representation.
90 Its semantics are otherwise no different from
93 The information is copied into the buffer specified by
95 The size of the buffer is given by the location specified by
98 and that location gives the amount of data copied after a successful call.
99 If the amount of data available is greater
100 than the size of the buffer supplied,
101 the call supplies as much data as fits in the buffer provided
102 and returns with the error code ENOMEM.
103 If the old value is not desired,
110 The size of the available data can be determined by calling
116 The size of the available data will be returned in the location pointed to by
118 For some operations, the amount of space may change often.
119 For these operations,
120 the system attempts to round up so that the returned size is
121 large enough for a call to return the data shortly thereafter.
125 is set to point to a buffer of length
127 from which the requested value is to be taken.
128 If a new value is not to be set,
138 function can be used to map the string representation of a MIB entry
139 to the numeric version.
142 argument should point to an array of integers large enough to hold the
145 should indicate the number of integer slots available.
146 Following a successful translation, the size_t indicated by
148 will be changed to show the number of slots consumed.
152 function performs name translation similar to
153 .Fn sysctlnametomib ,
154 but also canonicalizes the name (or returns the first erroneous token
155 from the string being parsed) into the space indicated by
160 should indicate the size of the buffer pointed to by
162 and on return, will indicate the size of the returned string including
173 are used to provide a tree for it to parse into, and to get back
174 either a pointer to, or a copy of, the terminal node.
180 uses its own internal tree for parsing, and checks it against the
181 kernel at each call, to make sure that the name-to-number mapping is
185 argument is ignored in this case.
190 but the pointer it references is, on a successful return,
192 will be adjusted to point to a copy of the terminal node.
195 argument indicates which version of the
197 node structure the caller wants.
198 The application must later
203 nor the pointer it references are
205 the pointer is used as the address of a tree over which the parsing is
207 In this last case, the tree is not checked against the kernel, no
208 refreshing of the mappings is performed, and the value given by
210 must agree with the version indicated by the tree.
211 It is recommended that applications always use
215 as defined in the include file
218 The numeric and text names of sysctl variables are described in
220 The numeric names are defined as preprocessor macros.
221 The top level names are defined with a CTL_ prefix in
223 The next and subsequent levels down have different prefixes for each
226 For example, the following retrieves the maximum number of processes allowed
230 .Bd -literal -offset indent -compact
235 mib[1] = KERN_MAXPROC;
236 len = sizeof(maxproc);
237 sysctl(mib, 2, \*[Am]maxproc, \*[Am]len, NULL, 0);
240 To retrieve the standard search path for the system utilities -
242 .Bd -literal -offset indent -compact
248 mib[1] = USER_CS_PATH;
249 sysctl(mib, 2, NULL, \*[Am]len, NULL, 0);
251 sysctl(mib, 2, p, \*[Am]len, NULL, 0);
253 .Sh DYNAMIC OPERATIONS
254 Several meta-identifiers are provided to perform operations on the
256 tree itself, or support alternate means of accessing the data
260 .Bl -column CTLXCREATESYMXXX
261 .It Sy Name Description
262 .It CTL\_QUERY Retrieve a mapping of names to numbers below a given node
263 .It CTL\_CREATE Create a new node
264 .It CTL\_CREATESYM Create a new node by its kernel symbol
265 .It CTL\_DESTROY Destroy a node
266 .It CTL\_DESCRIBE Retrieve node descriptions
269 The core interface to all of these meta-functions is the structure
270 that the kernel uses to describe the tree internally, as defined in
276 uint32_t sysctl_flags; /* flags and type */
277 int32_t sysctl_num; /* mib number */
278 char sysctl_name[SYSCTL_NAMELEN]; /* node name */
279 uint32_t sysctl_ver; /* node's version vs. rest of tree */
283 uint32_t suc_csize; /* size of child node array */
284 uint32_t suc_clen; /* number of valid children */
285 struct sysctlnode* suc_child; /* array of child nodes */
288 void *sud_data; /* pointer to external data */
289 size_t sud_offset; /* offset to data */
291 int32_t scu_alias; /* node this node refers to */
292 int32_t scu_idata; /* immediate "int" data */
293 u_quad_t scu_qdata; /* immediate "u_quad_t" data */
295 size_t _sysctl_size; /* size of instrumented data */
296 sysctlfn _sysctl_func; /* access helper function */
297 struct sysctlnode *sysctl_parent; /* parent of this node */
298 const char *sysctl_desc; /* description of node */
301 #define sysctl_csize sysctl_un.scu_child.suc_csize
302 #define sysctl_clen sysctl_un.scu_child.suc_clen
303 #define sysctl_child sysctl_un.scu_child.suc_child
304 #define sysctl_data sysctl_un.scu_data.sud_data
305 #define sysctl_offset sysctl_un.scu_data.sud_offset
306 #define sysctl_alias sysctl_un.scu_alias
307 #define sysctl_idata sysctl_un.scu_idata
308 #define sysctl_qdata sysctl_un.scu_qdata
311 Querying the tree to discover the name to number mapping permits
312 dynamic discovery of all the data that the tree currently has
314 For example, to discover all the nodes below the
317 .Bd -literal -offset indent -compact
318 struct sysctlnode query, vfs[128];
324 memset(\*[Am]query, 0, sizeof(query));
325 query.sysctl_flags = SYSCTL_VERSION;
327 sysctl(mib, 2, \*[Am]vfs[0], \*[Am]len, \*[Am]query, sizeof(query));
330 Note that a reference to an empty node with
334 is passed to sysctl in order to indicate the version that the program
336 All dynamic operations passing nodes into sysctl require that the
337 version be explicitly specified.
339 Creation and destruction of nodes works by constructing part of a new
340 node description (or a description of the existing node) and invoking
341 CTL_CREATE (or CTL_CREATESYM) or CTL_DESTROY at the parent of the new
342 node, with a pointer to the new node passed via the
351 are passed, a copy of the new node once in the tree will be returned.
352 If the create operation fails because a node with the same name or MIB
353 number exists, a copy of the conflicting node will be returned.
355 The minimum requirements for creating a node are setting the
357 to indicate the new node's type,
359 to either the new node's number (or CTL_CREATE or CTL_CREATESYM if a
360 dynamically allocated MIB number is acceptable),
362 to the size of the data to be instrumented (which must agree with the
365 must be set to the new node's name.
366 Nodes that are not of type
368 must also have some description of the data to be instrumented, which
369 will vary depending on what is to be instrumented.
371 If existing kernel data is to be covered by this new node, its address
374 or, if CTL_CREATESYM is used,
376 should be set to a string containing its name from the kernel's symbol
378 If new data is to be instrumented and an initial value is available,
379 the new integer or quad type data should be placed into either
383 respectively, along with the SYSCTL_IMMEDIATE flag being set, or
385 should be set to point to a copy of the new data, and the
386 SYSCTL_OWNDATA flag must be set.
387 This latter method is the only way that new string and struct type
388 nodes can be initialized.
389 Invalid kernel addresses are accepted, but any attempt to access those
390 nodes will return an error.
399 members are used by the kernel to link the tree together and must be
402 Nodes created in this manner cannot have helper functions, so
408 member is non-zero, it must match either the version of the parent or
409 the version at the root of the MIB or an error is returned.
410 This can be used to ensure that nodes are only added or removed from a
411 known state of the tree.
412 Note: It may not be possible to determine the version at the root
415 This example creates a new subtree and adds a node to it that controls the
417 kernel variable, thereby making it tunable at at any time, without
422 to alter the kernel's memory directly.
424 .Bd -literal -offset indent -compact
425 struct sysctlnode node;
429 mib[0] = CTL_CREATE; /* create at top-level */
431 memset(\*[Am]node, 0, len);
432 node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_NODE;
433 snprintf(node.sysctl_name, sizeof(node.sysctl_name), "local");
434 node.sysctl_num = CTL_CREATE; /* request dynamic MIB number */
435 sysctl(\*[Am]mib[0], 1, \*[Am]node, \*[Am]len, \*[Am]node, len);
437 mib[0] = node.sysctl_num; /* use new MIB number */
438 mib[1] = CTL_CREATESYM; /* create at second level */
440 memset(\*[Am]node, 0, len);
441 node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_INT;
442 snprintf(node.sysctl_name, sizeof(node.sysctl_name), "audiodebug");
443 node.sysctl_num = CTL_CREATE;
444 node.sysctl_data = "audiodebug"; /* kernel symbol to be used */
445 sysctl(\*[Am]mib[0], 2, NULL, NULL, \*[Am]node, len);
448 The process for deleting nodes is similar, but less data needs to
453 needs to be filled in; almost all other fields must be left blank.
458 fields can be filled in with the name and version of the existing node
459 as additional checks on what will be deleted.
460 If all the given data fail to match any node, nothing will be deleted.
465 are supplied and a node is deleted, a copy of what was in the MIB tree
468 This sample code shows the deletion of the two nodes created in the
471 .Bd -literal -offset indent -compact
475 memset(\*[Am]node, 0, len);
476 node.sysctl_flags = SYSCTL_VERSION;
478 mib[0] = 3214; /* assumed number for "local" */
479 mib[1] = CTL_DESTROY;
480 node.sysctl_num = 3215; /* assumed number for "audiodebug" */
481 sysctl(\*[Am]mib[0], 2, NULL, NULL, \*[Am]node, len);
483 mib[0] = CTL_DESTROY;
484 node.sysctl_num = 3214; /* now deleting "local" */
485 sysctl(\*[Am]mib[0], 1, NULL, NULL, \*[Am]node, len);
488 Descriptions of each of the nodes can also be retrieved, if they are
490 Descriptions can be retrieved in bulk at each level or on a per-node
492 The layout of the buffer into which the descriptions are returned is a
493 series of variable length structures, each of which describes its own
495 The length indicated includes the terminating
498 Nodes that have no description or where the description is not
499 available are indicated by an empty string.
504 value for a given node, so that descriptions for nodes whose number
505 have been recycled can be detected and ignored or discarded.
509 int32_t descr_num; /* mib number of node */
510 uint32_t descr_ver; /* version of node */
511 uint32_t descr_len; /* length of description string */
512 char descr_str[1]; /* not really 1...see above */
518 macro can be used to skip to the next description in the retrieved
521 .Bd -literal -offset indent -compact
522 struct sysctlnode desc;
523 struct sysctldesc *d;
528 /* retrieve kern-level descriptions */
530 mib[1] = CTL_DESCRIBE;
531 d = (struct sysctldesc *)\*[Am]buf[0];
533 sysctl(mib, 2, d, \*[Am]len, NULL, 0);
534 while ((caddr_t)d \*[Lt] (caddr_t)\*[Am]buf[len]) {
535 printf("node %d: %.*s\\n", d-\*[Gt]descr_num, d-\*[Gt]descr_len,
540 /* retrieve description for kern.securelevel */
541 memset(\*[Am]desc, 0, sizeof(desc));
542 desc.sysctl_flags = SYSCTL_VERSION;
543 desc.sysctl_num = KERN_SECURELEVEL;
544 d = (struct sysctldesc *)\*[Am]buf[0];
546 sysctl(mib, 2, d, \*[Am]len, \*[Am]desc, sizeof(desc));
547 printf("kern.securelevel: %.*s\\n", d-\*[Gt]descr_len, d-\*[Gt]descr_str);
550 Descriptions can also be set as follows, subject to the following rules:
554 The kernel securelevel is at zero or lower
556 The caller has super-user privileges
558 The node does not currently have a description
560 The node is not marked as
564 .Bd -literal -offset indent -compact
565 struct sysctlnode desc;
568 /* presuming the given top-level node was just added... */
569 mib[0] = 3214; /* mib numbers taken from previous examples */
570 mib[1] = CTL_DESCRIBE;
571 memset(\*[Am]desc, 0, sizeof(desc));
572 desc.sysctl_flags = SYSCTL_VERSION;
573 desc.sysctl_num = 3215;
574 desc.sysctl_desc = "audio debug control knob";
575 sysctl(mib, 2, NULL, NULL, \*[Am]desc, sizeof(desc));
578 Upon successfully setting a description, the new description will be
579 returned in the space indicated by the
587 field in the struct sysctlnode contains the sysctl version, node type
588 information, and a number of flags.
594 can be used to access the different fields.
596 .Bl -column CTLFLAGXPERMANENTXXX
597 .It Sy Name Description
598 .It CTLFLAG\_READONLY Node is read-only
599 .It CTLFLAG\_READWRITE Node is writable by the superuser
600 .It CTLFLAG\_ANYWRITE Node is writable by anyone
601 .It CTLFLAG\_PRIVATE Node is readable only by the superuser
602 .It CTLFLAG\_PERMANENT Node cannot be removed (cannot be set by
604 .It CTLFLAG\_OWNDATA Node owns data and does not instrument
606 .It CTLFLAG\_IMMEDIATE Node contains instrumented data and does not
607 instrument existing data
608 .It CTLFLAG\_HEX Node's contents should be displayed in a hexadecimal
610 .It CTLFLAG\_ROOT Node is the root of a tree (cannot be set at
612 .It CTLFLAG\_ANYNUMBER Node matches any MIB number (cannot be set by
614 .It CTLFLAG\_HIDDEN Node not displayed by default
615 .It CTLFLAG\_ALIAS Node refers to a sibling node (cannot be set
617 .It CTLFLAG\_OWNDESC Node owns its own description string space
622 is successful, 0 is returned.
623 Otherwise \-1 is returned and
625 is set appropriately.
627 .Bl -tag -width \*[Lt]netinet6/udp6Xvar.h\*[Gt] -compact
628 .It Aq Pa sys/sysctl.h
629 definitions for top level identifiers, second level kernel and hardware
630 identifiers, and user level identifiers
631 .It Aq Pa sys/socket.h
632 definitions for second level network identifiers
634 definitions for third level profiling identifiers
635 .It Aq Pa uvm/uvm_param.h
636 definitions for second level virtual memory identifiers
637 .It Aq Pa netinet/in.h
638 definitions for third level IPv4/v6 identifiers and
639 fourth level IPv4/v6 identifiers
640 .It Aq Pa netinet/icmp_var.h
641 definitions for fourth level ICMP identifiers
642 .It Aq Pa netinet/icmp6.h
643 definitions for fourth level ICMPv6 identifiers
644 .It Aq Pa netinet/tcp_var.h
645 definitions for fourth level TCP identifiers
646 .It Aq Pa netinet/udp_var.h
647 definitions for fourth level UDP identifiers
648 .It Aq Pa netinet6/udp6_var.h
649 definitions for fourth level IPv6 UDP identifiers
650 .It Aq Pa netinet6/ipsec.h
651 definitions for fourth level IPsec identifiers
652 .It Aq Pa netkey/key_var.h
653 definitions for third level PF_KEY identifiers
654 .It Aq Pa machine/cpu.h
655 definitions for second level machdep identifiers
658 The following errors may be reported:
667 contains an invalid address, or the requested value is temporarily
672 array is zero or greater than CTL_MAXNAME.
676 is given and its specified length in
678 is too large or too small, or the given value is not acceptable for
683 array specifies an intermediate rather than terminal name.
687 array specifies a node that does not exist in the tree.
689 An attempt was made to destroy a node that does not exist, or to
690 create or destroy a node below a node that does not exist.
692 The length pointed to by
694 is too short to hold the requested value.
698 array specifies a node below a node that addresses data.
700 An attempt was made to destroy a node that still has children.
704 array specifies a value that is unknown or a meta-operation was
705 attempted that the requested node does not support.
707 An attempt is made to set a read-only value.
709 A process without appropriate privilege attempts to set a value or to
710 create or destroy a node.
712 An attempt to change a value protected by the current kernel security
718 .Xr secmodel_securelevel 9
723 function first appeared in