Network Computing

NEWS BLOGS FORUMS NEWSLETTERS RESEARCH EVENTS DIGITAL LIBRARY CAREERS

IMMERSE YOURSELF:

TAR(1) USER COMMANDS TAR(1) NAME tar - create tape archives, and add or extract files SYNOPSIS tar [ - ] c|r|t|u|x [ bBefFhilmopvwX014578 ] [ tarfile ] [ blocksize ] [ exclude-file ] [ -I include-file ] filename1 filename2 ... -C directory filenameN ... DESCRIPTION tar archives and extracts multiple files onto a single tar, file archive, called a tarfile. A tarfile is usually a mag- netic tape, but it can be any file. tar's actions are con- trolled by the first argument, the key, a string of charac- ters containing exactly one function letter from the set crtux, and one or more of the optional function modifiers listed below. Other arguments to tar are file or directory names that specify which files to archive or extract. In all cases, the appearance of a directory name refers recur- sively to the files and subdirectories of that directory. FUNCTION LETTERS c Create a new tarfile and write the named files onto it. r Write the named files on the end of the tarfile. Note: this option does not work with quarter-inch archive tapes. t List the table of contents of the tarfile. u Add the named files to the tarfile if they are not there or if they have been modified since they were last archived. Note: this option does not work with quarter-inch archive tapes. x Extract the named files from the tarfile. If a named file matches a directory with contents written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode are restored (if possible). If no filename arguments are given, all files in the archive are extracted. Note: if multiple entries specifying the same file are on the tape, the last one overwrites all earlier versions. FUNCTION MODIFIERS b Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks. The block size is determined automatically when reading tapes (key letters x and t). This determination of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below). The maximum blocking factor is determined only by the amount of memory available to tar when it is run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better media utiliza- tion. B Force tar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. This option exists so that tar can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming. e If any unexpected errors occur tar will exit immedi- ately with a positive exit status. f Use the next argument as the name of the tarfile. If f is omitted, use the device indicated by the TAPE environment variable, if set. Otherwise, use /dev/rmt8 by default. If tarfile is given as `-', tar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, tar can be used as the head or tail of a filter chain. tar can also be used to copy hierarchies with the command: example% cd fromdir; tar cf - . | (cd todir; tar xfBp -) F With one F argument specified, exclude all directories named SCCS from tarfile. With two arguments FF, exclude all directories named SCCS, all files with .o as their suffix, and all files named errs, core, and a.out. h Follow symbolic links as if they were normal files or directories. Normally, tar does not follow symbolic links. i Ignore directory checksum errors. l Display error messages if all links to archived files cannot be resolved. If l is not used, no error mes- sages are printed. m Do not extract modification times of extracted files. The modification time will be the time of extraction. o Suppress information specifying owner and modes of directories which tar normally places in the archive. Such information makes former versions of tar generate an error message like: filename/: cannot create when they encounter it. p Restore the named files to their original modes, ignor- ing the present umask(2V). SetUID and sticky informa- tion are also extracted if you are the super-user. This option is only useful with the x key letter. v Verbose. Normally tar does its work silently; this option displays the name of each file tar treats, pre- ceded by the function letter. When used with the t function, v displays the tarfile entries in a form similar to `ls -l'. w Wait for user confirmation before taking the specified action. If you use w, tar displays the action to be taken followed by the file name, and then waits for a y response to proceed. No action is taken on the named file if you type anything other than a line beginning with y. X Use the next argument as a file containing a list of named files (or directories) to be excluded from the tarfile when using the key letters c, x, or t. Multi- ple X arguments may be used, with one exclude file per argument. 014578 Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid drives. The default is /dev/rmt8. If a file name is preceded by -I then the filename is opened. A list filenames, one per line, is treated as if each appeared separately on the command line. Be careful of trailing white space in both include and exclude file lists. In the case where excluded files (see X option) also exist, excluded files take precedence over all included files. So, if a file is specified in both the include and exclude files (or on the command line), it will be excluded. If a file name is preceded by -C in a c (create) or r (replace) operation, tar will perform a chdir (see csh(1)) to that file name. This allows multiple directories not related by a close common parent to be archived using short relative path names. See EXAMPLES below. Note: the -C option only applies to one following directory name and one following file name. EXAMPLES To archive files from /usr/include and from /etc, one might use: example% tar c -C /usr include -C /etc . If you get a table of contents from the resulting tarfile, you will see something like: include/ include/a.out.h and all the other files in /usr/include ... /chown and all the other files in /etc Here is a simple example using tar to create an archive of your home directory on a tape mounted on drive /dev/rmt0: example% cd example% tar cvf /dev/rmt0 . messages from tar The c option means create the archive; the v option makes tar tell you what it is doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmt0 in this example). Now you can read the table of contents from the archive like this: example% tar tvf /dev/rmt0 display table of contents of the archive (access user-id/group-id size mod. date filename) rw-r--r-- 1677/40 2123 Nov 7 18:15:1985./archive/test.c ... example% You can extract files from the archive like this: example% tar xvf /dev/rmt0 extract files from the archive messages from tar example% If there are multiple archive files on a tape, each is separated from the following one by an EOF marker. tar does not read the EOF mark on the tape after it finishes reading an archive file because tar looks for a special header to decide when it has reached the end of the archive. Now if you try to use tar to read the next archive file from the tape, tar does not know enough to skip over the EOF mark and tries to read the EOF mark as an archive instead. The result of this is an error message from tar to the effect: tar: blocksize=0 This means that to read another archive from the tape, you must skip over the EOF marker before starting another tar command. You can accomplish this using the mt(1) command, as shown in the example below. Assume that you are reading from /dev/nrmt0. example% tar xvfp /dev/nrmt0 read first archive from tape messages from tar example% mt fsf 1 skip over the end-of-file marker example% tar xvfp /dev/nrmt0 read second archive from tape messages from tar example% Finally, here is an example using tar to transfer files across the Ethernet. First, here is how to archive files from the local machine (example) to a tape on a remote sys- tem (host): example% tar cvfb - 20 filenames | rsh host dd of=/dev/rmt0 obs=20b messages from tar example% In the example above, we are creating a tarfile with the c key letter, asking for verbose output from tar with the v option, specifying the name of the output tarfile using the f option (the standard output is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b option. If you want to change the block- size, you must change the blocksize arguments both on the tar command and on the dd command. Now, here is how to use tar to get files from a tape on the remote system back to the local system: example% rsh -n host dd if=/dev/rmt0 bs=20b | tar xvBfb - 20 filenames messages from tar example% In the example above, we are extracting from the tarfile with the x key letter, asking for verbose output from tar with the v option, telling tar it is reading from a pipe with the B option, specifying the name of the input tarfile using the f option (the standard input is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b option. FILES /dev/rmt? half-inch magnetic tape interface /dev/rst? SCSI tape interface /tmp/tar* ENVIRONMENT TAPE If specified, in the environment, the value of TAPE indicates the default tape device. SEE ALSO cpio(1), csh(1), mt(1), umask(2V), tar(5), dump(8), restore(8) BUGS Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives cannot backspace. There is no way to ask for the nth occurrence of a file. Tape errors are handled ungracefully. The u option can be slow. There is no way selectively to follow symbolic links. When extracting tapes created with the r or u options, directory modification times may not be set correctly. Files with names longer than 100 characters cannot be pro- cessed. Filename substitution wildcards do not work for extracting files from the archive. To get around this, use a command of the form: tar xvf... /dev/rst0 `tar tf... /dev/rst0 | grep 'pat- tern'` Sun Release 4.1 Last change: 16 February 1988