Commands Reference, Volume 5

tar { -c | -r | -t | -u | -x } [ -b Blocks ] [ -B ] [ -d ] [ -F ] [ -h ] [ -i ] [ -L InputList ] [ -l ] [ -m ] [ -N Blocks ][ -o ] [ -p ] [ -s ] [ -v ] [ -w ] [ -Number ] [ -f Archive ] [ -S Blocksb | -S Feet | -S Feet@Density ] [ File | Directory | -C Directory ] ...

Description

Attention: Because of limitations on header block space in the tar command, user numbers (UIDs), and group identification numbers (GIDs) larger than 65,535 will be corrupted when restored to certain systems. The size constraint affects only the ownership and permissions causing no damage to the data. Corruption of the ownership occurs on the following systems:

Those that do not use uname and gname fields to check ownership.
Those that do not have the same user and group IDs as the archiving system.

Note:

The tar command is not enabled for files greater than 2 Gig in size due to limitations imposed by XPG/4 and POSIX.2 standards.
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 prefix buffer can be a maximum of 155 bytes and the name buffer can hold a maximum of 100 bytes. If the path name cannot be split into these two parts by a slash, it cannot be archived. This limitation is due to the structure of the tar archive headers, and must be maintained for compliance with standards and backwards compatibility. In addition, the length of a destination for a hard or symbolic link ( the 'link name') cannot exceed 100 bytes.

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.

Notes:
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.

Required Flags
-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.
-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.
Optional Flags
-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	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. Note: Although anyone can archive special files, only a user with root user authority can extract them from an 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 be always a name of file listing the files and directories that need to be archived. Alternatively the InputList argument can be a variable holding the name of the file that lists the files and directories that is to be archived. This option helps in writing the files and directories listed in the InputList argument to the archive. Directories from the InputList argument are not treated recursively. For directories contained in the InputList argument, the tar command writes only the directory to the archive, not the files and subdirectories rooted in the directory. If additional files and directories follow the InputList argument on the command line, the contents of the InputList argument are archived after these files and directories. These additional files or directories are archived with their default behavior, which is to treat them recursively.
-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.
-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.
-SBlocksb, -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.
-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.

Exit Status

This command returns the following exit values:

0	Successful completion.
>0	An error occurred.

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 .
```
Note: 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
```
Note: When archiving to an 8-mm device, the -S Feet and -S Feet@Density flags are not recommended, since 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
```

Files

/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.

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

Related Information

The cat command, dd command, pax command.

The rmt special file.

File Systems Overview for System Management in AIX 5L Version 5.1 System Management Concepts: Operating System and Devices explains file system types, management, structure, and maintenance.

Directory Overview in AIX 5L Version 5.1 System User's Guide: Operating System and Devices explains working with directories and path names.

Files Overview in AIX 5L Version 5.1 System User's Guide: Operating System and Devices provides information on working with files.