8.4.34 tar command (stores the target path name in the archive and extracts/displays the target path name)
Syntax
- [Only for Windows]
-
tar {-c|-r|-t|-u|-x} [-b blocking-factor] [-d] [-f archive] [-h] [-m] [-P] [-V] [-v] [-Xexcluded-list-file] [-z] [--cmdrc0] [--compatible=type] [-C directory] [-T file] [target-path-name...] tar {c|r|t|u|x}[b][d][f][h][m][P][V][v][X][z] [blocking-factor] [archive] [excluded-list-file] [--cmdrc0] [--compatible=type] [-C directory] [-T file] [target-path-name...]
- [Only for UNIX]
-
tar {-c|-r|-t|-u|-x} [-b blocking-factor] [-d] [-f archive] [-h] [-m] [-P] [-p] [-V] [-v] [-Xexcluded-list-file] [-z] [--cmdrc0] [--compatible=type] [-C directory] [-T file] [target-path-name...] tar {c|r|t|u|x}[b][d][f][h][m][P][p][V][v][X][z] [blocking-factor] [archive] [excluded-list-file] [--cmdrc0] [--compatible=type] [-C directory] [-T file] [target-path-name...]
Description
Stores the target path name in the archive and extracts/displays the target path name from the archive. The behavior of the command is determined by specifying one function character (c, r, t, u, or x) and another function modifier.
The archive that is created by this command is in the ustar format.
Arguments
Options of function characters
-c
- --create
-
This command creates a new archive. The command stores the target path name from the beginning of the archive. If the target path name is a directory, the portion in the directory is also stored.
-r
- --append
-
This command additionally stores the target path name at the end of the specified archive.
-t
- --list
-
This command displays a list of the names of the files in the archive.
The following detailed information appears if this option is specified with the -v option:
"permission uid/gid file-size date/time file-name"
-u
- --update
-
This command additionally stores files for which the target path name is newer than the file with the same name and files that are not stored in the archive.
-x
--extract
- --get
-
This command extracts the target path name from the archive. If the target path name is a directory, the portion in the directory is also extracted.
Files are extracted as follows:
-
If there is an existing file, this command creates a file after deleting the existing file (the permission of the existing file is not retained).
If you do not specify the -p option in UNIX, the permission is determined according to the permission stored in the archive and umask. If the executor is a non-Administrator user, setuid bit, setgid bit, and sticky bit are not set.
If the directory already exists, the extracted file is recovered in the corresponding directory.
-
If the executor is a superuser in UNIX, users and groups are extracted and set.
-
In Windows, the permission, user, and group are not extracted and set.
-
Function modifier options
-b blocking-factor
- --blocking-factor=blocking-factor
-
Block size is blocking factor * 512 bytes.
The default value is 20 (block size is 20 * 512 bytes).
The range that can be specified for the blocking factor is 1 to 63.
This option is enabled when this option is specified with the -c option. If this option is specified with the -t and -x options, the specification becomes invalid.
If this option is specified with the -r and -u options, the option is determined with the archive size and the specified blocking factor.
For multiple specifications, the blocking factor specified last is enabled.
If a value outside the allowed range is specified, this option operates assuming that 20 has been set.
- -d
-
Upon storage in the archive, this command stores special files and pipe files in the archive also.
This option is added by default and there are no differences in actions regardless of the existence of options.
-f archive
- --file= archive
-
This command specifies the archive. Archives that can be specified are regular files, pipe files, and symbolic link files.
If this option is not specified or "-" (hyphen) is specified, the standard input/output is indicated.
For the -r and -u options, you cannot use the combination of a standard input/output and a pipe file.
If you specify this option multiple times, the archive specified last is enabled.
-h
- --dereference
-
This command follows a symbolic link and handles the link as a file or directory.
This option is enabled when this option is specified together with the -c, -r, and -u options. If this option is specified with the -t and -x options, the specification becomes invalid.
-m
- --touch
-
The most recent modification date and time of the file is extracted but not set.
This option is enabled when this option is specified with the -x option. If this option is specified with the -c, -r, -u, and -t options, the specification becomes invalid.
In Windows, the most recent modification date and time of the directory cannot be set regardless of the specification of the -m option.
-P
- --absolute-names
-
This command does not remove the root directory of the target path name.
-p
--same-permissions
- --preserve-permissions
-
[Only for UNIX]
Permissions are extracted and set. This option is enabled when this option is specified with the -x option. If this option is specified with the -c, -r, -u, and -t options, the specification becomes invalid.
The superuser operates with the default setting.
- -V
-
When displaying the detailed information of the archive, English characters indicating the type of file are also output.
This option is added by default and there are no differences in actions regardless of the existence of options.
-v
- --verbose
-
This command outputs detailed information.
-z
--gzip
--gunzip
- --ungzip
-
Handles gzip archives.
If this option is specified together with the -c option, a new archive is created by compressing the data in gzip format.
If this option is specified together with the -x option, the target path name is extracted from the gzip archive.
If this option is specified together with the -t option, a list of names of files stored in the gzip archive is displayed.
When a gzip archive is used, the tar command calls the gzip command. To pass the options of the gzip command to the gzip command that is called by the tar command, set the options of the gzip command in the environment variable GZIP, and then execute the tar command. For details about the environment variable GZIP, see 2.5 Specifying environment variables.
The -z option cannot be specified together with the -r option or -u option. If the -z option is specified together with the -r or -u option, an error occurs and the processing ends.
If this option is specified together with the -x or -t option and the archive is not compressed in gzip format, the target path name cannot be extracted, and a list of file names cannot be displayed.
Note that the --gzip, --gunzip, and --ungzip options only signify the long options of the -z option. For example, when the -c and --gunzip options are specified, a new archive is created by compressing the data in gzip format.
- --cmdrc0
-
The return value must be set to 0 even if an error occurs after this command analyzes options.
- --compatible=Type
-
You can specify the following character string for Type:
long-file-name
When storing the target path name in the archive, the following restrictions apply with respect to the header area in the archive: the directory path length is 155 bytes, file name is 100 bytes, and the length of file name of the link destination of the symbolic link is 100 bytes.
When using this option, restrictions can be removed. (Up to 3072 bytes can be specified for the target path name. The length of the path name that can actually be created depends on the maximum length for each OS.)
However, the archive created with this option may not be compatible with the tar command in the ustar format provided by the OS.
This option is enabled when this option is specified with the -c, -r, and -u options. If this option is specified with the -t and -x options, the specification is ignored.
-C directory
- --directory= directory
-
This command enables operation upon jumping to the specified directory.
If you combine the target path name, -T option, and -C option, the target path specified after the -C option becomes the target.
If you specify the -C option multiple times, note that the current directory is moved by the previously specified -C option when you specifying the -C option for the second time or later.
-T file
-L file
-I file
- --files-from= file
-
This command loads, from the specified file, a list of the target paths to be stored, extracted, or displayed. You must accurately describe one target path name in each line. Spaces and blank lines are treated as path names.
When multiple files are specified, all specifications become valid.
Actions of the short options of the -T, -L, and -I options are the same regardless of their specifications.
If this option is combined with the -x or -t option, you can specify the target path name with a combination of wildcards.
To specify the characters used as the wildcards, you can escape with \ and you need to escape with \ for a specification with \.
Characters that can be used as the wildcards are as follows:
Wildcard
Meaning
?
Matches any single character.
*
Matches a character string of zero or more characters.
[...]
Matches any single character in the character string enclosed in [ ]. If there is an ! or a ^ at the beginning of the character string enclosed in [ ], there is a match if none of the characters in [ ] are found. If two characters are separated by a hyphen (-), the match is of any character between those two characters (including the two characters themselves).
The following examples in the table illustrate the use of the [ ] wildcards:
Examples
Meaning
[!abc]
Matches any character other than a, b, or c.
[0-9]
Matches any character from 0 through 9.
[a-z]
Matches any lowercase letter.
[A-Z]
Matches any uppercase letter.
[0-9a-zA-Z]
Matches any alphanumeric character.
-X file
- --exclude-from= file
-
This command loads, from the specified file, a list of the target paths that are to be excluded from being stored, extracted, or displayed. You must describe one target path name in each line. The target paths will be excluded from the description of the partial directory path.
Spaces and blank lines are treated as path names.
The list of files to be excluded that are specified with this option is prioritized over the file list specified with the -T, -L, -I, and --files-from options.
The target path name can be specified with a combination of wildcards. To specify the characters used as the wildcards, you can escape with \ and you need to escape with \ for a specification with \.
Characters that can be used as the wildcards are as follows:
Wildcard
Meaning
?
Matches any single character.
*
Matches a character string of zero or more characters.
[...]
Matches any single character in the character string enclosed in [ ]. If there is an ! or a ^ at the beginning of the character string enclosed in [ ], there is a match if none of the characters in [ ] are found. If two characters are separated by a hyphen (-), the match is of any character between those two characters (including the two characters themselves).
The following examples illustrate the use of the [ ] wildcards:
Examples
Meaning
[!abc]
Matches any character other than a, b, or c.
[0-9]
Matches any character from 0 through 9.
[a-z]
Matches any lowercase letter.
[A-Z]
Matches any uppercase letter.
[0-9a-zA-Z]
Matches any alphanumeric character.
- Target-path-name
-
This option specifies the path name of the file or directory to be stored, extracted, or displayed.
If the target path name is identical to the archive at the time of storage, the path name is not stored.
For restrictions on the length of the target path name, refer to the --compatible=long-file-name option.
If this option is combined with the -x or -t option, you can specify the target path name with a combination of wildcards.
To specify the characters used as the wildcards, you can escape with \ and you need to escape with \ for a specification with \.
Characters that can be used as the wildcards are as follows:
Wildcard
Meaning
?
Matches any single character.
*
Matches a character string of zero or more characters.
[...]
Matches any single character in the character string enclosed in [ ]. If there is an ! or a ^ at the beginning of the character string enclosed in [ ], there is a match if none of the characters in [ ] are found. If two characters are separated by a hyphen (-), the match is of any character between those two characters (including the two characters themselves).
The following examples illustrate the use of the [ ] wildcards:
Examples
Meaning
[!abc]
Matches any character other than a, b, or c.
[0-9]
Matches any character from 0 through 9.
[a-z]
Matches any lowercase letter.
[A-Z]
Matches any uppercase letter.
[0-9a-zA-Z]
Matches any alphanumeric character.
Handling of the root directory of the target path name to be stored or extracted
The command is executed after removing the root directory of the target path name when storing or extracting the path name. The following table shows the corresponding root directories. It is possible to execute the command without removing the root directory of the target path name by using the -P option.
If you specify the ADSH_CMDTAR_ROOTPATH environment variable, you can change the default action of the command from "remove the root directory of the target path name" to "do not remove the root directory of the target path name".
OS |
Description |
---|---|
UNIX |
When storing or extracting the target path name, the following root directory at the beginning is removed: / ../ |
Windows |
When storing or extracting the target path name, the following root directory at the beginning is removed: \ ..\ Drive letter:\ |
-
The ADSH_CMDTAR_ROOTPATH environment variable is not specified.
As the default behavior of the command, the command executes storage and extraction after removing the root directory. If you do not want to remove the root directory, execute the command upon specifying the -P option.
-
The ADSH_CMDTAR_ROOTPATH environment variable is specified.
If you set ADSH_CMDTAR_ROOTPATH=absolute, the command executes storage and extraction without removing the root directory as the default behavior of the command.
Handling of user name, user ID, group name, and group ID
The handling of the user and group during creation, extraction, and display of the archive is as follows: If the archive is operated between multiple platforms, the users and groups might differ.
Status of archive |
User ID/name |
Group ID/name |
---|---|---|
When creating an archive |
|
|
When extracting an archive |
|
|
When displaying an archive |
|
|
Temporary file directory
This command might create a temporary file. Temporary file directories are as follows:
- In Windows
-
common application folder\HITACHI\JP1AS\misc
- In UNIX
-
Directory defined in the TMPDIR environment variable
/var/tmp if the TMPDIR environment variable has not been defined.
Return codes
Return code |
Meaning |
---|---|
0 |
Normal termination. |
1 |
Termination with an error. Case 2 is excluded. |
2 |
Termination with an error. An invalid option has been specified. |
Notes
-
If you specify the syntax with the short option without "-", the options and operands need to be specified in the order displayed in "syntax".
-
For symbolic links, the most recent modification date/time and the final access date/time are not retained.
-
If you pause the tar command while the target path name is being stored in the archive, a temporary file with the following name might remain: In such case, you will need to manually delete the temporary file.
- [In Windows]
-
tar.XXXXXX (XXXXXX is an arbitrary character string of 6 characters.)
- [In UNIX]
-
tarppppp.XXXXXXXX (ppppp is the process ID with 5 or more digits and XXXXXXXX is an arbitrary 8-character character string.)
-
If an unknown file is detected during extraction, an attempt is made to process the file as a regular file.
In Windows, extracted block device files, character device files and pipe files are determined as unknown file types.
(Example)
C:\TEMP>%ADSH_OSCMD_DIR%\tar xvf PIPE.tar tar: PIPE/pp creating as regular file. PIPE/pp
-
If there are multiple path names having the same name in the archive, the older files are overwritten by the most recent path name.
-
In Windows, storage and extraction of UNC paths are not supported.
-
In Windows, if the extracted file name only has a difference in the use of upper and lowercase letters, the file is treated as the same file.
-
In Windows, short name specification executes storage, extraction and, display with the long name. However, the destination of the symbolic link stores, extracts, and displays with the specified file name.
-
In Windows, if backslashes (\) are used to separate directories, storage and extraction are converted and unified by using slashes (/).
-
In Windows, junctions are processed as actual files.
-
In Windows, the user must have the authority to create symbolic links to extract a symbolic link.
-
In Windows, link files cannot be extracted to a file system other than NTFS.
-
In Windows, it is not possible to extract a symbolic link in a state where the destination of the symbolic link does not exist.
-
If you store a file that includes backslashes (\) in UNIX and extract the file in Windows, backslashes (\) are used as directory separators.
-
If a file is stored in Windows and extracted in UNIX, the directory hierarchy of path specification that is unique to Windows might vary between the time when the file is stored and the time when the file is extracted.
(Example)
The driver letter is determined as part of the directory in UNIX.
An example where the drive letter is used is as follows:
Storing with Windows C:\TEMP>%ADSH_OSCMD_DIR%\tar cvfP reg.tar G:\DIR\regfile G:/DIR/regfile Extracting with UNIX $ tar xvf reg.tar G:/DIR/regfile $ ls -lR ./G: total 8 drwxrwxr-x 2 USER1 GROUP1 4096 Oct 30 15:59 DIR ./G:/DIR: total 8 -rw-rw-r-- 1 USER1 GROUP1 3 Oct 30 15:59 regfile
The driver letter is created as a directory in UNIX.
-
-
In UNIX, special files must be extracted by a user who has permission to create special files.
-
This command supports operation only on archives that were created by the command itself. When operating the archive between the tar command provided by each OS and the tar command of JP1/AS, due to differences in the archive format, files might not be stored, extracted, or displayed correctly.
-
If encoding varies upon storage, extraction, or display, the file name might not be extracted or displayed correctly.
-
Storing a file larger than 8GB in the archive and extracting and displaying a file larger than 8GB are not supported.
-
For UNIX, user IDs, group IDs, major numbers, and minor IDs exceeding 2097152 are not supported.
-
Files in which the number of characters of the user name and group name is 32 characters or more are not supported.
Examples
- Example 1 Creation of archive
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar cvf ar.tar ar ar ar/file1 ar/file2
- Example 2 Extraction of archive
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar xvf ar.tar ar ar ar\file1 ar\file2
- Example 3 Display of archive
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar tvf ar.tar drwx------ 1234/5678 0 Oct 30 15:52:24 2015 ar -rw------- 1234/5678 0 Oct 30 15:52:24 2015 ar/file1 -rw------- 1234/5678 0 Oct 30 15:52:24 2015 ar/file2
- Example 4 Additional storage of archive (when using the -r option)
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar rvf ar.tar ar tar: Reading archive to position at the end...done. ar ar/file1 ar/file2
- Example 5 Additional storage of archive (when using the -u option)
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar uvf ar.tar ar tar: Reading archive to position at the end...done. ar/file2
Although ar/file2 is already stored in ar.tar, the ar/file2 to be stored is stored due to having a later time compared to the file of ar.tar.
- Example 6 Cross-platform storage and extraction
-
Storing with Windows C:\TEMP>%ADSH_OSCMD_DIR%\tar cvf reg.tar .\regfile ./regfile Extracting with UNIX $ tar xvf reg.tar ./regfile
- Example 7 Setting the archive destination as a standard input/output
-
$ tar cvf - regfile > reg.tar regfile $ cat reg.tar | ./tar tvf - -rw------- 1234/5678 5 Feb 17 16:47:28 2015 regfile
- Example 8 Storing a file with a path name that is unique to Windows and extracting the file in UNIX
-
Storing with Windows C:\TEMP>%ADSH_OSCMD_DIR%\tar cvfP reg.tar G:\DIR\regfile G:/DIR/regfile Extracting with UNIX $ ./tar xvf reg.tar G:/DIR/regfile $ ls -lR ./G: total 8 drwxrwxr-x 2 USER1 GROUP1 4096 Oct 30 15:59 DIR ./G:/DIR: total 8 -rw-rw-r-- 1 USER1 GROUP1 3 Oct 30 15:59 regfile
For extraction in UNIX, G: is also extracted as the directory.
- Example 9 Extraction as a superuser
-
$ ./tar tvf reg.tar -rw-rw-r-- 1234/5678 3 Oct 30 15:59:00 2015 regfile Extraction as superuser # ./tar xvf reg.tar regfile # ls -al regfile -rw-rw-r-- 1 USER1 GROUP1 3 Oct 30 15:59 regfile
If a file is extracted as a superuser, the user and group are extracted and set.
- Example 10 Storing files with a different path name as the same parent directory
-
DIR1/SUB1/file1 DIR2/SUB1/file2 exists and the tar command is executed in the same hierarchy as DIR1 and DIR2 $ tar -c -v -f ar.tar -C DIR1 SUB1 -C ../DIR2 SUB1 SUB1 SUB1/file1 SUB1 SUB1/file2
- Example 11 Creating a gzip archive
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar cvzf ar.tar.gz ar ar ar/file1 ar/file2
- Example 12 Creating a gzip archive by specifying the gzip command option for the environment variable GZIP
-
$ export GZIP="-9 -q" $ /opt/jp1as/cmd/tar cvzf ar.tar.gz ar ar ar/file1 ar/file2
- Example 13 Extracting a directory from a gzip archive
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar xvzf ar.tar.gz ar ar ar/file1 ar/file2
- Example 14 Displaying a gzip archive
-
C:\TEMP>%ADSH_OSCMD_DIR%\tar tvzf ar.tar.gz drwx------ 0/0 0 Dec 09 19:44:24 2015 ar -rw------- 0/0 2758 Dec 09 19:39:35 2015 ar/file1 -rw------- 0/0 5516 Dec 09 19:39:55 2015 ar/file2