NAME
star - unique standard tape archiver
SYNOPSIS
star command [ options ] file1 ... filen
ustar command [ options ] file1 ... filen
tar command [ options ] file1 ... filen
star -copy [ options ] file1 ... 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 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 fetch files from a list of directories (in create mode) or to distribute files to a list of directories (in extract mode).
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 compatibilitx 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.
-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.
-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.
-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.
-ask_remove
obsoleted by -ask-remove
-ask-remove
Ask to remove non writable files on extraction. By default, star will not overwrite files that are read only. If this option is in effect, star will ask whether it should remove these files to allow the extraction of a file in the following way:
remove 'filename' ? Y(es)/N(o) :
-atime, -a
Reset access time of files after storing them to tarfile. On Solaris 2.x, (if invoked by root) star uses the _FIOSATIME ioctl to do this. This enables star not to trash the ctime while resetting the atime of the files. If the -atime option is used in conjunction with the list command, star lists access time instead of modification time. (This works only in conjunction with the star, xstar, xustar, exustar, and with the pax format.) Another option to retain the access time for the the files that are going to be archives is to readonly mount a UFS snapshot and to archive files from the mount point of the UFS snapshot.
-B
Force star to perform multiple reads (if necessary) to fill a block. This option exists so that star can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming. If star uses stdin as archive file, star behaves as if it has been called with the -B option. For this reason, the option -B in practice is rarely needed.
-block-number
Print the archive block number (archive offset / 512) at the beginning of each line when in verbose mode. This allows to write backup scripts that archive the offsets for files and that use
mt fsr blockno
to skip to the tape block number of interest in a fast way
if a single file needs to be restored.
blocks=#, b=#
Set the blocking factor of the tarfile to # times 512 bytes (unless a different multiplication factor has been specified - see bs= option for posible multiplication factors). Changing the blocking factor only makes sense when the archive is located on a real tape device or when the archive is accessed via the remote tape protocol (see f= option below). The default is to use a blocking factor of 20 i.e. 10 kBytes. Increasing the blocksize will speed up the backup. For portability with very old tar implementations (pre BSD 4.2 or pre AT&T SVR4), blocksize should not be more than 10 kBytes. For POSIX.1-1988 compatibility, blocksize should be no more than 10 kBytes. For POSIX.1-2001 compatibility, blocksize should be no more than 32 kBytes. Most systems also have a hardware limitation for the blocksize, 32 kBytes and 63 kBytes are common limits on many systems. The upper limit in any case is the size of the buffer RAM in the tape drive. Make a test if you want to make sure that the target system will handle the intended blocksize. If you use star for data exchange via tape, it is a good idea to use a blocksize of 10 kBytes unless you are sure that the reading system will handle a larger blocksize. If you use star for backup purposes with recent hardware (e.g. DLT tape drives), a blocksize of 256 kBytes results in sufficient speed and seems to be a good choice. Star allows block sizes up to 2 GByte if the system does not impose a smaller limit. If you want to determine the blocking factor when reading an unknown tar archive on tape, specify a blocking factor that is higher than the supposed blocking factor of the tape. Star then will determine the blocking factor by reading the first record of the tape and print a message:
star: Blocksize = # records.
Where # is the blocking factor in multiples of 512 bytes. The blocks= option and the bs= option are equivalent methods to specify the tape block size. The blocks= option is preferred by people who like to use an option that behaves similar to the interface of the historic tar(1) implementations.
bs=#
Set output block size to #. You may use the same method as in dd(1) and sdd(1). The number representing the size is taken in bytes unless otherwise specified. If a number is followed directly by the letter `.', `w', `b', `k', `m', `g', `t', or `p', the size is multiplied by 1, 2, 512, 1024, 1024*1024, 1024*1024*1024, 1024*1024*1024*1024 or 1024*1024*1024*1024*1024. If the size consists of numbers separated by `x' or `*', multiplication of the two numbers is performed. Thus bs=7x8k will specify a blocksize of 56 kBytes. Blocksize must be a multiple of 512 bytes. See also the description of the blocks= option for more details on blocksizes. The option bs= is preferred by people who like to use an option that behaves similar to the interface used by dd(1) and sdd(1).
-bz
run the input or output through a bzip2 p
