| blob | 6c9a5783c6653c4d0528814b81ea2b7c6dd36ea2 |
1 .\" $NetBSD: sysctl.3,v 1.198 2009/07/22 22:54:15 alc Exp $
2 .\"
3 .\" Copyright (c) 1993
4 .\" The Regents of the University of California. 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 .\" 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.
17 .\"
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
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)sysctl.3 8.4 (Berkeley) 5/9/95
31 .\"
32 .Dd September 26, 2009
33 .Dt SYSCTL 3
34 .Os
35 .Sh NAME
36 .Nm sysctl ,
37 .Nm sysctlbyname ,
38 .Nm sysctlgetmibinfo ,
39 .Nm sysctlnametomib
40 .Nd get or set system information
41 .Sh LIBRARY
42 .Lb libc
43 .Sh SYNOPSIS
44 .In sys/param.h
45 .In sys/sysctl.h
46 .Ft int
47 .Fn sysctl "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" \
48 "const void *newp" "size_t newlen"
49 .Ft int
50 .Fn sysctlbyname "const char *sname" "void *oldp" "size_t *oldlenp" \
51 "const void *newp" "size_t newlen"
52 .Ft int
53 .Fn sysctlgetmibinfo "const char *sname" "int *name" "u_int *namelenp" \
54 "char *cname" "size_t *csz" "struct sysctlnode **rnode" "int v"
55 .Ft int
56 .Fn sysctlnametomib "const char *sname" "int *name" "size_t *namelenp"
57 .Sh DESCRIPTION
58 The
59 .Nm
60 function retrieves system information and allows processes with
61 appropriate privileges to set system information.
62 The information available from
63 .Nm
64 consists of integers, strings, and tables.
65 Information may be retrieved and set from the command interface
66 using the
67 .Xr sysctl 8
68 utility.
69 .Pp
70 Unless explicitly noted below,
71 .Nm
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.
75 Calls to
76 .Nm
77 are serialized to avoid deadlock.
78 .Pp
79 The state is described using a ``Management Information Base'' (MIB)
80 style name, listed in
81 .Fa name ,
82 which is a
83 .Fa namelen
84 length array of integers.
85 .Pp
86 The
87 .Fn sysctlbyname
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
91 .Fn sysctl .
92 .Pp
93 The information is copied into the buffer specified by
94 .Fa oldp .
95 The size of the buffer is given by the location specified by
96 .Fa oldlenp
97 before the call,
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,
104 .Fa oldp
105 and
106 .Fa oldlenp
107 should be set to
108 .Dv NULL .
109 .Pp
110 The size of the available data can be determined by calling
111 .Nm
112 with a
113 .Dv NULL
114 parameter for
115 .Fa oldp .
116 The size of the available data will be returned in the location pointed to by
117 .Fa oldlenp .
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.
122 .Pp
123 To set a new value,
124 .Fa newp
125 is set to point to a buffer of length
126 .Fa newlen
127 from which the requested value is to be taken.
128 If a new value is not to be set,
129 .Fa newp
130 should be set to
131 .Dv NULL
132 and
133 .Fa newlen
134 set to 0.
135 .Pp
136 The
137 .Fn sysctlnametomib
138 function can be used to map the string representation of a MIB entry
139 to the numeric version.
140 The
141 .Fa name
142 argument should point to an array of integers large enough to hold the
143 MIB, and
144 .Fa namelenp
145 should indicate the number of integer slots available.
146 Following a successful translation, the size_t indicated by
147 .Fa namelenp
148 will be changed to show the number of slots consumed.
149 .Pp
150 The
151 .Fn sysctlgetmibinfo
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
156 .Fa cname
157 and
158 .Fa csz .
159 .Fa csz
160 should indicate the size of the buffer pointed to by
161 .Fa cname
162 and on return, will indicate the size of the returned string including
163 the trailing
164 .Sq nul
165 character.
166 .Pp
167 The
168 .Fa rnode
169 and
170 .Fa v
171 arguments to
172 .Fn sysctlgetmibinfo
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.
175 If
176 .Fa rnode
177 is
178 .Dv NULL ,
179 .Fn sysctlgetmibinfo
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
182 kept up to date.
183 The
184 .Fa v
185 argument is ignored in this case.
186 If
187 .Fa rnode
188 is not
189 .Dv NULL
190 but the pointer it references is, on a successful return,
191 .Fa rnode
192 will be adjusted to point to a copy of the terminal node.
193 The
194 .Fa v
195 argument indicates which version of the
196 .Nm
197 node structure the caller wants.
198 The application must later
199 .Fn free
200 this copy.
201 If neither
202 .Fa rnode
203 nor the pointer it references are
204 .Dv NULL ,
205 the pointer is used as the address of a tree over which the parsing is
206 done.
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
209 .Fa v
210 must agree with the version indicated by the tree.
211 It is recommended that applications always use
212 .Dv SYSCTL_VERSION
213 as the value for
214 .Fa v ,
215 as defined in the include file
216 .Pa sys/sysctl.h .
217 .Pp
218 The numeric and text names of sysctl variables are described in
219 .Xr sysctl 7 .
220 The numeric names are defined as preprocessor macros.
221 The top level names are defined with a CTL_ prefix in
222 .Aq Pa sys/sysctl.h .
223 The next and subsequent levels down have different prefixes for each
224 subtree.
225 .Pp
226 For example, the following retrieves the maximum number of processes allowed
227 in the system - the
228 .Li kern.maxproc
229 variable:
230 .Bd -literal -offset indent -compact
231 int mib[2], maxproc;
232 size_t len;
233 .sp
234 mib[0] = CTL_KERN;
235 mib[1] = KERN_MAXPROC;
236 len = sizeof(maxproc);
237 sysctl(mib, 2, \*[Am]maxproc, \*[Am]len, NULL, 0);
238 .Ed
239 .sp
240 To retrieve the standard search path for the system utilities -
241 .Li user.cs_path :
242 .Bd -literal -offset indent -compact
243 int mib[2];
244 size_t len;
245 char *p;
246 .sp
247 mib[0] = CTL_USER;
248 mib[1] = USER_CS_PATH;
249 sysctl(mib, 2, NULL, \*[Am]len, NULL, 0);
250 p = malloc(len);
251 sysctl(mib, 2, p, \*[Am]len, NULL, 0);
252 .Ed
253 .Sh DYNAMIC OPERATIONS
254 Several meta-identifiers are provided to perform operations on the
255 .Nm
256 tree itself, or support alternate means of accessing the data
257 instrumented by the
258 .Nm
259 tree.
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
267 .El
268 .Pp
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
271 .Aq Pa sys/sysctl.h
272 as:
273 .Pp
274 .Bd -literal
275 struct sysctlnode {
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 */
280 uint32_t __rsvd;
281 union {
282 struct {
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 */
286 } scu_child;
287 struct {
288 void *sud_data; /* pointer to external data */
289 size_t sud_offset; /* offset to data */
290 } scu_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 */
294 } sysctl_un;
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 */
299 };
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
309 .Ed
310 .Pp
311 Querying the tree to discover the name to number mapping permits
312 dynamic discovery of all the data that the tree currently has
313 instrumented.
314 For example, to discover all the nodes below the
315 CTL_VFS node:
316 .Pp
317 .Bd -literal -offset indent -compact
318 struct sysctlnode query, vfs[128];
319 int mib[2];
320 size_t len;
321 .sp
322 mib[0] = CTL_VFS;
323 mib[1] = CTL_QUERY;
324 memset(\*[Am]query, 0, sizeof(query));
325 query.sysctl_flags = SYSCTL_VERSION;
326 len = sizeof(vfs);
327 sysctl(mib, 2, \*[Am]vfs[0], \*[Am]len, \*[Am]query, sizeof(query));
328 .Ed
329 .Pp
330 Note that a reference to an empty node with
331 .Fa sysctl_flags
332 set to
333 .Dv SYSCTL_VERSION
334 is passed to sysctl in order to indicate the version that the program
335 is using.
336 All dynamic operations passing nodes into sysctl require that the
337 version be explicitly specified.
338 .Pp
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
343 .Fa new
344 and
345 .Fa newlen
346 arguments.
347 If valid values for
348 .Fa old
349 and
350 .Fa oldlenp
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.
354 .Pp
355 The minimum requirements for creating a node are setting the
356 .Fa sysctl_flags
357 to indicate the new node's type,
358 .Fa sysctl_num
359 to either the new node's number (or CTL_CREATE or CTL_CREATESYM if a
360 dynamically allocated MIB number is acceptable),
361 .Fa sysctl_size
362 to the size of the data to be instrumented (which must agree with the
363 given type), and
364 .Fa sysctl_name
365 must be set to the new node's name.
366 Nodes that are not of type
367 .Dq node
368 must also have some description of the data to be instrumented, which
369 will vary depending on what is to be instrumented.
370 .Pp
371 If existing kernel data is to be covered by this new node, its address
372 should be given in
373 .Fa sysctl_data
374 or, if CTL_CREATESYM is used,
375 .Fa sysctl_data
376 should be set to a string containing its name from the kernel's symbol
377 table.
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
380 .Fa sysctl_idata
381 or
382 .Fa sysctl_qdata ,
383 respectively, along with the SYSCTL_IMMEDIATE flag being set, or
384 .Fa sysctl_data
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.
391 .Pp
392 The
393 .Fa sysctl_csize ,
394 .Fa sysctl_clen ,
395 .Fa sysctl_child ,
396 .Fa sysctl_parent ,
397 and
398 .Fa sysctl_alias
399 members are used by the kernel to link the tree together and must be
400 .Dv NULL
401 or 0.
402 Nodes created in this manner cannot have helper functions, so
403 .Fa sysctl_func
404 must also be
405 .Dv NULL .
406 If the
407 .Fa sysctl_ver
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
413 of the tree.
414 .Pp
415 This example creates a new subtree and adds a node to it that controls the
416 .Fa audiodebug
417 kernel variable, thereby making it tunable at at any time, without
418 needing to use
419 .Xr ddb 4
420 or
421 .Xr kvm 3
422 to alter the kernel's memory directly.
423 .Pp
424 .Bd -literal -offset indent -compact
425 struct sysctlnode node;
426 int mib[2];
427 size_t len;
428 .sp
429 mib[0] = CTL_CREATE; /* create at top-level */
430 len = sizeof(node);
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);
436 .sp
437 mib[0] = node.sysctl_num; /* use new MIB number */
438 mib[1] = CTL_CREATESYM; /* create at second level */
439 len = sizeof(node);
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);
446 .Ed
447 .Pp
448 The process for deleting nodes is similar, but less data needs to
449 be supplied.
450 Only the
451 .Fa sysctl_num
452 field
453 needs to be filled in; almost all other fields must be left blank.
454 The
455 .Fa sysctl_name
456 and/or
457 .Fa sysctl_ver
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.
461 If valid values for
462 .Fa old
463 and
464 .Fa oldlenp
465 are supplied and a node is deleted, a copy of what was in the MIB tree
466 will be returned.
467 .Pp
468 This sample code shows the deletion of the two nodes created in the
469 above example:
470 .Pp
471 .Bd -literal -offset indent -compact
472 int mib[2];
473 .sp
474 len = sizeof(node);
475 memset(\*[Am]node, 0, len);
476 node.sysctl_flags = SYSCTL_VERSION;
477 .sp
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);
482 .sp
483 mib[0] = CTL_DESTROY;
484 node.sysctl_num = 3214; /* now deleting "local" */
485 sysctl(\*[Am]mib[0], 1, NULL, NULL, \*[Am]node, len);
486 .Ed
487 .Pp
488 Descriptions of each of the nodes can also be retrieved, if they are
489 available.
490 Descriptions can be retrieved in bulk at each level or on a per-node
491 basis.
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
494 size.
495 The length indicated includes the terminating
496 .Sq nul
497 character.
498 Nodes that have no description or where the description is not
499 available are indicated by an empty string.
500 The
501 .Fa descr_ver
502 will match the
503 .Fa sysctl_ver
504 value for a given node, so that descriptions for nodes whose number
505 have been recycled can be detected and ignored or discarded.
506 .Pp
507 .Bd -literal
508 struct sysctldesc {
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 */
513 };
514 .Ed
515 .Pp
516 The
517 .Fn NEXT_DESCR
518 macro can be used to skip to the next description in the retrieved
519 list.
520 .Pp
521 .Bd -literal -offset indent -compact
522 struct sysctlnode desc;
523 struct sysctldesc *d;
524 char buf[1024];
525 int mib[2];
526 size_t len;
527 .sp
528 /* retrieve kern-level descriptions */
529 mib[0] = CTL_KERN;
530 mib[1] = CTL_DESCRIBE;
531 d = (struct sysctldesc *)\*[Am]buf[0];
532 len = sizeof(buf);
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,
536 d-\*[Gt]descr_str);
537 d = NEXT_DESCR(d);
538 }
539 .sp
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];
545 len = sizeof(buf);
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);
548 .Ed
549 .Pp
550 Descriptions can also be set as follows, subject to the following rules:
551 .Pp
552 .Bl -bullet -compact
553 .It
554 The kernel securelevel is at zero or lower
555 .It
556 The caller has super-user privileges
557 .It
558 The node does not currently have a description
559 .It
560 The node is not marked as
561 .Dq permanent
562 .El
563 .Pp
564 .Bd -literal -offset indent -compact
565 struct sysctlnode desc;
566 int mib[2];
567 .sp
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));
576 .Ed
577 .Pp
578 Upon successfully setting a description, the new description will be
579 returned in the space indicated by the
580 .Fa oldp
581 and
582 .Fa oldlenp
583 arguments.
584 .Pp
585 The
586 .Fa sysctl_flags
587 field in the struct sysctlnode contains the sysctl version, node type
588 information, and a number of flags.
589 The macros
590 .Fn SYSCTL_VERS ,
591 .Fn SYSCTL_TYPE ,
592 and
593 .Fn SYSCTL_FLAGS
594 can be used to access the different fields.
595 Valid flags are:
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
603 processes)
604 .It CTLFLAG\_OWNDATA Node owns data and does not instrument
605 existing data
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
609 form
610 .It CTLFLAG\_ROOT Node is the root of a tree (cannot be set at
611 any time)
612 .It CTLFLAG\_ANYNUMBER Node matches any MIB number (cannot be set by
613 processes)
614 .It CTLFLAG\_HIDDEN Node not displayed by default
615 .It CTLFLAG\_ALIAS Node refers to a sibling node (cannot be set
616 by processes)
617 .It CTLFLAG\_OWNDESC Node owns its own description string space
618 .El
619 .Sh RETURN VALUES
620 If the call to
621 .Nm
622 is successful, 0 is returned.
623 Otherwise \-1 is returned and
624 .Va errno
625 is set appropriately.
626 .Sh FILES
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
633 .It Aq Pa sys/gmon.h
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
656 .El
657 .Sh ERRORS
658 The following errors may be reported:
659 .Bl -tag -width Er
660 .It Bq Er EFAULT
661 The buffer
662 .Fa name ,
663 .Fa oldp ,
664 .Fa newp ,
665 or length pointer
666 .Fa oldlenp
667 contains an invalid address, or the requested value is temporarily
668 unavailable.
669 .It Bq Er EINVAL
670 The
671 .Fa name
672 array is zero or greater than CTL_MAXNAME.
673 .It Bq Er EINVAL
674 A non-null
675 .Fa newp
676 is given and its specified length in
677 .Fa newlen
678 is too large or too small, or the given value is not acceptable for
679 the given node.
680 .It Bq Er EISDIR
681 The
682 .Fa name
683 array specifies an intermediate rather than terminal name.
684 .It Bq Er ENOENT
685 The
686 .Fa name
687 array specifies a node that does not exist in the tree.
688 .It Bq Er ENOENT
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.
691 .It Bq Er ENOMEM
692 The length pointed to by
693 .Fa oldlenp
694 is too short to hold the requested value.
695 .It Bq Er ENOTDIR
696 The
697 .Fa name
698 array specifies a node below a node that addresses data.
699 .It Bq Er ENOTEMPTY
700 An attempt was made to destroy a node that still has children.
701 .It Bq Er EOPNOTSUPP
702 The
703 .Fa name
704 array specifies a value that is unknown or a meta-operation was
705 attempted that the requested node does not support.
706 .It Bq Er EPERM
707 An attempt is made to set a read-only value.
708 .It Bq Er EPERM
709 A process without appropriate privilege attempts to set a value or to
710 create or destroy a node.
711 .It Bq Er EPERM
712 An attempt to change a value protected by the current kernel security
713 level is made.
714 .El
715 .Sh SEE ALSO
716 .Xr sysctl 7 ,
717 .Xr sysctl 8 ,
718 .Xr secmodel_securelevel 9
719 .\" .Xr sysctl 9
720 .Sh HISTORY
721 The
722 .Nm
723 function first appeared in
724 .Bx 4.4 .