Index of Section 1 Manual Pages
| Interix / SUA | tar.1 | Interix / SUA |
TAR(1) System General Commands Manual TAR(1)
NAME
tar - tape archiver
SYNOPSIS
tar [-]{crtux}[befhjkmopqsvwyzBHLNOPUQXZ014578] [blocksize] [archive]
[replstr] [-C directory] [-I file] [file ...]
DESCRIPTION
The tar command creates, adds files to, or extracts files from an archive
file in ``tar'' format. A tar archive is often stored on a magnetic
tape, but can be stored equally well on a floppy, CD-ROM, or in a regular
disk file.
One of the following flags must be present:
-c, --create Create new archive, or overwrite an existing archive,
adding the specified files to it.
-r, --append Append the named new files to existing archive. Note that
this will only work on media on which an end-of-file mark
can be overwritten.
-t, --list List contents of archive. If any files are named on the
command line, only those files will be listed.
-u, --update Alias for -r.
-x, --extract
Extract files from archive. If any files are named on the
command line, only those files will be extracted from the
archive. If more than one copy of a file exists in the
archive, later copies will overwrite earlier copies during
extraction. The file mode and modification time are pre-
served if possible. The file mode is subject to modifica-
tion by the umask(2).
In addition to the flags mentioned above, any of the following flags may
be used:
-b size, --block-size size
Set blocking factor as size to use for the archive. tar
uses 512 byte blocks. The default is 20, the maximum is
126. Archives with a blocking factor larger than 63 vio-
late the POSIX standard and will not be portable to all
systems.
-e Stop after the first error.
-f archive, --file archive
Filename where the archive is stored. Defaults to
/dev/tape0.
-h, --dereference
Follow symbolic links as if they were normal files or
directories. In extract mode this means that a directory
entry in the archive will not overwrite an existing sym-
bolic link, but rather what the link ultimately points to.
-j Same as option -y. Compress archive using bzip2.
-k Do not overwrite existing files whether they previously
existed or were recently extracted from this acrchive. Only
useful with the -x option.
-l Report files that are symbolic links that do not resolve to
existing files. By default no message is provided.
-m, --modification-time
Do not preserve modification time.
-o Extracted files will have the user and group id's of the
performing the extraction. This is the default action for
tar and is provided for the standards.
-p, --same-permission, -preserve-permissions
Preserve user and group ID as well as file mode regardless
of the current umask(2). The setuid and setgid bits are
only preserved if the user is the superuser. Only meaning-
ful in conjunction with the -x flag.
-q Select the first archive member that matches each pattern
operand. No more than one archive member is matched for
each pattern. When members of type directory are matched,
the file hierarchy rooted at that directory is also
matched.
-s replstr Modify the file or archive member names specified by the
pattern or file operands according to the substitution
expression replstr, using the syntax of the ed(1) utility
regular expressions. The format of these regular expres-
sions are:
/old/new/[gp]
As in ed(1), old is a basic regular expression and new can
contain an ampersand (&), \n (where n is a digit) back-ref-
erences, or subexpression matching. The old string may
also contain characters. Any non-null character
can be used as a delimiter (/ is shown here). Multiple -s
expressions can be specified. The expressions are applied
in the order they are specified on the command line, termi-
nating with the first successful substitution. The
optional trailing g continues to apply the substitution
expression to the pathname substring which starts with the
first character following the end of the last successful
substitution. The first unsuccessful substitution stops
the operation of the g option. The optional trailing p
will cause the final result of a successful substitution to
be written to standard error in the following format:
>>
File or archive member names that substitute to the empty
string are not selected and will be skipped.
-v, --verbose
Verbose operation mode.
-w, --interactive, --confirmation
Interactively rename files. This option causes tar to
prompt the user for the filename to use when storing or
extracting files in an archive.
-y Compress archive using bzip2.
-z, --gzip, --gunzip
Compress archive using gzip.
-B This is the tar default.
-C directory, --directory directory
This is a positional argument which sets the working direc-
tory for the following files. When extracting, files will
be extracted into the specified directory; when creating,
the specified files will be matched from the directory.
-H Follow symlinks given on command line only.
-L Follow all symlinks. In extract mode this means that a
directory entry in the archive will not overwrite an exist-
ing symbolic link, but rather what the link ultimately
points to.
-N Display numeric uid and gid values when listing the con-
tents of an archive instead of displaying the user and
group names. This is useful when evaluating the contents
of an archive in relationship to -p.
-O, --old-archive, --portability
Write old-style (non-POSIX) archives.
-P, --absolute-paths
Do not strip leading slashes (`/') from pathnames. Note:
this is a change in behavior from the previous Interix
releases, but essential de facto on most systems.
-Q Quiet warnings about files being archived without addi-
tional ACL information being stored in the archive. This
relates to S_ADDACE with stat(3) on Interix only.
-I file This is a positional argument which reads the names of
files to archive or extract from the given file, one per
line.
-X Do not cross mount points in the file system.
-Z, --compress, --uncompress
Compress archive using compress.
The options [-014578] can be used to select one of the compiled-in backup
devices, /dev/rstN.
EXAMPLES
$ tar c bonvole sekve
Creates an archive on the default tape drive, containing the files named
bonvole and sekve
$ tar zcf foriru.tar.gz bonvole sekve
Outputs a gzip(1) compressed archive containing the files bonvole and
sekve to a file called foriru.tar.gz
$ tar zcvf backup.tar.gz *.c
Verbosely creates an archive, called backup.tar.gz, of all files matching
the shell glob(3) function *.c
$ tar tvzf backup.tar.gz '*.jpeg'
Verbosely lists, but does not extract, all files ending in .jpeg from an
compressed archive named backup.tar.gz. Note that the glob pattern has
been quoted to avoid expansion by the shell.
For more detailed examples, see pax(1)
DIAGNOSTICS
tar will exit with one of the following values:
0 All files were processed successfully.
1 An error occurred.
Whenever tar cannot create a file or a link when extracting an archive or
cannot find a file while writing an archive, or cannot preserve the user
ID, group ID, file mode, or access and modification times when the -p
option is specified, a diagnostic message is written to standard error
and a non-zero exit value will be returned, but processing will continue.
In the case where tar cannot create a link to a file, tar will not create
a second copy of the file.
If the extraction of a file from an archive is prematurely terminated by
a signal or error, tar may have only partially extracted the file the
user wanted. Additionally, the file modes of extracted files and direc-
tories may have incorrect file bits, and the modification and access
times may be wrong.
If the creation of an archive is prematurely terminated by a signal or
error, tar may have only partially created the archive which may violate
the specific archive format specification.
FILES
/dev/tape0 default archive name
ENVIRONMENT
TMPDIR Path in which to store temporary files.
TAPE Default tape device to use instead of /dev/tape0.
SEE ALSO
cpio(1), pax(1), stat(3)
AUTHORS
Keith Muller at the University of California, San Diego.
HISTORY
A tar command first appeared in Version 7 AT&T UNIX.
CAVEATS
The -L flag is not portable to other versions of tar where it may have a
different meaning.
When an archive is being extracted the target files will be unlinked by
default before the file from the archive is written unless the k option
is specified. This means that when a target file is a hard link the
archive file will not accidentally overwrite the other files that are
part of the same hard link.
On many Unix (and similar) systems the UID's and GID's fit into a 16-bit
value. On Interix some UID and GID values are larger than this using up
to 32-bits. These UID and GID values larger than will fit in 16-bits
overflow the tar and ustar archive formats. Therefore, for portability
when values are too large the ID value of 32666 will be used.
You may see an error message with some extractions because of this (the
ID cannot be preserved). However, using the ustar format recording char-
acter string representations of the GID's and UID's will eliminate this
problem.
When a file or directory is encountered that has additional ACL (Access
Control List) information beyond the basic POSIX file permissions a warn-
ing is printed along with the pathname. The additional ACL information
cannot be stored in the archive. But this is not treated as an error and
tar continues to create the archive. The base cause of this warning is
usually related to a file or directory having been created by a Win32
application.
Archive files with leading slashes will have the slashes removed which is
not historical practice, but is current de facto practice for security.
Interix September 22, 2007 Interix