NAME

tar - file archiver (LEGACY)

 SYNOPSIS

tar key [file...]

 DESCRIPTION

The tar utility processes archives of files. Its actions are controlled by the key operand.

 OPTIONS

None.

 OPERANDS

The following operands are supported:

key

The key operand consists of a function letter followed immediately by zero or more modifying letters. The function letter is one of the following:

r

Write the named file or files on the end of the archive. If the archive is on a magnetic tape device, the results are unspecified.

x

Extract the named file or files from the archive. If a named file matches a directory whose contents had been written onto the archive, this directory is (recursively) extracted. If a named file in the archive does not exist on the system, the file is created with the same mode as the one in the archive, except that the set-user-ID and set-group-ID modes are not set unless the user has appropriate privileges. If the files exist, their modes are not changed except as described above. The owner, group, and modification time are restored (if possible). If no file operand is given, the entire content of the archive is extracted. Note that if several files with the same name are in the archive, the last one overwrites all earlier ones.

t

Write to standard output the names of all the files in the archive.

u

Add the named file or files to the archive if they are not already there, or have been modified since last written into the archive. If the archive is on a magnetic tape device, the results are unspecified.

c

Create a new archive; writing begins at the beginning of the archive, instead of after the last file.

The following characters can be appended to the function letter. Appending the same character more than once produces undefined results. The order of the b and f characters is significant.

v

(Verbose.) Write to standard error the name of each file processed, preceded by a string indicating the operation being performed, as follows:

Key Letter	String
c, r, u	"a "
x	"x "

The filename may be followed by additional information, such as the size of the file in the archive or file system, in an unspecified format. When used with the t function letter, v writes to standard output more information about the archive entries than just the name.

w

Write the action to be taken, followed by the name of the file, and then wait for the user's confirmation. If an affirmative response is given, the action is performed. Any other input suppresses the action.

f

Use the first file operand (or the second, if b has already been specified) as the name of the archive instead of the system-dependent default. If the name of the file is -, 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 pipeline. The tar utility can also be used to move directory hierarchies with the command:

(cd fromdir; tar cf - . ) | (cd todir; tar xf -)

b

Use the first file operand (or the second, if f has already been specified) as the blocking factor for tape records. The default is not greater than 20; the maximum is not less than 20. This modifier should only be used with raw magnetic tape archives (see f above). The block size is determined automatically when reading tapes (function letters x and t).

l

Report if all of the links to the files being archived cannot be resolved. If l is not specified, no error messages are written.

m

Do not restore the modification times. The modification time of the file will be the time of extraction.

o

Assign to extracted files the user and group identifier of the user running the program rather than those on the archive.

file

A pathname of a regular file or directory to be archived (when the c, r or u function letters are used), extracted (x ) or listed (t ). When file is the pathname of a directory, the action applies to all of the files and (recursively) subdirectories of that directory. When either or both of the b or f letters are used in the key operand, the initial file operands are interpreted as a blocking factor or archive name, as described previously.

 STDIN

When the f modifier is used with the t or x function letter and the pathname is -, the standard input is an archive file formatted as specified by pax with the -x ustar option. Otherwise, the standard input is not used.

 INPUT FILES

The files identified by the file operands are regular files or directories.

 ENVIRONMENT VARIABLES

The following environment variables may affect the execution of tar:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_COLLATE

Determine the locale for the behaviour of ranges, equivalence classes and multi-character collating elements used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files) and the behaviour of character classes used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_MESSAGES

Determine the locale for the processing of affirmative responses and that should be used to affect the format and contents of diagnostic messages written to standard error.

LC_TIME

Determine the format of date and time strings output when listing the contents of an archive with the v modifier; for example:

tar tvf /dev/tape

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

TZ

Determine the timezone used with date and time strings.

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

When the f modifier is used with the r, u or c function letter and the pathname is -, the standard output is an archive file formatted as specified by pax with the -x ustar option. When the t function letter is used, the standard output consists of the names of the files in the archive, separated by newline characters; if v is used with t, the standard output includes additional information in an unspecified format. Otherwise, the standard output is not used.

 STDERR

The standard error is used for diagnostic messages and the filename output described under the v modifier (when the t function letter is not used).

 OUTPUT FILES

Output files are created, as specified by the archive, when the x function letter is used.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

Some systems have usually had blocking factors in the range 1 to at least 127 with a default of 20 while other systems have usually had blocking factors in the range 1 to 20 with a default of 1. For maximum portability, applications should specify a blocking factor no larger than 20.

For portable communication of data between XSI-conformant systems, it is recommended that only characters defined in the ISO/IEC 646:1991 standard International Reference Version (equivalent to ASCII) 7-bit range of characters be used and that only characters defined in the Portable Filename Character Set be used for naming files. This recommendation is given because XSI-conformant systems support diverse codesets and run in various geographical areas and there is no single, well established codeset that incorporates all of the characters of the languages of the various geographical areas.

Note that the tar format can only support files up to 8 gigabytes in size.

Applications should migrate to the pax utility.

 EXAMPLES

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

cpio, pax.