tar Command

Purpose

Manipulates archives.

Syntax

X/Open Standards:

tar {-c|-r|-t|-u|-x} [-B] [ -d ] [ -E ] [ -F ] [-h ] [ -i ] [ -l ] [ -m ] [ -o ] [ -p ] [ -s ] [ -U ] [ -v ] [ -w]

[-Number] [-f Archive] [-b Blocks]
[-S [Feet] [Feet @Density] [Blocksb]] [-L InputList] [-X ExcludeList]
[-N Blocks] [-R] [-D] [-C Directory] [ -Z ] File | Directory ...

Berkeley Standards:

tar { c | r | t | u | x } [ b B d D E f F h i l L X m N o p R s S U v w Z [ 0-9 ] ]

[ Blocks ] [ Archive ] [ InputList ] [ ExcludeFile ]
[ [ Feet ] | [ Feet@Density ] | [ Blocksb ] ] Directory | File ...

Description

Note:

The ustar header format allows for file sizes to be as large as 8 GB. Therefore, the tar command is enabled to archive files of up to 8 GB in size.
tar does not preserve the sparse nature of any file that is sparsely allocated. Any file that was originally sparse before the restoration will have all space allocated within the filesystem for the size of the file.

The tar command manipulates archives by writing files to, or retrieving files from an archive storage medium. The files used by the tar command are represented by the File parameter. If the File parameter refers to a directory, then that directory and recursively all files and directories within it are referenced as well.

The tar command looks for archives on the default device (usually tape), unless you specify another device with the -f Archive flag. When specifying path names that are greater than 100 characters for the United States Tape Archiver (USTAR) format, remember that the path name is composed of a prefix buffer, a / (slash), and a name buffer.

The tar command supports the length of path+filename only till the system defined PATH_MAX limit. Any length of path+filename input greater than PATH_MAX limit is not archived

When writing to an archive, the tar command uses a temporary file (the /tmp/tar* file) and maintains in memory a table of files with several links. You receive an error message if the tar command cannot create the temporary file, or if there is not enough memory available to hold the link tables.

Two groups of flags exist for the tar command: the required flags and the optional flags. The required flags control the actions of the tar command and include the -c, -r, -t, -u, and -x flags. At least one required flag must be selected for the tar command to function. Having selected a required flag, you can select an optional flag but none are necessary to control the tar command.

Note:

When the storage device is an ordinary file or a block special file, the -u and -r flags backspace. However, raw magnetic tape devices do not support backspacing. So when the storage device is a raw magnetic tape, the -u and -r flags rewind the tape, open it, and then read it again.
Records are one block long on block magnetic tape, but they are typically less than half as dense on raw magnetic tape. As a result, although a blocked raw tape must be read twice, the total amount of tape motion is less than when reading one-block records from a block magnetic tape once.
The structure of a streaming tape device does not support the addition of information at the end of a tape. Consequently when the storage device is a streaming tape, the -u and -r flags are not valid options. An attempt to use these flags results in the following error message:
```
tar: Update and Replace options not valid for a 
streaming tape drive.
```
No recovery exists from tape errors.
The performance of the tar command to the IBM®9348 Magnetic Tape Unit Model 12 can be improved by changing the default block size. To change the block size, enter the following at the command line:
```
chdev -1 <device_name> -a block_size=32k
```

For more information on using tape devices see the rmt special file.

Flags

Flags for the tar command are in two groups, the required and the optional. You must supply at least one required flag to control the tar command.

Table 1. Required Flags
Required Flags	Description
-c	Creates a new archive and writes the files specified by one or more File parameters to the beginning of the archive.
-r	Writes the files specified by one or more File parameters to the end of the archive. This flag is not valid for any tape devices because such devices do not support the addition of information at the end of a tape.
-t	Lists the files in the order in which they appear in the archive. Files can be listed more than once.
-u	Adds the files specified by one or more File parameters to the end of the archive only if the files are not in the archive already, or if they have been modified since being written to the archive. The -u flag is not valid for any tape devices because such devices do not support the addition of information at the end of a tape.
-U	Allows archival and extraction of Extended Attributes. The Extended Attributes include Access control list (ACL) also.
-x	Extracts the files specified by one or more File parameters from the archive. If the File parameter refers to a directory, the tar command recursively extracts that directory from the archive. If you do not specify the File parameter, the tar command extracts all of the files from the archive. When an archive contains multiple copies of the same file, the last copy extracted overwrites all previously extracted copies. If the file being extracted does not already exist on the system, the file is created. If you have the proper permissions, the tar command restores all files and directories with the same owner and group IDs as they have on the tape. If you do not have the proper permissions, the files and directories are restored with your owner and group IDs. It is not possible to ask for any occurrence of a file other than the last.

Table 2. Optional Flags
Optional Flags	Description
-B	Forces input and output blocking to 20 blocks per record. With this option, the tar command can work across communications channels where blocking may not be maintained.
-b Blocks	Specifies the number of 512 bytes blocks per record. Both the default and the maximum is 20, which is appropriate for tape records. Due to the size of interrecord gaps, tapes written with large blocking factors can hold much more data than tapes with only one block per record. The block size is determined automatically when tapes are read (the -x or -t function flags). When archives are updated with the -u and -r functions, the existing record size is used. The tar command writes archives using the specified value of the Blocks parameter only when creating new archives with the -c flag. For output to ordinary files with the -f flag, you can save disk space by using a blocking factor that matches the size of disk blocks (for example, the -b4 flag for 2048-byte disk blocks).
-C Directory	Causes the tar command to perform a chdir subroutine to the directory specified by the Directory variable. Using the -C flag allows multiple directories not related by a close common parent to be archived, using short relative path names. For example, to archive files from the /usr/include and /etc directories, you might use the following command: `tar c -C /usr/include File1 File2 -C /etc File3 File4` The -CDirectory flag must appear after all other flags and can appear in the list of file names given.
-D	Suppress recursive processing when directories are specified.
-d	Makes separate entries for block files, special character files, and first-in-first-out (FIFO) piped processes. Normally, the tar command will not archive these special files. When writing to an archive with the -d flag, the tar command makes it possible to restore empty directories, special files, and first-in-first-out (FIFO) piped processes with the -x flag. Restriction: Although anyone can archive special files, only a user with root user authority can extract them from an archive (FIFO can also be extracted by non-root users).
-E	Avoids truncation of the long user and group names during addition of files to new or existing archive.
-F	Checks the file type before archiving. Source Code Control Systems (SCCS), Revision Control Systems (RCS), files named core, errs, a.out, and files ending in .o (dot o) are not archived.
-f Archive	Uses the Archive variable as the archive to be read or written. When this flag is not specified, the tar command uses a system-dependent default file name of the form /dev/rmt0. If the Archive variable specified is - (minus sign), the tar command writes to standard output or reads from standard input. If you write to standard output, the -c flag must be used.
-h	Forces the tar command to follow symbolic links as if they were normal files or directories. Normally, the tar command does not follow symbolic links.
-i	Ignores header checksum errors. The tar command writes a file header containing a checksum for each file in the archive. When this flag is not specified, the system verifies the contents of the header blocks by recomputing the checksum and stops with a directory checksum error when a mismatch occurs. When this flag is specified, the tar command logs the error and then scans forward until it finds a valid header block. This permits restoring files from later volumes of a multi-volume archive without reading earlier volumes.
-L InputList	The Inputlist argument to the -L option should always be the name of the file that lists the files and directories that need to be archived or extracted.
-l	Writes an error message to standard output for each file with a link count greater than 1 whose corresponding links were not also archived. For example, if file1 and file2 are hard-linked together and only file1 is placed on the archive, then the -l flag will issue an error message. Error messages are not displayed if the -l flag is not specified.
-m	Uses the time of extraction as the modification time. The default is to preserve the modification time of the files.
-N Blocks	Allows the tar command to use very large clusters of blocks when it deals with streaming tape archives. Note however, that on input, the tar command cannot automatically determine the block size of tapes with very long block sizes created with this flag. In the absence of a -N Blocks flag, the largest block size that the tar command can automatically determine is 20 blocks.
-o	Provides backwards compatibility with older versions (non-AIX®) of the tar command. When this flag is used for reading, it causes the extracted file to take on the User and Group ID (UID and GID) of the user running the program, rather than those on the archive. This is the default behavior for the ordinary user.
-p	Restores fields to their original modes, ignoring the present umask. The setuid, setgid, and tacky bit permissions are also restored to the user with root user authority. This flag restores files to their original mode but does not restore directories to their original mode.
-R	Use recursion when directories are specified. Ignored when used with the-D option.
-s	Tries to create a symbolic link If the tar command is unsuccessful in its attempt to link (regular link) two files with the -s flag.
-S Blocks b, -S Feet, -S Feet@Density	Specifies the number of 512KB blocks per volume (first format), independent of the tape blocking factor. You can also specify the size of the tape in feet by using the second form, in which case the tar command assumes a default Density variable. The third form allows you to specify both tape length and density. Feet are assumed to be 11 inches long to be conservative. This flag lets you deal more easily with multivolume tape archives, where the tar command must be able to determine how many blocks fit on each volume. Note: Tape drives vary in density capabilities. The Density variable calculates the amount of data a system can fit on a tape. When using 1/4-inch tape devices, be sure to take into account the number of tracks on the tape device when specifying the value for the Feet variable. For example, a 4-track,1/4-inch tape drive with a 600-foot tape and a density of 8000 bpi can be specified using the -S Feet@Density flag as follows: `-S 2400@8000` where 600 feet multiplied by 4 tracks equals 2400 feet.
-U	Archives or restores named extended attributes and ACLs. When listing, this option will display the names of any named extended attributes and the type of any ACLs associated with each file that are part of the archive image.
-v	Lists the name of each file as it is processed. With the -t flag, -v gives more information about the tape entries, including file sizes, times of last modification, User Number (UID), Group Number (GID), and permissions.
-w	Displays the action to be taken, followed by the file name, and then waits for user confirmation. If the response is affirmative, the action is performed. If the response is not affirmative, the file is ignored.
-Number	Uses the /dev/rmtNumber file instead of the default. For example, the -2 flag is the same as the -f/dev/rmt2 file.
-X ExcludeList	Excludes the file names or directories given in the ExcludeList from the tar archive being created, extracted or listed. The ExcludeList shall contain only one filename or directory per line which are to be excluded from the tar archive being created, extracted from or listed. The -X option can be specified multiple times and it takes precedence over all other options.
-Z	Archives the Encrypted File System (EFS) information of encrypted files or directories. The EFS information is extracted by default. When you specify the -t and -v flags along with the -Z flag, an e indicator is displayed after the file mode for encrypted files and directories that were archived with the -Z flag, and a hyphen (-) is displayed after the file mode for other files. Restriction: Archives created with the -Z flag can be restored only on AIX 6.1 or later releases.

Exit Status

This command returns the following exit values:

Item	Description
0	Successful completion.
>0	An error occurred.

Security

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in AIX Version 7.1 Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To write the file1 and file2 files to a new archive on the default tape drive, enter:
tar -c file1 file2
To extract all files in the /tmp directory from the archive file on the /dev/rmt2 tape device and use the time of extraction as the modification time, enter:
```
tar -xm -f/dev/rmt2 /tmp
```
To create a new archive file that contains the file1 file and pass the archive file to the dd command to be written to the /dev/rmt1 device, enter:
```
tar -cvf - file1 | dd of=/dev/rmt1 conv=sync
```
To display the names of the files in the out.tar disk archive file on the current directory, enter:
```
tar -vtf out.tar
```
To expand the compressed tar archive file, fil.tar.z, pass the file to the tar command, and extract all files from the expanded tar archive file, enter:
```
zcat fil.tar.Z | tar -xvf -
```
To archive the contents of /usr/include and /usr/bin files using short relative path names, enter:
```
cd /usr
tar -cvf/dev/rmt0 -C./include . -C ../bin .
```
Requirement: When specifying multiple instances of the -C flag with relative path names, the user must take the previous -C flag request into account.
To archive to an 8-mm device when using the -S flag, enter:
```
tar -cvf /dev/rmt0 -S 4800000b /usr
```
Restriction: When archiving to an 8-mm device, avoid using the -S Feet and -S Feet@Density flags, because the 8-mm device does not use the concept of density when writing to a tape.
To archive a list of all C files that is listed in the file through the InputList argument of the -L option, enter:
```
tar -cvf fl.tar -L fl_list
```
Where fl_list is a file consisting a list of all .c files in it. This can be obtained as follows:
```
ls *.c > fl_list
```
To archive a list of all C files by setting a variable using the -L option, enter:
```
ls *.c > fl_list
fl=fl_list
tar -cvf var.tar -L $fl
```
To avoid the truncation of long user or group names during creation of the archive, enter:
```
tar -cvEf file.tar file
```
To create a new archive file that contains the file1 file with ACL and EA, enter:
```
tar -cvUf /tmp/tar.ar file1 
```

Berkeley Options

The following are examples of the Berkeley options using the tar command:

Tip: With Berkeley options the arguments to the flags should be given in exact order in which the flags are given below. For example:

tar cvfbL test.tar 20 infile

where test.tar is archive tar file, 20 is number of blocks, and infile is Inputlist for the archive.

To archive all directories and complete filenames listed in input list file infile into ar.tar, enter :
```
tar cvfL ar.tar infile
```
Where infile contains the pathnames of files that are to be archived.
To archive files within directories listed in the input list file infile into ar.tar, enter:
```
tar cvRfL ar.tar infile
```
To extract directories and complete files specified in the input list file infile from an archive named ar.tar, enter:
```
tar xvfL ar.tar infile
```
To extract files from within directories and complete files specified in the input list file infile from an archive named ar.tar, enter:
```
tar xvRfL ar.tar infile
```

Files

Item	Description
/dev/rmt0	Specifies the default tape device.
/bin/tar	Specifies the symbolic link to the tar command.
/usr/bin/tar	Contains the tar command.
/tmp/tar*	Specifies a temporary file.

Tip: In AIX 3.2, the entire /bin directory is a symbolic link to /usr/bin.