👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for sysctlnametomib (netbsd section 3)

SYSCTL(3)			   BSD Library Functions Manual 			SYSCTL(3)

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

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/param.h>
     #include <sys/sysctl.h>

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

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

     int
     sysctlgetmibinfo(const char *sname, int *name, u_int *namelenp, char *cname, size_t *csz,
	 struct sysctlnode **rnode, int v);

     int
     sysctlnametomib(const char *sname, int *name, size_t *namelenp);

DESCRIPTION
     The sysctl function retrieves system information and allows processes with appropriate priv-
     ileges to set system information.	The information available from sysctl consists of inte-
     gers, 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 a string representation of a MIB entry and internally
     maps it to the appropriate numeric MIB representation.  Its semantics are otherwise no dif-
     ferent from sysctl().

     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.  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 a NULL parameter 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 can be used to map the string representation of a MIB entry
     to the numeric version.  The name argument should point to an array of integers large enough
     to hold the MIB, and namelenp should indicate the number of integer slots available.  Fol-
     lowing a successful translation, the size_t indicated by namelenp will be changed to show
     the number of slots consumed.

     The sysctlgetmibinfo() function performs name translation similar to sysctlnametomib(), but
     also canonicalizes the name (or returns the first erroneous token from the string being
     parsed) into the space indicated by cname and csz.  csz should indicate the size of the buf-
     fer pointed to by cname and on return, will indicate the size of the returned string includ-
     ing the trailing 'nul' character.

     The rnode and v arguments to sysctlgetmibinfo() are used to provide a tree for it to parse
     into, and to get back either a pointer to, or a copy of, the terminal node.  If rnode is
     NULL, sysctlgetmibinfo() uses its own internal tree for parsing, and checks it against the
     kernel at each call, to make sure that the name-to-number mapping is kept up to date.  The v
     argument is ignored in this case.	If rnode is not NULL but the pointer it references is, on
     a successful return, rnode will be adjusted to point to a copy of the terminal node.  The v
     argument indicates which version of the sysctl node structure the caller wants.  The appli-
     cation must later free() this copy.  If neither rnode nor the pointer it references are
     NULL, the pointer is used as the address of a tree over which the parsing is done.  In this
     last case, the tree is not checked against the kernel, no refreshing of the mappings is per-
     formed, and the value given by v must agree with the version indicated by the tree.  It is
     recommended that applications always use SYSCTL_VERSION as the value for v, as defined in
     the include file sys/sysctl.h.

     The numeric and text names of sysctl variables are described in sysctl(7).  The numeric
     names are defined as preprocessor macros.	The top level names are defined with a CTL_ pre-
     fix in <sys/sysctl.h>.  The next and subsequent levels down have different prefixes for each
     subtree.

     For example, the following retrieves the maximum number of processes allowed in the system -
     the kern.maxproc variable:
	   int mib[2], maxproc;
	   size_t len;

	   mib[0] = CTL_KERN;
	   mib[1] = KERN_MAXPROC;
	   len = sizeof(maxproc);
	   sysctl(mib, 2, &maxproc, &len, NULL, 0);

     To retrieve the standard search path for the system utilities - user.cs_path:
	   int mib[2];
	   size_t len;
	   char *p;

	   mib[0] = CTL_USER;
	   mib[1] = USER_CS_PATH;
	   sysctl(mib, 2, NULL, &len, NULL, 0);
	   p = malloc(len);
	   sysctl(mib, 2, p, &len, NULL, 0);

DYNAMIC OPERATIONS
     Several meta-identifiers are provided to perform operations on the sysctl tree itself, or
     support alternate means of accessing the data instrumented by the sysctl tree.

     Name		 Description
     CTL_QUERY		 Retrieve a mapping of names to numbers below a given node
     CTL_CREATE 	 Create a new node
     CTL_CREATESYM	 Create a new node by its kernel symbol
     CTL_DESTROY	 Destroy a node
     CTL_DESCRIBE	 Retrieve node descriptions

     The core interface to all of these meta-functions is the structure that the kernel uses to
     describe the tree internally, as defined in <sys/sysctl.h> as:

     struct sysctlnode {
	     uint32_t sysctl_flags;	     /* flags and type */
	     int32_t sysctl_num;	     /* mib number */
	     char sysctl_name[SYSCTL_NAMELEN]; /* node name */
	     uint32_t sysctl_ver;	 /* node's version vs. rest of tree */
	     uint32_t __rsvd;
	     union {
		     struct {
			     uint32_t suc_csize; /* size of child node array */
			     uint32_t suc_clen; /* number of valid children */
			     struct sysctlnode* suc_child; /* array of child nodes */
		     } scu_child;
		     struct {
			     void *sud_data; /* pointer to external data */
			     size_t sud_offset; /* offset to data */
		     } scu_data;
		     int32_t scu_alias;      /* node this node refers to */
		     int32_t scu_idata;      /* immediate "int" data */
		     u_quad_t scu_qdata;     /* immediate "u_quad_t" data */
	     } sysctl_un;
	     size_t _sysctl_size;	     /* size of instrumented data */
	     sysctlfn _sysctl_func;	     /* access helper function */
	     struct sysctlnode *sysctl_parent; /* parent of this node */
	     const char *sysctl_desc;	     /* description of node */
     };

     #define sysctl_csize    sysctl_un.scu_child.suc_csize
     #define sysctl_clen     sysctl_un.scu_child.suc_clen
     #define sysctl_child    sysctl_un.scu_child.suc_child
     #define sysctl_data     sysctl_un.scu_data.sud_data
     #define sysctl_offset   sysctl_un.scu_data.sud_offset
     #define sysctl_alias    sysctl_un.scu_alias
     #define sysctl_idata    sysctl_un.scu_idata
     #define sysctl_qdata    sysctl_un.scu_qdata

     Querying the tree to discover the name to number mapping permits dynamic discovery of all
     the data that the tree currently has instrumented.  For example, to discover all the nodes
     below the CTL_VFS node:

	   struct sysctlnode query, vfs[128];
	   int mib[2];
	   size_t len;

	   mib[0] = CTL_VFS;
	   mib[1] = CTL_QUERY;
	   memset(&query, 0, sizeof(query));
	   query.sysctl_flags = SYSCTL_VERSION;
	   len = sizeof(vfs);
	   sysctl(mib, 2, &vfs[0], &len, &query, sizeof(query));

     Note that a reference to an empty node with sysctl_flags set to SYSCTL_VERSION is passed to
     sysctl in order to indicate the version that the program is using.  All dynamic operations
     passing nodes into sysctl require that the version be explicitly specified.

     Creation and destruction of nodes works by constructing part of a new node description (or a
     description of the existing node) and invoking CTL_CREATE (or CTL_CREATESYM) or CTL_DESTROY
     at the parent of the new node, with a pointer to the new node passed via the new and newlen
     arguments.  If valid values for old and oldlenp are passed, a copy of the new node once in
     the tree will be returned.  If the create operation fails because a node with the same name
     or MIB number exists, a copy of the conflicting node will be returned.

     The minimum requirements for creating a node are setting the sysctl_flags to indicate the
     new node's type, sysctl_num to either the new node's number (or CTL_CREATE or CTL_CREATESYM
     if a dynamically allocated MIB number is acceptable), sysctl_size to the size of the data to
     be instrumented (which must agree with the given type), and sysctl_name must be set to the
     new node's name.  Nodes that are not of type ``node'' must also have some description of the
     data to be instrumented, which will vary depending on what is to be instrumented.

     If existing kernel data is to be covered by this new node, its address should be given in
     sysctl_data or, if CTL_CREATESYM is used, sysctl_data should be set to a string containing
     its name from the kernel's symbol table.  If new data is to be instrumented and an initial
     value is available, the new integer or quad type data should be placed into either
     sysctl_idata or sysctl_qdata, respectively, along with the SYSCTL_IMMEDIATE flag being set,
     or sysctl_data should be set to point to a copy of the new data, and the SYSCTL_OWNDATA flag
     must be set.  This latter method is the only way that new string and struct type nodes can
     be initialized.  Invalid kernel addresses are accepted, but any attempt to access those
     nodes will return an error.

     The sysctl_csize, sysctl_clen, sysctl_child, sysctl_parent, and sysctl_alias members are
     used by the kernel to link the tree together and must be NULL or 0.  Nodes created in this
     manner cannot have helper functions, so sysctl_func must also be NULL.  If the sysctl_ver
     member is non-zero, it must match either the version of the parent or the version at the
     root of the MIB or an error is returned.  This can be used to ensure that nodes are only
     added or removed from a known state of the tree.  Note: It may not be possible to determine
     the version at the root of the tree.

     This example creates a new subtree and adds a node to it that controls the audiodebug kernel
     variable, thereby making it tunable at at any time, without needing to use ddb(4) or kvm(3)
     to alter the kernel's memory directly.

	   struct sysctlnode node;
	   int mib[2];
	   size_t len;

	   mib[0] = CTL_CREATE; 	   /* create at top-level */
	   len = sizeof(node);
	   memset(&node, 0, len);
	   node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_NODE;
	   snprintf(node.sysctl_name, sizeof(node.sysctl_name), "local");
	   node.sysctl_num = CTL_CREATE;   /* request dynamic MIB number */
	   sysctl(&mib[0], 1, &node, &len, &node, len);

	   mib[0] = node.sysctl_num;	   /* use new MIB number */
	   mib[1] = CTL_CREATESYM;	   /* create at second level */
	   len = sizeof(node);
	   memset(&node, 0, len);
	   node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_INT;
	   snprintf(node.sysctl_name, sizeof(node.sysctl_name), "audiodebug");
	   node.sysctl_num = CTL_CREATE;
	   node.sysctl_data = "audiodebug"; /* kernel symbol to be used */
	   sysctl(&mib[0], 2, NULL, NULL, &node, len);

     The process for deleting nodes is similar, but less data needs to be supplied.  Only the
     sysctl_num field needs to be filled in; almost all other fields must be left blank.  The
     sysctl_name and/or sysctl_ver fields can be filled in with the name and version of the
     existing node as additional checks on what will be deleted.  If all the given data fail to
     match any node, nothing will be deleted.  If valid values for old and oldlenp are supplied
     and a node is deleted, a copy of what was in the MIB tree will be returned.

     This sample code shows the deletion of the two nodes created in the above example:

	   int mib[2];

	   len = sizeof(node);
	   memset(&node, 0, len);
	   node.sysctl_flags = SYSCTL_VERSION;

	   mib[0] = 3214;		   /* assumed number for "local" */
	   mib[1] = CTL_DESTROY;
	   node.sysctl_num = 3215;	   /* assumed number for "audiodebug" */
	   sysctl(&mib[0], 2, NULL, NULL, &node, len);

	   mib[0] = CTL_DESTROY;
	   node.sysctl_num = 3214;	   /* now deleting "local" */
	   sysctl(&mib[0], 1, NULL, NULL, &node, len);

     Descriptions of each of the nodes can also be retrieved, if they are available.  Descrip-
     tions can be retrieved in bulk at each level or on a per-node basis.  The layout of the buf-
     fer into which the descriptions are returned is a series of variable length structures, each
     of which describes its own size.  The length indicated includes the terminating 'nul' char-
     acter.  Nodes that have no description or where the description is not available are indi-
     cated by an empty string.	The descr_ver will match the sysctl_ver value for a given node,
     so that descriptions for nodes whose number have been recycled can be detected and ignored
     or discarded.

     struct sysctldesc {
	     int32_t	     descr_num;      /* mib number of node */
	     uint32_t	     descr_ver;      /* version of node */
	     uint32_t	     descr_len;      /* length of description string */
	     char	     descr_str[1];   /* not really 1...see above */
     };

     The NEXT_DESCR() macro can be used to skip to the next description in the retrieved list.

	   struct sysctlnode desc;
	   struct sysctldesc *d;
	   char buf[1024];
	   int mib[2];
	   size_t len;

	   /* retrieve kern-level descriptions */
	   mib[0] = CTL_KERN;
	   mib[1] = CTL_DESCRIBE;
	   d = (struct sysctldesc *)&buf[0];
	   len = sizeof(buf);
	   sysctl(mib, 2, d, &len, NULL, 0);
	   while ((caddr_t)d < (caddr_t)&buf[len]) {
		   printf("node %d: %.*s\n", d->descr_num, d->descr_len,
		       d->descr_str);
		   d = NEXT_DESCR(d);
	   }

	   /* retrieve description for kern.securelevel */
	   memset(&desc, 0, sizeof(desc));
	   desc.sysctl_flags = SYSCTL_VERSION;
	   desc.sysctl_num = KERN_SECURELEVEL;
	   d = (struct sysctldesc *)&buf[0];
	   len = sizeof(buf);
	   sysctl(mib, 2, d, &len, &desc, sizeof(desc));
	   printf("kern.securelevel: %.*s\n", d->descr_len, d->descr_str);

     Descriptions can also be set as follows, subject to the following rules:

     o	 The kernel securelevel is at zero or lower
     o	 The caller has super-user privileges
     o	 The node does not currently have a description
     o	 The node is not marked as ``permanent''

	   struct sysctlnode desc;
	   int mib[2];

	   /* presuming the given top-level node was just added... */
	   mib[0] = 3214; /* mib numbers taken from previous examples */
	   mib[1] = CTL_DESCRIBE;
	   memset(&desc, 0, sizeof(desc));
	   desc.sysctl_flags = SYSCTL_VERSION;
	   desc.sysctl_num = 3215;
	   desc.sysctl_desc = "audio debug control knob";
	   sysctl(mib, 2, NULL, NULL, &desc, sizeof(desc));

     Upon successfully setting a description, the new description will be returned in the space
     indicated by the oldp and oldlenp arguments.

     The sysctl_flags field in the struct sysctlnode contains the sysctl version, node type
     information, and a number of flags.  The macros SYSCTL_VERS(), SYSCTL_TYPE(), and
     SYSCTL_FLAGS() can be used to access the different fields.  Valid flags are:

     Name		     Description
     CTLFLAG_READONLY	     Node is read-only
     CTLFLAG_READWRITE	     Node is writable by the superuser
     CTLFLAG_ANYWRITE	     Node is writable by anyone
     CTLFLAG_PRIVATE	     Node is readable only by the superuser
     CTLFLAG_PERMANENT	     Node cannot be removed (cannot be set by processes)
     CTLFLAG_OWNDATA	     Node owns data and does not instrument existing data
     CTLFLAG_IMMEDIATE	     Node contains instrumented data and does not instrument existing
			     data
     CTLFLAG_HEX	     Node's contents should be displayed in a hexadecimal form
     CTLFLAG_ROOT	     Node is the root of a tree (cannot be set at any time)
     CTLFLAG_ANYNUMBER	     Node matches any MIB number (cannot be set by processes)
     CTLFLAG_HIDDEN	     Node not displayed by default
     CTLFLAG_ALIAS	     Node refers to a sibling node (cannot be set by processes)
     CTLFLAG_OWNDESC	     Node owns its own description string space

RETURN VALUES
     If the call to sysctl is successful, 0 is returned.  Otherwise -1 is returned and errno is
     set appropriately.

FILES
     <sys/sysctl.h>	    definitions for top level identifiers, second level kernel and hard-
			    ware identifiers, and user level identifiers
     <sys/socket.h>	    definitions for second level network identifiers
     <sys/gmon.h>	    definitions for third level profiling identifiers
     <uvm/uvm_param.h>	    definitions for second level virtual memory identifiers
     <netinet/in.h>	    definitions for third level IPv4/v6 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/tcp_var.h>    definitions for fourth level TCP identifiers
     <netinet/udp_var.h>    definitions for fourth level UDP identifiers
     <netinet6/udp6_var.h>  definitions for fourth level IPv6 UDP identifiers
     <netinet6/ipsec.h>     definitions for fourth level IPsec identifiers
     <netkey/key_var.h>     definitions for third level PF_KEY identifiers
     <machine/cpu.h>	    definitions for second level machdep identifiers

ERRORS
     The following errors may be reported:

     [EFAULT]		The buffer name, oldp, newp, or length pointer oldlenp contains an
			invalid address, or the requested value is temporarily unavailable.

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

     [EINVAL]		A non-null newp is given and its specified length in newlen is too large
			or too small, or the given value is not acceptable for the given node.

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

     [ENOENT]		The name array specifies a node that does not exist in the tree.

     [ENOENT]		An attempt was made to destroy a node that does not exist, or to create
			or destroy a node below a node that does not exist.

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

     [ENOTDIR]		The name array specifies a node below a node that addresses data.

     [ENOTEMPTY]	An attempt was made to destroy a node that still has children.

     [EOPNOTSUPP]	The name array specifies a value that is unknown or a meta-operation was
			attempted that the requested node does not support.

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

     [EPERM]		A process without appropriate privilege attempts to set a value or to
			create or destroy a node.

     [EPERM]		An attempt to change a value protected by the current kernel security
			level is made.

SEE ALSO
     sysctl(7), sysctl(8), secmodel_securelevel(9)

HISTORY
     The sysctl function first appeared in 4.4BSD.

BSD					September 26, 2009				      BSD


All times are GMT -4. The time now is 06:20 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?