Provided by: dar-static_2.4.8-1ubuntu1_amd64 bug

NAME

       dar - create, test, list, extract, compare, merge, isolate  dar archives

SYNOPSIS

       dar [-c | -x | -l | -d | -t | -C | -+] [<path>/]<basename> [<options>] [<user targets>]

       dar -h

       dar -V

DESCRIPTION

       dar is a full featured backup tool, aimed for disks (floppy, CD-R(W), DVD-R(W), zip, jazz,
       etc.) and since release 2.4.0 adapted to tapes.

       dar can store a backup in several files (called "slices" in  the  following)  of  a  given
       size,  eventually pausing or running a user command/script before starting the next slice.
       This can allow for example, the burning of the last generated slice on a CD-R, or changing
       a  floppy disk before continuing on the next one.  Like its grand-brother, the great "tar"
       command, dar may also use compression, at the difference that compression is  used  inside
       the  archive  to  be  able  to  have  compressed  slices of the defined size. But the most
       important feature of dar is its ability to make  differential  backups.  In  other  words,
       backups that contain only new files or files that have changed from a backup of reference.
       Moreover with differential backup, dar also stores files that have been deleted since  the
       backup  of  reference.  Thus,  when  restoring,  first  a  full  backup,  then  additional
       differential backups, at each restoration you get the exact state of the filesystem at the
       time  of  the  backup. And of course, the reference backup may be a full or a differential
       backup itself.

       dar is the first backup program I know that can also remove files during  restoration!  By
       the  way,  in  this  document,  "archive"  and  "backup" mean the same thing, and are used
       interchangeably.

       Unlike the tar command, dar has not to read a whole archive  to  know  its  contents:  dar
       archive  contains a table of contents (aka "catalogue") located at the end of the archive,
       so it seeks into the archive forth and backward to extract only the required files,  which
       is  much  faster  than  what  tar  is  used  to do. Since release 2.4.0 dar can also use a
       sequential reading mode, in which dar acts like tar, just reading byte by byte  the  whole
       archive  to know its contents and eventually extracting file at each step. In other words,
       the archive contents is located at both locations, all along the archive used for tar-like
       behavior  suitable  for  sequential access media (tapes) and at the end for faster access,
       suitable for random access media (disks).  However note that tar archive and  dar  archive
       are  not  compatible. Dar does not known anything about tar archive structure, neither tar
       known anything about dar archive structure. So keep using tar if you are  used  to  it  or
       find no advantage in using dar. Note also that the sequential reading mode let you extract
       data from a partially written archive (those that failed to complete due to a lack of disk
       space for example).

       Since  release  2.4.0,  a  "relax" reading mode is available that let dar to either ignore
       some incoherence in archive structure, or use internal redundant information  to  overcome
       what  seems to be data corruption, and in last resort ask the user on what to do when some
       archive structure information is missing. This relax mode can be used with both sequential
       and  direct access read modes. Note however that you should rather use Parchive to protect
       your data rather than just relying on the "relax" mode, which has to be seen as a the last
       chance  solution,  as  this  mode  cannot repair the archive, but may only lead to partial
       archive extraction upon archive corruption. For immediate Parchive integration  with  dar,
       use the "par2" user target defined in /etc/darrc.

       A few words about slice before going deeper in detail: a slice is just a simple file which
       name is composed of a "basename" followed by a dot, then a number, again  a  dot  and  the
       extension  (dar)  to  form  the filename of that slice. On the command line you will never
       have to give the full file name of a slice, just the basename. The number between the dots
       is  the  slice  number,  which  starts from 1 and may be arbitrary large (as large as your
       system can support the corresponding filename).

       Let's take an example:
                           considering the basename "joe", dar will make one  or  several  slices
                           during  backup  process  (depending  on your choice). The filenames of
                           these slices will be: joe.1.dar joe.2.dar ... joe.10.dar ... etc.   If
                           you  want  to extract, list, or use this backup as reference, you will
                           only have to use the basename, which  is  the  string  "joe"  in  this
                           example.

OPTIONS

       COMMANDS:

       Only  six  commands  define  what  action  will  be done by dar: Archive creation, archive
       extraction,  archive  listing,  archive  testing,  archive  comparison  with   filesystem,
       catalogue  isolation  and  archive  merging. These commands are described here below. Once
       defined, a large set of options can be used to modify the way the  command  is  performed.
       These  options  are described just after the commands chapter. Last, optional user targets
       may follow options, their use is described at the end of this document.

       Important note: Not all system actually support long options (Solaris, FreeBSD, ...).  For
       example  --create  will  not  be  available  on these systems, and you will have to use -c
       instead. In the same way, not all system do support optional  arguments  (FreeBSD  without
       GNU  getopt  for  example),  you then need to explicitly give the argument, for example in
       place of "-z" you will need to give "-z 9", see "EXPLICIT  OPTIONAL  ARGUMENTS"  paragraph
       near the end of this document for details on that point.

       -c, --create [<path>/]<basename>
                           creates  a  backup  with  the name based on <basename>. All the slices
                           will be created in the directory <path>  if  specified,  else  in  the
                           current  directory.  If  the  destination  filesystem  is too small to
                           contain all the slices of the backup, the -p  option  (pausing  before
                           starting  new  slices)  might  be  of  interest. Else, in the case the
                           filesystem is full, dar will suspend the  operation,  asking  for  the
                           user  to  make  free  space, then continue its operation. To make free
                           space, the only thing you cannot  do  is  to  touch  the  slice  being
                           written.  If  the filename is "-" *and* no slicing is asked for (no -s
                           option) the archive is produced on the standard  output  allowing  the
                           user  to  send  the  resulting  archive through a pipe (or into a tape
                           device).

       -x, --extract [<path>/]<basename>
                           extracts files from the given backup. Slices are expected to be in the
                           current  directory  or  in  the  directory given by <path>. It is also
                           possible to use symbolic links to gather slices that are  not  in  the
                           same directory. Path may also point to a removable device (floppy, CD,
                           etc.), in this case, to be able to mount/unmount the device, you  must
                           not  launch  dar  from  that  directory.  In  other words, the current
                           directory must not be that directory (see tutorial for  details).  The
                           basename  may  be  set  to  "-", in direct access mode (the default an
                           historical mode), you will need dar_slave to work with dar (see -i and
                           -o options, as well as dar_slave man page). However in sequential read
                           mode (--sequential-mode is used on command-line), dar  will  read  the
                           archive from standard input (see also -i option).

       -l, --list [<path>/]<basename>
                           lists  the  contents  of  the given backup.  dar will only require the
                           last slice of the archive in direct access mode. If however sequential
                           mode  is used, dar will read the overall archive, from the first slice
                           to the last one. "-" can be used as basename, the behavior is the same
                           as with -x option (read just above).

       -t, --test [<path>/]<basename>
                           checks  the backup integrity. Even without compression, dar is able to
                           detect at least one error  per  file  in  the  archive,  thanks  to  a
                           variable  length  CRC  recorded per file in the catalogue. Same remark
                           here, "-" may be used as basename (see -x option above for details).

       -d, --diff [<path>/]<basename>
                           compares saved files in the  backup  with  those  in  the  filesystem.
                           <basename> may also be "-" (see -x option above for details).

       -C, --isolate [<path>/]<basename>
                           isolate  a catalogue from its archive. The argument is the basename of
                           the file that will contain the catalogue. The -A option  is  mandatory
                           here  to  give  the name of the archive to extract the catalogue from.
                           Slicing is available (-s -S -p -b etc.). If the filename is "-"  *and*
                           no slice is asked (no -s option) the isolated catalogue is produced on
                           the standard output, allowing the user to send the  resulting  archive
                           through a pipe. Note that there is no difference in concept between an
                           isolated catalogue and an archive. Thus you can do all operation on an
                           isolated   catalogue,  in  particular  take  it  as  reference  for  a
                           differential archive. An archive produced with -C is almost equivalent
                           to differential archive done right after a full backup, (no data is in
                           it). Since release 2.4.0 you can use an isolated catalogue  to  rescue
                           the internal catalogue when it is corrupted (see -A option).

       -+, --merge [<path>/]<basename>
                           create  a  subset  archive  from  one  or  two  existing archives (the
                           resulting archive name is the argument to this command). The dar  file
                           selection  mechanism  (see below) let the user decide which files will
                           be present in the resulting archive and which  one  will  be  ignored.
                           This option thus let the user merge two archives in a single one (with
                           a filtering mechanism that accepts all files), as well as this  option
                           let  the user create a smaller archive which data is taken from one or
                           two archives of reference. Note that at no time the  contents  of  the
                           archives of reference is extracted to real files and directories: this
                           is an archive to archive transfer,  thus  you  may  lack  support  for
                           Extended  Attribute  while  you will be able to fully manipulate files
                           with their Extended Attributes from one archive to the resulting  one.
                           If  the  basename  is  "-" *and* no slice is asked (no -s option), the
                           archive is produced on standard output allowing the user to  send  the
                           resulting  archive  through  a  pipe.  The  first mandatory archive of
                           reference if provided thanks  to  the  -A  option,  while  the  second
                           "auxiliary"  (and optional) archive of reference is provided thanks to
                           the -@ option. When a tie contention occurs (same file names from both
                           archive have to be merged), the overwriting policy (-/ option) is used
                           to define the one to  keep  in  the  resulting  archive.  By  default,
                           archive  data selected for merging is uncompressed, and re-compressed.
                           Thus the merging operation can be used to change compression algorithm
                           of  given  archive  as  well as change its encryption. But, for better
                           performance it is also possible thanks to the -ak  option  (see  below
                           the  -ak  option  for  usage restrictions) to merge files keeping them
                           compressed, thus no decompression/re-compression is performed at  all,
                           which  make the operation faster. Last it is not possible to merge two
                           isolated catalogues.

       -h, --help          displays help usage.

       -V, --version       displays version information.

       GENERAL OPTIONS:

       -v, --verbose[=s[kipped]]
                           verbose  output.  --verbose  and  --verbose=skipped  are  independent.
                           --verbose=skipped  displays the files being excluded by filters, while
                           --verbose display actions under process. You can still use dar's  exit
                           status  to known which way the operation ended (seen EXIT CODES at the
                           end of this document).

       -q, --quiet         Suppress the final statistics report. If no verbose  output  is  asked
                           beside this option, nothing is displayed if the operation succeeds.

       -b, --beep          makes the terminal ring when user action is required (like for example
                           the creation of a new slice using the -p option)

       -n, --no-overwrite  do not allow overwriting of any slice.

                           If an overwriting policy is specified (see -/  option)  -n  option  do
                           only  apply  to  slices  overwriting,  the overwriting of files during
                           restoration or merging is handled by the overwriting policy. -n option
                           stay valid to forbid slice overwriting (merging, saving, isolation).

       -w, --no-warn       Do  not warn before overwriting (applied for slice overwriting and for
                           overwriting decision make  by  the  overwriting  policy).  By  default
                           overwriting is allowed but a warning is issued before proceeding. This
                           option may receive 'a' as argument (see just below):

       -wa, --no-warn=all  This implies the -w option, and means that over avoiding  warning  for
                           file  overwriting, DAR also avoid signaling a file about to be removed
                           when its type is not the expected one. File are removed when they have
                           been   recorded   as  deleted  since  the  archive  of  reference.  At
                           restoration of the differential archive, if a file of the  given  name
                           exists, it is remove, but if the type does not match the file that was
                           present at the time of the  archive  of  reference  (directory,  plain
                           file, fifo, socket, char or block device, etc.), a warning is normally
                           issued to prevent the accidental removal of data that was not saved in
                           the backup of reference. (See also -k option)

       -R, --fs-root <path>
                           The  path  points  to the directory tree containing all the files that
                           will be enrolled in the operation (backup, restoration or comparison).
                           By  default  the current directory is used. All other paths used in -P
                           or -g options on the command line are and must  be  relative  to  this
                           path  (or  to current directory if -R is not present). Note that -R is
                           useless for testing (-t option) isolation (-C option) and merging  (-+
                           option)

       -X, --exclude <mask>
                           The  mask  is  a  string  with wildcards (like * and ? see glob(7) for
                           details) which is applied to filenames which are not directories. If a
                           given  file  matches  the  mask, it is excluded from the operation. By
                           default (no -X on the command line), no  file  is  excluded  from  the
                           operation.  -X  may  be  present several times on the command line, in
                           that case a file will not be considered for the given operation if  it
                           matches at least one -X mask. See also -ar and -am options.

       -I, --include <mask>
                           The  mask  is  applied  to  filenames  which  are not directories (see
                           glob(7) for details on wildcard characters). If a given  file  matches
                           the  mask  and  does  not  match  any  mask given with -X, the file is
                           selected for the operation. By default (no -I and no -X on the command
                           line),  all  files  are  included for the operation. -I may be present
                           several times on the command line, in that case all  file  that  match
                           one of the -I mask will be considered for the given operation, if they
                           do not also match one of the -X mask. See also -ar and -am options.

       -P, --prune <path>  Do not consider file or directory sub-tree given by the path.  -P  may
                           be present several time on the command line. The difference with -X is
                           that the mask is not applied only to the filename,  but  also  include
                           the  path.  Moreover  it applies also to directories (-X does not). By
                           default (no -P on the command-line), no sub-tree or file  is  excluded
                           from  the  operation,  and  all the directory tree (as indicated by -R
                           option) is considered. Note that <path> may contains wildcards like  *
                           or ? see glob(7) man page for more information.

       -g, --go-into <path>
                           Files  or  directory to only take in account, as opposed to -P. -g may
                           be  present  several  time  on  command-line.  Same  thing  here,  the
                           difference  with  -I  is that the mask is applied to the path+filename
                           and also concerns directories. By  default  all  files  under  the  -R
                           directory  are  considered.  Else,  if one or more -g option is given,
                           just those are selected (if they do not  match  any  -P  option).  All
                           paths  given  this  way  must be relative to the -R directory. This is
                           equivalent as giving <path> out of any  option.   Warning,  -g  option
                           cannot receive wildcards, these would not be interpreted.

       -[, --include-from-file <listing_file>
                           Files  listed  in  the listing file are included for the operation. No
                           wildcard expression is interpreted  in  the  listing  file,  the  null
                           character  is  not allowed and the carriage return is used to separate
                           file names (one file name per line). Note that this option applies  to
                           any  files  and  directory  exactly  as  -g  does,  with  an important
                           difference however: -g option only uses relative  paths  to  the  root
                           directory  (the  directory given with the -R option), while -[ can use
                           absolute path as well. Another difference is when the  argument  is  a
                           directory -g will include all the subdirectories under that directory,
                           while when the same entry is found in a listing file given to -[  only
                           that  directory  will be included, no subdirectory or subfile would be
                           enrolled in the backup, with -[ you need to list the exact set of file
                           you  want  to  backup.  You  can thus generate a listing file with the
                           'find / -print > somefile' command and give 'somefile' as argument  to
                           -[  option. Note that however, dar will never save files out of the -R
                           given root directory tree, even if some are listed in  the  'somefile'
                           file.

       -], --exclude-from-file <listing_file>
                           Files listed in the listing file are excluded from the operation. If a
                           directory is listed in the file all its contents is  excluded  (unless
                           using ordered method and another mask includes some of its subfiles or
                           subdirectories). This option is the opposite of -[ and acts  the  same
                           was  as  -P  option  does  (in  particular it is compared to the whole
                           path+filename and applies to files and directories). As for -[ option,
                           -]  listing  file  can  contain  absolute paths, but wildcards are not
                           expanded, neither.

       File selection in brief:

       As seen above, -I -X -P, -g, -[ and -] options are used to select the files to operate on.
       -I  and -X only use the name of files and do not apply to directories, while -P, -g -[ and
       -] use the filename *and* the path, they *do* apply to directories.

       since version 2.2.0 two modes  of  interpretation  of  these  options  exist.  The  normal
       original method and the ordered method:

              the normal method is the default and is the one that has been presented above:
                   A  directory is elected for operation if no -P or -] option excludes it. If at
                   least one -g or -[ option is given one command line, one -g option must  cover
                   it,  else  it is not elected for operation. If a directory is not selected, no
                   recursion is done in it (the directory is pruned). For non directories  files,
                   the  same  is  true (P, -g, -[ and -] do apply) and a second test must also be
                   satisfied: no -X option must exclude the filename, and  if  at  least  one  -I
                   option is given, one must match the given filename (using or not wildcards).

              the ordered method (when -am option is given on command-line):
                   The  ordered  method  takes care of the order of presence between -X and -I in
                   one hand and of -P, -g, -[ and -] in the other hand (note that it has also the
                   same  action  concerning EA selection when using -u and -U options, but that's
                   no more file  selection).  In  the  ordered  method  the  last  argument  take
                   precedence over all the previous ones, let's take an example:

                   -X "*.mp?" -I "*.mp3" -I "toto*"
                        Here dar will include all files except file of name "*.mp?" (those ending
                        with "mpX" where X is any character), but it will however  include  those
                        ending with ".mp3". It will also include files which name begin by "toto"
                        whatever they end with. This way, "toto.mp2"  will  be  saved  (while  it
                        matches  "*.mp?"  it also begins by "toto") as well as "toto.txt" as well
                        as "joe.mp3" (while it matches "*.mp?" it also ends by "mp3").  But  will
                        not  be saved "joe.mp2" (because it does not begin by "toto", nor ends by
                        "mp3", and match "*.mp?" mask). As we see the  last  option  (-I  or  -X)
                        overcomes  the  previous one. -P, -g, -[ and -] act together the same but
                        as seen above they do  not  only  act  on  filename,  but  on  the  whole
                        path+filename.  Note  that (-g, -P, -[, -]) and (-X , -I) are independent
                        concerning their relative order. You can mix -X -I -g -P  -]  -[  in  any
                        order,  what  will  be  important is the relative positions of -X options
                        compared to -I options, and the relative positions of -g  -[  -]  and  -P
                        options between them.

              In  logical terms, if <prev_mask> is the mask generated by all previous mask on the
              command line, -I <mask> generates the new following mask: <prev_mask> or  <mask>  .
              While  -X <mask> generates the new following mask: <prev_mask> and not <mask>. This
              is recursive each time you add a -I or -X option. Things work the same with -P, -g,
              -[ and -] options.
       This ends the file selection explication let's continue with other options.

       -u, --exclude-ea <mask>
                           Do  not  consider the Extended Attributes (EA) that are matched by the
                           given mask. By default, no EA are excluded, if the support for EA  has
                           been  activated  at compilation time. This option can be used multiple
                           times.

       -U, --include-ea <mask>
                           Do only consider the EA that match the given mask. By default, all  EA
                           are  included  if no -u or -U option is present and if the support for
                           EA has been activated at compilation time. This  option  can  be  used
                           multiple  times.  See also the -am and -ae options, they also apply to
                           -U and -u options and read below the Note concerning EA.

       Note concerning Extended Attributes (EA)

              Support for EA must be activated at compilation time (the configure script tries to
              do  so  if your system has all the required support for that). Thus you can get two
              binaries of dar (of the same version), one supporting EA and another which does not
              (dar  -V to see whether EA support is activated). The archives they produce are the
              same and can be read by each other. The only difference is that the binary  without
              EA  support  is not able to save or restore EAs, but is still able to test them and
              list their presence.

              In the following when we will speak about Extended Attribute (EA) or EA  entry,  we
              will  only  consider  a  particular  Extended  Attribute  key  and  its  value.  By
              opposition, the set of all EA associated to a file will be designated by "EA set".

              Since version 2.3.x the name of EA entries include the namespace for dar be able to
              consider  any type of EA (not only "system" and "user" as previously). Thus the two
              previous options -u and -U have changed and now take an argument which  is  a  mask
              applied  to  EA  entry  names  written  in  the following form namespace.name where
              "namespace" is for example "user". Note that the mask may or may  not  include  the
              dot  (.)  and  may  match arbitrary part of the EA namespace+name, just remind that
              masks will be applied to the "namespace.name" global string.

              the -am flag here also enables the  ordered  method,  for  EA  selection  too.  The
              ordered  versus normal method have been explained above in the file selection note,
              with some examples using -X and -I. Here this is the same with  -U  and  -u,  (just
              replace  -X  by -u and -I by -U and remember that the corresponding mask will apply
              to Extended Attribute selection in place of file selection).

              Another point, independently of the -am option  the  -ae  option  can  be  used  at
              restoration  time only. If set, when a file is about to be overwritten, all EA will
              be first erased before restoring those selected  for  restoration  in  the  archive
              (according to the -U and -u options given). If not set, the EA of the existing file
              will be overwritten, those extra EA that are not in the archive or are not selected
              for  restoration  in regard to the -u and -U options will be preserved. If you have
              not used any -u/-U option at backup  time  and  want  to  restore  from  a  set  of
              full/differential  backups the EA exactly as they were, you have to use -ae for dar
              removes the EA before overwriting their set of EA as stored in the archive. Without
              -ae  option dar will simply add EA to existing ones, thus get a different set of EA
              for a give file than those recorded at the time of the backup.

              Last point the -acase and -an options alters the case sensitivity of the  -U and -u
              masks  that  follow  them on the command-line/included files as they do for -I, -X,
              -P, -g, -[ and -] as well. Very last point ;-), if -ac option is used during backup
              dar  set back the atime after having read each file (see -aa/-ac options), this has
              as side effect to modify the ctime date of each file. But ctime change is  used  by
              dar  to detect EA changes. In brief, the next time you backup a file that had to be
              read (thus which contents changed), its EA will be  saved  even  if  they  had  not
              changed. To avoid this side effect, don't use the -ac option if not necessary.
       This ends the Extended Attribute selection explication let's continue with other options.

       -i, --input <path>  is  available  when reading from pipe (basename is "-" for -x, -l, -t,
                           -d or for -A when -c, -C or -+  is  used).  When  reading  from  pipe,
                           standard input is used, but with this option, the file <path> (usually
                           a named pipe) is used instead.  This option is to receive output  from
                           dar_slave program (see doc/usage_notes.html for examples of use). Note
                           that when --sequential-read is used, dar uses a single pipe  and  does
                           no  more  rely  on  dar_slave, -i option can be used to tell dar which
                           named pipe to read the archive from, instead of the standard input.

       -o, --output <path> is available when reading from pipe (basename is "-" for -x,  -l,  -t,
                           -d  or  for  -A  when  -c,  -C or -+ is used). When reading from pipe,
                           standard output is used to send request to dar_slave,  but  with  this
                           option,  the  file <path> (usually a named pipe) is used instead. When
                           standard output is used, all messages goes to standard error (not only
                           interactive messages). See doc/usage_notes.html for examples of use.

       -O, --comparison-field[=<flag>]
                           When  comparing  with  the  archive  of  reference  (-c  -A)  during a
                           differential backup, when extracting (-x) or when  comparing  (-d)  do
                           only consider certain fields. The available flags are:

                           ignore-owner   all  fields  are considered except ownership.   This is
                                          useful when dar is used by a  non-privileged  user.  It
                                          will  not consider a file has changed just because of a
                                          uid or gid mismatch and at  restoration  dar  will  not
                                          even try to set the file ownership.

                           mtime          only   inode   type   and  last  modification  date  is
                                          considered as well as inode  specific  attributes  like
                                          file  size  for  plain  files.  Ownership  is  ignored,
                                          permission is ignored. During comparison, difference on
                                          ownership  or  permission is ignored and at restoration
                                          time dar will not try to set the inode  permission  and
                                          ownership.

                           inode-type     Only   the   inode   type   is  considered.  Ownership,
                                          permission  and  dates  are  ignored.  Inode   specific
                                          attributes  are  still  considered  (like file size for
                                          plain files). Thus comparison will  ignore  differences
                                          for ownership, permission, and dates and at restoration
                                          dar will not try to set the ownership,  permission  and
                                          dates.

       When  no flag is provided to this option, -O option acts as if the "ignore-owner" flag was
       set, which is the behavior in older releases  (<  2.3.0).  Note  also  that  for  backward
       compatibility, --ignore-owner option still exists and since version 2.3.0 is just an alias
       to the --comparison-field=ignore-owner option. Of course if this option is not  used,  all
       fields are used for comparison or restoration.

       -H[num], --hour[=num]
                           if  -H  is  used, two dates are considered equal if they differ from a
                           integer number of hours, and that number is  less  than  or  equal  to
                           [num]. If not specified, num defaults to 1. This is used when making a
                           differential backup, to compare last_modification date of  inodes,  at
                           restoration  or  merging time if overwriting policy is based on file's
                           data or EA being more recent and last, when comparing an archive  with
                           a filesystem (-d option). This is to workaround some filesystems (like
                           Samba filesystem) that seems to change the dates of files after having
                           gone  from  or to daylight saving time (winter/summer time). Note that
                           -H option has influence on the overwriting policy (see -/ option) only
                           if it is found before on command-line or in an included file (using -B
                           option).

       -E, --execute <string>
                           the string is a user command-line to be launched between  slices.  For
                           reading (thus using -t, -d, -l or -x options), the command is executed
                           before the slice is read or even  asked,  for  writing  instead  (thus
                           using -c, -C or -+ option), the command is executed once the slice has
                           been completed. Some substitution string can be used in the string:

                           %%        will be replaced by %

                           %p        will be replaced by the slice path

                           %b        will be replaced by the slice basename

                           %n        will be replaced by the slice number (to  be  read  or  just
                                     written).  For  reading, dar often needs the last slice, but
                                     initially it does not know its number. If it cannot be found
                                     in  the  current  directory,  the  user command-line is then
                                     called with %n equal to 0.  This  is  a  convenient  way  to
                                     inform  the user command to provide the last slice. If after
                                     it is still not present, dar asks the user (as usually) with
                                     a message on the terminal. Once the last slice is found, the
                                     user command-line is called a second time, with %n equal  to
                                     the value of the last slice number.

                           %N        is  the  slice  number  with  the leading zero as defined by
                                     --min-digits option. If this  option  is  not  used,  %N  is
                                     equivalent to %n.

                           %e        will  be replaced by the slice extension (always substituted
                                     by "dar")

                           %c        will be replaced by the  context.  Actually  three  possible
                                     values  exist:  "init",  "operation"  and "last_slice". When
                                     reading an archive for (testing, extraction, diff,  listing,
                                     or  while reading the archive of reference, see below the -F
                                     option), the "init" context takes place from  the  beginning
                                     up  to  the  time  the catalogue is retrieved. On a multiple
                                     slice archive this correspond to the first slice request and
                                     to  the  last  slice  requests.  After, that point comes the
                                     "operation" context.  While creating an archive, the context
                                     is  always  "operation"  except when the last slice has been
                                     created, in which case the context is set to "last_slice".
       Several -E option can be given, given commands will then  be  called  in  the  order  they
       appear  on  the  command  line,  and  included  files.  See  also the environment variable
       DAR_DUC_PATH in the ENVIRONMENT section at the end of this document.

       -F, --ref-execute <string>
                           same as -E but is applied between slices of the reference archive  (-A
                           option). --execute-ref is a synonym.

       -K, --key [[<algo>]:]<string>
                           encrypt/decrypt  the archive using the <algo> cipher with the <string>
                           as pass phrase. An encrypted archive can only be read if the same pass
                           phrase is given. Available ciphers are "blowfish" (alias "bf"), "aes",
                           "twofish",  "serpent"  and  "camellia"  for  strong   encryption   and
                           "scrambling" (alias "scram") for a very weak encryption. By default if
                           no <algo> or no ':' is given, the blowfish cipher is assumed. If  your
                           password  contains  a column ':' you need to specify the cipher to use
                           (or at least use the initial ':' which is equivalent to 'bf:'). If the
                           <string>  is  empty  the  pass phrase will be asked at execution time.
                           Thus, the smallest argument that -K can receive  is  ':'  which  means
                           blowfish cipher with the pass phrase asked at execution time.

       The old "blowfish_weak" implementation has been removed and is no more supported.

       Note  that  giving  the passphrase as argument to -K (or -J see below) may let other users
       learn pass phrase (thanks to the ps, or top program for examples).  It  is  thus  wise  to
       either  use  an  empty pass which will make dar ask the pass phrase when needed, or use -K
       (or -J option) from an Dar Command File (see -B option), assuming it has the  appropriated
       permission  to avoid other users reading it. For those paranoids that are really concerned
       about security of their passwords, having a password read from a DCF is not  that  secure,
       because  while  the file gets parsed, dar makes use of "unsecured" memory (memory than can
       be swapped to disk under heavy memory load conditions). It is only when the passphrase has
       been  identified  that  locked memory is used to store the parsed passphrase. So, the most
       secure way to transmit a passphrase to dar, then to libdar, then to libgcrypt,  is  having
       dar  asking  passphrase  at  execution time, dar then makes use of secured (locked) memory
       from the time the password is received by dar from user (but through the operating system)
       up to its usage inside libgcrypt (after having been passed through libdar which also makes
       use of locked memory).

       -J, --ref-key [[<algo>]:]<string>
                           same as -K but the given  key  is  used  to  decrypt  the  archive  of
                           reference (given with -A option). --key-ref is a synonym.

       -#, --crypto-block <size>
                           to  be able to randomly access data in an archive, it is not encrypted
                           globally but block by block. You can define the encryption block  size
                           thanks to this argument which default to 10240 bytes. Note that syntax
                           used for -s option is also available here. Note also that crypto-block
                           is  stored  as a 32 bits integer thus value larger than 4GB will cause
                           an error. Note last, that the block size given here must  be  provided
                           when reading this resulting archive (through the -* or -# options). If
                           it is not the correct  one,  the  archive  will  not  be  possible  to
                           decrypt, it is thus safe to keep the default value (and not use at all
                           the -# option).

       -*, --ref-crypto-block <size>
                           same as --crypto-block but for the archive of reference (same  default
                           value). --crypto-block-ref is a synonym.

       -B, --batch <filename>
                           You  can  put  in  the  file any option or argument as used on command
                           line, that will be parsed  as  if  they  were  in  place  of  the  "-B
                           <filename>"  option.  This  way you can overcome the command line size
                           limitation. Commands in the file may be disposed on several lines, and
                           -B  option  can  also  be used inside files, leading a file to include
                           other files. But an error occurs in case  of  loop  (a  file  includes
                           itself)  and  DAR  aborts  immediately. Comments are allowed, and must
                           start by a hash `#' character on each line. Note that for a line to be
                           considered  as  comment the hash character must be the first character
                           of the line (space or tab can still precede the hash). See Conditional
                           Syntax  bellow for a more rich syntax in configuration files. See also
                           the environment variable DAR_DCF_PATH in the  ENVIRONMENT  section  at
                           the end of this document.

       -N, --noconf        Do  not  try  to  read  neither  ~/.darrc nor /etc/darrc configuration
                           files. See files section bellow.

       -e, --dry-run       Do not perform any action (backup, restoration or  merging),  displays
                           all  messages  as  if  it was for real ("dry run" action). The --empty
                           option is a synonym.

       -aSI, --alter=SI[-unit[s]]
                           when using k M G T E Z Y  prefixes  to  define  a  size,  use  the  SI
                           meaning: multiple of 10^3 (a Mega is 1,000,000).

       -abinary, --alter=binary[-unit[s]]
                           when using k M G T E Z Y prefixes to define a size, use the historical
                           computer science meaning: multiple of 2^10  (a Mega is 1,048,576).

       The --alter=SI and --alter=binary options can be used several times on the  command  line.
       They  affect  all  prefixes  which  follow,  even  those found in files included by the -B
       option, up to the next --alter=binary or --alter=SI occurrence. Note that  if  in  a  file
       included  by the -B option, an --alter=binary or --alter=SI is encountered, it affects all
       the following prefixes, even those outside the included files. For example,  when  running
       with  the  parameters  "-B  some.dcf -s 1K", 1K may be equal to 1000 or 1024, depending on
       --alter=binary or --alter=SI being present in the some.dcf file. By  default  (before  any
       --alter=SI/binary  option  is  reached),  binary  interpretation  of prefixes is done, for
       compatibility with older versions.

       -Q                  Do not display an initial warning on stderr when not launched  from  a
                           terminal  (when  launched from a cronjob for example). This means that
                           all questions to the user will be answered with 'no',  which  most  of
                           the  time  will abort the program. Please note that this option cannot
                           be used in a configuration file, it must be given on the command line.
                           Since   version  2.2.2,  giving  this  option  also  forces  the  non-
                           interactive mode, even if dar is launched from a terminal. This  makes
                           it  possible  for  dar  to  run  in  the background. When you do, it's
                           recommended to redirect stdout and/or sterr to files.

       -ac, --alter=ctime  When reading a filesystem (during a backup  or  comparison),  restores
                           the  atime  of all files to what it was before the file was read. This
                           makes it appear as if it had not been read at  all.  However,  because
                           there  is  no system call to let applications changing the ctime (last
                           inode change) of a file, setting back the atime results in  the  ctime
                           being  changed  (hence the alter=ctime). Some recent unix system allow
                           an application to get 'furtive  read  mode'  to  the  filesystem  (see
                           below).  On  older systems, however, for most users, having the atimes
                           of the files changed shouldn't be a problem, since they can be changed
                           by any other program (running by any user!) as well (like the content-
                           index program Beagle). Ctimes on the other hand, are the only way  for
                           security software to detect if files on your system have been replaced
                           (by so called root-kits mostly). This means, that should you  run  dar
                           with  -ac,  security  software  which  uses ctimes to check, will mark
                           every file on your system as compromised after the backup.  In  short,
                           this  means  this  option  should only be used by people who know what
                           they are doing. It's the opinion of  this  writer  that  any  software
                           susceptible  to atime changes is flakey or even broken (because of the
                           afore mentioned reasons why atimes can change). But, that doesn't take
                           away  that  there  are programs who rely on atimes remaining the same,
                           like Leafnode NNTP chaching software. Therefore this option exists.

       -aa, --alter=atime  When specifying -aa (by opposition to -ac), the atime  of  every  read
                           file  and  directory  is  updated,  and the ctime remains the same. In
                           other words, Dar itself does nothing with atimes and ctimes,  it  only
                           let the system do its job to update atimes when files are accessed for
                           reading. This is in accordance with what atimes and ctimes were  meant
                           to  represent.  This  is  Dar's  default (since version 2.4.0), unless
                           'furtive read mode' (see below) is supported by your  system  and  dar
                           has been compiled with this support activated.

       Furtive  read mode is a mode in which neither atime nor ctime are modified while dar reads
       each file and directory. This provides also better performances as nothing has to be wrote
       back  to  disk.  A  known  Unix kernel that supports this feature is Linux 2.6.8 and above
       (support must also be present in the standard C library of the system for dar to  be  able
       to activate this feature at compilation time).  When this feature is activated, it becomes
       the default behavior of dar for super user ; for  other  users  the  default  is  -aa.  If
       however  as  root  user,  you  do  not  want to use "furtive read mode" (while it has been
       activated at compilation time), you need to explicitly specify either -aa or -ac option.

       -am, --alter=mask   set the ordered mode for mask. This affects the way -I and -X  options
                           are  interpreted,  as  well  as  -g,  -P, -[ and -] options, -Z and -Y
                           options and -U and -u options. It can take any place on  the  command-
                           line  and  can  be  placed  only once. See the file selection in brief
                           paragraph above for a detailed explanation of this option. It has also
                           an  incidence  on  the --backup-hook-exclude and --backup-hook-include
                           options.

       -an, --alter=no-case
                           set the filters in case insensitive mode.  This  concerns  only  masks
                           specified  after  this  option  (see  also  -acase option below). This
                           changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U options.

       -acase, --alter=case
                           set back to case sensitive mode for filters. All following  masks  are
                           case  sensitive,  up  to  end of parsing or up to the next -an option.
                           This changes the behavior of -I,  -X,  -g,  -P,  -Z,  -Y,  -u  and  -U
                           options.

       -ar, --alter=regex  set the filters to be interpreted as regular expressions (man regex(7)
                           ) instead of the default glob expression (man glob(7) ) This  modifies
                           the  -I,  -X,  -g, -P, -Z, -Y, -u and -U options that follows up to an
                           eventual -ag option (see just below). Note that  for  -P  option,  the
                           given  mask  matches  the  relative path part of the files path: Let's
                           take an example, assuming you  have  provided  /usr/local  to  the  -R
                           option,    the    mask    "^foo$"    will   replaced   internally   by
                           "^/usr/local/foo$" while the mask "foo$" will be  replaced  internally
                           by "^/usr/local/.*foo$".

       -ag, --alter=glob   This  option  returns  to glob expressions mode (which is the default)
                           after an -ar option has been used, this applies to any -I, -X, -g, -P,
                           -Z, -Y, -u and -U options that follow up to an eventual new -ar option
                           (see just above).

       -at, --alter=tape-marks
                           For archive creation and merging, the default behavior (since  release
                           2.4.0)  is  to add escape sequences (aka tape marks) followed by inode
                           information all along the archive. If -at is given, dar will  not  add
                           this  information  to  the  archive,  resulting  in a slightly smaller
                           archive and faster  backup.  When  reading  an  archive,  the  default
                           behavior  is  to  ignore these escape sequences and rather rely on the
                           catalogue located at the end of the archive. If instead  --sequential-
                           read  is  given  on command-line (see below), dar will avoid using the
                           catalogue at the end of the archive and  will  rely  on  these  escape
                           sequences  to  know  the contents of the archive, which will lead to a
                           sequential reading of the archive, operation suitable for tape  media.
                           Note  that it is not recommended to disable escape sequences (aka tape
                           marks) by using -at option except if you are  more  concerned  by  the
                           resulting  size  and  execution speed of your backup (in particular if
                           you have a lot of small files) than by the possibility to recover your
                           data  in  case  of  corrupted  or partially written archive.  Whithout
                           escape sequences, dar cannot sequential read an archive, which is  the
                           only  way  to  use an archive that has a corrupted catalogue or has no
                           catalogue at all, thing that happens if a system crash occurred during
                           the  archive  creation  or  due  to lack of disk space to complete the
                           archive.

       -0, --sequential-read
                           Change dar's  behavior  when  reading  an  archive.  By  default,  the
                           traditional  way  is  used, which relies on the table of contents (aka
                           "the  catalogue")  located  at  the  end  of  the  archive.  With  the
                           --sequential-read  option  instead,  dar will rely on escape sequences
                           that are inserted  all  along  the  archive  with  each  file's  inode
                           information.  This  will  lead to a sequential reading of the archive,
                           operation suitable for tape medium.  However,  this  feature  is  only
                           available  for  archive  format  starting  revision  "08" (i.e.: since
                           release 2.4.0) and if -at option  has  no  been  used  during  archive
                           creation  or  merging.  This  option  is available for archive testing
                           (-t), comparison (-d), restoration (-x), listing (-l) and to read  the
                           archive  of  reference (-A option) for isolation (-C) archive creation
                           (-c). The sequential reading of an archive is always much slower  than
                           the usual reading method, so you should not use this option unless you
                           really need it.

       -j, --jog           when virtual memory is exhausted, ask user to make room before  trying
                           to  continue.  By  default,  when memory is exhausted dar aborts. Note
                           that on several system, when memory is exhausted the kernel is  likely
                           to kill the process that failed to obtain virtual memory, thus on some
                           systems, dar may not be able to ask user for what to do when memory is
                           exhausted.

       -;, --min-digits <num>[,<num ref>[,<num aux>]]
                           By  default  slice number contained in filename do not have any padded
                           zeros, which, when sorting a directory contents  alphabetically  leads
                           to read all the slice starting by '1', then by '2'. for example, slice
                           1, 10, 11, 12, 13, ... 2, 20, 21, 23, ... etc. While dar is absolutely
                           not  perturbed  by  this display problem, some user shall like to have
                           the slices sorted by order. For that reason, the  --min-digits  option
                           lets you ask dar to prepend enough zeros in the slice number for it be
                           as wide as the argument passed to --min-digits. For  example,  if  you
                           provide  3  for  that  number, dar will store the slice number as 001,
                           002, 003, ... 999. Well, next slice will be 1000, thus it  will  break
                           again  the  alphabetical  sorting order. You are thus advised to use a
                           number large enough to convert the number of slice you expect to  use.
                           Then,  when  reading  your archive, you will also need to provide this
                           same argument, else dar will fail finding the slice. In  effect,  when
                           looking  for  slice  1  for  example,  dar should try opening the file
                           "basename.1.dar", but if it fails, it  should  try  opening  the  file
                           "basename.01.dar", then "basename.001.dar", ... up to infinity. If the
                           slice is just missing, dar would never ask you to  provide  it,  being
                           still  looking  for  a slice name with an additional leading zero. The
                           problem also arise when doing differential backup, merging  or  on-fly
                           isolation,  dar  must  know  the number of zero to prepend for each of
                           these archive. This is why the --min-digits option may receive  up  to
                           three integer values, the first for the archive to create or read, the
                           second for the archive of reference (-A option),  the  third  for  the
                           auxiliary  archive  of  reference (-@ option).  By default, no zero is
                           added, and it is also well working this way. But you  might  well  set
                           for  example "--min-digits 5,5,5" in your ($HOME)/.darrc file to do it
                           once and for all. Last important point, on command-line  (not  in  DCF
                           files), the short form of this option (-;) need to be quoted ('-;') to
                           avoid the shell interpreting the ';' character.

       --pipe-fd <num>     will read  further  arguments  from  the  file-descriptor  <num>.  The
                           arguments   read  through  this  file-descriptor  must  follow  a  TLV
                           (Type/Length/Value) list format. This option is not intended for human
                           use,  but  for  other  programs  launching  dar like dar_manager. This
                           feature has been added to overcome the command line length limit.

       SAVING, ISOLATION AND MERGING OPTIONS (to use with -c, -C or -+)

       -z[[algo:]level], --compression[=[algo][:][level]]
                           add compression within slices using gzip, bzip2 or lzo  algorithm  (if
                           -z  is  not  specified,  no compression is performed). The compression
                           level (an integer from 1 to 9) is optional, and is 9 by default, which
                           is  max  compression/slow  processing.  At  the opposite, 1 means less
                           compression and faster processing. "Algo" is  optional,  it  specifies
                           the  compression  algorithm  to  use and can take the following values
                           "gzip" "bzip2" or "lzo". "gzip" algorithm  is  used  by  default  (for
                           historical   reasons   see   --gzip  below).  If  both  algorithm  and
                           compression are given, a ':' must be placed between them. Valid  usage
                           of -z option is for example: -z, -z9, -zlzo, -zgzip, -zbzip2, -zlzo:6,
                           -zbzip2:2, -zgzip:1 and so on. Usage for  long  option  is  the  same:
                           --compression, --compression=9, --compression=lzo, --compression=gzip,
                           --compression=bzip2,    --compression=lzo:6,    --compression=bzip2:2,
                           --compression=gzip:1 and so on.

       --gzip[=level]      Same as -z (see just above). Historically -z/--gzip was for gzip while
                           -y/--bzip2 was for bzip2. But due to  the  lack  of  available  unused
                           letter  for  command  line options, lzo compression could not be added
                           without extending -z option grammar. For backward compatibility --gzip
                           is  kept,  but  is  deprecated.  Rather  use  --compression[=level] or
                           -z[level].

       -y[level], --bzip2[=level]
                           compresses using bzip2 algorithm. See -z above for usage details. This
                           option  is  DEPRECATED  and WILL DISAPPEAR in a future version. Please
                           use -zbzip2:level or --compression=bzip2:level.

       -s, --slice <number>
                           Size of the slices in bytes. If the number is appended by k (or K), M,
                           G,  T,  P  E,  Z  or Y the size is in kilobytes, megabytes, gigabytes,
                           terabytes, petabytes, exabytes, zettabytes or yottabytes respectively.
                           Example:  "20M"  means  20  megabytes,  by  default, it is the same as
                           giving 20971520 as argument (see also -aSI and -abinary  options).  If
                           -s  is  not  present  the  backup  will  be  written to a single slice
                           whatever the size of  the  backup  may  be  (there  is  probably  some
                           filesystem  limitation,  thus  you might expect problems for file size
                           over 2 gigabytes, depending on your filesystem,  but  this  is  not  a
                           limitation of dar).

       -S, --first-slice <number>
                           -S gives the size of the first slice which may be chosen independently
                           of the size of following slices. This option needs -s and by  default,
                           the  size  of  the first slice is the same as the one of the following
                           slices.

       -p [<integer>], --pause[=<integer>]
                           pauses before writing to a new slice (this requires  -s).  By  default
                           there is no pause, all slices are written in the same directory, up to
                           the end of the backup or until the filesystem is full. In  this  later
                           case, the user is informed of the lack of disk space and dar stops for
                           user action. As soon as some disk space is  available,  the  user  can
                           continue the backup. The optional integer that this option can receive
                           tells dar to only pause very 'n' slice. Giving 3 for 'n' will make dar
                           pause  only  after  slices  3,  6, 9 and so on. If this integer is not
                           specified, the behavior is as if '1' was given as argument which makes
                           dar pause after each slice.

       -A, --ref [<path>]/<basename>
                           Depending on the context, it specifies the archive to use as reference
                           (mandatory with -C and -+) or the rescue catalogue to use  (when  used
                           with  -x -t or -d). All slices of the reference backup are expected to
                           be on the same directory given by <path> or the current  directory  by
                           default.  Usually  only  the  last  slice  is  required to extract the
                           catalogue of reference. If necessary the use of symbolic links is also
                           possible  here  to  gather  slices  that  do  not  reside  in the same
                           directory. You can also point <path> to a floppy or any other  mounted
                           directory, because dar will pause and ask the user for required slices
                           if they are not present. The argument to -A may be of four types:

                           - An existing archive basename, which will be taken as reference

                           - a dash ("-") in direct access mode (default mode) it may  imply  the
                           use  of  -o and -i options, this allows the archive of reference to be
                           read from a pair of pipes with dar_slave at the other ends.  Dar_slave
                           can  be  run  through ssh on a remote host for example. Note that this
                           type of argument ("-") is not available when -A is used with -x, -d or
                           -t.  In  sequential  mode  (--sequential-mode is used), the archive of
                           reference is read from standard input or on named pipe specified by -i
                           option. -o option has no use in sequential mode. Note that merging (-+
                           option) cannot read archive of reference in sequential mode.

                           - a plus sign ("+") which makes the reference be the current directory
                           status  (only available with -c option). In other word, no file's data
                           will be saved, just the current status of the inodes will be  recorded
                           in  the  catalogue. This is like an extracted catalogue form a virtual
                           full backup, it can be taken for further reference without  having  to
                           make  the  full backup itself. This feature is known as the "snapshot"
                           backup.

                           - a <date>, if -af option has been placed before -A  on  the  command-
                           line  (or  in  a  included  file,  see -B option). For more about that
                           feature see -af option below.

                           During backup (-c option) the archive of  reference  given  thanks  to
                           this  option  is used to compare existing files on the filesystem. Dar
                           will then backup only files that have changed  since  the  archive  of
                           reference  was  done.  During merging (-+ option), the contents of the
                           given archive will  been  taken  with  the  contents  of  the  archive
                           specified  with  -@ option (see below). During Catalogue isolation (-C
                           option), dar will create the isolated catalogue  from  the  one  given
                           with  -A  option.  During  testing,  diff or extraction, (-t, -d or -x
                           options respectively), the table of contents (the catalogue)  will  be
                           read  from  the  archive  given  with -A instead of using the internal
                           catalogue of the archive (given with -t, -d or -x option). The archive
                           given  for  rescue  must  has  been previously isolated from this same
                           archive (else the contents will not  match  and  dar  will  refuse  to
                           proceed  to  this  operation).  This  gives  a solution to the case of
                           corruption inside an archive's catalogue, while the best way is  still
                           to use Parchive to protect your data against media error.

       -@, --aux [<path>]/<basename>, --on-fly-isolate [<path>]/<basename>
                           specifies  an  auxiliary archive of reference (merging context) or the
                           name of the on-fly isolated catalogue (creation context). This  option
                           is thus only available with -+ option (merging) and -c option (archive
                           creation). Over -A option which is mandatory with -+ option,  you  may
                           give  a  second  archive of reference thanks to the -@ option (merging
                           context). This allows you to merge two archives into a single one. See
                           also  -$,  -~ and -% for other options concerning auxiliary archive of
                           reference. While creating an archive (backup context) this option  let
                           the  user  specify the archive name for an on-fly isolation (former -G
                           option), you can also use -$  and  -~  to  define  encryption  of  the
                           archive  containing  the  on-fly  isolated  catalogue. On-fly isolated
                           catalogue is always bzip2 if possible else gzip  else  lzo  compressed
                           (using compression level 9) else not compressed, and it is also always
                           a single sliced archive. Due  to  command-line  exiguity,  it  is  not
                           possible  to  change  compression  algo  nor slice size for the on-fly
                           isolation. If you need a more complicated isolation, either look for a
                           GUI  over libdar, or do a normal (= not an on-fly) isolation operation
                           (By the way it is possible to isolate an already  isolated  catalogue,
                           this  is  equivalent  to  doing a copy, but you can change encryption,
                           compression or slicing, for example), you can also  use  dar_xform  if
                           you   only   want  to  change  slices  size  (this  is  faster  as  no
                           decompression/re-compression is done). Using the merging operation  on
                           an  isolated  catalogue  instead  of isolating the isolated catalogue,
                           leads the resulting archive to not be able to be used as a rescue  for
                           internal catalogue of the original archive. --aux-ref is a synonym.

       -D, --empty-dir     At  backup time, when excluding directories either explicitly using -P
                           or -] options, or implicitly by giving a -g or -[ options (a directory
                           is  excluded  if  it  does  not match mask given with -g options or -[
                           options) dar does not store anything about these. But with -D  option,
                           dar stores them as empty directories. This can be useful, if excluding
                           a mount point (like /proc or /dev/pts). At restoration time, dar  will
                           then  recreate  these  directories  (if necessary). This option has no
                           meaning with -C and is ignored in that case. Independently of that, -D
                           can  also  be  used  at  restoration time, but it activates a slightly
                           different feature (see restoration options below).

       -Z, --exclude-compression <mask>
                           Filenames covered by this mask are not compressed. It is  only  useful
                           with -z option. By default, all file are compressed (if compression is
                           used). This option can be used several times, in that case a file that
                           matches  one  of the -Z mask will not be compressed. Argument given to
                           -Z   must   not   be   include   any   path,   just    the    filename
                           (eventually/probably using wildcards).

       -Y, --include-compression <mask>
                           Filenames covered by this mask (and not covered by -Z) are the only to
                           be compressed. It is only available with -z  option.  By  default  all
                           files  are  compressed. This option can be used several times, in that
                           case all files that match one of the -Y will be compressed, if they do
                           not also match on of the -Z masks. The ordered method here applies too
                           when activated (with -am option), it works exactly the same as -I  and
                           -X  options,  but  apply  to  file compression, not file selection. In
                           other word, it matches only on the file  name,  not  on  the  path  of
                           files.

       -m, --mincompr <number>
                           files  which size is below this value will not be compressed. If -m is
                           not specified it is equivalent to giving -m 100 as  argument.  If  you
                           want to compress all file whatever their size is you thus need to type
                           -m 0 on the command line. The same number  extensions  as  those  used
                           with  -s  or -S are available here, if you want to specify the size in
                           kilobyte, megabyte, gigabyte etc.

       -1, --sparse-file-min-size <number>
                           Define the minimum length of zeroed bytes to replace  by  "holes".  By
                           default,  this  feature  is  activated  with  a  value of 15 bytes. To
                           completely disable it, set the size to zero.  Disabling  this  feature
                           will  bring  some  noticeable speed improvement but will probably make
                           the archive slightly bigger (depending on the  nature  of  the  data).
                           Sparse  files are files that contain so called holes. On a filesystem,
                           the portion of zeroed bytes is not stored on disk, thus  an  arbitrary
                           large  file with huge portion of zeros may only require a few bytes of
                           disk storage. While dar cannot detect how is allocated  a  given  file
                           because  it  makes  a  filesystem  abstraction  (it  does not know the
                           implementation  of  any  particular   filesystem,   where   from   its
                           portability),  however when it finds a sequence of zeroed bytes larger
                           than the given threshold it can assume that it is  in  presence  of  a
                           hole.  Doing  so,  it  does  not store the given zeroed bytes into the
                           archive, but place a tag beside the saved data to record the  size  of
                           the  hole and thus where to place the next no zeroed bytes. This makes
                           dar archive disk space requirement much smaller when a sparse files is
                           met.  At  restoration time, dar will restore holes writing normal data
                           and seeking over the hole to write down the  normal  data  after  each
                           hole.  If  the underlying file system supports sparse files, this will
                           restore the holes. Note that there is no difference  for  applications
                           whether  a  file  is sparse or not, thus dar may well transform normal
                           files into sparse files and viceversa, only the disk requirement  will
                           change.  Last  point,  if  dar can reduce disk requirement for archive
                           with holes as small as 15 bytes (smaller value works but the  overhead
                           cost  more  than what is required to store the zeroed bytes normally),
                           it may not be the same at restoration, because  filesystem  allocation
                           unit is usually several kilobytes, however restored file will never be
                           larger than it could be without  holes.  The  only  drawback  of  this
                           feature is the additional CPU cycle it requires.

       -ak, --alter=keep-compressed
                           During  merging  operation,  keep  files  compressed, this has several
                           restrictions : -z, -Z, -Y, -m are ignored, if two archives have to  be
                           merged,  both  must  use the same compression algorithm or one of them
                           must not use compression at all (this last restriction  will  probably
                           disappear  in  a  next  version).  The  advantage  of this option is a
                           greater speed of execution (compression is usually CPU intensive).

       -ah, --alter=holes-recheck
                           For merging, the  sparse  file  detection  mechanism  is  disabled  by
                           default.  However if you want to activate it (assuming you have an old
                           archive you want to convert the current archive format taking care  of
                           sparse  files),  you  need  to use -ah option to reactivate the sparse
                           file detection mechanism. Then for merging  --sparse-file-min-size can
                           be used as described above for archive creation. In particular setting
                           --sparse-file-min-size to zero beside -ah during merging, may also  be
                           used to convert file saved as sparse file into plain normal files.

       -af, --alter=fixed-date
                           Modify  the  -A  option  behavior,  making  it  receiving  a <date> as
                           argument in place of the  [<path>]/<basename>  default  argument.  The
                           <date>  is  used to define which file to save (file which modification
                           is newer or equal to <date>) and which to  consider  unchanged  (those
                           older  than  <date>).  This  option  has only a sense when creating an
                           archive (not when merging or isolating).

       <date> must be a date in the following possible formats:

       - a number of second since Jan 1st, 1970

       - a date in the following form [[[year/]month/]day-]hour:minute[:second]

       Here are some examples of date:
              91836383927108078

              2005/11/19-19:38:48 Which is 38 past 7 PM and 48 seconds, the 19th of November 2005

              20:20 Which is 8 PM of the current day

              2-00:08 Which is 8 past noon, the second day of the current month

              2/2-14:59 Which is 1 to 3 PM, the 2nd of February in the current year

       --nodump            do not save files which have the 'd' flag set (see chattr(1) lsattr(1)
                           ext2 commands). This option may not be available if the system dar has
                           been compiled on did not provide support for  ext2  flags.  Note  that
                           this  option does nothing with -+ option (merging) as no filesystem is
                           used for that operation.

       -M, --no-mount-points
                           stay in the same filesystem as the root  directory  (see  -R  option),
                           subdirectory  that  are mounting points for other filesystems will not
                           be saved (or saved empty if -D option is used). This option is useless
                           and ignored for merging operation.

       -, ,  --cache-directory-tagging
                           don't  save  contents  of  directories  that  use  the Cache Directory
                           Tagging  Standard.  See  http://www.brynosaurus.com/cachedir/spec.html
                           for details. (this option is useless with -+ option)

       -$, --aux-key [[<algo>]:]<string>
                           same as -J but for the auxiliary archive of reference (-@ option).

       -~, --aux-execute <string>
                           same as -F but for the auxiliary archive of reference (-@ option).

       -%, --aux-crypto-block <size>
                           same as -* but for the auxiliary archive of reference (-@ option).

       -/ , --overwriting-policy <policy>
                           This option let the user define when or how file overwriting can occur
                           at restoration or archive merging time. It  does  no  apply  to  slice
                           overwriting  which  are driven by the -n option, it does instead apply
                           to file during extraction and files inside archives when  merging  two
                           of them. When considering overwriting, a file is said to be 'in place'
                           while an other is known as 'new' or  'to  be  added'.  At  restoration
                           time,  the  'in  place' is the one that is present in filesystem while
                           the 'to be added' is the one from the archive. At  merging  time,  the
                           'in  place'  is the one of the '-A' archive of reference while the 'to
                           be added' is the one from the auxiliary '-@' archive or reference.

       As soon as you use -/ option -n only applies only to slice overwriting and the -r, -k  and
       -ae options are ignored (restoration options).

       The  given  <policy>  argument  is  composed  of  actions  and  eventually  of conditional
       expressions. Actions do define how to solve overwriting conflict  about  file's  data  and
       file's  EA. An action is thus a couple of action for Data and for EA. Actions for Data are
       represented by uppercase letters, while action for EA are defined  by  lowercase  letters.
       Both actions are independent of each other:

              P    means 'Preserve'. When merging two archives, the data of the resulting archive
                   will be taken from the 'in place' file. While when extracting, the data of the
                   inode  in filesystem will be preserved (thus no overwriting will occur for the
                   data).

              O    means 'Overwrite'. When merging  two  archives,  the  data  of  the  resulting
                   archive  will be taken from the 'to be added' file. While when extracting, the
                   data of the inode in filesystem will be overwritten by data from the archive.

              S    means 'mark Saved and preserve'. When merging two archives, the  data  of  the
                   resulting  archive will be marked as already saved in the archive of reference
                   (making thus a differential archive, even if none of the original archive were
                   differential archives). All data will be dropped in the resulting archive, but
                   the last modification date [aka mtime] (used to detect change in file's  data)
                   will  be  taken  from  the  'in  place'  file. This action does not apply when
                   extracting files, it is thus  considered  equal  to  "Preserve"  (P)  in  that
                   situation.

              T    means  'mark  Saved and overwrite'. When merging two archives, the data of the
                   resulting archive will be marked as already saved (same as  'S'  action):  all
                   data  will  be dropped in the resulting archive, however the last modification
                   date [aka mtime] (used to detect changes in a file's data) will be taken  from
                   the  'to  be added' file. This action does not apply when extracting files, it
                   is thus considered equal to "Overwrite" (O) in that situation.

              R    means 'Remove'. When merging two archives,  the  resulting  archive  will  not
                   contain  any  entry corresponding to the file that were in conflict. This also
                   implies that no EA will be stored for that particular entry as the entry  will
                   no  more exist in the resulting archive (as if it had never yet existed). When
                   extracting files, this will lead to file's suppression.

              p    means 'Preserve', same as 'P' (but lowercase letter)  preserve  the  whole  EA
                   set.  When  merging two archives, the EA set of the resulting file will be the
                   EAs of the 'in place' file (whatever is the overwriting action taken  for  its
                   data).  While  when  extracting  files  to  filesystem,  the EA of the file in
                   filesystem will not be changed (whatever is the overwriting action  taken  for
                   its data, unless the file is removed using the 'R' policy).

              o    means  'Overwrite',  same as 'O' (but lowercase letter) overwrite the whole EA
                   set. When merging two archives, the EA set of the resulting file will be taken
                   from  the  'to  be added' file. While when extracting files, the EA set of the
                   file in the filesystem will have its EA erased and replaced by  those  of  the
                   file in the archive (still independent of what overwriting action is taken for
                   file's data).

              s    means 'mark Saved and preserve', same as 'S' (but  lowercase  letter)  for  EA
                   instead  of  data. When merging two archives, the EA of the resulting file are
                   marked as already saved in the archive of reference, thus they are dropped but
                   the  date  of  last inode change [aka ctime] (used to detect changes in file's
                   EA) will be taken from the 'in place' file. This action does  not  apply  when
                   extracting  files,  it is thus considered equivalent to "Preserve" (p) in that
                   situation.

              t    means 'mark Saved and overwrite', same as 'T' (but lowercase  letter)  for  EA
                   instead  of  data. When merging two archives, the EA of the resulting file are
                   marked as already saved in the archive of reference, thus they are dropped but
                   the date of last inode change [aka ctime] (use to track changes in EA) will be
                   taken from the 'to be added' file. This action does not apply when  extracting
                   files,  it  is  thus  considered  an  equivalent  to  "Overwrite"  (o) in that
                   situation.

              m    means 'merge EA and preserve'. The resulting file in the merged  archive  will
                   have  EA entries from both the 'in place' and the 'to be added' files. If both
                   files share a same EA entry (same key for a given association) the one of  the
                   'in  place' file is kept (where from the 'preserve' notion). When extracting a
                   file, the file in the filesystem will have its EA set enriched by  EA  entries
                   of  the  file  in the archive that do not exist on filesystem, but its already
                   existing EA will stay untouched.

              n    means 'merge EA and overwrite'. The resulting file in the merged archive  will
                   have  EA entries from both the 'in place' and the 'to be added' files. If both
                   files share a same EA entry (same key for a given association) the one of  the
                   'to  be  added'  file  will  be kept (where from the 'overwrite' notion). When
                   extracting file, the file in the filesystem will have its EA set  enriched  by
                   EA  entries  of  the  file  in  the  archive  with some EA entry possibly been
                   overwritten.

              r    means 'remove', same as 'R' but for the EA set (thus  all  EA  entries)  of  a
                   given  file  ('r' is lowercase letter here). The file of the resulting archive
                   during merging operation will not own any EA, even if the  'in  place'  and/or
                   the  'to  be  added' files did have some. For file extraction, this means that
                   the file in the filesystem will loose all its EA set. As for all the  previous
                   tests,  this  EA  operation  is independent of the operation chosen for file's
                   data (uppercase letters).

              d    means 'delete'. When a same EA entry is found both in the 'in place'  and  'to
                   be  added'  files  these  entries  will be absent in the resulting archive. In
                   other words, when merging, the EA set will only contain EA entries specific to
                   the 'in place' and those specific to the 'to be added' file. Entries in common
                   will not be present. When extracting a file  from  an  archive,  the  file  on
                   filesystem  will have its EA set enriched by entries of the 'to be added' file
                   that are new to the 'in place' file. The other entries (which are thus present
                   in both archive and filesystem) will be removed from the EA set.

              *    is  valid for both EA and data. It tells that the action is not yet defined at
                   this step of the evaluation and that further evaluation is required  (see  the
                   'chain' operator below).

              A    means   'Ask   for   user  decision'.  This  uppercase  letter  concerns  Data
                   overwriting. An application interaction let the user  define  the  action  for
                   each  file  in  conflict. Note, that this action if used alone may become very
                   boring or painful. The idea is to use it in conditional statements (which  are
                   described below) to have dar ask for only non obvious cases.

              a    means  'Ask for user decision'. This lowercase letter is the equivalent for EA
                   of the 'A' action.  It  is  intended  to  be  used  in  the  same  conditional
                   statements described below.

              An  action is thus a couple of letters, the first being uppercase (for file's data)
              the second being lowercase (for file's EA). When -/ option is not given, the action
              is equivalent to '-/ Oo', making dar proceed to file and EA overwriting. This is to
              stay as close as possible to the former default action  where  neither  -n  nor  -w
              where  specified.  Note  that  -w  option stays untouched, in consequences, in this
              default condition for -/ option, a confirmation will be asked to  the  user  before
              dar  proceed  to  any overwriting. The former -n option (still used to handle slice
              overwriting) can  be  replaced  by  its  equivalent  '-/  Pp'  for  resolving  file
              overwriting  conflict (never overwrite). Here follows some examples of actions, all
              these are done for any entry found in conflict during archive  merging  or  archive
              extraction, we will see further how to define conditional actions.

              -/ Rr
                   will  result  lead  dar  to  remove  any file from filesystem that ought to be
                   restored(!). Note the action for EA is useless, the EA will always  be  erased
                   as well as data using 'R'. Thus '-/ Rp' would lead to the same result.

              -/ Po
                   will keep data of the 'in place' file and EA set from the 'to be added' file.

              -/ Ss
                   Using this option when merging an archive with itself (used both as archive of
                   reference (-A option) and auxiliary archive of reference (-@  option)  )  will
                   provide  the  same action as an archive isolation of the archive of reference,
                   but using twice more memory (so keep using the isolation operation as  before!
                   Here this is just an illustration of the possibility)

              As  seem  previously  -u  and  -U  options  can be used to filter which EA entry to
              consider and which to ignore. The question here is to explain  how  this  filtering
              mechanism  interacts with the different policies we just presented above. For files
              that are not in conflict (found only as 'in place' or as 'to be added'),  only  the
              EA  entries matching the EA filter are kept. For files in conflict, the overwriting
              policy is evaluated first, then the filtering mechanism is applied *after* it. Thus
              for example, using the following [ -/ "Po" -u "*test" ], when merging two archives,
              only EA ending with "test" will be retained, and when a conflict takes place,  this
              "*test"  ending  EA  will be taken from the 'to be added' file if it has some EA of
              that type, its other EA entry will be ignored as well as any EA entry  of  the  'in
              place'  file even those ending by "test". At restoration in using the same options,
              file without conflict will get restored but only EA entry ending with  "test"  will
              be  restored, and for file with conflict (already present in filesystem), EA set of
              file in filesystem will be removed and replaced the  EA  entries  of  the  file  in
              archive that ends by "test", if some exist.

              Well,  now let's see how to bring some more fun using conditional statements in all
              these actions. The structure to use is the following:

              {<condition>}[<action to follow if condition is true>]
                   This syntax let you place an action (as the ones we saw just above) inside the
                   brackets  '['  and  ']'  (for  example [Pp]) that will take effect only if the
                   evaluation of the <condition> is true.  Stated that a such statement is a  new
                   type  of  action,  you  may  have  guessed  that  you  may use it recursively:
                   {<condition1>}[{<condition2>}[<action>]).  Well so far it seems  useless.  But
                   instead of the "if <condition> then <action> else <action>" paradigm common to
                   programming languages, due to the command line context it has been  chosen  to
                   instead  use and implicit "OR" operator between actions.  Thus you can "stack"
                   conditional      statements      this      way:      {<condition1>}[<action1>]
                   {<condition2>}[<action2>]  <action3>. In this example, if <condition1> is true
                   then <action1> will be used, ELSE if <condition2> is true then <action2>  will
                   be  used ELSE <action3> will be used.  This leads to the same possibilities as
                   what is available with programming languages, but with a slightly more  simple
                   syntax.  Seen  this,  the recursion of conditional syntax is more interesting.
                   For readability, you are allowed to add any space or tab  in  the  overwriting
                   policy,  but  the  resulting  overwriting  policy  must  be  given as a single
                   argument to dar, thus the use of quotes (either  simple  '  or  double  ")  is
                   necessary.

              The  last  operator  we  will  see  is  the 'chain' operator. Once an expression is
              evaluated, the resulting couple of action may contain an '*' (undefined action  for
              EA  or  data).  Further  evaluation  must  be  done.  The  chain  operator which is
              represented  by  a  semi-column  ';'  let  one  to  separate  several   independent
              expressions  that  will be evaluated in turn up to the time the couple of action is
              fully defined. Once an action (for EA or for Data) is defined, it can be  redefined
              by a subsequent evaluation in the chain, however if the action is defined it cannot
              be set back to undefined, thus  '*'  will  never  overwrite  a  previously  defined
              action.  If at the end of the policy the couple of action is not fully defined, the
              'preserve' action is used ('P' or 'p' depending on which of  EA  or  Data  is  left
              undefined). Here follow a example of syntax:

              -/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ; Rr"
                   The  first  expression  will evaluate to either P* or O*. At this step, as the
                   action is not completely defined, the second part of the chain  is  evaluated,
                   It  will  end  with  either  *p  or *o. In any case, we have after this second
                   statement of the chain a fully defined action for both data and EA (either Pp,
                   Po,  Op  or Oo). Thus the evaluation stops here and the "Rr" policy will never
                   be evaluated.

              We now have one last thing to see: the available conditions (what to place  between
              braces  '{'  and '}'). Conditions are defined each by a letter, eventually followed
              by an argument between parenthesis. The  usual  logical  operators  are  available:
              negation  (!), conjunction (&) disjunction (|). These characters must be escaped or
              quoted to not be interpreted by the shell when used on command-line. In  particular
              the  '!'  under most shell must be quoted and escaped (-/ '{\!R}[..]..', The escape
              character '\' is not necessary inside DCF files (those given to -B  option)  as  no
              shell  is  used to interpret these files. To these usual operators has been added a
              new one: the "inversion" operator, noted '~'. Like the negation,  it  is  an  unary
              operator  but  unlike  the negation, it inverses the roles of 'in place' and 'to be
              added' for the evaluation, which is slightly different from taking the negation  of
              the  result  of  the  evaluation.  All these operators follow the usual precedence:
              unary operators ('!' and '~') are evaluated first, then the  conjunction  '&'  then
              the  disjunction  '|'. To override this, you can use parenthesis '(' and ')' inside
              the condition. Over these logical operators, the conditions  are  based  on  atomic
              operator  that  compare  the  'in  place' file to the 'to be added' file. Here they
              follow:

              I    true only if the 'in place' entry is an inode (a 'detruit'  which  record  the
                   fact  that  a  file  has been removed since the archive of reference is not an
                   inode for example). This condition do not have any consideration toward the to
                   be added object, as some others but not all below.

              D    true  only  if the 'in place' entry is a directory. To know whether the 'to be
                   added' is a directory or not, one would use the "inversion" operator: ~D

              F    true only if the 'in place' entry is a plain file (true  also  if  this  plain
                   file  is  a 'hard link', that's it if its inode is linked several times to the
                   directory tree)

              H    true only if the 'in place' entry is an inode  linked  several  times  to  the
                   directory  tree  (=  hard link) it may be a plain file, a Unix socket, a pipe,
                   char device, a block device for example.

              A    same as H but the current 'in place' entry is the first link we meet  pointing
                   to that hard linked inode.

              R    true if the 'in place' entry is more recent than or of same date as the 'to be
                   added' entry. The  last  modification  date  [aka  mtime]  is  used  for  this
                   comparison.  If  the  'to  be  added'  entry  is not an inode (and thus has no
                   mtime), the 'in place' is considered to be more recent than the 'to be  added'
                   entry.  Same  thing  if  the 'in place' entry is not an inode (ad has no mtime
                   available for comparison), it is here too assumed to be more recent.

              R(<date>)
                   true if the 'in place' entry is more recent than or of the same  date  as  the
                   fixed  <date>  given  in  argument. No consideration is done toward the 'to be
                   added' element. The <date> format is the same as the one used with -af option.
                   If  an  entry  has  no mtime (it is not an inode for example) it is assumed an
                   virtual mtime of zero.

              B    true only if both 'in place' and 'to be added' are plain file (hard linked  or
                   not) and if the 'in place' file's data is larger or equal to the 'to be added'
                   file's data. If one or both entry are not plain files (or hard link  to  plain
                   file)  and thus the file size comparison is not possible, the 'in place' entry
                   is assumed to be 'bigger' than the 'to be added' entry.

              S    true only if the 'in place' data is  saved  in  the  archive  (not  marked  as
                   unchanged  since  the  archive of reference). Note that while extracting files
                   from an archive, the 'in place' file is  the  one  in  the  filesystem,  which
                   always  has  its  data 'saved' (from libdar point of view). The 'inversion' of
                   this  atomic  operator  ~S  may  still  be  interesting  in  the  context   of
                   restoration.

              Y    true  only  if  the  'in place' data is saved but dirty (plain file having its
                   data changed at the time it was read for  backup).  Note,  that  restoring  in
                   sequential  read mode, it is not possible to known whether a file is dirty (it
                   is possible to know it once having read its data, but sequential reading  does
                   not  allows  then  to skip forward to get the dirty state of the file and skip
                   backward to eventually restore that file, depending on the overwriting  policy
                   result).

              X    true only if the 'in place' data is a sparse file

              T    true  only if the 'in place' and 'to be added' entries are of same type (plain
                   file, Unix socket, named pipe, block device, char device, symlink,  directory,
                   'detruit'  (which  stands  for file deleted since the archive of reference was
                   done), and so on). Note that the number of links to inode (i.e.  whether  this
                   is a hard links or not) is not taken into account.

              e    true  if  the  'in  place' entry has EA (may they be saved or just recorded as
                   existing).

              r    true if the 'in place' entry has more recent or equal dated EA to the  'to  be
                   added'  entry.  If  'to  be  added' has no EA or is even not an inode, true is
                   returned. If 'in place' has no EA or is even not an inode,  true  is  returned
                   unless 'to be added' has some EA. The comparison is done on ctime dates.

              r(<date>)
                   true  if  the  'in place' entry has more recent or equal dated EA to the fixed
                   <date> given in argument. No consideration is done toward the  'to  be  added'
                   element.  The <date> format is the same as the one used with -af option. If an
                   entry has no date (ctime date) (when it is not an inode  for  example)  it  is
                   assumed an virtual ctime of value zero.

              m    true  only if 'in place' has more or equal number of EA entry in its set of EA
                   than 'to be added' has. If an entry has not EA or is not even an inode, it  is
                   assumed  it  has  zero entry. The comparison is done on this number. Note that
                   the number of EA entry is not the  size  used  to  store  these  entries.  For
                   example,  the EA entry "user.test" counts for 1, whatever is the length of the
                   value associated to it.

              b    true if the 'in place' entry has bigger EA set or equal size EA set  than  the
                   'to  be  added'  entry.  If  an entry has no EA or is even not an inode, it is
                   assumed that it has a zero byte length EA set. The comparison is done on  this
                   number  in  that  case.  Note that the comparison is done on the bytes used to
                   store the whole EA set associated to a given file.

              s    true if the 'in place' entry is an inode (or a hard linked inode) and has  its
                   EA  saved  in  the archive of reference, not only marked present but unchanged
                   since last backup. This test does not  take  the  'to  be  added'  entry  into
                   account.

              Well,  you've  seen  that uppercase letter are kept when comparison is based on the
              inode or data while lowercase letter is used for atomics based on EA. Now  that  we
              have completed our tour of this feature let's see some examples:

              -/ Pp
                   as  seen  previously this is what does -n option for files when no overwriting
                   policy is defined, which avoids any overwriting for Data as well as for EA.

              -/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo"
                   Space and tabs are allowed to ease readability. Here the policy stands for: If
                   files in conflicts are not of the same type then keep Data and EA of the entry
                   'in place'. Else if 'in place' has a more recent data then if 'in  place'  has
                   more  recent  EA  then  keep both its Data and EA, else keep only its Data and
                   overwrite its EA. Else (if 'in place' has not the more recent data), if it has
                   the  more  recent  EA  then overwrite the data but keep its EA, else overwrite
                   both its data and EA.  This policy tends to preserve the most recent  data  or
                   EA,  but it does not take into account the fact that EA or Data is effectively
                   saved into the archive of just  marked  as  unchanged  since  the  archive  of
                   reference.

              -/ "{!T}[{~D}[Oo] Pp]"
                   If entries are not of the same type, if the 'to be added' entry is a directory
                   then we keep it and overwrite the 'in place'  entry,  else  we  keep  the  'in
                   place'  entry.  If  entry  are  of  same type, the policy does not provide any
                   action, thus the default action is used: "Pp". You  can  change  this  default
                   action easily using a chain operator:

              -/ "{!T}[{~D}[Oo] Pp] ; Aa"
                   In  this  case  instead, if entry are of the same type, the user will be asked
                   what to.

              -/  "{!T|!I}[{R}[Pp]  Oo]  {S}[{~S}[{R}[P*]  O*]  P*]  {~S}[O*]   {R}[P*]   O*]   ;
              {s}[{~s}[{r}[*p] *o] *p] {~s}[*o] {r}[*p] *o]"
                   Well  this  may  seems a bit too complex but just see it as an illustration of
                   what is possible to do: If both 'in place' and 'to be added' are  not  of  the
                   same  type  we  keep  data  and  EA of the most recent file (last modification
                   date). Else, both are of the same type. If both are inode we  evaluate  a  two
                   expressions chain (expressions are separated by a semi-column ';') we will see
                   in detail further. Else if they are of same type but are not inode we take the
                   EA  and  data  of  the  most  recent  entry  (this is the last 10 chars of the
                   string). Well, now let's see the case of inode: The first  expression  in  the
                   chain sets the action for data and keep the action for EA undefined. While the
                   seconds, is the exact equivalent but instead it leaves  the  action  for  data
                   undefined '*' and set the action for EA. These two expressions follow the same
                   principle: If both entries are saved (by opposition to be marked as  unchanged
                   since  the  archive  of reference) in the archives, the most recent EA/Data is
                   kept, else, the one of the inode that is saved is kept, but if none  is  saved
                   in the archive the most recent entry (mtime/ctime) is kept.

       -^, --slice-mode perm[:user[:group]]
                           defines  the  permission  and  ownership to use for created slices. By
                           default, dar creates slices with read and write available  for  anyone
                           letting the umask variable disable some privileges according to user's
                           preferences. If you need some more  restricted  permissions,  you  can
                           provide  the  permission as an octal value (thus beginning by a zero),
                           like 0600 to only grant read and write access to the user. Be  careful
                           not to avoid dar writing to its own slices, if for example you provide
                           permission such as 0400. Note also that the umask  is  always  applied
                           thus  specifying  -^  0777  will not grant word wide read-write access
                           unless your umask is 0000.

       -_, --retry-on-change count[:max-byte]
                           When a file has changed at the time it was read for  backup,  you  can
                           ask  dar  to  retry saving it again. To activate this feature you must
                           provide the maximum number a given file can be re-saved (this  is  the
                           'count' field).In option the overall maximum amount of byte allowed to
                           be wasted due to retrying changing file's backup can be given after  a
                           column  charactrer  (:),  this is the 'max-byte' field. By default (no
                           --retry-on-change option specified) no retry is  done.  If  'max-byte'
                           field  is not specified, no limit on the  bytes is used, each changing
                           file will be saved up  to  'count'  times  if  necessary.  A  file  is
                           considered  as  changed  when  the  last modification time has changed
                           between the time the file has been opened for backup and the  time  it
                           has been completely read. Retrying a backup cannot replace the already
                           saved backup, a second copy of the file is added just after the  first
                           previous  try  and  the  previous try becomes inaccessible, however it
                           holds some place in the archive, where from the designation of  wasted
                           bytes.  You  can  remove  all  wasted  bytes from an archive using the
                           merging/fitering feature: dar -+ new_arch -A old_arch -ak

       -ad, --alter=decremental
                           This flag is to be used only when merging two archives. Instead of the
                           usual  merging  where  each  files  of  both archives are added to the
                           resulting archive with eventually a tie using the  overwriting  policy
                           (see  -/ option), here the merging builds an archive which corresponds
                           to the decremental backup done based  on  two  full  backups.  the  -A
                           backup  is  expected  to  receive  the  older  archive while the -@ is
                           expected to point to the more recent one. If this option is used,  the
                           eventually   overwriting   policy   is  ignored  and  replaced  by  -/
                           "{T&R&~R&(A|!H)}[S*]    P*    ;    {(e&~e&r&~r)|(!e&!~e)}[*s]     *p".
                           Additionally, files found int the newer archive that do not existed in
                           the older are replaced by a 'detruit' entry, which marks  them  to  be
                           remove  at  restoration  time.  For more information about decremental
                           backups read the usage_notes.html file in the documentation.

       -asecu, --alter=secu
                           This option  disable  the  ctime  check  done  by  default  during  an
                           incremental  backup:  If  the  ctime of an inode has changed since the
                           archive of reference was done with all other  values  being  unchanged
                           (inode  type,  ownership,  permission,  last  modification  date, file
                           size), dar issues a "SECURITY WARNING", as this may be the sign of the
                           presence of a rootkit. You should use this option to disable this type
                           of warning, if you are doing a differential backup of a just  restored
                           data  (differential backup with the archive used for restoration taken
                           as reference), as it is not possible to restore ctime, restored data's
                           ctime  will  have changed while other parameters will be unchanged for
                           all restored files, leading dar to issue a warning  for  all  restored
                           files. This security check is disabled (implicitly) if dar is run with
                           -ac option. Last, if a file has only its EA changed since the  archive
                           of   reference  was  done,  the  security  warning  will  show  (false
                           positive).

       -., --user-comment "<message>"
                           This option let the user add an arbitrary  message  into  the  archive
                           header.  Warning! this message is always stored in clear text, even if
                           the archive is encrypted. You can  see  the  message  inserted  in  an
                           archive  displaying  the  archive  summary (dar -l <archive> -q). Some
                           macro can be used inside the <message>:

                           %c   is replaced by the command line used. Note that for security, any
                                option  related to archive encryption is removed (-K, -J, -$, -#,
                                -*, -%). The command included from a DCF file (see -B option) are
                                never  added  by this macro. As a consequence, if you do not want
                                to see --user-comment stored in user comments  you  can  add  the
                                --user-comment  definition  in an included file like ~/.darrc for
                                example.

                           %d   this is the current date and time

                           %u   this is the uid under which dar has been run

                           %g   this is the gid under which dar has been run

                           %h   the hostname on which the archive has been created

                           %%   the % character.

       -3, --hash <algo>   When creating, isolating or merging an archive, beside each  slice  is
                           generated an on-fly hash file using the specified algorithm. Available
                           algorithm are "md5" and "sha1", by default no hash file is  generated.
                           The  hash  file generated is named based on the name of the slice with
                           the .md5 or .sha1 extension added to it at the end. These  hash  files
                           can be processes by md5sum and sha1sum usual commands (md5sum -c <hash
                           file>) to verify that the slice has not been corrupted. Note that  the
                           result  is  different  than  generating  the hash file using md5sum or
                           sha1sum once the slice is created,  in  particular  if  the  media  is
                           faulty:  calling  md5sum or sha1sum on the written slice will make you
                           compute the hash  result  on  an  already  corrupted  file,  thus  the
                           corruption  will not be seen when testing the file against the hash at
                           a later time. Note also that the  creation  of  a  hash  file  is  not
                           available when producing the archive on a pipe ("dar -c -").

       -<, --backup-hook-include <mask>
                           The  mask is applied to path+filename during backup operation only. If
                           a given file matches the mask, a user command (see  -=  option  below)
                           will  be  run before proceeding to the backup and once the backup will
                           be completed. See also -> option below. IMPORTANT: if using the  short
                           option,  you need to enclose it between quotes: '-<' for the shell not
                           to interpret the < as a redirection.

       -> --backup-hook-exclude <mask>
                           The mask is applied to path+filename during backup operation only.  If
                           a  given  file matches the mask, even if it matches a mask given after
                           -< option, no user command will  be  executed  before  and  after  its
                           backup.  The  -<  and  -> options act like -g and -P, they can receive
                           wildcard expression and thus have  their  comportment  driven  by  the
                           --alter=globe and --alter=regex expressions seen above, as well as the
                           --alter=mask option. Last the --alter=case and --alter=no-case  modify
                           also  the  way  case  sensitivity  is  considered  for these masks. By
                           default, no -> or -< option, no file get  selected  for  backup  hook.
                           IMPORTANT:  if  using the short option, you need to enclose it between
                           quotes: '->' for the shell not to interpret the > as a redirection.

       -=, --backup-hook-execute <string>
                           for files covered by the  mask  provided  thanks  to  the  -<  and  ->
                           options,  the given string is executed by a shell before the backup of
                           that file starts and once it has completed. Several macro can be  used
                           that are substituted at run time:

                           %%        will be replaced by a literal %

                           %p        will be replaced by the full path under backup

                           %f        will be replaced by the filename (without the path)

                           %u        will be replaced by the UID of the file

                           %g        will be replaced by the GID of the file

                           %c        and  most  interesting, %c (c for context), will be replaced
                                     by "start" or by "end" when the command is  executed  before
                                     or after the backup respectively.
       This way, one can stop a database just before it was about to be backed up, and restart it
       once the backup is completed. Note that the masks seen above that drive the  execution  of
       this  command  can be applied to a directory or a plain file for example. When a directory
       is selected for this feature, the command is  logically  ran  before  starting  (with  the
       context  "start") to backup any file located in that directory or in a subdirectory of it,
       and once all file in that directory or subdirectories have been saved, the command is  ran
       a second time (with the context "end"). During that time, if any file do match the backup-
       hook masks, no command will be executed for these. It is assumed that when a directory has
       been  asked  for  a  backup-hook to be executed this hook (or user command) is prepare for
       backup all data located in that directory.  The  environment  variable  DAR_DUC_PATH  also
       applies to these user commands (see -E above, or the ENVIRONMENT paragraph below).

       -ai, --alter=ignore-unknown-inode-type
                           When dar meets an inode type it is not aware about (some times ago, it
                           was the case for Door inode on Solaris for example,  Door  inodes  are
                           handled  by  dar  since  release 2.4.0), it issues a warning about its
                           inability to handle such inode. This warning occurs even if that entry
                           is  filtered  out by mean of -X, -I, -P, -g, -[ or -] options, as soon
                           as some other entry in that same directory has to  be  considered  for
                           backup,  leading  dar  to  read that directory contents and failing on
                           that unknown inode type (filtering is done  based  on  the  result  of
                           directory  listing).  This option is to avoid dar issuing such warning
                           in that situation.

       RESTORATION OPTIONS (to use with -x)

       -k[{ignored|only}], --deleted[={ignore|only}]
                           Without argument or with the "ignore" argument, this option leads  dar
                           at  restoration  time to not delete files that have been deleted since
                           the backup  of  reference  (file  overwriting  can  still  occur).  By
                           default,  files that have been destroyed since the backup of reference
                           are deleted  during  restoration,  but  a  warning  is  issued  before
                           proceeding,  except  if  -w  is  used.  If -n is used, no file will be
                           deleted (nor overwritten), thus -k is useless when  using  -n.  If  -/
                           option  is  used,  this  option  without argument is ignored! With the
                           "only" argument, this option only  consider  files  marked  as  to  be
                           removed  in the archive to restore, no file are restored but some file
                           are removed. When -konly (or --deleted=only) is used, the -/ option is
                           ignored (at the opposition of the "--no-delete=ignore" option which is
                           ignored when the -/  is  used).  Of  course  "--no-delete=ignore"  and
                           "--no-delete=only"  are  mutually  exclusive,  because if both of them
                           were available at the same time dar would do nothing at all.

       -r, --recent        only restore files that are absent or more recent than  those  present
                           in filesystem. If -/ option is used, this option is ignored!

       -f, --flat          do  not  restore directory structure. All file will be restored in the
                           directory given to -R, if two files  of  the  same  name  have  to  be
                           restored, the usual scheme for warning (-w option) and overwriting (-n
                           option) is used. No rename  scheme  is  planned  actually.  When  this
                           option  is  set,  dar  does  not remove files that have been stored as
                           deleted since last backup. (-f implicitly implies -k).

       -ae, --alter=erase_ea
                           [DEPRECATED use -/ instead] Drop all existing EA of files  present  in
                           filesystem that will have to be restored. This way, the restored files
                           will have the exact set of EA they had at the time of the  backup.  If
                           this  option  is  not  given,  a  file  to  restore  will  have its EA
                           overwritten by those present in the backup and if some extra  EAs  are
                           present  they  will remain untouched. See the Note concerning Extended
                           Attributes (EA) above for a detailed explanation about this  behavior.
                           If -/ option is used, this option is ignored!

       -A, --ref [<path>]/<basename>
                           -A  takes a different meaning when used with -x, -d or -t. The archive
                           given after -A must be an extracted catalogue  based  on  the  archive
                           given  after  -x, -d or -t.  This extracted catalogue will be used for
                           the operation in place of the catalogue located in the  archive.  This
                           feature  is intended for the case of corruption within an archive that
                           affects the internal catalogue. If you have a sane extracted catalogue
                           of a given archive you can use it as replacement of the one located in
                           the archive itself. Note that with the -A option  are  also  available
                           the following options: -F, -J and -*.

       -D, --empty-dir     At  restoration  time,  if  -D is not specified (default) any file and
                           directory is restored in regard to the filtering  mechanism  specified
                           (see  -I, -X, -P, -g, -[ and -] options). But if -D option is provided
                           the restoration skips directory trees that do not contain saved files.
                           This  avoid  having  a  huge  empty  tree  with  a  few restored files
                           especially when restoring a differential archive in  an  empty  place.
                           Note:  This  feature cannot work when --sequential-read is used, as it
                           is not possible to know whether a directory contains or not some saved
                           files  at  the  time  the  directory inode is read from the archive in
                           sequential reading mode.

       -2, --dirty-behavior { ignore | no-warn }
                           At restoration time, if a file in the archive is  flagged  as  "dirty"
                           (meaning  that it had changed at the time it was saved), user is asked
                           for confirmation before restoring it. Specifying  "ignore"  will  skip
                           those  dirty  files,  while  "no-warn"  will restore them without user
                           confirmation. This feature is  incompatible  with  sequential  reading
                           mode,  in  this  mode  dar  cannot know whether a file is dirty before
                           having restored it, in consequences, dar cannot warn nor ignore that a
                           file  is dirty before restoring it, at that time if a file is dirty it
                           will be removed unless dirty-behavior is set to "no-warn".

       -al, --alter=lax    Dar will try to workaround data corruption of  slice  header,  archive
                           header  and  catalogue.  This  option  is  to  be  used as last resort
                           solution when facing media corruption. It is rather and still strongly
                           encourage  to  test  archives  before relying on them as well as using
                           Parchive to do parity data of each slice to be able  to  recover  data
                           corruption  in  a much more effective manner and with much more chance
                           of success. Dar also has the possibility to backup a  catalogue  using
                           an  isolated catalogue, but this does not face slice header corruption
                           or even saved file's data corruption (dar will  detect  but  will  not
                           correct such event).

       -/, --overwriting-policy <policy>
                           Overwriting  policy can be used for archive restoration to define when
                           and how file overwriting can occur. See above the description of  this
                           option.

       TESTING AND DIFFERENCE OPTIONS (to use with -t or -d)

       -ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
                           Whith  this option set, when comparing a symlink, mtime difference, no
                           message shows when symlink in archive ans  symlink  on  filesystem  do
                           only differ by their by their mtime. See also -O option.

       No  other  specific  option,  but  all general options are available except for example -w
       which is useless, as testing and comparing only read  data.  -A  option  is  available  as
       described just above for extraction (backup of internal catalogue).

       Doing  a  difference in sequential read mode is allowed but hard linked inodes can only be
       compared to the filesystem the first time they are met, next hard links to this same inode
       cannot  obtain the corresponding data because skipping backward in sequential read mode is
       forbidden. In that situation, the hard links are reported as skipped,  meaning  that  data
       comparison could not be performed.

       LISTING OPTIONS (to use with -l)

       -T, --list-format=<normal | tree | xml>, --tree-format
                           By  default, listing provides a tar-like output (the 'normal' output).
                           You can however get a tree-like output (the 'tree' output) or  an  XML
                           structured  output  (the  'xml' output). Providing -T without argument
                           gives the same as providing the 'tree'  argument  to  it.  The  option
                           --tree-format    is   an   alias   to   --list-format=tree   (backward
                           compatibility). Note that the files doc/dar-catalog-*.dtd  define  the
                           format  of  the  XML output listing (This file is also installed under
                           $PREFIX/share/doc)

       -as, --alter=saved  list only saved files

       -alist-ea, --alter=list-ea
                           list Extended Attributes name for each file that has some.

       -I, -X, -P, -g, -[, -]
                           can be used to filter file to list base on their name or path.

       Else only -v and -b from general options are useful. Note  that  -v  displays  an  archive
       summary  first,  where a detailed of information about the archive can be obtained. If you
       want to display only this summary use -q with -l option.

       displayed fields

                 [data]    possible values are [     ] or [Saved] or [InRef] or[DIRTY].  [      ]
                           means  that  the  data  has  not been saved because there is no change
                           since backup of reference. [Saved] means that the data has been saved,
                           and thus this archive is able to restore the file. [InRef] was used in
                           archive generated by dar version 2.3.x and before,  when  isolating  a
                           catalogue  from  an  archive  and means that the file was saved in the
                           reference archive. Last,  [DIRTY]  means  that  data  is  saved  (like
                           [Saved])  but  has  changed at the time dar was reading it for backup,
                           leading dar to possibly store the file in a state it never had.

                 [EA]      possible values are " " (empty string) or [     ] or [InRef],  [Saved]
                           or [Suppr]. It Shows whether Extended Attributes are present and saved
                           ([Saved]), are present but not saved ([     ]) which means there is no
                           change  since  backup  of  reference, if there is no EA saved for this
                           file (empty string) or if some EA  were  present  in  the  archive  of
                           reference  but none is currently available ([Suppr]). [InRef] was used
                           when isolating a catalogue (release 2.3.x and before) from an  archive
                           and means that the file was saved in the reference archive.

                 [compr]   possible values are [....%] or [-----] or [     ] or [worse]. Shows if
                           the   file   has   been   compressed   and   the   compression   ratio
                           "compressed/uncompressed"  ([...%],  for example [ 33%] means that the
                           compressed data takes a third of the corresponding uncompressed  data,
                           thus  the  lower  is this ratio, the better is the compression), or if
                           the file is stored without compression ([    ] see -Y and -Z  options)
                           or if the file is not subject to compression because it is not a saved
                           regular file ([----]), or if the file takes more space compressed than
                           its  original  size  ([worse]), due to compression overhead. Note that
                           the compression ratio used here is the  inverse  of  what  compression
                           tools  usually  provide  (uncompressed/compressed). The reason of this
                           choice is that the ratio used here has the advantage  to  always  stay
                           between  0 and 100%, which is much more easy to work with to provide a
                           well formatted output.

                 [S]       possible values are [ ] or [X]. [X] only applies to saved plain files,
                           and  tells  that  the file is stored using sparse file data structure:
                           not all data is stored, long sequence of zeros are skipped. This  also
                           means  that  at restoration time, if the filesystem supports it, holes
                           will be  restored.  To  store  hole  information  libdar  uses  escape
                           sequence  (special  sequence  of  byte),  but to avoid real data to be
                           considered as such escape sequence, a special escape sequence is  used
                           when  data looks like an escape sequence. So if a data contains a such
                           escape sequence, it must be read as if it contains holes to be able to
                           restore  back  the data in its original form. For that reason, in some
                           rare circumstances (saving an dar archive inside a dar archive without
                           compression  or  encryption,  for  example) a file without hole may be
                           marked [X] as if it had holes and will be longer by on byte  for  each
                           data sequence looking like an escape sequence.

                 permission
                           see  ls  man page. Note that a star (*) is prepended to the permission
                           string if the corresponding inode  is  linked  several  times  to  the
                           directory structure (hard link).

                 user      owner of the file

                 group     group owner of the file

                 size      size  in byte of the file (if compression is enabled, the real size in
                           the archive is "compression rate" time smaller).

                 date      the last modification date of the file. The last access time  is  also
                           saved and restored, but not displayed.

                 filename  The name of the file.

       EXPLICIT OPTIONAL ARGUMENTS

              When  dar has not been compiled with GNU getopt, which is not present by default on
              some systems like FreeBSD, you may lack the optional arguments syntax. For  example
              "-z"  will  create a parse error on command-line, or in -B configuration files. The
              solution is to explicitly give the  argument.  Here  follows  a  list  of  explicit
              argument to use in place of optional ones:

       -z                  must be replaced by -z 9

       -w                  must be replaced by -w d or -w default

       -H                  must be replaced by -H 1

       -0                  must be replaced by -0 ref

       important  !   When  using  GNU getopt(), optional arguments are available by sticking the
       argument to the short option: "-z" for example is available as well as "-z9". But  "-z  9"
       is wrong, it will be read as "-z" option and "9", a command line argument (not an argument
       to the -z option). In the other side, when using a non GNU getopt this time, "-z"  becomes
       an  option  that  always requires an argument, and thus "-z 9" is read as "-z" option with
       "9" as argument, while "-z9" will be rejected as a unknown option,  and  "-z"  alone  will
       generate  an  error  as no argument is provided. In consequences, you need a space between
       the option (like "-z") and its argument (like "9"), when  dar  does  not  rely  on  a  GNU
       getopt()  call,  which  also  imply you to explicitly use arguments to options listed just
       above.

EXIT CODES

       dar exits with the following code:

       0         Operation successful.

       1         Syntax error on command-line.

       2         Error due to a hardware problem or a lack of memory.

       3         Detection of a condition that should never happen, and which is considered as  a
                 bug of the application.

       4         Code  issued  when  the user has aborted the program upon dar question from dar.
                 This also happens when dar is not run from a terminal (for example launched from
                 crontab)  and  dar has a question to the user. In that case, dar aborts the same
                 way as if the user pressed the escape key at the question prompt.

       5         is returned when an error concerning the treated data has been  detected.  While
                 saving,  this  is  the  case  when  a  file  could  not be opened or read. While
                 restoring, it is the case when a file could not be created  or  replaced.  While
                 comparing,  it  is the case when a file in the archive does not match the one in
                 the filesystem. While testing, it is the case when a file is  corrupted  in  the
                 archive.

       6         an  error  occurred  while  executing user command (given with -E or -F option).
                 Mainly because the creation of a new process is not possible (process  table  is
                 full)  or  the  user  command  returned  an error code (exit status different of
                 zero).

       7         an error has occurred when calling a libdar routine. This means the caller  (dar
                 program),  did  not  respect  the  specification  of  the  API  (and this can be
                 considered as a particular case of a bug).

       8         the version of dar used is based in finite length integers (it has been compiled
                 with  the  option  --enable-mode=...).  This  code  is  returned when an integer
                 overflow occurred. use the full version  (based  in  the  so  called  "infinint"
                 class) to avoid this error.

       9         this  code  indicates  an unknown error. I have probably forgotten to update the
                 exception caching code to take care of new exceptions... this is a minor bug you
                 are welcome to report.

       10        you have tried to use a feature that has been disabled at compilation time.

       11        some saved files have changed while dar was reading them, this may lead the data
                 saved for this file not correspond to a valid state for this file. For  example,
                 if  the  beginning  and  the end of the file have been modified at the same time
                 (while dar is reading it), only the  change  at  the  end  will  be  saved  (the
                 beginning has already been read), the resulting state of the file as recorded by
                 dar has never existed and may cause problem to the application using it.

SIGNALS

       If dar receives a signal (see kill(2) man page) it will take the  default  behavior  which
       most of the time will abruptly abort the program, except for the following signals:

       SIGINT    This  signal  is  generated  by  the  terminal  when  hitting  CTRL-C  (with the
                 terminal's default settings), it can also be generated with the kill command

       SIGTERM   This signal is generated by the system when changing of run-level in  particular
                 when doing a shutdown, it can also be generated with the kill command

       SIGHUP    Depending  on  the  system, this signal may be sent before the SIGTERM signal at
                 shutdown time, it can also be generated with the kill command

       SIGQUIT   This signal  is  generated  by  the  terminal  when  hitting  CTRL-\  (with  the
                 terminal's default settings), it can also be generated with the kill command

       SIGUSR1   This signal can be generated by the kill command

       SIGUSR2   This signal can be generated by the kill command

       For  those  previous  signals, two behavior exit. For SIGHUP, SIGINT, SIGQUIT, SIGTERM and
       SIGUSR1, a delayed termination is done: the backup or isolation operation is stopped,  the
       catalogue  is  appended  to  the  archive  and  the archive is properly completed with the
       correct terminator string, this way the generated archive is usable, and can  be  used  as
       reference  for a differential backup at a later time. Note that if an on-fly isolation had
       been asked, it will *not* be performed, and no user command will be launched even  if  dar
       has  been  configured  for (-E option). For SIGUSR2 instead a fast termination is done: in
       case of backup or isolation, the archive is not completed at all, only  memory  and  mutex
       are released properly.

       For both type of termination and other operations than backup or isolation, dar's behavior
       is the same: For restoration, all opened directories are closed and  permissions  are  set
       back  to  their  original values (if they had to be changed for restoration). For listing,
       comparison, testing, the program aborts immediately.

       Another point, when using one of the previous signals, dar  will  return  with  the  exist
       status  4  meaning  that the user has aborted the operation. Note that answering "no" to a
       question from dar may also lead dar to exit this way. last,  If  before  the  end  of  the
       program the same signal is received a second time, dar will abort immediately.

FILES

       $HOME/.darrc  and  /etc/darrc if present are read for configuration option. They share the
       same syntax as file given to -B option. If $HOME/.darrc is not present and  only  in  that
       case,  /etc/darrc  is  consulted.  You  can  still  launch  /etc/darrc from .darrc using a
       statement like -B /etc/darrc.  None of these file need to be present, but if they are they
       are  parsed AFTER any option on the command line and AFTER included files from the command
       line (files given to the -B option). NOTE: if $HOME is not defined $HOME/.darrc default to
       /.darrc (at the root of the filesystem).

       Else  you  can see conditional syntax bellow, and -N option above that leads dar to ignore
       the /etc/darrc and $HOME/.darrc files.

CONDITIONAL SYNTAX

       configuration files (-B option, $HOME/.darrc and /etc/darrc) usually contain a simple list
       of  command-line  arguments,  split  or  not over several lines, and eventually mixed with
       comments (see -B option for more). But, you can also use make-like targets to  ask  for  a
       particular set of commands to be used in certain conditions.

       A condition takes the form of reserved word immediately followed by a colon ':'. This word
       + colon must stand alone on its line, eventually  with  spaces  or  tabs  beside  it.  The
       available conditions are:

       extract:            all  option  listed  after  this  condition  get used if previously on
                           command line or file the -x option has been used

       create:             all option listed after this  condition  get  used  if  previously  on
                           command line or file (-B option) the -c option has been used

       list: (or listing:) if -l option has been used

       test:               if -t option has been used

       diff:               if -d option has been used

       isolate:            if -C option has been used

       merge:              if -+ option has been used

       reference:          if  -A  option  has been used (except when -A is used for the snapshot
                           feature or in conjunction with -af)

       auxiliary:          if -@ option has been used

       all:                in any case

       default:            if no -c, -d, -x, -t, -C, -l  or -+ option has been used at this point
                           of the parsing.

       The  condition  stops  when  the  next  condition  starts, or at End of File. The commands
       inserted before any condition are equivalent to those inserted after the "all:" condition.
       Remark  :  -c  -d -x -t -C and -l are mutual exclusive, only one of them can be used while
       calling dar.

       Here is an example of conditional syntax

              create:
                # upon creation exclude the
                # following files from compression
              -Z "*.mp3" -Z "*.mpg"

              all:
              -b
              -p

              default:
              # this will get read if not
              # command has been set yet
              -V
              # thus by default dar shows its version

              all:
              -v
              # for any command we also ask to be verbose
              # this is added to the previous all: condition

       Last point, you may have several time the same condition (several all: ) for example. They
       will be concatenated together.

USER TARGETS

       User targets are arbitrary words found on command line, that do not start by a dash ('-').
       On most system they should be placed after command and options. They  are  collected  from
       command-line first, then comes the parsing of command and optional arguments. Their use is
       to extend conditional syntax described just above by having a set of options activated  by
       the  user  just  adding  a single word on command-line. Of course user targets must not be
       equal to one of the reserved words of the conditional syntax (extract,  create,  ...  all,
       default). A valid target is a word (thus without space) composed of lowercase or uppercase
       letters (case is  sensitive)  with  eventually  digits,  dashes  '-'  or  underscores  '_'
       characters.

       Let's see an example of use:

       first a DCF file named 'example.dcf' that will be given on command line:

              # normal set of files considered for backup

              create:
                -R /
                -P proc
                -P sys
                -P mnt
                -D

              #  if  the  "home" user target is applied on command line the following command get
              added

              home:
                 -g home

              # if the "verbose" user target is used, we will have some more verbosity ...

              verbose:
                -v
                -vs

       Then we could run dar in the following ways:

       dar -c test -B example.dcf
                           in that case only the command in the "create:" section of  example.dcf
                           would be used.

       dar -c test -B example.dcf verbose
                           here  over  the  "create:"  target  the  commands under the "verbose:"
                           target (-v and -vs) would be also used

       dar -c test -B example.dcf verbose home
                           last we use two user targets "verbose:" and "home:"  in  addition  the
                           the "create:" target of the usual conditional syntax.

       Note that if the last option *may* receive an argument, the first user target that follows
       it will be assumed an argument to that option. To avoid this, either change the  order  of
       options  on  command  line for the last option been an option that never or always uses an
       argument (for example -b never has an argument while -s always has one). Or  separate  the
       options  from the user targets by the -- word. And of course you can also use the explicit
       argument of the last option (see EXPLICIT OPTIONAL ARGUMENT section, above).

       Second point: It is allowed to have user targets inside a  DCF  file.  Note  however  that
       targets  are  collected  in  a first phase, which leads some part of the file to be hidden
       (because the corresponding conditional syntax or user target is not  present).  Then,  the
       remaining  part  of the file is then parsed and actions for each option found is taken. At
       that time, new user targets found are just recorded, but they do not  modify  the  current
       DCF  file  layout,  in  particular,  hidden  part  of  the  file  stay  hidden even if the
       corresponding user target is read in this same  file.  Next  DCF  parsing  (which  may  be
       triggered  by a second -B option on the command line, or by a -B option inside the current
       parsed DCF file) will thus be done with the additional targets found  in  that  first  DCF
       file, so in a way you may have user targets that activate other user targets. Here follows
       an examples of two DCF files, first.dcf and second.dcf:

              # cat first.dcf
                target3:
                  -K toto

                target1:
                  target2
                  -B second.dcf
                  target3

                target2:
                  #never reached
                  -s 10k

              # cat second.dcf
                target2:
                  -v
                target3:
                  -b

       In that example, target1 activates both target2 and  target3,  but  at  the  time  of  the
       parsing  of  first.dcf,  neither target2 nor target3 were yet activated thus '-K toto' and
       '-s 10k' will never be given to dar (unless activated beside target1 before first.dcf  get
       parsed),  however  when  comes  the  time  to  parse second.dcf, target2 *and* target3 are
       activated, thus both '-v' and '-b' will be passed to dar, even  if  'target3'  is  located
       after '-B second.dcf' in the file first.dcf

ENVIRONMENT

       DAR_DCF_PATH
                 if  set, dar looks for Dar Configuration File (DCF files, see -B option) that do
                 not have an fully qualified path  in  the  directories  listed  in  DAR_DCF_PATH
                 environment  variable.  This  variable  receives  a column (:) separated list of
                 paths and look in each of them in turn, up to the first  file  found  under  the
                 requested name.

       DAR_DUC_PATH
                 if  set,  dar looks for Dar User Command (DUC files, see -E, -F, -~, -= options)
                 that  do  not  have  a  fully  qualified  path  in  the  directories  listed  in
                 DAR_DUC_PATH.  This  variable  receives a column (:) separated list of paths and
                 looks in each of them in turn, up to the first file found  under  the  requested
                 name.

EXAMPLES

       You  can  find  some more examples of use in the tutorial, mini-howto, sample scripts, and
       other related documentation. All these are available in dar's source package, and are also
       installed  beside  dar  in  the <--prefix>/share/dar directory. This documentation is also
       available on-line at http://dar.linux.free.fr/doc/index.html#2

SEE ALSO

       dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), TUTORIAL and NOTES included in  the
       source package and also available at http://dar.linux.free.fr/doc/index.html

KNOWN BUGS

       dar  cannot restore time of symbolic links. Many (all ?) UNIX do not provide any way to do
       that, the utime() system call changes the file pointed to by the link rather than the date
       of the link itself.

       dar  saves  and  restores  atime  and mtime, but cannot restore ctime (last inode change),
       there does not seems to be a standard call to do that under UNIX.

AUTHOR

       http://dar.linux.free.fr/
       Denis Corbin
       France
       Europe