FreeBSD 4.11 manual page repository

FreeBSD is a free computer operating system based on BSD UNIX originally. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

tar - tape archiver; manipulate "tar" archive files

 

NAME

      tar - tape archiver; manipulate "tar" archive files
 

SYNOPSIS

      tar [[-]bundled-options Args] [gnu-style-flags]
          [filenames | -C directory-name] ...
 

DESCRIPTION

      Tar is short for “tape archiver”, so named for historical reasons; the
      tar program creates, adds files to, or extracts files from an archive
      file in tar format, called a tarfile.  A tarfile is often a magnetic
      tape, but can be a floppy diskette or any regular disk file.
 
      The first argument word of the tar command line is usually a command word
      of bundled function and modifier letters, optionally preceded by a dash;
      it must contain exactly one function letter from the set A, c, d, r, t,
      u, x, for append, create, difference, replace, table of contents, update,
      and extract (further described below).  The command word can also contain
      other function modifiers described below, some of which will take argu‐
      ments from the command line in the order they are specified in the com‐
      mand word (review the EXAMPLES section).  Functions and function modi‐
      fiers can also be specified with the GNU argument convention (preceded by
      two dashes, one function or modifier per word.  Command-line arguments
      that specify files to add to, extract from, or list from an archive may
      be given as shell pattern matching strings.
 

FUNCTIONS

      Exactly one of the following functions must be specified.
 
      -A
      --catenate
      --concatenate  Append the contents of named file, which must itself be a
                     tar archive, to the end of the archive (erasing the old
                     end-of-archive block).  This has the effect of adding the
                     files contained in the named file to the first archive,
                     rather than adding the second archive as an element of the
                     first.  Note: This option requires a rewritable tarfile,
                     and therefore does not work on quarter-inch cartridge
                     tapes.
      -c
      --create       Create a new archive (or truncates an old one) and writes
                     the named files to it.
      -d
      --diff
      --compare      Find differences between files in the archive and corre‐
                     sponding files in the file system.
      --delete       Delete named files from the archive.  (Does not work on
                     quarter-inch tapes).
      -r
      --append       Append files to the end of an archive.  (Does not work on
                     quarter-inch tapes).
      -t
      --list         List the contents of an archive; if filename arguments are
                     given, only those files are listed, otherwise the entire
                     table of contents is listed.
      -u
      --update       Append the named files if the on-disk version has a modi‐
                     fication date more recent than their copy in the archive
                     (if any).  Does not work on quarter-inch tapes.
      -x
      --extract
      --get          Extract files from an archive.  The owner, modification
                     time, and file permissions are restored, if possible.  If
                     no file arguments are given, extract all the files in the
                     archive.  If a filename argument matches the name of a
                     directory on the tape, that directory and its contents are
                     extracted (as well as all directories under that direc‐
                     tory).  If the archive contains multiple entries corre‐
                     sponding to the same file (see the --append command
                     above), the last one extracted will overwrite all earlier
                     versions.
 

OPTIONS

      The other options to tar may be combined arbitrarily; single-letter
      options may be bundled in with the command word.  Verbose options which
      take arguments will be followed by the argument; single-letter options
      will consume successive command line arguments (see the EXAMPLES below).
 
      --help                  Prints a message listing and briefly describing
                              all the command options to tar.
      --atime-preserve        Restore the access times on files which are writ‐
                              ten to tape (note that this will change the
                              inode-change time!).
      -b
      --block-size number     Sets the block size for reading or writing to
                              number * 512-byte blocks.
      -B
      --read-full-blocks      Re-assemble short reads into full blocks (for
                              reading 4.2BSD pipes).
      -C directory
      --directory directory   Change to directory before processing the remain‐
                              ing arguments.
      --checkpoint            Print number of buffer reads/writes while read‐
                              ing/writing the archive.
      -f [hostname:]file
      --file [hostname:]file  Read or write the specified file (default is
                              /dev/sa0).  If a hostname is specified, tar will
                              use rmt(8) to read or write the specified file on
                              a remote machine.  “-” may be used as a filename,
                              for reading or writing to/from stdin/stdout.
      --force-local           Archive file is local even if it has a colon.
      -F file
      --info-script file
      --new-volume-script file
                              Run a script at the end of each archive volume
                              (implies -M).
      --fast-read             Stop after all non-wildcard extraction targets
                              have been found in the archive.
      -G
      --incremental           Create/list/extract old GNU-format incremental
                              backup.
      -g file
      --listed-incremental file
                              Create/list/extract new GNU-format incremental
                              backup.
      -h
      --dereference           Don’t write symlinks as symlinks; write the data
                              of the files they name.
      -i
      --ignore-zeros          Ignore blocks of zeroes in archive (usually means
                              End-Of-File).
      --ignore-failed-read    Don’t exit with non-zero status on unreadable
                              files.
      -j
      -y
      --bzip
      --bzip2
      --bunzip2               Filter the archive through bzip2(1).
      -k
      --keep-old-files        Keep files which already exist on disk; don’t
                              overwrite them from the archive.
      -K file
      --starting-file file    Begin at file in the archive.
      -l
      --one-file-system       Stay in local file system when creating an
                              archive (do not cross mount points).
      -L number
      --tape-length number    Change tapes after writing number * 1024 bytes.
      -m
      --modification-time     Don’t extract file modified time.
      -M
      --multi-volume          Create/list/extract multi-volume archive.
      -n
      --norecurse             Don’t recurse into subdirectories when creating.
      --volno-file file       File name with volume number to start with.
      -N date
      --after-date date
      --newer date            Only store files with creation time newer than
                              date.
      --newer-mtime date      Only store files with modification time newer
                              than date.
      -o
      --old-archive
      --portability           Write a V7 format archive, rather than POSIX for‐
                              mat.
      -O
      --to-stdout             Extract files to standard output.
      -p
      --same-permissions
      --preserve-permissions  Extract all protection information.
      --preserve              Has the effect of -p -s.
      -P
      --absolute-paths        Don’t strip leading ‘/’ from file names.
      -R
      --record-number         Show record number within archive with each mes‐
                              sage.
      --remove-files          Remove files after adding them to the archive.
      -s
      --same-order
      --preserve-order        List of names to extract is sorted to match
                              archive.
      --show-omitted-dirs     Show directories which were omitted while pro‐
                              cessing the archive.
      -S
      --sparse                Handle “sparse” files efficiently.
      -T file
      -I file
      --files-from file       Get names of files to extract or create from
                              file, one per line.
      --null                  Modifies behavior of -T to expect null-terminated
                              names; disables -C.
      --totals                Prints total bytes written with --create.
      -U
      --unlink
      --unlink-first          Unlink files before creating them.
      -v
      --verbose               Lists files written to archive with --create or
                              extracted with --extract; lists file protection
                              information along with file names with --list.
      -V volume-name
      --label volume-name     Create archive with the given volume-name.
      --version               Print tar program version number.
      -w
      --interactive
      --confirmation          Ask for confirmation for every action.
      -W
      --verify                Attempt to verify the archive after writing it.
      --exclude pattern       Exclude files matching the pattern (don’t extract
                              them, don’t add them, don’t list them).
      -X file
      --exclude-from file     Exclude files listed in file.
      -Z
      --compress
      --uncompress            Filter the archive through compress(1).
      -z
      --gzip
      --gunzip                Filter the archive through gzip(1).
      --use-compress-program program
                              Filter the archive through program (which must
                              accept -d to mean “decompress”).
      --block-compress        Block the output of compression program for tapes
                              or floppies (otherwise writes will be of odd
                              length, which device drivers may reject).
      -[0-7][lmh]             Specify tape drive and density.
 

ENVIRONMENT

      The environment variable TAR_OPTIONS can hold a set of default options
      for tar.  These options are interpreted first and can be overwritten by
      explicit command line parameters.
 

EXAMPLES

      To create an archive on tape drive /dev/sa0 with a block size of 20
      blocks, containing files named bert and ernie, you can enter
            tar cfb /dev/sa0 20 bert ernie
      or
            tar --create --file /dev/sa0 --block-size 20 bert ernie
      Note that the -f and -b flags both require arguments, which they take
      from the command line in the order they were listed in the command word.
 
      Because /dev/sa0 is the default device, and 20 is the default block size,
      the above example could have simply been
            tar c bert ernie
 
      To extract all the C sources and headers from an archive named
      backup.tar, type
            tar xf backup.tar ’*.[ch]’
      Note that the pattern must be quoted to prevent the shell from attempting
      to expand it according the files in the current working directory (the
      shell does not have access to the list of files in the archive, of
      course).
 
      To move file hierarchies, use a command line like this:
 
      tar -cf - -C srcdir . | tar xpf - -C destdir
 
      To create a compressed archive on diskette, using gzip(1), use a command-
      line like
            tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/
 
      Note that you cannot mix bundled flags and --style flags; you can use
      single-letter flags in the manner above, rather than having to type
            tar --block-compress --gzip --verbose --file /dev/fd1a --block-size
            20 tar/
 
      The above-created diskette can be listed with
            tar tvfbz /dev/fd1a 36
 
      To join two tar archives into a single archive, use
            tar Af archive1.tar archive2.tar
      which will add the files contained in archive2.tar onto the end of
      archive1.tar (note that this can’t be done by simply typing
            cat archive2.tar >> archive1.tar
      because of the end-of-file block at the end of a tar archive).
 
      To archive all files from the directory srcdir, which were modified after
      Feb. 9th 1997, 13:00 h, use
            tar -c -f backup.tar --newer-mtime ’Feb 9 13:15 1997’ srcdir/
 
      Other possible time specifications are ‘02/09/97 13:15’, ‘1997-02-09
      13:15’, ‘13:15 9 Feb 1997’, ‘9 Feb 1997 13:15’, ‘Feb. 9, 1997 1:15pm’,
      ‘09-Feb’, ‘3 weeks ago’ or ‘May first Sunday’.  To specify the correct
      time zone use either e.g. ‘13:15 CEST’ or ‘13:15+200’.
 

ENVIRONMENT

      The tar program examines the following environment variables.
 
      POSIXLY_CORRECT  Normally, tar will process flag arguments that appear in
                       the file list.  If set in the environment, this causes
                       tar to consider the first non-flag argument to terminate
                       flag processing, as per the POSIX specification.
 
      SHELL            In interactive mode, a permissible response to the
                       prompt is to request to spawn a subshell, which will be
                       /bin/sh unless the SHELL variable is set.
 
      TAPE             Changes tar’s default tape drive (which is still over‐
                       ridden by the -f flag).
 
      TAR_RSH          The TAR_RSH environment variable allows you to override
                       the default shell used as the transport for tar.
 

FILES

      /dev/sa0  The default tape drive.
 

COMPATIBILITY

      The -y is a FreeBSD localism.  The GNU tar maintainer has now chosen -j
      as the offical bzip2(1) compression option in GNU tar 1.13.18 and later.
      The -I option is for compatibility with Solaris’s tar.
      bzip2(1), compress(1), gzip(1), pax(1), rmt(8)
 

HISTORY

      The tar format has a rich history, dating back to Sixth Edition UNIX.
      The current implementation of tar is the GNU implementation, which origi‐
      nated as the public-domain tar written by John Gilmore.
 

AUTHORS

      A cast of thousands, including [as listed in the ChangeLog file in the
      source] John Gilmore (author of original public domain version), Jay
      Fenlason (first GNU author), Joy Kendall, Jim Kingdon, David J.
      MacKenzie, Michael I Bushnell, Noah Friedman, and innumerable others who
      have contributed fixes and additions.
 
      Man page obtained by the FreeBSD group from the NetBSD 1.0 release.
 

BUGS

      The -C feature does not work like historical tar programs, and is proba‐
      bly untrustworthy.
 
      The -A command should work to join an arbitrary number of tar archives
      together, but it does not; attempting to do so leaves the end-of-archive
      blocks in place for the second and subsequent archives.
 
      The tar file format is a semi fixed width field format, and the field for
      device numbers were designed for 16 bit (8 major, 8 minor) and can not
      absorb our 32 bit (8 major, 16+8 minor) numbers.
 

Sections

Based on BSD UNIX
FreeBSD is an advanced operating system for x86 compatible (including Pentium and Athlon), amd64 compatible (including Opteron, Athlon64, and EM64T), UltraSPARC, IA-64, PC-98 and ARM architectures. It is derived from BSD, the version of UNIX developed at the University of California, Berkeley. It is developed and maintained by a large team of individuals. Additional platforms are in various stages of development.