HTAR Man Page

htar Command




Manipulates HPSS-resident tar-format archives.


htar -{c|t|x|K|X} [-?] -f Archive [-B] [--option ...] [-d debuglevel] [-E] 

[-H opt[:opt...]] [-h] [-I {IndexFile | .suffix}] [-L inputlist] [-M maxfiles] [-m]
days] [-O] [-o] [-P] [-p] [-q] [-S Bufsize] [-T Max Threads]
[-V] [-v] [-w] [-Y [
Archive COS ID][:Index File COS ID]]
Filespec | Directory ...]


The HTAR program manipulates HPSS-resident archives, or archives that reside on a remote system (subject to the restrictions noted below), by writing files to, or retrieving files from, either HPSS or a remote FTP server.

Files written to HPSS are in the POSIX 1003.1 "tar" format, and may be retrieved from HPSS (or the remote system), and read by native "tar" programs.

The local files used by the htar command are represented by the Filespec parameter. If the Filespec parameter refers to a directory, then that directory, and, recursively, all files and directories within it, are referenced as well.

Unlike the standard Unix "tar" command, there is no default archive device; the "-f Archive" flag is required.


HTAR has been optimized for creation of archive files directly in HPSS, without having to go through the intermediate step of first creating the archive file on local disk storage, and then copying the archive file to HPSS via some other process such as ftp or hsi. The program uses multiple threads and a sophisticated buffering scheme in order to package member files into in-memory buffers, while making use of the high-speed network striping capabilities of HPSS.

In most cases, it will be significantly faster to use HTAR to create a tar file in HPSS than to either create a local tar file and then copy it to HPSS, or to use tar piped into FTP or HSI, to create the tar file directly in HPSS.

In addition, HTAR creates a separate index file, which contains the names and locations of all of the member files in the archive (tar) file. Individual files and directories in the archive can be randomly retrieved without having to read through the archive file. Because the index file is usually smaller than the archive file, it is possible that the index file may reside in HPSS disk cache even though the archive file has been moved offline to tape. Since HTAR uses the index file for listing operations, it may be possible to list the contents of the archive file without having to incur the time delays of reading the archive file back onto disk cache from tape.

It is also possible to create an index file for a tar file that was not originally created by HTAR or to recreate an index that has been unintentionally deleted.

"Archive" and "Member" files

Throughout the HTAR documentation, the term "archive file" is used to refer to the tar-format file, which is named by the "-f filename" command line option. The term "member file" is used to refer to individual files contained within the archive file.

Member File Size Constraints

Individual member files are limited in size to 68719476735 bytes. This is because the POSIX tar specification allocates 12 octal digits for the file size (7777777777 = 68719476735 (base 10)).

HTAR Index File

As part of the process of creating an archive file on HPSS, HTAR also creates an index file, which is a directory of the files contained in the archive. The Index File includes the position of member files within the archive, so that files and/or directories can be randomly retrieved from the archive without having to read through it sequentially. The index file is usually significantly smaller in size than the archive file, and may often reside in HPSS disk cache even though the archive file resides on tape. All HTAR operations make use of an index file.

It is also possible to create an index file for an archive file that was not created by HTAR, by using the "Build Index" [-X] function (see below).

By default, the index filename is created by adding ".idx" as a suffix to the Archive name specified by the -f parameter. A different suffix or index filename may be specified by the "-I " option, as described below.

By default, the Index File is assumed to reside in the same directory as the Archive File. This can be changed by specifying a relative or absolute pathname via the -I option. The Index file’s relative pathname is relative to the Archive File directory unless an absolute pathname is specified.

Use of Absolute Pathnames

Although HTAR does not restrict the use of absolute pathnames (pathnames that begin with a leading "/") for member files when the archive is created, it will remove the leading / when files are extracted from the archive. All extracted files use pathnames that are relative to the current working directory.

However, when using the "verify" action (-K), absolute pathnames are used unless the -Hrelpaths ("relative paths") option is specifed (see below).

HTAR Consistency File

HTAR writes an extra file as the last member file of each Archive, with a name similar to:


This file is used to verify the consistency of the Archive File and the Index File. Unless the file is explicitly specified, HTAR does not extract this file from the Archive when the -x action is selected. The file currently is listed, however, when the -t action is selected.

The "-Hnocfchk" (see below) command line option can be used to specify that actions that normally verify the consistency file vs. the index file (for example, the Delete (-D) action) should not do so.

Tar File Restrictions

When specifying path names that are greater than 100 characters for a file (POSIX 1003.1 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. Since some implementations of TAR require the prefix and name buffers to terminate with a null (’ ’) character, HTAR enforces the restriction that the effective prefix buffer length is 154 characters (+ trailing zero byte), and the name buffer length is 99 bytes (+ trailing zero byte). 

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 (99 characters + zero-byte terminator).

HPSS Default Directories

The default directory for the Archive file is the HPSS home directory for the HPSS user. An absolute or relative HPSS path can optionally be specified for either the Archive file or the Index file. By default, the Index file is created in the same HPSS directory as the Archive file.

For the "Create" action, if the Archive file pathname contains subdirectories that do not already exist, the command will fail unless the "-P" option is used. This option is analogous to the "-p" option for the Un*x "mkdir" command.

Local Temporary Directory

HTAR makes use of the TMPDIR environment variable when creating temporary files. If TMPDIR is not set in the environment, then "/tmp" is used.

HTAR Command Line Options

Two groups of flags exist for the HTAR command; "action" flags and "optional" flags. Action flags specify the operation to be performed by the HTAR command, and are specified by one of the following:

-c, -t, -x, -X, -K, -D, -U

At least one action flag must be selected in order for the HTAR command to perform any useful function (note: in the initial implementation, one and only one action can be specified per execution).


A file specification has one of the following forms:


"WildcardPath" is a path specification that includes standard filename pattern-matching characters, as specified for the shell that is being used to invoke HTAR. The pattern-matching characters are expanded by the shell and passed to HTAR as command line arguments. 

Note that using wildcard characters for the -t and -x actions may not work as expected unless there are existing local files that match the pattern. For example,

htar -xf someFile.tar a*

will only extract files beginning with "a" in "someFile.tar" that also already exist in the current local working directory.

Action Flags

Action flags defined for HTAR are as follows:

-c   Creates a new HPSS-resident archive, and writes the local files specified by one or more File parameters into the archive. Warning: any preexisting archive file will be overwritten without prompting. This behavior mimics that of the AIX tar utility.

-t   Lists the member files in the order in which they appear in the HPSS- resident archive  Listable output is written to standard output; all other output is written to standard error.

-x   Extracts the member files specified by one or more File parameters from the archive. If the File parameter refers to a directory, the HTAR command recursively extracts that directory and all of its subdirectories from the archive.

If the File parameter is not specified, HTAR extracts all of the files from the archive. If 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, it is created. If you have the proper permissions, then the HTAR command restores all files and directories with the same owner and group IDs as they have on the HPSS tar file. If you do not have the proper permissions, then files and directories are restored with your owner and group IDs.

-K   Verifies the contents of the archive, based upon the verification level options given by the -Hverify and -Hrelpaths options.

-X   Builds a new index file by reading the entire tar file. This operation is used either to reconstruct an index for tar files whose Index File is unavailable (e.g., accidentally deleted), or for tar files that were not originally created by HTAR.

-D   Soft-deletes files by marking them as "deleted" in the index file. The index file is rewritten as a result of this action. Files that are soft-deleted are not extracted (-x action), and are marked in listings (-t action) with a "D" immediately following the permission string.

-U   Undeletes files that were previously marked as "deleted" in the index file. The index file is rewritten as a result of this action.


Note: starting with HTAR version 6.0.0, many command line options can now 
be specified in long form, preceded by as double-dash, such as ’--crc’ instead of ’-Hcrc’. 
This includes the ’exclude’ family of options, and options specified via ’-H’ (see below). 
The previous -H syntax continues to be supported, but may be removed in a future release.

For example, -Hcrc can also be specified as --crc 
If an empty option ’--’ is encountered, htar treats it as the end of all 
command line options; any parameters following the ’--’ are treated as filenames

-?   Displays HTAR’s verbose help

-B   Displays block numbers as part of the listing (-t option). This is normally used only for debugging.

-d debuglevel    Sets debug level (0 - N) for HTAR. 0 disables debug, 1 - n enable progressively higher levels of debug output. 5 is the highest level; anything > 5 is silently mapped to 5.

--exclude options

         Note: The exclude family of options only applies to creation of new archive files. 
         These options are applied during the initial directory scan, and all files and directories that 
         are excluded from the archive are listed, in order to provide an audit trail for the user.

         The specification (but not the code) for these options was based on the "exclude" feature of the 

          popular GNUTAR program.  However, there is no guarantee that the HTAR exclude feature will 

         operate exactly the same as the GNUTAR exclude feature.

        --exclude=pattern This causes htar to recursively avoid including files or directories whose name      

matches the shell wildcard. pattern

         Multiple --exclude options may be given.

        --exclude-from=file This causes htar to read a list of shell patterns from file to be recursively excluded. 
         Note: a frequent error that can be hard to find is whitespace characters after a name read from the file. However, empty lines are ok. 
         Multiple --exclude-from options may be given.

         exclude-vcs-ignores Before htar archives a new directory found during the prescan, it looks to see if the directory contains any of the following files:

         cvsignore, .gitignore (R), .bzrignore (R), .hgignore(R)

         If so, it reads patterns from the file and ignores objects that match any of the patterns. 
         It treats the files in the same way that the version control system would treat them, some recursively starting at the new directory (marked with R) and some that apply just to the new directory. Patterns in .bzrignore and .hgignore files can be either shell globbing patterns or regular expressions. .bzrignore and .hgignore files can also contain comments whose first character is ’#’.

         exclude-ignore=file Before scanning a new directory, htar checks if it contains file. If so, it reads exclusions patterns, which apply only to new directory, from file.

         exclude-ignore-recursive=file This is the same as exclude-ignore, except that patterns apply recursively to the new directory and to all of its subdirectories.

         exclude-vcs Excludes files and directories used by the following version control systems: 
             CVS, RCS, SCCS, Arch, Bazaar, Mercurial and Darcs. 

              This includes all of the following files and directories:

             • ‘CVS/’, and everything under it

             • ‘RCS/’, and everything under it

             • ‘SCCS/’, and everything under it

             • ‘.git/’, and everything under it

             • ‘.gitignore’

             • ‘.cvsignore’

             • ‘.svn/’, and everything under it

             • ‘.arch-ids/’, and everything under it

             • ‘{arch}/’, and everything under it

             • ‘=RELEASE-ID’

             • ‘=meta-update’

             • ‘=update’

             • ‘.bzr’

             • ‘.bzrignore’

             • ‘.bzrtags’

             • ‘.hg’

             • ‘.hgignore’

             • ‘.hgrags’

             • ‘_darcs’

        --exclude-backups This option causes htar to exclude backup and lock files that match the following shell globbing patterns (with the quotes removed):

".#*" "*~" "#*#"

        --exclude-caches options This option causes htar to exclude directories that contain a standard CACHEDIR.TAG file, in the form specified by


              There are 3 variations of the exclude-caches option, each with slightly different semantics:

                     • --exclude-caches- do not archive the contents of the directory, but archive the directory itself and the .CACHEDIR.TAG file

                     • --exclude-caches-under - do not archive the contents of the directory, nor the CACHEDIR.TAG file, archive just the directory itself

                     • --exclude-caches-all - entirely omit directories containing the CACHEDIR.TAG file

        --exclude-tag options This is a generalization of the ’exclude-caches’ option which allows specifying the filename to look for (instead of CACHEDIR.TAG).

                     • --exclude-tag=file- do not archive the contents of the directory, but archive the directory itself and file

                     • --exclude-tag-under=file-do not archive the contents of the directory, nor file, archive just the directory itself

                      --exclude-tag-all=file - entirely omit directories containing file

-E  If present, specifies that a local file should be used for the file specified by the "-f Archive" option. If not specified, then the archive file will reside in HPSS.

-f Archive   Uses "Archive" as the name of archive to be read or written. 

Note: This is a required parameter for HTAR, unlike the standard tar utility, which uses a built-in default name.

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 -I option is mandatory, in order to specify an Index File, which is copied to HPSS if the Archive file is successfully written to standard output.

 [Note: this behavior is deferred - reading from or writing to pipes is not supported in the current version of HTAR].

-G hsm|backup If present, specifies that this is a GPFS/HPSS interface operation. This option is intended for use only by system administrators, and is only recognized if HTAR was built with "GHI Support" enabled.

-H opt[:opt...]   Specifies HTAR-specific options. Multiple "-H" parameters may be specified, and multiple colon-separated options may be specified for each -H. Options may be either standalone keywords, or may be of the form "opt=value". The option string must not contain whitespace characters.

Opt may be any of the following:

    acct=id | name - sets the HPSS account ID or account name to use for the current run. This will result in setting the specified account ID/name for index files and archive files created by actions that write files in HPSS.

    cif - For extract (-x), specifying this option when extracting file from an HPSS-resident archive will cause HTAR to first copy the index file to a temporary local file. This option is normally unnecessary, but can be useful in situations that have been encountered when multithreading errors have occurred on some operating systems when trying to read both the archive and index files concurrently from HPSS. 

    This option has no effect for local file or ftp-resident archives.

    copies=n - sets number of copies to specify when using auto-COS selection during a <create> operation for an HPSS-resident archive.

    For example,

    would restrict selection to Classes of Service that have been configured by the HPSS administrator to create two tape copies when data is migrated. This option has no effect for operations other than create (-c), and also only effective if auto-COS selection is enabled via the -Y command line option, the "HTAR_COS" environment setting, or by the HPSS administrator when HTAR is installed.

    crc - specifies that HTAR should generate CRC checksums when creating the archive. For "extract" operations, (-x), specifying this option will cause checksums to be regenerated and verified for files that were added to the archive with checksums enabled. For "build index" (-X) operations, this option will cause the archive to be read, and a checksum to be added to the index. For list (-t) operations, this option will cause the checksum to be listed following the object permissions

    exfile=path Specifies pathname of file to contain "exception" messages. Messages are appended to the file if it already exists. If this option is not specified, the "exceptions" file will not be written.

    family=fid[,index_fid] Specifies the HPSS file family ID to use for archive and option for the index file. The default for both options is 0, which will cause the global file family to be used. This option is only useful for sites which have implemented file familes; check with your site administrator to determine the file family IDs that are available at each site.

    ghi_fsid=FSID,SID,SNAPID Specifies parameters needed for the GPFS/HPSS Interface (GHI). This option is intended for use only by system administrators.

    okfile=path Specifies pathname of file to contain a list of successfully transferred files. Messages are appended to the file if it already exists. If this option is not specified, the "success" file will not be written.

    nocfchk specifies that the Consistency File should not be checked vs the index file for operations that normally do so. Currently, this includes the "Delete" (-D) and "Undelete" (-U) actions.The "Build Index" (-X) action always checks for the presence of a Consistency File in order to determine whether the original file was or was not created by HTAR. This flag has no effect on Archive files that were not created by HTAR.

 - specifies that HTAR should should not generate CRC checksums when writing to the archive (-c or -X) or regenerate and compare CRCs (-x).

    nostage - specifies that HTAR should try to read the archive file directly from tape for read operations such as extract( -x), rather than having HPSS potentially stage the entire file onto disk cache when it is opened.  This option can be useful when only a small number of files are being extracted from a large archive. However, misuse of this option can cause HPSS tape drive resource contention, and should normally be used only after coordinating with the site’s HPSS administrators.

    port=port_number - specifies the port that HTAR should use when connecting to the HPSS server. This option has meaning only if the -Hserver option is specified (see below).

    rmlocal - specifies that HTAR should attempt to remove local files on a creation run (-c) after the archive is created and any post-transfer verification has completed without errors. Only local files that were successfully copied to the archive will be removed. Local directories are not affected by this option, only files and symbolic links.

    server=server_host - specifies the HPSS server that HTAR should connect to when it starts up. This is normally unnecessary, but can be specified if it is necessary to override the builtin setting. The "-Hport" option can also be specified to override the default port to which HTAR connects. "server_host" can be either an IP address, or a hostname.

    tss=stack_size - specifies the thread stack size to use for local file worker threads. The "stack_size" parameter may optionally contain a case-insensitive "k","kb" (kilobytes) or "m" or "mb" (megabytes) suffix, for example, -Htss=750KB. The default value if this option is not specified is 512KB. This option is currently only used for "create" (-c) operations.

    umask=octal_value - specifies the octal umask value to be used when the archive file or the index file is created. This value is silently truncated to 3 octal digits. For example, to restrict access to the file’s owner, "-Humask=077" would be specified.

    verify=option[,option...] - specifies one or more verification options that should be performed following successful creation of the archive (-c), or for the "verify" (-K) command. Multiple options can be specified by separating them with a comma, with no whitespace. 

    Options are processed from left to right, and, in the case of conflicting options, the last one encountered is used without comment.

    Options are as follows:

    info - compares tar header info with the corresponding values in the index

- enables CRC checking of archive files for which a CRC was generated when the file was added to the archive

    compare/nocompare - enables/disables a byte-by-byte comparison of archive member files and their local file counterparts. If -Hrelpaths is not specified, then absolute paths for member files in the archive will also be treated as absolute local paths.

    0 - enables "info" verification
    1 - enables level 0 + "crc" verification
    2 - enables level 1 + "compare" verification
    all - enables all comparison options (currently, tar hdr checking, CRC checking, and local file comparisons).

    relpaths - specifies that HTAR should use relative paths instead of absolute paths when comparing the archive and local member files. This option was intended to provide a way to compare files with absolute paths on an archive with member file(s) that were created with relative paths by a previous "extract" (-x) action.

-h    Directs HTAR to follow symbolic links as if they were normal files or directories. Normally, HTAR does not follow symbolic links.

-I index_name    Specifies the index file name or suffix. If the first character of the index_name is a period, then index_name is appended to the Archive name, e.g. "-f the_htar -I .xndx" would create an index file called "the_htar.xndx".

If the first character is not a period, then index_name is treated as a relative pathname for the index file (relative to the Archive file directory) if the pathname does not start with "/", or an absolute pathname otherwise.

The default directory for the Index file is the same as for the Archive file. If a relative Index file pathname is specifed, then it is appended to the directory path for the Archive file. For example, if the Archive file resides in HPSS in the directory "projects/prj/" and is called files.tar, then an Index file specification of "-I projects/prj/files.old.idx" would fail, because HTAR would look for the file in the directory "projects/prj/projects/prj". The correct specification in this case is "-I files.old.idx".

-L InputList    Writes the files and directories listed in the "InputList" file to the archive. Directories named in the InputList file are treated recursively. Note that "home directory" notation ("~") is currently not expanded for pathnames contained in the InputList file, nor are wildcard characters, such as "*" and "?". (This is a feature that is planned for a future release)

-M maxfiles    Sets the maximum number of member files that can be contained in the archive when it is initially created. The default maximum number of member files, and an absolute maximum number of files, are defined when HTAR is built.

No limit will be enforced if:


  •   The default maximum number of files was set to a negative value when HTAR was built, and the -M option is NOT specified, 


  A value less than 0 is specified for the -M option, and the absolute maximum number of files was also set to a negative value when HTAR was built.

If the value specified for the -M option exceeds the absolute maximum value that was defined when HTAR was built, HTAR will issue a warning message, and use the absolute maximum value.

-m    Uses the time of extraction as the modification time. The default is to preserve the modification time of the files. Note that the modification time of directories is not guaranteed to be preserved, since the operating system may change the timestamp as the directory contents are changed by extracting other files and/or directories. HTAR will explicitly set the timestamp on directories that it extracts from the Archive, but not on intermediate directories that are created during the process of extracting files.

-n time    Meaningful only for "create" (-c) action. If specified, only files that have been created or modified within the specified time will be included in the archive. This option is intended to simplify the creation of incremental backups. "time" is specified in one of the following forms:


hours days:hours

-O (capital letter "oh") If specified, files that are extracted using the -x option will be written to standard output. This is normally only useful when extracting a single file, as there is nothing in the output stream to mark the end of file.

-o    Provides backwards compatibility with older versions (non-AIX) of the tar command. When this flag is used for extracting (-x), 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. If HTAR is being run as root, use of this option causes files to be owned by root rather than the original user.

-p    Causes files to be restored to their original modes, ignoring the present umask. The setuid, setgid, and "sticky bit" permissions are also restored to the user with root user authority.

-P    This option is only meaningful for the "create" (-c) action. It causes intermediate subdirectories for the Archive file pathname to be created if they do not already exist.

-q    "quiet mode" flag. If this option is specified, HTAR will not display extraneous messages, such as interactive progress messages as it scans directories during a "create" operation.

-S bufsize    Specifies the buffer size to use when reading or writing the HPSS tar file. The buffer size can be specified as a value, or as kilobytes by appending any of the "k","K","kb", or "KB" suffixes (with no intervening whitespace) to the value. It can also be specified as megabytes by appending any of "m" or "M" or "mb" or "MB" suffixes to the value, for example, "23mb".

-T Max Threads    Specifies the maximum number of threads to use when copying local member files to the Archive file. The default is defined when HTAR is built; the release value is 15. The maximum number of threads actually used is dependent upon the local file sizes, and the size of the I/O buffers. A good approximation is usually:

    buffer size/average file size

If the -v or -V option is specified, then the maximum number of local file threads used while writing the Archive file to HPSS is displayed when the transfer is complete.

-V    "Slightly verbose" mode. If selected, file transfer progress will be displayed in interactive mode. This option should normally not be selected if verbose (-v) mode is enabled, as the outputs for the two different options are generated by separate threads, and may be intermixed on the output.

-v    "Verbose" mode. For each file processed, displays a one-character operation flag, and lists the name of each file. The flag values displayed are:

    a - file was added to the archive
 - file was extracted from the archive
- index file entry was created (Build Index operation)

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

-Y auto | [ArchiveCosID][:IndexCosID]  Specifies the HPSS Class of Service ID to use when creating a new Archive and/or Index file. If the keyword "auto" is specified, then the HPSS "hints" mechanism is used to select the archive COS, based upon file size.

If "-Y cosID" is specified, then "cosID" is the numeric COS ID to be used for the Archive File.

If "-Y :IndexCosID" is specified, then "IndexCosID" is the numeric COS ID to be used for the Index File. The default COS ID (or "auto") is a site-specific option that is defined when HTAR is built. If both COS IDs are specified, the entire parameter must be specified as a single string with no embedded spaces, e.g. "-Y 40:30"

Note: For HTAR release 3.5, either  ArchiveCosID or IndexCosID may be specified as auto to facilitate specifying auto for the archive file, and a numeric COS ID for the index file, or vice-versa.

This option may also be specified by the "HTAR_COS" environment variable, for example (if using sh, bash, or ksh):

HTAR_COS=40:30 export HTAR_COS

The environment variable is overridden by the -Y command line option, if both are used.

HTAR Memory Restrictions

When writing to an HPSS archive, the HTAR uses a temporary file (normally in /tmp) and maintains in memory a table of files; you receive an error message if HTAR cannot create the temporary file, or if there is not enough memory available to hold the internal tables.

Using HTAR with Firewalls

For HPSS transfers, the HPSS movers connect to the HTAR program to perform data transfers. If the HTAR client host lives behind a firewall, the only way for data transfers to work is for the system administrator to open a range of ports to allow for inbound connections from the HPSS movers.

One of two environment variables must be set in order to tell HTAR the port range that it should use when creating sockets to which the movers will connect. These environment variables are:




Use of RPC_RESTRICTED_PORTS is generally discouraged because it may interfere with the Distributed Computing Environment (DCE), which also uses this environment variable.

The format of the environment variable setting is:


For example, to set the restricted port range (using the Korn shell) to ports in the range 20300 - 20500, the following command could be used:

export HPSS_PFTPC_PORT_RANGE=ncacn_ip_tcp[20300-20500]

Note: If a firewall is in effect, and no port range has been set by the client host administrator, or the port range environment variable is not set, or it is set incorrectly, then HTAR transfers to or from HPSS will fail with -50 (ECONN) errors.


HTAR uses one of several different authentication mechanisms, as defined by the HPSS administrator, in order to grant access to HPSS. At sites that support Kerberos authentication, you may possibly obtain the necessary credentials automatically when you login to the system. At sites which use Kerberos authentication, if Kerberos credentials are not available when HTAR is started, it will run the kinit program to obtain them, and these credentials may be used for subsequent HTAR invocations, until such time as the credentials expire.

Use of a NETRC File

HTAR supports the use of an FTP-style NETRC file for authentication methods that require a user name and password. Within this file, the "login" and "password" entries are used; other entries such as "macdef" and "account" are currently ignored.

See the HSI web site at for a description of the netrc file

HTAR Installation Path

The normal installation location for HTAR is:


This path is set by the HPSS administrator when HTAR is installed, and may vary from site to site.

HTAR Execution Environment

At many sites, HTAR is actually a wrapper script, which sets the proper environment variables and then execs the HTAR executable.

HTAR makes use of the following HPSS environment variables, if they are available:

HTAR_COS - set to the default COS ID for the archive file, or the string "auto" to force automatic COS selection based upon file size hints. This environment variable is overridden by the -Y command line option.

HPSS_SERVER_HOST - contains the server hostname and optional  port number of the HTAR server.

HPSS_HOSTNAME - contains the hostname or IP address of the  network interface to which HPSS mover(s) should connect  when transferring data. This is overridden by the file  specified in the PFTP_CONFIG_FILENAME environment variable.

The default interface is the one specified by the "hostname"  command. Note that this is often a slow interface, such as the control ethernet on an IBM SP2.

HPSS_CFG_FILE_PATH - pathname of a local directory containing  the HPSS network options file (HPSS.conf).

HTAR also references the following non-HPSS environment variables:

TMPDIR - used when creating temporary files

HOME - used when searching for the network options file (normally only used by HPSS system administrators).


1. The maximum size of a single Member file within the Archive is approximately 64 GB, due to restrictions in the format of the tar header. HTAR does not impose any restriction on the size of the Archive File when it is written to HPSS; however, space quotas or other system restrictions may limit the size of the Archive File when it is written to a local file (-E option).

2. HTAR will optionally write to a local file(-E option); however, it will not write to any file type except "regular files". In particular, it is not suitable for writing to magnetic tape. To write to a magnetic tape device, use the "tar" or "cpio" utility.

Exit Status

This command returns the following exit values:

    0   Successful completion.

    >0 An error occurred.


1. To write the file1 and file2 files to a new archive called "files.tar" in the current HPSS home directory, enter:

htar -cf files.tar file1 file2

2. To extract all files from the project1/src directory in the Archive file called proj1.tar, and use the time of extraction as the modification time, enter:

htar -xm -f proj1.tar project1/src

3. To display the names of the files in the out.tar archive file within the HPSS home directory, enter:

htar -vtf out.tar


/usr/local/bin/htar Specifies the name of the htar executable or wrapper script.

/usr/local/bin/htar.exe Contains the htar executable if a wrapper script is used

/tmp/tar* Specifies a temporary file.

$HPSS_CFG_FILE_PATH/HPSS.conf Contains networking options used by HTAR

Related Information

For file archivers: the cat command, dd command, tar, pax commands. For HPSS file transfer programs: hsi,pftp

Bugs and Limitations:

- There is no way to specify relative Index file pathnames that are
not rooted in the Archive file directory without specifying an
absolute path.

- HTAR does not provide the ability to append, update or remove files.

- HTAR does not support wildcard expansion of pathnames

Web site