SYNOPSIS
star command [ options ] file1 ... filen
ustar command [ options ] file1 ... filen
tar command [ options ] file1 ... filen
DESCRIPTION
Star is a very fast tar(1) like tape archiver with improved functional-
ity.
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.
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 resolu-
tion, 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 pro-
cessed. 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 pat-
terns (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.
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 ar-
chive 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 typ-
ical 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 informa-
tion on how to increase verbosity while the archive is written.
-diff Compare the content and the attributes of the files from the ar-
chive in tarfile to the filesystem. This may also be used to
compare two file trees in the filesystem and gives with a good
choice of diffopts - in some cases - a more readable output than
diff -r. See diffopts for more details.
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 argu-
ment 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.
Exactly one of the commands above must be specified.
If one or more pattern are specified, they apply to any of the command
listed above.
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 ar-
chive where leading slashes have been stripped while retaining
correct path names, star does not strip leading slashes in cre-
ate mode.
-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 informa-
tion 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,
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 Eth-
ernet, 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), block-
size should not be more than 10 kBytes. For POSIX.1-1988 com-
patibility, 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 read-
ing system will handle a larger blocksize. If you use star for
backup purposes with recent hardware, 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:
1024*1024*1024, 1024*1024*1024*1024 or 1024*1024*1024*1024*1024.
If the size consists of numbers separated by `x' or `*', multi-
plication 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 pipe - see option -z
below. As both the -bz and the -z option are non standard, it
makes sense to omit the -bz and the -z inside shell scripts if
you are going to extract a compressed archive that is located
inside a plain file as star will auto detect compression and
choose the right decompression option to extract.
C=dir Perform a chdir(2) operation to dir before storing or extracting
the next files. In all cases, star will perform the chdir(2)
operation relative to the current working directory of the
shell.
o In list mode (with the -t flag), star ignores all -C
options.
o In create mode (with the -c, -r and -u flag), star walks
through all -C options and file type arguments. While a
BSD derived tar(1) implementation goes back to the cur-
rent working directory after storing one file argument
that immediately follows the -C option, star changes the
directory only if a new -C option follows. To emulate
the behavior of a BSD derived tar(1), add a -C . option
after the file argument.
o In extract mode (with the -x, -n and -diff flag), star
builds a pattern list together with corresponding direc-
tories and performs a chdir(2) to the corresponding
directory of a matching pattern. All pat= options in
this case are interpreted as if they were preceded by a
-C . option. See EXAMPLES for more information.
-copylinks
This option allows to copy hard/symlinks targets rather than
creating a link. It helps to extract tar files on systems that
do not implement links (e.g. OS/2). To extract and copy all
symlinks correctly, you may need to call star twice as star can-
not copy files that appear in the archive later than a symlink
pointing to them.
-ctime If used with the list command, this lists ctime rather than
mtime if the archive format is star, xstar, xustar, exustar, or
pax. If used with the extract command and the same archive for-
mats, this tries to restore even the ctime of a file by generat-
published with the seventh edition of UNIX are not able to deal
with directories in tar archives. If a tar archive is generated
without directories this avoids problems with tar implementa-
tions found on SYSVr3 and earlier.
-debug Print debug messages. Among other things, this gives debug mes-
sages for header type recognition, tar type properties, EOF
recognition, opening of remote archives and fifo internals.
diffopts=optlst
Comma separated list of diffopts. Valid members in optlst are:
help Print a summary of possible members of the diffopts
list.
!
not Invert the meaning of all members in the diffopts list
i.e. exclude all present options from an initially
complete set compare list. When using csh(1) you
might have problems to use ! due to its strange
parser. This is why the not alias exists.
perm Compare file permissions. With this option in effect,
star compares the low order 12 bits of the st_mode
field.
mode Same as perm.
type Compare file type. Note that star cannot compare the
file type in case of a hard link.
nlink Compare link count on hardlinks (currently not sup-
ported).
uid Compare numerical user id of file.
gid Compare numerical group id of file.
uname Compare ASCII version of user id of file. The user
name is mapped via the file /etc/passwd.
gname Compare ASCII version of group id of file. The group
name is mapped via the file /etc/group.
id Compare all user/group related info of file. Note
that this will always find differences if the source
and target system use different user or group map-
pings.
size Compare file size. Note that star cannot compare the
file size in case of a hard link.
symlink Compare target of symlinks. This evaluates the value
returned by the readlink(2) call.
atime Compare access time of file. This only works with if
the archive format is star, xstar, xustar, exustar, or
pax.
mtime Compare modification time of file.
ctime This only works with if the archive format is star,
xstar, xustar, exustar, or pax.
times Shorthand for: atime,mtime,ctime.
If optlst starts with a ! the meaning of all members in optlst
is inverted as with the not optlist member.
If diffopts are not specified, star compares everything but the
access time of the files.
-dirmode
If in create mode (i.e. when storing files to archive), star
stores directories past the corresponding files. This guarantees
that even old tar implementations without a directory cache will
be able to restore the correct times of directories.
-dodesc
Force star to descend directories found in a list=file. See
also the -D option above.
-dump This currently is an experimental option to make it easier to
implement a star version that supports true incremental dumps.
Star currently sets the archive type to exustar and archives
more inode meta data inside POSIX.1-2001 extended headers.
-F,-FF ...
Fast and simple exclude option for create mode. With one -F
argument, star ignores all directories called SCCS and RCS.
With two -F arguments, star in addition ignores all files called
core errs a.out all files ending with .o. OBJ/. With three -F
arguments, star ignores all sub trees starting from a directory
that includes a file .mirror or .exclude and all object files
and files called core errs a.out all files ending with .o. With
four -F arguments, star ignores all sub trees starting from a
directory that includes a file .mirror or .exclude the latter
files are excluded too as well as and all object files and files
called core errs a.out all files ending with .o. With five -F
arguments, star in addition again excludes all directories
called SCCS and RCS.
-fifo Use a fifo to optimize data flow from/to tarfile. This option
is in effect by default (it may be changed at compile time).
-fifostats
Print fifo statistics at the end of a star run when the fifo has
been in effect. All options that start with the -f sequence are
sensitive to typo problems, see BUGS section for more informa-
tion.
file=tarfilename, f=tarfilename
Use tarfilename as the name for the tar archive. Currently up to
100 file= options are possible. Specifying more then one file=
option make sense in multi volume mode. In this case star will
use the next name in the list every time a media change is
needed. To make star behave consistent with the single file
case, star loops over the list of known archive files. Note
that if star is installed suid root and the first tarfile is a
remote archive, only the connection to this archive will be cre-
ated with root privilleges. After this connection has been
established as root, star switches back to the id of the caller.
If any of the other archives in the list is located on a differ-
ent host, star will not be able to open this archive later on,
unless run by root.
Star normally uses stdin/stdout for the tar archive because the
most common way to use star is in conjunction with pipes. If
star is installed suid root or if it has been called by root,
tarfilename may be in remote syntax: user@host:filename as in
rcp(1) even if invoked by non root users. See SUID NOTES for
more information.
To make a file local although it includes a colon (:), the file-
name must start with: '/', './' or '../'
Note that if star talks to an old rmt remote tape server that
does not support symbolic open modes, it does not open a remote
tape with the O_CREAT open flag because this would be extremely
dangerous. If the rmt server on the other side is the rmt
server that comes with star or the GNU rmt server, star may use
the symbolic mode for the open flags. Only the symbolic open
modes allow to send all possible open modes in a portable way to
remote tape servers.
It is recommended to use the rmt server that comes with star.
It is the only rmt server that gives platform independent com-
patibility with BSD, Sun and GNU rmt clients and it includes
security features that may be set up in /etc/default/rmt. All
options that start with the -f sequence are sensitive to typo
problems, see BUGS section for more information.
-force_hole
obsoleted by -force-hole
-force-hole
star will not overwrite files that are read only. If this
option is in effect, star will silently remove these files to
allow the extraction of a file. All options that start with the
-f sequence are sensitive to typo problems, see BUGS section for
more information.
fs=# Set fifo size to #. See bs= for the possible syntax. The
default size of the fifo is 1 Mbyte on Sun mc68000 systems, 4
Mbytes on non mmap() aware Linux systems and 8 Mbytes on all
other systems. See -fifo option for hints on using the right
fifo size.
H=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.
tar Old 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 ar-
chive 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. 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.
gnutar This is a commonly used, but unfortunately not Posix
compliant (although designed after 1987) enhancement
to the old tar format. Do not use the gnutar archive
Files with pathnames longer than 100+155 chars or
linknames longer than 100 chars may not be archived.
If star is called as ustar the default archive format
is ustar.
If the ustar format has been selected, star will not
use enhancements to the POSIX.1-1988 tar format, the
archive will be strictly conforming. File size is
limited to 8 GB, uid/gid/major/minor is limited to
2097151. Sparse files will be filled up with zeroes.
pax The IEEE/Posix1003/IEC-9945-1-1988 successor, the
POSIX-1003.1-2001 Standard Data Interchange format.
If the pax format has been selected, star will not use
enhancements to the POSIX.1-2001 tar format, the ar-
chive will be strictly conforming. File size is
unlimited, uid/gid/uname/gidname is unlimited,
major/minor is limited to 2097151. Sparse files will
be filled up with zeroes.
xstar Extended standard tar format. Star uses the xstar
format as default archive format. This is an
upward/downward compatible enhancement of the
IEEE/Posix1003/IEC-9945-1 Standard Data Interchange
format. It allows among others very long filenames
(100+130 chars and above) and records access time and
creation time. The xstar format is the default format
when star is neither called as tar nor called as
ustar.
xustar New format introduced 1998, that omits the tar signa-
ture at the end of the tar header. It is otherwise
identical to the xstar format. As some tar implemen-
tations do not follow the POSIX rules and compute the
checksum for less than 512 bytes of the tar header,
this format may help to avoid problems with these tar
implementations. The main other difference to the
xstar format is that the format uses POSIX.1-2001
extended headers to overcome limitations of the his-
toric tar format while the xstar format uses propri-
etary extensions. The xustar format is the default
format when star is called as tar.
File size is unlimited, uid/gid/uname/gidname is
unlimited, major/minor is unlimited. Sparse files
will be archived correctly.
exustar A format similar to the xustar format but with forced
POSIX.1-2001 extended headers. If this format is used
together with the -acl option, star records Access
Control Lists (ACLs) in POSIX.1-2001 extended headers.
All tar archive formats may be interchanged if the archive con-
tains no files that may not be archived by using the old tar
format. Archives in the xstar format may be extracted by any
100% POSIX compliant tar implementation if they contain no files
with pathnames > 100+130 chars and if they contain no sparse
files that have been archived by using the -sparse option.
-h, -L Follow symbolic links as if they were files. Normally star will
not follow symbolic links but stores their values in tarfile.
See also the -L option.
-hardlinks
In extract mode, this option tells star to try to create a
hardlink whenever a symlink is encountered in the archive. In
create mode, this option tells star to try to archive a hardlink
whenever a symlink is encountered in the file system.
-hpdev Allow 24 bits for the minor device number using 8 octal digits.
Note that although it allows to create tar archives that can be
read with HP-UX tar, this creates tar archives which violate
POSIX.1-1988. This option is only needed if you like to use a
POSIX.1-1988 based archive format that does not include exten-
sions. If you use the xstar format, star will use a base 256
extension that allows bigger major/minor numbers by default, if
you use the xustar or the exustar format there is no limitation
at all as these formats use POSIX.1-2001 extended headers to ar-
chive the major/minor numbers by default.
-i Ignore checksum errors on tar headers. If this option is speci-
fied, star will not exit if a header with a bad checksum is
found but search for the next valid header.
-I Obsolete option, otherwise identical to -w.
-keep_old_files
obsoleted by -keep-old-files
-keep-old-files, -k
Keep existing files rather than restoring them from tarfile.
This saves files from being clobbered even if tarfile contains a
more recent version of the corresponding file.
-L, -h Follow symbolic links as if they were files. Normally star will
not follow symbolic links but stores their values in tarfile.
See also the -h option.
-l Do not print a warning message if not all links to hard linked
files could be dumped. This option is evaluated in the opposite
way to historic tar(1) implementations and to POSIX.1. POSIX.1
requests that by default no warning messages will be printed and
reason its only recommended to use this option when doing accu-
rate backups and when hard links to directories are expected.
When the option -link-dirs is not used and hard links to direc-
tories are present, the appendant sub-tree will appear more than
once on the archive and star will print Linkcount below zero
warnings for non directory hard links inside the sub-tree.
list=filename
Read filenames for store/create/list command from filename. The
file filename must contain a list of filenames, each on a sepa-
rate line. This option implies the -D option. To force star to
descend directories, use the -dodesc option in this case.
-M Do not descend mount points. This is useful when doing backups
of complete filesystems. See NOTES for more information.
-m Do not restore access an modification time. (Access time is
only available if star is reading star, xstar, xustar, exustar,
or pax archives). If star extracts other archive types, the -m
flag only refers to the modification time.
maxsize=#
Do not store files in tarfile if they are bigger than #. See
bs= for the possible syntax. By default, the number is multi-
plied by 1024, so the value counts in units of kBytes. If the
size specifier ends with a valid multiplication character (e.g
'.' for bytes or 'M' for MB) the specified size is used as spec-
ified and not multiplied by 1024. See bs= option for all possi-
ble multipliers.
-meta This currently is an experimental option. In create mode, it
causes star to archive all meta data of the file (e.g. uid, per-
missions, ...) bit not the file content. In extract mode, it
causes star to restore all meta data but not the file content.
In addition, in extract mode no plain file, special file or
directory will be created. Meta files are needed in future star
versions that support incremental backups.
Warning: Do not try to extract star archives containing meta
files using other tar implementations if they are not aware of
the meta file extensions of star. Star tries to force all tar
implementations that are not standard compliant to abort. Star
also tries to make all non POSIX.1-2001 compliant tar implemen-
tations unable to find a valid filename. However when other
POSIX.1-2001 aware tar implementations come up and don't know
about meta files, they will destroy files on disk.
The problems result from the only current fallback in the POSIX
standard that tells tar implementations to treat all unknown
file types as if they were plain files. As meta files are needed
-newest
In conjunction with the list command this lists you only the
newest file in tarfile.
-newest_file
obsoleted by -newest-file
-newest-file
In conjunction with the list command this lists you only the
newest regular file in tarfile.
new-volume-script=script
Call script at end of each tape if in multi volume mode. If
this option is not in effect, star will ask the user to confirm
the volume change.
-nodump
If this option is set, star will not dump files that have the
nodump flag set. Note that this currently only works on BSD-4.4
derivates and on Linux. On Linux, using this option will cause
a performance degradation (the system time increases by 10%)
because of the unlucky kernel interface.
-no_fifo
obsoleted by -no-fifo
-no-fifo
Don't use a fifo to optimize data flow from/to tarfile. Cur-
rently the -fifo option is used as default. (This may be changed
at compile time.)
-nochown, -o
Do not restore owner and group of files. This may be used if
super user privileges are needed to overwrite existing files but
the local ownership of the existing files should not change.
-no_statistics
obsoleted by -no-statistics
-no-statistics
Do not print statistic messages at the end of a star run.
-not, -V
Invert the meaning of the pattern list. i.e. use those files
which do not match any of the pattern. Note that this option
only applies to patterns that have been specified via the pat-
tern=pattern or pat=pattern option. Patterns specified as file
type arguments will not be affected.
-nowarn
Do not print warning messages. This sometimes is useful to make
this option, star generates archives which are fully compatible
with old UNIX tar archives. If in extract mode, star ignores any
additional info in the headers. This implies neither that ar-
chives generated with this option are binary equal with archives
generated by old tar versions nor that star is trying to compre-
hend all bugs that are found in old tar versions. The bug in
old tar versions that cause a reversal of a space and a NULL
byte in the checksum field is not repeated. If you want to have
signed checksums you have to specify the -singed-checksum option
too. If you want directories not to be archived in order to be
compatible to very old historic tar archives, you need to spec-
ify the -d option too.
This option is superseeded by the H=headertype option.
-o, -nochown
Do not restore owner and group of files. This may be used if
super user privileges are needed to overwrite existing files but
the local ownership of the existing files should not change.
-onull, -nullout
Do not actually write to the archive but compute and add the
sizes. This is useful when trying to figure out if a tape may
hold the current backup. Please only use the -onull option as
it is a similar option as used by the sdd(1) command.
-P Allow star to write a partial record as the last record. Nor-
mally, star writes each record with the same size. This option
is useful on unblocked tapes i.e. cartridge tapes like QIC tapes
as well as with archives that are located in files. If you use
this option on local files, the size of the archive will be
smaller. If you use this option on cartridge tapes, is makes
sure that later - in extract mode - star will read up to the end
of file marker on the tape and the next call to star will read
from the next archive on the same tape.
-p Restore filemodes of directories. Without this option directo-
ries are created using the present umask(2). If in create mode
(i.e. when storing files to archive), star stores directories
past the corresponding files. This guarantees that even old tar
implementations will be able to restore the correct times of
directories. If the archive contains Access Control Lists
(ACLs) in POSIX.1-2001 extended headers, star will restore the
access control lists from the archive for files if the -acl
option is specified. If the option -acl has not been specified,
ACLs are not restored at all.
pattern=pattern, pat=pattern
Set matching pattern to pattern. A maximum of 100 pattern=pat
options may be specified. As each pattern is unlimited in
length, this is no real limitation. If more than one pattern is
specified, a file matches if any of the specified pattern
pattern matcher. All patterns are selection patterns by
default. To make them exclude patterns, use the -not or the -V
option.
-qic24 Set tape volume size to 61440 kBytes. See tsize=# option for
more information.
-qic120
Set tape volume size to 128000 kBytes. See tsize=# option for
more information.
-qic150
Set tape volume size to 153600 kBytes. See tsize=# option for
more information.
-qic250
Set tape volume size to 256000 kBytes. See tsize=# option for
more information.
-refresh_old_files
obsoleted by -refresh-old-files
-refresh-old-files
-refresh
Do not create new files. Only already existing files may be
overwritten from tarfile if either newer versions are present in
the archive or if the -U flag is used. This allows to overwrite
files by more recent files from an archive that contains more
files than the target directory should contain. The option
-refresh-old-files is the same as the -refresh option.
-remove_first
obsoleted by -remove-first
-remove-first
Remove files before extraction. If this option is in effect,
star will remove files before extracting a file from the ar-
chive. This is needed if you want to change the file type or if
you need to break a hard link. If you do not use either
-ask-remove or -force-remove together with -remove-first, this
option is useless and no files will be removed.
-remove_recursive
obsoleted by -remove-recursive
-remove-recursive
Remove files recursive. If removing of a file is permitted,
star will only remove files, specials and empty directories. If
this option is in effect, star will be allowed to recursively
removes non empty directories too.
-signed_checksum
obsoleted by -signed-checksum
-signed-checksum
Use signed chars to calculate checksums. This violates the tar
specs but old versions of tar derived from the seventh edition
of UNIX are implemented in this way. Note: Only filenames and
linknames containing chars with the most significant bit set may
trigger this problem because all other fields only contain 7 bit
ASCII characters, octal digits or binary zeroes.
-silent
Suppress informational messages like foobar is sparse.
-sparse
Handle files with holes effectively on store/create. Note that
sparse files may not be archived this way if the archive format
is tar, ustar, pax, or suntar. On Solaris-2.3 ... Solaris-2.5.1
there is a special ioctl() called _FIOAI that allows root to get
the allocation info more efficiently. Other operating systems
lack support to get the real allocation list and force star to
scan the files to look for blocks that only contain null charac-
ters. This may star to assume more holes to be present than the
number that the file really contains.
-symlinks
This option tells star in extract mode to try to create a sym-
link whenever a hardlink is encountered in the archive.
-T If the option file= or f= is omitted and the -T option is
present, star will use the device indicated by the TAPE environ-
ment variable, if set.
-time Print timing info. See DIAGNOSTICS for more information.
-to_stdout
obsoleted by -to-stdout
-to-stdout
Extract files to stdout. This option may be used to extract
tarfiles containing tarfiles (see examples below).
-tpath Use this option together with the -t option to get only a list
of the pathnames of the files in the archive. This may be used
in shell scripts to generate a name list. If used together with
the -diff option, star will only print the names of the files
that differ. A second run of star may then be used to restore
all files that had differences to the archive. Use the list=
option to specify the namelist in this case.
tsize=#
Set tape volume size to # to enable multi volume tape support.
flag. Normally, star does its work silently. If the verbose
level is 2 or more and star is in create or update mode, star
will produce a listing to the format of the ls -l output.
-V, -not
Invert the meaning of the pattern list. i.e. use those files
which do not match any of the pattern. Note that this option
only applies to patterns that have been specified via the pat-
tern=pattern or pat=pattern option. Patterns specified as file
type arguments will not be affected.
-version
Print version information and exit.
VOLHDR=name
Use name to generate a volume header.
-w Do interactive creation, extraction or renaming. For every file
that matches the list of patterns and that has a more recent
modification time in the tar archive (if in extract mode and the
-U option is not specified) star prints its name and asks:
get/put ? Y(es)/N(o)/C(hange name) :
You may answer either `N' for No or <Return> to skip this file.
If you answer `Y' the file is extracted or archived on tape with
its original name. If you answer `C', you are prompted for a
new name. This name is used for the filename on disk if star is
in extract mode or for the archive name if star is in create
mode.
-wready
This option is added as a hack for a bug in the SunOS/Solaris st
device driver. This driver has problems to sense the loading
time with Exabyte drives with factory settings. Star waits up
to one minute for the drive to become ready if this option is
specified.
-xdir Extract directories even if the corresponding directories on the
archive are not newer. This is useful when for some reason, the
directories are recorded after their content (see -dirmode
option), or when the permissions of some directories must be set
in any case.
-xfflags
Store and extract extended file flags as found on BSD and Linux
systems. This option only makes sense when creating or extract-
ing exustar archives as it is based on POSIX.1-2001 extended tar
headers.
-z run the input or output through a gzip pipe. This is currently
a quick and dirty hack, that mainly will cover the most common
if the tape can hold 60 MB.
SIGNALS
If star handles a signal, it first prints the statistics. Star handles
the following signals:
SIGINT usually generated by ^C from the controlling tty. Upon
receipt of a SIGINT, star prints statistics and exits. If in
create mode i.e. storing files to archive, star finishes with
the current file to ensure that no partial file is written to
the archive, write an eof record and then exits.
SIGHUP not to be generated from a tty. The actions are the same as
upon receipt of a SIGINT.
SIGQUIT usually generated by ^\ from the controlling tty. Upon
receipt of a SIGQUIT, star prints statistics and continues
with the current operation. This is useful to watch the
progress of the current operation.
EXAMPLES
To get a listing in a way similar to ls -l one might use:
example% star -tv f=/dev/rmt/1bn
The same command as listed above in a POSIX tar command line syntax
compliant way is:
example% star tvf /dev/rmt/1mbn
To copy the directory tree in /home/someuser to the directory /home/fs
use:
example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)
or by using the change directory option of star:
example% star -c -C /home/someuser . | star -xp -C /home/fs
To copy a file tree including the Access Control List entries for all
files use:
example% star -c -Hexustar -acl -C /home/someuser . | star -xp -acl -C /home/fs
To compare the content of a tape to the filesystem one might use:
example% star -diff -v f=/dev/rmt/1bn
To compare two directory trees one might use:
the CD one might use:
example% star -zxp -C /tmp f=star-1.1.tar.gz
to extract the files from the tar archive to the /tmp directory.
To backup a list of files generated by the find(1) command:
example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
Note that this does not work if the file names from output of the find
command include new line characters.
To extract a tarfile that contains a tarfile one might use:
example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
Pat, in this case should match the tarfile in the tarfile on tape that
should be extracted.
To make a backup of the root filesystem to a tape drive connected to a
remote machine, one might use:
example# cd /
example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
You need a line in /etc/passwd like the following to enable this:
tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
And a .rhosts file in /etc/tapehome to allow remote connections from
the appropriate hosts. Make sure that the file /etc/default/rmt exists
and allows remote access to the requested tape drive.
To repair a corrupted filesystem for which no recent backup exists, do
the following:
example# fsck -y /filesys
example# mount /filesys
example# cd /filesys
example# star -xpk f=/dev/rmt/1bn
example# mt -f /dev/rmt/1bn rewind
example# star -diff -v diffopts=!times f=/dev/rmt/1bn
Now check the differences and decide whether to restore additional
files. This may be done by generating a list containing the needed
filenames and using the list= option or by using the interactive mode
(see -w option).
If you want a list that only contains all filenames from files with
differences you may use:
STAR_FIFO_SIZE
If you like to by default let star use a different fifo size,
set this environment variable to the desired size.
TAPE Unlike other tar(1) implementations, star defaults to use
stdin/stdout for the archive. If you like star to use the file
name from the TAPE environment instead, you need to specify the
-T option too.
FILES
Currently none except the files implied be the command line from star.
In future, star may use /etc/default/star to set up global defaults.
SEE ALSO
tar(1), cpio(1), rcp(1), mt(1), rmt(1), match(1), dd(1), sdd(1),
star(4/5), rcmd(3), fssnap(1m)
DIAGNOSTICS
star: f records + p bytes (total of x bytes = d.nnk).
The number of full records, the number of bytes in partial records and
the total amount of data in KBytes.
star: Total time x.yyysec (z kBytes/sec)
The time used and the transfer speed from/to the archive.
If there have been non fatal errors during the archive processing, star
will display a delayed error summary before exiting.
NOTES
The POSIX command line syntax for the tar command deviates from the
command line syntax defined for all other commands. While the POSIX
command line syntax requests all options to start with a dash (-) and
allows to either write options separately or combined (in case of
boolean flags), the POSIX tar command line syntax requires all options
to be combined into a single string that does not start with a dash.
Star by default assumes a command line syntax like a typical POSIX com-
mand and includes a compatibility mode that allows to specify a command
line syntax as documented for the POSIX tar command. If you believe
that you found a bug in the way star parses the command line, please
first check your command line for correctness before you make a bug
report for star.
If you like to write portable shell scripts that call tar, use the
POSIX tar command line syntax (i.e. a single option string and no
dash), choose the commands and options from the following set of char-
acters ( rxtuc vxfblmo ) and check the shell script with both, your
local tar and star for correct behavior. It you expect the script to
call gnutar, do not include the -o option as gnutar implements this
file may not be archived. Linknames longer than 100 chars may
not be archived too.
The star, xstar, xustar, exustar, pax, and gnutar archive formats don't
have these limitations. While gnutar uses a method that makes it impos-
sible for other tar implementations (except star) to restore filenames
that are longer than 100 chars, the xstar, xustar, exustar and pax ar-
chive format uses a method that allows an POSIX.1-1988 compliant way of
storing filenames, if the POSIX method would allow this. When the ar-
chive format is xustar, exustar or pax very long filenames are stored
using extended headers from the POSIX.1-2001 standard.
Some buggy tar implementations will generate incorrect filenames during
a restore operation if the archive contains pathnames or linknames of
exactly 100 chars length.
Star adds a tar signature in the last four bytes of each tar header if
the archive format is star or xstar. This is no problem with the star
archive format as it is an extension of the old pre POSIX.1-1988 tar
format. On the other side, the xstar archive format claims to be as
POSIX.1-1988 compliant as possible. Inserting this tar signature is a
minor deviation from the standard that has the last 12 bytes of each
header reserved for future use. On the other side, tar implementations
such as some pax implementations that only compute checksums on the
first 500 bytes of the header are violating the standard that requests
the checksum to be computed on all 512 bytes of the tar header. All tar
implementations that are 100% Posix compliant will be able to extract
xstar archives as long as no new standard is defined that claims the
last 12 bytes of the header for a different use. But then the ustar
version number should be changed from `00' to `01'. Now, that the
POSIX-2001 standard has been accepted, it is even predictable that all
extensions to the standard tar format will go into the POSIX.1-2001
extended headers which are extensible to include any feature without
future limitation. The only known tar implementation that also uses
the last 12 bytes of the tar header is Sun's tar which uses these 12
bytes for files that are split over several archives. Such archives
created by Sun's tar are not readable by the buggy pax implementation
too. The Sun extension is not incompatible to the star signature
because Sun expects an octal number at the beginning of the 12 byte
field which is a null character in the star case.
Star uses these four bytes since 1985 without problems. If you need a
100% POSIX.1-1988 and 100% POSIX.1-2001 compliant tar archive, you may
use the xustar, exustar or the pax archive format. The probability of
falsely detecting other tar formats as xustar or exustar format however
is higher.
There is no way to ask for the n-th occurrence of a file.
The way EOF is handled by star differs, whether the fifo is in effect
or not. If the fifo is not used, star stops reading the archive if it
encounters a logical EOF record in the archive. If the fifo is used,
If the author decides to change this method, later versions of star may
not be able to restore sparse files from tar archives made by the cur-
rent version of star.
Some tar implementations violate the standard in using only the first
500 Bytes of the header for checksum computation. These tar implementa-
tions will not accept star and xstar type tar archives.
Sun's Solaris 2.x tar implementation violates the Posix standard. Tar
archives generated by star cause Sun's tar to print tar: impossible
file type messages. You may ignore these messages.
Gnutar's dumpdirs are non standard and are currently not implemented.
If gnutar archives sparse files with more than four holes, it produces
archives that violate the standard in a way that prevents other tar
implementations to read these archives. Star knows about that and is
able to handle these gnutar archives.
The filetype N (LF_NAMES) from gnutar (an obsolete method of storing
long names) will never be implemented.
SUID NOTES
If star is installed suid root, star is able to make connections to
remote archives for non root users. This is done by using the rcmd(3)
interface to get a connection to a rmt(1) server.
Star resets its effective uid back to the real user id immediately
after setting up the remote connection to the rmt server and before
opening any other file.
LIMITATIONS
If star is running on a large file aware platform, star is able to han-
dle files up to 8 GB in a mode that is compliant to the POSIX.1-1988
ustar format. With a nonstandard star specific extension, up to 95 bits
may be used to code the filesize. This will handle files up to
200,000,000 TB. With the new POSIX.1-2001 extended headers used by the
xustar, exustar and pax format, any filesize may be archived.
BUGS
The fact that the -f option has to be implemented in a way that is com-
patible with old tar implementations gives several problems. The
options -fifostats, -force-hole, -force-remove and -fifo interfere with
the -f option and the fact that they exist prevents users from using
filenames like e.g. ifo using the traditional way where the filename
directly follows the string -f without any space between the option
name and the file name. However, there is no problem to use a file
named ifo by by calling -f ifo, f=ifo, -f=ifo or -f= ifo. Be careful
not to make typos with the above options. The result could be that a
file is created as a result of the mistyped option.
There is currently no way to set the fifo lowwater and highwater marks.
HISTORY
Star was first created in 1982 to extract tapes on a UNIX clone that
had no tar command. In 1985 the first fully functional version has
been released as mtar.
When the old star format extensions have been introduced in 1985, it
was renamed to star (Schily tar). In 1994, Posix 1003.1-1988 exten-
sions were added and star was renamed to star (Standard tar).
AUTHOR
Joerg Schilling
Seestr. 110
D-13353 Berlin
Germany
Mail bugs and suggestions to:
schilling@fokus.gmd.de or js@cs.tu-berlin.de or
joerg@schily.isdn.cs.tu-berlin.de
Joerg Schilling 02/05/09 STAR(1)
Man(1) output converted with
man2html