From nobody@FreeBSD.org  Wed Jan 14 14:32:10 2009
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id BD46B10656C8
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 14 Jan 2009 14:32:10 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id AA6AA8FC1A
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 14 Jan 2009 14:32:10 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n0EEW9Pg087052
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 14 Jan 2009 14:32:09 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id n0EEW9Xs087051;
	Wed, 14 Jan 2009 14:32:09 GMT
	(envelope-from nobody)
Message-Id: <200901141432.n0EEW9Xs087051@www.freebsd.org>
Date: Wed, 14 Jan 2009 14:32:09 GMT
From: Hywel Mallett <hywel@hmallett.co.uk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: gjournal man page is missing sysctls
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         130548
>Category:       docs
>Synopsis:       [patch] gjournal(8) man page is missing sysctls
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-geom
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 14 14:40:01 UTC 2009
>Closed-Date:    Mon Jan 31 16:21:54 UTC 2011
>Last-Modified:  Mon Jan 31 16:30:09 UTC 2011
>Originator:     Hywel Mallett
>Release:        7.1
>Organization:
>Environment:
>Description:
gjournal man page is missing descriptions of the sysctls. This is already acknowledged on the man page.
>How-To-Repeat:
man gjournal
>Fix:
See attached patch. It requires some corrections to the SGML, and verification that the content is correct.

Patch attached with submission follows:

--- gjournal.8	2009-01-05 10:52:33.000000000 +0000
+++ gjournal.8.new	2009-01-13 12:36:32.000000000 +0000
@@ -223,6 +223,100 @@
     mount -o async /dev/da0s1d.journal /mnt || \e
     mount /dev/da0s1d /mnt
 .Ed
+.Sh SYSCTLS
+gjournal adds the sysctl level kern.geom.journal
+The string and integer information available
+is detailed below.
+The changeable column shows whether a process with appropriate
+privilege may change the value.
+.Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent
+.It Sy "sysctl name	Type	Changeable"
+.It "debug	integer	yes"
+.It "switch_time	integer	yes"
+.It "force_switch	integer	yes"
+.It "parallel_flushes	integer	yes"
+.It "accept_immediately	integer	yes"
+.It "parallel_copies	integer	yes"
+.It "record_entries	integer	yes"
+.It "optimize	integer	yes"
+.E1
+.Pp
+.B1 -tag -width 6n
+.It Li debug
+Setting a non-zero value enables debugging at various levels. Debug level 1 will record actions at a journal level, relating to journal switches, metadata updates etc. Debug level 2 will record actions at a higher level, relating to the numbers of entries in journals, access requests etc. Debug level 3 will record verbose detail, including insetion of I/Os to the journal.
+.It Li switch_time
+The maximum number of seconds a journal is allowed to remain open before switching to a new journal.
+.It Li force_switch
+Force a journal switch when the journal uses more than N% of the free journal space.
+.It Li parallel_flushes
+The number of flush I/O requests to be sent in parallel when flushing the journal to the data provider.
+.It Li accept_immediately
+The maximum number of I/O requests accepted at the same time.
+.It Li parallel_copies
+The number of copy I/O requests to send in parallel.
+.It Li record_entries
+The maximum number of record entries to allow in a single journal.
+.It Li optimize
+Controls whether entries in a journal will be optimized, by combining overlapping I/Os into a single I/O, and reordering the entries in a journal. This can be disabled by setting the sysctl to 0.
+.E1
+.Ss cache
+The string and integer information available for the cache level
+is detailed below.
+The changeable column shows whether a process with appropriate
+privilege may change the value.
+.Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent
+.It Sy "sysctl name	Type	Changeable"
+.It "used	integer	no"
+.It "limit	integer	yes"
+.It "divisor	integer	no"
+.It "switch	integer	yes"
+.It "misses	integer	yes"
+.It "alloc_failures	integer	yes"
+.E1
+.Pp
+.B1 -tag -width 6n
+.It Li used
+The number of bytes currently allocated to the cache.
+.It Li limit
+The maximum number of bytes to be allocated to the cache.
+.It Li divisor
+Sets the cache size to be used as a proportion of kmem_size. A value of 2 (the default) will cause the cache size to be set to 1/2 of the kmem_size.
+.It Li switch
+Force a journal switch when this percentage of cache has been used.
+.It Li misses
+The number of cache misses, when data has been read, but was not found in the cache.
+.It Li alloc_failures
+The number of times memory failed to be allocated to the cache because the cache limit was hit.
+.E1
+.Ss statistics
+The string and integer information available for the statistics level
+is detailed below.
+The changeable column shows whether a process with appropriate
+privilege may change the value.
+.Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent
+.It Sy "sysctl name     Type    Changeable"
+.It "skipped_bytes       integer yes"
+.It "combined_ios      integer yes"
+.It "switches    integer yes"
+.It "wait_for_copy     integer yes"
+.It "journal_full    integer yes"
+.It "low_mem     integer yes"
+.E1
+.Pp
+.B1 -tag -width 6n
+.It Li skipped_bytes
+The number of bytes skipped.
+.It Li combined_ios
+The number of I/Os which were combined by journal optimization.
+.It Li switches
+The number of journal switches.
+.It Li wait_for_copy
+The number of times the journal switch process had to wait for the previous journal copy to complete.
+.It Li journal_full
+The number of times the journal was almost full, forcing a journal switch.
+.It Li low_mem
+The number of times the low_mem hook was called.
+.E1
 .Sh SEE ALSO
 .Xr geom 4 ,
 .Xr geom 8 ,
@@ -237,7 +331,3 @@
 .Fx 7.0 .
 .Sh AUTHORS
 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
-.Sh BUGS
-Documentation for sysctls
-.Va kern.geom.journal.*
-is missing.


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->pjd 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Jan 27 02:53:35 UTC 2009 
Responsible-Changed-Why:  
Pass this over to Pawel, as the author of gjournal. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=130548 
State-Changed-From-To: open->patched 
State-Changed-By: pjd 
State-Changed-When: wto 17 lut 20:32:58 2009 UTC 
State-Changed-Why:  
Patch committed to HEAD. Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=130548 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/130548: commit references a PR
Date: Tue, 17 Feb 2009 20:30:27 +0000 (UTC)

 Author: pjd
 Date: Tue Feb 17 20:30:17 2009
 New Revision: 188728
 URL: http://svn.freebsd.org/changeset/base/188728
 
 Log:
   Document kern.geom.journal.* sysctls.
   
   PR:		docs/130548
   Submitted by:	Hywel Mallett <hywel@hmallett.co.uk>
   MFC after:	1 week
 
 Modified:
   head/sbin/geom/class/journal/gjournal.8
 
 Modified: head/sbin/geom/class/journal/gjournal.8
 ==============================================================================
 --- head/sbin/geom/class/journal/gjournal.8	Tue Feb 17 19:57:52 2009	(r188727)
 +++ head/sbin/geom/class/journal/gjournal.8	Tue Feb 17 20:30:17 2009	(r188728)
 @@ -1,4 +1,4 @@
 -.\" Copyright (c) 2006-2007 Pawel Jakub Dawidek <pjd@FreeBSD.org>
 +.\" Copyright (c) 2006-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
  .\" All rights reserved.
  .\"
  .\" Redistribution and use in source and binary forms, with or without
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd April 13, 2008
 +.Dd February 17, 2008
  .Dt GJOURNAL 8
  .Os
  .Sh NAME
 @@ -223,6 +223,106 @@ gjournal label da0s1d da0s1e && \e
      mount -o async /dev/da0s1d.journal /mnt || \e
      mount /dev/da0s1d /mnt
  .Ed
 +.Sh SYSCTLS
 +Gjournal adds the sysctl level kern.geom.journal.
 +The string and integer information available is detailed below.
 +The changeable column shows whether a process with appropriate privilege may
 +change the value.
 +.Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent
 +.It Sy "sysctl name	Type	Changeable"
 +.It "debug	integer	yes"
 +.It "switch_time	integer	yes"
 +.It "force_switch	integer	yes"
 +.It "parallel_flushes	integer	yes"
 +.It "accept_immediately	integer	yes"
 +.It "parallel_copies	integer	yes"
 +.It "record_entries	integer	yes"
 +.It "optimize	integer	yes"
 +.El
 +.Pp
 +.Bl -tag -width 6n
 +.It Li debug
 +Setting a non-zero value enables debugging at various levels.
 +Debug level 1 will record actions at a journal level, relating to journal
 +switches, metadata updates etc.
 +Debug level 2 will record actions at a higher level, relating to the numbers of
 +entries in journals, access requests etc.
 +Debug level 3 will record verbose detail, including insertion of I/Os to the
 +journal.
 +.It Li switch_time
 +The maximum number of seconds a journal is allowed to remain open before
 +switching to a new journal.
 +.It Li force_switch
 +Force a journal switch when the journal uses more than N% of the free journal space.
 +.It Li parallel_flushes
 +The number of flush I/O requests to be sent in parallel when flushing the journal to the data provider.
 +.It Li accept_immediately
 +The maximum number of I/O requests accepted at the same time.
 +.It Li parallel_copies
 +The number of copy I/O requests to send in parallel.
 +.It Li record_entries
 +The maximum number of record entries to allow in a single journal.
 +.It Li optimize
 +Controls whether entries in a journal will be optimized, by combining overlapping I/Os into a single I/O, and reordering the entries in a journal. This can be disabled by setting the sysctl to 0.
 +.El
 +.Ss cache
 +The string and integer information available for the cache level
 +is detailed below.
 +The changeable column shows whether a process with appropriate
 +privilege may change the value.
 +.Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent
 +.It Sy "sysctl name	Type	Changeable"
 +.It "used	integer	no"
 +.It "limit	integer	yes"
 +.It "divisor	integer	no"
 +.It "switch	integer	yes"
 +.It "misses	integer	yes"
 +.It "alloc_failures	integer	yes"
 +.El
 +.Pp
 +.Bl -tag -width 6n
 +.It Li used
 +The number of bytes currently allocated to the cache.
 +.It Li limit
 +The maximum number of bytes to be allocated to the cache.
 +.It Li divisor
 +Sets the cache size to be used as a proportion of kmem_size. A value of 2 (the default) will cause the cache size to be set to 1/2 of the kmem_size.
 +.It Li switch
 +Force a journal switch when this percentage of cache has been used.
 +.It Li misses
 +The number of cache misses, when data has been read, but was not found in the cache.
 +.It Li alloc_failures
 +The number of times memory failed to be allocated to the cache because the cache limit was hit.
 +.El
 +.Ss stats
 +The string and integer information available for the statistics level
 +is detailed below.
 +The changeable column shows whether a process with appropriate
 +privilege may change the value.
 +.Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent
 +.It Sy "sysctl name	Type	Changeable"
 +.It "skipped_bytes	integer	yes"
 +.It "combined_ios	integer	yes"
 +.It "switches	integer	yes"
 +.It "wait_for_copy	integer	yes"
 +.It "journal_full	integer	yes"
 +.It "low_mem	integer	yes"
 +.El
 +.Pp
 +.Bl -tag -width 6n
 +.It Li skipped_bytes
 +The number of bytes skipped.
 +.It Li combined_ios
 +The number of I/Os which were combined by journal optimization.
 +.It Li switches
 +The number of journal switches.
 +.It Li wait_for_copy
 +The number of times the journal switch process had to wait for the previous journal copy to complete.
 +.It Li journal_full
 +The number of times the journal was almost full, forcing a journal switch.
 +.It Li low_mem
 +The number of times the low_mem hook was called.
 +.El
  .Sh SEE ALSO
  .Xr geom 4 ,
  .Xr geom 8 ,
 @@ -237,7 +337,3 @@ utility appeared in
  .Fx 7.0 .
  .Sh AUTHORS
  .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 -.Sh BUGS
 -Documentation for sysctls
 -.Va kern.geom.journal.*
 -is missing.
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
Responsible-Changed-From-To: pjd->freebsd-geom 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Thu May 28 22:17:23 UTC 2009 
Responsible-Changed-Why:  
pjd is not actively working on GEOM at the moment. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=130548 
State-Changed-From-To: patched->closed 
State-Changed-By: ae 
State-Changed-When: Mon Jan 31 16:21:24 UTC 2011 
State-Changed-Why:  
Merged to stable/8 and stable/7. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=130548 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/130548: commit references a PR
Date: Mon, 31 Jan 2011 16:20:37 +0000 (UTC)

 Author: ae
 Date: Mon Jan 31 16:20:28 2011
 New Revision: 218133
 URL: http://svn.freebsd.org/changeset/base/218133
 
 Log:
   MFC r188728 by pjd:
     Document kern.geom.journal.* sysctls.
   
     PR:		docs/130548
     Submitted by:	Hywel Mallett <hywel@hmallett.co.uk>
   
   MFC r188729 by pjd:
     Correct the year.
   
     Reported by:	Florian Smeets <flo@kasimir.com>
 
 Modified:
   stable/7/sbin/geom/class/journal/gjournal.8
 Directory Properties:
   stable/7/sbin/geom/class/journal/   (props changed)
 
 Modified: stable/7/sbin/geom/class/journal/gjournal.8
 ==============================================================================
 --- stable/7/sbin/geom/class/journal/gjournal.8	Mon Jan 31 15:52:00 2011	(r218132)
 +++ stable/7/sbin/geom/class/journal/gjournal.8	Mon Jan 31 16:20:28 2011	(r218133)
 @@ -1,4 +1,4 @@
 -.\" Copyright (c) 2006-2007 Pawel Jakub Dawidek <pjd@FreeBSD.org>
 +.\" Copyright (c) 2006-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
  .\" All rights reserved.
  .\"
  .\" Redistribution and use in source and binary forms, with or without
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd April 13, 2008
 +.Dd February 17, 2009
  .Dt GJOURNAL 8
  .Os
  .Sh NAME
 @@ -223,6 +223,106 @@ gjournal label da0s1d da0s1e && \e
      mount -o async /dev/da0s1d.journal /mnt || \e
      mount /dev/da0s1d /mnt
  .Ed
 +.Sh SYSCTLS
 +Gjournal adds the sysctl level kern.geom.journal.
 +The string and integer information available is detailed below.
 +The changeable column shows whether a process with appropriate privilege may
 +change the value.
 +.Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent
 +.It Sy "sysctl name	Type	Changeable"
 +.It "debug	integer	yes"
 +.It "switch_time	integer	yes"
 +.It "force_switch	integer	yes"
 +.It "parallel_flushes	integer	yes"
 +.It "accept_immediately	integer	yes"
 +.It "parallel_copies	integer	yes"
 +.It "record_entries	integer	yes"
 +.It "optimize	integer	yes"
 +.El
 +.Pp
 +.Bl -tag -width 6n
 +.It Li debug
 +Setting a non-zero value enables debugging at various levels.
 +Debug level 1 will record actions at a journal level, relating to journal
 +switches, metadata updates etc.
 +Debug level 2 will record actions at a higher level, relating to the numbers of
 +entries in journals, access requests etc.
 +Debug level 3 will record verbose detail, including insertion of I/Os to the
 +journal.
 +.It Li switch_time
 +The maximum number of seconds a journal is allowed to remain open before
 +switching to a new journal.
 +.It Li force_switch
 +Force a journal switch when the journal uses more than N% of the free journal space.
 +.It Li parallel_flushes
 +The number of flush I/O requests to be sent in parallel when flushing the journal to the data provider.
 +.It Li accept_immediately
 +The maximum number of I/O requests accepted at the same time.
 +.It Li parallel_copies
 +The number of copy I/O requests to send in parallel.
 +.It Li record_entries
 +The maximum number of record entries to allow in a single journal.
 +.It Li optimize
 +Controls whether entries in a journal will be optimized, by combining overlapping I/Os into a single I/O, and reordering the entries in a journal. This can be disabled by setting the sysctl to 0.
 +.El
 +.Ss cache
 +The string and integer information available for the cache level
 +is detailed below.
 +The changeable column shows whether a process with appropriate
 +privilege may change the value.
 +.Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent
 +.It Sy "sysctl name	Type	Changeable"
 +.It "used	integer	no"
 +.It "limit	integer	yes"
 +.It "divisor	integer	no"
 +.It "switch	integer	yes"
 +.It "misses	integer	yes"
 +.It "alloc_failures	integer	yes"
 +.El
 +.Pp
 +.Bl -tag -width 6n
 +.It Li used
 +The number of bytes currently allocated to the cache.
 +.It Li limit
 +The maximum number of bytes to be allocated to the cache.
 +.It Li divisor
 +Sets the cache size to be used as a proportion of kmem_size. A value of 2 (the default) will cause the cache size to be set to 1/2 of the kmem_size.
 +.It Li switch
 +Force a journal switch when this percentage of cache has been used.
 +.It Li misses
 +The number of cache misses, when data has been read, but was not found in the cache.
 +.It Li alloc_failures
 +The number of times memory failed to be allocated to the cache because the cache limit was hit.
 +.El
 +.Ss stats
 +The string and integer information available for the statistics level
 +is detailed below.
 +The changeable column shows whether a process with appropriate
 +privilege may change the value.
 +.Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent
 +.It Sy "sysctl name	Type	Changeable"
 +.It "skipped_bytes	integer	yes"
 +.It "combined_ios	integer	yes"
 +.It "switches	integer	yes"
 +.It "wait_for_copy	integer	yes"
 +.It "journal_full	integer	yes"
 +.It "low_mem	integer	yes"
 +.El
 +.Pp
 +.Bl -tag -width 6n
 +.It Li skipped_bytes
 +The number of bytes skipped.
 +.It Li combined_ios
 +The number of I/Os which were combined by journal optimization.
 +.It Li switches
 +The number of journal switches.
 +.It Li wait_for_copy
 +The number of times the journal switch process had to wait for the previous journal copy to complete.
 +.It Li journal_full
 +The number of times the journal was almost full, forcing a journal switch.
 +.It Li low_mem
 +The number of times the low_mem hook was called.
 +.El
  .Sh SEE ALSO
  .Xr geom 4 ,
  .Xr geom 8 ,
 @@ -237,7 +337,3 @@ utility appeared in
  .Fx 7.0 .
  .Sh AUTHORS
  .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 -.Sh BUGS
 -Documentation for sysctls
 -.Va kern.geom.journal.*
 -is missing.
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
>Unformatted:
