STAR(1) Schily´s USER COMMANDS STAR(1)
NAME
star(1,4) - unique standard tape archiver
SYNOPSIS
star(1,4) command [ options ] file1 ... filen
ustar command [ options ] file1 ... filen
tar command [ options ] file1 ... filen
star(1,4) -copy [ options ] file1 ... directory
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(1,n)
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(1,4) acts may be modified by additional options.
Note that unpacking tar archives may be a security risk because star(1,4)
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(1,2,n) stamps in(1,8) 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(1,8) 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(1,8) a tar archive into an existing file(1,n) tree. See also -U option. In
create mode use the pat= option to specify either select(2,7,2 select_tut) or exclude
patterns (depending on the -V flag). In extract or list mode all file(1,n)
type arguments are interpreted as select(2,7,2 select_tut) patterns while the patterns
specified with the pat= option may be used as select(2,7,2 select_tut) or exclude pat-
terns (depending on the -V flag). Have a look(1,8,3 Search::Dict) at the description of
the -C option to learn how fetch files from a list of directories (in(1,8)
create mode) or to distribute files to a list of directories (in(1,8)
extract mode). A substitute option allows ed(1) like pattern substitu-
tion in(1,8) file(1,n) names.
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(3,n) the
archive format is either chosen from the star(1,4) specific formats or is a
format that uses POSIX.1-2001 extended headers. This is either done in(1,8)
second resolution by using a star(1,4) specific POSIX.1-1988 compatible
extension or in(1,8) 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(1,4) is able to do backups
without changing any of the 3 the times.
If used with the H=ustar option, or if(3,n) called as ustar or tar while the
H=headertype option is not used, star(1,4) is 100% POSIX compliant.
Star's default format (if(3,n) called as star(1,4)) is xstar and is as posix com-
pliant 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(1,8) 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(1,4) is able to restore only the missing
files automatically. Use then star(1,4) -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(1,8)
their native mode, if(3,n) it knows about the peculiarities of the archive
type. See the H=headertype option for more details. To be able to do
this, star(1,4) adds hidden fingerprints to the archive header that allows
to recognise all star(1,4) 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(1,4) 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(1,4) expects commands and options to
appear as one single string(3,n) 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(1,2) named(5,8) 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.
-copy Copy named(5,8) files to the target directory which is the last file(1,n)
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(1,8) addition, star(1,4) per-
forms 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(1,n) I/O (such as Linux), it may
help to use -no-fsync in(1,8) addition, but then star(1,4) is unable to
detect all error(8,n) conditions; so use with care.
If the option -t has been specified in(1,8) addition, the last file(1,n)
type argument is not a target directory and star(1,4) is performing a
one pass listing instead of copying files. This makes sense as
the listing from star(1,4) 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(1,8) the best archive mode. This
implies that it defaults to H=exustar -dump. When in(1,8) -copy
mode, star(1,4) forks into two processes and data exchange is done
via the shared memory from the FIFO. This gives the best possi-
ble 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 ar-
chive in(1,8) tarfile to the filesystem. This may also be used to
compare two file(1,n) trees in(1,8) the filesystem. If you use a set(7,n,1 builtins) of
diffopts that fits your needs, it will give - in(1,8) many cases - a
more readable output than diff -r. If you use star(1,4)'s dump
extensions for the tar archive, the -diff option allows to find
even if(3,n) the directory in(1,8) the file(1,n) tree contains more files than
the archive. This way, it is possible to compare all properties
of two file(1,n) trees in(1,8) 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(3,n) in(1,8) -dump
mode.
-n No extraction. Show what star(1,4) would do, in(1,8) case the -x command
had been specified.
-r Replace files in(1,8) a tarfile. The named(5,8) 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 out-
put. With this option, the flags -a, -atime and -ctime have a
different meaning if(3,n) the archive is in(1,8) star(1,4), xstar, xustar,
exustar, or pax format. The option -a or -atime lists the
access(2,5) time(1,2,n) instead of the modification time(1,2,n), the option -ctime
lists the file(1,n) creation time(1,2,n) instead of the modification time.
The option -tpath may be used in(1,8) addition to modify the output
so it may be used in(1,8) shell scripts.
-u Update a tarfile. The named(5,8) files are written to the end of
tarfile if(3,n) they are not already there or if(3,n) the files are newer
than the files of the same name found in(1,8) the archive. The -r
and -u command only work if(3,n) the tar archives is a regular file(1,n)
or if(3,n) the tar archive is an unblocked tape that may backspace.
-x Extract the named(5,8) 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(1,4) extracts no file(1,n)
which is older than the corresponding file(1,n) on disk.
On operating systems with slow file(1,n) I/O (such as Linux), it may
help to use -no-fsync in(1,8) addition, but then star(1,4) is unable to
detect all error(8,n) 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 pat-
terns and substitute commands apply to the create side.
OPTIONS
-help Print a summary of the most important options for star(1,4)(1).
-xhelp Print a summary of the less(1,3) important options for star(1,4)(1).
-/ Don't strip leading slashes from file(1,n) 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(1,8) extract mode. As it may be impossible to create an ar-
chive where leading slashes have been stripped while retaining
correct path names, star(1,4) does not strip leading slashes in(1,8) cre-
ate mode.
See SECURITY NOTES for more information.
-.. Don't skip files that contain /../ in(1,8) the name. Tar archives
containing names with /../ could be used to compromise the sys-
tem. If they are unpacked together with a lot of other files,
this would in(1,8) most cases not even be noticed. For this reason,
star(1,4) by default does not extract files that contain /../ in(1,8) the
name if(3,n) star(1,4) is not in(1,8) interactive mode (see -w option).
See SECURITY NOTES for more information.
-0
-1
-2
-3
-4
-5
-6
-7 Select an archive entry from /etc/default/star(1,4). The format for
the archive entries is the same as the format in(1,8)
/etc/default/tar in(1,8) Solaris.
-acl Handle Access Control List (ACL) information in(1,8) create and
extract mode. If -acl has been specified, star(1,4) is in(1,8) create
mode and the header type is exustar, star(1,4) will add ACL informa-
tion to the archive using POSIX.1-2001 extended headers. If
-acl has been specified and star(1,4) is in(1,8) extract mode, star(1,4) will
try to restore ACL information. If there is no ACL information
for one or all files in(1,8) the archive, star(1,4) will clear(1,3x,3x clrtobot) the ACL
information for the specific file. Note that if(3,n) -acl has not
been specified, star(1,4) 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(1,4) assumes that the -p
option has been specified too.
artype=headertype
Generate a tape archive in(1,8) headertype format. If this option is
used in(1,8) extract/list mode this forces star(1,4) to interpret the
headers to be of type headertype. As star(1,4) even in(1,8) 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(1,4) 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(1,4) 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(1,4) Old star(1,4) standard format. This is an upward/downward
compatible enhancement of the old (pre Posix) UNIX tar
format. It has been introduced in(1,8) 1985 and therefore
is not Posix compliant. The star(1,4) format allows to ar-
chive special files (even sockets) and records access(2,5)
time(1,2,n) and creation time(1,2,n) besides the modification time.
Newer versions of the old star(1,4) 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(1,8) 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(1,8) the space
between the link(1,2) name and the POSIX file(1,n) name prefix.
As the star(1,4) format does not use a POSIX magic(4,5) string(3,n),
the extensions do not interfere with the POSIX tar
formats. The last 4 bytes of the tar header contain a
'tar\0' signature.
gnutar This is a commonly used, but unfortunately not Posix
compliant (although designed after 1987) enhancement
to the old tar format. The gnutar format has been
defined between 1989 and 1994. Do not use the gnutar
archive format unless you want to create an archive
for a target system that is known to have only the
gnutar program available. The gnutar archive format
violates basic rules for any (even the historic) tar
archive format. Using the gnutar archive format
causes a high risk that the resulting archive may only
be read(2,n,1 builtins) by gnutar or by star(1,4). The implementation of
the gnutar archive format within star(1,4) is not complete,
but sufficient for most gnutar archives. See NOTES
for more information.
ustar IEEE/Posix1003/IEC-9945-1-1988 Standard Data Inter-
change format. With this option in(1,8) effect, star(1,4) will
generate 100% POSIX.1-1988 compliant tar archives.
Files with pathnames longer than 100+155 chars or
linknames longer than 100 chars may not be archived.
If star(1,4) is called as ustar the default archive format
is ustar.
If the ustar format has been selected, star(1,4) 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 is the
POSIX-1003.1-2001 Standard Data Interchange format.
It is called the pax archive format.
If the pax format has been selected, star(1,4) 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(1,2)/gidname is unlimited,
major/minor is limited to 2097151. Sparse files will
be filled up with zeroes.
xstar The extended standard tar format has been introduced
in(1,8) 1994. Star uses the xstar format as default ar-
chive 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(2,5) time(1,2,n) and creation time.
The access(2,5) time(1,2,n) and creation time(1,2,n) are stored at the
end of the POSIX file(1,n) name prefix (this limits the
prefix to 130 chars). These extensions do not inter-
fere with the POSIX standard as the fields for mtime
and ctime field are always separated from the POSIX
file(1,n) name prefix by a null byte. The last 4 bytes of
the tar header contain a 'tar\0' signature.
The xstar format is the default format when star(1,4) is
neither called as tar nor called as ustar.
xustar A new format introduced 1998, that omits the 'tar\0'
signature at the end of the tar header. It is other-
wise identical to the xstar format. As some tar
implementations do not follow the POSIX rules and com-
pute the checksum for less(1,3) than 512 bytes of the tar
header, this format may help to avoid problems with
these broken tar implementations. The main other dif-
ference to the xstar format is that the xustar format
uses POSIX.1-2001 extended headers to overcome limita-
tions of the historic tar format while the xstar for-
mat uses proprietary extensions. The xustar format is
the default format when star(1,4) is called as tar.
File size is unlimited, uid/gid/uname(1,2)/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(1,4) records Access
Control Lists (ACLs) in(1,8) POSIX.1-2001 extended headers.
File size is unlimited, uid/gid/uname(1,2)/gidname is
unlimited, major/minor is unlimited. Sparse files
will be archived correctly.
suntar The extended header format found on Solaris 7/8/9.
This format is similar to the pax format but does not
handle atime and ctime and in(1,8) addition uses 'X' as the
typeflag for the extended headers instead of the stan-
dard 'x'.
File size is unlimited, uid/gid/uname(1,2)/gidname is
unlimited, major/minor is unlimited. Sparse files
will be filled up with zeroes.
bin The cpio UNIX V7 binary format. This is a format with
big interoperability problems. Try to avoid this for-
mat. It is only present to make the scpio command
SVr4 compliant.
cpio The POSIX.1-1988 cpio format. This format uses octal
ascii(1,7) headers. A similar format is created by calling
cpio -o -c on pre SYSVr4 systems and by calling cpio
-o -Hodc on SYSVr4 systems. The POSIX.1-1988 cpio
format allows a file(1,n) name length up to 262142 charac-
ters and allows to archive nearly any file(1,n) type. File
size is limited to 8 GB, uid/gid/st_dev is limited to
262143. The way major and minor device numbers are
stored inside the st_dev field is implementation
dependent.
Even though this archive format is covered by the
POSIX.1-1988 standard, it has a lower portability than
the ustar format. Try to avoid the cpio archive for-
mat.
odc This archive format is similar to the The POSIX.1-1988
cpio format but the file(1,n) name length is limited to 255
characters and the socket(2,7,n) file(1,n) type is not allowed.
This archive format has been introduced to allow non
POSIX cpio implementations such as the cpio program on
SYSV to accept(2,8) the archive. Use this format whenever
you are not sure if(3,n) the target system offers a fully
POSIX compliant cpio program.
Even though this archive format is covered by the
POSIX.1-1988 standard, it has a lower portability than
the ustar format. Try to avoid the odc archive format.
asc Tell star(1,4) to create a cpio archive in(1,8) the ascii(1,7) format
that is created with cpio -o -c on SYSVr4 systems. It
uses extended (32 bit) numbers for uid's, gid's and
device numbers but limits the file(1,n) size to 2 GB - 2
bytes although the format has been specified after the
POSIX.1-1988 cpio format. Try to avoid the asc ar-
chive format because of it's limited portability.
crc This format is similar to the asc cpio format but in(1,8)
addition uses a simple byte based checksum called CRC.
Try to avoid the crc archive format because of it's
limited portability.
All tar archive formats may be interchanged if(3,n) the archive con-
tains no files that may not be archived by using the old tar
format. Archives in(1,8) the xstar format may be extracted by any
100% POSIX compliant tar implementation if(3,n) they contain no files
with pathnames > 100+130 chars and if(3,n) they contain no sparse
files that have been archived by using the -sparse option.
-ask_remove
obsoleted by -ask-remove
-ask-remove
Ask to remove non writable files on extraction. By default,
star(1,4) will not overwrite files that are read(2,n,1 builtins) only. If this
option is in(1,8) effect, star(1,4) will ask whether it should remove
these files to allow the extraction of a file(1,n) in(1,8) the following
way:
remove 'filename' ? Y(es)/N(o) :
-atime, -a
Reset access(2,5) time(1,2,n) of files after storing them to tarfile. On
Solaris 2.x, (if(3,n) invoked by root) star(1,4) uses the _FIOSATIME ioctl
to do this. This enables star(1,4) not to trash the ctime while
resetting the atime of the files. If the -atime option is used
in(1,8) conjunction with the list command, star(1,4) lists access(2,5) time(1,2,n)
instead of modification time. (This works only in(1,8) conjunction
with the star(1,4), xstar, xustar, exustar, and with the pax format.)
Another option to retain the access(2,5) time(1,2,n) for the the files that
are going to be archives is to readonly mount(2,8) a UFS snapshot and
to archive files from the mount(2,8) point of the UFS snapshot.
-B Force star(1,4) to perform multiple reads (if(3,n) necessary) to fill a
block. This option exists so that star(1,4) can work across the Eth-
ernet, since pipes and sockets return partial blocks even when
more data is coming. If star(1,4) uses stdin as archive file(1,n), star(1,4)
behaves as if(3,n) it has been called with the -B option. For this
reason, the option -B in(1,8) practice is rarely needed.
-block-number
Print the archive block number (archive offset / 512) at the
beginning of each line when in(1,8) verbose mode. This allows to
write(1,2) backup scripts that archive the offsets for files and that
use
mt fsr blockno
to skip to the tape block number of interest in(1,8) a fast way if(3,n) a
single file(1,n) needs to be restored.
blocks=#, b=#
Set the blocking factor(1,6) of the tarfile to # times 512 bytes
(unless a different multiplication factor(1,6) has been specified -
see bs= option for posible multiplication factors). Changing
the blocking factor(1,6) 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(1,6) 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(1,8) any case is the size of the buffer
RAM in(1,8) the tape drive. Make a test if(3,n) you want to make sure
that the target system will handle the intended blocksize. If
you use star(1,4) 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(1,4) for
backup purposes with recent hardware (e.g. DLT tape drives), a
blocksize of 256 kBytes results in(1,8) sufficient speed and seems to
be a good choice. Star allows block sizes up to 2 GByte if(3,n) the
system does not impose a smaller limit. If you want to deter-
mine the blocking factor(1,6) when reading an unknown tar archive on
tape, specify a blocking factor(1,6) that is higher than the supposed
blocking factor(1,6) of the tape. Star then will determine the
blocking factor(1,6) by reading the first record of the tape and
print a message:
star: Blocksize = # records.
Where # is the blocking factor(1,6) in(1,8) 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(1,8)
dd(1) and sdd(1). The number representing the size is taken in(1,8)
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 `*', 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).
-bsdchdir
Switch the behavior of the C= option to BSD style. The default
behavior of star(1,4) is to stay in(1,8) a working directory until a new
C= is seen. With BSD tar, the C= option is only related to the
next file(1,n) type argument.
-bz run the input or output through a bzip2 pipe(2,8) - see option -z -Z
and -j below. As the -bz the -j the -Z and the -z option are
non standard, it makes sense to omit the -bz the -j the -Z and
the -z options inside shell scripts if(3,n) you are going to extract
a compressed archive that is located inside a plain file(1,n) as star(1,4)
will auto(5,8) 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(1,4) will perform the chdir(2)
operation relative to the current working directory of the
shell.
· In list mode (with the -t flag), star(1,4) ignores all -C
options.
· In create mode (with the -c, -r and -u flag), star(1,4) walks
through all -C options and file(1,n) type arguments. While a
BSD derived tar(1) implementation goes back to the cur-
rent working directory after storing one file(1,n) argument
that immediately follows the -C option, star(1,4) changes the
directory only if(3,n) a new -C option follows. To emulate
the behavior of a BSD derived tar(1), add a -C . option
after the file(1,n) argument.
· In extract mode (with the -x, -n and -diff flag), star(1,4)
builds a pattern list together with corresponding direc-
tories from previous C=dir options and performs a
chdir(2) to the corresponding directory of a matching
pattern. All pat= options that do not follow a C=dir
option are interpreted as if(3,n) they were preceded by a -C .
option. See EXAMPLES for more information.
compress-program=name
Set a named(5,8) compress program. The program must compress in(1,8) a
pipe(2,8) when called without parameters and decompress when run with
the -d option in(1,8) a pipe. This option is otherwise similar to
the -z the -j the -Z and the -bz option.
-copydlinks
Try to recursively copy the content of linked directories
instead of creating the link. This is an experimental feature
that may help to unpack archives on DOS.
-copyhardlinks
This option allows to copy hardlinked targets rather than creat-
ing the link. It helps to extract tar files on systems that do
not implement hardlinks (e.g. BeOS).
-copylinks
This option allows to copy both, hard- and symlinked 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(1,4) twice as
star(1,4) cannot copy files that appear in(1,8) the archive later than a
symlink pointing to them.
-copysymlinks
This option allows to copy symlinked targets rather than creat-
ing a symbolic 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(1,4) twice as star(1,4)
cannot copy files that appear in(1,8) the archive later than a sym-
link(1,2) pointing to them.
-ctime If used with the list command, this lists ctime rather than
mtime if(3,n) the archive format is star(1,4), 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(1,n) by generat-
ing time(1,2,n) storms. You should not do this when in(1,8) multi user mode
because this may confuse programs like cron and the news system.
If used with the create command this changes the behavior of the
newer= option. Star, in(1,8) this case compares the ctime of all
files to the mtime of the stamp file(1,n) rather then comparing the
mtimes of both files.
-cumulative
A shorthand for -dump-cumulative. See -dump-cumulative for more
information.
-D Do not descend directories. Normally, star(1,4) descends the whole
tree if(3,n) it encounters a directory in(1,8) in(1,8) its file(1,n) parameters.
The option -D is in(1,8) effect by default if(3,n) the list=file(1,n) option is
used. If you like star(1,4) to descend directories found in(1,8) the list
file(1,n), use the -dodesc option (see below).
-d Do not store/create directories. Old versions of tar such as
published with the seventh edition of UNIX are not able to deal
with directories in(1,8) 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(1,8) optlst are:
help Print a summary of possible members of the diffopts
list.
! Invert the meaning of the following string. No comma
is needed after the exclamation mark.
not Invert the meaning of all members in(1,8) the diffopts list
i.e. exclude all present options from an initially
complete set(7,n,1 builtins) 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(1,n) permissions. With this option in(1,8) effect,
star(1,4) compares the low order 12 bits of the st_mode
field.
mode Same as perm.
type Compare file(1,n) type. Note that star(1,4) cannot compare the
file(1,n) type in(1,8) case of a hard link.
nlink Compare link(1,2) count on hardlinks. This only works if(3,n)
the archive is in(1,8) exustar format and contains star(1,4)'s
dump extensions.
uid Compare numerical user id of file.
gid Compare numerical group id of file.
uname(1,2) Compare ASCII version(1,3,5) of user id of file. The user
name is mapped via the file(1,n) /etc/passwd.
gname Compare ASCII version(1,3,5) of group id of file. The group
name is mapped via the file(1,n) /etc/group.
id Shorthand for: uid,gid,uname(1,2),gname. Compare all
user/group related info(1,5,n) of file. Note that this will
always find differences if(3,n) the source and target sys-
tem use different user or group mappings.
size Compare file(1,n) size. Note that star(1,4) cannot compare the
file(1,n) size in(1,8) case of a hard link.
data Compare content of file. If star(1,4) already found that
the size of the files differ, it will not compare the
content anymore. If the size of the files differ,
star(1,4) will always report different data.
cont Same as data.
rdev Compare major/minor numbers for device nodes.
hardlink Compare target of hardlinks.
symlink Compare target of symlinks. This evaluates the value
returned by the readlink(1,2)(2) call.
sparse Compare if(3,n) either both files are sparse or not. If
only one of both files is sparse, then a difference is
flagged. This only works with if(3,n) the archive format
is star(1,4), xstar, xustar, exustar, or gnutar.
atime Compare access(2,5) time(1,2,n) of file. This only works with if(3,n)
the archive format is star(1,4), xstar, xustar, exustar, or
pax.
mtime Compare modification time(1,2,n) of file.
ctime This only works with if(3,n) the archive format is star(1,4),
xstar, xustar, exustar, or pax.
lmtime Compare the modification time(1,2,n) of symbolic links. By
default, star(1,4) will not compare the modification time(1,2,n)
of symbolic links as most systems cannot set(7,n,1 builtins) the modi-
fication time(1,2,n) of symbolic links.
times Shorthand for: atime,mtime,ctime.
dir Compare the content of directories. This only works
if(3,n) the archive is in(1,8) exustar format and contains
star(1,4)'s dump extensions. Together with increased ver-
bose level (-vv) this will print a list of files that
are only in(1,8) the archive and a list of files that are
only on the current filesystem.
acl Compare access(2,5) control lists. This only works if(3,n) the
archive is in(1,8) exustar format and has been created with
star(1,4)'s -acl option. You need to specify the -acl
option in(1,8) addition when running the diff.
xattr Compare extended file(1,n) attributes. This only works if(3,n)
the archive is in(1,8) exustar format and has been created
with star(1,4)'s -xattr option. You need to specify the
-xattr option in(1,8) addition when running the diff.
fflags Compare extended file(1,n) flags. This only works if(3,n) the
archive is in(1,8) exustar format and has been created with
star(1,4)'s -xfflags option. You need to specify the
-xfflags option in(1,8) addition when running the diff.
If optlst starts with a ! the meaning of all members in(1,8) optlst
is inverted as with the not optlist member. In this case, star(1,4)
starts with a complete list that includes atime and lmtime.
Reasonable diff options to use when comparing against a copy of
a directory tree are diffopts=!atime,ctime,lmtime.
If diffopts are not specified, star(1,4) compares everything but the
access(2,5) time(1,2,n) of the files and the modification time(1,2,n) of symbolic
links.
-dirmode
If in(1,8) create mode (i.e. when storing files to archive), star(1,4)
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. The option
-dirmode should only be used if(3,n) the archive needs to be
extracted by an old tar implementation. If star(1,4) is used to
extract an archive that has been created with -dirmode the
directories will not get an old time(1,2,n) stamp unless the option -U
is used while extracting the archive.
-dodesc
Force star(1,4) to descend directories found in(1,8) a list=file. See
also the -D option above.
-dump Allows to create archives with the same number of attributes as
an archive that has been created with the level= option but
without the restrictions that apply to a true dump.
The resultant archive may be seen as a level-less dump which
includes similar attributes as a level 0 dump but may span more
than a single file(1,n) system and does not need to use a -C option.
It has been originally introduced to make it easier to implement
a star(1,4) version(1,3,5) that supports true incremental dumps, but it is
kept as it gives additional benefits. Star currently sets the
archive type to exustar and, in(1,8) addition archives more inode
meta data inside POSIX.1-2001 extended headers. See also level=
option and the section INCREMENTAL BACKUPS for more information
on true incremental dumps.
-dump-cumulative
instructs star(1,4) to perform incremental dumps relatively to the
last incremental dump of the same level. Incremental dumps with
a level higher than 0 are normally done relatively to the con-
tent of a previous dump with lower level. If incremental dumps
and restores are going to be used to synchronize filesystem con-
tent, every successive incremental dump will increase in(1,8) size if(3,n)
-dump-cumulative is not used. See section SYNCHRONIZING
FILESYSTEMS for more information.
dumpdate=name
Tells star(1,4) to use the mtime of the time(1,2,n) stamp file(1,n) name instead
of using the start time(1,2,n) of star(1,4). This is needed when star(1,4) is
run on file(1,n) system snapshots. If star(1,4) would use the the start
time(1,2,n) with snapshots, all files that have been modified between
the setup(2,8) of the snapshot and the start of star(1,4) would be missing
on the backup.
-dumpmeta
changes the behavior of star(1,4) in(1,8) incremental dump mode. If
-dumpmeta is used and only the inode change time(1,2,n) (st_ctime) of a
file(1,n) has been updated since the last incremental dump, star(1,4) will
archive only the meta data of the file(1,n) (e.g. uid, permissions,
...) but not the file(1,n) content. Using -dumpmeta will result in(1,8)
smaller incremental dumps, but files that have been created
between two incrementals and set(7,n,1 builtins) to an old date in(1,8) st_mtime
(e.g. as a result from a tar extract) will not be archived with
full content. Using -dumpmeta thus may result in(1,8) incomplete
incremental dumps, use with extreme care.
errctl= name
Use the file(1,n) name as error(8,n) control file. The reason for using
an error(8,n) control file(1,n) is to make star(1,4) quiet about error(8,n) condi-
tions that are known to be irrelevant on the quality of the ar-
chive or restore run. A typical reason to use error(8,n) control is
to suppress warnings about growing log files while doing a
backup on a life file(1,n) system.
The error(8,n) control file(1,n) contains a set(7,n,1 builtins) of lines, each starting
with a list of error(8,n) conditions to be ignored followed by white
space followed by a file(1,n) name pattern (see match(1) or pat-
match(3) for more information). If the file(1,n) name pattern needs
to start with white space, use a backslash to escape the start
of the file(1,n) name. It is not possible to have new line characters
in(1,8) the file(1,n) name pattern. Whenever an error(8,n) situation is
encountered, star(1,4) checks the lines in(1,8) the error(8,n) control file(1,n)
starting from the top. If the current error(8,n) condition is listed
on a line in(1,8) the error(8,n) control file(1,n), then star(1,4) checks whether
the pattern on the rest of the line matches the current file(1,n)
name. If this is the case, star(1,4) ignores the current error(8,n) con-
dition.
The list of error(8,n) conditions to be ignored may use one or more
(in(1,8) this case separated by a '|' character) identifiers from the
list below:
STAT Suppress warnings that star(1,4) could not stat(1,2)(2) a
file.
GETACL Suppress warnings about files on which star(1,4) had
problems to retrieve the ACL information.
OPEN Suppress warnings about files that could not be
opened.
READ Suppress warnings read(2,n,1 builtins) errors on files.
WRITE Suppress warnings write(1,2) errors on files.
READLINK Suppress warnings readlink(1,2)(2) errors on symbolic
links.
GROW Suppress warnings about files that did grow while
they have been archived.
SHRINK Suppress warnings about files that did shrink while
they have been archived.
MISSLINK Suppress warnings about files for which star(1,4) was
unable to archive all hard links.
NAMETOOLONG Suppress warnings about files that could not be
archived because the name of the file(1,n) is too long
for the archive format.
FILETOOBIG Suppress warnings about files that could not be
archived because the size of the file(1,n) is too big for
the archive format.
SPECIALFILE Suppress warnings about files that could not be
archived because the file(1,n) type is not supported by
the archive format.
GETXATTR Suppress warnings about files on that star(1,4) could not
retrieve the extended file(1,n) attribute information.
SETTIME Suppress warnings about files on that star(1,4) could not
set(7,n,1 builtins) the time(1,2,n) information during extraction.
SETMODE Suppress warnings about files on that star(1,4) could not
set(7,n,1 builtins) the access(2,5) modes during extraction.
SECURITY Suppress warnings about files that have been skipped
on extraction because they have been considered to
be a security risk. This currently applies to all
files that have a '/../' sequence inside when -..
has not been specified.
LSECURITY Suppress warnings about links that have been skipped
on extraction because they have been considered to
be a security risk. This currently applies to all
link(1,2) names that start with '/' or have a '/../'
sequence inside when -secure-links has been speci-
fied. In this case, star(1,4) tries to match the link(1,2)
name against the pattern in(1,8) the error(8,n) control file.
SAMEFILE Suppress warnings about links that have been skipped
on extraction because source and target of the link(1,2)
are pointing to the same file. If star(1,4) would not
skip these files, it would end up with removing the
file(1,n) completely. In this case, star(1,4) tries to match
the link(1,2) name against the pattern in(1,8) the error(8,n) con-
trol file.
BADACL Suppress warnings access(2,5) control list conversion
problems.
SETACL Suppress warnings about files on that star(1,4) could not
set(7,n,1 builtins) the ACL information during extraction.
SETXATTR Suppress warnings about files on that star(1,4) could not
set(7,n,1 builtins) the extended file(1,n) attribute information during
extraction.
If a specific error(8,n) condition is ignored, then the error(8,n) condition is
not only handled in(1,8) a silent way but also excluded from the error(8,n) sta-
tistics that are printed at the end of the star(1,4) run.
Be very careful when using error(8,n) control as you may ignore any error(8,n)
condition. If you ignore the wrong error(8,n) conditions, you may not be
able to see real problems anymore.
-F,-FF ...
Fast and simple exclude option for create mode. With one -F
argument, star(1,4) ignores all directories called SCCS and RCS.
With two -F arguments, star(1,4) in(1,8) addition ignores all files called
core errs a.out all files ending with .o. OBJ/. With three -F
arguments, star(1,4) ignores all sub trees starting from a directory
that includes a file(1,n) .mirror or .exclude and all object files
and files called core errs a.out all files ending with .o. With
four -F arguments, star(1,4) ignores all sub trees starting from a
directory that includes a file(1,n) .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(1,4) in(1,8) addition again excludes all directories
called SCCS and RCS.
-fifo Use a fifo to optimize data flow from/to tarfile. This option
is in(1,8) effect by default (it may be changed at compile time(1,2,n)).
The default fifo size is 8 MBytes on all platforms except Linux
versions that do not support mmap() (4 MB because kernels before
2.4 did not handle big shared memory areas) and Sun/mc68000 (1
MB). This will star(1,4) make even work on a tiny machine like a Sun
3/50. The fifo size may be modified with the fs= option. A rule
of dumb for the fifo size is to use more than the buffer size of
the tape drive and less(1,3) then half of the real memory of the
machine. A good choice would be to use a fifo size between 8
and 256 MB. This may increase backup speed up to 5% compared to
the speed achieved with the default fifo size. Note that with a
DLT drive that gives 12MB/s transfer rate, a fifo of 256 MB size
will keep the tape at least streaming in(1,8) units(1,7) of 20 seconds.
All options that start with the -f sequence are sensitive to
typo problems, see BUGS section for more information.
-fifostats
Print fifo statistics at the end of a star(1,4) run when the fifo has
been in(1,8) effect. All options that start with the -f sequence are
sensitive to typo problems, see BUGS section for more informa-
tion.
file(1,n)=tarfilename, f=tarfilename
Use tarfilename as the name for the tar archive. Currently up to
100 file(1,n)= options are possible. Specifying more then one file(1,n)=
option make sense in(1,8) multi volume mode. In this case star(1,4) will
use the next name in(1,8) the list every time(1,2,n) a media change is
needed. To make star(1,4) behave consistent with the single file(1,n)
case, star(1,4) loops over the list of known archive files. Note
that if(3,n) star(1,4) is installed suid root and the first tarfile is a
remote archive, only the connection to this archive will be cre-
ated with root privileges. After this connection has been
established as root, star(1,4) switches back to the id of the caller.
If any of the other archives in(1,8) the list is located on a differ-
ent host(1,5), star(1,4) will not be able to open(2,3,n) 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(1,4) is in(1,8) conjunction with pipes. If
star(1,4) is installed suid root or if(3,n) it has been called by root,
tarfilename may be in(1,8) remote syntax: user@host:filename as in(1,8)
rcp(1) even if(3,n) invoked by non root users. See SUID NOTES for
more information.
To make a file(1,n) local although it includes a colon (:), the file-
name must start with: '/', './' or '../'
Note that if(3,n) star(1,4) talks to an old rmt remote tape server that
does not support symbolic open(2,3,n) modes, it does not open(2,3,n) a remote
tape with the O_CREAT open(2,3,n) flag because this would be extremely
dangerous. If the rmt server on the other side is the rmt
server that comes with star(1,4) or the GNU rmt server, star(1,4) may use
the symbolic mode for the open(2,3,n) flags. Only the symbolic open(2,3,n)
modes allow to send(2,n) all possible open(2,3,n) modes in(1,8) a portable way to
remote tape servers.
It is recommended to use the rmt server that comes with star(1,4).
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(7,n,1 builtins) up in(1,8) /etc/default/rmt. All
options that start with the -f sequence are sensitive to typo
problems, see BUGS section for more information.
See ENVIRONMENT section for information on how to use ssh(1) to
create a remote tape server connection.
-force_hole
obsoleted by -force-hole
-force-hole
Try to extract all files with holes. This even works with files
that are created without the -sparse option. Star, in(1,8) this case
examines the content of the files in(1,8) the archive and replaces
writes to parts containing binary zeroes with seeks. This option
should be used with extreme care because you sometimes get in(1,8)
trouble when files get unattended holes. All options that start
with the -f sequence are sensitive to typo problems, see BUGS
section for more information.
-force_remove
obsoleted by -force-remove
-force-remove
Force to remove non writable files on extraction. By default,
star(1,4) will not overwrite files that are read(2,n,1 builtins) only. If this
option is in(1,8) effect, star(1,4) 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.
-force-restore
Force an incremental restore even if(3,n) the incremental dump is
only a partial dump. See -wtardumps, level= and section INCRE-
MENTAL BACKUPS 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.
fs-name=mount_point
Use mount_point when recording information in(1,8) /etc/tardumps and
when comparing against information in(1,8) /etc/tardumps for incre-
mental backups. This makes sense when backups are made using
file(1,n) system snapshots and allows /etc/tardumps and the archive
to contain the real name of the file(1,n) system instead of the tem-
porary mount(2,8) point that is used for the snapshot device.
H=headertype
See artype=headertype option. Note that POSIX.1-2001 defines an
option -H that follows symbolic links that have been encountered
on the command line. For this reason, the old star(1,4) option
H=headertype option may go away in(1,8) the future even though this
option has been in(1,8) use by cpio since 1989.
-h, -L Follow symbolic links as if(3,n) they were files. Normally star(1,4) will
not follow symbolic links but stores their values in(1,8) tarfile.
See also the -L option.
-hardlinks
In extract mode, this option tells star(1,4) to try to create a
hardlink whenever a symlink is encountered in(1,8) the archive. In
create mode, this option tells star(1,4) to try to archive a hardlink
whenever a symlink is encountered in(1,8) the file(1,n) 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(2,n,1 builtins) with HP-UX tar, this creates tar archives which violate
POSIX.1-1988. This option is only needed if(3,n) you like to use a
POSIX.1-1988 based archive format that does not include exten-
sions. If you use the xstar format, star(1,4) will use a base 256
extension that allows bigger major/minor numbers by default, if(3,n)
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(1,4) will not exit(3,n,1 builtins) if(3,n) a header with a bad checksum is
found but search for the next valid header.
-j run the input or output through a bzip2 pipe(2,8) - see option -z -Z
and -bz below. As the -bz the -j the -Z and the -z option are
non standard, it makes sense to omit the -bz the -j the -Z and
the -z options inside shell scripts if(3,n) you are going to extract
a compressed archive that is located inside a plain file(1,n) as star(1,4)
will auto(5,8) detect compression and choose the right decompression
option to extract.
-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(3,n) tarfile contains a
more recent version(1,3,5) of the corresponding file.
See SECURITY NOTES for more information.
-L, -h Follow symbolic links as if(3,n) they were files. Normally star(1,4) will
not follow symbolic links but stores their values in(1,8) tarfile.
See also the -h option.
-l Do not print a warning message if(3,n) not all links to hard linked
files could be dumped. This option is evaluated in(1,8) 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
-l will enable warning messages when not all links could be
archived.
level=dumplevel
Set level for incremental dumps. This option is used to switch(1,n)
star(1,4) into true incremental dump mode.
In true incremental dump mode, a -C option which is followed by
the name a mount(2,8) point and a dot ('.') as starting directory
name is required. Only a single file(1,n) system may be handled at a
time. If the directory followed by the -C option is not refer-
ring to a root directory of a file(1,n) system, the dump is called a
partial dump. If the directory followed by the -C option is
referring to a root directory of a file(1,n) system and no other
restrictions apply that exclude certain files from the dump, the
dump is called a full dump.
By default, the tardumps database is not written. See also the
tardumps=name and -wtardumps options and the section INCREMENTAL
BACKUPS for more information.
-link-dirs
When in(1,8) create mode, try to find hard linked directories. Using
-link-dirs will force star(1,4) to keep track of all directories that
will go into the archive and thus causes a lot more memory to be
allocated than in(1,8) the default case.
If you like to extract a cpio archive that contains hard linked
directories, you also need to specify -link-dirs in(1,8) extract or
diff mode. This is needed because many cpio implementations
create buggy archives with respect to hard links. If star(1,4) would
look(1,8,3 Search::Dict) for hard linked directories in(1,8) all cases, it would detect
many pseudo hard links to directories. Use -link-dirs with care
if(3,n) you extract cpio archives.
Note that not all filesystem allow to create hard links to
directories. Also note that even though a non-root user is able
detect and archive hard linked directories, all known operating
systems require the extraction to be done as root in(1,8) order to be
able to create or remove hard links to directories. For this
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(1,4) 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(1,n) filename must contain a list of filenames, each on a sepa-
rate line. This option implies the -D option. To force star(1,4) to
descend directories, use the -dodesc option in(1,8) this case.
-lowmem
Try to run with reduced memory requirements. This causes star(1,4)
to default to 1 MB of FIFO memory. Instead of allocating memory
to hold the directory content and reading the directory at once,
star(1,4) reads the directory name by name. This may cause star(1,4) to
close(2,7,n) the directory if(3,n) it rans out of file(1,n) descriptors because
of deeply nested directories. If a directory then does not sup-
port telldir(3)/seekdir(3), star(1,4) will fail.
-M, -xdev
Do not descend mount(2,8) points. This is useful when doing backups
of complete file(1,n) systems. See NOTES for more information.
-m Do not restore access(2,5) and modification time. (Access time(1,2,n) is
only available if(3,n) star(1,4) is reading star(1,4), xstar, xustar, exustar,
or pax archives). If star(1,4) extracts other archive types, the -m
flag only refers to the modification time.
-match-tree
If in(1,8) create mode a pattern does not match a directory, and
-match-tree has been specified, the whole directory tree is
excluded from the archive and from further directory scans. By
default, star(1,4) excludes the directory but still recursively scans
the content of this directory as complex patterns could allow
files inside the directory tree to match. Using -match-tree
allows to efficiently exclude whole trees from scanning. This
helps to avoid scannings directory trees that are on remote file(1,n)
systems or contain excessive bad blocks.
maxsize=#
Do not store files in(1,8) tarfile if(3,n) they are bigger than #. See
bs= for the possible syntax. By default, the number is multi-
plied by 1024, so the value counts in(1,8) units(1,7) 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 In create mode, -meta causes star(1,4) to archive all meta data of
the file(1,n) (e.g. uid, permissions, ...) but not the file(1,n) content.
In extract mode, it causes star(1,4) to restore all meta data but not
the file(1,n) content. In addition, in(1,8) extract mode no plain file(1,n),
special file(1,n) or directory will be created. Meta files are
needed to support incremental backups.
Warning: Do not try to extract star(1,4) archives containing meta
files using other tar implementations if(3,n) they are not aware of
the meta file(1,n) extensions of star(1,4). 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(1,8) the POSIX
standard that tells tar implementations to treat all unknown
file(1,n) types as if(3,n) they were plain files. As meta files are needed
for incremental backups, I am looking for people and companies
who like to support me to be able to add the meta file(1,n) concept
to the POSIX.1-2005 standard.
-modebits
This options allows you to create tar archives that include more
than 12 bits from st_mode. Note this create tar archives that
violate POSIX but some tar implementations insist in(1,8) reading
such nonstandard archives.
-multivol
Switch to multi volume mode. In multi volume mode, there will
be no logical EOF marker written to the end of a single tape. If
-multivol is used in(1,8) read(2,n,1 builtins) mode, a hard EOF on input (if(3,n) not pre-
ceded by a logical EOF) triggers a medium change operation.
Specifying -multivol tells star(1,4) to split(1,n) files across volumes if(3,n)
needed. This way, a virtual(5,8) archive is created that spans more
than one medium. Multi volume mode is needed whenever it is not
possible to split(1,n) the archiving or extracting into several logi-
cally independent tasks. This is true for e.g. incremental
dump/restore operations where inode numbers need to be traced
for the whole task.
When tsize=# has been specified, but star(1,4) is not in(1,8) multi volume
mode, files cannot be split(1,n) across volumes.
When -multivol has been specified in(1,8) create mode together with
tsize=# then a media change is initiated exactly after an amount
of tsize data has been written. When -multivol has been speci-
fied in(1,8) create mode and tsize=# has not been specified, then the
medium change is triggered by a EOT condition from writing the
medium. This allows to use media where the size cannot be known
in(1,8) advance (e.g. tapes with build in(1,8) compression); it does not
work if(3,n) the EOT condition is not returned in(1,8) sync(1,2,8) with the
related write(1,2) operation. For this reason, it is expected that
data buffering inside a device driver cannot be used.
Depending on the selected archive format, star(1,4) writes a volume
header at the beginning of a new medium. This medium header
allows to verify(1,8) the correct volume