xref: /freebsd/lib/libc/gen/sysctl.3 (revision 0de89efe5c443f213c7ea28773ef2dc6cf3af2ed)
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\_MACHINE\_ARCH	string	no
226.\".It HW\_DISKNAMES	integer	no
227.\".It HW\_DISKSTATS	integer	no
228.El
229.Pp
230.Bl -tag -width "123456"
231.It Li HW_MACHINE
232The machine class.
233.It Li HW_MODEL
234The machine model
235.It Li HW_NCPU
236The number of cpus.
237.ne 1i
238.It Li HW_BYTEORDER
239The byteorder (4,321, or 1,234).
240.It Li HW_PHYSMEM
241The bytes of physical memory.
242.It Li HW_USERMEM
243The bytes of non-kernel memory.
244.It Li HW_PAGESIZE
245The software page size.
246.It Li HW_FLOATINGPOINT
247Nonzero if the floating point support is in hardware.
248.It Li HW_MACHINE_ARCH
249The machine dependent architecture type.
250.\".It Fa HW_DISKNAMES
251.\".It Fa HW_DISKSTATS
252.El
253.Sh CTL_KERN
254The string and integer information available for the CTL_KERN level
255is detailed below.
256The changeable column shows whether a process with appropriate
257privilege may change the value.
258The types of data currently available are process information,
259system vnodes, the open file entries, routing table entries,
260virtual memory statistics, load average history, and clock rate
261information.
262.Bl -column "KERNXMAXFILESPERPROCXXX" "struct clockrateXXX" -offset indent
263.It Sy Pa Second level name	Type	Changeable
264.It KERN\_ARGMAX	integer	no
265.It KERN\_BOOTFILE	string	yes
266.It KERN\_BOOTTIME	struct timeval	no
267.It KERN\_CLOCKRATE	struct clockinfo	no
268.It KERN\_FILE	struct file	no
269.It KERN\_HOSTID	integer	yes
270.It KERN\_HOSTNAME	string	yes
271.It KERN\_JOB\_CONTROL	integer	no
272.It KERN\_MAXFILES	integer	yes
273.It KERN\_MAXFILESPERPROC	integer	yes
274.It KERN\_MAXPROC	integer	yes
275.It KERN\_MAXPROCPERUID	integer	yes
276.It KERN\_MAXVNODES	integer	yes
277.It KERN\_NGROUPS	integer	no
278.It KERN\_NISDOMAINNAME	string	yes
279.It KERN\_OSRELDATE	integer	no
280.It KERN\_OSRELEASE	string	no
281.It KERN\_OSREV	integer	no
282.It KERN\_OSTYPE	string	no
283.It KERN\_POSIX1	integer	no
284.It KERN\_PROC	struct proc	no
285.It KERN\_PROF	node	not applicable
286.It KERN\_SAVED\_IDS	integer	no
287.It KERN\_SECURELVL	integer	raise only
288.It KERN\_UPDATEINTERVAL	integer	no
289.It KERN\_VERSION	string	no
290.It KERN\_VNODE	struct vnode	no
291.El
292.ne 1i
293.Pp
294.Bl -tag -width "123456"
295.It Li KERN_ARGMAX
296The maximum bytes of argument to
297.Xr execve 2 .
298.It Li KERN_BOOTFILE
299The full pathname of the file from which the kernel was loaded.
300.It Li KERN_BOOTTIME
301A
302.Va struct timeval
303structure is returned.
304This structure contains the time that the system was booted.
305.It Li KERN_CLOCKRATE
306A
307.Va struct clockinfo
308structure is returned.
309This structure contains the clock, statistics clock and profiling clock
310frequencies, the number of micro-seconds per hz tick and the skew rate.
311.It Li KERN_FILE
312Return the entire file table.
313The returned data consists of a single
314.Va struct filehead
315followed by an array of
316.Va struct file ,
317whose size depends on the current number of such objects in the system.
318.It Li KERN_HOSTID
319Get or set the host id.
320.It Li KERN_HOSTNAME
321Get or set the hostname.
322.It Li KERN_JOB_CONTROL
323Return 1 if job control is available on this system, otherwise 0.
324.It Li KERN_MAXFILES
325The maximum number of files that may be open in the system.
326.It Li KERN_MAXFILESPERPROC
327The maximum number of files that may be open for a single process.
328This limit only applies to processes with an effective uid of nonzero
329at the time of the open request.
330Files that have already been opened are not affected if the limit
331or the effective uid is changed.
332.It Li KERN_MAXPROC
333The maximum number of concurrent processes the system will allow.
334.It Li KERN_MAXPROCPERUID
335The maximum number of concurrent processes the system will allow
336for a single effective uid.
337This limit only applies to processes with an effective uid of nonzero
338at the time of a fork request.
339Processes that have already been started are not affected if the limit
340is changed.
341.It Li KERN_MAXVNODES
342The maximum number of vnodes available on the system.
343.It Li KERN_NGROUPS
344The maximum number of supplemental groups.
345.It Li KERN_NISDOMAINNAME
346The name of the current YP/NIS domain.
347.It Li KERN_OSRELDATE
348The system release date in YYYYMM format
349(January 1996 is encoded as 199601).
350.It Li KERN_OSRELEASE
351The system release string.
352.It Li KERN_OSREV
353The system revision string.
354.It Li KERN_OSTYPE
355The system type string.
356.It Li KERN_POSIX1
357The version of ISO/IEC 9945 (POSIX 1003.1) with which the system
358attempts to comply.
359.It Li KERN_PROC
360Return the entire process table, or a subset of it.
361An array of
362.Va struct kinfo_proc
363structures is returned,
364whose size depends on the current number of such objects in the system.
365The third and fourth level names are as follows:
366.Bl -column "Third level nameXXXXXX" "Fourth level is:XXXXXX" -offset indent
367.It Pa Third level name	Fourth level is:
368.It KERN\_PROC\_ALL	None
369.It KERN\_PROC\_PID	A process ID
370.It KERN\_PROC\_PGRP	A process group
371.It KERN\_PROC\_TTY	A tty device
372.It KERN\_PROC\_UID	A user ID
373.It KERN\_PROC\_RUID	A real user ID
374.El
375.It Li KERN_PROF
376Return profiling information about the kernel.
377If the kernel is not compiled for profiling,
378attempts to retrieve any of the KERN_PROF values will
379fail with EOPNOTSUPP.
380The third level names for the string and integer profiling information
381is detailed below.
382The changeable column shows whether a process with appropriate
383privilege may change the value.
384.Bl -column "GPROFXGMONPARAMXXX" "struct gmonparamXXX" -offset indent
385.It Sy Pa Third level name	Type	Changeable
386.It GPROF\_STATE	integer	yes
387.It GPROF\_COUNT	u_short[\|]	yes
388.It GPROF\_FROMS	u_short[\|]	yes
389.It GPROF\_TOS	struct tostruct	yes
390.It GPROF\_GMONPARAM	struct gmonparam	no
391.El
392.Pp
393The variables are as follows:
394.Bl -tag -width "123456"
395.It Li GPROF_STATE
396Returns GMON_PROF_ON or GMON_PROF_OFF to show that profiling
397is running or stopped.
398.It Li GPROF_COUNT
399Array of statistical program counter counts.
400.It Li GPROF_FROMS
401Array indexed by program counter of call-from points.
402.It Li GPROF_TOS
403Array of
404.Va struct tostruct
405describing destination of calls and their counts.
406.It Li GPROF_GMONPARAM
407Structure giving the sizes of the above arrays.
408.El
409.ne 1i
410.It Li KERN_SAVED_IDS
411Returns 1 if saved set-group and saved set-user ID is available.
412.It Li KERN_SECURELVL
413The system security level.
414This level may be raised by processes with appropriate privilege.
415It may only be lowered by process 1.
416.It Li KERN_VERSION
417The system version string.
418.It Li KERN_VNODE
419Return the entire vnode table.
420Note, the vnode table is not necessarily a consistent snapshot of
421the system.
422The returned data consists of an array whose size depends on the
423current number of such objects in the system.
424Each element of the array contains the kernel address of a vnode
425.Va struct vnode *
426followed by the vnode itself
427.Va struct vnode .
428.It Li KERN_UPDATEINTERVAL
429The interval between
430.Xr sync 2
431calls in the
432.Xr update 4
433process.
434.El
435.Sh CTL_MACHDEP
436The set of variables defined is architecture dependent.
437The following variables are defined for the i386 architecture.
438.Bl -column "CONSOLE_DEVICEXXX" "struct bootinfoXXX" -offset indent
439.It Sy Pa Second level name	Type	Changeable
440.It Li CPU_CONSDEV	dev_t	no
441.It Li CPU_ADJKERNTZ	int	yes
442.It Li CPU_DISRTCSET	int	yes
443.It Li CPU_BOOTINFO	struct bootinfo	no
444.It Li CPU_WALLCLOCK	int	yes
445.El
446.Sh CTL_NET
447The string and integer information available for the CTL_NET level
448is detailed below.
449The changeable column shows whether a process with appropriate
450privilege may change the value.
451.Bl -column "Second level nameXXXXXX" "routing messagesXXX" -offset indent
452.It Sy Pa Second level name	Type	Changeable
453.It PF\_ROUTE	routing messages	no
454.It PF\_INET	internet values	yes
455.El
456.Pp
457.Bl -tag -width "123456"
458.It Li PF_ROUTE
459Return the entire routing table or a subset of it.
460The data is returned as a sequence of routing messages (see
461.Xr route 4
462for the header file, format and meaning).
463The length of each message is contained in the message header.
464.Pp
465The third level name is a protocol number, which is currently always 0.
466The fourth level name is an address family, which may be set to 0 to
467select all address families.
468The fifth and sixth level names are as follows:
469.Bl -column "Fifth level nameXXXXXX" "Sixth level is:XXX" -offset indent
470.It Pa Fifth level name	Sixth level is:
471.It NET\_RT\_FLAGS	rtflags
472.It NET\_RT\_DUMP	None
473.It NET\_RT\_IFLIST	None
474.El
475.It Li PF_INET
476Get or set various global information about the internet protocols.
477The third level name is the protocol.
478The fourth level name is the variable name.
479The currently defined protocols and names are:
480.ne 1i
481.Bl -column "Protocol nameXXXXXX" "Variable nameXXX" "integerXXX" -offset indent
482.It Pa Protocol name	Variable name	Type	Changeable
483.It ip	forwarding	integer	yes
484.It ip	redirect	integer	yes
485.It ip	ttl	integer	yes
486.It icmp	maskrepl	integer	yes
487.It udp	checksum	integer	yes
488.El
489.Pp
490The variables are as follows:
491.Bl -tag -width "123456"
492.It Li ip.forwarding
493Returns 1 when IP forwarding is enabled for the host,
494meaning that the host is acting as a router.
495.It Li ip.redirect
496Returns 1 when ICMP redirects may be sent by the host.
497This option is ignored unless the host is routing IP packets,
498and should normally be enabled on all systems.
499.It Li ip.ttl
500The maximum time-to-live (hop count) value for an IP packet sourced by
501the system.
502This value applies to normal transport protocols, not to ICMP.
503.It Li icmp.maskrepl
504Returns 1 if ICMP network mask requests are to be answered.
505.It Li udp.checksum
506Returns 1 when UDP checksums are being computed and checked.
507Disabling UDP checksums is strongly discouraged.
508.El
509.Sh CTL_USER
510The string and integer information available for the CTL_USER level
511is detailed below.
512The changeable column shows whether a process with appropriate
513privilege may change the value.
514.Bl -column "USER_COLL_WEIGHTS_MAXXXX" "integerXXX" -offset indent
515.It Sy Pa Second level name	Type	Changeable
516.It USER\_BC\_BASE\_MAX	integer	no
517.It USER\_BC\_DIM\_MAX	integer	no
518.It USER\_BC\_SCALE\_MAX	integer	no
519.It USER\_BC\_STRING\_MAX	integer	no
520.It USER\_COLL\_WEIGHTS\_MAX	integer	no
521.It USER\_CS\_PATH	string	no
522.It USER\_EXPR\_NEST\_MAX	integer	no
523.It USER\_LINE\_MAX	integer	no
524.It USER\_POSIX2\_CHAR\_TERM	integer	no
525.It USER\_POSIX2\_C\_BIND	integer	no
526.It USER\_POSIX2\_C\_DEV	integer	no
527.It USER\_POSIX2\_FORT\_DEV	integer	no
528.It USER\_POSIX2\_FORT\_RUN	integer	no
529.It USER\_POSIX2\_LOCALEDEF	integer	no
530.It USER\_POSIX2\_SW\_DEV	integer	no
531.It USER\_POSIX2\_UPE	integer	no
532.It USER\_POSIX2\_VERSION	integer	no
533.It USER\_RE\_DUP\_MAX	integer	no
534.It USER\_STREAM\_MAX	integer	no
535.It USER\_TZNAME\_MAX	integer	no
536.El
537.Bl -tag -width "123456"
538.Pp
539.It Li USER_BC_BASE_MAX
540The maximum ibase/obase values in the
541.Xr bc 1
542utility.
543.It Li USER_BC_DIM_MAX
544The maximum array size in the
545.Xr bc 1
546utility.
547.It Li USER_BC_SCALE_MAX
548The maximum scale value in the
549.Xr bc 1
550utility.
551.It Li USER_BC_STRING_MAX
552The maximum string length in the
553.Xr bc 1
554utility.
555.It Li USER_COLL_WEIGHTS_MAX
556The maximum number of weights that can be assigned to any entry of
557the LC_COLLATE order keyword in the locale definition file.
558.It Li USER_CS_PATH
559Return a value for the
560.Ev PATH
561environment variable that finds all the standard utilities.
562.It Li USER_EXPR_NEST_MAX
563The maximum number of expressions that can be nested within
564parenthesis by the
565.Xr expr 1
566utility.
567.It Li USER_LINE_MAX
568The maximum length in bytes of a text-processing utility's input
569line.
570.It Li USER_POSIX2_CHAR_TERM
571Return 1 if the system supports at least one terminal type capable of
572all operations described in POSIX 1003.2, otherwise 0.
573.It Li USER_POSIX2_C_BIND
574Return 1 if the system's C-language development facilities support the
575C-Language Bindings Option, otherwise 0.
576.It Li USER_POSIX2_C_DEV
577Return 1 if the system supports the C-Language Development Utilities Option,
578otherwise 0.
579.It Li USER_POSIX2_FORT_DEV
580Return 1 if the system supports the FORTRAN Development Utilities Option,
581otherwise 0.
582.It Li USER_POSIX2_FORT_RUN
583Return 1 if the system supports the FORTRAN Runtime Utilities Option,
584otherwise 0.
585.It Li USER_POSIX2_LOCALEDEF
586Return 1 if the system supports the creation of locales, otherwise 0.
587.It Li USER_POSIX2_SW_DEV
588Return 1 if the system supports the Software Development Utilities Option,
589otherwise 0.
590.It Li USER_POSIX2_UPE
591Return 1 if the system supports the User Portability Utilities Option,
592otherwise 0.
593.It Li USER_POSIX2_VERSION
594The version of POSIX 1003.2 with which the system attempts to comply.
595.It Li USER_RE_DUP_MAX
596The maximum number of repeated occurrences of a regular expression
597permitted when using interval notation.
598.ne 1i
599.It Li USER_STREAM_MAX
600The minimum maximum number of streams that a process may have open
601at any one time.
602.It Li USER_TZNAME_MAX
603The minimum maximum number of types supported for the name of a
604timezone.
605.El
606.Sh CTL_VM
607The string and integer information available for the CTL_VM level
608is detailed below.
609The changeable column shows whether a process with appropriate
610privilege may change the value.
611.Bl -column "Second level nameXXXXXX" "struct loadavgXXX" -offset indent
612.It Sy Pa Second level name	Type	Changeable
613.It VM\_LOADAVG	struct loadavg	no
614.It VM\_METER	struct vmtotal	no
615.El
616.Pp
617.Bl -tag -width "123456"
618.It Li VM_LOADAVG
619Return the load average history.
620The returned data consists of a
621.Va struct loadavg .
622.It Li VM_METER
623Return the system wide virtual memory statistics.
624The returned data consists of a
625.Va struct vmtotal .
626.El
627.Sh RETURN VALUES
628If the call to
629.Fn sysctl
630is successful, the number of bytes copied out is returned.
631Otherwise \-1 is returned and
632.Va errno
633is set appropriately.
634.Sh ERRORS
635The following errors may be reported:
636.Bl -tag -width Er
637.It Bq Er EFAULT
638The buffer
639.Fa name ,
640.Fa oldp ,
641.Fa newp ,
642or length pointer
643.Fa oldlenp
644contains an invalid address.
645.It Bq Er EINVAL
646The
647.Fa name
648array is less than two or greater than CTL_MAXNAME.
649.It Bq Er EINVAL
650A non-null
651.Fa newp
652is given and its specified length in
653.Fa newlen
654is too large or too small.
655.It Bq Er ENOMEM
656The length pointed to by
657.Fa oldlenp
658is too short to hold the requested value.
659.It Bq Er ENOTDIR
660The
661.Fa name
662array specifies an intermediate rather than terminal name.
663.It Bq Er EOPNOTSUPP
664The
665.Fa name
666array specifies a value that is unknown.
667.It Bq Er EPERM
668An attempt is made to set a read-only value.
669.It Bq Er EPERM
670A process without appropriate privilege attempts to set a value.
671.El
672.Sh FILES
673.Bl -tag -width <netinet/icmpXvar.h> -compact
674.It Pa <sys/sysctl.h>
675definitions for top level identifiers, second level kernel and hardware
676identifiers, and user level identifiers
677.It Pa <sys/socket.h>
678definitions for second level network identifiers
679.It Pa <sys/gmon.h>
680definitions for third level profiling identifiers
681.It Pa <vm/vm_param.h>
682definitions for second level virtual memory identifiers
683.It Pa <netinet/in.h>
684definitions for third level Internet identifiers and
685fourth level IP identifiers
686.It Pa <netinet/icmp_var.h>
687definitions for fourth level ICMP identifiers
688.It Pa <netinet/udp_var.h>
689definitions for fourth level UDP identifiers
690.El
691.Sh SEE ALSO
692.Xr sysctl 8
693.Sh HISTORY
694The
695.Fn sysctl
696function first appeared in
697.Bx 4.4 .
698