COHERENT manpages
This page displays the COHERENT manpage for gtar [Archiving/backup utility].
List of available manpages
Index
gtar -- Command Archiving/backup utility gtar options 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: Copy-in Mode 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. Copy-out Mode 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: -A --catenate --concatenate Append files onto an archive. -c --create Create a new archive. -d --diff --compare 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. --delete Delete files from the archive. Do not for use this option with an archive that is on a magnetic tape. -r --append Replace files within an archive. If a file does not exist within an archive, append it onto the archive. -t --list List the contents of an archive. -u --update Append a file onto an archive only if it is younger than the identically named file within the archive. --use-compress-program Specify the compression program to use. By default, gtar invokes gzip to compress files. -x --extract --get Extract files from the archive. The following options modify other aspects of gtar's behavior: --atime-preserve Do not change the access times on files, whether copying into or out of an archive. -b N --block-size N Use a block size of N×512 bytes. By default, gtar uses an N of 20 -- that is, a block size of ten kilobytes. -B --read-full-blocks 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. --block-compress [compress|gzip] Block the output of the compression program for tapes. You must name one of the compression options to use: either compress or gzip. -C directory --directory directory Change to directory. --checkpoint Print directory names while reading the archive. --exclude file Do not include file when archiving or de-archiving files. file can be a regular expression. -f file --file file 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. --force-local 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. -F script --info-script script --new-volume-script script At the end of each tape (or disk), run script. Note that this option implies that you are also using option -M. -G [file ...] --incremental 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. -g --listed-incremental 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 -i --ignore-zeros Ignore blocks of zeros in archive. --ignore-failed-read 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. -k --keep-old-files 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. -K file --starting-file file Keep option: begin work with file in the archive. -l --one-file-system Stay in the local file system when creating an archive. -L N --tape-length N Change tapes after writing N×1,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. -m --modification-time Do not extract file modified time. -M --multi-volume 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. -N date --after-date date --newer date Only store files newer than date. -o --old-archive --portability Write a V7-format archive, rather than an ANSI-format archive. -O --to-stdout Write files to the standard output. -p --same-permissions --preserve-permissions Preserve the permissions that the file had originally. -P --absolute-paths Do not strip leading `/'s from file names. --preserve This option is identical to -p plus -s. -R --record-number Show record number within archive with each message. --remove-files Remove files after adding them to the archive. -s --same-order --preserve-order Sort the list of names to extract to match their order within the archive. --same-owner Create extracted files with the same ownership they had within the archive. -S --sparse Handle sparse files efficiently. For a description of what a sparse file is, see the Lexicon entry for chsize(). --show-omitted-dirs Print the names of directories omitted from the archive. -T file --files-from file Read from file the names of all files to archive or extract. --null Modify option -T so that it reads null-terminated names. This option disables option -C. --totals Print the number of bytes written with option -c. --use-compress-program program Filter the archive through program. Note that program must accept option -d. -v --verbose 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. -V name --label name Name the archive name. When used with the option --extract, name can be a regular expression. --version Print the version of gtar that you are using. --volno-file file 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. -w --interactive --confirmation Ask the user to confirm every action. -W --verify Attempt to verify the archive after writing it. -X file --exclude-from file Do not archive or de-archive all of the files named in file. -Z --compress --uncompress Filter files being archived or de-archived through compress. -z --gzip --ungzip Filter files being archived or de-archived through gzip. Examples The first example archives piggy, into archive piggy.tar: 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, §10.1.1 Notes COHERENT does not yet support networking. The above descriptions of host addressing do not yet apply. gtar is released under the conditions of the Free Software Foundation's ``copyleft''. Full source code is available through the Mark Williams bulletin board.