docs/130548: gjournal man page is missing sysctls

Wed Jan 14 14:40:02 UTC 2009

>Number:         130548
>Category:       docs
>Synopsis:       gjournal man page is missing sysctls
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 14 14:40:01 UTC 2009
>Closed-Date:
>Last-Modified:
>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 at FreeBSD.org
-.Sh BUGS
-Documentation for sysctls
-.Va kern.geom.journal.*
-is missing.


>Release-Note:
>Audit-Trail:
>Unformatted:

