Date: Tue, 26 Aug 1997 03:00:38 +0200 (MESZ) From: Robert Eckardt <roberte@MEP.Ruhr-Uni-Bochum.de> To: FreeBSD-gnats-submit@FreeBSD.ORG Subject: gnu/4385: un- and unclearly documented options in tar Message-ID: <199708260100.DAA07424@ghost.mep.ruhr-uni-bochum.de> Resent-Message-ID: <199708260110.SAA26116@hub.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 4385
>Category: gnu
>Synopsis: un- and unclearly documented options in tar
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-bugs
>State: open
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Aug 25 18:10:01 PDT 1997
>Last-Modified:
>Originator: Robert Eckardt
>Organization:
>Release: FreeBSD 2.2.2-RELEASE i386
>Environment:
tar and tar.1 from 2.2.2-RELEASE CD (WC)
>Description:
Some options in tar (esp. --newer-mtime) are undocumented.
--checkpoint is wrongly documented. Formatting of man-page
goes wrong in serveral places. Date/time format for options,
which require one, is undocumented.
>How-To-Repeat:
man tar
tar --help
>Fix:
Fix attached as unified diff relative to /usr/src below.
diff -ru2 gnu/usr.bin/tar-2.2.2/getdate.y gnu/usr.bin/tar/getdate.y
--- gnu/usr.bin/tar-2.2.2/getdate.y Mon Aug 25 00:57:07 1997
+++ gnu/usr.bin/tar/getdate.y Mon Aug 25 02:40:00 1997
@@ -479,4 +479,5 @@
{ "idlw", tZONE, HOUR(12) }, /* International Date Line West */
{ "cet", tZONE, -HOUR(1) }, /* Central European */
+ { "cest", tDAYZONE, -HOUR(1) }, /* Central European Summer */
{ "met", tZONE, -HOUR(1) }, /* Middle European */
{ "mewt", tZONE, -HOUR(1) }, /* Middle European Winter */
diff -ru2 gnu/usr.bin/tar-2.2.2/tar.1 gnu/usr.bin/tar/tar.1
--- gnu/usr.bin/tar-2.2.2/tar.1 Mon Aug 25 00:57:08 1997
+++ gnu/usr.bin/tar/tar.1 Tue Aug 26 02:46:20 1997
@@ -3,8 +3,9 @@
.\"
.\" Written by John F. Woods <jfw@jfwhome.funhouse.com>
+.\" Updated by Robert Eckardt <roberte@mep.ruhr-uni-bochum.de>
.\"
.\" $Id: tar.1,v 1.6 1996/08/13 00:13:49 chuckr Exp $
.\"
-.Dd 6 August 1994
+.Dd 25 August 1997
.Os FreeBSD
.Dt TAR 1
@@ -14,8 +15,7 @@
tape archiver; manipulate "tar" archive files
.Sh SYNOPSIS
-.Nm
-.Op Cm Bq -
-.Op Cm bundled-options
-.Op Ar [gnu-style-flags]
+.Nm tar
+.Op [-] Ns Ar bundled-options
+.Op Ar gnu-style-flags
.Op Ar tarfile
.Op Ar blocksize
@@ -24,5 +24,5 @@
.Op Fl C Ar directory-name
.Sh DESCRIPTION
-.Nm
+.Nm Tar
is short for
.Dq tape archiver,
@@ -124,5 +124,6 @@
.It Fl -help
Prints a message listing and briefly describing all the command
-options to tar.
+options to
+.Nm tar.
.It Fl -atime-preserve
Restore the access times on files which are written to tape (note that
@@ -140,5 +141,5 @@
for extraction.
.It Fl -checkpoint
-Print directory names while reading the archive.
+Print number of buffer reads/writes while reading/writing the archive.
.It Fl f Ar [hostname:]file
.It Fl -file Ar [hostname:]file
@@ -155,4 +156,6 @@
on a remote machine. "-" may be used is a filename, for reading
or writing to/from stdin/stdout.
+.It Fl -force-local
+Archive file is local even if it has a colon
.It Fl F Ar file
.It Fl -info-script Ar file
@@ -198,8 +201,13 @@
.It Fl -multi-volume
Create/list/extract multi-volume archive.
+.It Fl -volno-file Ar file
+File name with volume number to start with.
.It Fl N Ar date
.It Fl -after-date Ar date
.It Fl -newer Ar date
-Only store files newer than
+Only store files with creation time newer than
+.Ar date .
+.It Fl -newer-mtime Ar date
+Only store files with modifiction time newer than
.Ar date .
.It Fl o
@@ -229,4 +237,6 @@
.It Fl -preserve-order
List of names to extract is sorted to match archive.
+.It Fl -show-omitted-dirs
+Show directories which were omitted while processing the archive.
.It Fl S
.It Fl -sparse
@@ -243,9 +253,13 @@
.Fl C.
.It Fl -totals
-Prints total bytes written with --create.
+Prints total bytes written with
+.It Fl -create.
.It Fl v
.It Fl -verbose
-Lists files written to archive with --create or extracted with --extract;
-lists file protection information along with file names with --list.
+Lists files written to archive with
+.It Fl -create or extracted with
+.It Fl -extract;
+lists file protection information along with file names with
+.It Fl -list.
.It Fl V Ar volume-name
.It Fl -label Ar volume-name
@@ -253,5 +267,7 @@
.Ar volume-name .
.It Fl -version
-Print tar program version number.
+Print
+.Nm tar
+program version number.
.It Fl w
.It Fl -interactive
@@ -290,6 +306,4 @@
.It Fl [0-7][lmh]
Specify tape drive and density.
-.It Fl -norecurse
-Don't recurse into subdirectories when creating.
.It Fl -unlink
Unlink files before creating them.
@@ -300,5 +314,5 @@
.Dl tar cfb /dev/rst0 20 bert ernie
or
-.Dl tar --create --file /dev/rst0 --block-size 20 bert ernie
+.Dl tar\ --create\ --file\ /dev/rst0\ --block-size\ 20\ bert\ ernie
Note that the
.Fl f
@@ -314,5 +328,5 @@
To extract all the C sources and headers from an archive named
"backup.tar", type
-.Dl tar xf backup.tar "*.[ch]"
+.Dl tar xf backup.tar '*.[ch]'
Note that the pattern must be quoted to prevent the shell from
attempting to expand it according the files in the current working
@@ -321,13 +335,14 @@
.Pp
To move file hierarchies, use a command line like this:
-.Bd -literal
-tar tar -cf - -C srcdir . | tar xpf - -C destdir
-.Ed
+.Dl tar\ -cf\ -\ -C\ srcdir\ .\ |\ tar\ xpf\ -\ -C\ destdir
.Pp
To create a compressed archive on diskette, using gzip, use a command-line like
-.Dl tar --block-compress -z -c -v -f /dev/rfd1a -b 36 tar/
+.Pp
+.Dl tar\ --block-compress\ -z\ -c\ -v\ -f\ /dev/rfd1a\ -b\ 36\ srcdir/
+.Pp
Note that you cannot mix bundled flags and --style flags; you can use
single-letter flags in the manner above, rather than having to type
-.Dl tar --block-compress --gzip --verbose --file /dev/rfd1a --block-size 20 tar/
+.Dl tar\ --block-compress\ --gzip\ --create\ --verbose\ --file\ /dev/rfd1a\
+ --block-size\ 36\ srcdir/
.Pp
The above-created diskette can be listed with
@@ -340,10 +355,26 @@
.Dl cat archive2.tar >> archive1.tar
because of the end-of-file block at the end of a tar archive).
+.Pp
+To archive all files from the directory srcdir, which were modified
+after Feb. 9th 1997, 13:00 h, use
+.Dl tar\ -c\ -f\ backup.tar\ --newer-mtime\ 'Feb\ 9\ 13:15\ 1997'\ srcdir/
+
+Other possible time specifications are '02/09/97 13:15', '1997-02-09
+13:15', '13:15 9 Feb 1997', '9 Feb 1997 13:15', 'Feb. 9, 1997 1:15pm', '3 weeks
+ago' or 'May first Sunday'.
+To specify the correct time zone use either e.g. `13:15 CEST' or `13:15+200'.
+
.Sh ENVIRONMENT
-The tar program examines the following environment variables.
+The
+.Nm tar
+program examines the following environment variables.
.Bl -tag -width "POSIXLY-CORRECT"
.It POSIXLY-CORRECT
-Normally, tar will process flag arguments that appear in the file list
-If set in the environment, this causes tar to consider the first
+Normally,
+.Nm tar
+will process flag arguments that appear in the file list.
+If set in the environment, this causes
+.Nm tar
+to consider the first
non-flag argument to terminate flag processing, as per the POSIX specification.
.It SHELL
@@ -373,5 +404,7 @@
.Sh HISTORY
The tar format has a rich history, dating back to Sixth Edition UNIX.
-The current implementation of tar is the GNU implementation, which
+The current implementation of
+.Nm tar
+is the GNU implementation, which
originated as the public-domain tar written by John Gilmore.
.Sh AUTHORS
diff -ru2 gnu/usr.bin/tar-2.2.2/tar.c gnu/usr.bin/tar/tar.c
--- gnu/usr.bin/tar-2.2.2/tar.c Mon Aug 25 00:57:08 1997
+++ gnu/usr.bin/tar/tar.c Tue Aug 26 02:44:48 1997
@@ -709,5 +709,5 @@
-B, --read-full-blocks reblock as we read (for reading 4.2BSD pipes)\n\
-C, --directory DIR change to directory DIR\n\
---checkpoint print directory names while reading the archive\n\
+--checkpoint print number of buffer reads/writes\n\
", stdout); /* KLUDGE */
fprintf (stdout, "\
@@ -715,5 +715,5 @@
DEF_AR_FILE);
fputs ("\
---force-local archive file is local even if has a colon\n\
+--force-local archive file is local even if it has a colon\n\
-F, --info-script F\n\
--new-volume-script F run script at end of each tape (implies -M)\n\
@@ -731,6 +731,8 @@
-m, --modification-time don't extract file modified time\n\
-M, --multi-volume create/list/extract multi-volume archive\n\
+--volno-file F use volume number to start with from file F\n\
-N, --after-date DATE,\n\
- --newer DATE only store files newer than DATE\n\
+ --newer DATE only store files with creation time newer than DATE\n\
+--newer-mtime DATE only store files with modification time newer than DATE\n\
-o, --old-archive,\n\
--portability write a V7 format archive, rather than ANSI format\n\
@@ -747,4 +749,5 @@
--preserve-order list of names to extract is sorted to match archive\n\
--same-owner create extracted files with the same ownership \n\
+--show-omitted-dirs show omitted directories while processing the archive.\n\
-S, --sparse handle sparse files efficiently\n\
-T, --files-from F get names to extract or create from file F\n\
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199708260100.DAA07424>