Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for gnutar (opendarwin section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


TAR(1)				   BSD General Commands Manual				   TAR(1)

NAME
     gnutar -- tape archiver; manipulate "tar" archive files

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

DESCRIPTION
     Tar is short for ``tape archiver'', so named for historical reasons; the gnutar program cre-
     ates, adds files to, or extracts files from an archive file in gnutar 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 gnutar 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 arguments from the
     command line in the order they are specified in the command word (review the EXAMPLES sec-
     tion).  Functions and function modifiers can also be specified with the GNU argument conven-
     tion (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 gnutar 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 corresponding 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 modification 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 per-
		    missions 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 directory).  If the archive contains multiple
		    entries corresponding to the same file (see the --append command above), the
		    last one extracted will overwrite all earlier versions.

OPTIONS
     The other options to gnutar may be combined arbitrarily; single-letter options may be bun-
     dled 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).  gnutar will properly handle option arguments passed either with or without
     a leading `=` (i.e. either --option=arg or --option arg).

     --help		     Prints a message listing and briefly describing all the command
			     options to gnutar.
     --atime-preserve	     Restore the access times on files which are written to tape (note
			     that this will change the inode-change time!).
     -b
     --block-size number
     --blocking-factor number
     --record-size size      Sets the block size for reading or writing to number * 512-byte
			     blocks.  Or sets block size for reading or writing to size bytes
			     which must be a multiple of 512.
     -B
     --read-full-records     Re-assemble short reads into full records (for reading 4.2BSD
			     pipes).
     --backup control	     Backup files before removal.  Optionally, the user can specify a
			     control argument to control how gnutar performs the backups.  Sup-
			     ported values are listed bellow in the ENVIRONMENT section.
     --suffix suffix	     Backup files before removal.  Override the normal backup suffix
			     (default: '~'), using suffix instead.
     -C directory
     --directory directory   Change to directory before processing the remaining arguments.
     --checkpoint	     Print number of buffer reads/writes while reading/writing the ar-
			     chive.
     -f [hostname:]file
     --file [hostname:]file  Read or write the specified file (default is /dev/sa0).  If a
			     hostname is specified, gnutar will use rmt(8) to read or write the
			     specified file on a remote machine.  ``-'' may be used as a file-
			     name, 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).
     -G
     --incremental	     Create/list/extract old GNU-format incremental backup.
     -g file
     --listed-incremental file
			     Create/list/extract new GNU-format incremental backup.
     --group name	     Force group as group for added files.
     -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
     --bzip2		     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.
     --mode changes	     Force changes to file mode of added files.
     -m
     --modification-time     Don't extract file modified time.
     -M
     --multi-volume	     Create/list/extract multi-volume archive.
     --no-recursion	     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.
     --no-same-owner	     Do not preserve ownership when extracting files.  Extract them all
			     as owned by the current user.
     --no-same-permissions   Do not extract permission information.  Extract them using the
			     default permissions for the current user.
     --numeric-owner	     Use numbers instead of names for owner/group names.
     -o
     --old-archive
     --portability	     Write a V7 format archive, rather than POSIX format.
     -O
     --to-stdout	     Extract files to standard output.
     --owner name	     Force name as owner for added files.
     --overwrite	     Overwrite existing files when extracting.
     --overwrite-dir	     Overwrite directory metadata when extracting.
     -p
     --same-permissions
     --preserve-permissions  Extract all permission information.
     --preserve 	     Has the effect of -p -s.
     -P
     --absolute-names	     Don't strip leading '/' from file names.
     --posix		     Instructs gnutar to create a POSIX compliant `tar' archive.
     -R
     --block-number	     Show record number within archive with each message.
     --remove-files	     Remove files after adding them to the archive.
     --rsh-command command   Use command instead of rsh for remote archives/files.
     -s
     --same-order
     --preserve-order	     List of names to extract is sorted to match archive.
     --same-owner	     Try to preserve ownership when extracting files.
     --show-omitted-dirs     Show directories which were omitted while processing the archive.
     -S
     --sparse		     Handle ``sparse'' files efficiently.
     -T 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-first	     Unlink files before creating them.
     --recursive-unlink      Empty hierarchies prior to extracting directory.
     -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.  When used with list or
			     extract, volume-name is used as a globing pattern.
     --version		     Print gnutar 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.
     --anchored 	     Exclude patterns match file name start (default).
     --no-anchored	     Exclude patterns match after any /.
     --ignore-case	     Exclude patterns ignore case.
     --no-ignore-case	     Exclude patterns are case sensitive (default).
     --wildcards	     Exclude patterns use wildcards (default).
     --no-wildcards	     Exclude patterns are plain strings.
     --wildcards-match-slash
			     Exclude pattern wildcards match '/' (default).
     --no-wildcards-match-slash
			     Exclude pattern wildcards do not match '/'.
     -Z
     --compress
     --uncompress	     Filter the archive through compress(1).
     -z
     --gzip
     --ungzip
     --gunzip		     Filter the archive through gzip(1).
     --use-compress-program program
			     Filter the archive through program (which must accept -d to mean
			     ``decompress'').
     -[0-7][lmh]	     Specify tape drive and density.

ENVIRONMENT
     The gnutar program examines the following environment variables.

     POSIXLY_CORRECT  Normally, gnutar will process flag arguments that appear in the file list.
		      If set in the environment, this causes gnutar 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.

     SIMPLE_BACKUP_SUFFIX
		      Sets the backup suffix used by gnutar.  Default is '~'.

     TAPE	      Changes gnutar's default tape drive (which is still overridden by the -f
		      flag).

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

     TAR_RSH	      The TAR_RSH environment variable allows you to override the default shell
		      used as the transport for gnutar.

     VERSION_CONTROL  Sets the backup method used by gnutar.  Possible values:

		      t, numbered
				make numbered backups

		      nil, existing
				numbered if numbered backups exist, simple otherwise

		      never, simple
				always make simple backups
		      Default behaviour is 'existing'.

FILES
     /dev/sa0  The default tape drive.

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 gnutar 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 gnutar 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'.

SEE ALSO
     bzip2(1), compress(1), gzip(1), pax(1), rmt(8), info tar

HISTORY
     The gnutar format has a rich history, dating back to Sixth Edition UNIX.  The current imple-
     mentation of gnutar is the GNU implementation, which originated as the public-domain gnutar
     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 gnutar programs, and is probably untrustworthy.

     The -A command should work to join an arbitrary number of gnutar 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 gnutar 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.

BSD					December 23, 2000				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:43 PM.