unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

SYSCTL_INT(9)            BSD Kernel Developer's Manual           SYSCTL_INT(9)

NAME
     sysctl_int, sysctl_int_arr, sysctl_quad, sysctl_string, sysctl_tstring,
     sysctl_rdint, sysctl_rdquad, sysctl_rdstring, sysctl_rdstruct,
     sysctl_struct -- kernel sysctl interface

SYNOPSIS
     #include <&lt;sys/types.h>&gt;
     #include <&lt;sys/sysctl.h>&gt;

     int
     sysctl_int(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
         int *valp);

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

     int
     sysctl_quad(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
         int64_t *valp);

     int
     sysctl_string(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
         char *str, int maxlen);

     int
     sysctl_tstring(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
         char *str, int maxlen);

     int
     sysctl_rdint(void *oldp, size_t *oldlenp, void *newp, int val);

     int
     sysctl_rdquad(void *oldp, size_t *oldlenp, void *newp, int64_t val);

     int
     sysctl_rdstring(void *oldp, size_t *oldlenp, void *newp,
         const char *str);

     int
     sysctl_rdstruct(void *oldp, size_t *oldlenp, void *newp, const void *sp,
         int len);

     int
     sysctl_struct(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
         void *sp, int len);

DESCRIPTION
     These functions and data structures aim to simplify and partially imple-
     ment operations for the kernel and user implementations of the sysctl(3)
     interface.  A single syscall(9) is used to request and modify kernel
     variables.  The mib argument is recursively scanned as an array of inte-
     gers, either calling further functions for parsing the rest of the MIB
     for nodes or operating on kernel data for leaf nodes.

   Data Structures
     For each level of the MIB tree, the kernel header files provide a cpp(1)
     macro initialiser for an array of the following data structures:

           struct ctlname {
                   char    *ctl_name;      /* subsystem name */
                   int     ctl_type;       /* type of name */
           };

     For example:

           #define CTL_NAMES { \
                   { 0, 0 }, \
                   { "kern", CTLTYPE_NODE }, \
                   { "vm", CTLTYPE_NODE }, \
                   { "fs", CTLTYPE_NODE }, \
                   { "net", CTLTYPE_NODE }, \
                   { "debug", CTLTYPE_NODE }, \
                   { "hw", CTLTYPE_NODE }, \
                   { "machdep", CTLTYPE_NODE }, \
                   { "user", CTLTYPE_NODE }, \
                   { "ddb", CTLTYPE_NODE }, \
                   { "vfs", CTLTYPE_NODE }, \
           }

     Each array element initialiser maps the correspondent MIB identifier.
     The ctl_name field provides a string name.  The ctl_type field describes
     the identifier type, where possible values are:

           CTLTYPE_NODE     The name is a node;
           CTLTYPE_INT      The name describes an integer;
           CTLTYPE_STRING   The name describes a string;
           CTLTYPE_QUAD     The name describes a 64-bit number;
           CTLTYPE_STRUCT   The name describes a structure.

     For each of the types there are two functions provided to perform both
     read and write or only a read operation on the identifier (see the fol-
     lowing subsection).

     These data structures are used by the sysctl(8) program to provide map-
     ping into MIB identifiers.

   Functions
     All of the functions perform a write provided that newp is not a NULL
     pointer and newlen specifies an appropriate data length.  All read-only
     versions of the functions return EPERM if a write operation is requested.

     The following helper functions are provided to aid operation on the ker-
     nel data variables referenced by the leaf nodes in the MIBs:

     sysctl_int(void *oldp, size_t *oldlenp, void *newp, size_t newlen, int
              *valp)
              The variable referenced by valp is a 32-bit integer.  Read or
              write returning the previous value in the user memory location
              pointed to by the oldp argument.  The value pointed to by
              oldlenp has to be no less than four.

     sysctl_rdint(void *oldp, size_t *oldlenp, void *newp, int val)
              A read-only version of the above.

     sysctl_quad(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
              int64_t *valp)
              The variable referenced is a 64-bit integer.  Read or write
              returning the previous value in the user memory location pointed
              to by the oldp argument.  The value pointed to by oldlenp has to
              be no less than eight.

     sysctl_rdquad(void *oldp, size_t *oldlenp, void *newp, int64_t val)
              A read-only version of the above.

     sysctl_string(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
              char *str, int maxlen)
              The variable referenced by the str argument is a string of maxi-
              mum length of maxlen.  The old value is copied out into a user
              buffer pointed to by the oldp argument.  If there is not enough
              space to store it, an ENOMEM is returned.  If newlen is larger
              than maxlen, an EINVAL error is returned.

     sysctl_tstring(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
              char *str, int maxlen)
              A version of the above that truncates the old value that does
              not fit into the buffer provided by oldp instead of returning
              ENOMEM.

     sysctl_rdstring(void *oldp, size_t *oldlenp, void *newp, const char *str)
              A read-only version of sysctl_string().

     sysctl_struct(void *oldp, size_t *oldlenp, void *newp, size_t newlen,
              void *sp, int len)
              Assume the area pointed to by the sp argument is an opaque array
              of bytes of size len.  Old and new length checks are performed
              and data is copied in and/or out.

     sysctl_rdstruct(void *oldp, size_t *oldlenp, void *newp, const void *sp,
              int len)
              A read-only version of the above.

SEE ALSO
     sysctl(3), sysctl.conf(5), sysctl(8), syscall(9)

HISTORY
     These functions first appeared in 4.4BSD.

BSD                              June 4, 2013                              BSD