manpagez: man pages & more
man sysctl(3)
Home | html | info | man

sysctl(3)                BSD Library Functions Manual                sysctl(3)


NAME

     sysctl, sysctlbyname, sysctlnametomib -- get or set system information


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <sys/types.h>
     #include <sys/sysctl.h>

     int
     sysctl(int *name, u_int namelen, void *oldp, size_t *oldlenp, void *newp,
         size_t newlen);

     int
     sysctlbyname(const char *name, void *oldp, size_t *oldlenp, void *newp,
         size_t newlen);

     int
     sysctlnametomib(const char *name, int *mibp, size_t *sizep);


DESCRIPTION

     The sysctl() function retrieves system information and allows processes
     with appropriate privileges to set system information.  The information
     available from sysctl() consists of integers, strings, and tables.
     Information may be retrieved and set from the command interface using the
     sysctl(8) utility.

     Unless explicitly noted below, sysctl() returns a consistent snapshot of
     the data requested.  Consistency is obtained by locking the destination
     buffer into memory so that the data may be copied out without blocking.
     Calls to sysctl() are serialized to avoid deadlock.

     The state is described using a ``Management Information Base'' (MIB)
     style name, listed in name, which is a namelen length array of integers.

     The sysctlbyname() function accepts an ASCII representation of the name
     and internally looks up the integer name vector.  Apart from that, it
     behaves the same as the standard sysctl() function.

     The information is copied into the buffer specified by oldp.  The size of
     the buffer is given by the location specified by oldlenp before the call,
     and that location gives the amount of data copied after a successful call
     and after a call that returns with the error code ENOMEM.  If the amount
     of data available is greater than the size of the buffer supplied, the
     call supplies as much data as fits in the buffer provided and returns
     with the error code ENOMEM.  If the old value is not desired, oldp and
     oldlenp should be set to NULL.

     The size of the available data can be determined by calling sysctl() with
     the NULL argument for oldp.  The size of the available data will be
     returned in the location pointed to by oldlenp.  For some operations, the
     amount of space may change often.  For these operations, the system
     attempts to round up so that the returned size is large enough for a call
     to return the data shortly thereafter.

     To set a new value, newp is set to point to a buffer of length newlen
     from which the requested value is to be taken.  If a new value is not to
     be set, newp should be set to NULL and newlen set to 0.

     The sysctlnametomib() function accepts an ASCII representation of the
     name, looks up the integer name vector, and returns the numeric represen-
     tation in the mib array pointed to by mibp.  The number of elements in
     the mib array is given by the location specified by sizep before the
     call, and that location gives the number of entries copied after a suc-
     cessful call.  The resulting mib and size may be used in subsequent
     sysctl() calls to get the data associated with the requested ASCII name.
     This interface is intended for use by applications that want to repeat-
     edly request the same variable (the sysctl() function runs in about a
     third the time as the same request made via the sysctlbyname() function).

     The top level names are defined with a CTL_ prefix in <sys/sysctl.h>, and
     are as follows.  The next and subsequent levels down are found in the
     include files listed here, and described in separate sections below.

           Name              Next level names          Description
           CTL_DEBUG         sys/sysctl.h              Debugging
           CTL_VFS           sys/mount.h               File system
           CTL_HW            sys/sysctl.h              Generic CPU, I/O
           CTL_KERN          sys/sysctl.h              High kernel limits
           CTL_MACHDEP       sys/sysctl.h              Machine dependent
           CTL_NET           sys/socket.h              Networking
           CTL_USER          sys/sysctl.h              User-level
           CTL_VM            sys/resources.h           Virtual memory (struct
                                                       loadavg)

     For example, the following retrieves the maximum number of processes
     allowed in the system:

           int maxproc;
           size_t len = sizeof(maxproc);
           sysctlbyname("kern.maxproc", &maxproc, &len, NULL, 0);

     To retrieve the standard search path for the system utilities:

           char *p;
           size_t len;
           sysctlbyname("user.cs_path", NULL, &len, NULL, 0);
           p = malloc(len);
           sysctlbyname("user.cs_path", p, &len, NULL, 0);

   CTL_VFS
     A distinguished second level name, VFS_GENERIC, is used to get general
     information about all file systems.  One of its third level identifiers
     is VFS_MAXTYPENUM that gives the highest valid file system type number.
     Its other third level identifier is VFS_CONF that returns configuration
     information about the file system type given as a fourth level identifier
     (see getvfsbyname(3) as an example of its use).  The remaining second
     level identifiers are the file system type number returned by a statfs(2)
     call or from VFS_CONF.  The third level identifiers available for each
     file system are given in the header file that defines the mount argument
     structure for that file system.

   CTL_HW
     The string and integer information available for the CTL_HW level is
     detailed below.  The changeable column shows whether a process with
     appropriate privilege may change the value.

           Name                         Type          Changeable
           hw.activecpu                 int32_t       no
           hw.byteorder                 int32_t       no
           hw.cacheconfig               uint64_t[]    no
           hw.cachelinesize             int64_t       no
           hw.cachesize                 uint64_t[]    no
           hw.cpu64bit_capable          int32_t       no
           hw.cpufamily                 int32_t       no
           hw.cpufrequency              int64_t       no
           hw.cpufrequency_max          int64_t       no
           hw.cpufrequency_min          int64_t       no
           hw.cpusubtype                int32_t       no
           hw.cputhreadtype             int32_t       no
           hw.cputype                   int32_t       no
           hw.l1dcachesize              int64_t       no
           hw.l1icachesize              int64_t       no
           hw.l2cachesize               int64_t       no
           hw.l3cachesize               int64_t       no
           hw.logicalcpu                int32_t       no
           hw.logicalcpu_max            int32_t       no
           hw.machine                   char[]        no
           hw.memsize                   int64_t       no
           hw.model                     char[]        no
           hw.ncpu                      int32_t       no
           hw.packages                  int32_t       no
           hw.pagesize                  int64_t       no
           hw.physicalcpu               int32_t       no
           hw.physicalcpu_max           int32_t       no
           hw.tbfrequency               int64_t       no

     hw.byteorder
             The byte order (4321 or 1234).

     hw.model
             The machine model.

     hw.ncpu
             The number of cpus. This attribute is deprecated and it is recom-
             mended that hw.logicalcpu, hw.logicalcpu_max, hw.physicalcpu, or
             hw.physicalcpu_max be used instead.

     hw.logicalcpu
             The number of logical processors available in the current power
             management mode.

     hw.logicalcpu_max
             The maximum number of logical processors that could be available
             this boot.

     hw.physicalcpu
             The number of physical processors available in the current power
             management mode.

     hw.physicalcpu_max
             The maximum number of physical processors that could be available
             this boot.

     hw.pagesize
             The software page size in bytes.

   CTL_KERN
     The string and integer information available for the CTL_KERN level is
     detailed below.  The changeable column shows whether a process with
     appropriate privilege may change the value.  The types of data currently
     available are process information, system vnodes, the open file entries,
     routing table entries, virtual memory statistics, load average history,
     and clock rate information.

           Name                         Type                    Changeable
           kern.argmax                  int32_t                 no
           kern.bootargs                char[]                  no
           kern.boottime                struct timeval          no
           kern.check_openevt           int32_t                 yes
           kern.clockrate               struct clockinfo        no
           kern.coredump                int32_t                 yes
           kern.corefile                char[]                  yes
           kern.flush_cache_on_write    int32_t                 yes
           kern.hostid                  int32_t                 yes
           kern.hostname                char[]                  yes
           kern.job_control             int32_t                 no
           kern.maxfiles                int32_t                 yes
           kern.maxfilesperproc         int32_t                 yes
           kern.maxnbuf                 int32_t                 yes
           kern.maxproc                 int32_t                 yes
           kern.maxprocperuid           int32_t                 yes
           kern.maxvnodes               int32_t                 yes
           kern.msgbuf                  int32_t                 yes
           kern.nbuf                    int32_t                 no
           kern.netboot                 int32_t                 no
           kern.ngroups                 int32_t                 no
           kern.nisdomainname           char[]                  yes
           kern.num_files               int32_t                 no
           kern.num_tasks               int32_t                 no
           kern.num_taskthreads         int32_t                 no
           kern.num_threads             int32_t                 no
           kern.num_vnodes              int32_t                 no
           kern.nx                      int32_t                 yes
           kern.osrelease               char[]                  no
           kern.osrevision              int32_t                 no
           kern.ostype                  char[]                  no
           kern.osversion               char[]                  yes
           kern.posix1version           int32_t                 no
           kern.procname                char[]                  yes
           kern.safeboot                int32_t                 no
           kern.saved_ids               int32_t                 no
           kern.secure_kernel           int32_t                 no
           kern.securelevel             int32_t                 yes
           kern.singleuser              int32_t                 no
           kern.sleeptime               struct timeval          no
           kern.slide                   int32_t                 no
           kern.stack_depth_max         int32_t                 no
           kern.stack_size              int32_t                 no
           kern.sugid_coredump          int32_t                 yes
           kern.sugid_scripts           int32_t                 yes
           kern.symfile                 char[]                  no
           kern.usrstack                int32_t                 no
           kern.usrstack64              int64_t                 no
           kern.uuid                    char[]                  no
           kern.version                 char[]                  no
           kern.waketime                struct timeval          no

     kern.argmax
             The maximum bytes of argument to execve(2).

     kern.boottime
             A struct timeval structure is returned.  This structure contains
             the time that the system was booted.

     kern.clockrate
             A struct clockinfo structure is returned.  This structure con-
             tains the clock, statistics clock and profiling clock frequen-
             cies, the number of micro-seconds per hz tick and the skew rate.

     kern.hostid
             Get or set the host id.

     kern.hostname
             Get or set the hostname.

     kern.job_control
             Return 1 if job control is available on this system, otherwise 0.

     kern.maxfiles
             The maximum number of files that may be open in the system.

     kern.maxfilesperproc
             The maximum number of files that may be open for a single
             process.  This limit only applies to processes with an effective
             uid of nonzero at the time of the open request.  Files that have
             already been opened are not affected if the limit or the effec-
             tive uid is changed.

     kern.maxproc
             The maximum number of concurrent processes the system will allow.

     kern.maxprocperuid
             The maximum number of concurrent processes the system will allow
             for a single effective uid.  This limit only applies to processes
             with an effective uid of nonzero at the time of a fork request.
             Processes that have already been started are not affected if the
             limit is changed.

     kern.maxvnodes
             The maximum number of vnodes available on the system.

     kern.ngroups
             The maximum number of supplemental groups.

     kern.nisdomainname
             The name of the current YP/NIS domain.

     kern.osrelease
             The system release string.

     kern.osrevision
             The system revision number.

     kern.ostype
             The system type string.

     kern.posix1version
             The version of IEEE Std 1003.1 (``POSIX.1'') with which the sys-
             tem attempts to comply.

     kern.saved_ids
             Returns 1 if saved set-group and saved set-user ID is available.

     kern.securelevel
             The system security level.  This level may be raised by processes
             with appropriate privilege.  It may not be lowered.

     kern.version
             The system version string.

   CTL_MACHDEP
     The set of variables defined is architecture dependent.  The following
     variables are defined for the i386 architecture.

           Name                                   Type          Changeable
           machdep.cpu.address_bits.physical      int32_t       no
           machdep.cpu.address_bits.virtual       int32_t       no
           machdep.cpu.brand                      int32_t       no
           machdep.cpu.brand_string               char[]        no
           machdep.cpu.cache.L2_associativity     int32_t       no
           machdep.cpu.cache.linesize             int32_t       no
           machdep.cpu.cache.size                 int32_t       no
           machdep.cpu.core_count                 int32_t       no
           machdep.cpu.cores_per_package          int32_t       no
           machdep.cpu.extfamily                  int32_t       no
           machdep.cpu.extfeature_bits            int64_t       no
           machdep.cpu.extfeatures                char[]        no
           machdep.cpu.extmodel                   int32_t       no
           machdep.cpu.family                     int32_t       no
           machdep.cpu.feature_bits               int64_t       no
           machdep.cpu.features                   char[]        no
           machdep.cpu.leaf7_feature_bits         uint32_t      no
           machdep.cpu.leaf7_features             char[]        no
           machdep.cpu.logical_per_package        int32_t       no
           machdep.cpu.max_basic                  uint32_t      no
           machdep.cpu.max_ext                    uint32_t      no
           machdep.cpu.microcode_version          int32_t       no
           machdep.cpu.model                      int32_t       no
           machdep.cpu.processor_flag             int32_t       no
           machdep.cpu.signature                  int32_t       no
           machdep.cpu.stepping                   int32_t       no
           machdep.cpu.thread_count               int32_t       no
           machdep.cpu.tlb.data.large             int32_t       no
           machdep.cpu.tlb.data.large_level1      int32_t       no
           machdep.cpu.tlb.data.small             int32_t       no
           machdep.cpu.tlb.data.small_level1      int32_t       no
           machdep.cpu.tlb.inst.large             int32_t       no
           machdep.cpu.tlb.inst.small             int32_t       no
           machdep.cpu.tlb.shared                 int32_t       no
           machdep.cpu.ucupdate                   int32_t       yes
           machdep.cpu.vendor                     char[]        no
           machdep.cpu.xsave.extended_state       uint32_t      no
           machdep.tsc.deep_idle_rebase           uint32_t      yes
           machdep.tsc.frequency                  int64_t       no
           machdep.tsc.nanotime.generation        uint32_t      no
           machdep.tsc.nanotime.shift             uint32_t      no

   CTL_NET
     The string and integer information available for the CTL_NET level is
     detailed below.  The changeable column shows whether a process with
     appropriate privilege may change the value.

           Second level name          Type                   Changeable
           PF_ROUTE                   routing messages       no
           PF_INET                    IPv4 values            yes
           PF_INET6                   IPv6 values            yes

     PF_ROUTE
             Return the entire routing table or a subset of it.  The data is
             returned as a sequence of routing messages (see route(4) for the
             header file, format and meaning).  The length of each message is
             contained in the message header.

             The third level name is a protocol number, which is currently
             always 0.  The fourth level name is an address family, which may
             be set to 0 to select all address families.  The fifth, sixth,
             and seventh level names are as follows:

                   Fifth level      Sixth level    Seventh level
                   NET_RT_FLAGS     rtflags        None
                   NET_RT_DUMP      None           None or fib number
                   NET_RT_IFLIST    0 or if_index  None
                   NET_RT_IFMALIST  0 or if_index  None
                   NET_RT_IFLISTL   0 or if_index  None

             The NET_RT_IFMALIST name returns information about multicast
             group memberships on all interfaces if 0 is specified, or for the
             interface specified by if_index.

     PF_INET
             Get or set various global information about the IPv4 (Internet
             Protocol version 4).  The third level name is the protocol.  The
             fourth level name is the variable name.  The currently defined
             protocols and names are:

             Protocol      Variable      Type      Changeable
             icmp          bmcastecho    integer   yes
             icmp          maskrepl      integer   yes
             ip            forwarding    integer   yes
             ip            redirect      integer   yes
             ip            ttl           integer   yes
             udp           checksum      integer   yes

             The variables are as follows:

             icmp.bmcastecho
                     Returns 1 if an ICMP echo request to a broadcast or mul-
                     ticast address is to be answered.

             icmp.maskrepl
                     Returns 1 if ICMP network mask requests are to be
                     answered.

             ip.forwarding
                     Returns 1 when IP forwarding is enabled for the host,
                     meaning that the host is acting as a router.

             ip.redirect
                     Returns 1 when ICMP redirects may be sent by the host.
                     This option is ignored unless the host is routing IP
                     packets, and should normally be enabled on all systems.

             ip.ttl  The maximum time-to-live (hop count) value for an IP
                     packet sourced by the system.  This value applies to nor-
                     mal transport protocols, not to ICMP.

             udp.checksum
                     Returns 1 when UDP checksums are being computed and
                     checked.  Disabling UDP checksums is strongly discour-
                     aged.

                     For variables net.inet.*.ipsec, please refer to ipsec(4).

     PF_INET6
             Get or set various global information about the IPv6 (Internet
             Protocol version 6).  The third level name is the protocol.  The
             fourth level name is the variable name.

             For variables net.inet6.* please refer to inet6(4).  For vari-
             ables net.inet6.*.ipsec6, please refer to ipsec(4).

   CTL_USER
     The string and integer information available for the CTL_USER level is
     detailed below.  The changeable column shows whether a process with
     appropriate privilege may change the value.

           Name                         Type          Changeable
           user.bc_base_max             int32_t       no
           user.bc_dim_max              int32_t       no
           user.bc_scale_max            int32_t       no
           user.bc_string_max           int32_t       no
           user.coll_weights_max        int32_t       no
           user.cs_path                 char[]        no
           user.expr_nest_max           int32_t       no
           user.line_max                int32_t       no
           user.posix2_c_bind           int32_t       no
           user.posix2_c_dev            int32_t       no
           user.posix2_char_term        int32_t       no
           user.posix2_fort_dev         int32_t       no
           user.posix2_fort_run         int32_t       no
           user.posix2_localedef        int32_t       no
           user.posix2_sw_dev           int32_t       no
           user.posix2_upe              int32_t       no
           user.posix2_version          int32_t       no
           user.re_dup_max              int32_t       no
           user.stream_max              int32_t       no
           user.tzname_max              int32_t       no

     user.bc_base_max
             The maximum ibase/obase values in the bc(1) utility.

     user.bc_dim_max
             The maximum array size in the bc(1) utility.

     user.bc_scale_max
             The maximum scale value in the bc(1) utility.

     user.bc_string_max
             The maximum string length in the bc(1) utility.

     user.coll_weights_max
             The maximum number of weights that can be assigned to any entry
             of the LC_COLLATE order keyword in the locale definition file.

     user.cs_path
             Return a value for the PATH environment variable that finds all
             the standard utilities.

     user.expr_nest_max
             The maximum number of expressions that can be nested within
             parenthesis by the expr(1) utility.

     user.line_max
             The maximum length in bytes of a text-processing utility's input
             line.

     user.posix2_c_bind
             Return 1 if the system's C-language development facilities sup-
             port the C-Language Bindings Option, otherwise 0.

     user.posix2_c_dev
             Return 1 if the system supports the C-Language Development Utili-
             ties Option, otherwise 0.

     user.posix2_char_term
             Return 1 if the system supports at least one terminal type capa-
             ble of all operations described in IEEE Std 1003.2 (``POSIX.2''),
             otherwise 0.

     user.posix2_fort_dev
             Return 1 if the system supports the FORTRAN Development Utilities
             Option, otherwise 0.

     user.posix2_fort_run
             Return 1 if the system supports the FORTRAN Runtime Utilities
             Option, otherwise 0.

     user.posix2_localedef
             Return 1 if the system supports the creation of locales, other-
             wise 0.

     user.posix2_sw_dev
             Return 1 if the system supports the Software Development Utili-
             ties Option, otherwise 0.

     user.posix2_upe
             Return 1 if the system supports the User Portability Utilities
             Option, otherwise 0.

     user.posix2_version
             The version of IEEE Std 1003.2 (``POSIX.2'') with which the sys-
             tem attempts to comply.

     user.re_dup_max
             The maximum number of repeated occurrences of a regular expres-
             sion permitted when using interval notation.

     user.stream_max
             The minimum maximum number of streams that a process may have
             open at any one time.

     user.tzname_max
             The minimum maximum number of types supported for the name of a
             timezone.

   CTL_VM
     The string and integer information available for the CTL_VM level is
     detailed below.  The changeable column shows whether a process with
     appropriate privilege may change the value.

           Name                         Type          Changeable
           vm.loadavg                   struct loadavgno
           vm.swapusage                 struct xsw_usageno

     vm.loadavg
             Return the load average history.  The returned data consists of a
             struct loadavg.


RETURN VALUES

     Upon successful completion, the value 0 is returned; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.


FILES

     <sys/sysctl.h>        definitions for top level identifiers, second level
                           kernel and hardware identifiers, and user level
                           identifiers
     <sys/socket.h>        definitions for second level network identifiers
     <netinet/in.h>        definitions for third level IPv4/IPv6 identifiers
                           and fourth level IPv4/v6 identifiers
     <netinet/icmp_var.h>  definitions for fourth level ICMP identifiers
     <netinet/icmp6.h>     definitions for fourth level ICMPv6 identifiers
     <netinet/udp_var.h>   definitions for fourth level UDP identifiers


ERRORS

     The following errors may be reported:

     [EFAULT]           The buffer name, oldp, newp, or length pointer oldlenp
                        contains an invalid address.

     [EINVAL]           The name array is less than two or greater than
                        CTL_MAXNAME.

     [EINVAL]           A non-null newp is given and its specified length in
                        newlen is too large or too small.

     [ENOMEM]           The length pointed to by oldlenp is too short to hold
                        the requested value.

     [ENOMEM]           The smaller of either the length pointed to by oldlenp
                        or the estimated size of the returned data exceeds the
                        system limit on locked memory.

     [ENOMEM]           Locking the buffer oldp, or a portion of the buffer if
                        the estimated size of the data to be returned is
                        smaller, would cause the process to exceed its per-
                        process locked memory limit.

     [ENOTDIR]          The name array specifies an intermediate rather than
                        terminal name.

     [EISDIR]           The name array specifies a terminal name, but the
                        actual name is not terminal.

     [ENOENT]           The name array specifies a value that is unknown.

     [EPERM]            An attempt is made to set a read-only value.

     [EPERM]            A process without appropriate privilege attempts to
                        set a value.


SEE ALSO

     confstr(3), sysconf(3), sysctl(8)


HISTORY

     The sysctl() function first appeared in 4.4BSD.

BSD                              May 17, 2013                              BSD

OS X 10.10 - Generated Fri Oct 31 20:28:00 CDT 2014
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.