gtar" -- Command" "

Archiving/backup utility

ggttaarr _o_p_t_i_o_n_s

gtar is the GNU version of the archiving utility tar. It copies files into or out of a tar archive, reads the contents of a tar archive, and replaces files within an archive. It can also perform additional tasks such as compressing files as they are added to an archive, or uncompressing them as they are read out.

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

gtar recognizes the following options. Please note that not every option applies to both modes.

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.

The following options modify other aspects of gtar's behavior:

----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

The first example archives ppiiggggyy, into archive ppiiggggyy..ttaarr:
     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

Notes

COHERENT does not yet support networking. The above descriptions of host addressing do not yet apply.

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.