From seggers@semyam.dinoco.de  Mon Sep 21 13:49:22 1998
Received: from tim.xenologics.com (tim.xenologics.com [194.77.5.24])
          by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id NAA01993
          for <FreeBSD-gnats-submit@freebsd.org>; Mon, 21 Sep 1998 13:49:08 -0700 (PDT)
          (envelope-from seggers@semyam.dinoco.de)
Received: (from uucp@localhost)
	by tim.xenologics.com (8.8.5/8.8.8) with UUCP id WAA26485
	for FreeBSD-gnats-submit@freebsd.org; Mon, 21 Sep 1998 22:48:29 +0200 (MET DST)
Received: (from seggers@localhost)
	by semyam.dinoco.de (8.9.1/8.8.8) id WAA06312;
	Mon, 21 Sep 1998 22:45:38 +0200 (CEST)
	(envelope-from seggers)
Message-Id: <199809212045.WAA06312@semyam.dinoco.de>
Date: Mon, 21 Sep 1998 22:45:38 +0200 (CEST)
From: Stefan Eggers <seggers@semyam.dinoco.de>
Reply-To: seggers@semyam.dinoco.de
To: FreeBSD-gnats-submit@freebsd.org
Cc: seggers@semyam.dinoco.de
Subject: Some sysctl descriptions for the kernel
X-Send-Pr-Version: 3.2

>Number:         8015
>Category:       kern
>Synopsis:       [patch] Some sysctl descriptions for the kernel
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    nbm
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Mon Sep 21 13:50:00 PDT 1998
>Closed-Date:    Thu Jun 19 22:05:39 PDT 2003
>Last-Modified:  Thu Jun 19 22:05:39 PDT 2003
>Originator:     Stefan Eggers
>Release:        FreeBSD 3.0-BETA i386
>Organization:
none
>Environment:

	-current from Sunday.

>Description:

	Seeing a commit message asking for descriptions on new sysctl
entries I thought I might add some, too.  I choose the ones I could
identify right away and knew what they were doing.

>How-To-Repeat:

>Fix:
	
	This is untested but I think it will work.  Unfortunately we
don't have a tool to list the comments, yet so one can't really test
them anyway.  :-(

Index: kern_acct.c
===================================================================
RCS file: /usr2/FreeBSD/CVSROOT/src/sys/kern/kern_acct.c,v
retrieving revision 1.19
diff -u -r1.19 kern_acct.c
--- kern_acct.c	1998/06/05 21:44:19	1.19
+++ kern_acct.c	1998/09/21 20:29:11
@@ -93,15 +93,15 @@
  */
 static int acctsuspend = 2;	/* stop accounting when < 2% free space left */
 SYSCTL_INT(_kern, OID_AUTO, acct_suspend, CTLFLAG_RW,
-	&acctsuspend, 0, "");
+	&acctsuspend, 0, "percentage of free disk space below which accounting stops");
 
 static int acctresume = 4;	/* resume when free space risen to > 4% */
 SYSCTL_INT(_kern, OID_AUTO, acct_resume, CTLFLAG_RW,
-	&acctresume, 0, "");
+	&acctresume, 0, "percentage of free disk space above which accounting resumes");
 
 static int acctchkfreq = 15;	/* frequency (in seconds) to check space */
 SYSCTL_INT(_kern, OID_AUTO, acct_chkfreq, CTLFLAG_RW,
-	&acctchkfreq, 0, "");
+	&acctchkfreq, 0, "frequency for checking the free space");
 
 /*
  * Accounting system call.  Written based on the specification and
Index: kern_descrip.c
===================================================================
RCS file: /usr2/FreeBSD/CVSROOT/src/sys/kern/kern_descrip.c,v
retrieving revision 1.55
diff -u -r1.55 kern_descrip.c
--- kern_descrip.c	1998/07/29 17:38:13	1.55
+++ kern_descrip.c	1998/09/21 20:31:58
@@ -1157,9 +1157,9 @@
 	0, 0, sysctl_kern_file, "S,file", "");
 
 SYSCTL_INT(_kern, KERN_MAXFILESPERPROC, maxfilesperproc,
-	CTLFLAG_RW, &maxfilesperproc, 0, "");
+	CTLFLAG_RW, &maxfilesperproc, 0, "limit on number of open files per process");
 
-SYSCTL_INT(_kern, KERN_MAXFILES, maxfiles, CTLFLAG_RW, &maxfiles, 0, "");
+SYSCTL_INT(_kern, KERN_MAXFILES, maxfiles, CTLFLAG_RW, &maxfiles, 0, "limit on number of open files in system");
 
 static fildesc_devsw_installed = 0;
 #ifdef DEVFS
Index: kern_fork.c
===================================================================
RCS file: /usr2/FreeBSD/CVSROOT/src/sys/kern/kern_fork.c,v
retrieving revision 1.51
diff -u -r1.51 kern_fork.c
--- kern_fork.c	1998/01/22 17:29:46	1.51
+++ kern_fork.c	1998/09/21 20:38:20
@@ -67,7 +67,7 @@
 #else
 static int	fast_vfork = 1;
 #endif
-SYSCTL_INT(_kern, OID_AUTO, fast_vfork, CTLFLAG_RW, &fast_vfork, 0, "");
+SYSCTL_INT(_kern, OID_AUTO, fast_vfork, CTLFLAG_RW, &fast_vfork, 0, "flag to indicate whether we have a fast vfork()");
 
 /*
  * These are the stuctures used to create a callout list for things to do
Index: kern_mib.c
===================================================================
RCS file: /usr2/FreeBSD/CVSROOT/src/sys/kern/kern_mib.c,v
retrieving revision 1.16
diff -u -r1.16 kern_mib.c
--- kern_mib.c	1998/08/31 08:41:52	1.16
+++ kern_mib.c	1998/09/21 20:39:32
@@ -84,10 +84,10 @@
 extern int osreldate;
 SYSCTL_INT(_kern, KERN_OSRELDATE, osreldate, CTLFLAG_RD, &osreldate, 0, "");
 
-SYSCTL_INT(_kern, KERN_MAXPROC, maxproc, CTLFLAG_RD, &maxproc, 0, "");
+SYSCTL_INT(_kern, KERN_MAXPROC, maxproc, CTLFLAG_RD, &maxproc, 0, "limit on number of processes in system");
 
 SYSCTL_INT(_kern, KERN_MAXPROCPERUID, maxprocperuid,
-	CTLFLAG_RW, &maxprocperuid, 0, "");
+	CTLFLAG_RW, &maxprocperuid, 0, "limit on number of processes per user id");
 
 SYSCTL_INT(_kern, KERN_ARGMAX, argmax, CTLFLAG_RD, 0, ARG_MAX, "");
 
@@ -95,7 +95,7 @@
 
 SYSCTL_INT(_kern, KERN_NGROUPS, ngroups, CTLFLAG_RD, 0, NGROUPS_MAX, "");
 
-SYSCTL_INT(_kern, KERN_JOB_CONTROL, job_control, CTLFLAG_RD, 0, 1, "");
+SYSCTL_INT(_kern, KERN_JOB_CONTROL, job_control, CTLFLAG_RD, 0, 1, "flag to indicate whether we have job control");
 
 #ifdef _POSIX_SAVED_IDS
 SYSCTL_INT(_kern, KERN_SAVED_IDS, saved_ids, CTLFLAG_RD, 0, 1, "");
@@ -109,14 +109,14 @@
 	CTLFLAG_RW, kernelname, sizeof kernelname, "");
 
 #ifdef SMP
-SYSCTL_INT(_hw, HW_NCPU, ncpu, CTLFLAG_RD, &mp_ncpus, 0, "");
+SYSCTL_INT(_hw, HW_NCPU, ncpu, CTLFLAG_RD, &mp_ncpus, 0, "number of CPU's");
 #else
-SYSCTL_INT(_hw, HW_NCPU, ncpu, CTLFLAG_RD, 0, 1, "");
+SYSCTL_INT(_hw, HW_NCPU, ncpu, CTLFLAG_RD, 0, 1, "number of CPU's");
 #endif
 
-SYSCTL_INT(_hw, HW_BYTEORDER, byteorder, CTLFLAG_RD, 0, BYTE_ORDER, "");
+SYSCTL_INT(_hw, HW_BYTEORDER, byteorder, CTLFLAG_RD, 0, BYTE_ORDER, "the hardware's byte ordering");
 
-SYSCTL_INT(_hw, HW_PAGESIZE, pagesize, CTLFLAG_RD, 0, PAGE_SIZE, "");
+SYSCTL_INT(_hw, HW_PAGESIZE, pagesize, CTLFLAG_RD, 0, PAGE_SIZE, "the hardware's page size");
 
 static char	machine_arch[] = MACHINE_ARCH;
 SYSCTL_STRING(_hw, HW_MACHINE_ARCH, machine_arch, CTLFLAG_RD,
@@ -125,7 +125,7 @@
 char hostname[MAXHOSTNAMELEN];
 
 SYSCTL_STRING(_kern, KERN_HOSTNAME, hostname, CTLFLAG_RW,
-	hostname, sizeof(hostname), "");
+	hostname, sizeof(hostname), "the machine's hostname");
 
 int securelevel = -1;
 
@@ -145,7 +145,7 @@
 }
 
 SYSCTL_PROC(_kern, KERN_SECURELVL, securelevel, CTLTYPE_INT|CTLFLAG_RW,
-	0, 0, sysctl_kern_securelvl, "I", "");
+	0, 0, sysctl_kern_securelvl, "I", "the secure level");
 
 char domainname[MAXHOSTNAMELEN];
 SYSCTL_STRING(_kern, KERN_NISDOMAINNAME, domainname, CTLFLAG_RW,
>Release-Note:
>Audit-Trail:

From: Poul-Henning Kamp <phk@critter.freebsd.dk>
To: seggers@semyam.dinoco.de
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: kern/8015: Some sysctl descriptions for the kernel 
Date: Thu, 01 Oct 1998 10:24:17 +0200

 >	Seeing a commit message asking for descriptions on new sysctl
 >entries I thought I might add some, too.  I choose the ones I could
 >identify right away and knew what they were doing.
 
 >	This is untested but I think it will work.  Unfortunately we
 >don't have a tool to list the comments, yet so one can't really test
 >them anyway.  :-(
 
 That was actually my dream at one point, the comment would be in 
 SGML and some tool would walk all over the kernel and construct
 some doc from that.
 
 Any takers ?
 
 --
 Poul-Henning Kamp             FreeBSD coreteam member
 phk@FreeBSD.ORG               "Real hackers run -current on their laptop."
 "ttyv0" -- What UNIX calls a $20K state-of-the-art, 3D, hi-res color terminal
State-Changed-From-To: open->suspended 
State-Changed-By: nbm 
State-Changed-When: Mon Jun 26 06:52:37 PDT 2000 
State-Changed-Why:  
Added descriptions in 1.25 of kern_acct.c and 1.77 or kern_fork.c, and 
suspending until I backport. 


Responsible-Changed-From-To: freebsd-bugs->nbm 
Responsible-Changed-By: nbm 
Responsible-Changed-When: Mon Jun 26 06:52:37 PDT 2000 
Responsible-Changed-Why:  
I added them to -CURRENT, sometime I should MFC it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=8015 
State-Changed-From-To: suspended->closed 
State-Changed-By: jmg 
State-Changed-When: Thu Jun 19 22:04:46 PDT 2003 
State-Changed-Why:  
all the SYSCTL's mentioned have descriptions now. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=8015 
>Unformatted:
