Hitachi

JP1 Version 11 JP1/Advanced Shell Description, User's Guide, Reference, and Operator's Guide 

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

Table 8‒19: Root directory of the target path name to be removed with storage and extraction

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:\

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
UNIX

The user ID and user name of the corresponding file are stored.

Windows

0 for the user ID, and the user name of the corresponding file are stored.
UNIX

The group ID and group name of the corresponding file are stored.

Windows

0 is set for the group ID, and no group name is set.

When extracting an archive
UNIX

- Superuser

The user ID is obtained from the extracted user name and this user ID is set to the file. If the user ID cannot be obtained, the extracted user ID is set.

- Non-Administrator user

The execution user ID or execution user name are set.

Windows

Logon user name.
UNIX

- Superuser

The group ID is obtained from the extracted group name, and this group ID is set to the file. If the group ID cannot be obtained, the extracted group ID is set.

- Non-Administrator user

The group ID or group name belonging to the execution user name are set.

Windows

Not applicable

When displaying an archive
UNIX

The user ID is obtained from the extracted user name, and this user ID is displayed. If the user ID cannot be obtained, the extracted user ID appears.

Windows

The extracted user ID appears.
UNIX

The group ID is obtained from the extracted group name, and this group ID is displayed. If the group ID cannot be obtained, the extracted group ID is displayed.

Windows

The extracted group ID appears.

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

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

To Page Top

All Rights Reserved. Copyright (C) 2016, 2017, Hitachi, Ltd.