Changeset View
Changeset View
Standalone View
Standalone View
head/share/man/man9/sysctl.9
Show All 19 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" 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 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd February 25, 2019 | .Dd June 11, 2019 | ||||
.Dt SYSCTL 9 | .Dt SYSCTL 9 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm SYSCTL_DECL , | .Nm SYSCTL_DECL , | ||||
.Nm SYSCTL_ADD_BOOL , | .Nm SYSCTL_ADD_BOOL , | ||||
.Nm SYSCTL_ADD_COUNTER_U64 , | .Nm SYSCTL_ADD_COUNTER_U64 , | ||||
.Nm SYSCTL_ADD_COUNTER_U64_ARRAY , | .Nm SYSCTL_ADD_COUNTER_U64_ARRAY , | ||||
.Nm SYSCTL_ADD_INT , | .Nm SYSCTL_ADD_INT , | ||||
Show All 28 Lines | |||||
.Nm SYSCTL_NODE_CHILDREN , | .Nm SYSCTL_NODE_CHILDREN , | ||||
.Nm SYSCTL_PARENT , | .Nm SYSCTL_PARENT , | ||||
.Nm SYSCTL_BOOL , | .Nm SYSCTL_BOOL , | ||||
.Nm SYSCTL_COUNTER_U64 , | .Nm SYSCTL_COUNTER_U64 , | ||||
.Nm SYSCTL_COUNTER_U64_ARRAY , | .Nm SYSCTL_COUNTER_U64_ARRAY , | ||||
.Nm SYSCTL_INT , | .Nm SYSCTL_INT , | ||||
.Nm SYSCTL_INT_WITH_LABEL , | .Nm SYSCTL_INT_WITH_LABEL , | ||||
.Nm SYSCTL_LONG , | .Nm SYSCTL_LONG , | ||||
.Nm sysctl_msec_to_ticks , | |||||
.Nm SYSCTL_NODE , | .Nm SYSCTL_NODE , | ||||
.Nm SYSCTL_NODE_WITH_LABEL , | .Nm SYSCTL_NODE_WITH_LABEL , | ||||
.Nm SYSCTL_OPAQUE , | .Nm SYSCTL_OPAQUE , | ||||
.Nm SYSCTL_PROC , | .Nm SYSCTL_PROC , | ||||
.Nm SYSCTL_QUAD , | .Nm SYSCTL_QUAD , | ||||
.Nm SYSCTL_ROOT_NODE , | .Nm SYSCTL_ROOT_NODE , | ||||
.Nm SYSCTL_S8 , | .Nm SYSCTL_S8 , | ||||
.Nm SYSCTL_S16 , | .Nm SYSCTL_S16 , | ||||
▲ Show 20 Lines • Show All 356 Lines • ▼ Show 20 Lines | |||||
.Fa "struct sysctl_oid *oid" | .Fa "struct sysctl_oid *oid" | ||||
.Fc | .Fc | ||||
.Fn SYSCTL_BOOL parent number name ctlflags ptr val descr | .Fn SYSCTL_BOOL parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_COUNTER_U64 parent number name ctlflags ptr descr | .Fn SYSCTL_COUNTER_U64 parent number name ctlflags ptr descr | ||||
.Fn SYSCTL_COUNTER_U64_ARRAY parent number name ctlflags ptr len descr | .Fn SYSCTL_COUNTER_U64_ARRAY parent number name ctlflags ptr len descr | ||||
.Fn SYSCTL_INT parent number name ctlflags ptr val descr | .Fn SYSCTL_INT parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label | .Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label | ||||
.Fn SYSCTL_LONG parent number name ctlflags ptr val descr | .Fn SYSCTL_LONG parent number name ctlflags ptr val descr | ||||
.Ft int | |||||
.Fn sysctl_msec_to_ticks SYSCTL_HANDLER_ARGS | |||||
.Fn SYSCTL_NODE parent number name ctlflags handler descr | .Fn SYSCTL_NODE parent number name ctlflags handler descr | ||||
.Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label | .Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label | ||||
.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr | .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr | ||||
.Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr | .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr | ||||
.Fn SYSCTL_QUAD parent number name ctlflags ptr val descr | .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_ROOT_NODE number name ctlflags handler descr | .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr | ||||
.Fn SYSCTL_S8 parent number name ctlflags ptr val descr | .Fn SYSCTL_S8 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_S16 parent number name ctlflags ptr val descr | .Fn SYSCTL_S16 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_S32 parent number name ctlflags ptr val descr | .Fn SYSCTL_S32 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_S64 parent number name ctlflags ptr val descr | .Fn SYSCTL_S64 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_SBINTIME_MSEC parent number name ctlflags ptr descr | .Fn SYSCTL_SBINTIME_MSEC parent number name ctlflags ptr descr | ||||
.Fn SYSCTL_SBINTIME_USEC parent number name ctlflags ptr descr | .Fn SYSCTL_SBINTIME_USEC parent number name ctlflags ptr descr | ||||
.Fn SYSCTL_STRING parent number name ctlflags arg len descr | .Fn SYSCTL_STRING parent number name ctlflags arg len descr | ||||
.Fn SYSCTL_CONST_STRING parent number name ctlflags arg descr | .Fn SYSCTL_CONST_STRING parent number name ctlflags arg descr | ||||
.Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr | .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr | ||||
.Fn SYSCTL_U8 parent number name ctlflags ptr val descr | .Fn SYSCTL_U8 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_U16 parent number name ctlflags ptr val descr | .Fn SYSCTL_U16 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_U32 parent number name ctlflags ptr val descr | .Fn SYSCTL_U32 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_U64 parent number name ctlflags ptr val descr | .Fn SYSCTL_U64 parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_UINT parent number name ctlflags ptr val descr | .Fn SYSCTL_UINT parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_ULONG parent number name ctlflags ptr val descr | .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr | .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr | ||||
.Fn SYSCTL_UMA_MAX parent number name ctlflags ptr descr | .Fn SYSCTL_UMA_MAX parent number name ctlflags ptr descr | ||||
.Fn SYSCTL_UMA_CUR parent number name ctlflags ptr descr | .Fn SYSCTL_UMA_CUR parent number name ctlflags ptr descr | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Nm SYSCTL | .Nm SYSCTL | ||||
kernel interface allows dynamic or static creation of | kernel interface allows dynamic or static creation of | ||||
.Xr sysctl 8 | .Xr sysctl 8 | ||||
MIB entries. | MIB entries. | ||||
All static sysctls are automatically destroyed when the module which | All static sysctls are automatically destroyed when the module which | ||||
they are part of is unloaded. | they are part of is unloaded. | ||||
▲ Show 20 Lines • Show All 114 Lines • ▼ Show 20 Lines | |||||
The label acts as a hint that this component's name should not be part | The label acts as a hint that this component's name should not be part | ||||
of the metric's name, | of the metric's name, | ||||
but attached to the metric as a label instead. | but attached to the metric as a label instead. | ||||
.Pp | .Pp | ||||
Labels should only be applied to siblings that are structurally similar | Labels should only be applied to siblings that are structurally similar | ||||
and encode the same type of value, | and encode the same type of value, | ||||
as aggregation is of no use otherwise. | as aggregation is of no use otherwise. | ||||
.El | .El | ||||
.Sh NODE VALUE TYPES | |||||
Most of the macros and functions used to create sysctl nodes export a | |||||
read-only constant or in-kernel variable whose type matches the type | |||||
of the node's value. | |||||
For example, | |||||
.Fn SYSCTL_INT | |||||
reports the raw value of an associated variable of type | |||||
.Vt int . | |||||
However, nodes may also export a value that is a translatation of an internal | |||||
representation. | |||||
.Pp | |||||
The | |||||
.Fn sysctl_msec_to_ticks | |||||
handler can be used with | |||||
.Fn SYSCTL_PROC | |||||
or | |||||
.Fn SYSCTL_ADD_PROC | |||||
to export a millisecond time interval. | |||||
When using this handler, | |||||
the | |||||
.Fa arg2 | |||||
parameter points to an in-kernel variable of type | |||||
.Vt int | |||||
which stores a tick count suitable for use with functions like | |||||
.Xr tsleep 9 . | |||||
The | |||||
.Fn sysctl_msec_to_ticks | |||||
function converts this value to milliseconds when reporting the node's value. | |||||
Similarly, | |||||
.Fn sysctl_msec_to_ticks | |||||
accepts new values in milliseconds and stores an equivalent value in ticks to | |||||
.Fa *arg2 . | |||||
Note that new code should use kernel variables of type | |||||
.Vt sbintime_t | |||||
instead of tick counts. | |||||
.Pp | |||||
The | |||||
.Fn SYSCTL_ADD_SBINTIME_MSEC | |||||
and | |||||
.Fn SYSCTL_ADD_SBINTIME_USEC | |||||
functions and | |||||
.Fn SYSCTL_SBINTIME_MSEC | |||||
and | |||||
.Fn SYSCTL_SBINTIME_USEC | |||||
macros all create nodes which export an in-kernel variable of type | |||||
.Vt sbintime_t . | |||||
These nodes do not export the raw value of the associated variable. | |||||
Instead, they export a 64-bit integer containing a count of either | |||||
milliseconds (the MSEC variants) or microseconds (the USEC variants). | |||||
.Sh CREATING ROOT NODES | .Sh CREATING ROOT NODES | ||||
Sysctl MIBs or OIDs are created in a hierarchical tree. | Sysctl MIBs or OIDs are created in a hierarchical tree. | ||||
The nodes at the bottom of the tree are called root nodes, and have no | The nodes at the bottom of the tree are called root nodes, and have no | ||||
parent OID. | parent OID. | ||||
To create bottom tree nodes the | To create bottom tree nodes the | ||||
.Fn SYSCTL_ROOT_NODE | .Fn SYSCTL_ROOT_NODE | ||||
macro or the | macro or the | ||||
.Fn SYSCTL_ADD_ROOT_NODE | .Fn SYSCTL_ADD_ROOT_NODE | ||||
▲ Show 20 Lines • Show All 420 Lines • Show Last 20 Lines |