bin/46142: The cpio(1), pax(1) and tar(1) manpages need improvement

To: gnats-admin%netbsd.org@localhost,netbsd-bugs%netbsd.org@localhost
Subject: bin/46142: The cpio(1), pax(1) and tar(1) manpages need improvement
From: Bug Hunting <bughunting%xs4all.nl@localhost>
Date: Sun, 4 Mar 2012 14:55:00 +0000 (UTC)
>Number:         46142
>Category:       bin
>Synopsis:       The cpio(1), pax(1) and tar(1) manpages need improvement
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Mar 04 14:55:00 +0000 2012
>Originator:     Bug Hunting
>Release:        NetBSD-current (6.99.3)
>Description:

The cpio(1), pax(1), and tar(1) manpages (all from the same source
directory) need improvement.  Also, more or less related to it, a
the names of compiled-in tape devices in tar.c could be changed.



>How-To-Repeat:

To view the manpages:

   $ man -s 1 cpio pax tar
   [output omitted]

To show the default tape device being used:

   $ tar -x
   tar: Failed open to read on /dev/nrst0 (Permission denied)
   tar: Unexpected EOF on archive file



>Fix:

Apply the patch attached, for which the changes follow.

Notes on the patch:

Some text and ideas were taken from, or based upon, libarchive's
bsdtar(1) and OpenBSD's tar(1) manpage.

The new, correct, default tape device is taken from src/include/paths.h
(`PATH_DEFTAPE'); altering the compiled-in tape devices should be
reviewed though, as it is not completely clear to me whether or
not this can or should simply be done.

Changes:

cpio.1, pax.1, tar.1:
- bump date in case non-trivial changes were made;
- improve wording and overall consistency;
- specify the correct default and compiled-in tape device;
- better document the use of `file' arguments as well as where such
  arguments can be shell glob patterns (this works on the level of
  `-x' and `-t', rather than with `-q' and `-s' specifically);
- clarify `-k' and `-q';
- fix a typo;
- use `.Dq' macro;
- clarify the note on `-X' (it is a general remark, not one meant
  for the user);
- add glob(3) to `SEE ALSO' section.

tar.c:
- use, along the lines of the default tape device, /dev/nrstN
  instead of /dev/rstN for the compiled-in backup devices.

--CblX+4bnyfN0pR09
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="cpio_pax_tar.patch"

Index: bin/pax/cpio.1
===================================================================
RCS file: /cvsroot/src/bin/pax/cpio.1,v
retrieving revision 1.13
diff -u -r1.13 cpio.1
--- bin/pax/cpio.1      19 Jun 2011 07:34:24 -0000      1.13
+++ bin/pax/cpio.1      4 Mar 2012 14:27:42 -0000
@@ -120,7 +120,7 @@
 Be verbose about operations.
 List filenames as they are written to the archive.
 .It Fl Fl xz
-Compress/decompress archive using
+Compress archive using
 .Xr xz 1
 format.
 .It Fl Z
@@ -128,7 +128,7 @@
 .Xr compress 1
 format.
 .It Fl z
-Compress/decompress archive using
+Compress archive using
 .Xr gzip 1
 format.
 .El
Index: bin/pax/pax.1
===================================================================
RCS file: /cvsroot/src/bin/pax/pax.1,v
retrieving revision 1.61
diff -u -r1.61 pax.1
--- bin/pax/pax.1       19 Jun 2011 07:34:24 -0000      1.61
+++ bin/pax/pax.1       4 Mar 2012 14:27:42 -0000
@@ -33,7 +33,7 @@
 .\"
 .\"    @(#)pax.1       8.4 (Berkeley) 4/18/94
 .\"
-.Dd June 18, 2011
+.Dd March 4, 2012
 .Dt PAX 1
 .Os
 .Sh NAME
@@ -743,11 +743,11 @@
 .It Fl Fl xz
 Use
 .Xr xz 1
-compression, when reading or writing archive files.
+for compression when reading or writing archive files.
 .It Fl z
 Use
 .Xr gzip 1
-compression, when reading or writing archive files.
+for compression when reading or writing archive files.
 .It Fl A
 Do not strip leading `/'s from file names.
 .It Fl B Ar bytes
@@ -1042,8 +1042,7 @@
 .Dq ..
 can be processed.
 .It Fl Fl use-compress-program
-Use the named program as the program to decompress the input or compress
-the output.
+Use the named program for compression when reading or writing archive files.
 .El
 .Pp
 The options that operate on the names of files or archive members
@@ -1177,9 +1176,9 @@
 completes it will exit with a non-zero exit status.
 .Sh EXAMPLES
 The command:
-.Dl pax -w -f /dev/rst0 \&.
+.Dl pax -w -f /dev/nrst0 \&.
 copies the contents of the current directory to the device
-.Pa /dev/rst0 .
+.Pa /dev/nrst0 .
 .Pp
 The command:
 .Dl pax -v -f filename
Index: bin/pax/tar.1
===================================================================
RCS file: /cvsroot/src/bin/pax/tar.1,v
retrieving revision 1.32
diff -u -r1.32 tar.1
--- bin/pax/tar.1       19 Jun 2011 07:34:24 -0000      1.32
+++ bin/pax/tar.1       4 Mar 2012 14:27:42 -0000
@@ -25,7 +25,7 @@
 .\"
 .\"    OpenBSD: tar.1,v 1.28 2000/11/09 23:58:56 aaron Exp
 .\"
-.Dd June 18, 2011
+.Dd March 4, 2012
 .Dt TAR 1
 .Os
 .Sh NAME
@@ -56,24 +56,38 @@
 One of the following flags must be present:
 .Bl -tag -width Ar
 .It Fl c , Fl Fl create
-Create new archive, or overwrite an existing archive,
-adding the specified files to it.
+Create a new archive, or overwrite an existing archive,
+adding the files as specified by the
+.Ar file
+arguments to it.
 .It Fl r , Fl Fl append
-Append the named new files to existing archive.
+Append the files as specified by the
+.Ar file
+arguments to an existing archive.
 Note that this will only work on media on which an end-of-file mark
 can be overwritten.
 .It Fl t , Fl Fl list
-List contents of archive.
-If any files are named on the
+List contents of an archive.
+If any
+.Ar file
+arguments are given on the
 command line, only those files will be listed.
+The arguments may be specified as shell glob patterns, in which case
+.Nm
+will list all archive members that match each pattern.
 .It Fl u , Fl Fl update
 Alias for
 .Fl r .
 .It Fl x , Fl Fl extract , Fl Fl get
-Extract files from archive.
-If any files are named on the
+Extract files from an archive.
+If any
+.Ar file
+arguments are given on the
 command line, only those files will be extracted from the
 archive.
+The arguments may be specified as shell glob patterns, in which case
+.Nm
+will extract all archive members that match each pattern.
 If more than one copy of a file exists in the
 archive, later copies will overwrite earlier copies during
 extraction.
@@ -99,7 +113,7 @@
 .It Fl f Ar archive , Fl Fl file Ar archive
 Filename where the archive is stored.
 Defaults to
-.Pa /dev/rst0 .
+.Pa /dev/nrst0 .
 If the archive is of the form:
 .Ar [[user@]host:]file
 then the archive will be processed using
@@ -108,12 +122,13 @@
 Follow symbolic links as if they were normal files
 or directories.
 .It Fl j, Fl Fl bzip2, Fl Fl bunzip2
-Use
-.Xr bzip2 1
-for compression of the archive.
+Compress/decompress the archive using
+.Xr bzip2 1 .
 This option is a GNU extension.
 .It Fl k , Fl Fl keep-old-files
-Keep existing files; don't overwrite them from archive.
+Keep existing files; don't overwrite them from the archive.
+In particular, if a file appears more than once in an archive,
+later copies will not overwrite earlier copies.
 .It Fl l , Fl Fl one-file-system
 Do not descend across mount points.
 .\" should be '-X'
@@ -140,10 +155,13 @@
 flag.
 .It Fl q , Fl Fl fast-read
 Select the first archive member that matches each
-.Ar pattern
-operand.
+.Ar file
+argument.
 No more than one archive member is matched for each
-.Ar pattern .
+.Ar file .
+Exit as soon as each specified
+.Ar file
+argument has been matched.
 When members of type directory are matched, the file hierarchy rooted at that
 directory is also matched.
 .It Fl S , Fl Fl sparse
@@ -151,11 +169,7 @@
 .Nm
 always generates sparse files.
 .It Fl s Ar replstr
-Modify the file or archive member names specified by the
-.Ar pattern
-or
-.Ar file
-operands according to the substitution expression
+Modify the archive member names according to the substitution expression
 .Ar replstr ,
 using the syntax of the
 .Xr ed 1
@@ -194,7 +208,7 @@
 .Dv standard error
 in the following format:
 .Dl \*[Lt]original pathname\*[Gt] \*[Gt]\*[Gt] \*[Lt]new pathname\*[Gt]
-File or archive member names that substitute to the empty string
+Archive member names that substitute to the empty string
 are not selected and will be skipped.
 The substitutions are applied by default to the destination hard and symbolic
 links.
@@ -207,16 +221,16 @@
 Interactively rename files.
 This option causes
 .Nm
-to prompt the user for the filename to use when storing or
-extracting files in an archive.
+to prompt the user for the filename to use when storing files to or
+extracting files from an archive.
 .It Fl Fl xz
-Compress/decompress archive using 
-.Xr xz  1 .
+Compress/decompress the archive using
+.Xr xz 1 .
 .It Fl z , Fl Fl gzip , Fl Fl gunzip
-Compress/decompress archive using
+Compress/decompress the archive using
 .Xr gzip 1 .
 .It Fl B , Fl Fl read-full-blocks
-Reassemble small reads into full blocks (For reading from 4.2BSD pipes).
+Reassemble small reads into full blocks (for reading from 4.2BSD pipes).
 .It Fl C Ar directory , Fl Fl directory Ar directory
 This is a positional argument which sets the working directory for the
 following files.
@@ -226,7 +240,7 @@
 This argument and its parameter may also appear in a file list specified by
 .Fl T .
 .It Fl H
-Only follow symlinks given on command line.
+Only follow symlinks given on the command line.
 .Pp
 Note SysVr3/i386 picked up ISC/SCO UNIX compatibility which implemented
 .Dq Fl F Ar file
@@ -256,10 +270,16 @@
 Exclude files matching the shell glob patterns listed in the given file.
 .\" exclude should be '-E' and '-X' should be one-file-system
 .Pp
-Note that it would be more standard to use this option to mean ``do not
-cross filesystem mount points.''
+Note that it would be more standard if this option would mean
+.Dq do not cross filesystem mount points
+(for which this implementation uses
+.Fl l ) ,
+in the way
+.Xr pax 1
+does.
 .It Fl Z , Fl Fl compress , Fl Fl uncompress
-Compress archive using compress.
+Compress/decompress the archive using
+.Xr compress 1 .
 .It Fl Fl strict
 Do not enable GNU tar extensions such as long filenames and long link names.
 .It Fl Fl atime-preserve
@@ -279,7 +299,7 @@
 .Nm
 always unlinks files before creating them.
 .It Fl Fl use-compress-program Ar program
-Use the named program as the program to decompress the input.
+Compress/decompress the archive using the named program.
 .It Fl Fl force-local
 Do not interpret filenames that contain a
 .Sq \&:
@@ -302,10 +322,10 @@
 The options
 .Op Fl 014578
 can be used to select one of the compiled-in backup devices,
-.Pa /dev/rstN .
+.Pa /dev/nrstN .
 .Sh FILES
-.Bl -tag -width "/dev/rst0"
-.It Pa /dev/rst0
+.Bl -tag -width "/dev/nrst0"
+.It Pa /dev/nrst0
 default archive name
 .El
 .Sh DIAGNOSTICS
@@ -348,7 +368,8 @@
 specific archive format specification.
 .Sh SEE ALSO
 .Xr cpio 1 ,
-.Xr pax 1
+.Xr pax 1 ,
+.Xr glob 3
 .Sh HISTORY
 A
 .Nm
Index: bin/pax/tar.c
===================================================================
RCS file: /cvsroot/src/bin/pax/tar.c,v
retrieving revision 1.68
diff -u -r1.68 tar.c
--- bin/pax/tar.c       3 Nov 2011 21:59:45 -0000       1.68
+++ bin/pax/tar.c       4 Mar 2012 14:27:43 -0000
@@ -100,12 +100,12 @@
 static const char LONG_LINK[] = "././@LongLink";
 
 #ifdef _PAX_
-char DEV_0[] = "/dev/rst0";
-char DEV_1[] = "/dev/rst1";
-char DEV_4[] = "/dev/rst4";
-char DEV_5[] = "/dev/rst5";
-char DEV_7[] = "/dev/rst7";
-char DEV_8[] = "/dev/rst8";
+char DEV_0[] = "/dev/nrst0";
+char DEV_1[] = "/dev/nrst1";
+char DEV_4[] = "/dev/nrst4";
+char DEV_5[] = "/dev/nrst5";
+char DEV_7[] = "/dev/nrst7";
+char DEV_8[] = "/dev/nrst8";
 #endif
 
 static int

--CblX+4bnyfN0pR09--

>Unformatted:
 --CblX+4bnyfN0pR09
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
Prev by Date: Re: install/46042 (A newline fails in sysinst msg_display())
Next by Date: Re: install/46042 (A newline fails in sysinst msg_display())
Previous by Thread: Re: kern/45615 (qemu's tap and bridge networking does not work on recent NetBSD current)
Next by Thread: Re: bin/46142: The cpio(1), pax(1) and tar(1) manpages need improvement
Indexes:
Home | Main Index | Thread Index | Old Index