1STAR(1)                     Schily´s USER COMMANDS                     STAR(1)
2
3
4

NAME

6       star - unique standard tape archiver
7

SYNOPSIS

9       star  command [options] [-find] file1 ... filen [find_expr]
10       ustar command [options] [-find] file1 ... filen [find_expr]
11       tar   command [options]         file1 ... filen
12       star  -copy   [options] [-find] file1 ...  [f_expr] directory
13       star  -copy   [options] -C from_directory . to_directory
14       star  cli=name   ...
15

DESCRIPTION

17       Star is a very fast tar(1) like tape archiver with improved functional‐
18       ity.  It supports unlimited path name lengths (up to 8 GB) in all cases
19       that use suitable archive types.
20
21       Star  archives  and  extracts  multiple files to and from a single file
22       called a tarfile.  A tarfile is usually a magnetic tape, but it can  be
23       any  file.   In all cases, appearance of a directory name refers to the
24       files and (recursively) subdirectories of that directory.
25
26       Star's actions are controlled by the mandatory command flags  from  the
27       list below.  The way star acts may be modified by additional options.
28
29       Note  that  unpacking  tar archives may be a security risk because star
30       may overwrite existing files.  See SECURITY NOTES for more information.
31
32       If the first argument is in the form cli=name, the command line  inter‐
33       face is selected to match name.  See section CLI SELECTION below.
34

FEATURES

36       Star  includes  the  first free implementation of POSIX.1-2001 extended
37       tar headers. The POSIX.1-2001 extended tar headers define a  new  stan‐
38       dard  way  for going beyond the limitations of the historic tar format.
39       They allow (among others) to archive all UNIX time stamps in sub-second
40       resolution,  files of arbitrary size and filenames without length limi‐
41       tation using UNICODE UTF-8 coding for best exchange compatibility.
42
43       Star by default uses a fifo to optimize data flow  from/to  tape.  This
44       results  in  a  normally  streaming  tape during the whole backup.  See
45       -fifo and fs= option to get information on how to find  the  best  fifo
46       size.
47
48       Star includes a pattern matcher to control the list of files to be pro‐
49       cessed. This gives a convenient interface for archiving  and  restoring
50       complex  lists  of files. In conjunction with the -w flag it is easy to
51       merge a tar archive into an existing file tree. See also -U option.  In
52       create  mode  use  the  pat= option to specify either select or exclude
53       patterns (depending on the -V flag). In extract or list mode  all  file
54       type  arguments  are  interpreted as select patterns while the patterns
55       specified with the pat= option may be used as select  or  exclude  pat‐
56       terns  (depending  on  the -V flag).  Have a look at the description of
57       the -C option to learn how to fetch files from a  list  of  directories
58       (in  create  mode)  or to distribute files to a list of directories (in
59       extract mode).  A substitute option allows ed(1) like pattern substitu‐
60       tion in file names.
61
62       Star includes support for incremental backup and restore similar to the
63       BSD commands dump(1) and restore(1) that are known  as  ufsdump(1)  and
64       ufsrestore(1) on Solaris.
65
66       Star  includes an enhanced function that is similar to the find(1) com‐
67       mand (see sfind(1)).  This function  is  implemented  in  libfind.   It
68       allows  to use find expressions, even in extract or list mode, directly
69       on the content on an archive.  The extensions to find(1) allow to  mod‐
70       ify the file metadata.
71
72       Star includes a sophisticated diff command that is able to compare file
73       content and meta data.  Several  diff  options  allow  user  tailorable
74       functionality.   Star won't show you differences you are not interested
75       in.  Check the diffopts= option for more details.
76
77       Star has no limitation on filename length. Pathnames and  linknames  up
78       to  PATH_MAX  (typically 1024 bytes) may be archived by most tar imple‐
79       mentrations.  Star allows to archive path names up to 8  GB  on  modern
80       platforms.
81
82       Star deals with all 3 times, available for files on UNIX systems if the
83       archive format is either chosen from the star specific formats or is  a
84       format that uses POSIX.1-2001 extended headers.  This is either done in
85       second resolution by using  a  star  specific  POSIX.1-1988  compatible
86       extension  or  in  sub second resolution by using POSIX.1-2001 extended
87       headers.  Star is able to store and restore all 3 times  (mtime,  atime
88       and  even  ctime).  On  Solaris 2.x systems - if run as root -, star is
89       able to do backups without changing any of the 3 the times.
90
91       If used with the H=ustar option, or if called as ustar or tar while the
92       H=headertype option is not used, star is 100% POSIX compliant.
93
94       Star's default format (if called as star) is xstar and is as posix com‐
95       pliant as possible. Enhancements to the standard that  prevent  correct
96       extraction  of  single  files when using a different tar implementation
97       that is only POSIX.1-1988 compliant may occur,  but  they  only  affect
98       single  files with a pathname that is longer than 100+130 chars or when
99       archiving sparse files with the -sparse option in  effect.   All  other
100       files will extract correctly.  See the description for the H=headertype
101       option below for more information on archive formats and  possible  ar‐
102       chive interchange problems.
103
104       Star makes it easy to repair corrupted filesystems. After a fsck -y has
105       been run on the filesystem, star is able to restore  only  the  missing
106       files automatically.  Use then star -diff to check for differences (see
107       EXAMPLES for more information).
108
109       Star automatically recognizes the type of the archive.  Star  therefore
110       is able to handle features and properties of different archive types in
111       their native mode, if it knows about the peculiarities of  the  archive
112       type.   See the H=headertype option for more details.  To be able to do
113       this, star adds hidden fingerprints to the archive header  that  allows
114       to  recognise  all star specific archive formats. The GNU tar format is
115       recognised by the way it deviates from the standard.
116
117       Star automatically recognizes and handles byte swapped archives.  There
118       is no option to manually control byte swapping.
119
120       Star  automatically  recognizes  and handles compressed archives inside
121       plain files.
122
123       Star is able to archive and restore  Access  Control  Lists  for  files
124       using POSIX.1-2001 extended headers.
125

CLI SELECTION

127       If  the first argument is in the form cli=name, the command line inter‐
128       face is selected to match one of the supported CLI variants.  The  fol‐
129       lowing interfaces are supported:
130
131       star           The  star  interface  selects the command line interface
132                      described in this manual page.
133
134       suntar         The suntar interface selects the command line  interface
135                      of  the  classical UNIX tar command as described in sun‐
136                      tar(1).
137
138       gnutar         The gnutar interface selects the command line  interface
139                      of the GNU tar command as described in gnutar(1).
140
141       pax            The  pax interface selects the command line interface of
142                      the POSIX pax command as described in spax(1).
143
144       cpio           The cpio interface selects the command line interface of
145                      the   classical   UNIX  cpio  command  as  described  in
146                      scpio(1).
147

COMMAND

149       In native mode, star is compatible to the command line syntax of a typ‐
150       ical  POSIX command and for this reason expects commands and options to
151       start with a single dash (-). In this case, commands and options may be
152       specified  separately,  all  boolean  or  increment type options may be
153       specified either separately or combined.
154
155       For compatibility with GNU programs,  long  options  may  alternatively
156       start with a double dash.
157
158       In  compatibility  mode to POSIX tar, star expects commands and options
159       to appear as one single string that does not start  with  a  dash.   In
160       POSIX tar compatibility mode, additional non POSIX options may be spec‐
161       ified but must appear after the POSIX options and their args  and  need
162       to start with a dash.
163
164       -c     Create  a  new  tarfile  and write named files into it.  Writing
165              starts at the beginning of tarfile.  See -v option for  informa‐
166              tion on how to increase verbosity while the archive is written.
167
168              The  Option  -c may be used together with -diff and -t.  In this
169              case, the whole command line has to be similar  to  the  command
170              line for the -copy mode.
171
172       -copy  Copy  named files to the target directory which is the last file
173              type argument.  The target directory must exist.  The  shorthand
174              -cx  instead  of  -copy  is  not allowed because this could be a
175              result of a typo.
176
177              If the option -diff has been specified in  addition,  star  per‐
178              forms  a  one  pass  directory  tree  compare instead of copying
179              files.  The shorthand -c -diff instead of -copy  -diff  is  also
180              allowed.
181
182              On  operating systems with slow file I/O (such as Linux with any
183              filesystem or platforms with  Copy  on  Write  filesystems  like
184              ZFS),  it  may help to use -no-fsync in addition (see also ENVI‐
185              RONMENT and FILES), but then star is unable to detect all  error
186              conditions; so use with care.
187
188              If  the  option -t has been specified in addition, the last file
189              type argument is not a target directory and star is performing a
190              one  pass listing instead of copying files.  This makes sense as
191              the listing from star may be better  readable  than  the  output
192              from  ls -lR.  The shorthand -c -t or -ct instead of -copy -t is
193              also allowed.
194
195              The job is by default done  in  the  best  archive  mode.   This
196              implies  that  it  defaults  to  H=exustar -dump.  When in -copy
197              mode, star forks into two processes and data  exchange  is  done
198              via the shared memory from the FIFO.  This gives the best possi‐
199              ble performance.  Without FIFO, the -copy mode will not work.
200
201              The list= option, patterns and substitutions apply only  to  the
202              create side of the copy command.
203
204       -diff  Compare the content and the attributes of the files from the ar‐
205              chive in tarfile to the filesystem.  This may also  be  used  to
206              compare  two  file trees in the filesystem.  If you use a set of
207              diffopts that fits your needs, it will give - in many cases -  a
208              more  readable  output  than  diff  -r.   If you use star's dump
209              extensions for the tar archive, the -diff option allows to  find
210              even  if the directory in the file tree contains more files than
211              the archive. This way, it is possible to compare all  properties
212              of  two  file  trees in one run.  See diffopts for more details.
213              Adding one or more -v options increases the verbosity. With  -vv
214              and  above,  the  directory  content is compared also if star is
215              reading a tar archive that has been created in -dump mode.
216
217       -n     No extraction. Show what star would do, in case the  -x  command
218              had been specified.
219
220       -r     Replace  files in a tarfile.  The named files are written to the
221              end of tarfile.  This implies that later, the appropriate  files
222              will be found more than once on the tarfile.
223
224       -t     Table of contents.  List the contents of the tarfile.  If the -v
225              flag is used, the listing is similar to the format of ls -l out‐
226              put.   With  this option, the flags -a, -atime and -ctime have a
227              different meaning if the archive  is  in  star,  xstar,  xustar,
228              exustar,  or pax/epax format.  The option -a or -atime lists the
229              access time instead of the modification time, the option  -ctime
230              lists  the  file creation time instead of the modification time.
231              The option -tpath may be used in addition to modify  the  output
232              so it may be used in shell scripts.
233
234       -u     Update  a  tarfile.   The  named files are written to the end of
235              tarfile if they are not already there or if the files are  newer
236              than  the  files  of the same name found in the archive.  The -r
237              and -u command only work if the tar archives is a  regular  file
238              or if the tar archive is an unblocked tape that may backspace.
239
240       -x     Extract  the named files from the tarfile.  If no filename argu‐
241              ment or pattern is specified, the entire content of the  tarfile
242              is  restored.  If the -U flag is not used, star extracts no file
243              which is older than the corresponding file on disk.
244
245              On operating systems with slow file I/O (such as Linux with  any
246              filesystem  or  platforms  with  Copy  on Write filesystems like
247              ZFS), it may help to use -no-fsync in addition (see  also  ENVI‐
248              RONMENT  and FILES), but then star is unable to detect all error
249              conditions; so use with care.
250
251       Except for the shorthands documented above, exactly one of the commands
252       above must be specified.
253
254       If  one  or more patterns or substitution commands have been specified,
255       they apply to any of the command listed above.  In copy mode, all  pat‐
256       terns and substitute commands apply to the create side.
257
258

OPTIONS

260       -help  Print a summary of the most important options for star(1).
261
262       -xhelp Print a summary of the less important options for star(1).
263
264       -/     Don't  strip  leading slashes from file names when extracting an
265              archive.  Tar archives containing absolute pathnames are usually
266              a  bad  idea.  With other tar implementations, they may possibly
267              never be extracted without clobbering existing files.  Star  for
268              that  reason,  by  default strips leading slashes from filenames
269              when in extract mode.  As it may be impossible to create an  ar‐
270              chive  where  leading slashes have been stripped while retaining
271              correct path names, star does not strip leading slashes in  cre‐
272              ate mode.
273
274              See SECURITY NOTES for more information.
275
276       -..    Don't  skip  files  that  contain /../ in the name. Tar archives
277              containing names with /../ could be used to compromise the  sys‐
278              tem.  If  they  are unpacked together with a lot of other files,
279              this would in most cases not even be noticed. For  this  reason,
280              star  by default does not extract files that contain /../ in the
281              name if star is not in interactive mode (see -w option).
282
283              See SECURITY NOTES for more information.
284
285       -7z    run the input or output through a p7zip pipe  -  see  option  -z
286              below.
287
288              Note that the p7zip program currently does not operate on a pipe
289              but on a /tmp file copy and  thus  limits  the  maximum  archive
290              size.
291
292
293       -0
294
295       -1
296
297       -2
298
299       -3
300
301       -4
302
303       -5
304
305       -6
306
307       -7     Select  an archive entry from /etc/default/star.  The format for
308              the  archive  entries   is   the   same   as   the   format   in
309              /etc/default/tar in Solaris.
310
311       -acl   Handle  Access  Control  List  (ACL)  information  in create and
312              extract mode.  If -acl has been specified,  star  is  in  create
313              mode  and the header type is exustar, star will add ACL informa‐
314              tion to the archive using  POSIX.1-2001  extended  headers.   If
315              -acl  has  been specified and star is in extract mode, star will
316              try to restore ACL information. If there is no  ACL  information
317              for  one  or  all  files in the archive, star will clear the ACL
318              information for the specific file.  Note that if  -acl  has  not
319              been  specified, star will not handle ACL information at all and
320              files may inherit ACL information from the  parent  directories.
321              If  the -acl option has been specified, star assumes that the -p
322              option has been specified too.
323
324              Star currently supports ACLs from the withdrawn  POSIX.1e  draft
325              and NFSv4 ACLs.  To check which ACL flavors are supported on the
326              current platform, call star -version.   Whether  ACLs  from  the
327              withdrawn  POSIX.1e  draft  can  be  converted  into  NFSv4 ACLs
328              depends on the local ACL support library.
329
330       artype=headertype
331              Generate a tape archive in headertype format.  If this option is
332              used  in  extract/list  mode  this  forces star to interpret the
333              headers to be of type headertype.  As star even  in  case  of  a
334              user  selected  extract  archive format does format checking, it
335              may be that you will not be able to unpack  a  specific  archive
336              with  all possible forced archive formats. Selecting the old tar
337              format for extraction will always work though.  Valid  parameter
338              for headertype are:
339
340              help      Print a help message about possible header types.
341
342              v7tar     Old  UNIX V7 tar format.  This archive format may only
343                        store plain files.  Pathnames or linknames longer than
344                        99 chars may not be archived.
345
346                        If  the  v7tar format has been selected, star will not
347                        use enhancements to the historic UNIX V7  tar  format.
348                        File  size  is  limited  to 2 GB - 2 bytes, uid/gid is
349                        limited to 262143.  Sparse files  will  be  filled  up
350                        with zeroes.
351
352              tar       Old BSD UNIX tar format.  This archive format may only
353                        store plain files,  directories  and  symbolic  links.
354                        Pathnames or linknames longer than 99 chars may not be
355                        archived.  See also the -d option as a  note  to  some
356                        even older tar implementations.
357
358                        If the tar format has been selected, star will not use
359                        enhancements to the historic tar format.  File size is
360                        limited  to  2  GB  -  2  bytes, uid/gid is limited to
361                        262143.  Sparse files will be filled up with zeroes.
362
363              star      Old star standard format. This is  an  upward/downward
364                        compatible enhancement of the old (pre Posix) UNIX tar
365                        format.  It has been introduced in 1985 and  therefore
366                        is not Posix compliant.  The star format allows to ar‐
367                        chive special files (even sockets) and records  access
368                        time  and creation time besides the modification time.
369                        Newer versions of the old star format allow very  long
370                        filenames  (100+155 chars  and above), linknames > 100
371                        chars and sparse files (if  -sparse  is  used).   This
372                        format  is able to copy the device nodes on HP-UX that
373                        have 24 bits in the minor device number, which is more
374                        then   the   21   bits  that  are  possible  with  the
375                        POSIX-1003.1-1988 archive format.
376
377                        The nonstandard extensions are located  in  the  space
378                        between  the link name and the POSIX file name prefix.
379                        As the star format does not use a POSIX magic  string,
380                        the  extensions  do  not  interfere with the POSIX tar
381                        formats.  The last 4 bytes of the tar  header  in  the
382                        star archive format contain a 'tar\0' signature.
383
384                        This archive format supports very long path names.
385
386              gnutar    This  is  a commonly used, but unfortunately not Posix
387                        compliant (although designed after  1987)  enhancement
388                        to  the  old  tar  format.  The gnutar format has been
389                        defined between 1989 and 1994.  Do not use the  gnutar
390                        archive  format  unless  you want to create an archive
391                        for a target system that is known  to  have  only  the
392                        gnutar  program  available.  The gnutar archive format
393                        violates basic rules for any (even the  historic)  tar
394                        archive  format,  in  special  when  sparse  files are
395                        archived using the -sparse option.
396
397                        GNU tar is not able to extract files  with  with  long
398                        path names, but under some conditions creates archives
399                        with long path names. We therefore do  not  limit  the
400                        creation of gnutar archives with long path names.
401
402                        Using  the  gnutar  archive  format causes a high risk
403                        that the resulting archive may only be read by  gnutar
404                        or  by star.  The implementation of the gnutar archive
405                        format within star is not complete, but sufficient for
406                        most gnutar archives.  See NOTES for more information.
407
408                        This archive format supports very long path names.
409
410              ustar     IEEE/Posix1003/IEC-9945-1-1988  Standard  Data  Inter‐
411                        change format.  With this option in effect, star  will
412                        generate  100%  POSIX.1-1988  compliant  tar archives.
413                        Files with pathnames  longer  than  100+155  chars  or
414                        linknames  longer  than 100 chars may not be archived.
415                        If star is called as ustar the default archive  format
416                        is ustar.
417
418                        If  the  ustar format has been selected, star will not
419                        use enhancements to the POSIX.1-1988 tar  format,  the
420                        archive  will  be  strictly  conforming.  File size is
421                        limited to 8 GB,  uid/gid/major/minor  is  limited  to
422                        2097151.  Sparse files will be filled up with zeroes.
423
424              pax       The  IEEE/Posix1003/IEC-9945-1-1988  successor  is the
425                        POSIX-1003.1-2001 Standard  Data  Interchange  format.
426                        It is called the pax archive format.
427
428                        If the pax format has been selected, star will not use
429                        enhancements to the POSIX.1-2001 tar format,  the  ar‐
430                        chive  will  be  strictly  conforming.   File  size is
431                        unlimited,   uid/gid/uname/gidname    is    unlimited,
432                        major/minor  is limited to 2097151.  Sparse files will
433                        be filled up with zeroes.
434
435                        This archive format supports very long path names.
436
437              epax      A format similar to the pax  format  but  with  forced
438                        POSIX.1-2001  extended headers.  This enforces stimes‐
439                        tamps with nanosecond resolution in the archive.
440
441                        This archive format supports very long path names.
442
443              xstar     The extended standard tar format has  been  introduced
444                        in  1994.   Star  uses the xstar format as default ar‐
445                        chive format.  This is an  upward/downward  compatible
446                        enhancement  of the IEEE/Posix1003/IEC-9945-1 Standard
447                        Data Interchange format.  It allows among others  very
448                        long  filenames  (100+130 chars and above) and records
449                        access time and creation time.  Sparse files  will  be
450                        archived correctly (if -sparse is used).
451
452                        The  access  time  and creation time are stored at the
453                        end of the POSIX file name  prefix  (this  limits  the
454                        prefix  to 130 chars).  These extensions do not inter‐
455                        fere with the POSIX standard as the fields  for  mtime
456                        and  ctime  field  are always separated from the POSIX
457                        file name prefix by a null byte.  The last 4 bytes  of
458                        the tar header contain a 'tar\0' signature.
459
460                        The  xstar  format  is the default format when star is
461                        neither called as tar nor called as ustar.
462
463                        This archive format supports very long path names.
464
465              xustar    A new format introduced 1998, that omits  the  'tar\0'
466                        signature  at  the end of the tar header. It is other‐
467                        wise identical to  the  xstar  format.   As  some  tar
468                        implementations do not follow the POSIX rules and com‐
469                        pute the checksum for less than 512 bytes of  the  tar
470                        header,  this  format  may help to avoid problems with
471                        these broken tar implementations.  The main other dif‐
472                        ference  to the xstar format is that the xustar format
473                        uses POSIX.1-2001 extended headers to overcome limita‐
474                        tions  of the historic tar format while the xstar for‐
475                        mat uses proprietary extensions.  The xustar format is
476                        the default format when star is called as tar.
477
478                        File   size  is  unlimited,  uid/gid/uname/gidname  is
479                        unlimited, major/minor  is  unlimited.   Sparse  files
480                        will be archived correctly (if -sparse is used).
481
482                        This archive format supports very long path names.
483
484              exustar   A  format similar to the xustar format but with forced
485                        POSIX.1-2001 extended headers.  If this format is used
486                        together  with  the  -acl  option, star records Access
487                        Control Lists (ACLs) in POSIX.1-2001 extended headers.
488
489                        The exustar format allows to archive  all  file  types
490                        but it does not archive more than the POSIX.1-1988 set
491                        by default.  If the -dump option is used or if star is
492                        otherwise  on  dump mode, star archives all file types
493                        and in addition archives more meta data then usual.
494
495                        File  size  is  unlimited,  uid/gid/uname/gidname   is
496                        unlimited,  major/minor  is  unlimited.   Sparse files
497                        will be archived correctly (if -sparse is used).
498
499                        This archive format supports very long path names.
500
501              suntar    The extended header format  found  on  Solaris  7/8/9.
502                        This  format is similar to the pax format but does not
503                        handle atime and ctime and in addition uses 'X' as the
504                        typeflag for the extended headers instead of the stan‐
505                        dard 'x'.
506
507                        File  size  is  unlimited,  uid/gid/uname/gidname   is
508                        unlimited,  major/minor  is  unlimited.   Sparse files
509                        will be filled up with zeroes.
510
511              bin       The cpio UNIX V7 binary format.  This is a format with
512                        big  interoperability problems. Try to avoid this for‐
513                        mat.  It is only present to  make  the  scpio  command
514                        SVr4 compliant.
515
516              cpio      The  POSIX.1-1988  cpio format. This format uses octal
517                        ascii headers. A similar format is created by  calling
518                        cpio  -o  -c on pre SYSVr4 systems and by calling cpio
519                        -o -Hodc on SYSVr4  systems.   The  POSIX.1-1988  cpio
520                        format  allows a file name length up to 262142 charac‐
521                        ters and allows to archive nearly any file type.  File
522                        size  is limited to 8 GB, uid/gid/st_dev is limited to
523                        262143.  The way major and minor  device  numbers  are
524                        stored  inside  the  st_dev  field  is  implementation
525                        dependent.
526
527                        Even though this archive  format  is  covered  by  the
528                        POSIX.1-1988 standard, it has a lower portability than
529                        the ustar format. Try to avoid the cpio  archive  for‐
530                        mat.
531
532              odc       This archive format is similar to the The POSIX.1-1988
533                        cpio format but the file name length is limited to 255
534                        characters  and  the  socket file type is not allowed.
535                        This archive format has been introduced to  allow  non
536                        POSIX cpio implementations such as the cpio program on
537                        SYSV to accept the archive. Use this  format  whenever
538                        you  are  not sure if the target system offers a fully
539                        POSIX compliant cpio program.
540
541                        Even though this archive  format  is  covered  by  the
542                        POSIX.1-1988 standard, it has a lower portability than
543                        the ustar format. Try to avoid the odc archive format.
544
545              asc       Tell star to create a cpio archive in the ascii format
546                        that is created with cpio -o -c on SYSVr4 systems.  It
547                        uses extended (32 bit) numbers for  uid's,  gid's  and
548                        device  numbers  but  limits the file size to 4 GB - 2
549                        bytes although the format has been specified after the
550                        POSIX.1-1988  cpio  format.   Try to avoid the asc ar‐
551                        chive format because of its limited portability.
552
553              crc       This format is similar to the asc cpio format  but  in
554                        addition  uses  a  simple  byte based 32-bit checksum.
555                        Hence the archive type name CRC as  used  by  AT&T  is
556                        misleading.   Try  to  avoid  the  crc  archive format
557                        because of its limited portability.
558
559
560              All tar archive formats may be interchanged if the archive  con‐
561              tains  no  files  that  may not be archived by using the old tar
562              format.  Archives in the xstar format may be  extracted  by  any
563              100% POSIX compliant tar implementation if they contain no files
564              with pathnames > 100+130 chars and if  they  contain  no  sparse
565              files that have been archived by using the -sparse option.
566
567
568       -ask_remove
569              obsoleted by -ask-remove
570
571       -ask-remove
572              Ask  to  remove  non  writable files on extraction.  By default,
573              star will not overwrite files  that  are  read  only.   If  this
574              option  is  in  effect,  star  will ask whether it should remove
575              these files to allow the extraction of a file in  the  following
576              way:
577
578                     remove 'filename' ? Y(es)/N(o) :
579
580       -atime, -a
581              Reset  access  time  of files after storing them to tarfile.  On
582              Solaris 2.x, (if invoked by root) star uses the _FIOSATIME ioctl
583              to  do  this.  This  enables  star  not to trash the ctime while
584              resetting the atime of the files.  If the -atime option is  used
585              in  conjunction  with  the  list command, star lists access time
586              instead of modification time. (This works  only  in  conjunction
587              with  the  star,  xstar,  xustar, exustar, and with the pax/epax
588              format.)  Another option to retain the access time for  the  the
589              files  that  are going to be archives is to readonly mount a UFS
590              snapshot and to archive files from the mount point  of  the  UFS
591              snapshot.
592
593       -B     Force  star  to  perform multiple reads (if necessary) to fill a
594              block.  This option exists so that star can work across the Eth‐
595              ernet,  since  pipes and sockets return partial blocks even when
596              more data is coming.  If star uses stdin as archive  file,  star
597              behaves  as  if it has been called with the -B option.  For this
598              reason, the option -B in practice is rarely needed.
599
600       b=#    Set the block size for tape operations.  See option blocks=#.
601
602       -block-number
603              Print the archive block number (archive offset  /  512)  at  the
604              beginning  of  each  line  when  in verbose mode. This allows to
605              write backup scripts that archive the offsets for files and that
606              use
607
608                   mt fsr blockno
609
610              to  skip to the tape block number of interest in a fast way if a
611              single file needs to be restored.
612
613              Since the numbers printed by the -block-number option are  based
614              on  a block size of 512 bytes and the tape block size is usually
615              larger, the tape block number for the mt fsr command needs to be
616              computed to honor the tape blocking factor.
617
618       blocks=#, b=#
619              Set  the  blocking  factor  of  the tarfile to # times 512 bytes
620              (unless a different multiplication factor has been  specified  -
621              see  bs=  option for possible multiplication factors).  Changing
622              the blocking factor only makes sense when the archive is located
623              on  a  real  tape device or when the archive is accessed via the
624              remote tape protocol (see f= option below).  The default  is  to
625              use  a  blocking  factor  of 20 i.e.  10 kBytes.  Increasing the
626              blocksize will speed up the backup.  For portability  with  very
627              old  tar  implementations (pre BSD 4.2 or pre AT&T SVR4), block‐
628              size should not be more than 10 kBytes.  For  POSIX.1-1988  com‐
629              patibility,  blocksize  should  be  no more than 10 kBytes.  For
630              POSIX.1-2001 compatibility, blocksize should  be  no  more  than
631              32 kBytes.  Most systems also have a hardware limitation for the
632              blocksize, 32 kBytes and 63 kBytes are  common  limits  on  many
633              systems.   The upper limit in any case is the size of the buffer
634              RAM in the tape drive.  Make a test if you  want  to  make  sure
635              that  the  target system will handle the intended blocksize.  If
636              you use star for data exchange via tape, it is a  good  idea  to
637              use  a blocksize of 10 kBytes unless you are sure that the read‐
638              ing system will handle a larger blocksize.  If you use star  for
639              backup  purposes  with recent hardware (e.g. DLT tape drives), a
640              blocksize of 256 kBytes results in sufficient speed and seems to
641              be  a good choice.  Star allows block sizes up to 2 GByte if the
642              system does not impose a smaller limit.  If you want  to  deter‐
643              mine  the blocking factor when reading an unknown tar archive on
644              tape, specify a blocking factor that is higher than the supposed
645              blocking  factor  of  the  tape.   Star  then will determine the
646              blocking factor by reading the first  record  of  the  tape  and
647              print a message:
648
649                     star: Blocksize = # records.
650
651              Where  #  is the blocking factor in multiples of 512 bytes.  The
652              blocks= option and the bs=  option  are  equivalent  methods  to
653              specify the tape block size.  The blocks= option is preferred by
654              people who like to use an option that  behaves  similar  to  the
655              interface of the historic tar(1) implementations.
656
657              The best method to set the blocksize is to use the bs=# option.
658
659       bs=#   Set  output  block size to #.  You may use the same method as in
660              dd(1) and sdd(1).  The number representing the size is taken  in
661              bytes  unless  otherwise  specified.   If  a  number is followed
662              directly by the letter `.', `w', `b', `k',  `m',  `g',  `t',  or
663              `p',  the  size  is  multiplied  by  1, 2, 512, 1024, 1024*1024,
664              1024*1024*1024, 1024*1024*1024*1024 or 1024*1024*1024*1024*1024.
665              If  the size consists of numbers separated by `x' or `*', multi‐
666              plication of the two numbers is performed.   Thus  bs=7x8k  will
667              specify  a blocksize of 56 kBytes.  Blocksize must be a multiple
668              of 512 bytes.  See also the description of  the  blocks=  option
669              for  more details on blocksizes.  The option bs= is preferred by
670              people who like to use an option that  behaves  similar  to  the
671              interface used by dd(1) and sdd(1).
672
673       -bsdchdir
674              Switch  the behavior of the C= option to BSD style.  The default
675              behavior of star is to stay in a working directory until  a  new
676              C=  is seen.  With BSD tar, the C= option is only related to the
677              next file type argument.
678
679       -bz    run the input or output through a bzip2 pipe - see option -z  -Z
680              and  -j  below.   As the -bz the -j the -Z and the -z option are
681              non standard, it makes sense to omit the -bz the -j the  -Z  and
682              the  -z options inside shell scripts if you are going to extract
683              a compressed archive that is located inside a plain file as star
684              will  auto detect compression and choose the right decompression
685              option to extract.
686
687       C=dir
688
689       -C dir Perform a chdir(2) operation to dir before storing or extracting
690              the  next  files.   In all cases, star will perform the chdir(2)
691              operation relative to  the  current  working  directory  of  the
692              shell.
693
694              ·      In  list  mode  (with  the  -t flag), star ignores all -C
695                     options.
696
697              ·      In create mode (with the -c, -r and -u flag), star  walks
698                     through  all -C options and file type arguments.  While a
699                     BSD derived tar(1) implementation goes back to  the  cur‐
700                     rent  working  directory  after storing one file argument
701                     that immediately follows the -C option, star changes  the
702                     directory  only  if  a new -C option follows.  To emulate
703                     the behavior of a BSD derived tar(1), add a -C .   option
704                     after the file argument.
705
706              ·      In  extract  mode  (with the -x, -n and -diff flag), star
707                     builds a pattern list together with corresponding  direc‐
708                     tories   from  previous  C=dir  options  and  performs  a
709                     chdir(2) to the corresponding  directory  of  a  matching
710                     pattern.   All  pat=  options  that do not follow a C=dir
711                     option are interpreted as if they were preceded by a -C .
712                     option.  See EXAMPLES for more information.
713
714       compress-program=name
715              Set  a  named  compress program.  The program must compress in a
716              pipe when called without parameters and decompress when run with
717              the  -d  option  in a pipe.  This option is otherwise similar to
718              the -z the -j the -Z and the -bz option.
719
720       -copydlinks
721              Try to  recursively  copy  the  content  of  linked  directories
722              instead  of  creating  the link. This is an experimental feature
723              that may help to unpack archives on DOS.
724
725       -copyhardlinks
726              This option allows to copy hardlinked targets rather than creat‐
727              ing  the link.  It helps to extract tar files on systems that do
728              not implement hardlinks (e.g. BeOS).
729
730       -copylinks
731              This option allows to copy both,  hard-  and  symlinked  targets
732              rather  than  creating a link.  It helps to extract tar files on
733              systems that do not implement links (e.g. OS/2).  To extract and
734              copy  all symlinks correctly, you may need to call star twice as
735              star cannot copy files that appear in the archive later  than  a
736              symlink pointing to them.
737
738       -copysymlinks
739              This  option allows to copy symlinked targets rather than creat‐
740              ing a symbolic link.  It helps to extract tar files  on  systems
741              that  do  not  implement links (e.g. OS/2).  To extract and copy
742              all symlinks correctly, you may need to call star twice as  star
743              cannot  copy  files that appear in the archive later than a sym‐
744              link pointing to them.
745
746       -cpio-statistics
747              Instead of the star flavor of the statistics,  print  statistics
748              in cpio flavor.
749
750       -ctime If  used  with  the  list  command, this lists ctime rather than
751              mtime if the archive format is star, xstar, xustar, exustar,  or
752              pax/epax.
753
754              If  star  is  run as root and if -ctime is used with the extract
755              command and the same archive formats, this causes star to try to
756              restore even the ctime of a file by generating time storms.  You
757              should not do this when in multi user mode because this may con‐
758              fuse  programs  like  cron  and  the news system.  Although star
759              tries to eliminate the accumulative effects of the  time  storm,
760              there  is  a  tendency  for the system clock to slow down a bit.
761              The clock typically lags about  one  millisecond  per  extracted
762              file.  Use with care and check the system clock after using this
763              feature.
764
765              If used with the create command this changes the behavior of the
766              newer=  option.   Star,  in  this case compares the ctime of all
767              files to the mtime of the stamp file rather then  comparing  the
768              mtimes of both files.
769
770       -cumulative
771              A shorthand for -dump-cumulative.  See -dump-cumulative for more
772              information.
773
774       -D     Do not descend directories when in create mode.  Normally,  star
775              descends  the  whole tree if it encounters a directory in in its
776              file parameters.  The option -D is in effect by default  if  the
777              list=file  option is used.  If you like star to descend directo‐
778              ries found in the list file, use the -dodesc option (see below).
779
780       -d     Do not store/create directories.  Old versions of  tar  such  as
781              published  with the seventh edition of UNIX are not able to deal
782              with directories in tar archives.  If a tar archive is generated
783              without  directories  this  avoids problems with tar implementa‐
784              tions found on SYSVr3 and earlier.  If used during  extract,  no
785              intermediate missing directories are created.
786
787       -data-change-warn
788              If  the size of a file changes while the file is being archived,
789              treat this condition as a warning only that does not cause a non
790              zero  exit code.  A warning message is still written if the con‐
791              dition is not otherwise ignored by another rule from an  errctl=
792              option.  The -data-change-warn option works as if the last error
793              control option was
794
795                   errctl="WARN|GROW|SHRINK *"
796
797              The -e option or an ABORT entry in a condition set up by errctl=
798              has a higher precedence than the -data-change-warn option.  This
799              option is ignored in extract or list mode.
800
801       -debug Print debug messages. Among other things, this gives debug  mes‐
802              sages  for  header  type  recognition,  tar type properties, EOF
803              recognition, opening of remote archives and fifo internals.
804
805       diffopts=optlst
806              Comma separated list of diffopts.  Valid members in optlst are:
807
808              help      Print a summary of possible members  of  the  diffopts
809                        list.
810
811              !         Invert  the  meaning of the following string. No comma
812                        is needed after the exclamation mark.
813
814              not       Invert the meaning of all members in the diffopts list
815                        i.e.  exclude  all  present  options from an initially
816                        complete set compare  list.   When  using  csh(1)  you
817                        might  have  problems  to  use  !   due to its strange
818                        parser.  This is why the not alias exists.
819
820              perm      Compare file permissions. With this option in  effect,
821                        star  compares  the  low  order 12 bits of the st_mode
822                        field.
823
824              mode      Same as perm.
825
826              symperm   Compare permissions even in case the  target  file  on
827                        the  local filesystem is a symbolic link.  By default,
828                        star will not compare the permission of symbolic links
829                        as  most systems cannot set the permission of symbolic
830                        links.  Star compares symperm only if perm is compared
831                        also.
832
833              type      Compare  file type.  Note that star cannot compare the
834                        file type in case of a hard link.
835
836              nlink     Compare link count on hardlinks.  This only  works  if
837                        the  archive  is in exustar format and contains star's
838                        dump extensions.
839
840              uid       Compare numerical user id of file.
841
842              gid       Compare numerical group id of file.
843
844              uname     Compare ASCII version of user id of  file.   The  user
845                        name is mapped via the file /etc/passwd.
846
847              gname     Compare  ASCII version of group id of file.  The group
848                        name is mapped via the file /etc/group.
849
850              id        Shorthand  for:  uid,gid,uname,gname.    Compare   all
851                        user/group  related info of file.  Note that this will
852                        always find differences if the source and target  sys‐
853                        tem use different user or group mappings.
854
855              size      Compare  file size.  Note that star cannot compare the
856                        file size in case of a hard link.
857
858              data      Compare content of file.  If star already  found  that
859                        the  size of the files differ, it will not compare the
860                        content anymore.  If the size  of  the  files  differ,
861                        star will always report different data.
862
863              cont      Same as data.
864
865              rdev      Compare major/minor numbers for device nodes.
866
867              hardlink  Compare target of hardlinks.
868
869              symlink   Compare  target  of symlinks. This evaluates the paths
870                        returned by the readlink(2) call.
871
872                        Two symlinks are considered equal, it they either have
873                        a characterwise identical link-name, or if they either
874                        both use an absolute path name or both use a  relative
875                        path  name  and  the  following is true: Both symlinks
876                        point to the same file that must exist or  both  path‐
877                        names look similar enough.
878
879              sympath   Compare the target pathnames of symlinks. This charac‐
880                        terwise compares the strings returned from  the  read‐
881                        link(2) call.
882
883              sparse    Compare  if  either  both  files are sparse or not. If
884                        only one of both files is sparse, then a difference is
885                        flagged.   This  only works with if the archive format
886                        is star, xstar, xustar, exustar, or gnutar.
887
888              atime     Compare access time of file.  This only works with  if
889                        the archive format is star, xstar, xustar, exustar, or
890                        pax/epax.
891
892              mtime     Compare modification time of file.
893
894              ctime     This only works with if the archive  format  is  star,
895                        xstar, xustar, exustar, or pax/epax.
896
897              lmtime    Compare  the modification time even in case the target
898                        file on the local filesystem is a symbolic  link.   By
899                        default,  star  will not compare the modification time
900                        of symbolic links as most systems cannot set the modi‐
901                        fication time of symbolic links.  Star compares lmtime
902                        only if mtime is compared also.
903
904              times     Shorthand for: atime,mtime,ctime.
905
906              nsecs     Check nanoseconds in all selected timestamps as well.
907
908                        Note that the time resolution  of  various  filesystem
909                        differs.    While  modern  filesystems  like  ZFS  and
910                        filesystems that introduced  a  sub-second  resolution
911                        recently,  tend  to  support a nanosecond granularity,
912                        filesystems like UFS that support a sub-second resolu‐
913                        tion  since  the  early  1990s  tend to support only a
914                        microsecond granularity. Since even in  in  2018,  the
915                        POSIX.1-2008   feature  pathconf(_PC_TIMESTAMP_RESOLU‐
916                        TION) has not yet been implemented  on  any  platform,
917                        you may need to disable to compare nanoseconds in some
918                        cases.
919
920                        Star currently first tries to compare  the  timestamps
921                        based on a nanosecond resolution and if that fails and
922                        one timestamp seems to have a microsecond  resolution,
923                        the comparison is repeated with microsecond resolution
924                        only.
925
926              dir       Compare the content of directories.  This  only  works
927                        if  the  archive  is  in  exustar  format and contains
928                        star's dump extensions.  Together with increased  ver‐
929                        bose  level (-vv) this will print a list of files that
930                        are only in the archive and a list of files  that  are
931                        only on the current filesystem.
932
933              xtimes    Shorthand for: atime,mtime,ctime,lmtime.
934
935              acl       Compare  access control lists.  This only works if the
936                        archive is in exustar format and has been created with
937                        star's  -acl  option.   You  need  to specify the -acl
938                        option in addition when running the diff.
939
940              xattr     Compare extended file attributes.  This only works  if
941                        the  archive is in exustar format and has been created
942                        with star's -xattr option.  You need  to  specify  the
943                        -xattr option in addition when running the diff.
944
945              fflags    Compare  extended  file flags.  This only works if the
946                        archive is in exustar format and has been created with
947                        star's  -xfflags  option.   You  need  to  specify the
948                        -xfflags option in addition when running the diff.
949
950              If optlst starts with a ! the meaning of all members  in  optlst
951              is  inverted as with the not optlist member.  In this case, star
952              starts with a complete list  that  includes  atime  and  lmtime.
953              Reasonable  diff options to use when comparing against a copy of
954              a directory tree are diffopts=!atime,ctime,lmtime.
955
956              If diffopts are not specified, star compares everything but  the
957              access  time  of the files and the modification time of symbolic
958              links.
959
960       dir-group=group
961              If star extracts archives as root, this option allows to control
962              the group id of intermediate directories created by star.
963
964       dir-owner=user
965              If star extracts archives as root, this option allows to control
966              the owner of intermediate directories created by
967
968       -dirmode
969              If in create mode (i.e. when storing  files  to  archive),  star
970              stores directories past the corresponding files. This guarantees
971              that even old tar implementations without a directory cache will
972              be able to restore the correct times of directories.  The option
973              -dirmode should  only  be  used  if  the  archive  needs  to  be
974              extracted  by  an  old  tar  implementation.  If star is used to
975              extract an archive that  has  been  created  with  -dirmode  the
976              directories  will not get an old time stamp unless the option -U
977              is used while extracting the archive.
978
979       -do-fsync
980              Tell star to call fsync(2) for every file when in extract  mode.
981              This  enables star to check whether a file could be successfully
982              extracted.  See -no-fsync for more information.
983
984       -dodesc
985              Force star to descend directories found  in  a  list=file.   See
986              also the -D option above.  The -dodesc option only works in cre‐
987              ate mode.
988
989       -dump  Allows to create archives with the same number of attributes  as
990              an  archive  that  has  been  created with the level= option but
991              without the restrictions that apply to a true dump.
992
993              The resultant archive may be seen as  a  level-less  dump  which
994              includes  similar attributes as a level 0 dump but may span more
995              than a single file system and does not need to use a -C  option.
996              It has been originally introduced to make it easier to implement
997              a star version that supports true incremental dumps, but  it  is
998              kept  as  it gives additional benefits.  Star currently sets the
999              archive type to exustar and, in  addition  archives  more  inode
1000              meta data inside POSIX.1-2001 extended headers.  See also level=
1001              option and the section INCREMENTAL BACKUPS for more  information
1002              on true incremental dumps.
1003
1004       -dump-cumulative
1005              instructs  star  to  perform incremental dumps relatively to the
1006              last incremental dump of the same level.  Incremental dumps with
1007              a  level  higher than 0 are normally done relatively to the con‐
1008              tent of a previous dump with lower level. If  incremental  dumps
1009              and restores are going to be used to synchronize filesystem con‐
1010              tent, every successive incremental dump will increase in size if
1011              -dump-cumulative   is   not  used.   See  section  SYNCHRONIZING
1012              FILESYSTEMS for more information.
1013
1014
1015       dumpdate=name
1016              Tells star to use the mtime of the time stamp file name  instead
1017              of  using  the  start time of star.  This is needed when star is
1018              run on file system snapshots.  If star would use  the  the  it's
1019              own start time with snapshots, all files that have been modified
1020              between the setup of the snapshot and the start of star would be
1021              missing on the backup.
1022
1023              A  solution is to create the time stamp file, then to create the
1024              snapshot and later use the option dumpdate=name.
1025
1026       -dumpmeta
1027              changes the behavior of  star  in  incremental  dump  mode.   If
1028              -dumpmeta is used and only the inode change time (st_ctime) of a
1029              file has been updated since the last incremental dump, star will
1030              archive  only  the meta data of the file (e.g. uid, permissions,
1031              ...) but not the file content.  Using -dumpmeta will  result  in
1032              smaller  incremental  dumps,  but  files  that have been created
1033              between two incrementals and set to  an  old  date  in  st_mtime
1034              (e.g.  as a result from a tar extract) will not be archived with
1035              full content.  Using -dumpmeta thus  may  result  in  incomplete
1036              incremental dumps, use with extreme care.
1037
1038       -e     Exit  immediately  with  exit  status -3 (253) if any unexpected
1039              error occurs.  The -e option works as if the last error  control
1040              option was
1041
1042                   errctl="ABORT|ALL|DIFF   *"
1043
1044              This  allows  to  use  the  errctl=  option together with the -e
1045              option and thus to ignore some error conditions  while  aborting
1046              on all other conditions.
1047
1048       errctl= name
1049       errctl= error control spec
1050              Add  the content from file name to the error control definitions
1051              or add error control spec  to  the  error  control  definitions.
1052              More than one error control file and more than one error control
1053              spec as well as a mixture of both forms is possible.
1054
1055              The reason for using error control is to make star  quiet  about
1056              error  conditions that are known to be irrelevant on the quality
1057              of the archive or restore run or to tell star to abort  on  cer‐
1058              tain error conditions instead of trying to continue with the ar‐
1059              chive.
1060
1061              A typical reason to use error control is  to  suppress  warnings
1062              about growing log files while doing a backup on a live file sys‐
1063              tem.  Another typical reason to use error  control  is  to  tell
1064              star  to  abort  if e.g. a file could not be archived instead of
1065              continuing to archive other files from a list.
1066
1067              The error control file contains a set of  lines,  each  starting
1068              with  a list of error conditions to be ignored followed by white
1069              space followed by a file name  pattern  (see  match(1)  or  pat‐
1070              match(3) for more information).  The error control spec uses the
1071              same syntax as a single line from the error  control  file.   If
1072              the  file  name  pattern  needs to start with white space, use a
1073              backslash to escape the start of the file name. It is not possi‐
1074              ble to have new line characters in the file name pattern.  When‐
1075              ever an error situation is encountered, star checks the lines in
1076              the  error  control  file starting from the top.  If the current
1077              error condition is listed on a line in the error  control  file,
1078              then  star  checks  whether  the pattern on the rest of the line
1079              matches the current file name.  If this is the case,  star  uses
1080              the  current  error control specification to control the current
1081              error condition.
1082
1083              The list of error conditions to be handled may use one  or  more
1084              (in this case separated by a '|' character) identifiers from the
1085              list below:
1086
1087              ABORT       If this meta condition is included in an error  con‐
1088                          dition,  star  aborts  (exits)  as  soon as possible
1089                          after this error condition has been seen instead  of
1090                          making  star  quiet about the condition.  This error
1091                          condition flag may only be  used  together  with  at
1092                          leat another error condition or a list of error con‐
1093                          ditions (separated by a '|' character).
1094
1095              WARN        If this meta condition is included in an error  con‐
1096                          dition, star prints the warning about the error con‐
1097                          dition but the error condition does not  affect  the
1098                          exit code of star and the error statistics (which is
1099                          printed to the end) does  not  include  the  related
1100                          errors.   This error condition flag may only be used
1101                          together with at another error condition or  a  list
1102                          of  error conditions (separated by a '|' character).
1103                          The WARN meta condition has a lower precedence  than
1104                          ABORT.
1105
1106              DIFF        Suppress   output   in  case  that  star  -diff  did
1107                          encounter any differences.
1108
1109              ALL         This is a shortcut for all error conditions below.
1110
1111              STAT        Suppress warnings that  star  could  not  stat(2)  a
1112                          file.
1113
1114              GETACL      Suppress  warnings  about  files  on  which star had
1115                          problems to retrieve the ACL information.
1116
1117              OPEN        Suppress warnings about  files  that  could  not  be
1118                          opened.
1119
1120              READ        Suppress warnings about read errors on files.
1121
1122              WRITE       Suppress warnings about write errors on files.
1123
1124              READLINK    Suppress  warnings  about readlink(2) errors on sym‐
1125                          bolic links.
1126
1127              GROW        Suppress warnings about files that  did  grow  while
1128                          they have been archived.
1129
1130              SHRINK      Suppress  warnings about files that did shrink while
1131                          they have been archived.
1132
1133              MISSLINK    Suppress warnings about files  for  which  star  was
1134                          unable to archive all hard links.
1135
1136              NAMETOOLONG Suppress  warnings  about  files  that  could not be
1137                          archived because the name of the file  is  too  long
1138                          for the archive format.
1139
1140              FILETOOBIG  Suppress  warnings  about  files  that  could not be
1141                          archived because the size of the file is too big for
1142                          the archive format.
1143
1144              SPECIALFILE Suppress  warnings  about  files  that  could not be
1145                          archived because the file type is not  supported  by
1146                          the archive format.
1147
1148              GETXATTR    Suppress warnings about files on that star could not
1149                          retrieve the extended file attribute information.
1150
1151              CHDIR       Suppress warnings about chdir(2) errors.
1152
1153              ICONV       Suppress  warnings  about  iconv(3)  errors.   These
1154                          error  happen,  when  text  is  converted from or to
1155                          POSIX.1-2001 extended tar headers.
1156
1157              ID          Suppress warnings about uid/gid range errors.  These
1158                          errors  happen when the archive format does not sup‐
1159                          port the actual value.
1160
1161              SETTIME     Suppress warnings about files on that star could not
1162                          set the time information during extraction.
1163
1164              SETMODE     Suppress warnings about files on that star could not
1165                          set the access modes during extraction.
1166
1167              SECURITY    Suppress warnings about files that have been skipped
1168                          on  extraction  because they have been considered to
1169                          be a security risk.  This currently applies  to  all
1170                          files  that  have  a '/../' sequence inside when -..
1171                          has not been specified.
1172
1173              LSECURITY   Suppress warnings about links that have been skipped
1174                          on  extraction  because they have been considered to
1175                          be a security risk.  This currently applies  to  all
1176                          link  target  names  that  start  with '/' or have a
1177                          '/../' sequence inside when -no-secure-links has not
1178                          been  specified.   In this case, star tries to match
1179                          the link name against the pattern in the error  con‐
1180                          trol file.
1181
1182              SAMEFILE    Suppress warnings about links that have been skipped
1183                          on extraction because source and target of the  link
1184                          are  pointing  to  the same file.  If star would not
1185                          skip these files, it would end up with removing  the
1186                          file  completely.  In this case, star tries to match
1187                          the link name against the pattern in the error  con‐
1188                          trol file.
1189
1190              BADACL      Suppress  warnings about access control list conver‐
1191                          sion problems.
1192
1193              SETACL      Suppress warnings about files on that star could not
1194                          set the ACL information during extraction.
1195
1196              SETXATTR    Suppress warnings about files on that star could not
1197                          set the extended file attribute  information  during
1198                          extraction.
1199
1200       If  a  specific error condition is ignored, then the error condition is
1201       not only handled in a silent way but also excluded from the error  sta‐
1202       tistics that are printed at the end of the star run.
1203
1204       Be  very  careful  when using error control as you may ignore any error
1205       condition.  If you ignore the wrong error conditions, you  may  not  be
1206       able to see real problems anymore.
1207
1208       -exclude-from name
1209              Exclude from named file, this is an alias for the -X option. See
1210              -X option for more information.
1211
1212       -F,-FF ...
1213              Fast and simple exclude option for create  mode.   With  one  -F
1214              argument,  star  ignores  all  directories  called SCCS and RCS.
1215              With two -F arguments, star in addition ignores all files called
1216              core  errs a.out all files ending with .o.  OBJ/.  With three -F
1217              arguments, star ignores all sub trees starting from a  directory
1218              that  includes  a  file .mirror or .exclude and all object files
1219              and files called core errs a.out all files ending with .o.  With
1220              four  -F  arguments,  star ignores all sub trees starting from a
1221              directory that includes a file .mirror or  .exclude  the  latter
1222              files are excluded too as well as and all object files and files
1223              called core errs a.out all files ending with .o.  With  five  -F
1224              arguments,  star  in  addition  again  excludes  all directories
1225              called SCCS and RCS.
1226
1227       f=tarfilename
1228              Use tarfilename as the name for the  tar  archive.   See  option
1229              file=tarfilename.
1230
1231       -fifo  Use  a  fifo to optimize data flow from/to tarfile.  This option
1232              is in effect by default (it may be  changed  at  compile  time).
1233              The  default fifo size is 8 MBytes on all platforms except Linux
1234              versions that do not support mmap() (4 MB because kernels before
1235              2.4  did  not handle big shared memory areas) and Sun/mc68000 (1
1236              MB).  This will star make even work on a tiny machine like a Sun
1237              3/50.  The fifo size may be modified with the fs= option. A rule
1238              of dumb for the fifo size is to use more than the buffer size of
1239              the  tape  drive  and  less  then half of the real memory of the
1240              machine.  A good choice would be to use a fifo  size  between  8
1241              and 256 MB.  This may increase backup speed up to 5% compared to
1242              the speed achieved with the default fifo size. Note that with  a
1243              DLT  drive from y2000 that gives 12MB/s transfer rate, a fifo of
1244              256 MB size will keep the tape at least streaming in units of 20
1245              seconds.
1246
1247              Future  LTO tape drives are expected to implement transfer rates
1248              of aprox. 3GB/s and need a much larger fifo  size  to  keep  the
1249              tape streaming.
1250
1251              All  options  that  start  with the -f sequence are sensitive to
1252              typo problems, see BUGS section for more information.
1253
1254       -fifostats
1255              Print fifo statistics at the end of a star run when the fifo has
1256              been in effect.  All options that start with the -f sequence are
1257              sensitive to typo problems, see BUGS section for  more  informa‐
1258              tion.
1259
1260       file=tarfilename, f=tarfilename
1261              Use tarfilename as the name for the tar archive. Currently up to
1262              100 file= options are possible. Specifying more then  one  file=
1263              option  make  sense in multi volume mode. In this case star will
1264              use the next name in the list  every  time  a  media  change  is
1265              needed.   To  make  star  behave consistent with the single file
1266              case, star loops over the list of  known  archive  files.   Note
1267              that  if  star is installed suid root and the first tarfile is a
1268              remote archive, only the connection to this archive will be cre‐
1269              ated  with  root  privileges.   After  this  connection has been
1270              established as root, star switches back to the id of the caller.
1271              If any of the other archives in the list is located on a differ‐
1272              ent host, star will not be able to open this archive  later  on,
1273              unless run by root.
1274
1275              Star  normally uses stdin/stdout for the tar archive because the
1276              most common way to use star is in conjunction  with  pipes.   If
1277              star  is  installed  suid root or if it has been called by root,
1278              tarfilename may be in remote syntax:  user@host:filename  as  in
1279              rcp(1)  even  if  invoked by non root users.  See SUID NOTES for
1280              more information.
1281
1282              To make a file local although it includes a colon (:), the file‐
1283              name must start with: '/', './' or '../'
1284
1285              Note  that  if  star talks to an old rmt remote tape server that
1286              does not support symbolic open modes, it does not open a  remote
1287              tape  with the O_CREAT open flag because this would be extremely
1288              dangerous.  If the rmt server on  the  other  side  is  the  rmt
1289              server  that comes with star or the GNU rmt server, star may use
1290              the symbolic mode for the open flags.  Only  the  symbolic  open
1291              modes allow to send all possible open modes in a portable way to
1292              remote tape servers.
1293
1294              It is recommended to use the rmt server that  comes  with  star.
1295              It  is  the only rmt server that gives platform independent com‐
1296              patibility with BSD, Sun and GNU rmt  clients  and  it  includes
1297              security  features  that may be set up in /etc/default/rmt.  All
1298              options that start with the -f sequence are  sensitive  to  typo
1299              problems, see BUGS section for more information.
1300
1301              See  -rsh  option  on how to set up a different protocol for the
1302              connection to the remote tape server.
1303
1304              See ENVIRONMENT section for information on how to use ssh(1)  to
1305              create a remote tape server connection.
1306
1307              Note that if file=- has been specified, it is no longer possible
1308              to use the -find -exec primary.
1309
1310       -find  This option acts a separator.  If it is used, all  star  options
1311              must  be  to  the  left of the -find option. To the right of the
1312              -find option, star accepts the find command line syntax only.
1313
1314              The find expression acts as a filter between the source of  file
1315              names and the consumer, which may either be the archiving engine
1316              or list/extract engine. If  the  find  expression  evaluated  as
1317              TRUE,  then  the related file is selected for processing, other‐
1318              wise it is omited.
1319
1320              In order to make the evaluation of the find expression more con‐
1321              venient,  star  implements  additional  find primaries that have
1322              side effects on the file meta data.  Star implements the follow‐
1323              ing additional find primaries:
1324
1325              -chatime timespec
1326                     The  primary  always  evaluates  as true; it modifies the
1327                     time of last access  of  a  file  in  struct  stat.   See
1328                     sfind(1) for a description of timespec.
1329
1330              -chctime timespec
1331                     The  primary  always  evaluates  as true; it modifies the
1332                     time of last status change of a file in struct stat.  See
1333                     sfind(1) for a description of timespec.
1334
1335              -chmtime timespec
1336                     The  primary  always  evaluates  as true; it modifies the
1337                     time of last modification of a file in struct stat.   See
1338                     sfind(1) for a description of timespec.
1339
1340              -chgrp gname
1341                     The  primary  always evaluates as true; it sets the group
1342                     of the file to gname.
1343
1344              -chmod mode
1345                     The primary always evaluates as true; it sets the permis‐
1346                     sions  of  the  file to mode.  Octal and symbolic permis‐
1347                     sions are accepted for mode as with chmod(1).
1348
1349              -chown uname
1350                     The primary always evaluates as true; it sets  the  owner
1351                     of the file to uname.
1352
1353              -false The  primary always evaluates as false; it allows to make
1354                     the result of the  full  expression  different  from  the
1355                     result of a part of the expression.
1356
1357              -true  The  primary  always evaluates as true; it allows to make
1358                     the result of the  full  expression  different  from  the
1359                     result of a part of the expression.
1360
1361              The command line:
1362
1363              star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type d
1364
1365              lists  all  directories  and archives all non-directories to the
1366              archive o.tar.
1367
1368              The command line:
1369
1370              star -c f=o.tar -find . ( -type d -chown root -o true )
1371
1372              archives all directories so they appear to be owned by  root  in
1373              the archive, all non-directories are archived as they are in the
1374              file system.
1375
1376              Note that the -ls, -exec and the -ok primary cannot be  used  if
1377              stdin  or  stdout  has  been  redirected by the list=- of by the
1378              file=- options.
1379
1380       -force_hole
1381              obsoleted by -force-hole
1382
1383       -force-hole
1384              Try to extract all files with holes. This even works with  files
1385              that are created without the -sparse option.  Star, in this case
1386              examines the content of the files in the  archive  and  replaces
1387              writes to parts containing binary zeroes with seeks.
1388
1389              If  used  together  with the -sparse option in create mode, star
1390              assumes all files to be sparse and archives files with blocks of
1391              nulls as sparse files.
1392
1393              This  option  should be used with extreme care because you some‐
1394              times get in trouble  when  files  get  unattended  holes.   All
1395              options  that  start  with the -f sequence are sensitive to typo
1396              problems, see BUGS section for more information.
1397
1398       -force_remove
1399              obsoleted by -force-remove
1400
1401       -force-remove
1402              Force to remove non writable files on extraction.   By  default,
1403              star  will  not  overwrite  files  that  are read only.  If this
1404              option is in effect, star will silently remove  these  files  to
1405              allow the extraction of a file.  All options that start with the
1406              -f sequence are sensitive to typo problems, see BUGS section for
1407              more information.
1408
1409       -force-restore
1410              Force  an incremental restore even if there is a dump level mis‐
1411              match or a reference date mismatch.  See -wtardumps, level=  and
1412              sections  INCREMENTAL  BACKUPS and INCREMENTAL RESTORES for more
1413              information.
1414
1415       -freeze
1416              run the input or output through a freeze pipe -  see  option  -z
1417              below.
1418
1419       fs=#   Set fifo size to #.  See bs= for the possible syntax.
1420
1421              The  default size of the fifo is 1 Mbyte on Sun mc68000 systems,
1422              4 Mbytes on non mmap() aware Linux systems and 8 Mbytes  on  all
1423              other  systems.   See  -fifo option for hints on using the right
1424              fifo size.
1425
1426
1427       fs-name=mount_point
1428              Use mount_point when recording information in /etc/tardumps  and
1429              when  comparing  against information in /etc/tardumps for incre‐
1430              mental backups.  This makes sense when backups  are  made  using
1431              file  system  snapshots and allows /etc/tardumps and the archive
1432              to contain the real name of the file system instead of the  tem‐
1433              porary mount point that is used for the snapshot device.
1434
1435
1436       H=headertype
1437              See artype=headertype option.  Note that POSIX.1-2001 defines an
1438              option -H that follows symbolic links that have been encountered
1439              on  the  command  line.   For  this  reason, the old star option
1440              H=headertype option may go away in the future even  though  this
1441              option has been in use by cpio since 1989.
1442
1443       -h, -L Follow symbolic links as if they were files.  Normally star will
1444              not follow symbolic links but stores their  values  in  tarfile.
1445              See also the -L option.
1446
1447       -hardlinks
1448              In  extract  mode,  this  option  tells  star to try to create a
1449              hardlink whenever a symlink is encountered in the  archive.   In
1450              create mode, this option tells star to try to archive a hardlink
1451              whenever a symlink is encountered in the file system.
1452
1453       -hpdev Allow 24 bits for the minor device number using 8 octal  digits.
1454              Note  that although it allows to create tar archives that can be
1455              read with HP-UX tar, this creates  tar  archives  which  violate
1456              POSIX.1-1988.   This  option is only needed if you like to use a
1457              POSIX.1-1988 based archive format that does not  include  exten‐
1458              sions.   If  you  use the xstar format, star will use a base 256
1459              extension that allows bigger major/minor numbers by default,  if
1460              you  use the xustar or the exustar format there is no limitation
1461              at all as these formats use POSIX.1-2001 extended headers to ar‐
1462              chive the major/minor numbers by default.
1463
1464       -i     Ignore checksum errors on tar headers.  If this option is speci‐
1465              fied, star will not exit if a header  with  a  bad  checksum  is
1466              found but search for the next valid header.
1467
1468       -install
1469              Carefully  replace existing files when extracting files. This is
1470              done similar to install(1) by first extracting the files into  a
1471              temporary name and renaming the file to the final name after the
1472              extraction of that file was successful.
1473
1474              As star by default does not  remove  non-empty  directories,  an
1475              install  that needs to remove existing non-empty directories may
1476              also need the options -force-remove and -remove-recursive.
1477
1478       -j     run the input or output through a bzip2 pipe - see option -z  -Z
1479              and  -bz  below.  As the -bz the -j the -Z and the -z option are
1480              non standard, it makes sense to omit the -bz the -j the  -Z  and
1481              the  -z options inside shell scripts if you are going to extract
1482              a compressed archive that is located inside a plain file as star
1483              will  auto detect compression and choose the right decompression
1484              option to extract.
1485
1486       -keep-nonempty-dirs
1487              Do not complain about trying to remove nonempty  directories  in
1488              case that -remove-recursive has not been specified.
1489
1490       -keep_old_files
1491              obsoleted by -keep-old-files
1492
1493       -keep-old-files, -k
1494              Keep  existing  files  rather  than restoring them from tarfile.
1495              This saves files from being clobbered even if tarfile contains a
1496              more recent version of the corresponding file.
1497
1498              See SECURITY NOTES for more information.
1499
1500       -L, -h Follow symbolic links as if they were files.  Normally star will
1501              not follow symbolic links but stores their  values  in  tarfile.
1502              See also the -h option.
1503
1504       -l     Do  not  print a warning message if not all links to hard linked
1505              files could be dumped. This option is evaluated in the  opposite
1506              way  to historic tar(1) implementations and to POSIX.1.  POSIX.1
1507              requests that by default no warning messages will be printed and
1508              -l  will  enable  warning  messages  when not all links could be
1509              archived.
1510
1511       level=dumplevel
1512              Set level for incremental dumps.  This option is used to  switch
1513              star  into  true incremental dump mode.  The dumplevel may be in
1514              the range between 0..99.
1515
1516              In true incremental dump mode, a -C option which is followed  by
1517              the  name  a  mount  point and a dot ('.') as starting directory
1518              name is required.  Only a single file system may be handled at a
1519              time.  If the directory following the -C option is not referring
1520              to a root directory of a file system, the dump is called a  par‐
1521              tial  dump.   If the directory following the -C option is refer‐
1522              ring to a root directory of a file system and no other  restric‐
1523              tions  apply  that exclude certain files from the dump, the dump
1524              is called a full dump.
1525
1526              By default, the tardumps database is not written.  See also  the
1527              tardumps=name and -wtardumps options and the section INCREMENTAL
1528              BACKUPS for more information.
1529
1530       -link-data
1531              In create mode, include the data for files even if  these  files
1532              are  hard  links.  This feature in create mode is currently only
1533              available for the  exustar  archive  format  and  only  in  case
1534              -sparse has not been specified.
1535
1536              In  extract  mode,  allow  star to deal with data in hard linked
1537              files even if the standard would not allow this for the used ar‐
1538              chive format.
1539
1540       -link-dirs
1541              When in create mode, try to find hard linked directories.  Using
1542              -link-dirs will force star to keep track of all directories that
1543              will go into the archive and thus causes a lot more memory to be
1544              allocated than in the default case.
1545
1546              If you like to extract a cpio archive that contains hard  linked
1547              directories,  you  also need to specify -link-dirs in extract or
1548              diff mode.  This is needed  because  many  cpio  implementations
1549              create buggy archives with respect to hard links.  If star would
1550              look for hard linked directories in all cases, it  would  detect
1551              many pseudo hard links to directories.  Use -link-dirs with care
1552              if you extract cpio archives.
1553
1554              Note that not all filesystem  allow  to  create  hard  links  to
1555              directories.  Also note that even though a non-root user is able
1556              detect and archive hard linked directories, all known  operating
1557              systems require the extraction to be done as root in order to be
1558              able to create or remove hard links to  directories.   For  this
1559              reason  its only recommended to use this option when doing accu‐
1560              rate backups and when hard links to directories are expected.
1561
1562              When the option -link-dirs is not used and hard links to  direc‐
1563              tories are present, the appendant sub-tree will appear more than
1564              once on the archive and star will  print  Linkcount  below  zero
1565              warnings for non directory hard links inside the sub-tree.
1566
1567       list=filename
1568              Read filenames for store/create/list/diff command from filename.
1569              The file filename must contain a list of path names, each  on  a
1570              separate  line.   This  option  implies the -D option.  To force
1571              star to descend directories, use  the  -dodesc  option  in  this
1572              case.  See also the -X option.
1573
1574              Note that if list=- has been specified, it is no longer possible
1575              to use the -find -exec primary.
1576
1577       -lowmem
1578              Try to run with reduced memory requirements.  This  causes  star
1579              to default to 1 MB of FIFO memory.  Instead of allocating memory
1580              to hold the directory content and reading the directory at once,
1581              star  reads  the  directory name by name. This may cause star to
1582              close the directory if it rans out of file  descriptors  because
1583              of  deeply nested directories. If a directory then does not sup‐
1584              port telldir(3)/seekdir(3), star will fail.
1585
1586       -lzip  run the input or output through a lzip  pipe  -  see  option  -z
1587              below.
1588
1589       -lzma  run  the  input  or  output  through a lzma pipe - see option -z
1590              below.
1591
1592       -lzo   run the input or output through a lzop  pipe  -  see  option  -z
1593              below.
1594
1595       -M, -xdev
1596              Do  not descend mount points.  This is useful when doing backups
1597              of complete file systems.  See NOTES for more information.
1598
1599       -m     Do not restore access and modification time.   (Access  time  is
1600              only  available if star is reading star, xstar, xustar, exustar,
1601              or pax/epax archives). If star extracts other archive types, the
1602              -m flag only refers to the modification time.
1603
1604
1605       -match-tree
1606              If  in  create  mode  a  pattern does not match a directory, and
1607              -match-tree has been specified,  the  whole  directory  tree  is
1608              excluded  from the archive and from further directory scans.  By
1609              default, star excludes the directory but still recursively scans
1610              the  content  of  this directory as complex patterns could allow
1611              files inside the directory tree  to  match.   Using  -match-tree
1612              allows  to  efficiently  exclude whole trees from scanning. This
1613              helps to avoid scannings directory trees that are on remote file
1614              systems or contain excessive bad blocks.
1615
1616       maxsize=#
1617              Do  not  store  files in tarfile if they are bigger than #.  See
1618              bs= for the possible syntax.  By default, the number  is  multi‐
1619              plied  by  1024, so the value counts in units of kBytes.  If the
1620              size specifier ends with a valid multiplication  character  (e.g
1621              '.' for bytes or 'M' for MB) the specified size is used as spec‐
1622              ified and not multiplied by 1024.  See bs= option for all possi‐
1623              ble multipliers.
1624
1625       -meta  In  create  mode,  -meta causes star to archive all meta data of
1626              the file (e.g. uid, permissions, ...) but not the file  content.
1627              In extract mode, it causes star to restore all meta data but not
1628              the file content. In addition, in extract mode  no  plain  file,
1629              special  file  or  directory  will  be  created.  Meta files are
1630              needed to support incremental backups.
1631
1632              Warning: Do not try to extract  star  archives  containing  meta
1633              files  using  other tar implementations if they are not aware of
1634              the meta file extensions of star.  Star tries to force  all  tar
1635              implementations  that are not standard compliant to abort.  Star
1636              also tries to make all non POSIX.1-2001 compliant tar  implemen‐
1637              tations  unable  to  find  a  valid filename. However when other
1638              POSIX.1-2001 aware tar implementations come up  and  don't  know
1639              about meta files, they will destroy files on disk.
1640
1641              The  problems result from the only current fallback in the POSIX
1642              standard that tells tar implementations  to  treat  all  unknown
1643              file types as if they were plain files. As meta files are needed
1644              for incremental backups, I am looking for people  and  companies
1645              who  like  to support me to be able to add the meta file concept
1646              to the POSIX.1-2005 standard.
1647
1648       -modebits
1649              This options allows you to create tar archives that include more
1650              than  12  bits  from st_mode. Note this create tar archives that
1651              violate POSIX but some tar  implementations  insist  in  reading
1652              such nonstandard archives.
1653
1654       -multivol
1655              Switch  to  multi volume mode.  In multi volume mode, there will
1656              be no logical EOF marker written to the end of a single tape. If
1657              -multivol is used in read mode, a hard EOF on input (if not pre‐
1658              ceded by a logical EOF) triggers a medium change operation.
1659
1660              Specifying -multivol tells star to split files across volumes if
1661              needed.   This way, a virtual archive is created that spans more
1662              than one medium.  Multi volume mode is needed whenever it is not
1663              possible to split the archiving or extracting into several logi‐
1664              cally independent tasks.  This  is  true  for  e.g.  incremental
1665              dump/restore  operations  where  inode numbers need to be traced
1666              for the whole task.
1667
1668              When tsize=# has been specified, but star is not in multi volume
1669              mode, files cannot be split across volumes.
1670
1671              When  -multivol  has been specified in create mode together with
1672              tsize=# then a media change is initiated exactly after an amount
1673              of  tsize data has been written.  When -multivol has been speci‐
1674              fied in create mode and tsize=# has not been specified, then the
1675              medium  change  is triggered by a EOT condition from writing the
1676              medium. This allows to use media where the size cannot be  known
1677              in  advance  (e.g. tapes with build in compression); it does not
1678              work if the EOT condition is  not  returned  in  sync  with  the
1679              related  write  operation.  For this reason, it is expected that
1680              data buffering inside a device driver cannot be used.
1681
1682              Depending on the selected archive format, star writes  a  volume
1683              header  at  the  beginning  of  a new medium. This medium header
1684              allows to verify the correct volume after a change  during  read
1685              back.   It  is  recommended  to  use the exustar format for best
1686              results.  In create mode, -multivol is only  supported  for  ar‐
1687              chives  types  that  allow to write reliable multi volume header
1688              information.
1689
1690              See tsize=# option for more information.
1691
1692              Note that -multivol is an interactive option that prevents  star
1693              from being used in non-interactive environments.  If you like to
1694              use it in a non-interactive environment,  you  need  to  specify
1695              new-volume-script=script  in  addition  in order to automate the
1696              media change procedure.
1697
1698       newer=filename
1699              Do not store files to tarfile if their modification time is  not
1700              newer than the modification time of filename.  See -ctime option
1701              for changing this behavior.
1702
1703       -newest
1704              In conjunction with the list command this  lists  you  only  the
1705              newest file in tarfile.
1706
1707       -newest_file
1708              obsoleted by -newest-file
1709
1710       -newest-file
1711              In  conjunction  with  the  list command this lists you only the
1712              newest regular file in tarfile.
1713
1714       new-volume-script=script
1715              Call script at end of each tape if in  multi  volume  mode.   If
1716              this  option is not in effect, star will ask the user to confirm
1717              the volume change.  The script is called  with  two  parameters.
1718              The  first  parameter  is  the next volume number and the second
1719              parameter is the next archive file name.
1720
1721       -nodump
1722              If this option is set, star will not dump files  that  have  the
1723              nodump  flag set. Note that this currently only works on BSD-4.4
1724              derivates and on Linux.  On Linux, using this option will  cause
1725              a  performance  degradation  (the  system time increases by 10%)
1726              because of the unlucky kernel interface that requires a separate
1727              open and ioctl.
1728
1729       -no-dirslash
1730              Do  not  add a slash to the end of directory names if writing to
1731              an archive.  Historic tar archive  formats  did  only  allow  to
1732              specify  plain  files  and hard links.  Around 1980, BSD added a
1733              feature to specify a directory on tape by adding a slash to  the
1734              end of the name. POSIX.1-1988 defined the first official tar ar‐
1735              chive format that had a clean method to specify the  type  of  a
1736              directory.   As  old  tar  formats need the slash to recognize a
1737              directory, -no-dirslash may not be used if  archives  should  be
1738              compatible with the old tar format.
1739
1740       -no_fifo
1741              obsoleted by -no-fifo
1742
1743       -no-fifo
1744              Don't  use  a  fifo to optimize data flow from/to tarfile.  Cur‐
1745              rently the -fifo option is used as default. (This may be changed
1746              at compile time.)
1747
1748       -no-fsync
1749              Do  not call fsync(2) for each file that has been extracted from
1750              the archive.  Using -no-fsync may speed up extraction on operat‐
1751              ing  systems with slow file I/O (such as Linux with any filesys‐
1752              tem or platforms with Copy on Write filesystems like  ZFS),  but
1753              includes the risk that star may not be able to detect extraction
1754              problems that occur after the call to close(2).  A typical cause
1755              for  such problems is a NFS file system that fills up before the
1756              buffer cache is synced or a write error that  occurs  while  the
1757              buffer  cache  is synced.  There may be other reasons.  Use with
1758              extreme care.
1759
1760              See  also  -do-fsync   and   STAR_FSYNC   in   ENVIRONMENT   and
1761              /etc/default/star for ways to configue the default behavior.
1762
1763       -nochown, -o
1764              Do  not  restore  owner and group of files.  This may be used if
1765              super user privileges are needed to overwrite existing files but
1766              the local ownership of the existing files should not change.
1767
1768       -no-p  Do  not  restore files and directories to their original permis‐
1769              sions.  This option is needed only if  star  is  called  by  the
1770              super  user  and the permissions should not be restored from the
1771              archive.  See also the -p option. The -p options  has  a  higher
1772              precedence than the -no-p option.
1773
1774       -no_statistics
1775              obsoleted by -no-statistics
1776
1777       -no-statistics
1778              Do not print statistic messages at the end of a star run.
1779
1780       -no-secure-links
1781              Extract  hard  links or symbolic links even if the target of the
1782              link starts with a slash (/) or if /../ is contained in the link
1783              target.  See the description of the option -secure-links below.
1784
1785       -no-xheader
1786              Do  not  create  or extract POSIX.1-2001 extended headers.  This
1787              option may be used if you like to read an  archive  with  broken
1788              extended headers.
1789
1790       -not, -V
1791              Invert  the  meaning  of  the pattern list. i.e. use those files
1792              which do not match any of the pattern.  Note  that  this  option
1793              only  applies  to patterns that have been specified via the pat‐
1794              tern=pattern or pat=pattern option. Patterns specified  as  file
1795              type arguments will not be affected.
1796
1797       -notarg, -pax-c
1798              Match  all file or archive members except those specified by the
1799              pattern or file operands.
1800
1801       -nowarn
1802              Do not print warning messages.  This sometimes is useful to make
1803              the  output  more readable (e.g. when hundreds of files that are
1804              going to be extracted are not newer in the archive then  on  the
1805              filesystem).
1806
1807       -numeric
1808              Use the numeric user/group fields in the listing rather than the
1809              default.  The default  allows  to  list  the  ASCII  version  of
1810              user/group  of  the  file and to extract the owners of the files
1811              based on numeric values rather than the names.  In create  mode,
1812              no  user/groups  names  are  put  on  the archive.  The -numeric
1813              option also applies when  ACLs  are  going  to  be  archived  or
1814              extracted.
1815
1816       -O     Be  compatible  to old versions of tar.  If star is invoked with
1817              this option, star generates archives which are fully  compatible
1818              with old UNIX tar archives. If in extract mode, star ignores any
1819              additional info in the headers.  This implies neither  that  ar‐
1820              chives generated with this option are binary equal with archives
1821              generated by old tar versions nor that star is trying to compre‐
1822              hend  all  bugs  that are found in old tar versions.  The bug in
1823              old tar versions that cause a reversal of a  space  and  a  NULL
1824              byte in the checksum field is not repeated.  If you want to have
1825              signed checksums you have to specify the -signed-checksum option
1826              too.   If you want directories not to be archived in order to be
1827              compatible to very old historic tar archives, you need to  spec‐
1828              ify the -d option too.
1829
1830              This option is superseeded by the H=headertype option.
1831
1832       -o, -nochown
1833              Do  not  restore  owner and group of files.  This may be used if
1834              super user privileges are needed to overwrite existing files but
1835              the local ownership of the existing files should not change.
1836
1837       -onull, -nullout
1838              Do  not  actually  write  to the archive but compute and add the
1839              sizes.  This is useful when trying to figure out if a  tape  may
1840              hold  the  current backup.  Please only use the -onull option as
1841              it is a similar option as used by the sdd(1) command.
1842
1843       -P     Allow star to write a partial record as the last  record.   Nor‐
1844              mally,  star writes each record with the same size.  This option
1845              is useful on unblocked tapes i.e. cartridge tapes like QIC tapes
1846              as  well as with archives that are located in files.  If you use
1847              this option on local files, the size  of  the  archive  will  be
1848              smaller.   If  you  use this option on cartridge tapes, is makes
1849              sure that later - in extract mode - star will read up to the end
1850              of  file  marker on the tape and the next call to star will read
1851              from the next archive on the same tape.
1852
1853       -p     Restore files and directories  to  their  original  permissions.
1854              Without  this  option, they are created using the permissions in
1855              the archive and the present umask(2).  If star is called by  the
1856              super  user,  star  behaves as if it has been called with the -p
1857              option. See also -no-p option.  If the archive  contains  Access
1858              Control Lists (ACLs) in POSIX.1-2001 extended headers, star will
1859              restore the access control lists from the archive for  files  if
1860              the  -acl  option is specified.  If the option -acl has not been
1861              specified, ACLs are not restored at all.
1862
1863       -partial
1864              Force an incremental restore even if  the  incremental  dump  is
1865              only  a partial dump. See -wtardumps, level= and sections INCRE‐
1866              MENTAL BACKUPS and INCREMENTAL RESTORES for more information.
1867
1868       pattern=pattern, pat=pattern
1869              Set matching pattern to pattern.  A maximum of  100  pattern=pat
1870              options  may  be  specified.   As  each  pattern is unlimited in
1871              length, this is no real limitation.  If more than one pattern is
1872              specified,  a  file  matches  if  any  of  the specified pattern
1873              matches.  Patterns may be used  in  create  mode  to  select  or
1874              exclude  files from the list of file type arguments or the files
1875              located in a sub tree of a file  type  argument  directory.   By
1876              default, star scans the whole directory tree underneath a direc‐
1877              tory that is in the argument list. This may be modified by using
1878              the  -match-tree option.  In extract or list mode, all file type
1879              arguments are interpreted to be select pattern  and  all  option
1880              type patterns may be either select or exclude patterns depending
1881              on the presence or absence of the -not option.  If you use  file
1882              type  select patterns, they work exactly like the method used by
1883              other (non pattern aware)  tar(1)  implementations.   File  type
1884              select  patterns  do  not  offer  pattern  matching but allow to
1885              restore subtrees.  To extract  a  complete  sub  tree  from  the
1886              directory  dir with star using the pattern= option, use pattern=
1887              dir/\* if you like to select a subtree  by  using  the  historic
1888              method,  use  dir  as  file  type argument.  If you only like to
1889              extract the directory itself, use dir/ as  file  type  argument.
1890              See  manual  page  for  match(1) for more details of the pattern
1891              matcher.  All patterns are selection  patterns  by  default.  To
1892              make them exclude patterns, use the -not or the -V option.
1893
1894       pkglist=file
1895              This  is  (for  now) an internal interface for the Schily Source
1896              Package System (sps).  It only works in create mode and  behaves
1897              similar to the list= option, but it allows to overwrite the per‐
1898              missions, the uid  and  gid  values  from  the  content  of  the
1899              pkglist= file.  Each line from the pkglist= file contains a file
1900              name followed by the permission, a user name and a  group  name.
1901              The permission is an octal character string.  Each value that is
1902              not used to overwrite the original values may be replaced  by  a
1903              '?'.  The fields are separated by spaces, so the pkglist= option
1904              does not allow files that contain newline or space characters.
1905
1906       -pax-c, -notarg
1907              Match all file or archive members except those specified by  the
1908              pattern or file operands.
1909
1910       -pax-H Follow  symbolic links that have been encountered on the command
1911              line.  If the referenced file does not exist, the file  informa‐
1912              tion  and type will be for the link itself.  If the link is ref‐
1913              erencing a file type that cannot be archived  with  the  current
1914              archive  format,  the  file information and type will be for the
1915              link itself.
1916
1917       -pax-i Do interactive renaming in a way that has been defined for POSIX
1918              pax.   Star  will  print  the original filename and prompt for a
1919              reply.  If you type just RETURN, than the file is  skipped.   If
1920              you  type  '.', then the original file name is retained.  If you
1921              type anything else, then this is taken as the new file name.
1922
1923              Note that -pax-i is an interactive  option  that  prevents  star
1924              from being used in non-interactive environments.
1925
1926       -pax-L Follow  symbolic  links.  If the referenced file does not exist,
1927              the file information and type will be for the link  itself.   If
1928              the link is referencing a file type that cannot be archived with
1929              the current archive format, the file information and  type  will
1930              be for the link itself.
1931
1932       -pax-ls
1933              Switch  listing  format  to the format defined for POSIX pax and
1934              ls.
1935
1936       -pax-match
1937              Allow file type arguments to be recognised  as  regular  expres‐
1938              sions in a way that has been defined for POSIX pax.
1939
1940       -pax-n Allow  each  pattern to match only once.  If a pattern matches a
1941              directory, then the whole sub tree matches the pattern.
1942
1943       -pax-o string
1944              Set a pax like option control pattern.
1945
1946              The only argument that is currently supported is binary to  cre‐
1947              ate a hdrcharset=BINARY header.
1948
1949       -pax-p string
1950              PAX  style  privileges string.  Several characters (each has its
1951              own meaning). The following characters are defined:
1952
1953              a      Do not preserve file access times.  This option  is  cur‐
1954                     rently ignored.
1955
1956              e      Preserve  the user ID, group ID, file mode bits.  This is
1957                     equivalent to calling star -p -acl -xfflags.
1958
1959              m      Do not preserve file modification times.   This  is  cur‐
1960                     rently equivalent to calling star -m.
1961
1962              o      Preserve  the  user ID and group ID.  This is the default
1963                     for star if called as root.
1964
1965              p      Preserve the file mode bits.  This is equivalent to call‐
1966                     ing star -p.
1967
1968       -prinodes
1969              Print inode numbers in verbose list mode if the archive contains
1970              inode numbers.
1971
1972       -print-artype
1973              Check the type of the archive, print the archive and compression
1974              type on a single line and exit.
1975
1976       -qic24 Set  tape  volume  size to 61440 kBytes.  See tsize=# option for
1977              more information.
1978
1979       -qic120
1980              Set tape volume size to 128000 kBytes.  See tsize=#  option  for
1981              more information.
1982
1983       -qic150
1984              Set  tape  volume size to 153600 kBytes.  See tsize=# option for
1985              more information.
1986
1987       -qic250
1988              Set tape volume size to 256000 kBytes.  See tsize=#  option  for
1989              more information.
1990
1991       -qic525
1992              Set  tape  volume size to 512500 kBytes.  See tsize=# option for
1993              more information.
1994
1995       -read0 Read null terminated file names from the file specified with the
1996              list= option.
1997
1998       -refresh_old_files
1999              obsoleted by -refresh-old-files
2000
2001       -refresh-old-files
2002
2003       -refresh
2004              Do  not  create  new  files.  Only already existing files may be
2005              overwritten from tarfile if either newer versions are present in
2006              the archive or if the -U flag is used.  This allows to overwrite
2007              files by more recent files from an archive  that  contains  more
2008              files  than  the  target  directory  should contain.  The option
2009              -refresh-old-files is the same as the -refresh option.
2010
2011       -remove_first
2012              obsoleted by -remove-first
2013
2014       -remove-first
2015              Remove files before extraction.  If this option  is  in  effect,
2016              star  will  remove  files  before extracting a file from the ar‐
2017              chive.  This is needed if you want to change the file type or if
2018              you  need  to  break  a  hard  link.   If  you do not use either
2019              -ask-remove or -force-remove together with  -remove-first,  this
2020              option is useless and no files will be removed.
2021
2022       -remove_recursive
2023              obsoleted by -remove-recursive
2024
2025       -remove-recursive
2026              Remove  files  recursive.   If  removing of a file is permitted,
2027              star will only remove files, specials and empty directories.  If
2028              this  option  is  in effect, star will be allowed to recursively
2029              removes non empty directories too.
2030
2031       -restore
2032              switches star into true incremental restore mode.  A file  named
2033              star-symtable  and  a  directory named star-tmpdir is created in
2034              the root directory of the file system where the extraction takes
2035              place.  If -restore has been specified, star behaves as if -xdot
2036              has been specified too.  See  also  level=  option  and  section
2037              INCREMENTAL BACKUPS for more information.
2038
2039              Note: Do not use the -restore option if you only like to restore
2040              a single file or a list of selected files.
2041
2042       rmt=path
2043              Specify the path to the program at the remote  tape  server  for
2044              the RMT protocol.
2045
2046              star by default calls the UNIX default path /etc/rmt.
2047
2048              Since  most  rmt  implementations  cause  problems  in case that
2049              server and client are on a different OS, it  is  recommended  to
2050              tell  star  to  call  the  rmt  program  that  comes  with  star
2051              (/opt/schily/sbin/rmt).
2052
2053       rsh=path
2054              Specify the program to log into the remote tape server  for  the
2055              RMT  protocol.  If the argument is the empty string, connections
2056              are made via rcmd(3).  The default method to log into the remote
2057              server  is  configurable at compile time. The current default is
2058              set up to use ssh.
2059
2060       -S     Do not store/create special files.  A special files is any  file
2061              except plain files, symbolic links and directories.  You need to
2062              be super user to extract special files.
2063
2064       -s replstr
2065              Modify file or archive member names named by a pattern according
2066              to  the  substitution expression replstr.  The format of replstr
2067              is:
2068
2069                   -s /old/new/[gp]
2070
2071              The old pattern may use regular expressions and the  new  string
2072              may contain the special character '&'. The character '&' is sub‐
2073              stituted by the  string  that  matches  the  old  pattern.   The
2074              optional  trailing  'g' means global substitution. If 'g' is not
2075              used, a substitution pattern is only used once on  a  name.   If
2076              the  optional  trailing 'p' is used, the substitution is printed
2077              to standard error.
2078
2079              Up to 100 substitute options may be used. If more than one  sub‐
2080              stitute  option has been specified, star will loop over all sub‐
2081              stitute patterns until one matches.
2082
2083              If the name  substitutes  to  the  empty  string,  the  file  is
2084              skipped.
2085
2086       -secure-links
2087              Do not extract hard links or symbolic links if the target of the
2088              link starts with a slash (/) or if /../ is contained in the link
2089              target.   Tar  archives  containing  such links could be used to
2090              compromise the system. If they are unpacked together with a  lot
2091              of other files, this may not even be noticed.
2092
2093              Links  that  do  not point outside the tree that starts with the
2094              current working directory are not seen as a security risk.  This
2095              makes  star easy to use.  It is always safe to unpack an unknown
2096              archive in an empty directory.
2097
2098              Many system installations contain plenty of symbolic links  with
2099              absolute  path name or with /../ inside.  The usability of a tar
2100              archiver for system backups would be  limited  if  -secure-links
2101              checking would be done by default for backups as well, star thus
2102              makes link  checking  optional  when  in  -restore  mode.   When
2103              -restore  has  not been specified, link checking is the default,
2104              since this is the usual way where archives from unknown  sources
2105              are going to be unpacked.
2106
2107              To  turn  off  this  default  for  the  usual  case,  the option
2108              -no-secure-links may be used and in -restore mode, -secure-links
2109              may be specified to turn it on.
2110
2111              If  you  unpacked a tar archive while -secure-links is effective
2112              and did not get a security warning at the end of the  star  run,
2113              all  files and links have been extracted.  If you get a warning,
2114              you should unpack the archive a  second  time  and  specify  the
2115              options  -k,  -w and -nowarn in addition to the options used for
2116              the first run.  To speed this up, it helps to use:
2117
2118                  star -xvpw -find -type l
2119
2120              See SECURITY NOTES for more information.
2121
2122       -shm   Use System V shared memory for fifo.  Normally star is  compiled
2123              to  use  mapped  /dev/zero  pages for the fifo, if the operating
2124              system supports this.  If star is compiled to have both code for
2125              mapped  pages  and  for  System  V  shared memory, star will use
2126              shared memory instead of the default.  If the -help menu doesn't
2127              show  the  -shm  flag  you  have no choice.  When using System V
2128              shared memory, you may have to raise the system's internal limit
2129              for  shared  memory  resources  to  get enough shared memory for
2130              star.
2131
2132       -signed_checksum
2133              obsoleted by -signed-checksum
2134
2135       -signed-checksum
2136              Use signed chars to calculate checksums. This violates  the  tar
2137              specs  but  old versions of tar derived from the seventh edition
2138              of UNIX are implemented in this way.  Note: Only  filenames  and
2139              linknames containing chars with the most significant bit set may
2140              trigger this problem because all other fields only contain 7 bit
2141              ASCII characters, octal digits or binary zeroes.
2142
2143       -silent
2144              Suppress informational messages like foobar is sparse.
2145
2146       -sparse
2147              Handle  files with holes effectively on store/create.  Note that
2148              sparse files may not be archived this way if the archive  format
2149              is tar, ustar, suntar, pax, or any cpio variant.  On Solaris-2.3
2150              ... Solaris-2.5.1 there is a special ioctl() called _FIOAI  that
2151              allows  root  to  get  the allocation info more efficiently.  On
2152              Solaris 11 there is an enhanced lseek(2)  call  with  additional
2153              whence  values  SEEK_HOLE and SEEK_DATA that allow to find holes
2154              in an efficient way.  Other operating systems  lack  support  to
2155              get the real allocation list and force star to scan the files to
2156              look for blocks that only contain  null  characters.   This  may
2157              star  cause  to  assume more holes to be present than the number
2158              that the file really contains.
2159
2160       -symlinks
2161              This option tells star in extract mode to try to create  a  sym‐
2162              link whenever a hardlink is encountered in the archive.
2163
2164       -T     If  the  option  file=  or  f=  is  omitted and the -T option is
2165              present, star will use the device indicated by the TAPE environ‐
2166              ment variable, if set.
2167
2168       tardumps=name
2169              Set  the  file  name  for  tar dump dates database to name.  The
2170              default name is /etc/tardumps.   Use  in  combination  with  the
2171              level= option to create true incremental dumps.  See also -wtar‐
2172              dumps option and section INCREMENTAL BACKUPS for  more  informa‐
2173              tion.
2174
2175       -time  Print timing info.  See DIAGNOSTICS for more information.
2176
2177       -to_stdout
2178              obsoleted by -to-stdout
2179
2180       -to-stdout
2181              Extract  files  to  stdout.  This  option may be used to extract
2182              tarfiles containing tarfiles (see examples below).
2183
2184       -tpath Use this option together with the -t option or with -cv (verbose
2185              create)  to get only a list of the pathnames of the files in the
2186              archive.  This may be used in shell scripts to generate  a  name
2187              list.   If  used  together with the -diff option, star will only
2188              print the names of the files that differ.  A second run of  star
2189              may  then  be  used to restore all files that had differences to
2190              the archive.  Use the list= option to specify  the  namelist  in
2191              this case.
2192
2193       tsize=#
2194              Set  tape  volume size to # to enable multi volume tape support.
2195              The value refers to the archive size without  compression.   See
2196              bs=  for  the possible syntax.  By default, the number is multi‐
2197              plied by 512, so the value counts in units of 512  byte  blocks.
2198              If the size specifier ends with a valid multiplication character
2199              (e.g '.' for bytes or 'M' for MB) the specified size is used  as
2200              specified  and  not  multiplied  by  512.   With  this option in
2201              effect, star is able to archive filesystems that are bigger then
2202              the  tape size.  If the option tsize=# without -multivol then no
2203              file will be split across volumes and each volume may in  theory
2204              be read back separately.  Files that do not fit on a single tape
2205              may not be stored in this mode.  If -multivol has been specified
2206              in addition, star will split files when the maximum allowed tape
2207              size has been reached.  If the tape volume size is not a  multi‐
2208              ple  of  the  tape  block size, the tape volume size is silently
2209              rounded down to a value that is a multiple  of  the  tape  block
2210              size.
2211
2212              See -multivol option for more information.
2213
2214       -U     Restore  files  unconditionally.  By default, an older file from
2215              the archive will not replace a corresponding newer file on disk.
2216
2217       umask=mask
2218              Set star's umask to mask.  This allows to  control  the  permis‐
2219              sions  for  intermediate directories that are created by star in
2220              extract mode.  See also -p option.
2221
2222       -uncond-rename
2223              When in interactive restore mode or when the -s option was spec‐
2224              ified,  unconditionally  ask for a new name or apply a substitu‐
2225              tion.  This happens even when the current  path  name  would  be
2226              skipped  otherwise  because the file in the archive is not newer
2227              than the file with the original name on disk.
2228
2229       -v     Increment verbose level by one.  This normally results  in  more
2230              output during operation.  See also in the description for the -t
2231              flag.  Normally, star does its work silently.   If  the  verbose
2232              level  is  2  or more and star is in create or update mode, star
2233              will produce a listing to the format of the ls -l output.
2234
2235       -V, -not
2236              Invert the meaning of the pattern list.  i.e.  use  those  files
2237              which  do  not  match any of the pattern.  Note that this option
2238              only applies to patterns that have been specified via  the  pat‐
2239              tern=pattern  or  pat=pattern option. Patterns specified as file
2240              type arguments will not be affected.
2241
2242       -version
2243              Print version information and exit.
2244
2245       VOLHDR=name
2246              Use name to generate a volume header.
2247
2248       -w     Do interactive creation, extraction or renaming.  For every file
2249              that  matches  the  list  of patterns and that has a more recent
2250              modification time in the tar archive (if in extract mode and the
2251              -U option is not specified) star prints its name and asks:
2252
2253                     get/put ? Y(es)/N(o)/C(hange name) :
2254
2255              You  may answer either `N' for No or <Return> to skip this file.
2256              If you answer `Y' the file is extracted or archived on tape with
2257              its  original  name.   If you answer `C', you are prompted for a
2258              new name. This name is used for the filename on disk if star  is
2259              in  extract  mode  or  for the archive name if star is in create
2260              mode.
2261
2262       See SECURITY NOTES for more information.
2263
2264       Note that -w is an interactive option that  prevents  star  from  being
2265       used in non-interactive environments.
2266
2267       -wready
2268              This  option  tells Star to wait up to two minutes for the drive
2269              to become ready.  It has been added as a hack for a bug  in  the
2270              SunOS/Solaris  st  device  driver.  This  driver has problems to
2271              sense the loading time with Exabyte  drives  with  factory  set‐
2272              tings.   It  also  makes sense to use -wready if multiple remote
2273              backups are made. In this case, the remote connection is  closed
2274              while  the  remote tape server is still writing a file mark.  If
2275              another remote backup is initiated before the old remote  server
2276              did  finish  to  write  the file mark, it would be impossible to
2277              open the tape driver unless -wready is specified to tell star to
2278              wait for the drive to become ready again.
2279
2280       -wtardumps
2281              Tell  star  to  update the file that contains the tar dump dates
2282              data base if in dump mode.  If the dump is not a full dump,  the
2283              tar  dump  dates  data  base file is not written.  See also tar‐
2284              dumps=name and -C option or INCREMENTAL BACKUPS section for more
2285              information.
2286
2287       -X filename
2288              Use  the file filename as a file containing a list of path names
2289              to be excluded from the store/create/list/diff  operation.   The
2290              file filename must contain a list of path names, each on a sepa‐
2291              rate line.  Be careful with white space and note that path names
2292              in  the list may not contain new lines.  Multiple -X options may
2293              be used. Each argument must refer  to  a  file  containing  path
2294              names.   The  -X option has precedence before other options that
2295              select files to be included in the operation.   See  also  list=
2296              option.
2297
2298       -xattr Reserved for NFSv4 extended attributes.
2299
2300       -xattr-linux
2301              Store  and  extract  extended  file attributes as found on Linux
2302              systems.  This option only makes sense when creating or extract‐
2303              ing exustar archives as it is based on POSIX.1-2001 extended tar
2304              headers.
2305
2306              The method used in the current implementation could be  used  to
2307              store  and  extract extended file attributes from BSD too.  Note
2308              that the current implementation is not generic enough  to  cover
2309              more general extended file attribute implementations as found on
2310              Solaris.  If star starts  to  implement  a  method  that  covers
2311              extended file attributes on Solaris, the new method will be used
2312              then -xattr has been specified and -xattr-linux  will  refer  to
2313              the  old  method.  The method used with -xattr-linux may go away
2314              in the future.
2315
2316       -xcopy An alias for -copy -sparse -acl
2317
2318       xdebug=#, xd=#
2319              Set extended debug level to #.
2320
2321       -xdev, -M
2322              Do not descend mount points.  This is useful when doing  backups
2323              of complete file systems.  See NOTES for more information.
2324
2325       -xdir  Extract directories even if the corresponding directories on the
2326              archive are not newer.  This is useful when for some reason, the
2327              directories  are  recorded  after  their  content  (see -dirmode
2328              option), or when the permissions of some directories must be set
2329              in any case.  As the classical UNIX cpio program does not imple‐
2330              ment delayed directory permission and time stamp  setting,  cpio
2331              users  often  create archives in reverse order (directories past
2332              their content). For this reason, it makes  sense  to  use  -xdir
2333              while extracting cpio archives.
2334
2335       -xdot  Unconditionally  extract  the  first directory in the archive if
2336              the name of this directory is either '.' or './'.  This helps to
2337              extract archives in an expected way if the target directory is a
2338              newly created empty directory. As this directory is  newer  than
2339              the  top level directory in the archive, star would usually skip
2340              this directory during extraction.  The effect of this  directory
2341              is  as if -xdir has been specified but is switched off after the
2342              first directory has been found.
2343
2344       -xfflags
2345              Store and extract extended file flags as found on BSD and  Linux
2346              systems.  This option only makes sense when creating or extract‐
2347              ing exustar archives as it is based on POSIX.1-2001 extended tar
2348              headers.   See NOTES section for problems with -xfflags on Linux
2349              systems.
2350
2351       -xmeta Extract meta files as if they were files.   Meta  files  in  ar‐
2352              chives  are  plain files that do not contain any content data in
2353              the archive.  They may be created by using the -meta  option  in
2354              star's  create  mode.   Existing files are not overwritten. If a
2355              file is missing, a zero sized file is created.   If  the  option
2356              -meta  is  used  together  with  the option -force-hole, missing
2357              plain files are created as sparse empty files  of  the  original
2358              size.
2359
2360       -xz    run the input or output through a xz pipe - see option -z below.
2361
2362       -Z     run  the input or output through a compress pipe - see option -z
2363              below.
2364
2365       -z     run the input or output through a gzip pipe.  This is  currently
2366              a  quick  and dirty hack, that mainly will cover the most common
2367              usage to compress the tar output if it is a file.  No reblocking
2368              will  be  done, so this option will currently only make sense on
2369              plain files.  As the -bz the -j the -Z and the -z option are non
2370              standard,  it  makes sense to omit the -bz the -j the -Z and the
2371              -z options inside shell scripts if you are going  to  extract  a
2372              compressed  archive  that is located inside a plain file as star
2373              will auto detect compression and choose the right  decompression
2374              option  to extract.  The environment variable STAR_COMPRESS_FLAG
2375              may be used to specify one option for  gzip.   If  you  want  to
2376              write write compressed archives to tape, you should use
2377              star -c . | gzip | sdd ibs=4k obs=32k -fill of=/dev/rmt/1bn
2378              or
2379              star  -c  .  |  gzip  |  sdd  ibs=4k  obs=32k  -fill  ovsize=60m
2380              of=/dev/rmt/1bn
2381              if the tape can hold 60 MB.
2382
2383       -zstd  run the input or output through a zstd  pipe  -  see  option  -z
2384              above.
2385

INCREMENTAL BACKUPS

2387       Star  is  able to back up file system in full and incremental mode.  To
2388       allow incremental backups, the file system must implement POSIX  seman‐
2389       tics.
2390
2391       To be more verbose:
2392
2393       ·      The  filesystem needs to uniquely identify files by the two num‐
2394              bers st_dev (The filesystem ID or device ID of the  device  con‐
2395              taining  the  file)  and  st_ino (The file serial number).  If a
2396              file is renamed, these numbers need to be retained.   Both  num‐
2397              bers need to be a cardinal scalar that is expressible in a deci‐
2398              mal number.
2399
2400       ·      The filesystem needs to implement  at  least  two  time  stamps,
2401              st_mtime  the  file's  last  modification  time and st_ctime the
2402              file's last status change time.  Both time  stamps  need  to  be
2403              dealt  with  as  documented by the POSIX standard.  Both numbers
2404              need to be a cardinal scalar that is expressible  in  a  decimal
2405              number  or  as  a  decimal  number  that  counts in seconds plus
2406              another number that counts in fractions of a second.
2407
2408       ·      The filesystem needs to allow to rename files and directories by
2409              either calling rename(2), or link(2) and unlink(2).
2410
2411       ·      The  filesystem  needs  to  honor  and preserve the case of file
2412              names.
2413
2414       The incremental backup method used by star  depends  on  comparing  the
2415       time stamps of all files against the time of the last backup. Note that
2416       this method only works correctly if the level 0 backup and  all  higher
2417       level incrementals include the whole file system.  As star archives all
2418       inode meta data, star is able to detect renamed files by comparing  the
2419       inode numbers of all files while in incremental restore mode.
2420
2421       Detecting renamed files only works if star, while in backup mode, scans
2422       the whole file system tree for each full and incremental backup.   This
2423       will work in case no files are excluded and the dump starts at the root
2424       directory of a file system.  In case that no  files  are  renamed  from
2425       excluded  parts  to  included parts, partial backups may be taken also.
2426       Partial backups only make sense if a complete  directory  sub  tree  is
2427       excluded  (e.g. by using the pat= option) or if a partial backup starts
2428       at a sub directory that is not the root directory of the file system.
2429
2430       In case of a partial backup, it is important that no file or  directory
2431       will  ever  be  moved  outside  the scope and later move into the scope
2432       again. Moving files or directories  outside  the  scope  of  a  partial
2433       backup is detected as deletion and moving the files back into the scope
2434       does not make them appear in  an  incremental  backup  since  the  time
2435       stamps of files from inside renamed directories did not change.
2436
2437       Note that a backup must not include files that are mounted from another
2438       filesystem and a restore cannot be done with more than  one  filesystem
2439       as target.
2440
2441       Files  in the backup tree that are hidden under a mount point cannot be
2442       part of the backup as long as the backup is not done from a snapshot.
2443
2444       To create a level 0 dump call:
2445
2446       star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
2447           f=archive-name -C /filestem-mount-point .
2448
2449       To create a level 1 dump call:
2450
2451       star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
2452           f=archive-name -C /filestem-mount-point .
2453
2454       Do not forget the dot at the end of the command line that specifies the
2455       directory to start the operation.
2456
2457       Backups  from live filesystems should be avoided.  On operating systems
2458       that support file system snapshots, backups should be made from a read-
2459       only mount of a snapshot. Be careful that all files that have been cre‐
2460       ated between setting up a snapshot and starting an  incremental  backup
2461       may  be  missing  from  all  backups unless the dumpdate=name option is
2462       used.
2463
2464       If the system that is going to be backed up is not  acting  as  a  file
2465       server,  it  makes  sense  to shut down all services that may result in
2466       inconsistent file states before setting  up  the  filesystem  snapshot.
2467       After  the  filesystem  snapshot  has  been set up, the services may be
2468       restarted.
2469
2470       If the the system that is going to be backed up is  acting  as  a  file
2471       server,  it  may  be that services on remote clients cause inconsistent
2472       file states unless all such services that  remotely  access  files  are
2473       shut down before the snapshot is set up.
2474
2475       Star  includes  options  that  help to deal with file system snapshots.
2476       The following example backs up a file system on Solaris  using  a  file
2477       system snapshot from UFS:
2478
2479       echo > /tmp/snapstamp
2480
2481       mount -r `fssnap -F ufs -o \
2482           backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs` /mnt
2483
2484       star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
2485           f=archive-name dumpdate=/tmp/snapstamp \
2486           fs-name=/export/nfs -C /mnt .
2487
2488       First  a file with a current time stamp is created, then a snapshot for
2489       /export/nfs is created and mounted on /mnt.  The following star command
2490       then  creates  a level 0 backup from the file system using the time the
2491       snapshot was created and the original mount point of  the  file  system
2492       for /etc/tardumps and the archive header.
2493
2494       Note  that if the backup is done on a live file system, it may be unre‐
2495       liable. A typical problem problem in this context is caused by  growing
2496       log  files.   As growing files are not a real problem with backups, the
2497       best way of dealing with growing files is to set up a star  error  con‐
2498       trol  file  (see  errctl=  option)  and  to tell star to ignore growing
2499       files.
2500

BACKUP SCHEDULES

2502       Full (level 0) dumps should be made on a  regular  base  (e.g.  once  a
2503       month).   As  a full dump may take a long time and takes a lot of tape,
2504       it is wise to make higher level incremental dumps with  shorter  inter‐
2505       vals.   The  next  table  shows  a  dump level list that may be used if
2506       monthly full dumps take place:
2507
2508                          Sun   Mon   Tue   Wed   Thu   Fri
2509              Week 1:     0     10    10    10    10    5
2510              Week 2:     10    10    10    10    10    5
2511              Week 3:     10    10    10    10    10    5
2512              Week 4:     10    10    10    10    10    5
2513
2514       The level 10 dumps  made  between  Monday  and  Friday  accumulate  all
2515       changes  made  within the week, but you only need to restore the latest
2516       level 10 dump in order to get all changes back.  If you don't like  the
2517       size of the accumulated changes, use the following backup schedule:
2518
2519                          Sun   Mon   Tue   Wed   Thu   Fri
2520              Week 1:     0     20    30    40    50    5
2521              Week 2:     10    20    30    40    50    5
2522              Week 3:     10    20    30    40    50    5
2523              Week 4:     10    20    30    40    50    5
2524
2525       Note that in this case, 7 dumps need to be restored if the a crash hap‐
2526       pens at the worst case date (just before the Friday dump in week  2  or
2527       later).
2528
2529

INCREMENTAL RESTORES

2531       Incremental restores should be made to an empty file system (except for
2532       the lost+found directory).  Star is currently unable to perform  incre‐
2533       mental restores to a file system that contains active mount points.
2534
2535       Incremental restores should be run as root user.  Star supports private
2536       incremental dumps and restores run as an unprivileged  user,  but  this
2537       mode has been tested less frequently.
2538
2539       The  incremental  restore procedure starts with restoring the last full
2540       (level 0) dump. Then the latest incremental dump  of  each  dump  level
2541       (with ascending order of dump levels) need to be restored.
2542
2543       Let  us  assume the first example from the section BACKUP SCHEDULES for
2544       the backup schedule. If a disk crash happens before the  Thursday  dump
2545       of  week  3  has been made, the following restore procedure needs to be
2546       applied:
2547
2548       level 0
2549              starting with an empty disk, the full (level 0) dump from week 1
2550              is restored.
2551
2552       level 5
2553              after  the  level  0 restore has been finished, the level 5 dump
2554              from Friday in week 2 is restored.
2555
2556       level 10
2557              after the level 5 restore has been finished, the level  10  dump
2558              from Wednesday in week 3 is restored.
2559
2560       The  disk  now contains the same files as it did when the level 10 dump
2561       has been made on Wednesday of week 3.
2562
2563       To extract a level 0 dump call:
2564
2565       cd /extract-filestem-mount-point
2566       star -xpU -restore f=archive-name
2567
2568       This creates the directory star-tmpdir and the  database  star-symtable
2569       in the root directory of the new file system.  Subsequent restores with
2570       higher level backups depend on these files.
2571
2572       To extract a level 1 (or higher) dump call:
2573
2574       cd /extract-filestem-mount-point
2575       star -xpU -restore f=archive-name
2576
2577       In order to restore a partial dump, the -partial  option  needs  to  be
2578       specified.  This is to make sure that the user understands that renames
2579       to a path outside the scope of the partial dump may result in inconsis‐
2580       tencies during a restore.
2581
2582       In case there is a dump level mismatch or a reference date mismatch, it
2583       is possible to give a restore a chance by specifying the -force-restore
2584       option.
2585
2586       Note  that  the  environment  variable STAR_DEBUG exists, star does not
2587       remove files with link count 1 that have been removed between incremen‐
2588       tal  dumps. These files are moved to the directory star-tmpdir.  Before
2589       you start to extract the next incremental, you need to remove all files
2590       in star-tmpdir.
2591
2592

SYNCHRONIZING FILESYSTEMS

2594       Star  may  be  used  to synchronize filesystem content.  To do this, an
2595       initial copy of the current content of the source filesystem  needs  to
2596       be performed first.
2597
2598       To create an initial copy of a filesystem call:
2599
2600       star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
2601           -C /filestem-mount-point . | \
2602           star -xpU -restore -C /extract-target-dir
2603
2604       In order to perform subsequent synchronization of the target filesystem
2605       with the content of  the  source  filesystem,  a  modified  incremental
2606       dump/restore procedure may be used.
2607
2608       To copy incremental content of a filesystem call:
2609
2610       star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
2611           -cumulative -C /filestem-mount-point . | \
2612           star -xpU -restore -C /extract-target-dir
2613
2614       Note  that  like with backups in general, copies from a live filesystem
2615       should be avoided.  On operating systems that support file system snap‐
2616       shots,  copies  should be made from a read-only mount of a snapshot. Be
2617       careful that all files that have been  created  between  setting  up  a
2618       snapshot  and  starting  an  incremental  copy  may be missing from all
2619       copies unless the dumpdate=name option is used.
2620
2621       See section INCREMENTAL BACKUPS to learn how to modify the command line
2622       in case file system snapshots are used.
2623

SIGNALS

2625       If star handles a signal, it first prints the statistics.  Star handles
2626       the following signals:
2627
2628       SIGINT    usually generated by  ^C  from  the  controlling  tty.   Upon
2629                 receipt of a SIGINT, star prints statistics and exits.  If in
2630                 create mode i.e. storing files to archive, star finishes with
2631                 the current file to ensure that no partial file is written to
2632                 the archive, write an eof record and then exits.
2633
2634       SIGHUP    not to be generated from a tty. The actions are the  same  as
2635                 upon receipt of a SIGINT.
2636       SIGQUIT
2637       SIGINFO   usually  generated  by  ^\  from  the  controlling tty.  Upon
2638                 receipt of a SIGQUIT, star prints  statistics  and  continues
2639                 with  the  current  operation.  This  is  useful to watch the
2640                 progress of the current operation.
2641

EXIT STATUS

2643       The following exit values are returned. Note that the  negative  values
2644       are  only available to modern shells and programs that use waitid(2) on
2645       a POSIX OS and thus can retrieve the full 32  bits  of  the  star  exit
2646       code. The positive number variants are what you get when only the low 8
2647       bits from the exit code are available.
2648
2649       0      All files were processed successfully.
2650
2651       -4 / 252
2652              Star has been interrupted in create mode and the end of star has
2653              been  delayed  until  the  current  file  has been archived com‐
2654              pletely. This error is only used in case  that  no  other  error
2655              occured  and  the  tar  archive  only  has  become  shorter than
2656              expected.
2657
2658       -3 / 253
2659              Star has been called with the option -e, or the  errctl=  option
2660              has been used to mark the current error fatal.
2661
2662       -2 / 254
2663              One or more files could not be processed successfully.
2664
2665       -1 / 255
2666              Command line parsing error.
2667
2668       >0     Other positive exit codes: The errno of the call that caused the
2669              fatal error.
2670

EXAMPLES

2672       To get a listing in a way similar to ls -l one might use:
2673
2674              example% star -tv f=/dev/rmt/1bn
2675
2676       The same command as listed above in a POSIX  tar  command  line  syntax
2677       compliant way is:
2678
2679              example% star tvf /dev/rmt/1mbn
2680
2681       To  copy the directory tree in /home/someuser to the directory /home/fs
2682       use:
2683
2684              example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)
2685
2686       or by using the change directory option of star:
2687
2688              example% star -c -C /home/someuser . | star -xp -C /home/fs
2689
2690       Note that both examples above are not the optimum way to copy a  direc‐
2691       tory  tree. A more efficient way to copy a directory tree is to use the
2692       -copy option.
2693
2694              example% star -copy -p -xdot -C /home/someuser . /home/fs
2695
2696       To copy a file tree including the Access Control List entries  for  all
2697       files and to correctly copy sparse (holey) files use:
2698
2699              example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs
2700
2701       To compare the content of a tape to the filesystem one might use:
2702
2703              example% star -diff -v f=/dev/rmt/1bn
2704
2705       To compare two directory trees one might use:
2706
2707              example% star -c . | star -C todir -diff -v diffopts=!times
2708
2709       or better by using a method similar to the -copy method above:
2710
2711              example% star -c -diff -v diffopts=!times -C fromdir . todir
2712
2713       To compare all properties of two file trees, use:
2714
2715              example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir
2716
2717       To  extract  a backup of the /usr tree without all files residing below
2718       /usr/openwin one might use:
2719
2720              example% star -xp -V pat=openwin/\* f=/dev/rmt/1bn
2721
2722       To extract all .c files to src, all .o files to obj and all other files
2723       to /tmp one might use:
2724
2725              example% star -xp -C src '*.c' -C obj '*.o' -C /tmp '*' f=/dev/rmt/1bn
2726
2727       To  extract  files  from a zipped tar archive that is located on a read
2728       only filesystem e.g. a CD while having the shell's working directory on
2729       the CD one might use:
2730
2731              example% star -zxp -C /tmp f=star-1.1.tar.gz
2732
2733       to extract the files from the tar archive to the /tmp directory.
2734
2735       To backup a list of files generated by the find(1) command:
2736
2737              example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
2738
2739       Note  that this does not work if the file names from output of the find
2740       command include new line characters.
2741
2742       To extract a tarfile that contains a tarfile one might use:
2743
2744              example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
2745
2746       Pat, in this case should match the tarfile in the tarfile on tape  that
2747       should be extracted.
2748
2749       To  make a backup of the root filesystem to a tape drive connected to a
2750       remote machine, one might use:
2751
2752              example# cd /
2753              example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
2754
2755       You need a line in /etc/passwd like the following to enable this:
2756
2757              tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
2758
2759       And a .rhosts file in /etc/tapehome to allow  remote  connections  from
2760       the appropriate hosts.  Make sure that the file /etc/default/rmt exists
2761       and allows remote access to the requested tape drive.
2762
2763       To use a faster rcmd(3) connection  for  a  backup  to  a  remote  tape
2764       server, one might use:
2765
2766              example#  env  RSH=''  star  -cM  fs=128m  bs=63k f=tape@remote‐
2767              host:/dev/rmt/1bn .
2768
2769       Note that this requires root privileges.
2770
2771
2772       To repair a corrupted filesystem for which no recent backup exists,  do
2773       the following:
2774
2775              example# fsck -y /filesys
2776              example# mount /filesys
2777              example# cd /filesys
2778              example# star -xpk f=/dev/rmt/1bn
2779              example# mt -f /dev/rmt/1bn rewind
2780              example# star -diff -v diffopts=!times f=/dev/rmt/1bn
2781
2782       Now  check  the  differences  and  decide whether to restore additional
2783       files. This may be done by generating  a  list  containing  the  needed
2784       filenames  and  using the list= option or by using the interactive mode
2785       (see -w option).
2786
2787       If you want a list that only contains all  filenames  from  files  with
2788       differences you may use:
2789
2790              example# star -diff -tpath diffopts=!times f=/dev/rmt/1bn
2791
2792       If  you  are looking for files that changed the type or the access per‐
2793       mission because this is a common case on still corrupted files, use:
2794
2795              example# star -diff -tpath diffopts=type,perm f=/dev/rmt/1bn
2796
2797       If you like to archive all directories only that are part of the direc‐
2798       tory tree under ".", use:
2799
2800              example# star -c f=archive-name -find . -type d
2801
2802       If  you like to archive all files as owner root and group root and make
2803       all files world readable in the archive, use:
2804
2805              example# star -c f=archive-name -find . -chown root -chgrp  root
2806              -chmod o+r
2807
2808       If you like to archive all files with a mtime of now, use:
2809
2810              example# star -c f=archive-name -find . -chmtime now
2811
2812       If  you  like  to  list all files in an archive in a way like sfind(1),
2813       instead of the way used by star, use:
2814
2815              example# star -t f=archive-name -find . -ls -false
2816
2817

ENVIRONMENT

2819       STAR_COMPRESS_FLAG
2820              If you like star to always create compressed files that use max‐
2821              imum compression, you may set the environment variable STAR_COM‐
2822              PRESS_FLAG to -9.
2823
2824       STAR_DEBUG
2825              If this environment variable is present, star  will  not  remove
2826              temporary files from ./star-tmpdir.  The files in this directory
2827              are files that have been removed by users before the last incre‐
2828              mental dump did take place on the master filesystem.
2829
2830       STAR_FIFOSIZE
2831              If  you  like  to by default let star use a different fifo size,
2832              set this environment variable to the desired size.
2833
2834       STAR_FSYNC
2835              If set to `N', the  default  behavior  of  star  is  as  if  the
2836              -no-fsync option has always been specified.
2837
2838              This grants that star is always faster than other archivers, but
2839              makes it impossible for star to check whether the extracion of a
2840              file to the filesystem was successful.
2841
2842              If set to any other value, the default behavior of star is as if
2843              the -do-fsync option has always been specified.
2844
2845              The environment STAR_FSYNC has precedence over /etc/default/star
2846              but may still be overwritten by command line options.
2847
2848       STAR_WORKAROUNDS
2849              If  this  environment variable is present, implement workarounds
2850              for named problems.  The environment  variable  is  expected  to
2851              contain a comma separated list of bug names:
2852
2853              ssh-tcpip
2854                     implement  a workaround for a bug caused by ssh or TCP-IP
2855                     seen on Linux in 2003.  The bug caused the verbose output
2856                     from  star  on  stderr  to be lost when calling something
2857                     like:
2858
2859                         ssh host 'star -c ...'
2860
2861                     The workaround is activated when stderr is not  connected
2862                     to  a  terminal  and works by waiting for 0.1 seconds for
2863                     the output to appear.
2864
2865       TAPE   Unlike  other  tar(1)  implementations,  star  defaults  to  use
2866              stdin/stdout  for the archive.  If you like star to use the file
2867              name from the TAPE environment instead, you need to specify  the
2868              -T option too.
2869
2870       RSH    If  the  RSH  environment is present, the remote connection will
2871              not be created via the default method, but rather uses the  pro‐
2872              gram  specified  by RSH.  Use e.g.  RSH=/path/to/ssh to create a
2873              secure shell connection using a specific ssh version.
2874
2875              If the RSH environment is not present, the compiled  in  default
2876              is used.  This currently is ssh.
2877
2878              If the RSH environment is empty, then rcmd(3) is used.
2879
2880              Former  versions  of star by default did use rcmd(3) to create a
2881              remote connection.  Using a different method forces star to cre‐
2882              ate  a  pipe to the rsh(1) or ssh (1) program and disallows star
2883              to directly access the network  socket  to  the  remote  server.
2884              This  makes  it  impossible  to  work at maximum performance and
2885              slows down the connection compared to a root  initiated  rcmd(3)
2886              connection.
2887
2888              See rsh= option for more information.
2889
2890              See BUGS section for more information.
2891
2892       RMT    If  the  RMT environment is present, the remote tape server will
2893              not be the program /etc/rmt but the program pointed to  by  RMT.
2894              Note that the remote tape server program name will be ignored if
2895              you log in using an account that has been created with a  remote
2896              tape server program as login shell.
2897
2898              See rmt= option for more information.
2899

FILES

2901       /etc/default/star
2902              Default   values  can  be  set  for  the  following  options  in
2903              /etc/default/star.  For example: CDR_FIFOSIZE=64m
2904
2905              STAR_FIFOSIZE
2906                     Sets the default size of the FIFO (see also fs=# option).
2907
2908              STAR_FIFOSIZE_MAX
2909                     Sets the maximum size of the FIFO (see also fs=# option).
2910                     Setting  STAR_FIFOSIZE_MAX in /etc/default/star allows to
2911                     overwrite global values from backup scripts for  machines
2912                     with less memory.
2913
2914              STAR_FSYNC
2915                     If  set to `N', the default behavior of star is as if the
2916                     -no-fsync option has always been specified.
2917
2918                     This  grants  that  star  is  always  faster  than  other
2919                     archivers,  but  makes  it  impossible  for star to check
2920                     whether the extracion of a file  to  the  filesystem  was
2921                     successful.
2922
2923                     If  you  like to make the default fast, keep in mind that
2924                     you need to specify -do-fsync for cases where star  needs
2925                     to be able to know whether the extraction was successful.
2926
2927              archive0=
2928
2929              archive1=
2930
2931              archive2=
2932
2933              archive3=
2934
2935              archive4=
2936
2937              archive5=
2938
2939              archive6=
2940
2941              archive7=
2942                     Archive entries for the -[0..7] option.
2943
2944                     A   correct  archive?=  line  has  3..4  space  separated
2945                     entries.  The  first  is  the  device  entry  (e.g.   ar‐
2946                     chive0=/dev/tape).   The second is the blocking factor in
2947                     512 byte units.  The third is the maximum media  size  in
2948                     1024  byte  units.   If this entry contains a 0, then the
2949                     media size is unlimited.  The fourth entry  is  optional.
2950                     If it contains a 'n' or a 'N', then the archive device is
2951                     not a tape.
2952
2953                     Examples:
2954
2955                     archive0=/dev/tape 512 0 y
2956                     archive1=/dev/fd0 1 1440 n
2957                     archive2=/dev/rmt/0mbn 512 0
2958
2959                     If the default file does not need to be shared  with  the
2960                     tar  program  from Solaris, any number may be used like a
2961                     generic size option like bs=.
2962
2963                     Example:
2964
2965                     archive0=/dev/tape 256k 40G y
2966
2967       /etc/tardumps
2968              The default name for the dump level archive. The default name is
2969              used  whenever  the tardumps=name option has not been specified.
2970              The file is written or updated when -wtardumps is used.
2971
2972              The file holds one or more lines, each specifying a  dump  level
2973              entry.   Each  dump  level  entry starts with a mount point name
2974              followed by a TAB and one or more spaces, followed by the  deci‐
2975              mal dump level, a space and the dump time.
2976
2977              If  the  dump level is directly followed by a 'P', then the dump
2978              refers to a partial dump (a dump that does not include the whole
2979              filesystem).
2980
2981              The  dump time itself includes the decimal representation of the
2982              UTC seconds since Jan 01 1970, a space  and  the  textual  local
2983              time representation of the dump time.
2984
2985              The  numerical  decimal dump time representation may be followed
2986              by a dot and a sub second value.  The textual local time  repre‐
2987              sentation is for informational use by humans only and not evalu‐
2988              ated by star.
2989
2990       ./star-symtable
2991              Contains a database that is needed in incremental restore mode.
2992
2993       ./star-symdump
2994              Contains an intermediate dump of restore database after a  fatal
2995              error condition was met during an incremental restore operation.
2996
2997       ./star-tmpdir
2998              Is  the  temporary  directory  that is used as intermediate file
2999              storage by star if in incremental restore mode.
3000
3001       ./star-lock
3002              Is a lock  file  created  by  star  when  doing  an  incremental
3003              restore.  If this file is present, it prevents star from running
3004              another incremental restore operation. This helps to avoid  more
3005              than one restore operation at a time (e.g. from a cron script).
3006
3007       /dev/tty
3008              Is used for the interactive user interface.
3009

SEE ALSO

3011       spax(1),  scpio(1),  tar(1),  cpio(1),  pax(1),  rcp(1), mt(1), rmt(1),
3012       match(1),  dd(1),  sdd(1),  rsh(1),  ssh(1),  star_sym(1),  tartest(1),
3013       star(1), rcmd(3), fssnap(1m)
3014

DIAGNOSTICS

3016       star: f records + p bytes (total of x bytes = d.nnk).
3017
3018       The  number of full records, the number of bytes in partial records and
3019       the total amount of data in KBytes.
3020
3021       star: Total time x.yyysec (z kBytes/sec)
3022
3023       The time used and the transfer speed from/to the archive.
3024
3025       If there have been non fatal errors during the archive processing, star
3026       will display a delayed error summary before exiting.
3027
3028

NOTES

3030       The  command  line  syntax  for  the tar command (as defined in SUSv2 -
3031       UNIX-98) deviates from the command line syntax defined  for  all  other
3032       commands.  While  the POSIX command line syntax requests all options to
3033       start with a dash (-) and allows to either write options separately  or
3034       combined  (in  case  of  boolean  flags),  the  tar command line syntax
3035       requires all options to be combined into a single string that does  not
3036       start  with a dash.  Star by default assumes a command line syntax like
3037       a typical POSIX command and includes a compatibility mode  that  allows
3038       to specify a command line syntax as documented for the UNIX-98 tar com‐
3039       mand.  If you believe that you found a bug in the way star  parses  the
3040       command  line,  please  first  check  your command line for correctness
3041       before you make a bug report for star.
3042
3043       If you like to write portable shell scripts  that  call  tar,  use  the
3044       UNIX-98  tar  command  line  syntax (i.e. a single option string and no
3045       dash), choose the commands and options from the following set of  char‐
3046       acters  (  rxtuc  vxfblmo  ) and check the shell script with both, your
3047       local tar and star for correct behavior. It you expect  the  script  to
3048       call  gnutar,  do  not  include the -o option as gnutar implements this
3049       option in a way that violates UNIX-98.
3050
3051       Star strips leading ./ sequences from pathnames. This lets star in many
3052       cases store longer pathnames than other implementations.
3053
3054       The  POSIX.1-1988 method (ustar format) of storing files with pathnames
3055       that are longer than 100 chars has some limitations:
3056
3057              The name field (100 chars) an inserted slash (`/') and the  pre‐
3058              fix  field  (155  chars)  produce the pathname of the file. When
3059              recreating the original filename, name and prefix  are  concate‐
3060              nated, using a slash character in the middle. If a pathname does
3061              not fit in the space provided or may not be  split  at  a  slash
3062              character  so  that the parts will fit into 100 + 155 chars, the
3063              file may not be archived.  Linknames longer than 100  chars  may
3064              not be archived too.
3065
3066       The star, xstar, xustar, exustar, pax, and gnutar archive formats don't
3067       have these limitations. While gnutar uses a method that makes it impos‐
3068       sible  for other tar implementations (except star) to restore filenames
3069       that are longer than 100 chars, the xstar, xustar, exustar and pax/epax
3070       archive  format uses a method that allows an POSIX.1-1988 compliant way
3071       of storing filenames, if the POSIX method would allow this.   When  the
3072       archive  format  is xustar, exustar or pax/epax very long filenames are
3073       stored using extended headers from the POSIX.1-2001 standard.
3074
3075       Some buggy tar implementations will generate incorrect filenames during
3076       a  restore  operation if the archive contains pathnames or linknames of
3077       exactly 100 chars length.
3078
3079       Star adds a tar signature in the last four bytes of each tar header  if
3080       the  archive format is star or xstar.  This is no problem with the star
3081       archive format as it is an extension of the old  pre  POSIX.1-1988  tar
3082       format.   On  the  other side, the xstar archive format claims to be as
3083       POSIX.1-1988 compliant as possible.  Inserting this tar signature is  a
3084       minor  deviation  from  the standard that has the last 12 bytes of each
3085       header reserved for future use. On the other side, tar  implementations
3086       such  as  some  pax  implementations that only compute checksums on the
3087       first 500 bytes of the header are violating the standard that  requests
3088       the checksum to be computed on all 512 bytes of the tar header. All tar
3089       implementations that are 100% Posix compliant will be able  to  extract
3090       xstar  archives  as  long as no new standard is defined that claims the
3091       last 12 bytes of the header for a different use.  But  then  the  ustar
3092       version  number  should  be  changed  from `00' to `01'.  Now, that the
3093       POSIX-2001 standard has been accepted, it is even predictable that  all
3094       extensions  to  the  standard  tar format will go into the POSIX.1-2001
3095       extended headers which are extensible to include  any  feature  without
3096       future  limitation.   The  only known tar implementation that also uses
3097       the last 12 bytes of the tar header is Sun's tar which  uses  these  12
3098       bytes  for  files  that  are split over several archives. Such archives
3099       created by Sun's tar are not readable by the buggy  pax  implementation
3100       too.  The  Sun  extension  is  not  incompatible  to the star signature
3101       because Sun expects an octal number at the beginning  of  the  12  byte
3102       field which is a null character in the star case.
3103
3104       Star  uses these four bytes since 1985 without problems.  If you need a
3105       100% POSIX.1-1988 and 100% POSIX.1-2001 compliant tar archive, you  may
3106       use  the xustar, exustar or the pax/epax archive format.  The probabil‐
3107       ity of falsely detecting other tar formats as xustar or exustar  format
3108       however is higher.
3109
3110       There is no way to ask for the n-th occurrence of a file.
3111
3112       The  way  EOF is handled by star differs, whether the fifo is in effect
3113       or not.  If the fifo is not used, star stops reading the archive if  it
3114       encounters  a  logical EOF record in the archive.  If the fifo is used,
3115       star may read until the fifo is full or until the real EOF mark on tape
3116       is reached.  How much data star actually reads depends on the time when
3117       the star foreground process sends a fifo shutdown signal to  the  back‐
3118       ground fifo read process.
3119
3120       Gnu  tar  often  creates tar archives with incorrect logical EOF marks.
3121       The standard requires two blocks that are  completely  zeroed,  whereas
3122       gnutar often only adds one of them.
3123
3124       Old  versions  of  tar  found on SYSVr3 and earlier cannot read tar ar‐
3125       chives with a blocksize greater than 10 kBytes.
3126
3127       The method of storing sparse files currently used  with  the  star  and
3128       xstar  format  is  not guaranteed to be used in later versions of star.
3129       If the author decides to change this method, later versions of star may
3130       not  be able to restore sparse files from tar archives made by the cur‐
3131       rent version of star.
3132
3133       Some tar implementations violate the standard in using only  the  first
3134       500 Bytes of the header for checksum computation. These tar implementa‐
3135       tions will not accept star and xstar type tar archives.
3136
3137       Sun's Solaris 2.x tar implementation violates the Posix  standard.  Tar
3138       archives  generated  by  star  cause Sun's tar to print tar: impossible
3139       file type messages. You may ignore these messages.
3140
3141       Gnutar's dumpdirs are non standard and are currently not implemented.
3142
3143       If gnutar archives sparse files with more than four holes, it  produces
3144       archives  that  violate  the  standard in a way that prevents other tar
3145       implementations to read these archives.  Star knows about that  and  is
3146       able to handle these gnutar archives.
3147
3148       The  filetype  N  (LF_NAMES) from gnutar (an obsolete method of storing
3149       long names) will never be implemented.
3150
3151       Note that on operating systems (like DOS) that do  not  implement  real
3152       pipes,  star  implements  compression via a temporary file.  Using com‐
3153       pression thus is limited by the maximum file  size  and  the  available
3154       disk space.
3155
3156       The  extended  file flags implementation (see -xfflags option) on Linux
3157       is buggy by design.  In order to retrieve the needed information, every
3158       file  needs  to be opened.  If the /dev directory is included in create
3159       mode, every possible driver will be loaded which may  hang  the  system
3160       for  a long time. In the worst case, unwanted side effects from opening
3161       devices (such as causing tape  drives  to  rewind  the  media)  may  be
3162       caused.
3163
3164

SECURITY NOTES

3166       If  you unpack a tar archive in a non empty directory, any file in that
3167       directory may be overwritten unless you specify the -k option.  If  the
3168       archive  contains symbolic links or hard links, star may even overwrite
3169       files outside the current directory.  If the directory  where  the  ar‐
3170       chive  is  been  unpacked  is  not empty and contains contains symbolic
3171       links or hard links to directories outside  that  directory,  star  may
3172       also overwrite files outside the current directory.  As many other com‐
3173       mands, star usually has all possible  permissions  when  run  as  root.
3174       Unpacking  archives  as root thus may have fatal results to any file on
3175       your system.  Be very careful when you try to extract an  archive  that
3176       has  not been created by you. It is possible to create hand crafted tar
3177       archives that may overwrite critical files (like /etc/passwd)  on  your
3178       system.   In  addition all tar archives that have been created with the
3179       list= option and tar archives where the C=  option  was  not  specified
3180       before all file type arguments may be critical.
3181
3182       A  good  advise  is  to extract all doubtful archives as non root in an
3183       empty  directory  and  to  neither  specify  the   -/   nor   -..    or
3184       -no-secure-links  options.  If you get a warning, you should unpack the
3185       archive a second time and specify the options -k,  -w  and  -nowarn  in
3186       addition to the options used for the first run.
3187

SUID NOTES

3189       If  star  is  installed  suid root, star is able to make connections to
3190       remote archives for non root users.  This is done by using the  rcmd(3)
3191       interface to get a connection to a rmt(1) server.
3192
3193       Star  resets  its  effective  uid  back to the real user id immediately
3194       after setting up the remote connection to the  rmt  server  and  before
3195       opening any other file.
3196
3197       If  star  has  not  been installed suid root and not called by root, it
3198       will try to create the remote connection via rsh(1) or ssh(1) (in  case
3199       the  environment RSH has been set to ssh).  Note that in this case, the
3200       throughput to the remote tape server will be much  lower  than  with  a
3201       connection that has been initiated via rcmd(3).
3202

LIMITATIONS

3204       If star is running on a large file aware platform, star is able to han‐
3205       dle files up to 8 GB in a mode that is compliant  to  the  POSIX.1-1988
3206       ustar format. With a nonstandard star specific extension, up to 95 bits
3207       may be used to code  the  filesize.   This  will  handle  files  up  to
3208       200,000,000 TB.  With the new POSIX.1-2001 extended headers used by the
3209       xustar, exustar and pax/epax format, any filesize may be archived.
3210

BUGS

3212       The fact that the -f option has to be implemented in a way that is com‐
3213       patible  with  old  tar  implementations  gives  several problems.  The
3214       options -fifostats, -force-hole, -force-remove and -fifo interfere with
3215       the  -f  option  and the fact that they exist prevents users from using
3216       filenames like e.g.  ifo using the traditional way where  the  filename
3217       directly  follows  the  string  -f without any space between the option
3218       name and the file name.  However, there is no problem  to  use  a  file
3219       named  ifo  by by calling -f ifo, f=ifo, -f=ifo or -f= ifo.  Be careful
3220       not to make typos with the above options. The result could  be  that  a
3221       file is created as a result of the mistyped option.
3222
3223       There is currently no way to set the fifo lowwater and highwater marks.
3224
3225       If  you  ever  discover a hang in the fifo of star, get the process ids
3226       for both star processes, send both a RTMAX  signal  using  kill(1)  and
3227       report the disgnostic output.
3228
3229       There  is  currently no way to automatically delete files in the target
3230       file tree if they are obsolete.  Star should implement something  simi‐
3231       lar to gnutar's dumpdirs.
3232
3233       If  not invoked by the super user star may not be able to extract files
3234       if they reside in read only directories.
3235
3236       Star is not able to make a complete backup of a filesystem if files are
3237       hidden  by a mount that is in effect on a directory of this filesystem.
3238       This may be avoided in case of the ufs filesystem if the backup is made
3239       off a ufs snapshot (see the man page for fssnap(1m) It could be avoided
3240       for any filesystem if the loopback filesystem had an option that  tells
3241       lofs not to traverse mountpoints.
3242
3243       For now (late 2002), we know that the following programs are broken and
3244       do not implement signal handling correctly:
3245
3246       rsh    on SunOS-5.0...SunOS-5.9
3247
3248       ssh    from ssh.com
3249
3250       ssh    from openssh.org
3251
3252       Sun already did accept a bug  report  for  rsh(1)/ssh(1).   Openssh.org
3253       accepted and fixed a bug for their implementation of ssh(1).
3254
3255       If  you use star to create a remote connection via an unfixed rsh(1) or
3256       ssh(1), be prepared that terminal generated signals may  interrupt  the
3257       remote connection.
3258
3259

HISTORY

3261       A  tar  command appeared in Seventh Edition Unix, which was released in
3262       January, 1979. It replaced the tp  program  from  Fourth  Edition  Unix
3263       which replaced the tap program from First Edition Unix.
3264
3265       Star  was first created in 1982 to extract tapes on a UNIX clone (UNOS)
3266       that had no tar command.  In 1985 the first  fully  functional  version
3267       has been released as mtar.
3268
3269       When  the  old  star format extensions have been introduced in 1985, it
3270       was renamed to star (Schily tar).  In 1994,  Posix  1003.1-1988  exten‐
3271       sions were added and star was renamed to star (Standard tar).
3272
3273

AUTHOR

3275       Joerg Schilling
3276       Seestr. 110
3277       D-13353 Berlin
3278       Germany
3279
3280       Mail bugs and suggestions to:
3281
3282       joerg.schilling@fokus.fraunhofer.de or joerg@schily.net
3283
3284

SOURCE DOWNLOAD

3286       The source code for star is in the star project at Sourceforge at:
3287
3288           http://sourceforge.net/projects/s-tar/
3289
3290       The download directory is:
3291
3292           http://sourceforge.net/projects/s-tar/files/
3293
3294       Frequent  development snapshots of the star source are also included in
3295       the schilytools project and  may  be  retrieved  from  the  schilytools
3296       project at Sourceforge at:
3297
3298           http://sourceforge.net/projects/schilytools/
3299
3300       The download directory is:
3301
3302           http://sourceforge.net/projects/schilytools/files/
3303
3304       Check for the schily-*.tar.bz2 archives.
3305
3306
3307
3308Joerg Schilling                   2019/03/27                           STAR(1)
Impressum