BSDTAR(1)                 BSD General Commands Manual                BSDTAR(1)

NAME
     tar - manipulate tape archives

SYNOPSIS
     tar [bundled-flags <args>] [<file> | <pattern> ...]
     tar {-c} [options] [files | directories]
     tar {-r | -u} -f archive-file [options]
         [files | directories]
     tar {-t | -x} [options] [patterns]

DESCRIPTION
     tar creates and manipulates streaming archive files.  This
     implementation can extract from tar, pax, cpio, zip, jar,
     ar, and ISO 9660 cdrom images and can create tar, pax,
     cpio, ar, and shar archives.

     The first synopsis form shows a ``bundled'' option word.
     This usage is provided for compatibility with historical
     implementations.  See COMPATIBILITY below for details.

     The other synopsis forms show the preferred usage.  The
     first option to tar is a mode indicator from the following
     list:
     -c      Create a new archive containing the specified
             items.
     -r      Like -c, but new entries are appended to the
             archive.  Note that this only works on uncom-
             pressed archives stored in regular files.  The -f
             option is required.
     -t      List archive contents to stdout.
     -u      Like -r, but new entries are added only if they
             have a modification date newer than the corre-
             sponding entry in the archive.  Note that this
             only works on uncompressed archives stored in reg-
             ular files.  The -f option is required.
     -x      Extract to disk from the archive.  If a file with
             the same name appears more than once in the
             archive, each copy will be extracted, with later
             copies overwriting (replacing) earlier copies.

     In -c, -r, or -u mode, each specified file or directory is
     added to the archive in the order specified on the command
     line.  By default, the contents of each directory are also
     archived.

     In extract or list mode, the entire command line is read
     and parsed before the archive is opened.  The pathnames or
     patterns on the command line indicate which items in the
     archive should be processed.  Patterns are shell-style
     globbing patterns as documented in tcsh(1).

OPTIONS
     Unless specifically stated otherwise, options are applica-
     ble in all operating modes.

     @archive
             (c and r mode only) The specified archive is
             opened and the entries in it will be appended to
             the current archive.  As a simple example,
                   tar -c -f - newfile @original.tar
             writes a new archive to standard output containing
             a file newfile and all of the entries from
             original.tar.  In contrast,
                   tar -c -f - newfile original.tar
             creates a new archive with only two entries.  Sim-
             ilarly,
                   tar -czf - --format pax @-
             reads an archive from standard input (whose format
             will be determined automatically) and converts it
             into a gzip-compressed pax-format archive on std-
             out.  In this way, tar can be used to convert
             archives from one format to another.

     -b blocksize
             Specify the block size, in 512-byte records, for
             tape drive I/O.  As a rule, this argument is only
             needed when reading from or writing to tape
             drives, and usually not even then as the default
             block size of 20 records (10240 bytes) is very
             common.

     -C directory
             In c and r mode, this changes the directory before
             adding the following files.  In x mode, change
             directories after opening the archive but before
             extracting entries from the archive.

     --check-links (-W check-links)
             (c and r modes only) Issue a warning message
             unless all links to each file are archived.

     --exclude pattern (-W exclude=pattern)
             Do not process files or directories that match the
             specified pattern.  Note that exclusions take
             precedence over patterns or filenames specified on
             the command line.

     --format format (-W format=format)
             (c mode only) Use the specified format for the
             created archive.  Supported formats include
             ``cpio'', ``pax'', ``shar'', and ``ustar''.  Other
             formats may also be supported; see
             libarchive-formats(5) for more information about
             currently-supported formats.

     -f file
             Read the archive from or write the archive to the
             specified file.  The filename can be - for stan-
             dard input or standard output.  If not specified,
             the default tape device will be used.  (On
             FreeBSD, the default tape device is /dev/sa0.)

     --fast-read (-W fast-read)
             (x and t mode only) Extract or list only the first
             archive entry that matches each pattern or file-
             name operand.  Exit as soon as each specified pat-
             tern or filename has been matched.  By default,
             the archive is always read to the very end, since
             there can be multiple entries with the same name
             and, by convention, later entries overwrite ear-
             lier entries.  This option is provided as a per-
             formance optimization.

     -H      (c and r mode only) Symbolic links named on the
             command line will be followed; the target of the
             link will be archived, not the link itself.

     -h      (c and r mode only) Synonym for -L.

     -I      Synonym for -T.

     --include pattern (-W include=pattern)
             Process only files or directories that match the
             specified pattern.  Note that exclusions specified
             with --exclude take precedence over inclusions.
             If no inclusions are explicitly specified, all
             entries are processed by default.  The --include
             option is especially useful when filtering
             archives.  For example, the command
                   tar -c -f new.tar --include='*foo*' @old.tgz
             creates a new archive new.tar containing only the
             entries from old.tgz containing the string `foo'.

     -j      (c mode only) Compress the resulting archive with
             bzip2(1).  In extract or list modes, this option
             is ignored.  Note that, unlike other tar implemen-
             tations, this implementation recognizes bzip2 com-
             pression automatically when reading archives.

     -k      (x mode only) Do not overwrite existing files.  In
             particular, if a file appears more than once in an
             archive, later copies will not overwrite earlier
             copies.

     -L      (c and r mode only) All symbolic links will be
             followed.  Normally, symbolic links are archived
             as such.  With this option, the target of the link
             will be archived instead.

     -l      This is a synonym for the --check-links option.

     -m      (x mode only) Do not extract modification time.
             By default, the modification time is set to the
             time stored in the archive.

     -n      (c, r, u modes only) Do not recursively archive
             the contents of directories.

     --newer date (-W newer=date)
             (c, r, u modes only) Only include files and direc-
             tories newer than the specified date.  This com-
             pares ctime entries.

     --newer-mtime date (-W newer-mtime=date)
             (c, r, u modes only) Like --newer, except it com-
             pares mtime entries instead of ctime entries.

     --newer-than file (-W newer-than=file)
             (c, r, u modes only) Only include files and direc-
             tories newer than the specified file.  This com-
             pares ctime entries.

     --newer-mtime-than file (-W newer-mtime-than=file)
             (c, r, u modes only) Like --newer-than, except it
             compares mtime entries instead of ctime entries.

     --nodump (-W nodump)
             (c and r modes only) Honor the nodump file flag by
             skipping this file.

     --null (-W null)
             (use with -I, -T, or -X) Filenames or patterns are
             separated by null characters, not by newlines.
             This is often used to read filenames output by the
             -print0 option to find(1).

     -O      (x, t modes only) In extract (-x) mode, files will
             be written to standard out rather than being
             extracted to disk.  In list (-t) mode, the file
             listing will be written to stderr rather than the
             usual stdout.

     -o      (x mode only) Use the user and group of the user
             running the program rather than those specified in
             the archive.  Note that this has no significance
             unless -p is specified, and the program is being
             run by the root user.  In this case, the file
             modes and flags from the archive will be restored,
             but ACLs or owner information in the archive will
             be discarded.

     --one-file-system (-W one-file-system)
             (c, r, and u modes) Do not cross mount points.

     -P      Preserve pathnames.  By default, absolute path-
             names (those that begin with a / character) have
             the leading slash removed both when creating
             archives and extracting from them.  Also, tar will
             refuse to extract archive entries whose pathnames
             contain .. or whose target directory would be
             altered by a symlink.  This option suppresses
             these behaviors.

     -p      (x mode only) Preserve file permissions.  Attempt
             to restore the full permissions, including owner,
             file modes, file flags and ACLs, if available, for
             each item extracted from the archive.  By default,
             newly-created files are owned by the user running
             tar, the file mode is restored for newly-created
             regular files, and all other types of entries
             receive default permissions.  If tar is being run
             by root, the default is to restore the owner
             unless the -o option is also specified.

     --strip-components count (-W strip-components=count)
             (x and t mode only) Remove the specified number of
             leading path elements.  Pathnames with fewer ele-
             ments will be silently skipped.  Note that the
             pathname is edited after checking inclusion/exclu-
             sion patterns but before security checks.

     -T filename
             In x or t mode, tar will read the list of names to
             be extracted from filename.  In c mode, tar will
             read names to be archived from filename.  The spe-
             cial name ``-C'' on a line by itself will cause
             the current directory to be changed to the direc-
             tory specified on the following line.  Names are
             terminated by newlines unless --null is specified.
             Note that --null also disables the special han-
             dling of lines containing ``-C''.

     -U      (x mode only) Unlink files before creating them.
             Without this option, tar overwrites existing
             files, which preserves existing hardlinks.  With
             this option, existing hardlinks will be broken, as
             will any symlink that would affect the location of
             an extracted file.

     --use-compress-program program
             Pipe the input (in x or t mode) or the output (in
             c mode) through program instead of using the
             builtin compression support.

     -v      Produce verbose output.  In create and extract
             modes, tar will list each file name as it is read
             from or written to the archive.  In list mode, tar
             will produce output similar to that of ls(1).
             Additional -v options will provide additional
             detail.

     -W longopt=value
             Long options (preceded by --) are only supported
             directly on systems that have the getopt_long(3)
             function.  The -W option can be used to access
             long options on systems that do not support this
             function.

     -w      Ask for confirmation for every action.

     -X filename
             Read a list of exclusion patterns from the speci-
             fied file.  See --exclude for more information
             about the handling of exclusions.

     -y      (c mode only) Compress the resulting archive with
             bzip2(1).  In extract or list modes, this option
             is ignored.  Note that, unlike other tar implemen-
             tations, this implementation recognizes bzip2 com-
             pression automatically when reading archives.

     -z      (c mode only) Compress the resulting archive with
             gzip(1).  In extract or list modes, this option is
             ignored.  Note that, unlike other tar implementa-
             tions, this implementation recognizes gzip com-
             pression automatically when reading archives.

ENVIRONMENT
     The following environment variables affect the execution
     of tar:

     LANG       The locale to use.  See environ(7) for more
                information.

     TAPE       The default tape device.  The -f option over-
                rides this.

     TZ         The timezone to use when displaying dates.  See
                environ(7) for more information.

FILES
     /dev/sa0   The default tape device, if not overridden by
                the TAPE environment variable or the -f option.

EXIT STATUS
     The tar utility exits 0 on success, and >0 if an error
     occurs.

EXAMPLES
     The following creates a new archive called file.tar.gz
     that contains two files source.c and source.h:
           tar -czf file.tar.gz source.c source.h

     To view a detailed table of contents for this archive:
           tar -tvf file.tar.gz

     To extract all entries from the archive on the default
     tape drive:
           tar -x

     To examine the contents of an ISO 9660 cdrom image:
           tar -tf image.iso

     To move file hierarchies, invoke tar as
           tar -cf - -C srcdir . | tar -xpf - -C destdir
     or more traditionally
           cd srcdir ; tar -cf - . | (cd destdir ; tar -xpf -)

     In create mode, the list of files and directories to be
     archived can also include directory change instructions of
     the form -Cfoo/baz and archive inclusions of the form
     @archive-file.  For example, the command line
           tar -c -f new.tar foo1 @old.tgz -C/tmp foo2
     will create a new archive new.tar.  tar will read the file
     foo1 from the current directory and add it to the output
     archive.  It will then read each entry from old.tgz and
     add those entries to the output archive.  Finally, it will
     switch to the /tmp directory and add foo2 to the output
     archive.

     The --newer and --newer-mtime switches accept a variety of
     common date and time specifications, including ``12 Mar
     2005 7:14:29pm'', ``2005-03-12 19:14'', ``5 minutes ago'',
     and ``19:14 PST May 1''.

COMPATIBILITY
     The bundled-arguments format is supported for compatibil-
     ity with historic implementations.  It consists of an ini-
     tial word (with no leading - character) in which each
     character indicates an option.  Arguments follow as sepa-
     rate words.  The order of the arguments must match the
     order of the corresponding characters in the bundled com-
     mand word.  For example,
           tar tbf 32 file.tar
     specifies three flags t, b, and f.  The b and f flags both
     require arguments, so there must be two additional items
     on the command line.  The 32 is the argument to the b
     flag, and file.tar is the argument to the f flag.

     The mode options c, r, t, u, and x and the options b, f,
     l, m, o, v, and w comply with SUSv2.

     For maximum portability, scripts that invoke tar should
     use the bundled-argument format above, should limit them-
     selves to the c, t, and x modes, and the b, f, m, v, and w
     options.

     On systems that support getopt_long(), additional long
     options are available to improve compatibility with other
     tar implementations.

SECURITY
     Certain security issues are common to many archiving pro-
     grams, including tar.  In particular, carefully-crafted
     archives can request that tar extract files to locations
     outside of the target directory.  This can potentially be
     used to cause unwitting users to overwrite files they did
     not intend to overwrite.  If the archive is being
     extracted by the superuser, any file on the system can
     potentially be overwritten.  There are three ways this can
     happen.  Although tar has mechanisms to protect against
     each one, savvy users should be aware of the implications:

            Archive entries can have absolute pathnames.  By
             default, tar removes the leading / character from
             filenames before restoring them to guard against
             this problem.

            Archive entries can have pathnames that include ..
             components.  By default, tar will not extract
             files containing .. components in their pathname.

            Archive entries can exploit symbolic links to
             restore files to other directories.  An archive
             can restore a symbolic link to another directory,
             then use that link to restore a file into that
             directory.  To guard against this, tar checks each
             extracted path for symlinks.  If the final path
             element is a symlink, it will be removed and
             replaced with the archive entry.  If -U is speci-
             fied, any intermediate symlink will also be uncon-
             ditionally removed.  If neither -U nor -P is spec-
             ified, tar will refuse to extract the entry.
     To protect yourself, you should be wary of any archives
     that come from untrusted sources.  You should examine the
     contents of an archive with
           tar -tf filename
     before extraction.  You should use the -k option to ensure
     that tar will not overwrite any existing files or the -U
     option to remove any pre-existing files.  You should gen-
     erally not extract archives while running with super-user
     privileges.  Note that the -P option to tar disables the
     security checks above and allows you to extract an archive
     while preserving any absolute pathnames, .. components, or
     symlinks to other directories.

SEE ALSO
     bzip2(1), cpio(1), gzip(1), mt(1), pax(1), shar(1),
     libarchive(3), libarchive-formats(5), tar(5)

STANDARDS
     There is no current POSIX standard for the tar command; it
     appeared in ISO/IEC 9945-1:1996 (``POSIX.1'') but was
     dropped from IEEE Std 1003.1-2001 (``POSIX.1'').  The
     options used by this implementation were developed by sur-
     veying a number of existing tar implementations as well as
     the old POSIX specification for tar and the current POSIX
     specification for pax.

     The ustar and pax interchange file formats are defined by
     IEEE Std 1003.1-2001 (``POSIX.1'') for the pax command.

HISTORY
     A tar command appeared in Seventh Edition Unix, which was
     released in January, 1979.  There have been numerous other
     implementations, many of which extended the file format.
     John Gilmore's pdtar public-domain implementation (circa
     November, 1987) was quite influential, and formed the
     basis of GNU tar.  GNU tar was included as the standard
     system tar in FreeBSD beginning with FreeBSD 1.0.

     This is a complete re-implementation based on the
     libarchive(3) library.

BUGS
     This program follows ISO/IEC 9945-1:1996 (``POSIX.1'') for
     the definition of the -l option.  Note that GNU tar prior
     to version 1.15 treated -l as a synonym for the
     --one-file-system option.

     The -C dir option may differ from historic implementa-
     tions.

     All archive output is written in correctly-sized blocks,
     even if the output is being compressed.  Whether or not
     the last output block is padded to a full block size
     varies depending on the format and the output device.  For
     tar and cpio formats, the last block of output is padded
     to a full block size if the output is being written to
     standard output or to a character or block device such as
     a tape drive.  If the output is being written to a regular
     file, the last block will not be padded.  Many compres-
     sors, including gzip(1) and bzip2(1), complain about the
     null padding when decompressing an archive created by tar,
     although they still extract it correctly.

     The compression and decompression is implemented inter-
     nally, so there may be insignificant differences between
     the compressed output generated by
           tar -czf - file
     and that generated by
           tar -cf - file | gzip

     The default should be to read and write archives to the
     standard I/O paths, but tradition (and POSIX) dictates
     otherwise.

     The r and u modes require that the archive be uncompressed
     and located in a regular file on disk.  Other archives can
     be modified using c mode with the @archive-file extension.

     To archive a file called @foo or -foo you must specify it
     as ./@foo or ./-foo, respectively.

     In create mode, a leading ./ is always removed.  A leading
     / is stripped unless the -P option is specified.

     There needs to be better support for file selection on
     both create and extract.

     There is not yet any support for multi-volume archives or
     for archiving sparse files.

     Converting between dissimilar archive formats (such as tar
     and cpio) using the @- convention can cause hard link
     information to be lost.  (This is a consequence of the
     incompatible ways that different archive formats store
     hardlink information.)

     There are alternative long options for many of the short
     options that are deliberately not documented.

BSD                             April 13, 2004                             BSD
