+++ /dev/null
-.\" @(#)tar.1 1.11.1 93/19/22 PJV;
-.TH TAR 1 "24 Feb 2009"
-.SH NAME
-tar \- The GNU version of the tar archiving utility
-.SH SYNOPSIS
-.B tar
-[
-.B \-
-]
-.B A \-\-catenate \-\-concatenate \||\| c \-\-create \||\| d \-\-diff \-\-compare \||\| \-\-delete \||\| r \-\-append \||\| t \-\-list \||\| u \-\-update \||\| x \-\-extract \-\-get
-.I [ options ]
-.I pathname [ pathname ... ]
-.SH DESCRIPTION
-.LP
-This manual page documents the GNU version of
-.B tar
-, an archiving program designed to store and extract files from
-an archive file known as a
-.IR tarfile.
-A
-.IR tarfile
-may be made on a tape drive, however, it is also common
-to write a
-.IR tarfile
-to a normal file.
-The first argument to
-.B tar
-must be one of the options:
-.BR Acdrtux ,
-followed by any optional functions.
-The final arguments to
-.B tar
-are the names of the files or directories which should be archived. The use
-of a directory name always implies that the subdirectories below should be
-included in the archive.
-.SH EXAMPLES
-.TP
-.B tar \-xvvf foo.tar
-extract foo.tar
-.TP
-.B tar \-xvvzf foo.tar.gz
-extract gzipped foo.tar.gz
-.TP
-.B tar \-cvvf foo.tar foo/
-tar contents of folder foo in foo.tar
-.SH "FUNCTION LETTERS"
-.TP
-.B One of the following options must be used:
-.TP
-.B \-A, \-\-catenate, \-\-concatenate
-append tar files to an archive
-.TP
-.B \-c, \-\-create
-create a new archive
-.TP
-.B \-d, \-\-diff, \-\-compare
-find differences between archive and file system
-.TP
-.B \-\-delete
-delete from the archive (not for use on mag tapes!)
-.TP
-.B \-r, \-\-append
-append files to the end of an archive
-.TP
-.B \-t, \-\-list
-list the contents of an archive
-.TP
-.B \-u, \-\-update
-only append files that are newer than copy in archive
-.TP
-.B \-x, \-\-extract, \-\-get
-extract files from an archive
-.SH "OTHER OPTIONS"
-.TP
-.B \-\-allow\-name\-mangling
-re-enable handling of GNUTYPE_NAMES which is now disabled by default
-.TP
-.B \-\-anchored
-force exclusion patterns to match initial subsequences
-.TP
-.B \-\-atime\-preserve
-don't change access times on dumped files
-.TP
-.B \-a, \-\-auto\-compress
-with \-\-create, selects compression algorithm basing on the suffix
-of the archive file name
-.TP
-.B \-b, \-\-blocking\-factor N
-use record size of Nx512 bytes (default N=20)
-.TP
-.B \-B, \-\-read\-full\-records
-reblock as we read (for reading 4.2BSD pipes)
-.TP
-.B \-\-backup[\=TYPE]
-back up files instead of overwriting (TYPE=numbered, existing, simple)
-.TP
-.B \-C, \-\-directory DIR
-change to directory DIR
-.TP
-.B \-\-checkpoint
-print periodic checkpoints
-.TP
-.B \-\-checkpoint\-action
-this action allows to specify an action to be executed upon hitting a
-checkpoint. Recognized actions are: dot, echo (the default),
-echo\=string, ttyout\=string, exec\=cmdline, and sleep\=value. Any number
-of `\-\-checkpoint\-action' options can be specified, the actions will be
-executed in order of their appearance in the command line.
-.TP
-.B \-\-check\-device
-enables comparing device numbers. This is the default.
-.TP
-.B \-\-no\-check\-device
-disables comparing device numbers during preparatory stage of an
-incremental dump.
-This allows to avoid creating full dumps if the device numbers change
-(e.g. when using an LVM snapshot)
-.TP
-.B \-\-exclude=PATTERN
-exclude files matching PATTERN
-.TP
-.B \-f, \-\-file [HOSTNAME:]F
-use archive file or device F (otherwise value of TAPE environment variable; if unset, "\-", meaning stdin/stdout)
-.TP
-.B \-F, \-\-info\-script F, \-\-new\-volume\-script F
-run script at end of each tape (implies \-M)
-.TP
-.B \-\-force\-local
-archive file is local even if it has a colon
-.TP
-.B \-G, \-\-incremental
-create/list/extract old GNU-format incremental backup
-.TP
-.B \-g, \-\-listed\-incremental F
-create/list/extract new GNU-format incremental backup
-.TP
-.B \-\-group G
-set group to G while adding files
-.TP
-.B \-h, \-\-dereference
-don't dump symlinks; dump the files they point to
-.TP
-.B \-\-hard\-dereference
-during archive creation, dereferences hard links and stores the files
-they refer to, instead of creating usual hard link members (type '1')
-.TP
-.B \-\-help
-print help message
-.TP
-.B \-i, \-\-ignore\-zeros
-ignore blocks of zeros in archive (normally mean EOF)
-.TP
-.B \-\-ignore\-case
-ignore case when excluding files
-.TP
-.B \-\-ignore\-failed\-read
-don't exit with non-zero status on unreadable files
-.TP
-.B \-j, \-\-bzip2
-filter archive through bzip2, use to decompress .bz2 files.
-WARNING: some previous versions of tar used option \-I to
-filter through bzip2. When writing scripts, use \-\-bzip2
-instead of \-j so that both older and newer tar versions
-will work.
-.TP
-.B \-k, \-\-keep\-old\-files
-keep existing files; don't overwrite them from archive
-.TP
-.B \-K, \-\-starting\-file F
-begin at file F in the archive
-.TP
-.B \-J, \-\-lzma
-selects LZMA compression algorithm
-.TP
-.B \-l, \-\-check\-links
-print a message if not all links are dumped
-.TP
-.B \-L, \-\-tape\-length N
-change tapes after writing N*1024 bytes
-.TP
-.B \-\-lzop
-filter the archive through lzop
-.TP
-.B \-m, \-\-touch
-don't extract file modified time
-.TP
-.BI \-\-transform " expr"
-applies filename transformations.
-The argument to this option can be a list of replace expressions, separated
-by semicolon (as in `sed').
-Filename transformations are applied to symbolic link targets during both
-creation and extraction.
-This option may be specified any number of
-times, the specified transofrmations will be applied in turn.
-.TP
-.B \-M, \-\-multi\-volume
-create/list/extract multi-volume archive
-.TP
-.B \-\-mode M
-set permissions to M while adding files
-.TP
-.B \-N, \-\-after\-date DATE, \-\-newer DATE
-only store files newer than DATE
-.TP
-.B \-\-newer\-mtime DATE
-only store files whose contents have changed after DATE
-.TP
-.B \-\-no\-anchored
-allow exclusion patterns to match any substring (the default)
-.TP
-.B \-\-no\-auto\-compress
-Cancels the effect of previous \-\-auto\-compress options
-.TP
-.B \-\-no\-ignore\-case
-match patterns case sensitively (the default)
-.TP
-.B \-\-no\-null
-cancels the effect of previous \-\-null option
-.TP
-.B \-\-no\-recursion
-do not recurse into subdirectories
-.TP
-.B \-o, \-\-no\-same\-owner
-extract files with owner set to current user (the default for non-root
-users)
-.TP
-.B \-\-no\-same\-permissions
-apply umask to extracted files (the default for non-root users)
-.TP
-.B \-\-no\-wildcards
-do not use wildcards when excluding files
-.TP
-.B \-\-no\-wildcards\-match\-slash
-don't let wildcards match "/" when excluding files
-.TP
-.B \-\-null
-for \-T, use "NUL" instead of newline as filename terminator
-.TP
-.B \-\-numeric\-owner
-always use numbers for user/group names
-.TP
-.B \-\-old\-archive, \-\-portability
-write a V7 format archive, rather than ANSI format. These options are
-deprecated, please use
-.B \-\-format\=v7
-instead.
-.TP
-.B \-\-one\-file\-system
-stay in local file system when creating an archive
-.TP
-.B \-\-owner O
-set owner to O while adding files
-.TP
-.B \-O, \-\-to\-stdout
-extract files to standard output
-.TP
-.B \-p, \-\-same\-permissions, \-\-preserve\-permissions
-ignore umask when extracting files (the default for root)
-.TP
-.B \-P, \-\-absolute\-names
-don't strip leading `/'s from file names
-.TP
-.B \-\-posix
-create POSIX compliant archive. This option is deprecated,
-please use
-.B \-\-format\=posix
-instead.
-.TP
-.B \-\-preserve
-like \-p \-s
-.TP
-.B \-R, \-\-block\-number
-show block number within archive with each message
-.TP
-.B \-\-record\-size SIZE
-use SIZE bytes per record
-.TP
-.B \-\-recursion
-recurse into directories (the default)
-.TP
-.B \-\-recursive\-unlink
-remove existing directories before extracting directories of the same
-name
-.TP
-.B \-\-remove\-files
-remove files after adding them to the archive
-.TP
-.B \-\-rsh\-command=CMD
-Use remote COMMAND instead of `rsh'. This option exists so that
-people who use something other than the standard `rsh' (e.g., a
-Kerberized `rsh') can access a remote device.
-.TP
-.B \-S, \-\-sparse
-handle sparse files efficiently
-.TP
-.B \-s, \-\-same\-order, \-\-preserve\-order
-list of names to extract is sorted to match archive
-.TP
-.B \-\-same\-owner
-extract files with owner as specified in archive (the default for
-root)
-.TP
-.B \-\-show\-omitted\-dirs
-mention directories that are being skipped over
-.TP
-.BI \-\-strip\-components " n"
-Strip the given number of leading directory components
-.TP
-.B \-\-strip, \-\-strip\-components N
-Strips the first N components from archive members' pathnames when
-unpacking.
-.TP
-.B \-\-suffix SUFFIX
-append SUFFIX to make backup files (default ~)
-.TP
-.B \-T, \-\-files\-from F
-get names to extract or archive from file F
-.TP
-.B \-\-totals
-display total bytes written after creating an archive
-.TP
-.B \-U, \-\-unlink\-first
-unlink & recreate files instead of overwriting
-.TP
-.B \-\-use\-compress\-program PROG
-filter the archive through PROG (which must accept \-d)
-.TP
-.B \-v, \-\-verbose
-verbosely list files processed
-.TP
-.B \-V, \-\-label NAME
-create archive with volume name NAME
-.TP
-.B \-\-version
-print tar program version number
-.TP
-.B \-\-volno\-file F
-keep track of current volume (of a multi-volume archive) in F
-.TP
-.B \-w, \-\-interactive, \-\-confirmation
-ask for confirmation for every action
-.TP
-.B \-W, \-\-verify
-attempt to verify the archive after writing it
-.TP
-.B \-\-wildcards
-use wildcards when excluding files (the default)
-.TP
-.B \-\-wildcards\-match\-slash
-allow wildcards to match "/" (the default)
-.TP
-.B \-X, \-\-exclude\-from=FILE
-exclude files matching patterns listed in FILE
-.TP
-.B \-Z, \-\-compress, \-\-uncompress
-filter the archive through compress
-.TP
-.B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip
-filter the archive through gzip
-.TP
-.B \-[0\-7][lmh]
-specify drive and density
-.SH ENVIRONMENT
-The behavior of tar is controlled by the following environment variables,
-among others:
-.TP
-.B TAPE
-Device or file to use for the archive if \fB--file\fR is not specified.
-If this environment variable is unset, use stdin or stdout instead.
-.TP
-.B TAR_OPTIONS
-Options to prepend to those specified on the command line, separated by
-whitespace. Embedded backslashes may be used to escape whitespace or
-backslashes within an option.
-.LP
-In addition, the value of the blocking factor is made available to info
-and checkpoint scripts via environment variable
-.B TAR_BLOCKING_FACTOR.
-.SH BUGS
-.LP
-The GNU folks, in general, abhor man pages, and create info documents instead.
-Unfortunately, the info document describing tar is licensed under the GFDL with
-invariant cover texts, which violates the Debian Free Software Guidelines. As
-a result, the info documentation for tar is not included in the Debian package.
-
-If you want to read the complete documentation for GNU tar, please refer to
-the online version at
-.PP
-.ce 1
-<http://www.gnu.org/software/tar/manual/index.html>
-.PP
-This man page was created for the Debian distribution. It does not describe
-all of the functionality of tar, and it is often out of date. Patches to
-improve the coverage and/or accuracy of this man page are appreciated, and
-should be filed as wishlist severity bugs against the Debian tar package,
-not submitted to the GNU tar maintainers.
--- /dev/null
+#
+# tarman - make tar man page from src/tar.c
+# some text cribbed from debian tar man page
+#
+
+use strict;
+
+my $t = "".localtime(time);
+my $datestr = substr($t,4,3)." ".substr($t,8,2).", ".substr($t,20,4);
+
+@ARGV=qw(src/tar.c);
+my $mode;
+my @operations;
+my $lastoperation;
+my @options;
+my @formats;
+my @short;
+my $examples;
+my $saw_format;
+my @env_vars;
+while (<>) {
+ my $nflag = 0;
+ chomp;
+# print "$mode: $_\n";
+ if (/getenv.*"/) {
+ next if defined($mode);
+ my @c1 = split('"');
+ if ($#c1 > 0) {
+ push @env_vars, $c1[1];
+ }
+ }
+ if (/Main operation mode:/) {
+ $mode = 1;
+ next;
+ }
+ if (/Operation modifiers:/) {
+ $mode = 2;
+ next;
+ }
+ if (/Examples:/) {
+ $mode = 3;
+ next;
+ }
+ if (/define GRID/) {
+ $mode = 2;
+ }
+ if (/undef GRID/) {
+ undef $lastoperation;
+ undef $mode;
+ next;
+ }
+ if ($mode == 1 || $mode == 2) {
+ if (/{"/) { # }
+ my @j = split(',');
+ my @c1 = split('"', $j[0]);
+ if (/OPTION_ALIAS/) {
+ next unless defined($lastoperation);
+ push @{$$lastoperation{'alias'} }, $c1[1];
+ next;
+ }
+ my %newhash = ();
+ $lastoperation = \%newhash;
+ my $name = $c1[1];
+ if ($name =~ /^ /) {
+ $name =~ s/^ */format=/;
+ push @formats, $lastoperation;
+ } elsif ($mode == 1) {
+ push @operations, $lastoperation;
+ } else {
+ push @options, $lastoperation;
+ }
+ $newhash{'name'} = $name;
+ if ($mode == 2 && $name eq 'format') {
+ $saw_format = $lastoperation;
+ }
+ my @c2 = split("'", $j[1]);
+ if ($#c2 > 0) {
+ $newhash{'short'} = $c2[1];
+ push @short, $c2[1] if ($mode == 1);
+ }
+ if ($j[2] =~ /N_/) {
+ $nflag = 1;
+ }
+ }
+ if (/N_/) {
+ next unless defined($lastoperation);
+ my $nrest = $_;
+ $nrest =~ s/.*N_//;
+ my @c3 = split('"', $nrest);
+ if ($#c3 > 0) {
+ if ($nflag) {
+ $$lastoperation{'operand'} .= $c3[1];
+ } else {
+ $$lastoperation{'description'} .= $c3[1];
+ }
+ }
+ }
+ }
+ if ($mode == 3 ) {
+ my $j = $_;
+ $j =~ s/\\n.*//;
+ my ($c1, $c2) = split('#', $j, 2);
+ $c1 =~ s/ *$//;
+ $c1 =~ s/^ *//;
+$c1 =~ s/-/\\-/g;
+ $c2 =~ s/^ *//;
+$examples .= <<".";
+$c2
+.Bd -literal -offset indent -compact
+$c1
+.Ed
+.
+ # (
+ if (/"\)/) {
+ undef $mode;
+ }
+ }
+}
+
+# for my $q ( @operations) {
+# print "\nshort=".$$q{'short'}."\n";
+# print "name=".$$q{'name'}."\n";
+# print "desc=".$$q{'description'}."\n";
+# if (defined($$q{'alias'})) {
+# print "alias=".join(',',@{ $$q{'alias'}})."\n";
+# }
+# }
+
+sub long2nroff {
+ my $f = shift;
+ if ($f !~ /^-/) {
+ $f = "Fl -$f";
+ }
+ $f =~ s/-/\\-/g;
+ return $f;
+}
+
+sub format_options
+{
+ my $h = shift;
+ my $r;
+ for my $q ( @$h ) {
+ $r .= ".It";
+ my @functions;
+ push @functions, " Fl ".$$q{'short'} if defined($$q{'short'});
+ push @functions, " ".long2nroff($$q{'name'});
+ push @functions, join(' ', '', map {long2nroff $_} @{ $$q{'alias'} })
+ if defined($$q{'alias'});
+ $r .= join(' ,', @functions);
+ if (defined($$q{'operand'})) {
+ if ($#functions > 0) {
+ $r .= " ";
+ } else {
+ $r .= " Ns \\= Ns ";
+ }
+ $r .= "Ar ".$$q{'operand'};
+ }
+ $r .= "\n".$$q{'description'}."\n";
+ $r .= $$q{'extra'};
+ }
+ return $r;
+}
+
+sub optionkeyword
+{
+ my $h = shift;
+ my $k = $$h{'short'};
+ $k = $$h{'name'} if !defined($k);
+ my $l = $k;
+ if ($l =~ s/^no-//) {
+ $l .= "-no";
+ }
+ return ($l,$k);
+}
+
+sub optioncmp
+{
+ my ($x1, $x2) = optionkeyword($a);
+ my ($y1, $y2) = optionkeyword($b);
+ my $r = lc($x1) cmp lc($y1);
+ return $r if $r;
+ $r = $y1 cmp $x1;
+ return $r if $r;
+ return $x2 cmp $y2;
+}
+
+@operations = sort optioncmp @operations;
+@operations = sort optioncmp @operations;
+@options = sort optioncmp @options;
+@formats = sort optioncmp @formats;
+
+if ($#formats >= 0 && !$saw_format) {
+ print STDERR "FIXME: saw --format=X but no root --format!\n";
+ exit(1);
+}
+
+my $function_letters;
+my $short_letters = join('', sort @short);
+my $option_letters;
+my $format_letters;
+my $command_string = <<".";
+.Nm tar
+.
+$command_string .= ".Oo Fl Oc";
+my $env_variables;
+my %env_description = (
+'SIMPLE_BACKUP_SUFFIX' => <<".",
+Backup prefix to use when extracting, if
+.Fl \\-suffix
+is not specified.
+The backup suffix defaults to `~' if neither is specified.
+.
+'TAPE' => <<".",
+Device or file to use for the archive if
+.Fl \\-file
+is not specified.
+If this environment variable is unset, use stdin or stdout instead.
+.
+'TAR_OPTIONS' => <<".",
+Options to prepend to those specified on the command line, separated by
+whitespace. Embedded backslashes may be used to escape whitespace or
+backslashes within an option.
+.
+);
+my $sep = "";
+for my $q ( @operations) {
+ $command_string .= " Cm";
+ $command_string .= $sep;
+ $command_string .= " ".$$q{'short'} if defined($$q{'short'});
+ $command_string .= " ".long2nroff($$q{'name'});
+ if (defined($$q{'alias'})) {
+ my $t = join(' ', '', map{long2nroff $_} @{ $$q{'alias'} });
+ $t =~ s/ Fl / /g;
+ $command_string .= $t;
+ }
+ $sep = " \\||\\|";
+}
+$function_letters = ".Bl -tag -width flag\n";
+$function_letters .= format_options(\@operations);
+$function_letters .= ".El";
+if ($#formats >= 0) {
+ $format_letters = ".Bl -tag -width flag\n";
+ $format_letters .= format_options(\@formats);
+ $format_letters .= ".El\n";
+ $$saw_format{'extra'} = $format_letters;
+}
+### Ar Cm Ic Li Nm Op Pa Va
+$option_letters = ".Bl -tag -width flag\n";
+$option_letters .= format_options(\@options);
+$option_letters .= ".El";
+$env_variables .= ".Bl -tag -width Ds\n";
+for my $q ( @env_vars) {
+ $env_variables .= ".It Ev $q\n";
+ $env_variables .= $env_description{$q};
+}
+$env_variables .= ".El";
+
+$examples =~ s/\n$//;
+$function_letters =~ s/\n$//;
+$option_letters =~ s/\n$//;
+$env_variables =~ s/\n$//;
+print <<".";
+.\\" generated by script on $t
+.Dd $datestr
+.Dt TAR 1
+.Sh NAME
+.Nm tar
+.Nd The GNU version of the tar archiving utility
+.Sh SYNOPSIS
+$command_string
+.Op Ar options
+.Op Ar pathname ...
+.Sh DESCRIPTION
+.Nm Tar
+stores and extracts files from a tape or disk archive.
+.Pp
+The first argument to
+.B tar
+should be a function; either one of the letters
+.Cm $short_letters ,
+or one of the long function names.
+A function letter need not be prefixed with ``\\-'', and may be combined
+with other single-letter options.
+A long function name must be prefixed with
+.Cm \\\\-\\\\- .
+Some options take a parameter; with the single-letter form
+these must be given as separate arguments.
+With the long form, they may be given by appending
+.Cm = Ns Ar value
+to the option.
+.Sh FUNCTION LETTERS
+Main operation mode:
+$function_letters
+.Sh OTHER OPTIONS
+Operation modifiers:
+$option_letters
+.Sh ENVIRONMENT
+The behavior of tar is controlled by the following environment variables,
+among others:
+$env_variables
+.Sh EXAMPLES
+$examples
+.Sh SEE ALSO
+.\\" libarchive
+.Xr tar 5 ,
+.\\" man-pages
+.Xr symlink 7 ,
+.Xr rmt 8
+.Sh HISTORY
+The
+.Nm tar
+command appeared in
+.At v7 .
+.Sh BUGS
+The GNU folks, in general, abhor man pages, and create info documents instead.
+Unfortunately, the info document describing tar is licensed under the GFDL with
+invariant cover texts, which makes it impossible to include any text
+from that document in this man page.
+Most of the text in this document was automatically extracted from the usage
+text in the source.
+It may not completely describe all features of the program.
+.
+__END__
projects / tar / commitdiff