arnold@unix.cc.emory.edu (Arnold D. Robbins) (11/23/88)
I submitted these a while back to gnu@prep.ai.mit.edu, but tar.tar.Z
hasn't changed recently.
There are a number of spelling and texinfo bugs, as well as missing
pxref's, and one or two incomplete sentences. The following context
diff fixes all the problems.
Gnu tar looks really nifty.
Arnold Robbins
------
*** tar.texinfo.orig Fri Nov 4 14:37:26 1988
--- tar.texinfo Thu Nov 10 10:25:11 1988
***************
*** 18,24 ****
(this paragraph not being relevant to the printed manual).
@end ignore
! Premission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of
a permission notice identical to this one.
--- 18,24 ----
(this paragraph not being relevant to the printed manual).
@end ignore
! Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of
a permission notice identical to this one.
***************
*** 28,33 ****
--- 28,37 ----
modified versions.
@end ifinfo
+ @iftex
+ @finalout
+ @end iftex
+
@titlepage
@center @titlefont{tar}
@sp 1
***************
*** 86,92 ****
The tape archiver @code{tar} allows you to store many files in an
@dfn{archive file} or @dfn{tar file} which describes the names and contents
! of the constituent files. Later you an extract some or all of these files
from the archive.
Tar files are not restricted to magnetic tapes. (The @code{tar} program
--- 90,96 ----
The tape archiver @code{tar} allows you to store many files in an
@dfn{archive file} or @dfn{tar file} which describes the names and contents
! of the constituent files. Later you can extract some or all of these files
from the archive.
Tar files are not restricted to magnetic tapes. (The @code{tar} program
***************
*** 181,193 ****
@item -t
The @samp{-t} command causes @code{tar} to display a list of the files
! in the archive. If you specify file names is given, only files in
that you specify will be mentioned (but each of them is mentioned only
if it appears in the archive).
@item -u
The @samp{-u} command causes @code{tar} to add the specified files to
! the end of the archive, like @samp{-r}, but only when a file doesn't
already exist in the archive or is newer than the version in the
archive (last-modification time is compared). This command can be
very slow.
--- 185,197 ----
@item -t
The @samp{-t} command causes @code{tar} to display a list of the files
! in the archive. If you specify file names, only the files
that you specify will be mentioned (but each of them is mentioned only
if it appears in the archive).
@item -u
The @samp{-u} command causes @code{tar} to add the specified files to
! the end of the archive, like @w{@samp{-r}}, but only when a file doesn't
already exist in the archive or is newer than the version in the
archive (last-modification time is compared). This command can be
very slow.
***************
*** 219,232 ****
re-writing the archive) to delete files from a magnetic tape.
@end table
! @node Options, GlobalOptions, Commands, Top
@chapter Options That Change How @code{tar} Works
Options may be specified as individual arguments starting with @samp{-}.
In this case, if the option wants an argument (as does, for example,
! @samp{-f}) then the argument should
All options are optional. Some options make sense with any command, while
! others are meaningful only with particular commands.
@menu
* General Options::
--- 223,237 ----
re-writing the archive) to delete files from a magnetic tape.
@end table
! @node Options, Global Options, Commands, Top
@chapter Options That Change How @code{tar} Works
Options may be specified as individual arguments starting with @samp{-}.
In this case, if the option wants an argument (as does, for example,
! @samp{-f}) then the argument should come after the option, separated
! from it by a space.
All options are optional. Some options make sense with any command, while
! others are meaningful only with particular commands.@refill
@menu
* General Options::
***************
*** 247,253 ****
The default blocking factor is set when @code{tar} is compiled, and is
typically 20.
! Blocking facters larger than 20 cannot be read by very old versions of
@code{tar}, or by some newer versions of tar running on old machines
with small address spaces.
--- 252,258 ----
The default blocking factor is set when @code{tar} is compiled, and is
typically 20.
! Blocking factors larger than 20 cannot be read by very old versions of
@code{tar}, or by some newer versions of tar running on old machines
with small address spaces.
***************
*** 264,270 ****
With GNU @code{tar} the blocking factor is limited only by the maximum
block size the device containing the archive, or by the amount of
! avaliable virtual memory.
@item -f @var{filename}
This option is used to specify the file name of the archive @code{tar}
--- 269,275 ----
With GNU @code{tar} the blocking factor is limited only by the maximum
block size the device containing the archive, or by the amount of
! available virtual memory.
@item -f @var{filename}
This option is used to specify the file name of the archive @code{tar}
***************
*** 290,297 ****
up an @code{/etc/rmt} on the remote machine. If you give an alternate login
name, it will be given to the @code{rsh}. Naturally, the remote machine must
have a copy of @file{/etc/rmt}. @code{/etc/rmt} is free software
! from the University of California, and a copy of the souce code can be found
! with the sources for @code{tar}. @code{/etc/rmt} will have to be modifed to
run on non-BSD4.3 systems.
@item -C @var{dir}
--- 295,302 ----
up an @code{/etc/rmt} on the remote machine. If you give an alternate login
name, it will be given to the @code{rsh}. Naturally, the remote machine must
have a copy of @file{/etc/rmt}. @code{/etc/rmt} is free software
! from the University of California, and a copy of the source code can be found
! with the sources for @code{tar}. @code{/etc/rmt} will have to be modified to
run on non-BSD4.3 systems.
@item -C @var{dir}
***************
*** 359,365 ****
@item -R
If @samp{-R} is used, @code{tar} prints, along with every message it
would normally produce, the record number within the archive where
! the message occured. This option is especially useful when reading
damaged archives, since it helps pinpoint the damaged sections.
This can also be useful when making a log of a file-system backup tape,
--- 364,370 ----
@item -R
If @samp{-R} is used, @code{tar} prints, along with every message it
would normally produce, the record number within the archive where
! the message occurred. This option is especially useful when reading
damaged archives, since it helps pinpoint the damaged sections.
This can also be useful when making a log of a file-system backup tape,
***************
*** 408,415 ****
This option causes @code{tar} to read a list of filenames
(actually regular expressions) from the file @var{file},
@code{tar} will ignore files with those names.
! Thus if @code{tar} is called as @example{tar -c -X foo .}
! and the file @file{foo} contains @example{*.o} none of the files
whose names end in @file{.o} in the current directory will be added
to the archive. Multiple @code{-X} options may be given.
--- 413,420 ----
This option causes @code{tar} to read a list of filenames
(actually regular expressions) from the file @var{file},
@code{tar} will ignore files with those names.
! Thus if @code{tar} is called as @samp{tar -c -X foo .}
! and the file @file{foo} contains @samp{*.o} none of the files
whose names end in @file{.o} in the current directory will be added
to the archive. Multiple @code{-X} options may be given.
***************
*** 432,443 ****
@section Options for Creating Or Updating an Archive
These options are used to control which files @code{tar} puts in an
! archive, or to control the format the archive is written in. FOO xref
Except as noted below, these options are useful with the @samp{-c},
@samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D} commands.
! Also note, that the @samp{-B} option, (FOO xref), is also useful
! with the @samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D} commands.
@table @code
@c this command no longer exists -D is now the old -J command
--- 437,448 ----
@section Options for Creating Or Updating an Archive
These options are used to control which files @code{tar} puts in an
! archive, or to control the format the archive is written in (@pxref{Format}).
Except as noted below, these options are useful with the @samp{-c},
@samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D} commands.
! Also note, that the @samp{-B} option, (@pxref{Extraction Options}),
! is also useful with the @samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D} commands.
@table @code
@c this command no longer exists -D is now the old -J command
***************
*** 470,476 ****
link. This could be considered a bug.
@item -l
! This option causes @code{tar} to not cross filesystem boundries
when archiving parts of a directory tree. This option only
affects the files archived because they are in a directory that
is archived ; files named on the command line are archived
--- 475,481 ----
link. This could be considered a bug.
@item -l
! This option causes @code{tar} to not cross filesystem boundaries
when archiving parts of a directory tree. This option only
affects the files archived because they are in a directory that
is archived ; files named on the command line are archived
***************
*** 485,491 ****
@item -o
This option causes @code{tar} to write an old format archive, which
does not include information about directories, pipes, fifos,
! continguous files, or device files, and specifies file ownership by
numeric user- and group-ids rather than by user and group names. In
most cases, a @emph{new} format archive can be read by an @emph{old}
@code{tar} program without serious trouble, so this option should
--- 490,496 ----
@item -o
This option causes @code{tar} to write an old format archive, which
does not include information about directories, pipes, fifos,
! contiguous files, or device files, and specifies file ownership by
numeric user- and group-ids rather than by user and group names. In
most cases, a @emph{new} format archive can be read by an @emph{old}
@code{tar} program without serious trouble, so this option should
***************
*** 523,529 ****
This option is turned on by default when @code{tar} is reading an
archive from standard input, or from a remote machine. This is
! because on BSD systems a read of a pipe will return however much
happens to be in the pipe, even if it is less than @code{tar}
requested. If this option was not used, @code{tar} would fail
as soon as it read an incomplete block from the pipe.
--- 528,534 ----
This option is turned on by default when @code{tar} is reading an
archive from standard input, or from a remote machine. This is
! because on BSD Unix systems a read of a pipe will return however much
happens to be in the pipe, even if it is less than @code{tar}
requested. If this option was not used, @code{tar} would fail
as soon as it read an incomplete block from the pipe.
***************
*** 539,545 ****
directory at the time the archive was created. This information is
put out in a format that is not easy for humans to read, but which
is unambiguous for a program: each filename is preceded by either a
! @samp{Y} if the file is present in the archive, or a @samp{N} if the
file is a directory, or is not included in the archive. Each
filename is terminated by a null character. The last file is
followed by an additional null and a newline to indicate the end of
--- 544,550 ----
directory at the time the archive was created. This information is
put out in a format that is not easy for humans to read, but which
is unambiguous for a program: each filename is preceded by either a
! @samp{Y} if the file is present in the archive, or an @samp{N} if the
file is a directory, or is not included in the archive. Each
filename is terminated by a null character. The last file is
followed by an additional null and a newline to indicate the end of
***************
*** 549,555 ****
for a directory is found, all files that currently exist in that directory
but are not listed in the archive @emph{are deleted from the directory}.
! This behavior convenient when you are restoring a damaged file system
from a succession of incremental backups: it restores the entire state
of the file system to that which obtained when the backup was made.
If you don't use @samp{-G}, the file system will probably fill up
--- 554,560 ----
for a directory is found, all files that currently exist in that directory
but are not listed in the archive @emph{are deleted from the directory}.
! This behavior is convenient when you are restoring a damaged file system
from a succession of incremental backups: it restores the entire state
of the file system to that which obtained when the backup was made.
If you don't use @samp{-G}, the file system will probably fill up
***************
*** 649,657 ****
argument of @samp{-f}.
@chapter Using @code{tar} to Perform Full Dumps
! @node FullDumps, ExtractingOptions, IncDumps, Top
Full dumps should only be made when no other people or programs are
! modifying files in the filesystem. If files are modifed while
@code{tar} is making the backup, they may not be stored properly in
the archive, in which case you won't be able to restore them if you
have to.
--- 654,662 ----
argument of @samp{-f}.
@chapter Using @code{tar} to Perform Full Dumps
! @node FullDumps, Extracting Options, IncDumps, Top
Full dumps should only be made when no other people or programs are
! modifying files in the filesystem. If files are modified while
@code{tar} is making the backup, they may not be stored properly in
the archive, in which case you won't be able to restore them if you
have to.
***************
*** 660,672 ****
volume label, so you can tell what this archive is even if the label
falls off the tape, or anything like that.
! Unless the filesystem you are dumping is guarenteed to fit on one
volume, you will need to use the @samp{-M} option. Make sure you
have enough tapes on hand to complete the backup.
! If you want to dump each filesystem separatly you will need to use
the @samp{-l} option to prevent @code{tar} from crossing filesystem
! boundries when storing (sub)directories.
The @samp{-G} option is not needed, since this is a complete copy of
everything in the filesystem, and a full restore from this backup
--- 665,677 ----
volume label, so you can tell what this archive is even if the label
falls off the tape, or anything like that.
! Unless the filesystem you are dumping is guaranteed to fit on one
volume, you will need to use the @samp{-M} option. Make sure you
have enough tapes on hand to complete the backup.
! If you want to dump each filesystem separately you will need to use
the @samp{-l} option to prevent @code{tar} from crossing filesystem
! boundaries when storing (sub)directories.
The @samp{-G} option is not needed, since this is a complete copy of
everything in the filesystem, and a full restore from this backup
***************
*** 702,707 ****
--- 707,713 ----
files will not be dumped, and the next day's incremental dump will
@emph{not} store files that would have gone onto that dump.
+ @example
#!/bin/csh
# Dump thingie
set now = `date`
***************
*** 718,723 ****
--- 724,730 ----
/sugar-bombs/u
echo $now > date.nfs.dump
mt -f /dev/rtu20 rew
+ @end example
Output from this script is stored in a file, for the operator to
read later.
***************
*** 726,732 ****
the last dump.
Since this is a streaming tape drive, no attempt to verify the
! archvie is done. This is also why the high blocking factor (126) is
used. The tape drive must also be rewound by the @code{mt} command
after the dump is made.
--- 733,739 ----
the last dump.
Since this is a streaming tape drive, no attempt to verify the
! archive is done. This is also why the high blocking factor (126) is
used. The tape drive must also be rewound by the @code{mt} command
after the dump is made.
***************
*** 748,766 ****
pipes and cartridge tape drives.
Some other media can be backspaced, and @code{tar} will work on them
! once it is modifed to do so.
Archives created with the @samp{-M}, @samp{-V}, and @samp{-G}
! options may not be readable by other version of tar. In paticular,
! restoring a file that was split over a a volume boundry will require
! some careful work with DD, if it can be done at all. Other versions
of @code{tar} may also create an empty file whose name is that of
the volume header. Some versions of @code{tar} may created normal
files instead of directories archived with the @samp{-G} option.
@chapter The Remote Tape Server
! @node RemTape, IncDumps, Format, Top
In order to access the tape drive on a remote machine, @code{tar}
uses the remote tape server written at the University of California
at Berkeley. The remote tape server must be installed as
--- 755,773 ----
pipes and cartridge tape drives.
Some other media can be backspaced, and @code{tar} will work on them
! once it is modified to do so.
Archives created with the @samp{-M}, @samp{-V}, and @samp{-G}
! options may not be readable by other version of tar. In particular,
! restoring a file that was split over a volume boundary will require
! some careful work with @code{dd}, if it can be done at all. Other versions
of @code{tar} may also create an empty file whose name is that of
the volume header. Some versions of @code{tar} may created normal
files instead of directories archived with the @samp{-G} option.
@chapter The Remote Tape Server
! @node Rem Tape, IncDumps, Format, Top
In order to access the tape drive on a remote machine, @code{tar}
uses the remote tape server written at the University of California
at Berkeley. The remote tape server must be installed as
***************
*** 778,790 ****
non-4.3BSD system.
@chapter The Format of a @code{tar} Archive
! @node Format, RemTape, , Top
! This chapter is based heavily on John Gilmore's tar.5 manual page
for the public domain @code{tar} that GNU @code{tar} is based on.
@section The Standard Format
! A @code{tar tape} or file contains a series of records. Each record
! contains RECORDSIZE bytes (FOO pxref). Although this format may be
thought of as being on magnetic tape, other media are often used.
Each file archived is represented by a header record which describes
--- 785,797 ----
non-4.3BSD system.
@chapter The Format of a @code{tar} Archive
! @node Format, Rem Tape, , Top
! This chapter is based heavily on John Gilmore's @i{tar}(5) manual page
for the public domain @code{tar} that GNU @code{tar} is based on.
@section The Standard Format
! A @dfn{tar tape} or file contains a series of records. Each record
! contains @code{RECORDSIZE} bytes. Although this format may be
thought of as being on magnetic tape, other media are often used.
Each file archived is represented by a header record which describes
***************
*** 796,802 ****
The records may be @dfn{blocked} for physical I/O operations. Each
block of @var{N} records (where @var{N} is set by the @samp{-b}
! option to @code{tar} is written with a single @code{write()}
operation. On magnetic tapes, the result of such a write is a
single tape record. When writing an archive, the last block of
records should be written at the full size, with records after the
--- 803,809 ----
The records may be @dfn{blocked} for physical I/O operations. Each
block of @var{N} records (where @var{N} is set by the @samp{-b}
! option to @code{tar}) is written with a single @code{write()}
operation. On magnetic tapes, the result of such a write is a
single tape record. When writing an archive, the last block of
records should be written at the full size, with records after the
***************
*** 899,909 ****
The @code{mode} field provides nine bits specifying file permissions
and three bits to specify the Set UID, Set GID, and Save Text
! (TSVTX) modes. Values for these bits are defined above. When
special permissions are required to create a file with a given mode,
and the user restoring files from the archive does not hold such
permissions, the mode bit(s) specifying those special permissions
! are ignored. Modes which are not supported by the operating
restoring files from the archive will be ignored. Unsupported modes
should be faked up when creating or updating an archive; e.g. the
group permission could be copied from the @code{other} permission.
--- 906,916 ----
The @code{mode} field provides nine bits specifying file permissions
and three bits to specify the Set UID, Set GID, and Save Text
! (``sticky'') modes. Values for these bits are defined above. When
special permissions are required to create a file with a given mode,
and the user restoring files from the archive does not hold such
permissions, the mode bit(s) specifying those special permissions
! are ignored. Modes which are not supported by the operating system
restoring files from the archive will be ignored. Unsupported modes
should be faked up when creating or updating an archive; e.g. the
group permission could be copied from the @code{other} permission.
***************
*** 914,923 ****
ignored.
The @code{size} field is the size of the file in bytes; linked files
! are archived with this field specified as zero. FOO xref to -G here
The @code{mtime} field is the modification time of the file at the
! time it was archived. It is the ASCII repersentation of the octal
value of the last time the file was modified, represented as an
integer number of seconds since January 1, 1970, 00:00 Coordinated
Universal Time.
--- 921,931 ----
ignored.
The @code{size} field is the size of the file in bytes; linked files
! are archived with this field specified as zero.
! @xref{Extraction Options}; in particular the @samp{-G} option.@refill
The @code{mtime} field is the modification time of the file at the
! time it was archived. It is the ASCII representation of the octal
value of the last time the file was modified, represented as an
integer number of seconds since January 1, 1970, 00:00 Coordinated
Universal Time.
***************
*** 936,948 ****
error.
@table @code
! @itemx LF_NORMAL
! @item LF_OLDNORMAL
! These represent a regular file. In order to be compatable with
older versions of @code{tar}, a @code{typeflag} value of
@code{LF_OLDNORMAL} should be silently recognized as a regular
file. New archives should be created using @code{LF_NORMAL}. Also,
! for backward compatability, @code{tar} treats a regular file whose
name ends with a slash as a directory.
@item LF_LINK
--- 944,956 ----
error.
@table @code
! @item LF_NORMAL
! @itemx LF_OLDNORMAL
! These represent a regular file. In order to be compatible with
older versions of @code{tar}, a @code{typeflag} value of
@code{LF_OLDNORMAL} should be silently recognized as a regular
file. New archives should be created using @code{LF_NORMAL}. Also,
! for backward compatibility, @code{tar} treats a regular file whose
name ends with a slash as a directory.
@item LF_LINK
***************
*** 955,962 ****
This represents a symbolic link to another file. The linked-to
name is specified in the @code{linkname} field with a trailing null.
! @itemx LF_CHR
! @item FL_BLK
These represent character special files and block special files
respectively. In this case the @code{devmajor} and @code{devminor}
fields will contain the major and minor device numbers
--- 963,970 ----
This represents a symbolic link to another file. The linked-to
name is specified in the @code{linkname} field with a trailing null.
! @item LF_CHR
! @itemx LF_BLK
These represent character special files and block special files
respectively. In this case the @code{devmajor} and @code{devminor}
fields will contain the major and minor device numbers
***************
*** 984,1000 ****
systems which do not allow contiguous allocation should silently treat
this type as a normal file.
! @itemx A @dots{}
! @item Z
These are reserved for custom implementations. Some of these are
used in the GNU modified format, as described below.
@end table
! Other values are reserverd for specification in future revisions of
! the p1003 standard, and should not be used by any @code{tar} program.
The @code{magic} field indicates that this archive was output in the
! p1003 archive format. If this field contains @code{TMAGIC}, the
@code{uname} and @code{gname} fields will contain the ASCII
representation of the owner and group of the file respectively. if
found, the user and group ID represented by these names will be used
--- 992,1008 ----
systems which do not allow contiguous allocation should silently treat
this type as a normal file.
! @item 'A' @dots{}
! @itemx 'Z'
These are reserved for custom implementations. Some of these are
used in the GNU modified format, as described below.
@end table
! Other values are reserved for specification in future revisions of
! the P1003 standard, and should not be used by any @code{tar} program.
The @code{magic} field indicates that this archive was output in the
! P1003 archive format. If this field contains @code{TMAGIC}, the
@code{uname} and @code{gname} fields will contain the ASCII
representation of the owner and group of the file respectively. if
found, the user and group ID represented by these names will be used
***************
*** 1005,1012 ****
files in an archive. These are listed below.
@table @code
! @itemx LF_DUMPDIR
! @item 'D'
This represents a directory and a list of files created by the
@samp{-G} option. The @code{size} field gives the total size of the
associated list of files. Each filename is preceded by either a 'Y'
--- 1013,1020 ----
files in an archive. These are listed below.
@table @code
! @item LF_DUMPDIR
! @itemx 'D'
This represents a directory and a list of files created by the
@samp{-G} option. The @code{size} field gives the total size of the
associated list of files. Each filename is preceded by either a 'Y'
***************
*** 1015,1022 ****
terminated by a null. There is an additional null after the last
filename.
! @itemx LF_MULTIVOL
! @item 'M'
This represents a file continued from another volume of a
multi-volume archive created with the @samp{-M} option. The original
type of the file is not given here. The @code{size} field gives the
--- 1023,1030 ----
terminated by a null. There is an additional null after the last
filename.
! @item LF_MULTIVOL
! @itemx 'M'
This represents a file continued from another volume of a
multi-volume archive created with the @samp{-M} option. The original
type of the file is not given here. The @code{size} field gives the
***************
*** 1026,1033 ****
file begins. Thus @code{size} plus @code{offset} should equal the
original size of the file.
! @itemx LF_VOLHDR
! @item 'V'
This file type is used to mark the volume header that was given with
the @samp{-V} option when the archive was created. The @code{name}
field contains the @code{name} given after the @samp{-V} option.
--- 1034,1041 ----
file begins. Thus @code{size} plus @code{offset} should equal the
original size of the file.
! @item LF_VOLHDR
! @itemx 'V'
This file type is used to mark the volume header that was given with
the @samp{-V} option when the archive was created. The @code{name}
field contains the @code{name} given after the @samp{-V} option.
***************
*** 1039,1042 ****
--- 1047,1051 ----
You may have trouble reading a GNU format archive on a non-GNU system
if the options @samp{-G}, @samp{-M} or @samp{-V} were used when writing
the archive.
+ @contents
@bye