2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
724 lines
22 KiB
Groff
724 lines
22 KiB
Groff
.\" $NetBSD: sysctl.3,v 1.200 2010/03/22 19:30:54 joerg Exp $
|
|
.\"
|
|
.\" Copyright (c) 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)sysctl.3 8.4 (Berkeley) 5/9/95
|
|
.\"
|
|
.Dd September 26, 2009
|
|
.Dt SYSCTL 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sysctl ,
|
|
.Nm sysctlbyname ,
|
|
.Nm sysctlgetmibinfo ,
|
|
.Nm sysctlnametomib
|
|
.Nd get or set system information
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In sys/sysctl.h
|
|
.Ft int
|
|
.Fn sysctl "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" \
|
|
"const void *newp" "size_t newlen"
|
|
.Ft int
|
|
.Fn sysctlbyname "const char *sname" "void *oldp" "size_t *oldlenp" \
|
|
"const void *newp" "size_t newlen"
|
|
.Ft int
|
|
.Fn sysctlgetmibinfo "const char *sname" "int *name" "u_int *namelenp" \
|
|
"char *cname" "size_t *csz" "struct sysctlnode **rnode" "int v"
|
|
.Ft int
|
|
.Fn sysctlnametomib "const char *sname" "int *name" "size_t *namelenp"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
function retrieves system information and allows processes with
|
|
appropriate privileges to set system information.
|
|
The information available from
|
|
.Nm
|
|
consists of integers, strings, and tables.
|
|
Information may be retrieved and set from the command interface
|
|
using the
|
|
.Xr sysctl 8
|
|
utility.
|
|
.Pp
|
|
Unless explicitly noted below,
|
|
.Nm
|
|
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
|
|
.Nm
|
|
are serialized to avoid deadlock.
|
|
.Pp
|
|
The state is described using a ``Management Information Base'' (MIB)
|
|
style name, listed in
|
|
.Fa name ,
|
|
which is a
|
|
.Fa namelen
|
|
length array of integers.
|
|
.Pp
|
|
The
|
|
.Fn 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 different from
|
|
.Fn sysctl .
|
|
.Pp
|
|
The information is copied into the buffer specified by
|
|
.Fa oldp .
|
|
The size of the buffer is given by the location specified by
|
|
.Fa 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,
|
|
.Fa oldp
|
|
and
|
|
.Fa oldlenp
|
|
should be set to
|
|
.Dv NULL .
|
|
.Pp
|
|
The size of the available data can be determined by calling
|
|
.Nm
|
|
with a
|
|
.Dv NULL
|
|
parameter for
|
|
.Fa oldp .
|
|
The size of the available data will be returned in the location pointed to by
|
|
.Fa 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.
|
|
.Pp
|
|
To set a new value,
|
|
.Fa newp
|
|
is set to point to a buffer of length
|
|
.Fa newlen
|
|
from which the requested value is to be taken.
|
|
If a new value is not to be set,
|
|
.Fa newp
|
|
should be set to
|
|
.Dv NULL
|
|
and
|
|
.Fa newlen
|
|
set to 0.
|
|
.Pp
|
|
The
|
|
.Fn sysctlnametomib
|
|
function can be used to map the string representation of a MIB entry
|
|
to the numeric version.
|
|
The
|
|
.Fa name
|
|
argument should point to an array of integers large enough to hold the
|
|
MIB, and
|
|
.Fa namelenp
|
|
should indicate the number of integer slots available.
|
|
Following a successful translation, the size_t indicated by
|
|
.Fa namelenp
|
|
will be changed to show the number of slots consumed.
|
|
.Pp
|
|
The
|
|
.Fn sysctlgetmibinfo
|
|
function performs name translation similar to
|
|
.Fn sysctlnametomib ,
|
|
but also canonicalizes the name (or returns the first erroneous token
|
|
from the string being parsed) into the space indicated by
|
|
.Fa cname
|
|
and
|
|
.Fa csz .
|
|
.Fa csz
|
|
should indicate the size of the buffer pointed to by
|
|
.Fa cname
|
|
and on return, will indicate the size of the returned string including
|
|
the trailing
|
|
.Sq nul
|
|
character.
|
|
.Pp
|
|
The
|
|
.Fa rnode
|
|
and
|
|
.Fa v
|
|
arguments to
|
|
.Fn 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
|
|
.Fa rnode
|
|
is
|
|
.Dv NULL ,
|
|
.Fn 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
|
|
.Fa v
|
|
argument is ignored in this case.
|
|
If
|
|
.Fa rnode
|
|
is not
|
|
.Dv NULL
|
|
but the pointer it references is, on a successful return,
|
|
.Fa rnode
|
|
will be adjusted to point to a copy of the terminal node.
|
|
The
|
|
.Fa v
|
|
argument indicates which version of the
|
|
.Nm
|
|
node structure the caller wants.
|
|
The application must later
|
|
.Fn free
|
|
this copy.
|
|
If neither
|
|
.Fa rnode
|
|
nor the pointer it references are
|
|
.Dv 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 performed, and the value given by
|
|
.Fa v
|
|
must agree with the version indicated by the tree.
|
|
It is recommended that applications always use
|
|
.Dv SYSCTL_VERSION
|
|
as the value for
|
|
.Fa v ,
|
|
as defined in the include file
|
|
.Pa sys/sysctl.h .
|
|
.Pp
|
|
The numeric and text names of sysctl variables are described in
|
|
.Xr sysctl 7 .
|
|
The numeric names are defined as preprocessor macros.
|
|
The top level names are defined with a CTL_ prefix in
|
|
.In sys/sysctl.h .
|
|
The next and subsequent levels down have different prefixes for each
|
|
subtree.
|
|
.Pp
|
|
For example, the following retrieves the maximum number of processes allowed
|
|
in the system - the
|
|
.Li kern.maxproc
|
|
variable:
|
|
.Bd -literal -offset indent -compact
|
|
int mib[2], maxproc;
|
|
size_t len;
|
|
.sp
|
|
mib[0] = CTL_KERN;
|
|
mib[1] = KERN_MAXPROC;
|
|
len = sizeof(maxproc);
|
|
sysctl(mib, 2, \*[Am]maxproc, \*[Am]len, NULL, 0);
|
|
.Ed
|
|
.sp
|
|
To retrieve the standard search path for the system utilities -
|
|
.Li user.cs_path :
|
|
.Bd -literal -offset indent -compact
|
|
int mib[2];
|
|
size_t len;
|
|
char *p;
|
|
.sp
|
|
mib[0] = CTL_USER;
|
|
mib[1] = USER_CS_PATH;
|
|
sysctl(mib, 2, NULL, \*[Am]len, NULL, 0);
|
|
p = malloc(len);
|
|
sysctl(mib, 2, p, \*[Am]len, NULL, 0);
|
|
.Ed
|
|
.Sh DYNAMIC OPERATIONS
|
|
Several meta-identifiers are provided to perform operations on the
|
|
.Nm
|
|
tree itself, or support alternate means of accessing the data
|
|
instrumented by the
|
|
.Nm
|
|
tree.
|
|
.Bl -column CTLXCREATESYMXXX
|
|
.It Sy Name Description
|
|
.It CTL\_QUERY Retrieve a mapping of names to numbers below a given node
|
|
.It CTL\_CREATE Create a new node
|
|
.It CTL\_CREATESYM Create a new node by its kernel symbol
|
|
.It CTL\_DESTROY Destroy a node
|
|
.It CTL\_DESCRIBE Retrieve node descriptions
|
|
.El
|
|
.Pp
|
|
The core interface to all of these meta-functions is the structure
|
|
that the kernel uses to describe the tree internally, as defined in
|
|
.In sys/sysctl.h
|
|
as:
|
|
.Pp
|
|
.Bd -literal
|
|
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
|
|
.Ed
|
|
.Pp
|
|
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:
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
struct sysctlnode query, vfs[128];
|
|
int mib[2];
|
|
size_t len;
|
|
.sp
|
|
mib[0] = CTL_VFS;
|
|
mib[1] = CTL_QUERY;
|
|
memset(\*[Am]query, 0, sizeof(query));
|
|
query.sysctl_flags = SYSCTL_VERSION;
|
|
len = sizeof(vfs);
|
|
sysctl(mib, 2, \*[Am]vfs[0], \*[Am]len, \*[Am]query, sizeof(query));
|
|
.Ed
|
|
.Pp
|
|
Note that a reference to an empty node with
|
|
.Fa sysctl_flags
|
|
set to
|
|
.Dv 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.
|
|
.Pp
|
|
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
|
|
.Fa new
|
|
and
|
|
.Fa newlen
|
|
arguments.
|
|
If valid values for
|
|
.Fa old
|
|
and
|
|
.Fa 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.
|
|
.Pp
|
|
The minimum requirements for creating a node are setting the
|
|
.Fa sysctl_flags
|
|
to indicate the new node's type,
|
|
.Fa sysctl_num
|
|
to either the new node's number (or CTL_CREATE or CTL_CREATESYM if a
|
|
dynamically allocated MIB number is acceptable),
|
|
.Fa sysctl_size
|
|
to the size of the data to be instrumented (which must agree with the
|
|
given type), and
|
|
.Fa sysctl_name
|
|
must be set to the new node's name.
|
|
Nodes that are not of type
|
|
.Dq node
|
|
must also have some description of the data to be instrumented, which
|
|
will vary depending on what is to be instrumented.
|
|
.Pp
|
|
If existing kernel data is to be covered by this new node, its address
|
|
should be given in
|
|
.Fa sysctl_data
|
|
or, if CTL_CREATESYM is used,
|
|
.Fa 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
|
|
.Fa sysctl_idata
|
|
or
|
|
.Fa sysctl_qdata ,
|
|
respectively, along with the SYSCTL_IMMEDIATE flag being set, or
|
|
.Fa 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.
|
|
.Pp
|
|
The
|
|
.Fa sysctl_csize ,
|
|
.Fa sysctl_clen ,
|
|
.Fa sysctl_child ,
|
|
.Fa sysctl_parent ,
|
|
and
|
|
.Fa sysctl_alias
|
|
members are used by the kernel to link the tree together and must be
|
|
.Dv NULL
|
|
or 0.
|
|
Nodes created in this manner cannot have helper functions, so
|
|
.Fa sysctl_func
|
|
must also be
|
|
.Dv NULL .
|
|
If the
|
|
.Fa 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.
|
|
.Pp
|
|
This example creates a new subtree and adds a node to it that controls the
|
|
.Fa audiodebug
|
|
kernel variable, thereby making it tunable at at any time, without
|
|
needing to use
|
|
.Xr ddb 4
|
|
or
|
|
.Xr kvm 3
|
|
to alter the kernel's memory directly.
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
struct sysctlnode node;
|
|
int mib[2];
|
|
size_t len;
|
|
.sp
|
|
mib[0] = CTL_CREATE; /* create at top-level */
|
|
len = sizeof(node);
|
|
memset(\*[Am]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(\*[Am]mib[0], 1, \*[Am]node, \*[Am]len, \*[Am]node, len);
|
|
.sp
|
|
mib[0] = node.sysctl_num; /* use new MIB number */
|
|
mib[1] = CTL_CREATESYM; /* create at second level */
|
|
len = sizeof(node);
|
|
memset(\*[Am]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(\*[Am]mib[0], 2, NULL, NULL, \*[Am]node, len);
|
|
.Ed
|
|
.Pp
|
|
The process for deleting nodes is similar, but less data needs to
|
|
be supplied.
|
|
Only the
|
|
.Fa sysctl_num
|
|
field
|
|
needs to be filled in; almost all other fields must be left blank.
|
|
The
|
|
.Fa sysctl_name
|
|
and/or
|
|
.Fa 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
|
|
.Fa old
|
|
and
|
|
.Fa oldlenp
|
|
are supplied and a node is deleted, a copy of what was in the MIB tree
|
|
will be returned.
|
|
.Pp
|
|
This sample code shows the deletion of the two nodes created in the
|
|
above example:
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
int mib[2];
|
|
.sp
|
|
len = sizeof(node);
|
|
memset(\*[Am]node, 0, len);
|
|
node.sysctl_flags = SYSCTL_VERSION;
|
|
.sp
|
|
mib[0] = 3214; /* assumed number for "local" */
|
|
mib[1] = CTL_DESTROY;
|
|
node.sysctl_num = 3215; /* assumed number for "audiodebug" */
|
|
sysctl(\*[Am]mib[0], 2, NULL, NULL, \*[Am]node, len);
|
|
.sp
|
|
mib[0] = CTL_DESTROY;
|
|
node.sysctl_num = 3214; /* now deleting "local" */
|
|
sysctl(\*[Am]mib[0], 1, NULL, NULL, \*[Am]node, len);
|
|
.Ed
|
|
.Pp
|
|
Descriptions of each of the nodes can also be retrieved, if they are
|
|
available.
|
|
Descriptions can be retrieved in bulk at each level or on a per-node
|
|
basis.
|
|
The layout of the buffer 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
|
|
.Sq nul
|
|
character.
|
|
Nodes that have no description or where the description is not
|
|
available are indicated by an empty string.
|
|
The
|
|
.Fa descr_ver
|
|
will match the
|
|
.Fa sysctl_ver
|
|
value for a given node, so that descriptions for nodes whose number
|
|
have been recycled can be detected and ignored or discarded.
|
|
.Pp
|
|
.Bd -literal
|
|
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 */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fn NEXT_DESCR
|
|
macro can be used to skip to the next description in the retrieved
|
|
list.
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
struct sysctlnode desc;
|
|
struct sysctldesc *d;
|
|
char buf[1024];
|
|
int mib[2];
|
|
size_t len;
|
|
.sp
|
|
/* retrieve kern-level descriptions */
|
|
mib[0] = CTL_KERN;
|
|
mib[1] = CTL_DESCRIBE;
|
|
d = (struct sysctldesc *)\*[Am]buf[0];
|
|
len = sizeof(buf);
|
|
sysctl(mib, 2, d, \*[Am]len, NULL, 0);
|
|
while ((caddr_t)d \*[Lt] (caddr_t)\*[Am]buf[len]) {
|
|
printf("node %d: %.*s\\n", d-\*[Gt]descr_num, d-\*[Gt]descr_len,
|
|
d-\*[Gt]descr_str);
|
|
d = NEXT_DESCR(d);
|
|
}
|
|
.sp
|
|
/* retrieve description for kern.securelevel */
|
|
memset(\*[Am]desc, 0, sizeof(desc));
|
|
desc.sysctl_flags = SYSCTL_VERSION;
|
|
desc.sysctl_num = KERN_SECURELEVEL;
|
|
d = (struct sysctldesc *)\*[Am]buf[0];
|
|
len = sizeof(buf);
|
|
sysctl(mib, 2, d, \*[Am]len, \*[Am]desc, sizeof(desc));
|
|
printf("kern.securelevel: %.*s\\n", d-\*[Gt]descr_len, d-\*[Gt]descr_str);
|
|
.Ed
|
|
.Pp
|
|
Descriptions can also be set as follows, subject to the following rules:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
The kernel securelevel is at zero or lower
|
|
.It
|
|
The caller has super-user privileges
|
|
.It
|
|
The node does not currently have a description
|
|
.It
|
|
The node is not marked as
|
|
.Dq permanent
|
|
.El
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
struct sysctlnode desc;
|
|
int mib[2];
|
|
.sp
|
|
/* presuming the given top-level node was just added... */
|
|
mib[0] = 3214; /* mib numbers taken from previous examples */
|
|
mib[1] = CTL_DESCRIBE;
|
|
memset(\*[Am]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, \*[Am]desc, sizeof(desc));
|
|
.Ed
|
|
.Pp
|
|
Upon successfully setting a description, the new description will be
|
|
returned in the space indicated by the
|
|
.Fa oldp
|
|
and
|
|
.Fa oldlenp
|
|
arguments.
|
|
.Pp
|
|
The
|
|
.Fa sysctl_flags
|
|
field in the struct sysctlnode contains the sysctl version, node type
|
|
information, and a number of flags.
|
|
The macros
|
|
.Fn SYSCTL_VERS ,
|
|
.Fn SYSCTL_TYPE ,
|
|
and
|
|
.Fn SYSCTL_FLAGS
|
|
can be used to access the different fields.
|
|
Valid flags are:
|
|
.Bl -column CTLFLAGXPERMANENTXXX
|
|
.It Sy Name Description
|
|
.It CTLFLAG\_READONLY Node is read-only
|
|
.It CTLFLAG\_READWRITE Node is writable by the superuser
|
|
.It CTLFLAG\_ANYWRITE Node is writable by anyone
|
|
.It CTLFLAG\_PRIVATE Node is readable only by the superuser
|
|
.It CTLFLAG\_PERMANENT Node cannot be removed (cannot be set by
|
|
processes)
|
|
.It CTLFLAG\_OWNDATA Node owns data and does not instrument
|
|
existing data
|
|
.It CTLFLAG\_IMMEDIATE Node contains instrumented data and does not
|
|
instrument existing data
|
|
.It CTLFLAG\_HEX Node's contents should be displayed in a hexadecimal
|
|
form
|
|
.It CTLFLAG\_ROOT Node is the root of a tree (cannot be set at
|
|
any time)
|
|
.It CTLFLAG\_ANYNUMBER Node matches any MIB number (cannot be set by
|
|
processes)
|
|
.It CTLFLAG\_HIDDEN Node not displayed by default
|
|
.It CTLFLAG\_ALIAS Node refers to a sibling node (cannot be set
|
|
by processes)
|
|
.It CTLFLAG\_OWNDESC Node owns its own description string space
|
|
.El
|
|
.Sh RETURN VALUES
|
|
If the call to
|
|
.Nm
|
|
is successful, 0 is returned.
|
|
Otherwise \-1 is returned and
|
|
.Va errno
|
|
is set appropriately.
|
|
.Sh FILES
|
|
.Bl -tag -width \*[Lt]netinet6/udp6Xvar.h\*[Gt] -compact
|
|
.It Aq Pa sys/sysctl.h
|
|
definitions for top level identifiers, second level kernel and hardware
|
|
identifiers, and user level identifiers
|
|
.It Aq Pa sys/socket.h
|
|
definitions for second level network identifiers
|
|
.It Aq Pa sys/gmon.h
|
|
definitions for third level profiling identifiers
|
|
.It Aq Pa uvm/uvm_param.h
|
|
definitions for second level virtual memory identifiers
|
|
.It Aq Pa netinet/in.h
|
|
definitions for third level IPv4/v6 identifiers and
|
|
fourth level IPv4/v6 identifiers
|
|
.It Aq Pa netinet/icmp_var.h
|
|
definitions for fourth level ICMP identifiers
|
|
.It Aq Pa netinet/icmp6.h
|
|
definitions for fourth level ICMPv6 identifiers
|
|
.It Aq Pa netinet/tcp_var.h
|
|
definitions for fourth level TCP identifiers
|
|
.It Aq Pa netinet/udp_var.h
|
|
definitions for fourth level UDP identifiers
|
|
.It Aq Pa netinet6/udp6_var.h
|
|
definitions for fourth level IPv6 UDP identifiers
|
|
.It Aq Pa netinet6/ipsec.h
|
|
definitions for fourth level IPsec identifiers
|
|
.It Aq Pa netkey/key_var.h
|
|
definitions for third level PF_KEY identifiers
|
|
.It Aq Pa machine/cpu.h
|
|
definitions for second level machdep identifiers
|
|
.El
|
|
.Sh ERRORS
|
|
The following errors may be reported:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EFAULT
|
|
The buffer
|
|
.Fa name ,
|
|
.Fa oldp ,
|
|
.Fa newp ,
|
|
or length pointer
|
|
.Fa oldlenp
|
|
contains an invalid address, or the requested value is temporarily
|
|
unavailable.
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa name
|
|
array is zero or greater than CTL_MAXNAME.
|
|
.It Bq Er EINVAL
|
|
A non-null
|
|
.Fa newp
|
|
is given and its specified length in
|
|
.Fa newlen
|
|
is too large or too small, or the given value is not acceptable for
|
|
the given node.
|
|
.It Bq Er EISDIR
|
|
The
|
|
.Fa name
|
|
array specifies an intermediate rather than terminal name.
|
|
.It Bq Er ENOENT
|
|
The
|
|
.Fa name
|
|
array specifies a node that does not exist in the tree.
|
|
.It Bq Er 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.
|
|
.It Bq Er ENOMEM
|
|
The length pointed to by
|
|
.Fa oldlenp
|
|
is too short to hold the requested value.
|
|
.It Bq Er ENOTDIR
|
|
The
|
|
.Fa name
|
|
array specifies a node below a node that addresses data.
|
|
.It Bq Er ENOTEMPTY
|
|
An attempt was made to destroy a node that still has children.
|
|
.It Bq Er EOPNOTSUPP
|
|
The
|
|
.Fa name
|
|
array specifies a value that is unknown or a meta-operation was
|
|
attempted that the requested node does not support.
|
|
.It Bq Er EPERM
|
|
An attempt is made to set a read-only value.
|
|
.It Bq Er EPERM
|
|
A process without appropriate privilege attempts to set a value or to
|
|
create or destroy a node.
|
|
.It Bq Er EPERM
|
|
An attempt to change a value protected by the current kernel security
|
|
level is made.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr sysctl 7 ,
|
|
.Xr sysctl 8 ,
|
|
.Xr secmodel_securelevel 9
|
|
.\" .Xr sysctl 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
function first appeared in
|
|
.Bx 4.4 .
|