| blob | 2fd2c12bff2ab869cf8043f37967a3cd1fb6a810 |
1 .\" $NetBSD: sysctl.3,v 1.202 2014/06/13 22:05:15 wiz 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 June 13, 2014
33 .Dt SYSCTL 3
34 .Os
35 .Sh NAME
36 .Nm sysctl ,
37 .Nm sysctlbyname ,
38 .Nm sysctlgetmibinfo ,
39 .Nm sysctlnametomib ,
40 .Nm asysctl ,
41 .Nm asysctlbyname
42 .Nd get or set system information
43 .Sh LIBRARY
44 .Lb libc
45 .Sh SYNOPSIS
46 .In sys/param.h
47 .In sys/sysctl.h
48 .Ft int
49 .Fn sysctl "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" \
50 "const void *newp" "size_t newlen"
51 .Ft int
52 .Fn sysctlbyname "const char *sname" "void *oldp" "size_t *oldlenp" \
53 "const void *newp" "size_t newlen"
54 .Ft int
55 .Fn sysctlgetmibinfo "const char *sname" "int *name" "u_int *namelenp" \
56 "char *cname" "size_t *csz" "struct sysctlnode **rnode" "int v"
57 .Ft int
58 .Fn sysctlnametomib "const char *sname" "int *name" "size_t *namelenp"
59 .Ft void *
60 .Fn asysctl "const int *name" "size_t namelen" "size_t *len"
61 .Ft void *
62 .Fn asysctlbyname "const char *sname" "size_t *len"
63 .Sh DESCRIPTION
64 The
65 .Nm
66 function retrieves system information and allows processes with
67 appropriate privileges to set system information.
68 The information available from
69 .Nm
70 consists of integers, strings, and tables.
71 Information may be retrieved and set from the command interface
72 using the
73 .Xr sysctl 8
74 utility.
75 .Pp
76 Unless explicitly noted below,
77 .Nm
78 returns a consistent snapshot of the data requested.
79 Consistency is obtained by locking the destination
80 buffer into memory so that the data may be copied out without blocking.
81 Calls to
82 .Nm
83 are serialized to avoid deadlock.
84 .Pp
85 The state is described using a ``Management Information Base'' (MIB)
86 style name, listed in
87 .Fa name ,
88 which is a
89 .Fa namelen
90 length array of integers.
91 .Pp
92 The
93 .Fn sysctlbyname
94 function accepts a string representation of a MIB entry and internally
95 maps it to the appropriate numeric MIB representation.
96 Its semantics are otherwise no different from
97 .Fn sysctl .
98 .Pp
99 The information is copied into the buffer specified by
100 .Fa oldp .
101 The size of the buffer is given by the location specified by
102 .Fa oldlenp
103 before the call,
104 and that location gives the amount of data copied after a successful call.
105 If the amount of data available is greater
106 than the size of the buffer supplied,
107 the call supplies as much data as fits in the buffer provided
108 and returns with the error code ENOMEM.
109 If the old value is not desired,
110 .Fa oldp
111 and
112 .Fa oldlenp
113 should be set to
114 .Dv NULL .
115 .Pp
116 The size of the available data can be determined by calling
117 .Nm
118 with a
119 .Dv NULL
120 parameter for
121 .Fa oldp .
122 The size of the available data will be returned in the location pointed to by
123 .Fa oldlenp .
124 For some operations, the amount of space may change often.
125 For these operations,
126 the system attempts to round up so that the returned size is
127 large enough for a call to return the data shortly thereafter.
128 .Pp
129 To set a new value,
130 .Fa newp
131 is set to point to a buffer of length
132 .Fa newlen
133 from which the requested value is to be taken.
134 If a new value is not to be set,
135 .Fa newp
136 should be set to
137 .Dv NULL
138 and
139 .Fa newlen
140 set to 0.
141 .Pp
142 The
143 .Fn sysctlnametomib
144 function can be used to map the string representation of a MIB entry
145 to the numeric version.
146 The
147 .Fa name
148 argument should point to an array of integers large enough to hold the
149 MIB, and
150 .Fa namelenp
151 should indicate the number of integer slots available.
152 Following a successful translation, the size_t indicated by
153 .Fa namelenp
154 will be changed to show the number of slots consumed.
155 .Pp
156 The
157 .Fn sysctlgetmibinfo
158 function performs name translation similar to
159 .Fn sysctlnametomib ,
160 but also canonicalizes the name (or returns the first erroneous token
161 from the string being parsed) into the space indicated by
162 .Fa cname
163 and
164 .Fa csz .
165 .Fa csz
166 should indicate the size of the buffer pointed to by
167 .Fa cname
168 and on return, will indicate the size of the returned string including
169 the trailing
170 .Sq nul
171 character.
172 .Pp
173 The
174 .Fa rnode
175 and
176 .Fa v
177 arguments to
178 .Fn sysctlgetmibinfo
179 are used to provide a tree for it to parse into, and to get back
180 either a pointer to, or a copy of, the terminal node.
181 If
182 .Fa rnode
183 is
184 .Dv NULL ,
185 .Fn sysctlgetmibinfo
186 uses its own internal tree for parsing, and checks it against the
187 kernel at each call, to make sure that the name-to-number mapping is
188 kept up to date.
189 The
190 .Fa v
191 argument is ignored in this case.
192 If
193 .Fa rnode
194 is not
195 .Dv NULL
196 but the pointer it references is, on a successful return,
197 .Fa rnode
198 will be adjusted to point to a copy of the terminal node.
199 The
200 .Fa v
201 argument indicates which version of the
202 .Nm
203 node structure the caller wants.
204 The application must later
205 .Fn free
206 this copy.
207 If neither
208 .Fa rnode
209 nor the pointer it references are
210 .Dv NULL ,
211 the pointer is used as the address of a tree over which the parsing is
212 done.
213 In this last case, the tree is not checked against the kernel, no
214 refreshing of the mappings is performed, and the value given by
215 .Fa v
216 must agree with the version indicated by the tree.
217 It is recommended that applications always use
218 .Dv SYSCTL_VERSION
219 as the value for
220 .Fa v ,
221 as defined in the include file
222 .Pa sys/sysctl.h .
223 .Pp
224 The numeric and text names of sysctl variables are described in
225 .Xr sysctl 7 .
226 The numeric names are defined as preprocessor macros.
227 The top level names are defined with a CTL_ prefix in
228 .In sys/sysctl.h .
229 The next and subsequent levels down have different prefixes for each
230 subtree.
231 .Pp
232 For example, the following retrieves the maximum number of processes allowed
233 in the system - the
234 .Li kern.maxproc
235 variable:
236 .Bd -literal -offset indent -compact
237 int mib[2], maxproc;
238 size_t len;
239 .sp
240 mib[0] = CTL_KERN;
241 mib[1] = KERN_MAXPROC;
242 len = sizeof(maxproc);
243 sysctl(mib, 2, \*[Am]maxproc, \*[Am]len, NULL, 0);
244 .Ed
245 .sp
246 To retrieve the standard search path for the system utilities -
247 .Li user.cs_path :
248 .Bd -literal -offset indent -compact
249 int mib[2];
250 size_t len;
251 char *p;
252 .sp
253 mib[0] = CTL_USER;
254 mib[1] = USER_CS_PATH;
255 sysctl(mib, 2, NULL, \*[Am]len, NULL, 0);
256 p = malloc(len);
257 sysctl(mib, 2, p, \*[Am]len, NULL, 0);
258 .Ed
259 .Pp
260 The
261 .Fn asysctl
262 and
263 .Fn asysctlbyname
264 functions are wrappers for
265 .Fn sysctl
266 and
267 .Fn sysctlbyname .
268 They return memory allocated with
269 .Xr malloc 3
270 and resize the buffer in a loop until all data fits.
271 .Sh DYNAMIC OPERATIONS
272 Several meta-identifiers are provided to perform operations on the
273 .Nm
274 tree itself, or support alternate means of accessing the data
275 instrumented by the
276 .Nm
277 tree.
278 .Bl -column CTLXCREATESYMXXX
279 .It Sy Name Description
280 .It CTL\_QUERY Retrieve a mapping of names to numbers below a given node
281 .It CTL\_CREATE Create a new node
282 .It CTL\_CREATESYM Create a new node by its kernel symbol
283 .It CTL\_DESTROY Destroy a node
284 .It CTL\_DESCRIBE Retrieve node descriptions
285 .El
286 .Pp
287 The core interface to all of these meta-functions is the structure
288 that the kernel uses to describe the tree internally, as defined in
289 .In sys/sysctl.h
290 as:
291 .Pp
292 .Bd -literal
293 struct sysctlnode {
294 uint32_t sysctl_flags; /* flags and type */
295 int32_t sysctl_num; /* mib number */
296 char sysctl_name[SYSCTL_NAMELEN]; /* node name */
297 uint32_t sysctl_ver; /* node's version vs. rest of tree */
298 uint32_t __rsvd;
299 union {
300 struct {
301 uint32_t suc_csize; /* size of child node array */
302 uint32_t suc_clen; /* number of valid children */
303 struct sysctlnode* suc_child; /* array of child nodes */
304 } scu_child;
305 struct {
306 void *sud_data; /* pointer to external data */
307 size_t sud_offset; /* offset to data */
308 } scu_data;
309 int32_t scu_alias; /* node this node refers to */
310 int32_t scu_idata; /* immediate "int" data */
311 u_quad_t scu_qdata; /* immediate "u_quad_t" data */
312 } sysctl_un;
313 size_t _sysctl_size; /* size of instrumented data */
314 sysctlfn _sysctl_func; /* access helper function */
315 struct sysctlnode *sysctl_parent; /* parent of this node */
316 const char *sysctl_desc; /* description of node */
317 };
319 #define sysctl_csize sysctl_un.scu_child.suc_csize
320 #define sysctl_clen sysctl_un.scu_child.suc_clen
321 #define sysctl_child sysctl_un.scu_child.suc_child
322 #define sysctl_data sysctl_un.scu_data.sud_data
323 #define sysctl_offset sysctl_un.scu_data.sud_offset
324 #define sysctl_alias sysctl_un.scu_alias
325 #define sysctl_idata sysctl_un.scu_idata
326 #define sysctl_qdata sysctl_un.scu_qdata
327 .Ed
328 .Pp
329 Querying the tree to discover the name to number mapping permits
330 dynamic discovery of all the data that the tree currently has
331 instrumented.
332 For example, to discover all the nodes below the
333 CTL_VFS node:
334 .Pp
335 .Bd -literal -offset indent -compact
336 struct sysctlnode query, vfs[128];
337 int mib[2];
338 size_t len;
339 .sp
340 mib[0] = CTL_VFS;
341 mib[1] = CTL_QUERY;
342 memset(\*[Am]query, 0, sizeof(query));
343 query.sysctl_flags = SYSCTL_VERSION;
344 len = sizeof(vfs);
345 sysctl(mib, 2, \*[Am]vfs[0], \*[Am]len, \*[Am]query, sizeof(query));
346 .Ed
347 .Pp
348 Note that a reference to an empty node with
349 .Fa sysctl_flags
350 set to
351 .Dv SYSCTL_VERSION
352 is passed to sysctl in order to indicate the version that the program
353 is using.
354 All dynamic operations passing nodes into sysctl require that the
355 version be explicitly specified.
356 .Pp
357 Creation and destruction of nodes works by constructing part of a new
358 node description (or a description of the existing node) and invoking
359 CTL_CREATE (or CTL_CREATESYM) or CTL_DESTROY at the parent of the new
360 node, with a pointer to the new node passed via the
361 .Fa new
362 and
363 .Fa newlen
364 arguments.
365 If valid values for
366 .Fa old
367 and
368 .Fa oldlenp
369 are passed, a copy of the new node once in the tree will be returned.
370 If the create operation fails because a node with the same name or MIB
371 number exists, a copy of the conflicting node will be returned.
372 .Pp
373 The minimum requirements for creating a node are setting the
374 .Fa sysctl_flags
375 to indicate the new node's type,
376 .Fa sysctl_num
377 to either the new node's number (or CTL_CREATE or CTL_CREATESYM if a
378 dynamically allocated MIB number is acceptable),
379 .Fa sysctl_size
380 to the size of the data to be instrumented (which must agree with the
381 given type), and
382 .Fa sysctl_name
383 must be set to the new node's name.
384 Nodes that are not of type
385 .Dq node
386 must also have some description of the data to be instrumented, which
387 will vary depending on what is to be instrumented.
388 .Pp
389 If existing kernel data is to be covered by this new node, its address
390 should be given in
391 .Fa sysctl_data
392 or, if CTL_CREATESYM is used,
393 .Fa sysctl_data
394 should be set to a string containing its name from the kernel's symbol
395 table.
396 If new data is to be instrumented and an initial value is available,
397 the new integer or quad type data should be placed into either
398 .Fa sysctl_idata
399 or
400 .Fa sysctl_qdata ,
401 respectively, along with the SYSCTL_IMMEDIATE flag being set, or
402 .Fa sysctl_data
403 should be set to point to a copy of the new data, and the
404 SYSCTL_OWNDATA flag must be set.
405 This latter method is the only way that new string and struct type
406 nodes can be initialized.
407 Invalid kernel addresses are accepted, but any attempt to access those
408 nodes will return an error.
409 .Pp
410 The
411 .Fa sysctl_csize ,
412 .Fa sysctl_clen ,
413 .Fa sysctl_child ,
414 .Fa sysctl_parent ,
415 and
416 .Fa sysctl_alias
417 members are used by the kernel to link the tree together and must be
418 .Dv NULL
419 or 0.
420 Nodes created in this manner cannot have helper functions, so
421 .Fa sysctl_func
422 must also be
423 .Dv NULL .
424 If the
425 .Fa sysctl_ver
426 member is non-zero, it must match either the version of the parent or
427 the version at the root of the MIB or an error is returned.
428 This can be used to ensure that nodes are only added or removed from a
429 known state of the tree.
430 Note: It may not be possible to determine the version at the root
431 of the tree.
432 .Pp
433 This example creates a new subtree and adds a node to it that controls the
434 .Fa audiodebug
435 kernel variable, thereby making it tunable at at any time, without
436 needing to use
437 .Xr ddb 4
438 or
439 .Xr kvm 3
440 to alter the kernel's memory directly.
441 .Pp
442 .Bd -literal -offset indent -compact
443 struct sysctlnode node;
444 int mib[2];
445 size_t len;
446 .sp
447 mib[0] = CTL_CREATE; /* create at top-level */
448 len = sizeof(node);
449 memset(\*[Am]node, 0, len);
450 node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_NODE;
451 snprintf(node.sysctl_name, sizeof(node.sysctl_name), "local");
452 node.sysctl_num = CTL_CREATE; /* request dynamic MIB number */
453 sysctl(\*[Am]mib[0], 1, \*[Am]node, \*[Am]len, \*[Am]node, len);
454 .sp
455 mib[0] = node.sysctl_num; /* use new MIB number */
456 mib[1] = CTL_CREATESYM; /* create at second level */
457 len = sizeof(node);
458 memset(\*[Am]node, 0, len);
459 node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_INT;
460 snprintf(node.sysctl_name, sizeof(node.sysctl_name), "audiodebug");
461 node.sysctl_num = CTL_CREATE;
462 node.sysctl_data = "audiodebug"; /* kernel symbol to be used */
463 sysctl(\*[Am]mib[0], 2, NULL, NULL, \*[Am]node, len);
464 .Ed
465 .Pp
466 The process for deleting nodes is similar, but less data needs to
467 be supplied.
468 Only the
469 .Fa sysctl_num
470 field
471 needs to be filled in; almost all other fields must be left blank.
472 The
473 .Fa sysctl_name
474 and/or
475 .Fa sysctl_ver
476 fields can be filled in with the name and version of the existing node
477 as additional checks on what will be deleted.
478 If all the given data fail to match any node, nothing will be deleted.
479 If valid values for
480 .Fa old
481 and
482 .Fa oldlenp
483 are supplied and a node is deleted, a copy of what was in the MIB tree
484 will be returned.
485 .Pp
486 This sample code shows the deletion of the two nodes created in the
487 above example:
488 .Pp
489 .Bd -literal -offset indent -compact
490 int mib[2];
491 .sp
492 len = sizeof(node);
493 memset(\*[Am]node, 0, len);
494 node.sysctl_flags = SYSCTL_VERSION;
495 .sp
496 mib[0] = 3214; /* assumed number for "local" */
497 mib[1] = CTL_DESTROY;
498 node.sysctl_num = 3215; /* assumed number for "audiodebug" */
499 sysctl(\*[Am]mib[0], 2, NULL, NULL, \*[Am]node, len);
500 .sp
501 mib[0] = CTL_DESTROY;
502 node.sysctl_num = 3214; /* now deleting "local" */
503 sysctl(\*[Am]mib[0], 1, NULL, NULL, \*[Am]node, len);
504 .Ed
505 .Pp
506 Descriptions of each of the nodes can also be retrieved, if they are
507 available.
508 Descriptions can be retrieved in bulk at each level or on a per-node
509 basis.
510 The layout of the buffer into which the descriptions are returned is a
511 series of variable length structures, each of which describes its own
512 size.
513 The length indicated includes the terminating
514 .Sq nul
515 character.
516 Nodes that have no description or where the description is not
517 available are indicated by an empty string.
518 The
519 .Fa descr_ver
520 will match the
521 .Fa sysctl_ver
522 value for a given node, so that descriptions for nodes whose number
523 have been recycled can be detected and ignored or discarded.
524 .Pp
525 .Bd -literal
526 struct sysctldesc {
527 int32_t descr_num; /* mib number of node */
528 uint32_t descr_ver; /* version of node */
529 uint32_t descr_len; /* length of description string */
530 char descr_str[1]; /* not really 1...see above */
531 };
532 .Ed
533 .Pp
534 The
535 .Fn NEXT_DESCR
536 macro can be used to skip to the next description in the retrieved
537 list.
538 .Pp
539 .Bd -literal -offset indent -compact
540 struct sysctlnode desc;
541 struct sysctldesc *d;
542 char buf[1024];
543 int mib[2];
544 size_t len;
545 .sp
546 /* retrieve kern-level descriptions */
547 mib[0] = CTL_KERN;
548 mib[1] = CTL_DESCRIBE;
549 d = (struct sysctldesc *)\*[Am]buf[0];
550 len = sizeof(buf);
551 sysctl(mib, 2, d, \*[Am]len, NULL, 0);
552 while ((caddr_t)d \*[Lt] (caddr_t)\*[Am]buf[len]) {
553 printf("node %d: %.*s\\n", d-\*[Gt]descr_num, d-\*[Gt]descr_len,
554 d-\*[Gt]descr_str);
555 d = NEXT_DESCR(d);
556 }
557 .sp
558 /* retrieve description for kern.securelevel */
559 memset(\*[Am]desc, 0, sizeof(desc));
560 desc.sysctl_flags = SYSCTL_VERSION;
561 desc.sysctl_num = KERN_SECURELEVEL;
562 d = (struct sysctldesc *)\*[Am]buf[0];
563 len = sizeof(buf);
564 sysctl(mib, 2, d, \*[Am]len, \*[Am]desc, sizeof(desc));
565 printf("kern.securelevel: %.*s\\n", d-\*[Gt]descr_len, d-\*[Gt]descr_str);
566 .Ed
567 .Pp
568 Descriptions can also be set as follows, subject to the following rules:
569 .Pp
570 .Bl -bullet -compact
571 .It
572 The kernel securelevel is at zero or lower
573 .It
574 The caller has super-user privileges
575 .It
576 The node does not currently have a description
577 .It
578 The node is not marked as
579 .Dq permanent
580 .El
581 .Pp
582 .Bd -literal -offset indent -compact
583 struct sysctlnode desc;
584 int mib[2];
585 .sp
586 /* presuming the given top-level node was just added... */
587 mib[0] = 3214; /* mib numbers taken from previous examples */
588 mib[1] = CTL_DESCRIBE;
589 memset(\*[Am]desc, 0, sizeof(desc));
590 desc.sysctl_flags = SYSCTL_VERSION;
591 desc.sysctl_num = 3215;
592 desc.sysctl_desc = "audio debug control knob";
593 sysctl(mib, 2, NULL, NULL, \*[Am]desc, sizeof(desc));
594 .Ed
595 .Pp
596 Upon successfully setting a description, the new description will be
597 returned in the space indicated by the
598 .Fa oldp
599 and
600 .Fa oldlenp
601 arguments.
602 .Pp
603 The
604 .Fa sysctl_flags
605 field in the struct sysctlnode contains the sysctl version, node type
606 information, and a number of flags.
607 The macros
608 .Fn SYSCTL_VERS ,
609 .Fn SYSCTL_TYPE ,
610 and
611 .Fn SYSCTL_FLAGS
612 can be used to access the different fields.
613 Valid flags are:
614 .Bl -column CTLFLAGXPERMANENTXXX
615 .It Sy Name Description
616 .It CTLFLAG\_READONLY Node is read-only
617 .It CTLFLAG\_READWRITE Node is writable by the superuser
618 .It CTLFLAG\_ANYWRITE Node is writable by anyone
619 .It CTLFLAG\_PRIVATE Node is readable only by the superuser
620 .It CTLFLAG\_PERMANENT Node cannot be removed (cannot be set by
621 processes)
622 .It CTLFLAG\_OWNDATA Node owns data and does not instrument
623 existing data
624 .It CTLFLAG\_IMMEDIATE Node contains instrumented data and does not
625 instrument existing data
626 .It CTLFLAG\_HEX Node's contents should be displayed in a hexadecimal
627 form
628 .It CTLFLAG\_ROOT Node is the root of a tree (cannot be set at
629 any time)
630 .It CTLFLAG\_ANYNUMBER Node matches any MIB number (cannot be set by
631 processes)
632 .It CTLFLAG\_HIDDEN Node not displayed by default
633 .It CTLFLAG\_ALIAS Node refers to a sibling node (cannot be set
634 by processes)
635 .It CTLFLAG\_OWNDESC Node owns its own description string space
636 .El
637 .Sh RETURN VALUES
638 If the call to
639 .Nm
640 is successful, 0 is returned.
641 Otherwise \-1 is returned and
642 .Va errno
643 is set appropriately.
644 .Sh FILES
645 .Bl -tag -width \*[Lt]netinet6/udp6Xvar.h\*[Gt] -compact
646 .It Aq Pa sys/sysctl.h
647 definitions for top level identifiers, second level kernel and hardware
648 identifiers, and user level identifiers
649 .It Aq Pa sys/socket.h
650 definitions for second level network identifiers
651 .It Aq Pa sys/gmon.h
652 definitions for third level profiling identifiers
653 .It Aq Pa uvm/uvm_param.h
654 definitions for second level virtual memory identifiers
655 .It Aq Pa netinet/in.h
656 definitions for third level IPv4/v6 identifiers and
657 fourth level IPv4/v6 identifiers
658 .It Aq Pa netinet/icmp_var.h
659 definitions for fourth level ICMP identifiers
660 .It Aq Pa netinet/icmp6.h
661 definitions for fourth level ICMPv6 identifiers
662 .It Aq Pa netinet/tcp_var.h
663 definitions for fourth level TCP identifiers
664 .It Aq Pa netinet/udp_var.h
665 definitions for fourth level UDP identifiers
666 .It Aq Pa netinet6/udp6_var.h
667 definitions for fourth level IPv6 UDP identifiers
668 .It Aq Pa netinet6/ipsec.h
669 definitions for fourth level IPsec identifiers
670 .It Aq Pa netkey/key_var.h
671 definitions for third level PF_KEY identifiers
672 .It Aq Pa machine/cpu.h
673 definitions for second level machdep identifiers
674 .El
675 .Sh ERRORS
676 The following errors may be reported:
677 .Bl -tag -width Er
678 .It Bq Er EFAULT
679 The buffer
680 .Fa name ,
681 .Fa oldp ,
682 .Fa newp ,
683 or length pointer
684 .Fa oldlenp
685 contains an invalid address, or the requested value is temporarily
686 unavailable.
687 .It Bq Er EINVAL
688 The
689 .Fa name
690 array is zero or greater than
691 .Dv CTL_MAXNAME ;
692 or a non-null
693 .Fa newp
694 is given and its specified length in
695 .Fa newlen
696 is too large or too small, or the given value is not acceptable for
697 the given node.
698 .It Bq Er EISDIR
699 The
700 .Fa name
701 array specifies an intermediate rather than terminal name.
702 .It Bq Er ENOENT
703 The
704 .Fa name
705 array specifies a node that does not exist in the tree;
706 or an attempt was made to destroy a node that does not exist, or to
707 create or destroy a node below a node that does not exist.
708 .It Bq Er ENOMEM
709 The length pointed to by
710 .Fa oldlenp
711 is too short to hold the requested value.
712 .It Bq Er ENOTDIR
713 The
714 .Fa name
715 array specifies a node below a node that addresses data.
716 .It Bq Er ENOTEMPTY
717 An attempt was made to destroy a node that still has children.
718 .It Bq Er EOPNOTSUPP
719 The
720 .Fa name
721 array specifies a value that is unknown or a meta-operation was
722 attempted that the requested node does not support.
723 .It Bq Er EPERM
724 An attempt is made to set a read-only value; or
725 a process without appropriate privilege attempts to set a value or to
726 create or destroy a node; or
727 an attempt to change a value protected by the current kernel security
728 level is made.
729 .El
730 .Sh SEE ALSO
731 .Xr sysctl 7 ,
732 .Xr sysctl 8 ,
733 .Xr secmodel_securelevel 9
734 .\" .Xr sysctl 9
735 .Sh HISTORY
736 The
737 .Nm
738 function first appeared in
739 .Bx 4.4 .