tar(1) User Commands tar(1) NAME tar - create tape archives and add or extract files SYNOPSIS tar c [bBefFhiloPvwX [ 0-7 ]] [ block ] [ tarfile ] [ exclude-file ] { -I include-file | -C directory file | file } ... tar r [ bBefFhilvw [ 0-7 ]] [ block ] { -I include-file | -C directory file | file } ... tar t [ BefFhilvX [ 0-7 ]] [ tarfile ] [ exclude-file ] { -I include-file | file } ... tar u [ bBefFhilvw [ 0-7 ]] [ block ] [ tarfile ] file ... tar x [ BefFhilmopvwX [ 0-7 ]] [ tarfile ] [ exclude-file ] [ file ... ] AVAILABILITY SUNWcsu DESCRIPTION The tar command archives and extracts files to and from a single file 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 key argument. The key is a string of charac- ters containing exactly one function letter (c, r, t , u, or x) and zero or more function modifiers (letters or digits), depending on the function letter used. The key string con- tains no SPACE characters. Function modifier arguments are listed on the command line in the same order as their corresponding function modifiers appear in the key string. The -I include-file, -C directory file, and file arguments specify which files or directories are to be archived or extracted. In all cases, appearance of a directory name refers to the files and (recursively) subdirectories of that directory. Arguments appearing within braces ({ indicate that one of the arguments must be specified. OPTIONS The following options are supported: -I include-file Open include-file containing a list of files, one per line, and treat as if each file appeared separately on the command line. Be careful of trailing white spaces. In the case where excluded files (see X function modif- ier) are also specified, they take precedence over all included files. If a file is specified in both the exclude-file and the include-file (or on the command SunOS 5.5.1 Last change: 20 Feb 1996 1 tar(1) User Commands tar(1) line), it will be excluded. -C directory file Perform a chdir (see cd(1)) operation on directory and perform the c (create) or r (replace) operation on file. Use short relative path names for file. If file is `.', archive all files in directory. This option enables archiving files from multiple directories not related by a close common parent. OPERANDS The following operands are supported: file A path name of a regular file or directory to be archived (when the c, r or u functions are specified), extracted (x) or listed (t). When file is the path name of a directory, the action applies to all of the files and (recursively) subdirectories of that direc- tory. The directory portion of file (see dirname(1)) cannot exceed 155 characters. The file name portion (see basename(1)) cannot exceed 100 characters. Function Letters The function portion of the key is specified by one of the following letters: c Create. Writing begins at the beginning of the tarfile, instead of at the end. r Replace. The named files are written at the end of the tarfile. t Table of Contents. The names of the specified files are listed each time they occur in the tarfile. If no file argument is given, the names of all files in the tarfile are listed. With the v function modifier, additional information for the specified files is displayed. u Update. The named files are written at the end of the tarfile if they are not already in the tarfile, or if they have been modified since last written to that tar- file. An update can be rather slow. A tarfile created on a 5.x system cannot be updated on a 4.x system. x Extract or restore. The named files are extracted from the tarfile and written to the directory specified in the tarfile, relative to the current directory. Use the relative path names of files and directories to be extracted. If a named file matches a directory whose contents has been written to the tarfile, this direc- tory is recursively extracted. The owner, modification SunOS 5.5.1 Last change: 20 Feb 1996 2 tar(1) User Commands tar(1) time, and mode are restored (if possible); otherwise, to restore owner, you must be the super-user. Character-special and block-special devices (created by mknod(1M)) can only be extracted by the super-user. If no file argument is given, the entire content of the tarfile is extracted. If the tarfile contains several files with the same name, each file is written to the appropriate directory, overwriting the previous one. Filename substitution wildcards cannot be used for extracting files from the archive; rather, use a com- mand of the form: tar xvf... /dev/rmt/0 `tar tf... /dev/rmt/0 | grep 'pattern'` When extracting tapes created with the r or u functions, directory modification times may not be set correctly. These same functions cannot be used with many tape drives due to tape drive limitations such as the absence of back- space or append capabilities. When using the r, u, or x functions or the X function modif- ier, the named files must match exactly the corresponding files in the tarfile. For example, to extract ./thisfile, you must specify ./thisfile, and not thisfile. The t func- tion displays how each file was archived. Function Modifiers The characters below may be used in conjunction with the letter that selects the desired function. b Blocking Factor. Use when reading or writing to raw magnetic archives (see f below). The block argument specifies the number of 512-byte tape blocks to be included in each read or write operation performed on the tarfile. The minimum is 1, the default is 20. The maximum value is a function of the amount of memory available and the blocking requirements of the specific tape device involved (see mtio(7I) for details.) When a tape archive is being read, its actual blocking factor will be automatically detected, provided that it is less than or equal to the nominal blocking factor (the value of the block argument, or the default value if the b modifier is not specified). If the actual blocking factor is greater than the nominal blocking factor, a read error will result. See Example 5 in EXAMPLES below. The automatic determination of the actual blocking fac- tor may be fooled when reading from a pipe or a socket (see the B function modifier below). SunOS 5.5.1 Last change: 20 Feb 1996 3 tar(1) User Commands tar(1) 1/4" streaming tape has an inherent blocking factor of one 512-byte block. It can be read or written using any blocking factor. This function modifier works for archives on disk files and block special devices, among others, but is intended principally for tape devices. B Block. Force tar to perform multiple reads (if neces- sary) to read exactly enough bytes to fill a block. This function modifier enables tar to work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming. When reading from stan- dard input, '-', this function modifier is selected by default to ensure that tar can recover from short reads. e Error. Exit immediately with a positive exit status if any unexpected errors occur. f File. Use the tarfile argument as the name of the tar- file. If f is specified, /etc/default/tar is not searched. If f is omitted, tar will use the device indicated by the TAPE environment variable, if set; otherwise, it will use the default values defined in /etc/default/tar. If the name of the tarfile is '-', tar writes to the standard output or reads from the standard input, whichever is appropriate. tar can be used as the head or tail of a pipeline. tar can also be used to move hierarchies with the command: example% cd fromdir; tar cf - . | (cd todir; tar xfBp -) F With one F argument, tar excludes all directories named SCCS and RCS from the tarfile. With two arguments, FF, tar excludes all directories named SCCS and RCS, 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 Link. Output error message if unable to resolve all links to the files being archived. If l is not speci- fied, no error messages are printed. m Modify. The modification time of the file is the time of extraction. This function modifier is valid only SunOS 5.5.1 Last change: 20 Feb 1996 4 tar(1) User Commands tar(1) with the x function. o Ownership. Assign to extracted files the user and group identifiers of the user running the program, rather than those on tarfile. This is the default behavior for users other than root. If the o function modifier is not set and the user is root, the extracted files will take on the group and user identifiers of the files on tarfile (see chown(1) for more informa- tion). The o function modifier is only valid with the x function. p Restore the named files to their original modes, and ACLs if applicable, ignoring the present umask(1). SETUID and sticky information are also extracted for the super-user. When this function modifier is used with the c function, ACLs are created in the tarfile along with other information. Errors will occur when a tarfile with ACLs is extracted by previous versions of tar. P Suppress the addition of a trailing "/" on directory entries in the archive. v Verbose. Output the name of each file preceded by the function letter. With the t function, v provides addi- tional information about the tarfile entries. The listing is similar to the format produced by the -l option of the ls(1) command. w What. Output the action to be taken and the name of the file, then await the user's confirmation. If the first keystroke is y, the action is performed; other- wise, the action is not performed. This function modifier cannot be used with the t function. X Exclude. Use the exclude-file argument as a file con- taining a list of relative path names for files (or directories) to be excluded from the tarfile when using the functions c, x, or t. Be careful of trailing white spaces. Multiple X arguments may be used, with one exclude-file per argument. In the case where included files (see -I include-file option) are also specified, the excluded files take precedence over all included files. If a file is specified in both the exclude-file and the include-file (or on the command line), it will be excluded. [0-7] Select an alternative drive on which the tape is mounted. The default entries are specified in /etc/default/tar. If no digit or f function modifier SunOS 5.5.1 Last change: 20 Feb 1996 5 tar(1) User Commands tar(1) is specified, the entry in /etc/default/tar with digit "0" is the default. EXAMPLES 1. The following is an example using tar to create an archive of your home directory on a tape mounted on drive /dev/rmt/0: example% cd example% tar cvf /dev/rmt/0 . messages from tar The c function letter means create the archive; the v function modifier outputs messages explaining what tar is doing; the f function modifier indicates that the tarfile is being specified ( /dev/rmt/0 in this example). The dot (.) at the end of the command line indicates the current directory and is the argument of the f function modifier. Display the table of contents of the tarfile with the following command: example% tar tvf /dev/rmt/0 The output will be similar to the following: rw-r--r-- 1677/40 2123 Nov 7 18:15 1985 ./test.c ... example% The columns have the following meanings: +o column 1 is the access permissions to ./test.c +o column 2 is the user-id/group-id of ./test.c +o column 3 is the size of ./test.c in bytes +o column 4 is the modification date of ./test.c +o column 5 is the name of ./test.c To extract files from the archive: example% tar xvf /dev/rmt/0 messages from tar example% If there are multiple archive files on a tape, each is separated from the following one by an EOF marker. To have tar read the first and second archives from a tape with multiple archives on it, the non-rewinding version of the tape device name must be used with the f function modifier, as follows: example% tar xvfp /dev/rmt/0n read first archive from tape SunOS 5.5.1 Last change: 20 Feb 1996 6 tar(1) User Commands tar(1) messages from tar example% tar xvfp /dev/rmt/0n read second archive from tape messages from tar example% Note that in some earlier releases, the above scenario did not work correctly, and intervention with mt(1) between tar invocations was necessary. To emulate the old behavior, use the non-rewind device name containing the letter b for BSD behavior. See the Close Operations section of the mtio(7I) manual page. 2. To archive files from /usr/include and from /etc to default tape drive 0: example% tar c -C /usr include -C /etc . The table of contents from the resulting tarfile would produce output like the following: include/ include/a.out.h and all the other files in /usr/include ... ./chown and all the other files in /etc To extract all files in the include directory: example% tar xv include x include/, 0 bytes, 0 tape blocks and all files under include... 3. The following 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 system (host): example% tar cvfb - 20 files | rsh host dd of=/dev/rmt/0 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 function modifier, specifying the name of the output tarfile using the f function modifier (the standard out- put is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b func- tion modifier. If you want to change the blocksize, you must change the blocksize arguments both on the tar com- mand and on the dd command. SunOS 5.5.1 Last change: 20 Feb 1996 7 tar(1) User Commands tar(1) 4. The following is an example that uses tar to retrieve files from a tape on the remote system back to the local system: example% rsh -n host dd if=/dev/rmt/0 bs=20b | tar xvBfb - 20 files 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 function modifier, telling tar it is reading from a pipe with the B function modifier, specifying the name of the input tarfile using the f function modifier (the standard input is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b function modifier. 5. The following example creates an archive of the home directory on /dev/rmt/0 with an actual blocking factor of 19. example% tar cvfb /dev/rmt/0 19 $HOME To recognize this archive's actual blocking factor without using the b function modifier: example% tar tvf /dev/rmt/0 tar: blocksize = 19 ... To recognize this archive's actual blocking factor using a larger nominal blocking factor: example% tar tvf /dev/rmt/0 30 tar: blocksize = 19 ... Attempt to recognize this archive's actual blocking fac- tor using a nominal blocking factor that is too small: example% tar tvf /dev/rmt/0 10 tar: tape read error ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the execution of tar: LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_TIME, TZ, and NLSPATH. EXIT STATUS The following exit values are returned: 0 Successful completion. SunOS 5.5.1 Last change: 20 Feb 1996 8 tar(1) User Commands tar(1) >0 An error occurred. FILES /dev/rmt/[0-7][b][n] /dev/rmt/[0-7]l[b][n] /dev/rmt/[0-7]m[b][n] /dev/rmt/[0-7]h[b][n] /dev/rmt/[0-7]u[b][n] /dev/rmt/[0-7]c[b][n] /etc/default/tar Settings may look like this: archive0=/dev/rmt/0 archive1=/dev/rmt/0n archive2=/dev/rmt/1 archive3=/dev/rmt/1n archive4=/dev/rmt/0 archive5=/dev/rmt/0n archive6=/dev/rmt/1 archive7=/dev/rmt/1n /tmp/tar* SEE ALSO ar(1), basename(1), cd(1), chown(1), cpio(1), csh(1), dir- name(1), ls(1), mt(1), pax(1), setfacl(1), umask(1), mknod(1M), vold(1M), environ(5), mtio(7I) DIAGNOSTICS Diagnostic messages are output for bad key characters and tape read/write errors, and for insufficient memory to hold the link tables. NOTES There is no way to access for the n-th occurrence of a file. Tape errors are handled ungracefully. When the Volume Management daemon is running, accesses to floppy devices through the conventional device names (for example, /dev/rdiskette) may not succeed. See vold(1M) for further details. The tar archive format allows UIDs and GIDs up to 2097151 to be stored in the archive header. Files with UIDs and GIDs greater than this value will be archived with the UID and GID of 60001. SunOS 5.5.1 Last change: 20 Feb 1996 9