Author: jhb
Date: Tue Jun 11 22:57:25 2019
New Revision: 348969
URL: https://svnweb.freebsd.org/changeset/base/348969
Log:
Document sysctl nodes that translate their values.
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
Modified:
head/share/man/man9/Makefile
head/share/man/man9/sysctl.9
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Tue Jun 11 22:41:39 2019
(r348968)
+++ head/share/man/man9/Makefile Tue Jun 11 22:57:25 2019
(r348969)
@@ -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 \
Modified: head/share/man/man9/sysctl.9
==============================================================================
--- head/share/man/man9/sysctl.9 Tue Jun 11 22:41:39 2019
(r348968)
+++ head/share/man/man9/sysctl.9 Tue Jun 11 22:57:25 2019
(r348969)
@@ -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 str
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
_______________________________________________
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
