svn commit: r351222 - in stable: 11/share/man/man9 12/share/man/man9

[John Baldwin]

Author: jhb
Date: Mon Aug 19 17:27:06 2019
New Revision: 351222
URL: https://svnweb.freebsd.org/changeset/base/351222

Log:
  MFC 348969: Document sysctl nodes that translate their values.
  
  This documents the behavior of sysctl_msec_to_ticks.
  
  The MFC does not document SYSCTL_{ADD,}_SBINTIME_[UM]SEC since those
  are only present in head.

Modified:
  stable/12/share/man/man9/Makefile
  stable/12/share/man/man9/sysctl.9
Directory Properties:
  stable/12/   (props changed)

Changes in other areas also in this revision:
Modified:
  stable/11/share/man/man9/Makefile
  stable/11/share/man/man9/sysctl.9
Directory Properties:
  stable/11/   (props changed)

Modified: stable/12/share/man/man9/Makefile
==============================================================================
--- stable/12/share/man/man9/Makefile	Mon Aug 19 17:26:04 2019	(r351221)
+++ stable/12/share/man/man9/Makefile	Mon Aug 19 17:27:06 2019	(r351222)
@@ -2021,6 +2021,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: stable/12/share/man/man9/sysctl.9
==============================================================================
--- stable/12/share/man/man9/sysctl.9	Mon Aug 19 17:26:04 2019	(r351221)
+++ stable/12/share/man/man9/sysctl.9	Mon Aug 19 17:27:06 2019	(r351222)
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 1, 2018
+.Dd June 11, 2019
 .Dt SYSCTL 9
 .Os
 .Sh NAME
@@ -60,6 +60,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 ,
@@ -352,6 +353,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
@@ -372,6 +375,7 @@
 .Fn SYSCTL_UINT 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
+
 .Sh DESCRIPTION
 The
 .Nm SYSCTL
@@ -501,6 +505,38 @@ 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 .
 .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