From owner-svn-src-stable@freebsd.org Mon Aug 19 17:27:08 2019 Return-Path: Delivered-To: svn-src-stable@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 19ED1CC44D; Mon, 19 Aug 2019 17:27:08 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 46C17v6nDJz44d7; Mon, 19 Aug 2019 17:27:07 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id CA4AD1E030; Mon, 19 Aug 2019 17:27:07 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x7JHR7p8082539; Mon, 19 Aug 2019 17:27:07 GMT (envelope-from jhb@FreeBSD.org) Received: (from jhb@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x7JHR70h082537; Mon, 19 Aug 2019 17:27:07 GMT (envelope-from jhb@FreeBSD.org) Message-Id: <201908191727.x7JHR70h082537@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: jhb set sender to jhb@FreeBSD.org using -f From: John Baldwin Date: Mon, 19 Aug 2019 17:27:07 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-11@freebsd.org Subject: svn commit: r351222 - in stable: 11/share/man/man9 12/share/man/man9 X-SVN-Group: stable-11 X-SVN-Commit-Author: jhb X-SVN-Commit-Paths: in stable: 11/share/man/man9 12/share/man/man9 X-SVN-Commit-Revision: 351222 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-stable@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for all the -stable branches of the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 Aug 2019 17:27:08 -0000 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/11/share/man/man9/Makefile stable/11/share/man/man9/sysctl.9 Directory Properties: stable/11/ (props changed) Changes in other areas also in this revision: Modified: stable/12/share/man/man9/Makefile stable/12/share/man/man9/sysctl.9 Directory Properties: stable/12/ (props changed) Modified: stable/11/share/man/man9/Makefile ============================================================================== --- stable/11/share/man/man9/Makefile Mon Aug 19 17:26:04 2019 (r351221) +++ stable/11/share/man/man9/Makefile Mon Aug 19 17:27:06 2019 (r351222) @@ -1772,6 +1772,7 @@ MLINKS+=sysctl.9 SYSCTL_DECL.9 \ sysctl.9 SYSCTL_PARENT.9 \ sysctl.9 SYSCTL_INT.9 \ sysctl.9 SYSCTL_LONG.9 \ + sysctl.9 sysctl_msec_to_ticks.9 \ sysctl.9 SYSCTL_NODE.9 \ sysctl.9 SYSCTL_OPAQUE.9 \ sysctl.9 SYSCTL_PROC.9 \ Modified: stable/11/share/man/man9/sysctl.9 ============================================================================== --- stable/11/share/man/man9/sysctl.9 Mon Aug 19 17:26:04 2019 (r351221) +++ stable/11/share/man/man9/sysctl.9 Mon Aug 19 17:27:06 2019 (r351222) @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 16, 2017 +.Dd June 11, 2019 .Dt SYSCTL 9 .Os .Sh NAME @@ -58,6 +58,7 @@ .Nm SYSCTL_PARENT , .Nm SYSCTL_INT , .Nm SYSCTL_LONG , +.Nm sysctl_msec_to_ticks , .Nm SYSCTL_NODE , .Nm SYSCTL_OPAQUE , .Nm SYSCTL_PROC , @@ -337,6 +338,8 @@ .Fc .Fn SYSCTL_INT 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_OPAQUE parent number name ctlflags ptr len format descr .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr @@ -356,6 +359,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 @@ -473,6 +477,38 @@ structures .It Fa descr A pointer to a textual description of the OID. .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