tar(C) 06 January 1993 tar(C) Name tar - archive files Syntax tar [ key ] [ files ] Description The tar command saves and restores files to and from an archive medium, which is typically a floppy disk or tape, or a standard file. Its actions are controlled by the key argument. The key is a string of char- acters containing at most one function letter and possibly one or more function modifiers. Valid function letters are r, x, t, u, c, and e. Other arguments to the command are files (or directory names) specifying which files are to be backed up or restored. In all cases, a directory name refers to the files and (recursively) the subdirectories of that directory. The r and u options cannot be used with tape devices. The function portion of the key is specified by one of the following letters: r The named files are written to the end of an existing archive. x The named files are extracted from the archive. If a named file matches a directory whose contents had been written onto the archive, this directory is (recursively) extracted. The owner, modification time, and mode are restored (if possible). If no files argument is given, the entire contents of the archive are extracted. Note that if several files with the same name are on the archive, the last one overwrites all ear- lier ones. t The names of the specified files are listed each time that they occur on the archive. If no files argument is given, all the names on the archive are listed. u The named files are added to the archive if they are not already there, or if they have been modified since last written on that archive. c Creates a new archive; writing begins at the beginning of the archive, instead of after the last file. The following characters may be used in addition to the letter that selects the desired function: 0,...,9999 This numeric key selects the device on which the archive is mounted. The available numeric keys are defined in the file /etc/default/tar. A list of archive devices and their corre- sponding numeric keys can be displayed by entering tar without any arguments. The f option is used to specify an archive de- vice which is not in /etc/default/tar. v Normally, tar does its work silently. The v (verbose) option causes it to display the name of each file it treats, preceded by the function letter. With the t function, v gives more in- formation about the archive entries than just the name. w Causes tar to display the action to be taken, followed by the name of the file, and then wait for the user's confirmation. If a word beginning with ``y'' is given, the action is per- formed. Any other input means ``no''. f Causes tar to use the next argument as the name of the archive instead of the default device listed in /etc/default/tar. If the name of the file is a dash (-), tar writes to the standard output or reads from the standard input, whichever is appropri- ate. Thus, tar can be used as the head or tail of a pipeline. tar can also be used to move hierarchies with the command: cd fromdir; tar cf - . | (cd todir; tar xf -) b Causes tar to use the next argument as the blocking factor for archive records. The default is 1, the maximum is 20. This option should only be used with raw magnetic tape archives (see f above). The block size is determined automatically when reading tapes (key letters x and t). F Causes tar to use the next argument as the name of a file from which succeeding arguments are taken. l Tells tar to display an error message if it cannot resolve all of the links to the files being backed up. If l is not speci- fied, no error messages are displayed. m Tells tar not to restore the modification times. The modifica- tion time of the file is the time of extraction. k Causes tar to use the next argument as the size of an archive volume in kilobytes (K). The minimum value allowed is 250. Very large files are split into ``extents'' across volumes. When restoring from a multi-volume archive, tar only prompts for a new volume if a split file has been partially restored. To override the value of k in the default file, specify k as 0 on the command line. e Prevents files from being split across volumes (tapes or floppy disks). If there is not enough room on the present volume for a given file, tar prompts for a new volume. This is only valid when the k option is also specified on the command line. n Indicates the archive device is not a magnetic tape. The k option implies this. Listing and extracting the contents of an archive are faster because tar can seek over files it wishes to skip. Sizes are printed in kilobytes instead of tape blocks. p Indicates that files are extracted using their original permis- sions. It is possible that a non-super user may be unable to extract files because of the permissions associated with the files or directories being extracted. A Suppresses absolute filenames. Any leading ``/'' characters are removed from filenames. During extraction arguments given should match the relative (rather than the absolute) pathnames. With the c, r, and u options, the A option can be used to inhi- bit putting leading slashes in the archive headers. q During extraction causes tar to exit immediately after each file on the command line has been extracted, rather than con- tinuing to look for additional files of the same name. L Follow symbolic links. By default, symbolic links are not fol- lowed; when tar encounters a symbolic link, it issues a warning message, skips over the link, and continues with the rest of the files. T Truncates filenames of greater than 14 characters on extrac- tion. This is used for extracting files from EAFS-type file- systems that support long filenames (up to 255 characters long) to AFS-type filesystems that support maximum 14-character filenames. If no archive device is specified, either by using a numeric key or the f option, tar looks for a line in the file /etc/default/tar beginning with the string archive=. Following this string are 4 fields, separated by spaces, which contain values for the device name, blocking factor, volume size, and device type. The blocking factor is the size in kilobytes of each block on the archive medium. The volume size entry should be modi- fied to reflect the size in kilobytes of the archive volume used. Note that a volume size of `0' indicates infinite volume length. The device type is set to y for tape devices; otherwise, it is set to n. For example, the following is the default device entry from /etc/default/tar: archive=/dev/fd096ds15 10 1200 n This indicates that the default device is a floppy disk drive with a blocking factor of 10K and a volume size of 1.2 megabytes (1.2M). Any default value may be overridden using the b and k options. When a numeric key (#, in the range 0-9999) is specified, the corre- sponding device attributes are read from the line beginning with archive#= in the file /etc/default/tar. The remainder of the line has the same format as for the default archive device. The default file /etc/default/tar must exist if a device is not specified on the command line using the f option. A critical consideration when creating a tar volume involves the use of absolute or relative pathnames. Consider the following tar command exam- ples, as executed from the directory /u/target: tar cv /u/target/arrow tar cv arrow The first command creates a tar volume with the absolute pathname: /u/target/arrow. The second yields a tar volume with a relative path- name: ./arrow. (The ./ is implicit and shown here as an example; ./ should not be specified when retrieving the file from the archive.) When restored, the first example results in the file arrow being written to the directory /u/target (if it exists and you have write permission) no matter what your working directory. The second example simply writes the file arrow to your present working directory. Absolute pathnames specify the location of a file in relation to the root directory (/); relative pathnames are relative to the current directory. This must be taken into account when making a tar tape or disk. Backup volumes use absolute pathnames so that they can be restored to the proper directory. Use relative pathnames when creating a tar volume where abso- lute pathnames are unnecessary. Examples If the name of a floppy disk device is /dev/fd1, then a tar format file can be created on this device by entering: assign /dev/fd tar cvfk /dev/fd1 360 files where files are the names of files you want archived and 360 is the capa- city of the floppy disk in kilobytes. Note that arguments to key letters are given in the same order as the key letters themselves, thus the fk key letters have corresponding arguments /dev/fd1 and 360. If you assign(C) the disk at the beginning, remember to deassign it when you have finished. To display a listing of the archive, enter: tar tvf /dev/fd1 At some later time you may want to extract the files from the archive floppy. You can do this by entering: tar xvf /dev/fd1 The above command extracts all files from the archive, using the exact same pathnames as used when the archive was created. Because of this behavior, it is normally best to save archive files with relative path- names rather than absolute ones, since directory permissions may not let you read the files into the absolute directories specified. (See the A flag under ``Options''.) In the above examples, the v verbose option is used simply to confirm the reading or writing of archive files on the screen. Also, a normal file could be substituted for the floppy device /dev/fd1 shown in the exam- ples. If the default device were to be used for the above examples, the corre- sponding tar commands would be: tar cvk 360 files tar tv tar xv The tar commands for the device corresponding to 5 in the device table would be: tar cv5k 360 files tar tv5 tar xv5 Files /etc/default/tar Default devices, blocking and volume sizes, device type /tmp/tar* See also assign(C) and tar(F). Diagnostics Displays an error message about bad key characters and archive read/write errors. Displays an error message if not enough memory is available to hold the link tables. Notes There is no way to ask for the nth occurrence of a file. tar does not verify the selected media type. The u option can be slow. The limit on pathname length is 100 characters. When archiving a directory that contains subdirectories, tar will only access those subdirectories that are within 17 levels of nesting. Sub- directories at higher levels will be ignored after tar displays an error message. When using tar with a raw device, specify the block size with the b option as a multiple of 512 bytes. For example, to use a 9K block size, enter: tar cvfb /dev/rfd0 18 file Do not enter: tar xfF - - This would imply taking two things from the standard input at the same time. Use error-free floppy disks for best results with tar. Standards conformance tar is conformant with: AT&T SVID Issue 2; and X/Open Portability Guide, Issue 3, 1989.