1SYSCTL(3)                  Library Functions Manual                  SYSCTL(3)
2
3
4

NAME

6       sysctl - get or set system information
7

SYNOPSIS

9       #include <sys/sysctl.h>
10
11       int
12       sysctl(name, namelen, oldp, *oldlenp, *newp, newlen)
13          int *name;
14          u_int namelen;
15          void *oldp;
16          size_t *oldlenp;
17          void *newp;
18          size_t newlen
19

DESCRIPTION

21       The  sysctl  function retrieves system information and allows processes
22       with appropriate privileges to set system information.  The information
23       available  from  sysctl  consists  of  integers,  strings,  and tables.
24       Information may be retrieved and set from the command  interface  using
25       the sysctl(1) utility.
26
27       Unless  explicitly noted below, sysctl returns a consistent snapshot of
28       the data requested.  Calls to sysctl are serialized to avoid deadlock.
29
30       The state is described using a ``Management  Information  Base''  (MIB)
31       style  name,  listed in name , which is a namelen length array of inte‐
32       gers.
33
34       The information is copied into the buffer specified by oldp .  The size
35       of  the buffer is given by the location specified by oldlenp before the
36       call, and that location gives the amount of data copied  after  a  suc‐
37       cessful call.  If the amount of data available is greater than the size
38       of the buffer supplied, the call supplies as much data as fits  in  the
39       buffer  provided  and  returns  with the error code ENOMEM.  If the old
40       value is not desired, oldp and oldlenp should be set to NULL.
41
42       The size of the available data can be determined by calling sysctl with
43       a  NULL  parameter  for  oldp.   The size of the available data will be
44       returned in the location pointed to by oldlenp.  For  some  operations,
45       the amount of space may change often.  For these operations, the system
46       attempts to round up so that the returned size is large  enough  for  a
47       call to return the data shortly thereafter.
48
49       To  set  a new value, newp is set to point to a buffer of length newlen
50       from which the requested value is to be taken.  If a new value  is  not
51       to be set, newp should be set to NULL and newlen set to 0.
52
53       The  top  level names are defined with a CTL_ prefix in <sys/sysctl.h>,
54       and are as follows.  The next and subsequent levels down are  found  in
55       the  include  files  listed  here,  and  described in separate sections
56       below.
57
58         Name         Next level names      Description
59         CTL_DEBUG    sys/sysctl.h          Debugging
60         CTL_FS       sys/sysctl.h          File system
61         CTL_HW       sys/sysctl.h          Generic CPU, I/O
62         CTL_KERN     sys/sysctl.h          High kernel limits
63         CTL_MACHDEP  sys/sysctl.h          Machine dependent
64         CTL_NET      sys/socket.h          Networking
65         CTL_USER     sys/sysctl.h          User-level
66         CTL_VM       vm/vm_param.h         Virtual memory
67
68       For example, the following retrieves the maximum  number  of  processes
69       allowed in the system:
70
71            int mib[2], maxproc;
72            size_t len;
73
74            mib[0] = CTL_KERN;
75            mib[1] = KERN_MAXPROC;
76            len = sizeof(maxproc);
77            sysctl(mib, 2, &maxproc, &len, NULL, 0);
78
79       To retrieve the standard search path for the system utilities:
80
81            int mib[2];
82            size_t len;
83            char *p;
84
85            mib[0] = CTL_USER;
86            mib[1] = USER_CS_PATH;
87            sysctl(mib, 2, NULL, &len, NULL, 0);
88            p = malloc(len);
89            sysctl(mib, 2, p, &len, NULL, 0);
90

CTL_DEBUG

92       The  debugging variables vary from system to system.  A debugging vari‐
93       able may be added or deleted without need to recompile sysctl  to  know
94       about  it.   Each time it runs, sysctl gets the list of debugging vari‐
95       ables from the kernel and displays their current  values.   The  system
96       defines  twenty struct ctldebug variables named debug0 through debug19.
97       They are declared as separate variables so that they can  be  individu‐
98       ally  initialized  at  the  location of their associated variable.  The
99       loader prevents multiple use of the same variable by issuing errors  if
100       a  variable  is  initialized  in  more than one place.  For example, to
101       export the variable dospecialcheck as a debugging variable, the follow‐
102       ing declaration would be used:
103
104            int dospecialcheck = 1;
105            struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck };
106

CTL_FS

108       There are currently no second level names for the file system.
109

CTL_HW

111       The  string  and  integer information available for the CTL_HW level is
112       detailed below.  The changeable column shows  whether  a  process  with
113       appropriate privilege may change the value.
114
115         Second level name        Type      Changeable
116         HW_MACHINE               string    no
117         HW_MODEL                 string    no
118         HW_NCPU                  integer   no
119         HW_BYTEORDER             integer   no
120         HW_PHYSMEM               integer   no
121         HW_USERMEM               integer   no
122         HW_PAGESIZE              integer   no
123
124       HW_MACHINE
125            The machine class.
126
127       HW_MODEL
128            The machine model
129
130       HW_NCPU
131            The number of cpus.
132
133       HW_BYTEORDER
134            The byteorder (3412, 4321, or 1234).
135
136       HW_PHYSMEM
137            The bytes of physical memory.
138
139       HW_USERMEM
140            The bytes of non-kernel memory.
141
142       HW_PAGESIZE
143            The software page size.
144
145

CTL_KERN

147       The  string and integer information available for the CTL_KERN level is
148       detailed below.  The changeable column shows  whether  a  process  with
149       appropriate  privilege  may  change  the value.  The types of data cur‐
150       rently available are process information, system inodes, the open  file
151       entries, routing table entries, virtual memory statistics, load average
152       history, and clock rate information.
153
154
155         Second level name        Type              Changeable
156         KERN_ARGMAX              integer           no
157         KERN_BOOTTIME            struct timeval    no
158         KERN_CHOWN_RESTRICTED    integer           no
159         KERN_CLOCKRATE           struct clockinfo  no
160         KERN_FILE                struct file       no
161         KERN_HOSTID              long              yes
162         KERN_HOSTNAME            string            yes
163         KERN_JOB_CONTROL         integer           no
164         KERN_MAXFILES            integer           no
165         KERN_MAXPROC             integer           no
166         KERN_MAXINODES           integer           no
167         KERN_MAXTEXTS            integer           no
168         KERN_NGROUPS             integer           no
169         KERN_OSRELEASE           string            no
170         KERN_OSREV               integer           no
171         KERN_OSTYPE              string            no
172         KERN_POSIX1              integer           no
173         KERN_PROC                struct proc       no
174         KERN_PROF                node              not applicable
175         KERN_SAVED_IDS           integer           no
176         KERN_SECURELVL           integer           raise only
177         KERN_TEXT                struct text       no
178         KERN_VERSION             string            no
179         KERN_INODE               struct inode      no
180
181       KERN_ARGMAX
182            The maximum bytes of argument to exec(2).
183
184       KERN_BOOTTIME
185            A struct timeval structure is returned.  This  structure  contains
186            the time that the system was booted.
187
188       KERN_CLOCKRATE
189            A struct clockinfo structure is returned.  This structure contains
190            the clock, statistics clock and profiling clock  frequencies,  and
191            the number of micro-seconds per hz tick.
192
193       KERN_FILE
194            Return  the  entire file table as an array of extended file struc‐
195            tures.  Each element of the array contains the kernel address of a
196            file  struct  inode  *  followed  by  the file itself struct file.
197            There can never be more than KERN_MAXFILES inodes returned.
198
199       KERN_HOSTID
200            Get or set the host id.
201
202       KERN_HOSTNAME
203            Get or set the hostname.
204
205       KERN_JOB_CONTROL
206            Return 1 if job control is available on this system, otherwise 0.
207
208       KERN_MAXFILES
209            The maximum number of open files that may be open in the system.
210
211       KERN_MAXPROC
212            The maximum number  of  simultaneous  processes  the  system  will
213            allow.
214
215       KERN_MAXINODES
216            The maximum number of inodes available on the system.
217
218       KERN_MAXTEXTS
219            The maximum number of text structures available on the system.
220
221       KERN_NGROUPS
222            The maximum number of supplemental groups.
223
224       KERN_OSRELEASE
225            The system release string.
226
227       KERN_OSREV
228            The system revision string.
229
230       KERN_OSTYPE
231            The system type string.
232
233       KERN_POSIX1
234            The  version  of ISO/IEC 9945 (POSIX 1003.1) with which the system
235            attempts to comply.
236
237       KERN_PROC
238            Return the entire process table, or a subset of it.  An  array  of
239            struct  kinfo_proc  structures  is returned, whose size depends on
240            the current number of such objects in the system.
241
242       The third and fourth level names are as follows:
243
244         Third level name            Fourth level is:
245         KERN_PROC_ALL               None
246         KERN_PROC_PID               A process ID
247         KERN_PROC_PGRP              A process group
248         KERN_PROC_TTY               A tty device
249         KERN_PROC_UID               A user ID
250         KERN_PROC_RUID              A real user ID
251         KERN_PROF                   Return kernel profiling information.
252
253            If the kernel is not compiled for profiling, attempts to  retrieve
254            any of the KERN_PROF values will fail with EOPNOTSUPP.
255
256       The  third level names for the string and integer profiling information
257       is detailed below.  The changeable column shows whether a process  with
258       appropriate privilege may change the value.
259
260            Third level name      Type                Changeable
261              GPROF_STATE         integer             yes
262              GPROF_COUNT         u_short[]           yes
263              GPROF_FROMS         u_short[]           yes
264              GPROF_TOS           struct tostruct     yes
265              GPROF_GMONPARAM     struct gmonparam    no
266
267       The variables are as follows:
268
269       GPROF_STATE
270            Returns  GMON_PROF_ON  or  GMON_PROF_OFF to show that profiling is
271            running or stopped.
272
273       GPROF_COUNT
274            Array of statistical program counter counts.
275
276       GPROF_FROMS
277            Array indexed by program counter of call-from points.
278
279       GPROF_TOS
280            Array of struct tostruct describing destination of calls and their
281            counts.
282
283       GPROF_GMONPARAM
284            Structure giving the sizes of the above arrays.
285
286       KERN_SAVED_IDS
287            Returns 1 if saved set-group and saved set-user ID is available.
288
289  KERN_SECURELVL
290       The  system security level.  This level may be raised by processes with
291       appropriate privilege.  It may only be lowered by process 1.
292
293  KERN_VERSION
294       The system version string.
295
296  KERN_INODE
297       Return the entire inode table.  Note, the inode table is not  necessar‐
298       ily a consistent snapshot of the system.  The returned data consists of
299       an array whose size depends on the current number of  such  objects  in
300       the system.  Each element of the array contains the kernel address of a
301       inode struct inode * followed by the inode itself struct inode.   There
302       can never be more than KERN_MAXINODES inodes returned.
303
304  KERN_TEXT
305       Return  the  entire text table.  The returned data consists of an array
306       whose size depends on the current number of such objects active in  the
307       system.   Each  element  of  the array contains the kernel address of a
308       text struct text * followed by the text structure itself  struct  text.
309       There can never be more structures than returned by KERN_MAXTEXTS.
310

CTL_MACHDEP

312       The set of variables defined is architecture dependent.  Most architec‐
313       tures define at least the following variables.
314
315         Second level name        Type      Changeable
316         CPU_CONSDEV              dev_t     no
317

CTL_NET

319       The string and integer information available for the CTL_NET  level  is
320       detailed  below.   The  changeable  column shows whether a process with
321       appropriate privilege may change the value.
322
323         Second level name   Type              Changeable
324         PF_ROUTE            routing messages  no
325         PF_INET             internet values   yes
326
327       PF_ROUTE
328            Return the entire routing table or a subset of it.   The  data  is
329            returned  as  a sequence of routing messages (see route(4) for the
330            header file, format and meaning).  The length of each  message  is
331            contained in the message header.
332
333       The third level name is a protocol number, which is currently always 0.
334       The fourth level name is an address family, which may be set  to  0  to
335       select  all  address  families.  The fifth and sixth level names are as
336       follows:
337
338         Fifth level name         Sixth level is:
339         NET_RT_FLAGS             rtflags
340         NET_RT_DUMP              None
341         NET_RT_IFLIST            None
342
343       PF_INET
344            Get or set various global information about  the  internet  proto‐
345            cols.   The  third  level  name is the protocol.  The fourth level
346            name is the variable name.  The currently  defined  protocols  and
347            names are:
348
349         Protocol name     Variable name    Type      Changeable
350         ip                forwarding       integer   yes
351         ip                redirect         integer   yes
352         ip                ttl              integer   yes
353         icmp              maskrepl         integer   yes
354         udp               checksum         integer   yes
355
356       The variables are as follows:
357
358       ip.forwarding
359            Returns 1 when IP forwarding is enabled for the host, meaning that
360            the host is acting as a router.
361
362       ip.redirect
363            Returns 1 when ICMP redirects may  be  sent  by  the  host.   This
364            option  is  ignored  unless  the  host  is routing IP packets, and
365            should normally be enabled on all systems.
366
367       ip.ttl
368            The maximum time-to-live  (hop  count)  value  for  an  IP  packet
369            sourced  by  the  system.   This value applies to normal transport
370            protocols, not to ICMP.
371
372       icmp.maskrepl
373            Returns 1 if ICMP network mask requests are to be answered.
374
375       udp.checksum
376            Returns 1 when UDP checksums are being computed and checked.  Dis‐
377            abling UDP checksums is strongly discouraged.
378
379

CTL_USER

381       The  string and integer information available for the CTL_USER level is
382       detailed below.  The changeable column shows  whether  a  process  with
383       appropriate privilege may change the value.
384
385         Second level name           Type        Changeable
386         USER_BC_BASE_MAX            integer     no
387         USER_BC_DIM_MAX             integer     no
388         USER_BC_SCALE_MAX           integer     no
389         USER_BC_STRING_MAX          integer     no
390         USER_COLL_WEIGHTS_MAX       integer     no
391         USER_CS_PATH                string      no
392         USER_EXPR_NEST_MAX          integer     no
393         USER_LINE_MAX               integer     no
394         USER_POSIX2_CHAR_TERM       integer     no
395         USER_POSIX2_C_BIND          integer     no
396         USER_POSIX2_C_DEV           integer     no
397         USER_POSIX2_FORT_DEV        integer     no
398         USER_POSIX2_FORT_RUN        integer     no
399         USER_POSIX2_LOCALEDEF       integer     no
400         USER_POSIX2_SW_DEV          integer     no
401         USER_POSIX2_UPE             integer     no
402         USER_POSIX2_VERSION         integer     no
403         USER_RE_DUP_MAX             integer     no
404         USER_STREAM_MAX             integer     no
405         USER_TZNAME_MAX             integer     no
406
407       USER_BC_BASE_MAX
408            The maximum ibase/obase values in the bc(1) utility.
409
410       USER_BC_DIM_MAX
411            The maximum array size in the bc(1) utility.
412
413       USER_BC_SCALE_MAX
414            The maximum scale value in the bc(1) utility.
415
416       USER_BC_STRING_MAX
417            The maximum string length in the bc(1) utility.
418
419       USER_COLL_WEIGHTS_MAX
420            The maximum number of weights that can be assigned to any entry of
421            the LC_COLLATE order keyword in the locale definition file.
422
423       USER_CS_PATH
424            Return a value for the PATH environment variable  that  finds  all
425            the standard utilities.
426
427       USER_EXPR_NEST_MAX
428            The maximum number of expressions that can be nested within paren‐
429            thesis by the expr(1) utility.
430
431       USER_LINE_MAX
432            The maximum length in bytes of a text-processing  utility's  input
433            line.
434
435       USER_POSIX2_CHAR_TERM
436            Return 1 if the system supports at least one terminal type capable
437            of all operations described in POSIX 1003.2, otherwise 0.
438
439       USER_POSIX2_C_BIND
440            Return 1 if the system's C-language development facilities support
441            the C-Language Bindings Option, otherwise 0.
442
443       USER_POSIX2_C_DEV
444            Return  1 if the system supports the C-Language Development Utili‐
445            ties Option, otherwise 0.
446
447       USER_POSIX2_FORT_DEV
448            Return 1 if the system supports the FORTRAN Development  Utilities
449            Option, otherwise 0.
450
451       USER_POSIX2_FORT_RUN
452            Return  1  if  the  system  supports the FORTRAN Runtime Utilities
453            Option, otherwise 0.
454
455       USER_POSIX2_LOCALEDEF
456            Return 1 if the system supports the creation of locales, otherwise
457            0.
458
459       USER_POSIX2_SW_DEV
460            Return 1 if the system supports the Software Development Utilities
461            Option, otherwise 0.
462
463       USER_POSIX2_UPE
464            Return 1 if the system supports  the  User  Portability  Utilities
465            Option, otherwise 0.
466
467       USER_POSIX2_VERSION
468            The version of POSIX 1003.2 with which the system attempts to com‐
469            ply.
470
471       USER_RE_DUP_MAX
472            The maximum number of repeated occurrences of a regular expression
473            permitted when using interval notation.
474
475       USER_STREAM_MAX
476            The minimum maximum number of streams that a process may have open
477            at any one time.
478
479       USER_TZNAME_MAX
480            The minimum maximum number of types supported for the  name  of  a
481            timezone.
482

CTL_VM

484       The  string  and  integer information available for the CTL_VM level is
485       detailed below.  The changeable column shows  whether  a  process  with
486       appropriate privilege may change the value.
487
488         Second level name   Type              Changeable
489         VM_LOADAVG          struct loadavg    no
490         VM_METER            struct vmtotal    no
491         VM_SWAPMAP          struct map        no
492         VM_COREMAP          struct map        no
493
494       VM_LOADAVG
495            Return  the load average history.  The returned data consists of a
496            struct loadavg.
497
498       VM_METER
499            Return the system wide virtual memory  statistics.   The  returned
500            data consists of a struct vmtotal.
501
502       VM_SWAPMAP
503            Return  the  swapmap.  The size of this structure is fixed and may
504            be determined by specifying a oldlenp  initialized  to  zero,  the
505            kernel will fill in the size of the swapmap.
506
507       VM_COREMAP
508            Same  as  for swapmap above except that the core allocation map is
509            returned.
510

RETURN VALUES

512       If the call to sysctl is successful, 0 is returned.   Otherwise  -1  is
513       returned and errno is set appropriately.
514

ERRORS

516       The following errors may be reported:
517
518       EFAULT         The buffer name, oldp , newp , or length pointer oldlenp
519                      contains an invalid address.
520
521       EINVAL         The name array is less than two or greater than CTL_MAX‐
522                      NAME.
523
524       EINVAL         A  non-null  newp  is  given and its specified length in
525                      newlen is too large or too small.
526
527       ENOMEM         The length pointed to by oldlenp is too  short  to  hold
528                      the requested value.
529
530       ENOTDIR        The  name  array  specifies  an intermediate rather than
531                      terminal name.
532
533       EOPNOTSUPP     The name array specifies a value that is unknown.
534
535       EPERM          An attempt is made to set a read-only value.
536
537       EPERM          A process without appropriate privilege attempts to  set
538                      a value.
539

FILES

541       <sys/sysctl.h> definitions for top level identifiers, second level ker‐
542                      nel and hardware identifiers, and user level identifiers
543
544       <sys/socket.h> definitions for second level network identifiers
545
546       <sys/gmon.h>   definitions for third level profiling identifiers
547
548       <sys/vmparam.h>
549                      definitions for second level virtual memory identifiers
550
551       <netinet/in.h> definitions for third  level  Internet  identifiers  and
552                      fourth level IP identifiers
553
554       <netinet/icmp_var.h>
555                      definitions for fourth level ICMP identifiers
556
557       <netinet/udp_var.h>
558                      definitions for fourth level UDP identifiers
559

SEE ALSO

561       sysctl(8)
562

HISTORY

564       The sysctl function first appeared in 4.4BSD.
565
566       The   KERN_TEXT,  KERN_MAXTEXTS,  VM_SWAPMAP,  VM_COREMAP  options  are
567       2.11BSD specific extensions to the 4.4BSD sysctl implmentation.
568
569       Having KERN_FILE return the address of the file  structure  before  the
570       actual  struct  file  is a 2.11BSD enhancement.  The inode (vnode under
571       4.4) table was handled this way.
572
573
574
5754th Berkeley Distribution      January 13, 1995                      SYSCTL(3)
Impressum