tar(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | SUMMARY OF TRUSTED SOLARIS CHANGES | FILES | ATTRIBUTES | SEE ALSO | DIAGNOSTICS | NOTES
NAME
- tar– create tape archives and add or extract files
SYNOPSIS
-
tar c [bBefFhiloPpTvwX[0-7]] [block] [tarfile] [exclude-file] {-I include-file| -C| "directory| file"| file…}
tar r [bBefFhilPpTvw[0-7]] [block] {-I include-file| -C directory| file| file…}
tar t [BedfFhilTvX[0-7]] [tarfile] [exclude-file] {-I include-file| file…}
tar u [bBefFhilPpTvw[0-7]] [block] [tarfile] file…
tar x [BedfFhilmopTvwX[0-7]] [tarfile] [exclude-file] [file…]
DESCRIPTION
The tar command archives and extracts files to and from a single file called a tarfile. A tarfile is usually a magnetic tape, but it can be any file. tar's actions are controlled by the key argument. The key is a string of characters 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 contains 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, to subdirectories of that directory. Arguments appearing within braces ({ }) indicate that one of the arguments must be specified.
The tar command provides the functionality to create, update, list the table of contents, and extract a tarfile that contains extended Trusted Solaris security attributes, MLD and SLD information. The tar command also provides the compatibility support to list the table of contents and extract a Trusted Solaris 1.2 tarfile onto a Trusted Solaris 2.5.1 or 7 system. Two new function modifiers, T and d, are added to support these functions; see below for their descriptions.
The tar command operates on a single file called the tarfile. The tarfile is essentially a sequence of the archived files. Each archived file contains the information that is needed to restore a file. When the tarfile contains Trusted Solaris extended security attributes, MLD and SLD information, each archived file is preceded by its own ancillary file, which holds the extended security attributes, MLD and SLD information.
Without privileges, the tar command works within the Trusted Solaris security policy, which is enforced by the file system. When invoked by an ordinary user without privileges, tar works at a single sensitivity label and can be used only to create a tarfile at the sensitivity label of the current workspace.
OPTIONS
- -I include-file
-
Opens include-file containing a list of files, one per line, and treats it as if each file appeared separately on the command line. Be careful of trailing white spaces. Also beware of leading white spaces, since, for each line in the included file, the entire line (apart from the newline) will be used to match against the initial string of files to include. In the case where excluded files (see X function modifier) 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 line), it will be excluded.
- -C directory file
-
Performs a chdir (see cd(1)) operation on directory and performs 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.
The following options are supported:
OPERANDS
- 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 directory.
When a file is archived, and the E flag (see Function Modifiers) is not specified, the filename cannot exceed 256 characters. In addition, it must be possible to split the name between parent directory names so that the prefix is no longer than 155 characters and the name is no longer than 100 characters. If E is specified, a name of up to PATH_MAX characters may be specified.
For example, a file whose basename is longer than 100 characters could not be archived without using the E flag. A file whose directory portion is 200 characters and whose basename is 50 characters could be archived (without using E) if a slash appears in the directory name somewhere in character positions 151-156.
- 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. A file created with extended headers must be updated with extended headers (see E flag under Function Modifiers). A file created without extended headers cannot be modified with extended headers.
- 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 tarfile. An update can be rather slow. A tarfile created on a 5.x system cannot be updated on a 4.x system. A file created with extended headers must be updated with extended headers (see E flag under Function Modifiers). A file created without extended headers cannot be modified with extended headers.
- 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 directory is recursively extracted. The owner, modification time, and mode are restored (if possible); otherwise, to restore owner, tar must be run with user ID of 0. Character-special and block-special devices (created by mknod(1M)) can only be extracted when the tar program has asserted the sys_devices privilege. 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 command of the form:
tar xvf . . . /dev/rmt/0 `tar tf . . . /dev/rmt/0 | grep 'pattern' `
- 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.) The maximum cannot exceed INT_MAX/512 (4194303).
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.
- B
-
Block. Force tar to perform multiple reads (if necessary) 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 standard input, '-', this function modifier is selected by default to ensure that tar can recover from short reads.
- d
-
The function modifier d indicates the tarfile is in Trusted Solaris 1.2 format. This function letter is not valid for the function letters c, r, or u. When this function modifier is used with the function letter t to display tarfile's contents, the tar program processes the input tarfile according to the Trusted Solaris 1.2 format. If the function modifier T is also specified, then the contents of the Trusted Solaris 1.2 tarfile is displayed with a line for each ancillary file and a line for each archived file. The line for an ancillary file has the same filename as its corresponding archived file, but it is suffixed by the string "(A)".
When this function modifier is used with the function letter x to extract a tarfile, the tar program processes the input tarfile according to the Trusted Solaris 1.2 format. If the function modifier T is also specified, the appropriate MLD , SLD information and extended security attributes (which are valid on Trusted Solaris 2.5.1 and 7 systems) are used to restore each archived file.
- e
-
Error. Exit immediately with a positive exit status if any unexpected errors occur. The SYSV3 environment variable overrides the default behavior. (See ENVIRONMENT section below.)
- E
-
Write a tarfile with extended headers. (Used with c, r, or u options; ignored with t or x options.) When a tarfile is written with extended headers, the modification time is maintained with a granularity of microseconds rather than seconds. In addition, filenames no longer than PATH_MAX characters that could not be archived without E, and file sizes greater than 8GB, are supported. The E flag is required whenever the larger files and/or files with longer names, or whose UID/GID exceed 2097151, are to be archived, or if time granularity of microseconds is desired.
- f
-
File. Use the tarfile argument as the name of the tarfile. 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. The SYSV3 environment variable overrides the default behavior. (See ENVIRONMENT VARIABLES section below.)
- h
-
Follow symbolic links as if they were normal files or directories. Normally, tar does not follow symbolic links.
- i
-
Ignore directory checksum errors.
- k size
-
Requires tar to use the size argument as the size of an archive in kilobytes. This is useful when the archive is intended for a fixed size device such as floppy disks. Large files are then split across volumes if they do not fit in the specified size.
- l
-
Link. Output error message if unable to resolve all links to the files being archived. If l is not specified, no error messages are printed.
- m
-
Modify. The modification time of the file is the time of extraction. This function modifier is valid only with the x function.
- n
-
The file being read is a non-tape device. Reading of the archive is faster since tar can randomly seek around the archive.
- 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 when tar is not being run with the user ID of 0. If the o function modifier is not set and the tar command's user ID is 0, the extracted files will take on the group and user identifiers of the files on tarfile (see chown(1) for more information). 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). This is the default behavior if invoked by the user ID of 0 with the x function letter specified. If tar is invoked with the user ID of 0, SETUID and sticky information are also extracted, and files are restored with their original owners and permissions, rather than owned by root. 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.
- T
-
When this modifier is used with the function letter c, r, or u for creating, replacing or updating a tarfile, the extended security attributes, MLD and SLD information associated with each archived file are stored in the tarfile. The tar command also traverses any MLD it encounters. Hence, SLDs dominated by the tar process's sensitivity label are walked, or all SLDs are walked with certain privileges.
Specifying T implies the function modifier p.
When used with the function letter t, the tarfile content is displayed with a line for each ancillary file and a line for each archived file. The line for an ancillary file has the same filename as its corresponding archived file, but it is suffixed by the string "(A)".
When used with the function letter x for extracting a tarfile, the tar program attempts to restore each archived file using the MLD and SLD information, and the extended security attributes.
- q
-
Stop after extracting the first occurrence of the named file. tar will normally continue reading the archive after finding an occurrence of a file.
- v
-
Verbose. Output the name of each file preceded by the function letter. With the t function, v provides additional 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 response is affirmative, the action is performed; otherwise, 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 containing 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. Also beware of leading white spaces, since, for each line in the excluded file, the entire line (apart from the newline) will be used to match against the initial string of files to exclude. 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 is specified, the entry in /etc/default/tar with digit "0" is the default.
The following operands are supported:
Function Letters
The function portion of the key is specified by one of the following letters:
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 backspace or append capabilities.
When using the r, u, or x functions or the X function modifier, 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 function displays how each file was archived.
Function Modifiers
The characters below may be used in conjunction with the letter that selects the desired function.
USAGE
See largefile(5) for the description of the behavior of tar when encountering files greater than or equal to 2 Gbyte ( 231 bytes).
The automatic determination of the actual blocking factor may be fooled when reading from a pipe or a socket (see the B function modifier below).
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.
For information on tar header format, see archives(4).
EXAMPLES
-
column 1 is the access permissions to ./test.c
-
column 2 is the user-id/group-id of ./test.c
-
column 3 is the size of ./test.c in bytes
-
column 4 is the modification date of ./test.c. When the LC_TIME category is not set to the POSIX locale, a different format and date order field may be used.
-
column 5 is the name of ./test.c
Example 1 Using the tar Command to Create an Archive of Your Home Directory
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 |
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 for the POSIX locale:
rw-r--r-- 1677/40 2123 Nov 7 18:15 1985 ./test.c … example% |
The columns have the following meanings:
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 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.
Example 2 Using tar to Archive Files from /usr/include and from /etc to Default Tape Drive 0:
To archive files from /usr/include and from /etc to default tape drive 0:
example% tar c -C /usr include -C /etc . |
include/ include/a.out.h and all the other files in /usr/include . . . ./chown and all the other files in /etc |
example% tar xv include x include/, 0 bytes, 0 tape blocksand all files under include . . . |
Example 3 Using tar to Transfer Files Across the Network
The following is an example using tar to transfer files across the network. 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% |
Example 4 Using tar to Retrieve Files From a Tape on the Remote System Back to the Local System:
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% |
Example 5 Creating an Archive of the Home Directory on /dev/rmt/0 with a Blocking Factor of 19
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 |
example% tar tvf /dev/rmt/0 tar: blocksize = 19 . . . |
example% tar tvf /dev/rmt/0 30 tar: blocksize = 19 . . . |
example% tar tvf /dev/rmt/0 10 tar: tape read error |
Example 6 Creating a tar File with Extended Security Attributes
The following example uses tar to create a tarfile of the tartest directory and save the extended security attributes, MLD and SLD information.
example% cd example% tar cvfT onetarfile tartest |
The output will be similar to the following:
a tartest/(A) 1K a tartest/ 0K a tartest/file1(A) 1K a tartest/file1 0K a tartest/mld1/(A) 1K a tartest/mld1/ 0K a tartest/mld1/(A) 1K a tartest/mld1/ 0K a tartest/mld1/file50(A) 1K a tartest/mld1/file50 1K … |
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 name of the tarfile to be created ( onetarfile in this example). The T function modifier indicates that the extended security attributes, MLD and SLD information for each archived file are stored in the tarfile. The tartest is the name of the directory from which to create the tarfile.
The lines that end with (A) are the ancillary files for each archived file.
Display the table of contents of the tarfile (onetarfile in this example) with the following command:
example% tar tvfT onetarfile |
The output will be similar to the following:
drwxr-xr-x 35436/10 54 Nov 11 17:07 1996 tartest/(A) drwxr-xr-x+35436/10 0 Nov 11 17:07 1996 tartest/ -rw-r--r-- 35436/10 64 Nov 11 10:40 1996 tartest/file1(A) -rw-r--r--+35436/10 0 Nov 11 10:40 1996 tartest/file1 drwxr-xr-x 35436/10 82 Nov 11 11:44 1996 tartest/mld1/(A) drwxr-xr-x+35436/10 0 Nov 11 11:44 1996 tartest/mld1/ drwxr-xr-x 35436/10 87 Nov 11 11:33 1996 tartest/mld1/(A) drwxr-xr-x+35436/10 0 Nov 11 11:33 1996 tartest/mld1/ -rw-r--r-- 35436/10 106 Nov 11 11:06 1996 tartest/mld1/file50(A) -rw-r--r--+35436/10 17 Nov 11 11:06 1996 tartest/mld1/file50… |
The lines that end with (A) are ancillary files for each archived file.
Extract files from the tarfile (onetarfile in this example) with the following command:
example% tar xvfT onetarfile |
The output will be similar to the following:
x tartest/(A), 54 bytes, 1 tape blocks x tartest/, 0 bytes, 0 tape blocks x tartest/file1(A), 64 bytes, 1 tape blocks x tartest/file1, 0 bytes, 0 tape blocks x tartest/mld1/(A), 82 bytes, 1 tape blocks x tartest/.MLD.mld1/, 0 bytes, 0 tape blocks x tartest/mld1/(A), 87 bytes, 1 tape blocks x tartest/.MLD.mld1/.SLD.0/, 0 bytes, 0 tape blocks x tartest/mld1/file50(A), 106 bytes, 1 tape blocks x tartest/.MLD.mld1/.SLD.0/file50, 17 bytes, 1 tape blocks… |
The lines that end with (A) are ancillary files for each archived file.
ENVIRONMENT VARIABLES
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
SUMMARY OF TRUSTED SOLARIS CHANGES
tar provides a function modifier T for creating, processing, and extracting a tarfile containing the extended security attributes, and MLD and SLD information. When an MLD is encountered in creating or updating a tarfile, the MLD is traversed according to the tar process's sensitivity label and privileges.
In addition, tar provides another function modifier for processing and extracting a tarfile created on a Trusted Solaris 1.2 system. The function modifier d can be used only with the function letters t and x.
MAC restrictions apply when tar is used. Appropriate privileges may be required to override access checks that are enforced for the create, update and extract operations.
For creating or updating a tarfile, one or more of the following privileges may be required: file_mac_read, file_mac_write, file_mac_search, file_dac_read, file_dac_write, file_dac_search, or sys_trans_label.
The extended security attributes that require privileges to restore, are restored when the appropriate privileges are present. Hence, to successfully extract files from a tarfile and restore the extended security attributes, one or more of the following privileges may be required: file_mac_read, file_mac_write, file_dac_read, file_dac_write, file_setdac, file_setid, file_chown, file_owner, file_downgrade_sl, file_upgrade_sl, file_setpriv, file_audit, sys_devices, or sys_trans_label.
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*
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Availability | SUNWcsu |
| CSI | Enabled |
SEE ALSO
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 the nth 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.
If an archive is created that contains files whose names were created by processes running in multiple locales, a single locale that uses a full 8-bit codeset (for example, the en_US locale) should be used both to create the archive and to extract files from the archive.
Notes for function modifier T and d:
For Trusted Solaris 1.2, Trusted Solaris 2.5.1, and Trusted Solaris 7 tarfiles, a compatible label_encodings(4) file is expected between the time the tarfile is created or updated and the time the tarfile is extracted.
When a Trusted Solaris 1.2 tarfile is restored on a Trusted Solaris 2.5.1 system, the label SYSTEM_HIGH is mapped to the label ADMIN_HIGH, and the label SYSTEM_LOW is mapped to the label ADMIN_LOW. In addition, the privileges and file audit mask are not used
for the restored files because their formats are not compatible with Trusted Solaris 2.5.1 and 7's equivalent security attributes.
If the name of the linked file in a symbolic link contains explicitly adorned MLD names and/or SLD names, it may no longer be a valid pathname after extraction. The reason is that the MLD adornment and SLD name at the time the tarfile is created or updated might be different than they are at the time the tarfile is extracted. At extraction time, tar attempts to update the link pathname of the symbolic link with the proper MLD adornment and SLD name. If tar fails, an error message is issued. Users need to perform any corrections themselves after the extraction is done.
Extracting a Trusted Solaris 2.5.1 tarfile on a Solaris 2.5 system may cause directory-checksum errors. Use the -i option, which ignores directory-checksum errors, to get around this problem.
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | SUMMARY OF TRUSTED SOLARIS CHANGES | FILES | ATTRIBUTES | SEE ALSO | DIAGNOSTICS | NOTES
- © 2010, Oracle Corporation and/or its affiliates