NetBSD Problem Report #46142

From bughunting@xs4all.nl  Sun Mar  4 14:54:56 2012
Return-Path: <bughunting@xs4all.nl>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	by www.NetBSD.org (Postfix) with ESMTP id D278F63BFFC
	for <gnats-bugs@gnats.NetBSD.org>; Sun,  4 Mar 2012 14:54:56 +0000 (UTC)
Message-Id: <20120304145651.GA7801@frohike.homeunix.org>
Date: Sun, 4 Mar 2012 15:56:51 +0100
From: Bug Hunting <bughunting@xs4all.nl>
To: NetBSD GNATS <gnats-bugs@gnats.NetBSD.org>
Subject: The cpio(1), pax(1) and tar(1) manpages need improvement
X-Send-Pr-Version: 3.95

>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
>Last-Modified:  Fri Apr 06 11:50:02 +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--

>Audit-Trail:
From: Thomas Klausner <wiz@NetBSD.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: bin/46142: The cpio(1), pax(1) and tar(1) manpages need
 improvement
Date: Sun, 4 Mar 2012 16:03:04 +0100

 On Sun, Mar 04, 2012 at 02:55:00PM +0000, Bug Hunting wrote:
 > 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.

 I've no idea about this part.

 > 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

 Compare these two above to:
 > -Use
 > -.Xr bzip2 1
 > -for compression of the archive.
 > +Compress/decompress the archive using
 > +.Xr bzip2 1 .
 ..
 >  .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 Z , Fl Fl compress , Fl Fl uncompress
 > -Compress archive using compress.
 > +Compress/decompress the archive using
 > +.Xr compress 1 .
 ...
 >  .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.

 I think we should have consistency in the wording here.


 > +Exit as soon as each specified
 > +.Ar file
 > +argument has been matched.

 I'd prefer:
 Exit as soon as all specified
 .Ar file
 arguments have been matched.

 > 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

 Can someone please confirm if this patch is ok?
  Thomas

From: Marc Balmer <mbalmer@NetBSD.org>
To: gnats-bugs@NetBSD.org
Cc: Thomas Klausner <wiz@NetBSD.org>, gnats-admin@NetBSD.org,
        netbsd-bugs@NetBSD.org, Bug Hunting <bughunting@xs4all.nl>
Subject: Re: bin/46142: The cpio(1), pax(1) and tar(1) manpages need improvement
Date: Sun, 04 Mar 2012 16:31:32 +0100

 Am 04.03.12 16:05, schrieb Thomas Klausner:

 [...]

 >  > 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
 >  
 >  Can someone please confirm if this patch is ok?

 I don't understand why this change is requested or why it should be
 good.  The only difference is that rstX are rewinding tape devices and
 nrstX are non-rewinding tapes (they rewind on close).

From: Bug Hunting <bughunting@xs4all.nl>
To: NetBSD GNATS <gnats-bugs@gnats.NetBSD.org>
Cc: Thomas Klausner <wiz@NetBSD.org>, Marc Balmer <mbalmer@NetBSD.org>
Subject: Re: bin/46142: The cpio(1), pax(1) and tar(1) manpages need
 improvement
Date: Sun, 11 Mar 2012 02:22:50 +0100

 Hi,

 On Sun, Mar 04, 2012 at 03:05:03PM +0000, Thomas Klausner wrote:
 >  I think we should have consistency in the wording here.
 The patch as proposed was made to create consistency within individual
 manpages, but indeed not across them; if this is wished for, that
 could be done so as well.  Note however that the removals of
 ``/decompress'' in cpio.1 are not needed for consistency, but
 because the `-o' option, what these parts are about, is about
 archive creation, which does not involve decompression.

 While at it, also note the mixed use of ``decompress'' and
 ``uncompress''; if this will be made to be consistent as well,
 choosing the latter would probably be best, since that's also the
 name of one of tar(1)'s options (and, of course, the external
 program being called, i.e., uncompress(1)).

 >  > +Exit as soon as each specified
 >  > +.Ar file
 >  > +argument has been matched.
 >  
 >  I'd prefer:
 >  Exit as soon as all specified
 >  .Ar file
 >  arguments have been matched.
 The sentence as proposed was copied verbatim (except the argument
 name) from libarchive's bsdtar(1) manpage; sticking with that would
 maintain a bit of consistency.  Choose what fits best though.

 On Sun, Mar 04, 2012 at 03:35:02PM +0000, Marc Balmer wrote:
 >  I don't understand why this change is requested or why it should be
 >  good.  The only difference is that rstX are rewinding tape devices and
 >  nrstX are non-rewinding tapes (they rewind on close).
 The reason is, as the PR says (although with the added note on
 doubting the change along with it), that the default tape device
 was changed to a non-rewinding one as well; why would tar(1) use
 a non-rewinding tape as its default, but rewinding ones as other
 compiled-in ones?

 Thanks,

 Bug Hunting

From: Thomas Klausner <wiz@NetBSD.org>
To: Bug Hunting <bughunting@xs4all.nl>
Cc: NetBSD GNATS <gnats-bugs@gnats.NetBSD.org>,
	Marc Balmer <mbalmer@NetBSD.org>
Subject: Re: bin/46142: The cpio(1), pax(1) and tar(1) manpages need
 improvement
Date: Fri, 6 Apr 2012 13:47:28 +0200

 On Sun, Mar 11, 2012 at 02:22:50AM +0100, Bug Hunting wrote:
 > The patch as proposed was made to create consistency within individual
 > manpages, but indeed not across them; if this is wished for, that
 > could be done so as well.  Note however that the removals of
 > ``/decompress'' in cpio.1 are not needed for consistency, but
 > because the `-o' option, what these parts are about, is about
 > archive creation, which does not involve decompression.
 > 
 > While at it, also note the mixed use of ``decompress'' and
 > ``uncompress''; if this will be made to be consistent as well,
 > choosing the latter would probably be best, since that's also the
 > name of one of tar(1)'s options (and, of course, the external
 > program being called, i.e., uncompress(1)).

 What's the latest suggested patch you have for these?

 > The sentence as proposed was copied verbatim (except the argument
 > name) from libarchive's bsdtar(1) manpage; sticking with that would
 > maintain a bit of consistency.  Choose what fits best though.

 Ok, then let's leave that for now as you suggested.

 > On Sun, Mar 04, 2012 at 03:35:02PM +0000, Marc Balmer wrote:
 > >  I don't understand why this change is requested or why it should be
 > >  good.  The only difference is that rstX are rewinding tape devices and
 > >  nrstX are non-rewinding tapes (they rewind on close).
 > The reason is, as the PR says (although with the added note on
 > doubting the change along with it), that the default tape device
 > was changed to a non-rewinding one as well; why would tar(1) use
 > a non-rewinding tape as its default, but rewinding ones as other
 > compiled-in ones?

 I'm not comfortable with changing this part since I haven't ever used
 tapes. Please send me a patch without that part and open a new PR for
 the tape part, so someone else can pick this up.

 Thanks,
  Thomas

>Unformatted:
 --CblX+4bnyfN0pR09
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline

NetBSD Home
NetBSD PR Database Search

(Contact us) $NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2007 The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.