From swear@blarg.net  Thu Jan 24 20:03:25 2002
Return-Path: <swear@blarg.net>
Received: from lists.blarg.net (lists.blarg.net [206.124.128.17])
	by hub.freebsd.org (Postfix) with ESMTP id 9F7F937B404
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 Jan 2002 20:03:24 -0800 (PST)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id 4E148BDC9
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 Jan 2002 20:03:24 -0800 (PST)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id UAA30170
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 Jan 2002 20:03:23 -0800
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id g0P46i903341;
	Thu, 24 Jan 2002 20:06:44 -0800 (PST)
	(envelope-from swear@blarg.net)
Message-Id: <3zpu3z6pm3.u3z@localhost.localdomain>
Date: 24 Jan 2002 20:06:44 -0800
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: dump(8) man page block/record/other clarifications.
X-GNATS-Notify:

>Number:         34248
>Category:       docs
>Synopsis:       dump(8) man page block/record/other clarifications.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 24 20:10:00 PST 2002
>Closed-Date:    Fri Apr 19 09:32:31 PDT 2002
>Last-Modified:  Fri Apr 19 09:32:31 PDT 2002
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.5-PRERELEASE i386 (~26'dec'02)
>Organization:
none
>Environment:
n/a
================
>Description:

The dump(8) man page has several problems:

-- It confusing in its use of "records", "blocks", "blocksize", etc.
-- It doesn't give -b's default, 10.
-- It doesn't say that -B argument gets rounded down.
-- It doesn't mention "rdump" except in "NAME" section.
-- It uses both "filesystem" and "file system" in similar contexts.
-- It doesn't describe the "filesystem" argument.
-- The second SYNOPSIS command improperly shows required options as
optional.
================
>How-To-Repeat:
n/a
================
>Fix:

patch -d "unknown uncompressed man directory" < this-PR

--- /tmp/dump..orig.8	Thu Jan 24 15:32:29 2002
+++ /tmp/dump.8	Thu Jan 24 19:58:28 2002
@@ -53,7 +53,11 @@
 .Op Fl T Ar date
 .Ar filesystem
 .Nm
-.Op Fl W Li \&| Fl w
+.Fl W | Fl w
+.Pp
+.Nm rdump
+is an alternate name for
+.Nm .
 .Pp
 .in \" XXX
 (The
@@ -83,17 +87,23 @@
 (such as some cartridge tape drives)
 each volume is of a fixed size;
 the actual size is determined by the tape size and density and/or
-block count options below.
+.Fl B
+options.
 By default, the same output file name is used for each volume
 after prompting the operator to change media.
 .Pp
+The filesystem to be dumped is specified by the argument
+.Ar filesystem
+as either its device-special file or its mount point
+(if that is in a standard entry in /etc/fstab).
+.Pp
 The following options are supported by
 .Nm :
 .Bl -tag -width Ds
 .It Fl 0\-9
 Dump levels.
 A level 0, full backup,
-guarantees the entire file system is copied
+guarantees the entire filesystem is copied
 (but see also the
 .Fl h
 option below).
@@ -112,11 +122,15 @@
 drive with hardware compression (where you can never be sure about
 the compression ratio).
 .It Fl B Ar records
-The number of 1 KB blocks per volume.
+The number of kilobytes per output volume, except that if it is
+not an integer multiple of the output block size,
+the command uses the next smaller such multiple.
 This option overrides the calculation of tape size
 based on length and density.
 .It Fl b Ar blocksize
-The number of kilobytes per dump record.
+The number of kilobytes per output block, except that if it is
+larger than 64, the command uses 64. (See the BUGS section.)
+The default block size is 10.
 .It Fl c
 Change the defaults for use with a cartridge tape drive, with a density
 of 8000 bpi, and a length of 1700 feet.
@@ -240,7 +254,7 @@
 option may be used to change it.
 .It Fl W
 .Nm Dump
-tells the operator what file systems need to be dumped.
+tells the operator what filesystems need to be dumped.
 This information is gleaned from the files
 .Pa dumpdates
 and
@@ -249,12 +263,12 @@
 .Fl W
 option causes
 .Nm
-to print out, for each file system in
+to print out, for each filesystem in
 the
 .Pa dumpdates
 file
 the most recent dump date and level,
-and highlights those file systems that should be dumped.
+and highlights those filesystems that should be dumped.
 If the
 .Fl W
 option is set, all other options are ignored, and
@@ -345,8 +359,7 @@
 This should be done at set intervals, say once a month or once every two months,
 and on a set of fresh tapes that is saved forever.
 .It
-After a level 0, dumps of active file
-systems are taken on a daily basis,
+After a level 0, dumps of active filesystems are taken on a daily basis,
 using a modified Tower of Hanoi algorithm,
 with this sequence of dump levels:
 .Bd -literal -offset indent
@@ -357,7 +370,7 @@
 for each day, used on a weekly basis.
 Each week, a level 1 dump is taken, and
 the daily Hanoi sequence repeats beginning with 3.
-For weekly dumps, another fixed set of tapes per dumped file system is
+For weekly dumps, another fixed set of tapes per dumped filesystem is
 used, also on a cyclical basis.
 .El
 .Pp
@@ -380,7 +393,7 @@
 .Fl D
 option)
 .It Pa /etc/fstab
-dump table: file systems and frequency
+dump table: filesystems and frequency
 .It Pa /etc/group
 to find group
 .Em operator
@@ -405,7 +418,7 @@
 Currently,
 .Xr physio 9
 slices all requests into chunks of 64 KB.  Therefore, it is
-impossible to use a larger tape blocksize, so
+impossible to use a larger output block size, so
 .Nm
 will prevent this from happening.
 .Pp
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->analyzed 
State-Changed-By: trhodes 
State-Changed-When: Fri Apr 12 13:44:15 PDT 2002 
State-Changed-Why:  
I will take care of this, thanks Gary. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Fri Apr 12 13:44:15 PDT 2002 
Responsible-Changed-Why:  
I will take care of this, thanks Gary. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34248 
State-Changed-From-To: analyzed->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Apr 16 19:10:43 PDT 2002 
State-Changed-Why:  
Applied flawlessly to CURRENT, waiting MFC to STABLE.  Thanks for the 
submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34248 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Fri Apr 19 09:31:55 PDT 2002 
State-Changed-Why:  
Just did the MFC, Final stage is to close this.  Thanks for the submission! 

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