d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document sysctl nodes that translate their values.

Browse Source 
This documents the behavior of sysctl_msec_to_ticks and
SYSCTL_{ADD,}_SBINTIME_[UM]SEC.

Reviewed by:	cem
MFC after:	1 week
Sponsored by:	Chelsio Communications
Differential Revision:	https://reviews.freebsd.org/D20596
This commit is contained in:
John Baldwin 2019-06-11 22:57:25 +00:00
parent e65d58a0fe
commit 574b98cbd9
2 changed files with 55 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
share/man/man9/Makefile
View File

@ -2011,6 +2011,7 @@ MLINKS+=sysctl.9 SYSCTL_DECL.9 \
sysctl.9 SYSCTL_INT.9 \
sysctl.9 SYSCTL_INT_WITH_LABEL.9 \
sysctl.9 SYSCTL_LONG.9 \
sysctl.9 sysctl_msec_to_ticks.9 \
sysctl.9 SYSCTL_NODE.9 \
sysctl.9 SYSCTL_NODE_WITH_LABEL.9 \
sysctl.9 SYSCTL_OPAQUE.9 \

55
share/man/man9/sysctl.9
View File

@ -25,7 +25,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd February 25, 2019
.Dd June 11, 2019
.Dt SYSCTL 9
.Os
.Sh NAME
@ -70,6 +70,7 @@
.Nm SYSCTL_INT ,
.Nm SYSCTL_INT_WITH_LABEL ,
.Nm SYSCTL_LONG ,
.Nm sysctl_msec_to_ticks ,
.Nm SYSCTL_NODE ,
.Nm SYSCTL_NODE_WITH_LABEL ,
.Nm SYSCTL_OPAQUE ,
@ -442,6 +443,8 @@
.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_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_WITH_LABEL parent number name ctlflags handler descr label
.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
@ -466,6 +469,7 @@
.Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
.Fn SYSCTL_UMA_MAX parent number name ctlflags ptr descr
.Fn SYSCTL_UMA_CUR parent number name ctlflags ptr descr
.Sh DESCRIPTION
The
.Nm SYSCTL
@ -596,6 +600,55 @@ Labels should only be applied to siblings that are structurally similar
and encode the same type of value,
as aggregation is of no use otherwise.
.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
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