star (1) Linux Manual Page

NAME

star – unique standard tape archiver

SYNOPSIS

star  command [options] [-find] file1 … filen [find_expr]
ustar command [options] [-find] file1 … filen [find_expr]
tar   command [options]         file1 … filen
star  -copy   [options] [-find] file1 … [f_expr] directory
star  -copy   [options] -C from_directory . to_directory

DESCRIPTION

Star is a very fast tar(1) like tape archiver with improved functionality.

Star archives and extracts multiple files to and from a single file called a tarfile. A tarfile is usually a magnetic tape, but it can be any file. In all cases, appearance of a directory name refers to the files and (recursively) subdirectories of that directory.

Star’s actions are controlled by the mandatory command flags from the list below. The way star acts may be modified by additional options.

Note that unpacking tar archives may be a security risk because star may overwrite existing files. See SECURITY NOTES for more information.

FEATURES

Star includes the first free implementation of POSIX.1-2001 extended tar headers. The POSIX.1-2001 extended tar headers define a new standard way for going beyond the limitations of the historic tar format. They allow (among others) to archive all UNIX time stamps in sub-second resolution, files of arbitrary size and filenames without length limitation using UNICODE UTF-8 coding for best exchange compatibility.

Star by default uses a fifo to optimize data flow from/to tape. This results in a normally streaming tape during the whole backup. See -fifo and fs= option to get information on how to find the best fifo size.

Star includes a pattern matcher to control the list of files to be processed. This gives a convenient interface for archiving and restoring complex lists of files. In conjunction with the -w flag it is easy to merge a tar archive into an existing file tree. See also -U option. In create mode use the pat= option to specify either select or exclude patterns (depending on the -V flag). In extract or list mode all file type arguments are interpreted as select patterns while the patterns specified with the pat= option may be used as select or exclude patterns (depending on the -V flag). Have a look at the description of the -C option to learn how to fetch files from a list of directories (in create mode) or to distribute files to a list of directories (in extract mode). A substitute option allows ed(1) like pattern substitution in file names.

Star includes an enhanced function that is similar to the find(1) command (see sfind(1)). This allows to use find expressions, even in extract or list mode, directly on the content on an archive. The extensions to find(1) allow to modify the file metadata.

Star includes a sophisticated diff command. Several diff options allow user tailorable functionality. Star won’t show you differences you are not interested in. Check the diffopts= option for more details.

Star has no limitation on filename length. Pathnames and linknames up to PATH_MAX (1023 bytes with old OS versions and 4095 bytes with POSIX.1-2001) may be archived. Later versions may be able to deal with longer pathnames.

Star deals with all 3 times, available for files on UNIX systems if the archive format is either chosen from the star specific formats or is a format that uses POSIX.1-2001 extended headers. This is either done in second resolution by using a star specific POSIX.1-1988 compatible extension or in sub second resolution by using POSIX.1-2001 extended headers. Star is able to store and restore all 3 times (mtime, atime and even ctime). On Solaris 2.x systems, star is able to do backups without changing any of the 3 the times.

If used with the H=ustar option, or if called as ustar or tar while the H=headertype option is not used, star is 100% POSIX compliant.

Star’s default format (if called as star) is xstar and is as posix compliant as possible. Enhancements to the standard that prevent correct extraction of single files when using a different tar implementation that is only POSIX.1-1988 compliant may occur, but they only affect single files with a pathname that is longer than 100+130 chars or when archiving sparse files with the -sparse option in effect. All other files will extract correctly. See the description for the H=headertype option below for more information on archive formats and possible archive interchange problems.

Star makes it easy to repair corrupted filesystems. After a fsck -y has been run on the filesystem, star is able to restore only the missing files automatically. Use then star -diff to check for differences (see EXAMPLES for more information).

Star automatically recognizes the type of the archive. Star therefore is able to handle features and properties of different archive types in their native mode, if it knows about the peculiarities of the archive type. See the H=headertype option for more details. To be able to do this, star adds hidden fingerprints to the archive header that allows to recognise all star specific archive formats. The GNU tar format is recognised by the way it deviates from the standard.

Star automatically recognizes and handles byte swapped archives. There is no option to manually control byte swapping.

Star automatically recognizes and handles compressed archives inside plain files.

Star is able to archive and restore Access Control Lists for files using POSIX.1-2001 extended headers.

COMMAND

In native mode, star is compatible to the command line syntax of a typical POSIX command and for this reason expects commands and options to start with a single dash (-). In this case, commands and options may be specified separately, all boolean or increment type options may be specified either separately or combined. For compatibility with GNU programs, long options may alternatively start with a double dash. In compatibility mode to POSIX tar, star expects commands and options to appear as one single string that does not start with a dash. In POSIX tar compatibility mode, additional non POSIX options may be specified but must appear after the POSIX options and their args and need to start with a dash.

-c

Create a new tarfile and write named files into it. Writing starts at the beginning of tarfile. See -v option for information on how to increase verbosity while the archive is written.

-copy

Copy named files to the target directory which is the last file type argument. The target directory must exist. The shorthand -cx instead of -copy is not allowed because this could be a result of a typo.

If the option -diff has been specified in addition, star performs a one pass directory tree compare instead of copying files. The shorthand -c -diff instead of -copy -diff is also allowed.

On operating systems with slow file I/O (such as Linux), it may help to use -no-fsync in addition, but then star is unable to detect all error conditions; so use with care.

If the option -t has been specified in addition, the last file type argument is not a target directory and star is performing a one pass listing instead of copying files. This makes sense as the listing from star may be better readable than the output from ls -lR. The shorthand -c -t or -ct instead of -copy -t is also allowed.

The job is by default done in the best archive mode. This implies that it defaults to H=exustar -dump. When in -copy mode, star forks into two processes and data exchange is done via the shared memory from the FIFO. This gives the best possible performance. Without FIFO, the -copy mode will not work.

The list= option, patterns and substitutions apply only to the create side of the copy command.

-diff

Compare the content and the attributes of the files from the archive in tarfile to the filesystem. This may also be used to compare two file trees in the filesystem. If you use a set of diffopts that fits your needs, it will give – in many cases – a more readable output than diff -r. If you use star’s dump extensions for the tar archive, the -diff option allows to find even if the directory in the file tree contains more files than the archive. This way, it is possible to compare all properties of two file trees in one run. See diffopts for more details. Adding one or more -v options increases the verbosity. With -vv and above, the directory content is compared also if star is reading a tar archive that has been created in -dump mode.

-n

No extraction. Show what star would do, in case the -x command had been specified.

-r

Replace files in a tarfile. The named files are written to the end of tarfile. This implies that later, the appropriate files will be found more than once on the tarfile.

-t

Table of contents. List the contents of the tarfile. If the -v flag is used, the listing is similar to the format of ls -l output. With this option, the flags -a, -atime and -ctime have a different meaning if the archive is in star, xstar, xustar, exustar, or pax format. The option -a or -atime lists the access time instead of the modification time, the option -ctime lists the file creation time instead of the modification time. The option -tpath may be used in addition to modify the output so it may be used in shell scripts.

-u

Update a tarfile. The named files are written to the end of tarfile if they are not already there or if the files are newer than the files of the same name found in the archive. The -r and -u command only work if the tar archives is a regular file or if the tar archive is an unblocked tape that may backspace.

-x

Extract the named files from the tarfile. If no filename argument or pattern is specified, the entire content of the tarfile is restored. If the -U flag is not used, star extracts no file which is older than the corresponding file on disk.

On operating systems with slow file I/O (such as Linux), it may help to use -no-fsync in addition, but then star is unable to detect all error conditions; so use with care.

Except for the shorthands documented above, exactly one of the commands above must be specified.

If one or more patterns or substitution commands have been specified, they apply to any of the command listed above. In copy mode, all patterns and substitute commands apply to the create side.

OPTIONS

-help

Print a summary of the most important options for star(1).

-xhelp

Print a summary of the less important options for star(1).

-/

Don’t strip leading slashes from file names when extracting an archive. Tar archives containing absolute pathnames are usually a bad idea. With other tar implementations, they may possibly never be extracted without clobbering existing files. Star for that reason, by default strips leading slashes from filenames when in extract mode. As it may be impossible to create an archive where leading slashes have been stripped while retaining correct path names, star does not strip leading slashes in create mode.

See SECURITY NOTES for more information.

-..

Don’t skip files that contain /../ in the name. Tar archives containing names with /../ could be used to compromise the system. If they are unpacked together with a lot of other files, this would in most cases not even be noticed. For this reason, star by default does not extract files that contain /../ in the name if star is not in interactive mode (see -w option).

See SECURITY NOTES for more information.

-7z

run the input or output through a p7zip pipe – see option -z below.

Note that the p7zip program currently does not operate on a pipe but on a /tmp file copy and thus limits the maximum archive size.

-0

-1

-2

-3

-4

-5

-6

-7

Select an archive entry from /etc/default/star. The format for the archive entries is the same as the format in /etc/default/tar in Solaris.

-acl

Handle Access Control List (ACL) information in create and extract mode. If -acl has been specified, star is in create mode and the header type is exustar, star will add ACL information to the archive using POSIX.1-2001 extended headers. If -acl has been specified and star is in extract mode, star will try to restore ACL information. If there is no ACL information for one or all files in the archive, star will clear the ACL information for the specific file. Note that if -acl has not been specified, star will not handle ACL information at all and files may inherit ACL information from the parent directories. If the -acl option has been specified, star assumes that the -p option has been specified too.

artype=headertype

Generate a tape archive in headertype format. If this option is used in extract/list mode this forces star to interpret the headers to be of type headertype. As star even in case of a user selected extract archive format does format checking, it may be that you will not be able to unpack a specific archive with all possible forced archive formats. Selecting the old tar format for extraction will always work though. Valid parameter for headertype are:

help

Print a help message about possible header types.

v7tar

Old UNIX V7 tar format. This archive format may only store plain files. Pathnames or linknames longer than 99 chars may not be archived.

If the v7tar format has been selected, star will not use enhancements to the historic UNIX V7 tar format. File size is limited to 2 GB – 2 bytes, uid/gid is limited to 262143. Sparse files will be filled up with zeroes.

tar

Old BSD UNIX tar format. This archive format may only store plain files, directories and symbolic links. Pathnames or linknames longer than 99 chars may not be archived. See also the -d option as a note to some even older tar implementations.

If the tar format has been selected, star will not use enhancements to the historic tar format. File size is limited to 2 GB – 2 bytes, uid/gid is limited to 262143. Sparse files will be filled up with zeroes.

star

Old star standard format. This is an upward/downward compatible enhancement of the old (pre Posix) UNIX tar format. It has been introduced in 1985 and therefore is not Posix compliant. The star format allows to archive special files (even sockets) and records access time and creation time besides the modification time. Newer versions of the old star format allow very long filenames (100+155 chars and above), linknames > 100 chars and sparse files (if -sparse is used). This format is able to copy the device nodes on HP-UX that have 24 bits in the minor device number, which is more then the 21 bits that are possible with the POSIX-1003.1-1988 archive format.

The nonstandard extensions are located in the space between the link name and the POSIX file name prefix. As the star format does not use a POSIX magic string, the extensions do not interfere with the POSIX tar formats. The last 4 bytes of the tar header contain a ‘tar