xref: /freebsd/lib/libc/gen/sysctl.3 (revision ce834215a70ff69e7e222827437116eee2f9ac6f)
1.\" Copyright (c) 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"	@(#)sysctl.3	8.4 (Berkeley) 5/9/95
33.\"
34.Dd May 9, 1995
35.Dt SYSCTL 3
36.Os
37.Sh NAME
38.Nm sysctl ,
39.Nm sysctlbyname
40.Nd get or set system information
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Fd #include <sys/sysctl.h>
44.Ft int
45.Fn sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen"
46.Fn sysctlbyname "const char *name" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen"
47.Sh DESCRIPTION
48The
49.Fn sysctl
50function retrieves system information and allows processes with
51appropriate privileges to set system information.
52The information available from
53.Fn sysctl
54consists of integers, strings, and tables.
55Information may be retrieved and set from the command interface
56using the
57.Xr sysctl 8
58utility.
59.Pp
60Unless explicitly noted below,
61.Fn sysctl
62returns a consistent snapshot of the data requested.
63Consistency is obtained by locking the destination
64buffer into memory so that the data may be copied out without blocking.
65Calls to
66.Fn sysctl
67are serialized to avoid deadlock.
68.Pp
69The state is described using a ``Management Information Base'' (MIB)
70style name, listed in
71.Fa name ,
72which is a
73.Fa namelen
74length array of integers.
75.Pp
76The
77.Fn sysctlbyname
78function accepts an ascii representation of the name and internally
79looks up the integer name vector.  Apart from that, it behaves the same
80as the standard
81.Fn sysctl
82function.
83.Pp
84The information is copied into the buffer specified by
85.Fa oldp .
86The size of the buffer is given by the location specified by
87.Fa oldlenp
88before the call,
89and that location gives the amount of data copied after a successful call
90and after a call that returns with the error code ENOMEM.
91If the amount of data available is greater
92than the size of the buffer supplied,
93the call supplies as much data as fits in the buffer provided
94and returns with the error code ENOMEM.
95If the old value is not desired,
96.Fa oldp
97and
98.Fa oldlenp
99should be set to NULL.
100.Pp
101The size of the available data can be determined by calling
102.Fn sysctl
103with a NULL parameter for
104.Fa oldp .
105The size of the available data will be returned in the location pointed to by
106.Fa oldlenp .
107For some operations, the amount of space may change often.
108For these operations,
109the system attempts to round up so that the returned size is
110large enough for a call to return the data shortly thereafter.
111.Pp
112To set a new value,
113.Fa newp
114is set to point to a buffer of length
115.Fa newlen
116from which the requested value is to be taken.
117If a new value is not to be set,
118.Fa newp
119should be set to NULL and
120.Fa newlen
121set to 0.
122.Pp
123The top level names are defined with a CTL_ prefix in
124.Pa <sys/sysctl.h> ,
125and are as follows.
126The next and subsequent levels down are found in the include files
127listed here, and described in separate sections below.
128.Pp
129.Bl -column CTLXMACHDEPXXX "Next level namesXXXXXX" -offset indent
130.It Sy Pa Name	Next level names	Description
131.It CTL\_DEBUG	sys/sysctl.h	Debugging
132.It CTL\_VFS	sys/mount.h	Filesystem
133.It CTL\_HW	sys/sysctl.h	Generic CPU, I/O
134.It CTL\_KERN	sys/sysctl.h	High kernel limits
135.It CTL\_MACHDEP	sys/sysctl.h	Machine dependent
136.It CTL\_NET	sys/socket.h	Networking
137.It CTL\_USER	sys/sysctl.h	User-level
138.It CTL\_VM	vm/vm_param.h	Virtual memory
139.El
140.Pp
141For example, the following retrieves the maximum number of processes allowed
142in the system:
143.Pp
144.Bd -literal -offset indent -compact
145int mib[2], maxproc;
146size_t len;
147
148mib[0] = CTL_KERN;
149mib[1] = KERN_MAXPROC;
150len = sizeof(maxproc);
151sysctl(mib, 2, &maxproc, &len, NULL, 0);
152.Ed
153.Pp
154To retrieve the standard search path for the system utilities:
155.Pp
156.Bd -literal -offset indent -compact
157int mib[2];
158size_t len;
159char *p;
160
161mib[0] = CTL_USER;
162mib[1] = USER_CS_PATH;
163sysctl(mib, 2, NULL, &len, NULL, 0);
164p = malloc(len);
165sysctl(mib, 2, p, &len, NULL, 0);
166.Ed
167.Sh CTL_DEBUG
168The debugging variables vary from system to system.
169A debugging variable may be added or deleted without need to recompile
170.Fn sysctl
171to know about it.
172Each time it runs,
173.Fn sysctl
174gets the list of debugging variables from the kernel and
175displays their current values.
176The system defines twenty
177.Ns ( Va struct ctldebug )
178variables named
179.Nm debug0
180through
181.Nm debug19 .
182They are declared as separate variables so that they can be
183individually initialized at the location of their associated variable.
184The loader prevents multiple use of the same variable by issuing errors
185if a variable is initialized in more than one place.
186For example, to export the variable
187.Nm dospecialcheck
188as a debugging variable, the following declaration would be used:
189.Bd -literal -offset indent -compact
190int dospecialcheck = 1;
191struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck };
192.Ed
193.Sh CTL_VFS
194A distinguished second level name, VFS_GENERIC,
195is used to get general information about all filesystems.
196One of its third level identifiers is VFS_MAXTYPENUM
197that gives the highest valid filesystem type number.
198Its other third level identifier is VFS_CONF that
199returns configuration information about the filesystem
200type given as a fourth level identifier (see
201.Xr getvfsbyname 3
202as an example of its use).
203The remaining second level identifiers are the
204filesystem type number returned by a
205.Xr statfs 2
206call or from VFS_CONF.
207The third level identifiers available for each filesystem
208are given in the header file that defines the mount
209argument structure for that filesystem.
210.Sh CTL_HW
211The string and integer information available for the CTL_HW level
212is detailed below.
213The changeable column shows whether a process with appropriate
214privilege may change the value.
215.Bl -column "Second level nameXXXXXX" integerXXX -offset indent
216.It Sy Pa Second level name	Type	Changeable
217.It HW\_MACHINE	string	no
218.It HW\_MODEL	string	no
219.It HW\_NCPU	integer	no
220.It HW\_BYTEORDER	integer	no
221.It HW\_PHYSMEM	integer	no
222.It HW\_USERMEM	integer	no
223.It HW\_PAGESIZE	integer	no
224.It HW\_FLOATINGPOINT	integer	no
225.\".It HW\_DISKNAMES	integer	no
226.\".It HW\_DISKSTATS	integer	no
227.El
228.Pp
229.Bl -tag -width "123456"
230.It Li HW_MACHINE
231The machine class.
232.It Li HW_MODEL
233The machine model
234.It Li HW_NCPU
235The number of cpus.
236.ne 1i
237.It Li HW_BYTEORDER
238The byteorder (4,321, or 1,234).
239.It Li HW_PHYSMEM
240The bytes of physical memory.
241.It Li HW_USERMEM
242The bytes of non-kernel memory.
243.It Li HW_PAGESIZE
244The software page size.
245.It Li HW_FLOATINGPOINT
246Nonzero if the floating point support is in hardware.
247.\".It Fa HW_DISKNAMES
248.\".It Fa HW_DISKSTATS
249.El
250.Sh CTL_KERN
251The string and integer information available for the CTL_KERN level
252is detailed below.
253The changeable column shows whether a process with appropriate
254privilege may change the value.
255The types of data currently available are process information,
256system vnodes, the open file entries, routing table entries,
257virtual memory statistics, load average history, and clock rate
258information.
259.Bl -column "KERNXMAXFILESPERPROCXXX" "struct clockrateXXX" -offset indent
260.It Sy Pa Second level name	Type	Changeable
261.It KERN\_ARGMAX	integer	no
262.It KERN\_BOOTFILE	string	yes
263.It KERN\_BOOTTIME	struct timeval	no
264.It KERN\_CLOCKRATE	struct clockinfo	no
265.It KERN\_FILE	struct file	no
266.It KERN\_HOSTID	integer	yes
267.It KERN\_HOSTNAME	string	yes
268.It KERN\_JOB\_CONTROL	integer	no
269.It KERN\_MAXFILES	integer	yes
270.It KERN\_MAXFILESPERPROC	integer	yes
271.It KERN\_MAXPROC	integer	yes
272.It KERN\_MAXPROCPERUID	integer	yes
273.It KERN\_MAXVNODES	integer	yes
274.It KERN\_NGROUPS	integer	no
275.It KERN\_NISDOMAINNAME	string	yes
276.It KERN\_OSRELDATE	integer	no
277.It KERN\_OSRELEASE	string	no
278.It KERN\_OSREV	integer	no
279.It KERN\_OSTYPE	string	no
280.It KERN\_POSIX1	integer	no
281.It KERN\_PROC	struct proc	no
282.It KERN\_PROF	node	not applicable
283.It KERN\_SAVED\_IDS	integer	no
284.It KERN\_SECURELVL	integer	raise only
285.It KERN\_UPDATEINTERVAL	integer	no
286.It KERN\_VERSION	string	no
287.It KERN\_VNODE	struct vnode	no
288.El
289.ne 1i
290.Pp
291.Bl -tag -width "123456"
292.It Li KERN_ARGMAX
293The maximum bytes of argument to
294.Xr execve 2 .
295.It Li KERN_BOOTFILE
296The full pathname of the file from which the kernel was loaded.
297.It Li KERN_BOOTTIME
298A
299.Va struct timeval
300structure is returned.
301This structure contains the time that the system was booted.
302.It Li KERN_CLOCKRATE
303A
304.Va struct clockinfo
305structure is returned.
306This structure contains the clock, statistics clock and profiling clock
307frequencies, the number of micro-seconds per hz tick and the skew rate.
308.It Li KERN_FILE
309Return the entire file table.
310The returned data consists of a single
311.Va struct filehead
312followed by an array of
313.Va struct file ,
314whose size depends on the current number of such objects in the system.
315.It Li KERN_HOSTID
316Get or set the host id.
317.It Li KERN_HOSTNAME
318Get or set the hostname.
319.It Li KERN_JOB_CONTROL
320Return 1 if job control is available on this system, otherwise 0.
321.It Li KERN_MAXFILES
322The maximum number of files that may be open in the system.
323.It Li KERN_MAXFILESPERPROC
324The maximum number of files that may be open for a single process.
325This limit only applies to processes with an effective uid of nonzero
326at the time of the open request.
327Files that have already been opened are not affected if the limit
328or the effective uid is changed.
329.It Li KERN_MAXPROC
330The maximum number of concurrent processes the system will allow.
331.It Li KERN_MAXPROCPERUID
332The maximum number of concurrent processes the system will allow
333for a single effective uid.
334This limit only applies to processes with an effective uid of nonzero
335at the time of a fork request.
336Processes that have already been started are not affected if the limit
337is changed.
338.It Li KERN_MAXVNODES
339The maximum number of vnodes available on the system.
340.It Li KERN_NGROUPS
341The maximum number of supplemental groups.
342.It Li KERN_NISDOMAINNAME
343The name of the current YP/NIS domain.
344.It Li KERN_OSRELDATE
345The system release date in YYYYMM format
346(January 1996 is encoded as 199601).
347.It Li KERN_OSRELEASE
348The system release string.
349.It Li KERN_OSREV
350The system revision string.
351.It Li KERN_OSTYPE
352The system type string.
353.It Li KERN_POSIX1
354The version of ISO/IEC 9945 (POSIX 1003.1) with which the system
355attempts to comply.
356.It Li KERN_PROC
357Return the entire process table, or a subset of it.
358An array of
359.Va struct kinfo_proc
360structures is returned,
361whose size depends on the current number of such objects in the system.
362The third and fourth level names are as follows:
363.Bl -column "Third level nameXXXXXX" "Fourth level is:XXXXXX" -offset indent
364.It Pa Third level name	Fourth level is:
365.It KERN\_PROC\_ALL	None
366.It KERN\_PROC\_PID	A process ID
367.It KERN\_PROC\_PGRP	A process group
368.It KERN\_PROC\_TTY	A tty device
369.It KERN\_PROC\_UID	A user ID
370.It KERN\_PROC\_RUID	A real user ID
371.El
372.It Li KERN_PROF
373Return profiling information about the kernel.
374If the kernel is not compiled for profiling,
375attempts to retrieve any of the KERN_PROF values will
376fail with EOPNOTSUPP.
377The third level names for the string and integer profiling information
378is detailed below.
379The changeable column shows whether a process with appropriate
380privilege may change the value.
381.Bl -column "GPROFXGMONPARAMXXX" "struct gmonparamXXX" -offset indent
382.It Sy Pa Third level name	Type	Changeable
383.It GPROF\_STATE	integer	yes
384.It GPROF\_COUNT	u_short[\|]	yes
385.It GPROF\_FROMS	u_short[\|]	yes
386.It GPROF\_TOS	struct tostruct	yes
387.It GPROF\_GMONPARAM	struct gmonparam	no
388.El
389.Pp
390The variables are as follows:
391.Bl -tag -width "123456"
392.It Li GPROF_STATE
393Returns GMON_PROF_ON or GMON_PROF_OFF to show that profiling
394is running or stopped.
395.It Li GPROF_COUNT
396Array of statistical program counter counts.
397.It Li GPROF_FROMS
398Array indexed by program counter of call-from points.
399.It Li GPROF_TOS
400Array of
401.Va struct tostruct
402describing destination of calls and their counts.
403.It Li GPROF_GMONPARAM
404Structure giving the sizes of the above arrays.
405.El
406.ne 1i
407.It Li KERN_SAVED_IDS
408Returns 1 if saved set-group and saved set-user ID is available.
409.It Li KERN_SECURELVL
410The system security level.
411This level may be raised by processes with appropriate privilege.
412It may only be lowered by process 1.
413.It Li KERN_VERSION
414The system version string.
415.It Li KERN_VNODE
416Return the entire vnode table.
417Note, the vnode table is not necessarily a consistent snapshot of
418the system.
419The returned data consists of an array whose size depends on the
420current number of such objects in the system.
421Each element of the array contains the kernel address of a vnode
422.Va struct vnode *
423followed by the vnode itself
424.Va struct vnode .
425.It Li KERN_UPDATEINTERVAL
426The interval between
427.Xr sync 2
428calls in the
429.Xr update 4
430process.
431.El
432.Sh CTL_MACHDEP
433The set of variables defined is architecture dependent.
434The following variables are defined for the i386 architecture.
435.Bl -column "CONSOLE_DEVICEXXX" "struct bootinfoXXX" -offset indent
436.It Sy Pa Second level name	Type	Changeable
437.It Li CPU_CONSDEV	dev_t	no
438.It Li CPU_ADJKERNTZ	int	yes
439.It Li CPU_DISRTCSET	int	yes
440.It Li CPU_BOOTINFO	struct bootinfo	no
441.It Li CPU_WALLCLOCK	int	yes
442.El
443.Sh CTL_NET
444The string and integer information available for the CTL_NET level
445is detailed below.
446The changeable column shows whether a process with appropriate
447privilege may change the value.
448.Bl -column "Second level nameXXXXXX" "routing messagesXXX" -offset indent
449.It Sy Pa Second level name	Type	Changeable
450.It PF\_ROUTE	routing messages	no
451.It PF\_INET	internet values	yes
452.El
453.Pp
454.Bl -tag -width "123456"
455.It Li PF_ROUTE
456Return the entire routing table or a subset of it.
457The data is returned as a sequence of routing messages (see
458.Xr route 4
459for the header file, format and meaning).
460The length of each message is contained in the message header.
461.Pp
462The third level name is a protocol number, which is currently always 0.
463The fourth level name is an address family, which may be set to 0 to
464select all address families.
465The fifth and sixth level names are as follows:
466.Bl -column "Fifth level nameXXXXXX" "Sixth level is:XXX" -offset indent
467.It Pa Fifth level name	Sixth level is:
468.It NET\_RT\_FLAGS	rtflags
469.It NET\_RT\_DUMP	None
470.It NET\_RT\_IFLIST	None
471.El
472.It Li PF_INET
473Get or set various global information about the internet protocols.
474The third level name is the protocol.
475The fourth level name is the variable name.
476The currently defined protocols and names are:
477.ne 1i
478.Bl -column "Protocol nameXXXXXX" "Variable nameXXX" "integerXXX" -offset indent
479.It Pa Protocol name	Variable name	Type	Changeable
480.It ip	forwarding	integer	yes
481.It ip	redirect	integer	yes
482.It ip	ttl	integer	yes
483.It icmp	maskrepl	integer	yes
484.It udp	checksum	integer	yes
485.El
486.Pp
487The variables are as follows:
488.Bl -tag -width "123456"
489.It Li ip.forwarding
490Returns 1 when IP forwarding is enabled for the host,
491meaning that the host is acting as a router.
492.It Li ip.redirect
493Returns 1 when ICMP redirects may be sent by the host.
494This option is ignored unless the host is routing IP packets,
495and should normally be enabled on all systems.
496.It Li ip.ttl
497The maximum time-to-live (hop count) value for an IP packet sourced by
498the system.
499This value applies to normal transport protocols, not to ICMP.
500.It Li icmp.maskrepl
501Returns 1 if ICMP network mask requests are to be answered.
502.It Li udp.checksum
503Returns 1 when UDP checksums are being computed and checked.
504Disabling UDP checksums is strongly discouraged.
505.El
506.Sh CTL_USER
507The string and integer information available for the CTL_USER level
508is detailed below.
509The changeable column shows whether a process with appropriate
510privilege may change the value.
511.Bl -column "USER_COLL_WEIGHTS_MAXXXX" "integerXXX" -offset indent
512.It Sy Pa Second level name	Type	Changeable
513.It USER\_BC\_BASE\_MAX	integer	no
514.It USER\_BC\_DIM\_MAX	integer	no
515.It USER\_BC\_SCALE\_MAX	integer	no
516.It USER\_BC\_STRING\_MAX	integer	no
517.It USER\_COLL\_WEIGHTS\_MAX	integer	no
518.It USER\_CS\_PATH	string	no
519.It USER\_EXPR\_NEST\_MAX	integer	no
520.It USER\_LINE\_MAX	integer	no
521.It USER\_POSIX2\_CHAR\_TERM	integer	no
522.It USER\_POSIX2\_C\_BIND	integer	no
523.It USER\_POSIX2\_C\_DEV	integer	no
524.It USER\_POSIX2\_FORT\_DEV	integer	no
525.It USER\_POSIX2\_FORT\_RUN	integer	no
526.It USER\_POSIX2\_LOCALEDEF	integer	no
527.It USER\_POSIX2\_SW\_DEV	integer	no
528.It USER\_POSIX2\_UPE	integer	no
529.It USER\_POSIX2\_VERSION	integer	no
530.It USER\_RE\_DUP\_MAX	integer	no
531.It USER\_STREAM\_MAX	integer	no
532.It USER\_TZNAME\_MAX	integer	no
533.El
534.Bl -tag -width "123456"
535.Pp
536.It Li USER_BC_BASE_MAX
537The maximum ibase/obase values in the
538.Xr bc 1
539utility.
540.It Li USER_BC_DIM_MAX
541The maximum array size in the
542.Xr bc 1
543utility.
544.It Li USER_BC_SCALE_MAX
545The maximum scale value in the
546.Xr bc 1
547utility.
548.It Li USER_BC_STRING_MAX
549The maximum string length in the
550.Xr bc 1
551utility.
552.It Li USER_COLL_WEIGHTS_MAX
553The maximum number of weights that can be assigned to any entry of
554the LC_COLLATE order keyword in the locale definition file.
555.It Li USER_CS_PATH
556Return a value for the
557.Ev PATH
558environment variable that finds all the standard utilities.
559.It Li USER_EXPR_NEST_MAX
560The maximum number of expressions that can be nested within
561parenthesis by the
562.Xr expr 1
563utility.
564.It Li USER_LINE_MAX
565The maximum length in bytes of a text-processing utility's input
566line.
567.It Li USER_POSIX2_CHAR_TERM
568Return 1 if the system supports at least one terminal type capable of
569all operations described in POSIX 1003.2, otherwise 0.
570.It Li USER_POSIX2_C_BIND
571Return 1 if the system's C-language development facilities support the
572C-Language Bindings Option, otherwise 0.
573.It Li USER_POSIX2_C_DEV
574Return 1 if the system supports the C-Language Development Utilities Option,
575otherwise 0.
576.It Li USER_POSIX2_FORT_DEV
577Return 1 if the system supports the FORTRAN Development Utilities Option,
578otherwise 0.
579.It Li USER_POSIX2_FORT_RUN
580Return 1 if the system supports the FORTRAN Runtime Utilities Option,
581otherwise 0.
582.It Li USER_POSIX2_LOCALEDEF
583Return 1 if the system supports the creation of locales, otherwise 0.
584.It Li USER_POSIX2_SW_DEV
585Return 1 if the system supports the Software Development Utilities Option,
586otherwise 0.
587.It Li USER_POSIX2_UPE
588Return 1 if the system supports the User Portability Utilities Option,
589otherwise 0.
590.It Li USER_POSIX2_VERSION
591The version of POSIX 1003.2 with which the system attempts to comply.
592.It Li USER_RE_DUP_MAX
593The maximum number of repeated occurrences of a regular expression
594permitted when using interval notation.
595.ne 1i
596.It Li USER_STREAM_MAX
597The minimum maximum number of streams that a process may have open
598at any one time.
599.It Li USER_TZNAME_MAX
600The minimum maximum number of types supported for the name of a
601timezone.
602.El
603.Sh CTL_VM
604The string and integer information available for the CTL_VM level
605is detailed below.
606The changeable column shows whether a process with appropriate
607privilege may change the value.
608.Bl -column "Second level nameXXXXXX" "struct loadavgXXX" -offset indent
609.It Sy Pa Second level name	Type	Changeable
610.It VM\_LOADAVG	struct loadavg	no
611.It VM\_METER	struct vmtotal	no
612.El
613.Pp
614.Bl -tag -width "123456"
615.It Li VM_LOADAVG
616Return the load average history.
617The returned data consists of a
618.Va struct loadavg .
619.It Li VM_METER
620Return the system wide virtual memory statistics.
621The returned data consists of a
622.Va struct vmtotal .
623.El
624.Sh RETURN VALUES
625If the call to
626.Fn sysctl
627is successful, the number of bytes copied out is returned.
628Otherwise \-1 is returned and
629.Va errno
630is set appropriately.
631.Sh ERRORS
632The following errors may be reported:
633.Bl -tag -width Er
634.It Bq Er EFAULT
635The buffer
636.Fa name ,
637.Fa oldp ,
638.Fa newp ,
639or length pointer
640.Fa oldlenp
641contains an invalid address.
642.It Bq Er EINVAL
643The
644.Fa name
645array is less than two or greater than CTL_MAXNAME.
646.It Bq Er EINVAL
647A non-null
648.Fa newp
649is given and its specified length in
650.Fa newlen
651is too large or too small.
652.It Bq Er ENOMEM
653The length pointed to by
654.Fa oldlenp
655is too short to hold the requested value.
656.It Bq Er ENOTDIR
657The
658.Fa name
659array specifies an intermediate rather than terminal name.
660.It Bq Er EOPNOTSUPP
661The
662.Fa name
663array specifies a value that is unknown.
664.It Bq Er EPERM
665An attempt is made to set a read-only value.
666.It Bq Er EPERM
667A process without appropriate privilege attempts to set a value.
668.El
669.Sh FILES
670.Bl -tag -width <netinet/icmpXvar.h> -compact
671.It Pa <sys/sysctl.h>
672definitions for top level identifiers, second level kernel and hardware
673identifiers, and user level identifiers
674.It Pa <sys/socket.h>
675definitions for second level network identifiers
676.It Pa <sys/gmon.h>
677definitions for third level profiling identifiers
678.It Pa <vm/vm_param.h>
679definitions for second level virtual memory identifiers
680.It Pa <netinet/in.h>
681definitions for third level Internet identifiers and
682fourth level IP identifiers
683.It Pa <netinet/icmp_var.h>
684definitions for fourth level ICMP identifiers
685.It Pa <netinet/udp_var.h>
686definitions for fourth level UDP identifiers
687.El
688.Sh SEE ALSO
689.Xr sysctl 8
690.Sh HISTORY
691The
692.Fn sysctl
693function first appeared in
694.Bx 4.4 .
695