filesystem. You should have some basic understanding of directory
structure and how files are named according to which directory they are
in. You should understand concepts such as standard output and standard
filesystem. You should have some basic understanding of directory
structure and how files are named according to which directory they are
in. You should understand concepts such as standard output and standard
-input, what various definitions of the term ``argument'' mean, the
-differences between relative and absolute path names, and @FIXME{what
-else?}.
+input, what various definitions of the term ``argument'' mean, and the
+differences between relative and absolute path names. @FIXME{and what
+else?}
Whenever you use @samp{create}, @code{tar} will erase the current
contents of the file named by @value{op-file} if it exists. @code{tar}
will not tell you if you are about to overwrite a file unless you
Whenever you use @samp{create}, @code{tar} will erase the current
contents of the file named by @value{op-file} if it exists. @code{tar}
will not tell you if you are about to overwrite a file unless you
-specify an option which does this @FIXME{xref to the node for
---backup!}. To add files to an existing archive, you need to use a
+specify an option which does this. @FIXME{xref to the node for
+--backup!} To add files to an existing archive, you need to use a
different option, such as @value{op-append}; see @ref{append} for
information on how to do this.
different option, such as @value{op-append}; see @ref{append} for
information on how to do this.
(@file{collection.tar}), and @samp{--file} is the option which lets
you give it the name you chose. The files, @file{blues}, @file{folk},
and @file{jazz}, are now members of the archive, @file{collection.tar}
(@file{collection.tar}), and @samp{--file} is the option which lets
you give it the name you chose. The files, @file{blues}, @file{folk},
and @file{jazz}, are now members of the archive, @file{collection.tar}
-(they are @dfn{file name arguments} to the @samp{--create} operation)
-@FIXME{xref here to the discussion of file name args?}. Now that they
+(they are @dfn{file name arguments} to the @samp{--create} operation).
+@FIXME{xref here to the discussion of file name args?} Now that they
When you create an archive, you @emph{must} specify which files you want
placed in the archive. If you do not specify any archive members, GNU
When you create an archive, you @emph{must} specify which files you want
placed in the archive. If you do not specify any archive members, GNU
(@emph{Please note:} Other versions of @code{tar} are not so clever;
they will enter an infinite loop when this happens, so you should not
depend on this behavior unless you are certain you are running GNU
(@emph{Please note:} Other versions of @code{tar} are not so clever;
they will enter an infinite loop when this happens, so you should not
depend on this behavior unless you are certain you are running GNU
all the time, and we've been doing it in the editing passes for this
manual: In general, make sure that the archive is not inside a
all the time, and we've been doing it in the editing passes for this
manual: In general, make sure that the archive is not inside a
@node list, extract, create, Tutorial
@section How to List Archives
@node list, extract, create, Tutorial
@section How to List Archives
@item --backup=@var{backup-type}
Rather than deleting files from the file system, @code{tar} will back them up
using simple or numbered backups, depending upon @var{backup-type}.
@item --backup=@var{backup-type}
Rather than deleting files from the file system, @code{tar} will back them up
using simple or numbered backups, depending upon @var{backup-type}.
@item --blocking-factor=@var{blocking}
@itemx -b @var{blocking}
Sets the blocking factor @code{tar} uses to @var{blocking} x 512 bytes per
@item --blocking-factor=@var{blocking}
@itemx -b @var{blocking}
Sets the blocking factor @code{tar} uses to @var{blocking} x 512 bytes per
@item --checkpoint
This option directs @code{tar} to print periodic checkpoint messages as it
reads through the archive. Its intended for when you want a visual
indication that @code{tar} is still running, but don't want to see
@item --checkpoint
This option directs @code{tar} to print periodic checkpoint messages as it
reads through the archive. Its intended for when you want a visual
indication that @code{tar} is still running, but don't want to see
@code{tar} will use the @code{compress} program when reading or writing the
archive. This allows you to directly act on archives while saving
@code{tar} will use the @code{compress} program when reading or writing the
archive. This allows you to directly act on archives while saving
@item --directory=@var{dir}
@itemx -C @var{dir}
When this option is specified, @code{tar} will change its current directory
to @var{dir} before performing any operations. When this option is used
@item --directory=@var{dir}
@itemx -C @var{dir}
When this option is specified, @code{tar} will change its current directory
to @var{dir} before performing any operations. When this option is used
@item --exclude=@var{pattern}
When performing operations, @code{tar} will skip files that match
@item --exclude=@var{pattern}
When performing operations, @code{tar} will skip files that match
@item --exclude-from=@var{file}
@itemx -X @var{file}
Similar to @samp{--exclude}, except @code{tar} will use the list of patterns
@item --exclude-from=@var{file}
@itemx -X @var{file}
Similar to @samp{--exclude}, except @code{tar} will use the list of patterns
@item --file=@var{archive}
@itemx -f @var{archive}
@code{tar} will use the file @var{archive} as the @code{tar} archive it
performs operations on, rather than @code{tar}'s compilation dependent
@item --file=@var{archive}
@itemx -f @var{archive}
@code{tar} will use the file @var{archive} as the @code{tar} archive it
performs operations on, rather than @code{tar}'s compilation dependent
@item --files-from=@var{file}
@itemx -T @var{file}
@code{tar} will use the contents of @var{file} as a list of archive members
or files to operate on, in addition to those specified on the
@item --files-from=@var{file}
@itemx -T @var{file}
@code{tar} will use the contents of @var{file} as a list of archive members
or files to operate on, in addition to those specified on the
@item --group=@var{group}
Files added to the @code{tar} archive will have a group id of @var{group},
rather than the group from the source file. @var{group} is first decoded
as a group symbolic name, but if this interpretation fails, it has to be
@item --group=@var{group}
Files added to the @code{tar} archive will have a group id of @var{group},
rather than the group from the source file. @var{group} is first decoded
as a group symbolic name, but if this interpretation fails, it has to be
This option tells @code{tar} to read or write archives through @code{gzip},
allowing @code{tar} to directly operate on several kinds of compressed
This option tells @code{tar} to read or write archives through @code{gzip},
allowing @code{tar} to directly operate on several kinds of compressed
Used to inform @code{tar} that it is working with an old GNU-format
incremental backup archive. It is intended primarily for backwards
Used to inform @code{tar} that it is working with an old GNU-format
incremental backup archive. It is intended primarily for backwards
@item --info-script=@var{script-file}
@itemx --new-volume-script=@var{script-file}
@itemx -F @var{script-file}
When @code{tar} is performing multi-tape backups, @var{script-file} is run
@item --info-script=@var{script-file}
@itemx --new-volume-script=@var{script-file}
@itemx -F @var{script-file}
When @code{tar} is performing multi-tape backups, @var{script-file} is run
Specifies that @code{tar} should ask the user for confirmation before
performing potentially destructive options, such as overwriting files.
Specifies that @code{tar} should ask the user for confirmation before
performing potentially destructive options, such as overwriting files.
When creating an archive, instructs @code{tar} to write @var{name} as a name
record in the archive. When extracting or listing archives, @code{tar} will
only operate on archives that have a label matching the pattern
When creating an archive, instructs @code{tar} to write @var{name} as a name
record in the archive. When extracting or listing archives, @code{tar} will
only operate on archives that have a label matching the pattern
@code{tar} creates is a new GNU-format incremental backup, using
@var{snapshot-file} to determine which files to backup.
With other operations, informs @code{tar} that the archive is in incremental
@code{tar} creates is a new GNU-format incremental backup, using
@var{snapshot-file} to determine which files to backup.
With other operations, informs @code{tar} that the archive is in incremental
@item --null
When @code{tar} is using the @samp{--files-from} option, this option
instructs @code{tar} to expect filenames terminated with @kbd{NUL}, so
@code{tar} can correctly work with file names that contain newlines.
@item --null
When @code{tar} is using the @samp{--files-from} option, this option
instructs @code{tar} to expect filenames terminated with @kbd{NUL}, so
@code{tar} can correctly work with file names that contain newlines.
@item --one-file-system
@itemx -l
Used when creating an archive. Prevents @code{tar} from recursing into
directories that are on different file systems from the current
@item --one-file-system
@itemx -l
Used when creating an archive. Prevents @code{tar} from recursing into
directories that are on different file systems from the current
when creating archives, instead of the user associated with the source
file. @var{user} is first decoded as a user symbolic name, but if
this interpretation fails, it has to be a decimal numeric user ID.
when creating archives, instead of the user associated with the source
file. @var{user} is first decoded as a user symbolic name, but if
this interpretation fails, it has to be a decimal numeric user ID.
There is no value indicating a missing number, and @samp{0} usually means
@code{root}. Some people like to force @samp{0} as the value to offer in
There is no value indicating a missing number, and @samp{0} usually means
@code{root}. Some people like to force @samp{0} as the value to offer in
@item --record-size=@var{size}
Instructs @code{tar} to use @var{size} bytes per record when accessing the
@item --record-size=@var{size}
Instructs @code{tar} to use @var{size} bytes per record when accessing the
@item --rsh-command=@var{cmd}
Notifies @code{tar} that is should use @var{cmd} to communicate with remote
@item --rsh-command=@var{cmd}
Notifies @code{tar} that is should use @var{cmd} to communicate with remote
@item --show-omitted-dirs
Instructs @code{tar} to mention directories its skipping over when operating
@item --show-omitted-dirs
Instructs @code{tar} to mention directories its skipping over when operating
@item --use-compress-program=@var{prog}
Instructs @code{tar} to access the archive through @var{prog}, which is
@item --use-compress-program=@var{prog}
Instructs @code{tar} to access the archive through @var{prog}, which is
@item --verbose
@itemx -v
Specifies that @code{tar} should be more verbose about the operations its
performing. This option can be specified multiple times for some
@item --verbose
@itemx -v
Specifies that @code{tar} should be more verbose about the operations its
performing. This option can be specified multiple times for some
@item --volno-file=@var{file}
Used in conjunction with @samp{--multi-volume}. @code{tar} will keep track
of which volume of a multi-volume archive its working in @var{file}.
@item --volno-file=@var{file}
Used in conjunction with @samp{--multi-volume}. @code{tar} will keep track
of which volume of a multi-volume archive its working in @var{file}.
@end table
@node Short Option Summary, , Option Summary, All Options
@end table
@node Short Option Summary, , Option Summary, All Options
choose among several backup tapes when retrieving a file later, in
favor of the tape where the file appears earliest (closest to the
front of the tape). @FIXME-xref{when the node name is set and the
choose among several backup tapes when retrieving a file later, in
favor of the tape where the file appears earliest (closest to the
front of the tape). @FIXME-xref{when the node name is set and the
@node interactive, , verbose, tar invocation
@section Asking for Confirmation During Operations
@node interactive, , verbose, tar invocation
@section Asking for Confirmation During Operations
MMwtSN node; not sure. i didn't know how to make it simpler...}
There are a few ways to get around this. @FIXME-xref{Multiple Members
MMwtSN node; not sure. i didn't know how to make it simpler...}
There are a few ways to get around this. @FIXME-xref{Multiple Members
@cindex Members, replacing with other members
@cindex Replacing members with other members
@cindex Members, replacing with other members
@cindex Replacing members with other members
overwritten by the newer version. You can confirm this by extracting
the archive and running @samp{ls} on the directory. @xref{Writing},
for more information. (@emph{Please note:} This is the case unless
overwritten by the newer version. You can confirm this by extracting
the archive and running @samp{ls} on the directory. @xref{Writing},
for more information. (@emph{Please note:} This is the case unless
with the Same Name}.)
@node update, concatenate, append, Advanced tar
with the Same Name}.)
@node update, concatenate, append, Advanced tar
Both @samp{--update} and @samp{--append} work by adding to the end
of the archive. When you extract a file from the archive, only the
version stored last will wind up in the file system, unless you use
Both @samp{--update} and @samp{--append} work by adding to the end
of the archive. When you extract a file from the archive, only the
version stored last will wind up in the file system, unless you use
command line. (Nothing happens if you don't list any.) The members,
and their member names, will be copied verbatim from those archives. If
this causes multiple members to have the same name, it does not delete
command line. (Nothing happens if you don't list any.) The members,
and their member names, will be copied verbatim from those archives. If
this causes multiple members to have the same name, it does not delete
-any members; all the members with the same name coexist. For
-information on how this affects reading the archive, @FIXME-ref{Multiple
-Members with the Same Name}.
+any members; all the members with the same name coexist. @FIXME-ref{For
+information on how this affects reading the archive, Multiple
+Members with the Same Name.}
To demonstrate how @samp{--concatenate} works, create two small archives
called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
To demonstrate how @samp{--concatenate} works, create two small archives
called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
When you use @samp{--concatenate}, the source and target archives must
already exist and must have been created using compatable format
When you use @samp{--concatenate}, the source and target archives must
already exist and must have been created using compatable format
concatenated archive will be called by the same name as the first
archive listed on the command line. @FIXME{is there a way to specify a
new name?}
concatenated archive will be called by the same name as the first
archive listed on the command line. @FIXME{is there a way to specify a
new name?}
Before you use these scripts, you need to edit the file
@file{backup-specs}, which specifies parameters used by the backup
scripts and by the restore script. @FIXME{There is no such restore
Before you use these scripts, you need to edit the file
@file{backup-specs}, which specifies parameters used by the backup
scripts and by the restore script. @FIXME{There is no such restore
are set, you can perform backups or restoration by running the
appropriate script.
The name of the restore script is @code{restore}. @FIXME{There is
are set, you can perform backups or restoration by running the
appropriate script.
The name of the restore script is @code{restore}. @FIXME{There is
scripts are, respectively, @code{level-1} and @code{level-0}.
The @code{level-0} script also exists under the name @code{weekly}, and
the @code{level-1} under the name @code{daily}---these additional names
can be changed according to your backup schedule. @FIXME-xref{Scripted
scripts are, respectively, @code{level-1} and @code{level-0}.
The @code{level-0} script also exists under the name @code{weekly}, and
the @code{level-1} under the name @code{daily}---these additional names
can be changed according to your backup schedule. @FIXME-xref{Scripted
-Restoration}, for more information on running the restoration script.
-@FIXME-xref{Scripted Backups}, for more information on running the
-backup scripts.
+Restoration, for more information on running the restoration script.}
+@FIXME-xref{Scripted Backups, for more information on running the
+backup scripts.}
@emph{Please Note:} The backup scripts and the restoration scripts are
designed to be used together. While it is possible to restore files by
hand from an archive which was created using a backup script, and to create
an archive by hand which could then be extracted using the restore script,
@emph{Please Note:} The backup scripts and the restoration scripts are
designed to be used together. While it is possible to restore files by
hand from an archive which was created using a backup script, and to create
an archive by hand which could then be extracted using the restore script,
@value{xref-incremental}, and @value{xref-listed-incremental},
before making such an attempt.
@value{xref-incremental}, and @value{xref-listed-incremental},
before making such an attempt.
@FIXME{This about backup scripts needs to be written: BS is a shell
script .... thus ... @file{backup-specs} is in shell script syntax.}
@FIXME{This about backup scripts needs to be written: BS is a shell
script .... thus ... @file{backup-specs} is in shell script syntax.}
@FIXME{Whats a parameter .... looked at by the backup scripts
... which will be expecting to find ... now syntax ... value is linked
@FIXME{Whats a parameter .... looked at by the backup scripts
... which will be expecting to find ... now syntax ... value is linked
where @var{time-to-be-run} can be a specific system time, or can be
@kbd{now}. If you do not specify a time, the script runs at the time
where @var{time-to-be-run} can be a specific system time, or can be
@kbd{now}. If you do not specify a time, the script runs at the time
You should start a script with a tape or disk mounted. Once you
start a script, it prompts you for new tapes or disks as it
You should start a script with a tape or disk mounted. Once you
start a script, it prompts you for new tapes or disks as it
The @code{restore} script prompts for media by its archive volume,
so to avoid an error message you should keep track of which tape
(or disk) contains which volume of the archive. @FIXME{There is
The @code{restore} script prompts for media by its archive volume,
so to avoid an error message you should keep track of which tape
(or disk) contains which volume of the archive. @FIXME{There is
@FIXME{Have file names changed?}
The backup scripts write two files on the file system. The first is a
record file in @file{/etc/tar-backup/}, which is used by the scripts
to store and retrieve information about which files were dumped. This
file is not meant to be read by humans, and should not be deleted by
@FIXME{Have file names changed?}
The backup scripts write two files on the file system. The first is a
record file in @file{/etc/tar-backup/}, which is used by the scripts
to store and retrieve information about which files were dumped. This
file is not meant to be read by humans, and should not be deleted by
-them. @FIXME-xref{incremental and listed-incremental}, for a more
-detailed explanation of this file.
+them. @FIXME-xref{incremental and listed-incremental, for a more
+detailed explanation of this file.}
The second file is a log file containing the names of the file systems
and files dumped, what time the backup was made, and any error
The second file is a log file containing the names of the file systems
and files dumped, what time the backup was made, and any error
volumes as they are needed. If the archive is on tape, you don't need
to rewind the tape to to its beginning---if the tape head is
positioned past the beginning of the archive, the script will rewind
volumes as they are needed. If the archive is on tape, you don't need
to rewind the tape to to its beginning---if the tape head is
positioned past the beginning of the archive, the script will rewind
If you specify @samp{--all} as the @var{files} argument, the
@code{restore} script extracts all the files in the archived file
If you specify @samp{--all} as the @var{files} argument, the
@code{restore} script extracts all the files in the archived file
By default, @code{tar} takes file names from the command line. However,
there are other ways to specify file or member names, or to modify the
manner in which @code{tar} selects the files or members upon which to
By default, @code{tar} takes file names from the command line. However,
there are other ways to specify file or member names, or to modify the
manner in which @code{tar} selects the files or members upon which to
specifying the names of files and archive members.
@node files, exclude, Selecting Archive Members, Choosing
specifying the names of files and archive members.
@node files, exclude, Selecting Archive Members, Choosing
@node recurse, one, after, Choosing
@section Descending into Directories
@node recurse, one, after, Choosing
@section Descending into Directories
@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some
format parameters must be taken into consideration when modifying an
@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some
format parameters must be taken into consideration when modifying an
You can use @samp{--gzip} and @samp{--gunzip} on physical devices
(tape drives, etc.) and remote files as well as on normal files; data
You can use @samp{--gzip} and @samp{--gunzip} on physical devices
(tape drives, etc.) and remote files as well as on normal files; data
When writing an archive, @code{tar} writes the user id and user name
separately. If it can't find a user name (because the user id is not
in @file{/etc/passwd}), then it does not write one. When restoring,
When writing an archive, @code{tar} writes the user id and user name
separately. If it can't find a user name (because the user id is not
in @file{/etc/passwd}), then it does not write one. When restoring,
-and doing a @code{chmod} like when you use @value{op-same-permissions}
-(@FIXME{same-owner?}), it tries to look the name (if one was written)
+and doing a @code{chmod} like when you use @value{op-same-permissions},
+@FIXME{same-owner?} it tries to look the name (if one was written)
up in @file{/etc/passwd}. If it fails, then it uses the user id
stored in the archive instead.
up in @file{/etc/passwd}. If it fails, then it uses the user id
stored in the archive instead.
Archives are permitted to have more than one member with the same
member name. One way this situation can occur is if more than one
version of a file has been stored in the archive. For information
Archives are permitted to have more than one member with the same
member name. One way this situation can occur is if more than one
version of a file has been stored in the archive. For information
-about adding new versions of a file to an archive, see @ref{update},
-and to learn more about having more than one archive member with the
-same name, see @FIXME-xref{-backup node, when it's written}.
+about adding new versions of a file to an archive, see @ref{update}.
+@FIXME-xref{To learn more about having more than one archive member with the
+same name, see -backup node, when it's written.}
In addition to entries describing archive members, an archive may
contain entries which @code{tar} itself uses to store information.
In addition to entries describing archive members, an archive may
contain entries which @code{tar} itself uses to store information.
not support numeric user or group IDs, these fields should be ignored.
The @code{size} field is the size of the file in bytes; linked files
not support numeric user or group IDs, these fields should be ignored.
The @code{size} field is the size of the file in bytes; linked files
-are archived with this field specified as zero. @FIXME-xref{Modifiers}, in
-particular the @value{op-incremental} option.
+are archived with this field specified as zero. @FIXME-xref{Modifiers, in
+particular the @value{op-incremental} option.}
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 @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
Before reading an archive, you should make sure the tape head is at
the beginning of the archive you want to read. (The @code{restore}
script will find the archive automatically. @FIXME{There is no such
Before reading an archive, you should make sure the tape head is at
the beginning of the archive you want to read. (The @code{restore}
script will find the archive automatically. @FIXME{There is no such
an explanation of the tape moving utility.
If you want to add new archive file entries to a tape, you should
an explanation of the tape moving utility.
If you want to add new archive file entries to a tape, you should
on it) and print an error if the archive label doesn't match the
@var{archive-name} specified. @var{archive-name} can be any regular
expression. If the labels match, @code{tar} extracts the archive.
on it) and print an error if the archive label doesn't match the
@var{archive-name} specified. @var{archive-name} can be any regular
expression. If the labels match, @code{tar} extracts the archive.
@var{volume-label} as the name of the archive to the front of the archive
which will be displayed when the archive is listed with @value{op-list}.
If you are creating a multi-volume archive with @value{op-multi-volume}
@var{volume-label} as the name of the archive to the front of the archive
which will be displayed when the archive is listed with @value{op-list}.
If you are creating a multi-volume archive with @value{op-multi-volume}
@samp{Volume @var{nnn}} appended to the name you give, where @var{nnn} is
the number of the volume of the archive. (If you use the @value{op-label}
option when reading an archive, it checks to make sure the label on the
@samp{Volume @var{nnn}} appended to the name you give, where @var{nnn} is
the number of the volume of the archive. (If you use the @value{op-label}
option when reading an archive, it checks to make sure the label on the
@value{op-multi-volume}, each volume of the archive will have an
archive label of the form @samp{@var{archive-label} Volume @var{n}},
where @var{n} is 1 for the first volume, 2 for the next, and so on.
@value{op-multi-volume}, each volume of the archive will have an
archive label of the form @samp{@var{archive-label} Volume @var{n}},
where @var{n} is 1 for the first volume, 2 for the next, and so on.
If you list or extract an archive using @value{op-label}, @code{tar} will
print an error if the archive label doesn't match the @var{archive-label}
If you list or extract an archive using @value{op-label}, @code{tar} will
print an error if the archive label doesn't match the @var{archive-label}
projects / chaz / tar / commitdiff
