Date: Tue, 11 Jun 2019 22:57:26 +0000 (UTC) From: John Baldwin <jhb@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r348969 - head/share/man/man9 Message-ID: <201906112257.x5BMvQ3f086689@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906112257.x5BMvQ3f086689>