gtar" -- Command" "

ggttaarr _o_p_t_i_o_n_s

gtar works in either of two modes:

_C_o_p_y_-_i_n _M_o_d_e

gtar copies files from an archive or lists the archive's contents. By default, it reads the archive from the standard input; you can also use the option -f (described below) to name the file or device that holds the archive you want read.

gtar regards any non-option argument as a shell wild-card pattern; and it copies from the archive only those files whose names match one or more of those patterns. Unlike the shell, an initial `.' in a file name matches a wildcard at the start of a pattern, and a `/' in a file name can match a wildcard. If the command line contains no pattern, gtar extracts all files.

_C_o_p_y_-_o_u_t _M_o_d_e

gtar copies files into an archive. By default, gtar reads a list of file names, one per line, from the standard input. However, if the command line contains non-option arguments, gtar regards each as a shell wild-card pattern that names one or more files to copy into the archive. If an argument names a directory, then gtar recursively copies all files within that directory into the archive.

By default, gtar writes its newly built archive to the standard output. However, you can use the option -f (described below) to name the file or device into gtar writes the new archive.

gtar normally writes into the local directory all files that it reads from an archive. If files were archived using absolute path names, gtar by default drops the leading `/' from the path name; to suppress this behavior, use the option -P, described below. If a file being extracted resides within a directory that does not exist in the current directory, gtar will create that directory. gtar will fail, of course, if you do not have write permission in the current directory.

Options

Please note, too, that some options have more than one name. Every option has a multi-character name that begins with with two hyphens --; some commonly used options also have a one-character name that begins with a single hyphen. This convention may appear clumsy, but it does permit option names to have hyphens embedded within them.

The following command-line options govern the mode in which gtar works:

--AA

----ccaatteennaattee

----ccoonnccaatteennaattee

Append files onto an archive.

--cc

----ccrreeaattee

Create a new archive.

--dd

----ddiiffff

----ccoommppaarree

Find the differences between the files in an archive and the identically named files in the file system. This is very useful in verifying that a new archive was built correctly.

----ddeelleettee

Delete files from the archive. Do not for use this option with an archive that is on a magnetic tape.

--rr

----aappppeenndd

Replace files within an archive. If a file does not exist within an archive, append it onto the archive.

--tt

----lliisstt

List the contents of an archive.

--uu

----uuppddaattee

Append a file onto an archive only if it is younger than the identically named file within the archive.

----uussee--ccoommpprreessss--pprrooggrraamm

Specify the compression program to use. By default, gtar invokes gzip to compress files.

--xx

----eexxttrraacctt

----ggeett

Extract files from the archive.

----aattiimmee--pprreesseerrvvee

Do not change the access times on files, whether copying into or out of an archive.

--bb _N

----bblloocckk--ssiizzee _N

Use a block size of _Nx512 bytes. By default, gtar uses an N of 20 -- that is, a block size of ten kilobytes.

--BB

----rreeaadd--ffuullll--bblloocckkss

Tell gtar to reblock as it reads. This is required for reading pipes under Berkeley UNIX release 4.2, and does not apply to COHERENT.

----bblloocckk--ccoommpprreessss [[ccoommpprreessss||ggzziipp]]

Block the output of the compression program for tapes. You must name one of the compression options to use: either compress or gzip.

--CC _d_i_r_e_c_t_o_r_y

----ddiirreeccttoorryy _d_i_r_e_c_t_o_r_y

Change to directory.

----cchheecckkppooiinntt

Print directory names while reading the archive.

----eexxcclluuddee _f_i_l_e

Do not include file when archiving or de- archiving files. file can be a regular expression.

--ff _f_i_l_e

----ffiillee _f_i_l_e

Read the input from, or write the output to, file. file can name an ordinary file or a device. File name `-' indicates the standard input or standard output (depending upon whether an archive is being read or written). When this option is not used, gtar by default reads from the standard input and writes to the standard output.

----ffoorrccee--llooccaall

The archive file is local even if its name contains a colon. gtar usually interprets a file name that contains a colon as naming a file on a remote system that is connected via a network.

--FF _s_c_r_i_p_t

----iinnffoo--ssccrriipptt _s_c_r_i_p_t

----nneeww--vvoolluummee--ssccrriipptt _s_c_r_i_p_t

At the end of each tape (or disk), run script. Note that this option implies that you are also using option -M.

--GG [[_f_i_l_e _._._.]]

----iinnccrreemmeennttaall

Create, list, or extract every file that is in an archive written in the format of the old GNU incremental backup. If no file is named, all gtar extracts all files.

--gg

----lliisstteedd--iinnccrreemmeennttaall

Create, list, or extract files that are in an archive written in the format of the new GNU incremental backup. create/list/extract new GNU-format incremental backup

--ii

----iiggnnoorree--zzeerrooss

Ignore blocks of zeros in archive.

----iiggnnoorree--ffaaiilleedd--rreeaadd

gtar normally exits with non-zero status when it encounters an unreadable file. With this option, gtar ignores the unreadable file and continues to work.

--kk

----kkeeeepp--oolldd--ffiilleess

If a file being extracted from an archive has an identically named analogue in the file system, gtar normally overwrites the file in the file system with the file withdrawn from the archive. This option tells gtar to rename the file that is in the file system, rather than overwrite it.

--KK _f_i_l_e

----ssttaarrttiinngg--ffiillee _f_i_l_e

Keep option: begin work with file in the archive.

--ll

----oonnee--ffiillee--ssyysstteemm

Stay in the local file system when creating an archive.

--LL _N

----ttaappee--lleennggtthh _N

Change tapes after writing _Nx1,024 bytes. gtar normally reads or writes until it reaches the end of the medium, then prompts for the name of the next device. This option, of course, normally does not apply to archives being written to or read from disk.

--mm

----mmooddiiffiiccaattiioonn--ttiimmee

Do not extract file modified time.

--MM

----mmuullttii--vvoolluummee

Create, list, or extract a multi-volume archive. You can use this option with multiple -f options. gtar uses the output devices in sequence, then wraps around to the beginning. This lets you, say, write output to two different tape drives or floppy-disk drives; you can loading blank media into one while gtar is writing to the other. Note that if you are using this option to create an archive, be very careful to label disks or tapes correctly to note the order in which they were written.

--NN _d_a_t_e

----aafftteerr--ddaattee _d_a_t_e

----nneewweerr _d_a_t_e

Only store files newer than date.

--oo

----oolldd--aarrcchhiivvee

----ppoorrttaabbiilliittyy

Write a V7-format archive, rather than an ANSI-format archive.

--OO

----ttoo--ssttddoouutt

Write files to the standard output.

--pp

----ssaammee--ppeerrmmiissssiioonnss

----pprreesseerrvvee--ppeerrmmiissssiioonnss

Preserve the permissions that the file had originally.

--PP

----aabbssoolluuttee--ppaatthhss

Do not strip leading `/'s from file names.

----pprreesseerrvvee

This option is identical to -p plus -s.

--RR

----rreeccoorrdd--nnuummbbeerr

Show record number within archive with each message.

----rreemmoovvee--ffiilleess

Remove files after adding them to the archive.

--ss

----ssaammee--oorrddeerr

----pprreesseerrvvee--oorrddeerr

Sort the list of names to extract to match their order within the archive.

----ssaammee--oowwnneerr

Create extracted files with the same ownership they had within the archive.

--SS

----ssppaarrssee

Handle sparse files efficiently. For a description of what a sparse file is, see the Lexicon entry for chsize().

----sshhooww--oommiitttteedd--ddiirrss

Print the names of directories omitted from the archive.

--TT ffiillee

----ffiilleess--ffrroomm _f_i_l_e

Read from file the names of all files to archive or extract.

----nnuullll

Modify option -T so that it reads null-terminated names. This option disables option -C.

----ttoottaallss

Print the number of bytes written with option -c.

----uussee--ccoommpprreessss--pprrooggrraamm _p_r_o_g_r_a_m

Filter the archive through program. Note that program must accept option -d.

--vv

----vveerrbboossee

Write the names of all files archived or extracted. When you also use the option -f, gtar writes the names to the standard output; however, when you do not use -f, it writes them to the standard error.

--VV _n_a_m_e

----llaabbeell _n_a_m_e

Name the archive name. When used with the option --extract, name can be a regular expression.

----vveerrssiioonn

Print the version of gtar that you are using.

----vvoollnnoo--ffiillee _f_i_l_e

Read from file the volume number used when prompting the user. Note that gtar does not use the contents of file when it records volume identifiers on the archive.

--ww

----iinntteerraaccttiivvee

----ccoonnffiirrmmaattiioonn

Ask the user to confirm every action.

--WW

----vveerriiffyy

Attempt to verify the archive after writing it.

--XX _f_i_l_e

----eexxcclluuddee--ffrroomm _f_i_l_e

Do not archive or de-archive all of the files named in file.

--ZZ

----ccoommpprreessss

----uunnccoommpprreessss

Filter files being archived or de-archived through compress.

--zz

----ggzziipp

----uunnggzziipp

Filter files being archived or de-archived through gzip.

Examples

     gtar -cf piggy.tar piggy

To simultaneously compress piggy with the utility gzip, use the command:

     gtar -czf piggy.gtz piggy

Note that the suffix .gtz is used by convention to mark archives whose contents are compressed. This is not required, but it is a good idea to use this or some similar suffix to mark compressed archives: if you do not remember to use the -z option to de- archive a compress archive, gtar will fail. So, to extract file piggy from its compressed archive, use the command:

     gtar -xzf piggy.gtz piggy

The -z is recommended: it speeds archiving of large files or file systems, and increases their accuracy -- because the archives are smaller, there are fewer opportunities for errors to occur.

To write an archive onto a device, use the option -f to name that device instead of a file. You must, of course, have write permission on that device. If you are writing onto a floppy disk, the disk must have been formatted with the command fdformat, but does not need to have a COHERENT file system on it; in fact, gtar will overwrite all file-system information that may reside on a disk. For example, to write file piggy onto a high-density, 5.25-inch, formatted floppy disk in drive 0, use the following command:

     gtar -czf /dev/fha0 piggy

To copy piggy back from this archive, use the command:

     gtar -xzf /dev/fha0

As noted above, you must remember to use the -z option to de-archive files from a compressed archive.

As noted above, if you name a directory on gtar's command line, gtar will archive or de-archive that directory and all files that it contains, including its sub-directories and their contents. For example, to archive all of your personal files, use the command:

     gtar -cvzf backup.gtz $HOME

The option -v tells gtar to name every file that it is copying into its archive. Note, too, that gtar is smart enough not to copy an archive into itself, so you can execute the above command while still within your home directory.

The following backs up your personal files onto a high- density, 3.5-inch disk in drive 0:

     gtar -cvzf /dev/fva0 $HOME

NB, if you are backing up a directory that will require more than one floppy disk, you should consider using the utility cpio instead: it is somewhat easier to use when you are handling multiple-volume archives.

To copy directory src to the SCSI tape device with SCSI identifier 2, use the command:

     tar cvzf /dev/rStp2 src

To archive src to a tape and then confirm it, use the command

     tar cvzf /dev/rStp2 src ; tar dvzf /dev/rStp2 src

Note that this can be time consuming, but will confirm the integrity of backups of vital files. To restore src from its tape, use the command:

     tar xvzf /dev/rStp2

gtar by default saves files with their original ownerships and permissions; however, when it restores files, it may modify them. To restore files with their original permissions, use the option -p. For example, to restore src and restore the original ownership and permissions of its files, use the command:

     tar xvpzf /dev/rStp2

See Also

• commands,
• compression,
• gnucpio,
• tar
POSIX Standard" Standard, S10.1.1 A

Notes

A gtar is released under the conditions of the Free Software Foundation's ``copyleft''. Full source code is available through the Mark Williams bulletin board.