Provided by: dar-static_2.6.8-1_amd64 bug

NAME

       dar - creates, tests, lists, extracts, compares, merges, isolates, repairs dar archives

SYNOPSIS

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

       dar -h

       dar -V

DESCRIPTION

       dar is a full featured backup tool, aimed for local and  remote  disks  (floppy,  CD-R(W),
       DVD-R(W),  zip,  jazz, hard-disks, usb keys, etc. and cloud storage by mean of ftp or sftp
       protocols) and also 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  DVD-R(W),  Blue-
       ray  Disk,  or  changing  of  usb  key 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, incremental and
       decremental  backups.  In  other  words, backups that contain only new files or files that
       have changed from a backup of reference. Binary delta is available but  not  activated  by
       default:  in  combination  with differential and incremental backups, it leads not only to
       not save a file that has not changed (thing dar does without binary delta),  but  also  to
       only save an rsync patch of any modified file, which lead to even smaller backups.

       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 the differential backup was made.  dar is the first backup program I  know  that  can
       also remove files during restoration! By the way, in this document, "archive" and "backup"
       are used interchangeably, the difference is the purpose you build them for.

       Unlike the tar command, dar has not to read a whole archive  nor  to  stick  together  the
       different  parts  (the  slices)  to  access  its contents: dar archives contain a table of
       contents (aka "catalogue") located at the end, so dar can seek into the  archive  to  read
       only  the required data to restore files, thing which is much faster than what tar is used
       to do. The "catalogue" can be copied out of the archive (operation called isolation) to be
       used  as  reference  for further backup and as backup of the internal catalogue in case of
       archive corruption.

       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, a first time  all
       along  the archive used for tar-like behavior suitable for sequential access media (tapes)
       and a second time at the end for faster access, suitable for random access media  (disks).
       However  note  that  tar  archive  and  dar archive are not compatible. 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) and since release 2.6.0 such
       truncated archive can be repaired to become a normal archive (the "catalogue"  is  rebuilt
       from inlined information).

       Dar  is  able  to  save  and  restore  to  a  cloud storage by mean of ftp or sftp network
       protocols. It can also leverage ssh protocol using dar_slave and dar_xform two  auxilliary
       programs provided beside dar.

       Dar  format  is  quite  robust against corruption: Only the file where the corruption took
       place in the archive will not be possible to restore. To have the possibility to repair  a
       corrupted archive dar can work with par2 seamlessly just specifying "par2" on command-line
       (see /etc/darrc). Last a "relax" reading mode is available which let dar to either  ignore
       some incoherence in archive structure, use internal redundant information to overcome data
       corruption or in last resort asking the user on what to do  when  some  archive  structure
       information  is missing (-al option). This relax mode can be used with both sequential and
       direct access read modes. Note 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.

       dar takes care of POSIX Extended Attributes (EA in short)  that  are  used  in  particular
       under  Linux  to  carry File Access Control List (FACL) as well as security attributes for
       SELinux, and also under MacOS X EA they are used to store file forks. EA  also  have  room
       for  user  to  add  any  key  /  value  paire to any file, this is known as user EA. These
       attributes are not specific to any particular filesystem, they exist the  same  way  under
       ext3/4, HFS+ and any other filesystem.

       dar also takes care of Filesystem Specific Attributes (FSA in short) which are, as you can
       guess, specific to one or several filesystem(s). For example the  Birth  date  of  a  file
       exists  for  HFS+ and NTFS but not for ext2/3/4 filesystem. The immutable attribute exists
       for ext2/3/4 but not for NTFS while the nodump files does not exists for NTFS  but  exists
       for HFS+, ext2/3/4 and many other Unix filesystems.

       Sparse  files  (files with holes that system reports using several hundred gigabytes while
       they effectively use a few kilobytes on disk) are also  well  managed  by  dar:  they  are
       detected, stored and restored to filesystem properly.

       Last, dar is also able to properly save and restore hard-links

WARNING

       This  document  is  to  be  considered  as  a full reference of dar/libdar features. It is
       however not adapted to discover dar, for that purpose some tutorials are provided  in  dar
       documentation.  Once  you  have  apprehended  the basic dar usages you are welcome to read
       further this document to see all other features you may find useful for your needs.

DOCUMENT STRUCTURE

       The rest of this document is organized that way:

              COMMANDS
                   The eight actions you can performs with dar

              GENERAL OPTIONS
                   A set of options common to all actions

              SAVING, ISOLATING, MERGING AND REPAIRING SPECIFIC OPTIONS
                   A set of options that are specific  to  the  operation  of  backup,  catalogue
                   isolation and archive merging

              RESTORATION SPECIFIC OPTIONS
                   A set of options that are specific to the restoration operation

              TESTING AND DIFFERENCE SPECIFIC OPTIONS
                   A  set  of  options  that are specific to the operation of archive testing and
                   archive comparison with a filesystem

              LISTING OPTIONS
                   A set of options that are specific to archive listing operation

              EXPICIT OPTIONAL ARGUMENTS
                   Some system do not allow optional arguments to options, this  chapter  explain
                   how to overcome this restriction

              EXIT CODES
                   List of values dar returns at end of execution. This chapter should be read if
                   you intend to create scripts relying on dar

              SIGNALS
                   details the signal and their action on a running dar process

              FILES
                   List configuration files that dar checks for

              CONDITIONAL SYNTAX
                   Over command line, command and options can be passed to dar thanks to a  plain
                   file  (known  as DCF file). This plain file can also contain a specific syntax
                   that  will  let   you   pass   an   option   to   dar   only   under   certain
                   situation/condition.  This  chapter  describes  this  simple  syntax  and  the
                   different available conditions.

              USER TARGETS
                   User can add  their  own  conditions  known  as  user  targets.  This  chapter
                   describes what they are and how to use them

              ENVIRONMENT
                   Dar  may  rely  on  environment variables to look for DCF files and DUC files,
                   SFTP private and public key and so on.

COMMANDS AND OPTIONS

       COMMANDS:

       Only eight commands define what action will be done  by  dar:  Archive  creation,  archive
       extraction,   archive  listing,  archive  testing,  archive  comparison  with  filesystem,
       catalogue isolation, archive merging and archive repairing. 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.

       Important note: Not all systems 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 systems 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.

       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). For
       example "my_first_archive.42.dar" is the 42th slice  of  the  archive  which  basename  is
       "my_first_archive".

       -c, --create [[<URL>]<path>/]<basename>
                           creates  a  backup  with  the name based on <basename>. All the slices
                           will be created in the directory <path> if  specified,  details  about
                           the  <URL>  syntaxe  is  explained  below  at Remote repository syntax
                           paragraph.  Without <path> nor <URL> the current directory is used. 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 directly or using the dar_split
                           command).

       -x, --extract [[<URL>]<path>/]<basename>
                           extracts files from the given backup. Slices are expected to be in the
                           current directory or in the directory given by <path> (see also Remote
                           repository syntax below). 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, USB key, 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  on  the
                           removable  media  you  plan to unmount (see tutorial for details). The
                           basename may be set  to  "-",  in  direct  access  mode  (the  default
                           historical  mode),  you will then 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-read is used on command-line), dar
                           will read the archive from standard input (see also -i  option),  this
                           can eventually be used in combination with dar_split.

       -l, --list [[<URL>]<path>/]<basename>
                           lists  the  contents  of  the given backup (see also Remote repository
                           syntax below) 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 [[<URL>]<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 data, file EA and  file  FSA  in
                           the  catalogue.  Archive  structure  (slice  header,  archive  header,
                           catalogue) is also protected by CRC to be able to detect any  kind  of
                           archive corruption. Same remark here, "-" may be used as basename (see
                           -x option above for details).

       -d, --diff [[<URL>]<path>/]<basename>
                           compares saved files in the  backup  with  those  on  the  filesystem.
                           <basename>  may  also  be  "-" (see -x option above for details). Note
                           that the target for this operation is to be seen  as  a  step  further
                           than  archive  testing,  where  in  addition to archive coherence, the
                           archive contents is verified to be the same as what is  found  on  the
                           filesystem.  But  if  new  files  are  present  on the filesystem, dar
                           ignores them. If you want to check for changes  since  a  archive  has
                           been made, better use dry-run differential backup.

       -C, --isolate [[<URL>]<path>/]<basename>
                           isolate a catalogue from its archive (that's to say make a copy of the
                           internal catalogue to its own archive container). The argument is  the
                           basename  of  the  file  to  create which will contain the catalogue's
                           copy. The -A option is mandatory here to give the name of the  archive
                           to  copy  the  catalogue  from,  this  archive is not modified at all.
                           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 quite no difference in concept
                           between an isolated catalogue and an archive.  Thus  you  can  do  all
                           operations on an isolated catalogue, in particular take it in place of
                           the original backup as reference for a differential  archive,  archive
                           testing,  archive  comparison.  Note  however  that for comparison (-d
                           option) as data is not present in the isolated catalogue,  dar  relies
                           on embedded CRC rather than comparing data byte by byte  (what is done
                           with a plain archive), and no comparison can be  performed  concerning
                           EA  or  FSA  even  if each of them have their own CRC in the catalogue
                           because different  ordering  as  provided  by  the  OS  of  the  items
                           composing  EA and FSA may lead the CRC to be different while the EA or
                           FSA are exactly the same, so CRC here is used only to dectect  archive
                           corruption.  Since  release 2.4.0 you can use an isolated catalogue to
                           rescue a corrupted internal catalogue of the archive it has been based
                           on (see -A option).

       -+, --merge [[<URL>]<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  GENERAL OPTIONS) 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 is 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.

       -y, --add-missing-catalogue [[<URL>]<path>/]<basename>
                           create a "repaired" archive based on the archive given with -A option.
                           The  repairing  only  concerns  the  case  where  an  archive has been
                           interrupted and dar could not cleanly end the archive creation process
                           (lack of disk space, power outage, and so on). This operation consists
                           in reading the tape marks in sequential reading  mode  to  gather  the
                           content  of  the  archive and once its end is reached, to recreate the
                           missing table of content (aka catalogue) located at  the  end  of  the
                           archive.  Note that the damaged archive is not modified but a repaired
                           copy is built beside it. Why not just appending the catalogue  to  the
                           archive?  Because  first it was simpler to implement allowing to reuse
                           routines of the merging operation, second by precaution for dar to not
                           mess  an  existing  archive  due  to  a  bug and last, it would not be
                           compatible with archive signing  and  gpg  encryption  under  certains
                           conditions  (several  recipients  or the archive is signed and you are
                           not the one who signed it).

              During the repairing operation, the repaired archive may have a  different  slicing
              (-s  and  -S options), a different encryption (-K and associated options, including
              gpg  encryption  and  signing),  a  different  repository  slices  permissions  and
              ownership  (--slice-mode  option),  user  comment  (--user-comment), generated hash
              (--hash) and min digits in slice number (--min-digits), but compression  cannot  be
              changed  and  tape  marks  cannot  be  removed  (you  can do it once reparation has
              completed using the merging operation). Last, file filtering is not allowed  during
              archive repairing.

       -h, --help          displays help usage.

       -V, --version       displays version information.

       Remote repository syntax for [<URL>]<path>

              for  all commands described above as well as some options detailes below (-A and -@
              options), the <path> optional argument can be a Unix path like  /var/tmp  when  the
              archive  is  located  on the host dar runs on. But it can also make use of <URL> to
              define the remote host the archive is to  be  read  or  written  to.  "<URL><path>"
              follows the usual syntax:

                     proto://[login[:password]@]hostname[:port]/path

              proto
                 is either ftp or sftp

              login
                 is  optional,  if  not  provided  it defaults to anonymous.  If the login string
                 comports an @ it need to be escaped by \\  (a  pair  of  backshashes)  to  avoid
                 libdar  considering it the hostname starting part. Exemple: login is me@here.com
                 host is www.example.org  gives:  sftp://me\\@here.com@www.example.org/some/file.
                 You  may  also need to escape the same way any other special characters like for
                 exampl ecolumn (:) slash (/) if they are part of the login string.

              password
                 if login is provided, the associated password may be given after  a  column  (:)
                 but this exposes the secret password to other users of the current system having
                 access the table of process (using top, ps, /proc or other ways). If  the  login
                 is  given  without  password, the password will be asked interactively by dar at
                 run time, which is much more secure. Alternatives are either to rely on ~/.netrc
                 for  FTP  and also SFTP (!) transfers for that you need to use the --alter=file-
                 authentication option (see below), or for SFTP only on public key authentication
                 (you  can  also use --alter=file-authentication in that case to avoid a password
                 being asked interactively). Note that passphrase support for  sftp  key  is  not
                 (yet) supported.

              hostname
                 is  the  name  or  IP  address  of the host to connect to. For sftp the server's
                 public key is checked against the ~/.ssh/known_hosts file (or the  file  pointed
                 to  by then environment variable DAR_SFTP_KNOWNHOST_FILE, see more details about
                 that variable at the bottom of this man page), the host must be  known  and  the
                 public  key  received from the network must match the one in that file, else dar
                 aborts. If thus you want to operate with a new sftp server,  first  use  ssh  of
                 sftp  commands  to  do  the  usual  fingerprint  verifications which updates the
                 known_hosts file accordingly, then run dar/libdar toward this sftp server.

              port
                 if not provided, dar will  use  the  default/standard  port  in  regard  to  the
                 protocol specified in the "proto" field

              path
                 a  unix  path  where  resides  the archive to read from the remote repository or
                 where to write the archive to in that  remote  repository.  The  given  path  is
                 absolute,  in  regard  to  the  remote  root  filesystem available for the given
                 account though the requested protocol.  See  also  --network-retry-delay  option
                 below.

       GENERAL OPTIONS:

       -v, --verbose       For  backward  compatibility,  this  is  an  alias  to "-vt -vm" (both
                           options set).

       -vs, --verbose=skipped
                           Display files skipped because of file filtering exclusion specified by
                           the user

       -vt, --verbose=treated
                           Display treated files because of file filtering inclusion specified by
                           the user or no file filtering  specified  at  all.  For  each  file  a
                           message  is displayed *before* the file is treated. This option is not
                           available for archive isolation and is useless for archive listing  as
                           it is always set, unless -q is used.

       -vd, --verbose=dir  Display  the  directory  under  process.  The  messages shows *before*
                           entering a directory. You can have a  less  verbose  output  than  -vt
                           while  are still able to follow what's dar is doing. Note that -vt and
                           -vd are mutually exclusive.

       -vm, --verbose=messages
                           Display detailed messages about what dar is currently  performing  but
                           not related to currently treated or skipped files and directories

       -vf, --verbose=finished
                           Issues  a summary *after* each treated directory containing the amount
                           of data backed up in that directory as well as the average compression
                           ratio. This option is only available for archive creation.

       -va, --verbose=all  is  equivalent to -vm -vs -vt, see also -Q and -q options below. Note:
                           When using dar from a script better use  dar's  exit  status  to  know
                           which  way the operation has ended (seen EXIT CODES at the end of this
                           document).

       -vmasks, --verbose=masks
                           Display raw information about the masks  set  by  dar  and  passed  to
                           libdar

       -q, --quiet         Suppress  the  final  statistics report. If no verbose output is asked
                           beside this option, nothing is displayed if  the  operation  succeeds.
                           When  using  dar  from  a  script better use dar's exit status to know
                           which way the operation has ended (seen EXIT CODES at the end of  this
                           document)

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

       -B, --batch <filename>
                           In the file which name is given in argument to this  option,  You  can
                           put  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 that includes itself directly  or  not)
                           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  a  comment  the  hash character must be the first character of the
                           line (space or tab can still precede the hash). See Conditional Syntax
                           below for a richer syntax in this type of configuration files known as
                           DCF file (Dar Configuration File). See also the  environment  variable
                           DAR_DCF_PATH in the ENVIRONMENT section at the end of this document.

       Note  that you can use quotes simple (´arg´) double ("arg") and back-quotes (`arg`) inside
       such file, but they need to be balanced (have  an  ending  one).  To  use  such  character
       without  the meaning of a quote, for example as an apostrophe, you need to escape it using
       a back-slack ("That\'s an example"). Of course to add a  single  back-slash  as  a  normal
       character in the file you will have to double it ("c:\\windows" for example)

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

       -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 by 'no', which most of  the
                           time  will  abort  the program. Please note that this option cannot be
                           used in a configuration file (-B option). 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 also redirect stdout
                           and/or sterr to files: dar -Q ... &> /dev/null &

       -n, --no-overwrite  do not allow overwriting

                           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.  Without
                           overwriting  policy, -n applies to restored files as well as generated
                           slices.

       -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 avoids 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)

       -A, --ref [[<URL>]<path>]/<basename>
                           Depending  on  the  context,  it  specifies  the  archive  to  use  as
                           reference,  which  is  mandatory for archive isolation (-C option) and
                           merging operation (-+ option). Else it specifies the rescue  catalogue
                           to  use when restoring (-x command), testing (-t command) or comparing
                           (-d command) an archive.  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 USB key, DVD-R(W) 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, when
                                  --senquential-read is not used) 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 only available when -A
                                  is  used for isolation (-C option) and merging (-+ options). In
                                  sequential mode (--sequential-read is  used),  the  archive  of
                                  reference  is  read  from standard input or from the named pipe
                                  specified by -i option. -o option  has  no  use  in  sequential
                                  mode.  Note  that  merging  operation  (-+  option) cannot read
                                  archive of reference in sequential mode.

                                  - a plus sign ("+") which makes the reference  be  the  current
                                  directory  status.  This argument is only available for archive
                                  creation (-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  feature  is  known  as  the  "snapshot"
                                  backup.  A snapshot backup can be used as reference later on to
                                  detect or save only the  files  that  have  changed  since  the
                                  snapshot was made.

                                  -  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. This form is only
                                  available for archive creation (-c option).

                           During backup operation (-c option) the archive  of  reference,  given
                           thanks to the -A option, is used for comparison with existing files on
                           the filesystem. Dar will then backup  only  files  that  have  changed
                           since the archive of reference was done. If no -A option is given, the
                           backup operation is a full backup. With -A option if  the  archive  of
                           reference  is  a full backup some call it a differential backup, while
                           if the archive of reference is differential  backup,  some  call  this
                           type  of  backup an incremental backup. For dar there is no difference
                           in structure between incremental and  differential  backup,  both  are
                           usually   designed   globally   as   "differential"   backup   in  the
                           documentation.

                           During merging operation (-+ option), the contents  of  the  -A  given
                           archive  will  been  taken  eventually  with  the  contents  of the -@
                           auxiliary archive if specified (see below), to form a new archive from
                           files  of  this  or these archives. Note that you can filter out files
                           from the operation and setup subset of the original archive(s).

                           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. 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 acts as  a  backup
                           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.

       -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 meaning when creating an
                           archive (-c option) and must be placed before -A  option  to  have  an
                           effect.

                           <date> must be a date in the two 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

                           Note  that  the provided date is relative to the system timezone which
                           is overriden if the TZ environement variable is set  (see  tzselect(1)
                           for more details)

       -@, --aux [[<URL>]<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). Note that --aux and --on-fly-isolate are really aliases  to
                           the  same  option,  this  is  the  context of use (archive creation or
                           merging) which lead it to behave a way or another.

                           In a merging context, over -A option which is mandatory, you may  give
                           a second archive of reference thanks to the -@ option. This allows you
                           to  merge  two  archives  into  a  single  one.  See  also  -$  option
                           (encryption)  -~ option (command execution) and -% (crypto block size)
                           for other options concerning auxiliary archive of reference. They  are
                           the respective equivalent of -J, -F and -* options relative to archive
                           given thanks to -A option.

                           In a backup context -@ option let the user specify  the  archive  name
                           for  an  on-fly  isolation. With on-fly isolation, you can also use -$
                           option (to define encryption algorithm and passphrase), -~ option  (to
                           execute a command once the on-fly isolated catalogue is completed) and
                           -% option (crypto block size). 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 on an isolated
                           catalogue if you only want to change slices size (this is faster as no
                           decompression/re-compression  nor encryption/decryption is necessary).
                           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 to --aux.

       -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 files  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 the whole 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, which
                           defaults to current directory.   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) each line must  not  exceed  20479
                           bytes.  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.  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 or -[ 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,  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.

       -4 --fsa-scope <family>[,<family>[, ...]
                           Reduce  the  scope  of  Filesystem  Specific  Attribute  (FSA)  to  be
                           considered  for  the  operation.  FSA  are  grouped by family. Current
                           available families are:

                           extX this family takes care of Linux ext2/3/4 flag attributes  set  by
                                chattr(1)  and  read  by lsattr(1). Dar only considers flags that
                                are possible to set or  clear  by  users  (or  privileged  user):
                                append-only,  compressed, no_dump (Yes, dar can save files having
                                the nodump flag set and restore then  afterward  with  that  flag
                                set!),   immutable,  data-journaling,  secure-deletion,  no-tail-
                                merging,  undeletable,   noatime-update,   synchronous-directory,
                                synchronous-update,  top-of-directory-hierarchy. Note that "extx"
                                and "ext" are aliases for this FSA family. In spite of its  name,
                                this family of attributes is not limited to ext2/3/4 filesystems.

                            HFS+
                                this  family  takes care of Mac OS X HFS+ birth date of files, in
                                addition of commonly found dates like atime (last  access  time),
                                ctime (last meta data change) and mtime (last data change).

                           none "none"  is  not  a FSA family but can be used alone to ignore all
                                FSA families.

                           By default no  restriction  is  done  and  FSA  of  all  families  are
                           considered at restoration time, but if a family has not been activated
                           at compilation time a warning is issued for each file that cannot have
                           its  FSA  restored completely (unless this family is excluded from the
                           scope thanks to the -4 option). At backup time, if an FSA  family  has
                           not  been  activated at compilation time, no warning is issued and FSA
                           of that family are ignored. Still at backup time, you can also  ignore
                           FSA  that  have  compilation  time  support by excluding them from the
                           operation thanks to this -4 option.

                           Example of use: --fsa-scope extX,HFS+

       -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.

       Warning: case insensitivity requires interpreting filenames which depends  on  the  locale
       with  which  dar  is  run  (defined  by the LANG environment variable). For example if you
       create files with LANG set to fr_FR.UTF-8 and use non plain ASCII characters in  filename,
       there is chances that these non ASCII characters will be stored over several bytes in that
       filename: so called "wide characters". If then you run dar with LANG set to another  value
       like  ru_RU.koi8r,  there  is much chances that these wide characters do not correspond to
       the same letter or worse, that they do not match any valid wide character for that locale.
       A  filename  is always a sequence of bytes and always saved as such, but using --alter=no-
       case implies interpreting that sequence in a way that depends  on  the  given  locale  (as
       defined by the LANG environment variable). As such, dar cannot know if a given file has to
       be read with fr_FR.UTF-8 locale or with it_IT.iso88591 or ru_RU.koi8r and so  on,  because
       this information is not stored in filenames. In consequence, if different locales are used
       on your system and you are doing a system wide backup, using  --alter=no-case  option  may
       lead  dar  to  detect invalid wide character, in that case it falls back to a byte by byte
       case sensitivity comparison (ASCII characters), which may not be what you would expect  at
       first sight: Most of the time, an upper case wide character (stored on several bytes) does
       not match the equivalent  lower  case  wide  character  (several  bytes  too),  when  case
       sensitivity comparison is performed byte by byte.

       -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).

       -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.
                           This option is not to be used in --sequential-read mode.

       -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 considers 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 an archive (thus using -t, -d, -l or -x commands),  the  given
                           string is executed before the slice is read or even asked, for writing
                           an archive instead (thus using -c,  -C  or  -+  commands),  the  given
                           string   is   executed   once  the  slice  has  been  completed.  Some
                           substitution macros 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
                                     executing the  string  the  requested  slice  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 last slice request.
                                     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".

                           %u        will  be replaced by the full URL of path where the slice is
                                     stored

       Several -E option can be given, given commands will then  be  called  in  the  order  they
       appear on the command line and -B included files. Note that having '-E script1 -E script2'
       is totally equivalent to '-E "script1 ;  script2"'.  In  other  words  if  script1  fails,
       script2  fill  still  be  executed and dar will only be notified of the exit status of the
       last -E option. Exit status of previous -E given commands will be ignored.  If  this  does
       not  match your need, consider using a single -aduc option (see below). More generally you
       can use any shell construction in the argument to -E, including parenthesis,  ||  and  &&.
       Such  files  given  to  -E  option are known as DUC files (Dar User Command). See also the
       environment variable DAR_DUC_PATH in the ENVIRONMENT section at the end of this document.

       -aduc, --alter=duc  As described above for -E option, several -E/-F/-~  options  (aka  DUC
                           commands) are combined using the shell ";" operator, which ignores the
                           exit status of the first commands and only reports  to  dar  the  exit
                           status  of  the  last  command,  leading  all commands to always being
                           executed. --aduc option combines the different DUC commands using  the
                           shell "&&" operator, which execute the next command if and only if the
                           previous command succeeded. In other words, dar  get  notified  of  an
                           error  in  any  given  DUC  command  but  due  to an error not all DUC
                           commands may be executed.

       --aduc modifies the way the next DUC file is sticked to the  previous  command,  in  other
       words:

              dar --aduc -E script1 -E script2 ...
                   leads libdar to call a shell with the following line "script1 && script2"

              dar -E script1 -script2 --aduc -E script3 ...
                   leads  libdar  to  call  a shell with the following line "script1 ; script2 &&
                   script3". In other words if you want to avoid the ";" use  --aduc  before  any
                   -E/-F/-~ option.

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

       -~, --aux-execute <string>
                           same as -E and -F but is  applied  between  slices  of  the  auxiliary
                           archive (-@ option).

       -K, --key [[<algo>]:]<string>

       -K, --key gnupg:[<algo>]:email[,email[...]]
                           In  the  first  syntax,  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 (symmetric encryption).
                           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  aes256  cipher is assumed (default was blowfish up to
                           2.5.x). 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 aes256 cipher with the  pass  phrase  asked  at  execution
                           time.

                           Note  that  giving the passphrase as argument to -K (or -J or '-$' 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  a 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 (aka secure
                           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 beginning.

                           since  archive  format  9  (archive  generated  by  release  2.5.0 and
                           following) at reading  time,  it  is  not  necessary  to  provide  the
                           encryption  algorithm  used, just the passphrase is required, dar will
                           figure out  which  encryption  algorithm  had  been  used  at  archive
                           creation  time. You can either ommit -K in which case dar will ask for
                           the passphrase at execution time, or you can use -K <string> in a  DCF
                           file as explained above (avoid using -K directly on command-line).

                           The  second  syntax  starts with the word "gnupg" followed by a column
                           ':' .  In  that  situation,  the  same  set  or  symmetric  encryption
                           algorithms  as  described above is available after the column, but the
                           passphrase is not given by the user but randomly chosen by libdar  and
                           encrypted  using  the  public  key  of the target users which email is
                           given in a comma separated list. This  random  key  (see  also  --key-
                           length  below),  once  encrypted is placed at the beginning and at the
                           end of the generated archive. At reading time  only  the  listed  user
                           will  be  able to read that archive thanks to their respective private
                           key. This feature implies that each user (the archive creator as  well
                           as  the  target  users)  have  their  GnuPG  keyring  set properly. In
                           particular, the archive creator must have validated the public keys of
                           the  target  users,  and  the  target users must own the corresponding
                           private   key   in    their    keyring.    Example:    using    "--key
                           gnupg::bob@nowhere.org,joe@somewhere.com"   will  generate  an  aes256
                           encrypted archive which passprhase randomly chosen by libdar  will  be
                           encrypted    with    the    public   keys   of   bob@nowhere.org   and
                           joe@somewhere.com. To use blowfish in place of ars256  one  could  use
                           "--key gnupg:bf:bob@nowhere.org,joe@somewhere.com". Note that no check
                           is done about the trust you have set in GPG keyring that a  particular
                           public  key is owned by the phyical person you expect. See also --sign
                           option below.

                           Note that if you have set a passphrase on your private key,  dar  will
                           ask  it  dynamically, which requires dar to be run from a terminal. No
                           other way has been provided to transmit a private key's passphrase  to
                           libdar.  In  consequence  if you want to use dar/libdar in scripts and
                           make use of public key algorithm you should avoid setting a passphrase
                           to  the  private  key  you  want  to  use.  See  also GNUPGHOME in the
                           ENVIRONMENT section at the end of this document.

                           Obvious but important!  To read a gnupg encrypted  archive,  you  need
                           your  private  key  (not  only the passphrase to activate it, if set).
                           Thus if you plan to make backup of your system and encrypt the  backup
                           using  gnupg, you should have a copy of this private key available out
                           of the archive (usb key, floppy, CD/DVD, ...) in order to be  able  to
                           restore your backup!

       -J, --ref-key [[<algo>]:]<string>
                           same  meaning/use  as  -K  option's first syntax, but the given key is
                           used to decrypt the archive  of  reference  (given  with  -A  option).
                           --key-ref  is  a  synonym.  Note that for archives generated using dar
                           release 2.5.0 and above this option is no more necessary,  unless  you
                           want  to  give  the passphrase on command-line (not recommended) or in
                           DCF file (which file would be set with restricted  access  permissions
                           and/or ACL).

       -$, --aux-key [[<algo>]:]<string>
                           same  as  -J but for the auxiliary archive of reference (given with -@
                           option). Here too, this option is no more necessary to  read  archives
                           generated by dar release 2.5.0 and above.

       -#, --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 the
                           syntax used for -s option is also available here (k, M, G, etc.). 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, using
                           the -* option if the archive is the archive of reference (given to  -A
                           option)  using  -%  options if the archive is the auxiliary archive of
                           reference (given to -@ option) or using this -# option if  it  is  the
                           subject  of  the operation (listing, comparing, testing that archive).
                           If the value is not the default and the given value is not correct  in
                           regard  to  the value given at archive creation time, the archive will
                           not be possible to decrypt, it is thus safer to keep the default value
                           (and not using at all the -#, -*, -% options).

       -*, --ref-crypto-block <size>
                           same  as  --crypto-block  but  to  read  the  archive of reference (-A
                           option). --crypto-block-ref is a synonym.

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

       -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.

       -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 caching 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 can specify either -aa or -ac option.

       -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.   Without
                           escape  sequences, dar cannot sequential read an archive, which is the
                           only way beside using an isolated catalogue 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)  and  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.

       -9, --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  slices  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.

       --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.

       -al, --alter=lax    When reading an archive, 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).

       -G, --multi-thread  When  libdar  is  compiled  against  libthreadar,  it  can make use of
                           several threads. The number of thread is not settable but  depends  on
                           the number of features activated (compression, encryption, tape marks,
                           sparse file, etc.) that require CPU intensive  operations.  The  load-
                           balancing  type  per  thread used is called "pipeline". As performance
                           gain is little (not all algorithms are adapted to parallel  computing)
                           this  feature  is  flagged  as experimental: it has not been tested as
                           intensively as other new features and it is not encouraged for use. If
                           you  want  better  performance,  use  several  dar  processes each for
                           different directory trees. You'll get several archives instead of  one
                           which isolated catalogues can be merged together (no need to merge the
                           backups, just the isolated catalogues) and used as base for  the  next
                           differential  backup.  Note: if you want to silent the initial warning
                           about the fact this feature is experimental use -Q  option  before  -G
                           option.

       -j, --network-retry-delay <seconds>
                           When  a  temporary  network error occurs (lack of connectivity, server
                           unavailable, and so on), dar does not give up, it waits some time then
                           retries  the  failed operation. This option is available to change the
                           default retry time which is 3 seconds. If set to zero, libdar will not
                           wait  but  rather  ask  the  user whether to retry or abort in case of
                           network error.

       -afile-auth, --alter=file-authentication
                           With this option, When reading or  writing  an  archive  to  a  remote
                           repository  when  no  password  is  provided, instead of interactively
                           asking for a password dar will  first  check  the  ~/.netrc  file  for
                           credentials  when  relying  on FTP protocol and also for SFTP protocol
                           (libcurl allows that, which is unusual  but  somehow  useful).  If  no
                           password could be found in ~/.netrc, in second time and for SFTP only,
                           dar will try to connect using public key  authentication.  Public  key
                           authentication  is tried without this option, but it is useful here to
                           avoid having password requested interactively.

       -ab, --alter=blind-to-signatures
                           do not check whether an encrypted archive with  public  key  that  has
                           also been signed have correct signatures.

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

       -z[[algo:]level], --compression[=[algo][:][level]]
                           add  compression  within slices using gzip, bzip2, lzo or xz 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. Be
                           careful when using xz algorithm better  specify  a  compression  ratio
                           less  than  or  equal  to  6 to avoid important memory requirements. A
                           ratio of 1 means less compression and faster processing, while at  the
                           opposite a ratio of 9 gives the best compression but longest procesing
                           time. "Algo" is optional, it specifies the  compression  algorithm  to
                           use  and can take the following values "gzip", "bzip2", "lzo" or "xz".
                           "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, -zxz:6 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
                           --compression=xz:9 and so on.

              About lzo compression, the compression levels of dar and lzop program do not match.
              If you want to get the behavior of compression level 1  of  lzop,  use  the  lzop-1
              algorithm  in place of lzo with dar/libdar. If you want to get the behavior of lzop
              compression level 3, use the lzop-3 algorithm in place of the lzo  algorithm.  Lzop
              compression  levels  2,  4,  5  and  6  are  the same as level 3. last, there is no
              difference about compression level 7, 8 and 9 between dar and lzop. The lzop-1  and
              lzop-3  algorithms  do  not make use of any compression level (compression level is
              ignored with these algorithms).

       --gzip[=level]      Same as -z (see just above). This option  is  deprecated,  please  use
                           --compression or -z.

       -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 (assuming your operating system
                           can support arbitrarily large files).

       -S, --first-slice <number>
                           -S gives the size of the first slice which may be chosen independently
                           of  the  size  of  following  slices  (either bigger or smaller). This
                           option needs -s option and by default of -S option, 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 every '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.

       -D, --empty-dir     At backup time only,  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 SPECIFIC OPTIONS below).

       -Z, --exclude-compression <mask>
                           Filenames  covered  by this mask are not compressed. It is only useful
                           in conjunction with -z option. By default, all  files  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). This  option  used
                           while  merging  or  repairing  allow  one to change the compression of
                           files.

       -Y, --include-compression <mask>
                           Filenames covered by this mask (and not  covered  masks  given  to  -Z
                           option(s)) 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. This option used while merging or  repairing
                           allow one to change the compression 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  files whatever their size is you thus need to
                           type -m 0 on the command line. The size unit is the byte  (octet)  and
                           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), 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 non 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 (a page), 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 and repairing 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  and  repairing,  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 and reparing
                           --sparse-file-min-size can be used  as  described  above  for  archive
                           creation. In addition, you can have files stored as sparse file in the
                           archive of reference be stored as normal files in the  merged  archive
                           using  -ah  and passing to --sparse-file-min-size an value larger than
                           all file sizes, for example as of today  in  year  2018,  passing  -ah
                           --sparse-file-min-size 1E (1E for one exabyte) should be large enough.

       --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.

       -5, --exclude-by-ea[=<extended attribute name>]
                           exclude  inodes  from  backup  that have been set with the EA given in
                           argument. If not argument is given to that option the default EA  used
                           to  exclude  files from backup is "user.libdar_no_backup". To set this
                           attribute to a given file, use the  following  command:  "setfattr  -n
                           user.libdar_no_backup   <filename>",   to   remove  it:  "setfattr  -x
                           user.libdar_no_backup <filename>". Last, to check  the  presence  this
                           EA: "getfattr <filename>"

       -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)

       -/ , --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.
                           This option does not apply to archive reparing.

                           As soon as you use -/ option -n only applies only to slice overwriting
                           and  the  -r,  -k  and  -ae  options are ignored (restoration specific
                           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 on one side and file's Attributes (Extended
                           and Filesystem Specific) on the other side. An action is thus a couple
                           of action for Data and for EA+FSA. Actions for Data are represented by
                           uppercase  letters,  while  action for EA+FSA 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 and FSA. When merging two archives,  the  Attributes
                                set of the resulting file will be the ones of the 'in place' file
                                (whatever is the overwriting action taken for  its  data).  While
                                when  extracting  files to filesystem, the Attributes 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, which would  remove  the  inode  and  thus  also  any
                                Attributes it had).

                           o    means  'Overwrite',  same as 'O' (but lowercase letter) overwrite
                                the whole  EA  set  and  FSA.  When  merging  two  archives,  the
                                Attributes  set  of the resulting file will be taken from the 'to
                                be added' file. While when extracting files, the  Attributes  set
                                of the file in the filesystem will have its Attributes 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  and  FSA  instead  of  data.  When  merging  two
                                archives,  the  EA  and  FSA  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 and FSA) 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  and  FSA  instead  of  data.  When  merging two
                                archives, the EA and FSA 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 Attributes and preserve'. The resulting file in the
                                merged archive will have Attribute  entries  from  both  the  'in
                                place'  and  the  'to be added' files. If both files share a same
                                Attribute entry (same FSA or for EA the  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 and FSA set enriched by the ones of
                                the file in the archive that do not exist on filesystem, but  its
                                already existing Attributes will stay untouched.

                           n    means 'merge Attributes and overwrite'. The resulting file in the
                                merged archive will have Attribute  entries  from  both  the  'in
                                place'  and  the  'to be added' files. If both files share a same
                                Attribute entry (same FSA or for EA the  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 Attributes set enriched by
                                ones of the file in the archive with some of them  possibly  been
                                overwritten.

                           r    means  'remove',  same as 'R' but for the Attribute set (thus all
                                EA and FSA entries) of a given  file  ('r'  is  lowercase  letter
                                here). The file of the resulting archive during merging operation
                                will not own any EA nor any FSA, 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.
                                The  FSA cannot be 'removed' from a filesystem and may not always
                                have a default value, thus this action does not modify FSA at all
                                in case of archive extraction. But in case of merging the FSA are
                                removed as previously described. As for all the  previous  tests,
                                this  Attribute  operation is independent of the operation chosen
                                for file's data (uppercase letters).

                           d    means 'delete'. When a same EA or FSA entry is found both in  the
                                'in  place' and 'to be added' files, such entry will be absent in
                                the resulting archive. In other words, when merging, the  EA  set
                                and  FSA will only contain EA and FSA 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 EA  entries  (which  are  thus  present  in  both
                                archive  and  filesystem) will be removed from the set, which the
                                other FSA will stay untouched (FSA cannot  be  "removed"  from  a
                                filesystem, nor they always have a default value).

                           *    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 and FSA 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 and FSA). When
                           -/ option is not given, the action is equivalent to  '-/  Oo',  making
                           dar  proceed to file, EA and FSA 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 lead dar to remove any file from filesystem that ought to be
                                restored(!).  Note  the  action for EA/FSA is useless, the EA and
                                FSA 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 and FSA 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.

                           the situation is similar with FSA family scope and overwriting policy.
                           Only  FSA  of  a  family  present  in  the scope will be retained, the
                           overwriting policy acts first then the  FSA  scope  is  applied.  Note
                           however  that  any FSA present on filesystem and excluded from the FSA
                           scope are not touched.

                           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 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 ´arg´ or double  "arg")  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. Note that
                                ~I can be used to check the nature of the 'to be added' object.

                           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 (and 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  nor marked as only inode metadata changed,
                                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.

                           L    true only if the 'in place' entry has delta signature  associated
                                with it.

                           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. By default a file can be re-saved up
                           to 3 times (this is the 'count' field), you can  set  it  to  zero  to
                           disable  this  feature.  In  option the overall maximum amount of byte
                           allowed to be wasted due to retry 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) a limit  of  1  wasted
                           byte is allowed which is the mininum. Specifying zero for max-byte set
                           no limit on the amount of wasted bytes (same as if no  'max-byte'  was
                           specified),  each  changing  file is then 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. In some situation it is not possible
                           to  replace  the  already  saved data for a file (writing archive to a
                           pipe for example), in that situation only, a second copy of  the  file
                           is  added  just after the first previous try which leads that previous
                           try to 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.

                           Note:  since release 2.5.0, in normal condition no byte is wasted when
                           a file changed at the time it was read for backup, except when doing a
                           backup  to  pipe (using '-c -' option), except if the beginning of the
                           modified file is located in a  previous  slice  and  except  if  slice
                           hashing or strong encryption is used.

       -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 internally 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. Note that
                           decremental backup is not compatible with delta binary.

       -asecu, --alter=secu
                           This option  disable  the  ctime  check  done  by  default  during  an
                           differential  backup:  If the ctime of an plain file has changed since
                           the archive  of  reference  was  done  while  all  other  values  stay
                           unchanged (inode type, ownership, permission, last modification date),
                           dar issues a "SECURITY WARNING", as  this  may  be  the  sign  of  the
                           presence  of  a  rootkit.  You should use the -asecu option to disable
                           this type of warning globally, if you are doing a differential  backup
                           of  a  just restored data (a differential backup with the archive used
                           for restoration taken as reference). Effectively in that situation, as
                           it  is  not  possible to restore ctime, the 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 (new EA, removed EA, modified EA), 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>   With  this  option set, when creating, isolating, merging or repairing
                           an archive, beside each generated slices an on-fly hash  file  of  the
                           slice  is  created  using the specified algorithm. Available algorithm
                           are "md5", "sha1" and "sha512". By default no hash file is  generated.
                           The  hash  file generated is named based on the name of the slice with
                           the .md5, .sha1 or .sha512 extension added to it  at  the  end.  These
                           hash  files  can  be  processes by md5sum, sha1sum and sha512sum 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 a possibly 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 -").

       -7, --sign email[,email[,...email]]
                           When creating, isolating, merging or repairing an archive with  public
                           key  encryption  (read  -K option) it is also possible to sign it with
                           one or more of your private key(s). At  the  difference  of  the  hash
                           feature  above,  only  the  randomly  generated key used to cipher the
                           archive, key that is dropped at the beginning and at the  end  of  the
                           archive,  is  signed.  If  the archive is modified at some place, that
                           part will not be possible to decipher, but signature verification will
                           stay  quick  and  valid, unless the part that has been tempered is the
                           key inside the archive in which case signature  check  will  report  a
                           failure  and  archive will not be readable at all. If the signature is
                           valid and the archive could be  extracted  without  error,  the  whole
                           archive  could  be  assumed  to be signed by the gnupg key owners, but
                           read below the security note. See also GNUPGHOME  in  the  ENVIRONMENT
                           section at the end of this document.

                           A  summay  information  about  the  signature information is displayed
                           while listing an archive in summary mode "dar -l  <archive>  -q".  For
                           any  operation  involving a signed archive, a short message only shows
                           if the archive is signed an one or more  signature  check  failed,  no
                           message  is  displayed  in  case  of  successful signature check. This
                           warning may be disabled using the --alter=blind-to-signatures command.

       -<, --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 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

                           %t        will be replaced by a letter corresponding to  the  type  of
                                     inode:  'f'  for  plain  file,  'l'  for  symlink,  'd'  for
                                     directory, 'c' for char devices, 'b' for block devices,  's'
                                     for sockets, 'p' for pipes, 'o' for doors.

                           %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 dump a database in a directory just before it is about to be backed up,
       and clean it up once the backup has 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 files 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.

       -8, --delta sig     This  option  can  be  used for archive backup, isolation and merging.
                           Important: read also the best practice paragraph below

                           Called during  a  backup  operation  it  leads  dar  to  create  delta
                           signature  for  each  file:  If  the  file  is  new  or has changed, a
                           signature is  computed  and  stored  beside  the  file's  data,  which
                           increases the archive size. If the file is not new and has not changed
                           (differential backup context) if an delta signature is  found  in  the
                           archive of reference (or isolated catalogue), this signature is copied
                           to the resulting archive, but not the file's data.  If  the  reference
                           archive  does  not  hold  delta  signature,  a  new delta signature is
                           computed based on the current data found on filesystem for  that  file
                           and  then  stored  in the resulting archive.  But in any case, without
                           --delta sig the resulting archive will hold no delta  signature.  Note
                           that  delta  signature  transfer  is  not possible when the archive of
                           reference is read in sequential mode, thus delta signature is disabled
                           when the archive of reference is read in sequential mode.

                           For  isolation  and  merging  operations,  the  behavior  is  sligthly
                           different:  --delta  sig  option  let  dar  transfer  existing   delta
                           signatures  from  the  original archive to the isolated/merged one but
                           does not lead dar to compute delta signatures for files  that  do  not
                           have one, unless one of the --include-delta-sig or --exclude-delta-sig
                           option  is  specified;  in  that  case  the   delta   signatures   are
                           transfered/dropped  and if not present calculated accordingly to these
                           mask options. However note that it is not possible to calculate  delta
                           signature  for  unsaved files in the archive of reference (because the
                           archive of reference does not hold their data) as well  as  for  fully
                           saved  files  when  merging is performed keeping files compressed (see
                           -ak option). Another restriction while merging concernes sparse files,
                           it  is  not  possible to calculate binary signature for file stored as
                           sparse files, but if sparse file detection mechanism is  activated  at
                           merging  time,  delta signature can be calculated for sparse files too
                           even if it is missing in the reference archive. In short: if you  want
                           recalculation  of  delta  signature  while  merging,  do not keep file
                           compressed (do not use -ak option) and if you  want  to  avoid  having
                           sparse files excluded from the delta signature recalcutation, activate
                           sparse file detection (use -ah option). Delta  signature  transfer  is
                           not  possible  for  on-fly  isolation,  you  need to do normal atchive
                           isolation to obtain an isolated catalogue with delta signatures.

       -8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]]
                           this variant of '--delta sig' option let you  specify  the  block  len
                           used to build delta signatures. Larger values reduce CPU load required
                           to build  delta  signature,  but  also  lead  to  less  accuracy  when
                           computing  delta  binary, which means larger delta patch and more data
                           saved when  a  file  has  changed.  The  block  length  is  calculated
                           following          the          formula:          block_len          =
                           function(filesize)*multiplier/divisor  If  this  calculated  value  is
                           lower than "min", it is set to min. If the calculated value is greater
                           than "max" it is set to max unless max is set to zero  in  which  case
                           the  value  is  kept  as  is.  Of course "divisor" cannot be null. The
                           avalaible functions are:

                           fixed
                                always returns 1, in other terms, the block size is indepent from
                                the file size to build delta signature for

                           linear
                                returns  the  filesize. here, you will most of the time use 1 for
                                multiplier and increase divisor to at least 10 for it makes sense

                           log2 returns the upper rounded power of 2 to the  file  size  (base  2
                                logarithm).

                           square2
                                returns  the  approximated  value  of the square root of the file
                                size. Note that for better performance and  as  accurary  is  not
                                important    here,    this    function    is    implemented    as
                                exp2(log2(filesize)/2) where exp2 and  log2  are  based  ont  the
                                integer left and right bit shift operations.

                           square3
                                returns  the  approximated  value  of  the cube root of filesize,
                                implemented as exp2(log(filesize)/3)

                           All numerical fields can receive multiplier suffix  (k,  M,  ...)  for
                           more  details  about these suffixes, see -s option description. If not
                           specified "max" defaults to zero (no maximum value  defined).  If  not
                           specified  "min"  defaults  to  RS_DEFAULT_BLOCK_LEN  (see  below  for
                           details on this symbol). If not specified  "divisor"  defaults  to  1.
                           Using  "--delta  sig" without additional fields is equivalent to using
                           --delta sig:fixed:RS_DEFAULT_BLOCK_LEN where "RS_DEFAULT_BLOCK_LEN" is
                           taken  from  librsync and is today equal to 2048 bytes (which may well
                           change in the future by the way if librsync maintainers decide  to  do
                           so).

       -{, --include-delta-sig <mask>
                           By default when --delta sig is provided, delta signatures are computed
                           for all files enrolled in the backup operation (see also  --delta-sig-
                           min-size   option).   This   option   and   --exclude-delta-sig  allow
                           restricting the files for which delta signature have to be  calculated
                           in that situation. The mask applies to the whole path, the same way as
                           -P/-g options do.

                           For merging or isolation operations, when --delta sig is used no delta
                           signature  is computed only existing ones are transfered as is without
                           restriction. To change that behavior and thus either drop or add delta
                           signature  to files that did not have one in the archive of reference,
                           specify an combination of --include-delta-sig  or  --exclude-delta-sig
                           with  --delta  sig.  This option as well as --exclude-delta-sig can be
                           used several times on command-line  but  are  useless/ignored  without
                           --delta sig. See also -am, -ag and -ar options.

       -}, --exclude-delta-sig <mask>
                           Files  matching  the given mask will never have their delta signatures
                           calculated, may --delta sig option  be  specified  or  not.  See  also
                           --include-delta-sig option above and --delta-sig-min-size below.

       -6, --delta-sig-min-size <number>
                           For   archive  merging,  isolation  and  creation,  when  dar  has  to
                           (re-)calculate delta signatures, this option modifies the minimum file
                           size  (in  bytes)  below  which dar never calculates delta signatures.
                           This option acts independently from --include-delta-sig and --exclude-
                           delta-sig   ,   however   it   cannot   re-activate   delta  signature
                           recalculation  by  itself  while  merging/isolating  an  archive,   it
                           requires  either  --exclude-delta-sig or --include-delta-sig option to
                           be active in that situation. For archive backup instead, it  does  not
                           require  --exclude-delta-sig  nor --include-delta-sig to act, but only
                           need --delta sig option to be set. By default, this minimum size is 10
                           kio.  The same option suffixes (k for kilo, M for mega, G for giga, T,
                           ...) as the ones available with --slice option can be used  here  too.
                           Using  zero  as  argument gives the same result as not specifying this
                           option at all (default size).

       -8, --delta no-patch
                           In the context of differential backup, this option leads dar to  never
                           consider  files for delta binary even if delta signatures are present.
                           By default delta binary (rsync-like) operation  is  performed  when  a
                           file  has  changed  since the archive of reference was made *and* if a
                           delta signature could be found in the archive of  reference  for  that
                           file  (or  in  the  isolated  catalogue  used  as  reference  for  the
                           incremental/differential backup). If no delta signature could be found
                           or  if  --delta  no-patch  is used, the normal behavoir is done, which
                           consist of saving that whole file in the archive.  Note  that  if  the
                           archive  of reference is read in sequential mode, the --delta no patch
                           is implicitely used as reading in sequential mode an archive does  not
                           let  skipping backward to fetch the delta signature necessary to setup
                           a delta patch.

       Binary delta options usage and best practices:
              First it must  be  understood  that  binary  delta  has  advantages  (less  storage
              requirement)  and  drawbacks:  data corruption has a wider impact on the ability to
              restore a given file, restoration of incrementaly backed up file may ask much  more
              than  one archive to be used. To limit the impact of the first drawback, dar binary
              delta is done per file, not globally on the total amount of  saved  data.  You  are
              also  strongly  encoraged  to protect your backups with parity data using par2 (see
              dar_par.dcf file in the examples section of the documentation).  Adding  par2  data
              will  increase  storage  requirement  by  a  little, but usually much less than the
              amount gained using binary delta. Last drawback, binary delta  relies  on  checksum
              (contained  in  the  delta  signature) and not on the real data to build the binary
              delta. There is chances that two different files provide the same checksum, even if
              the  chances  are  very low, probability is not null. The consequence is that using
              binary delta the risk exists that the restored data do not match the original  data
              and  this  will  not  be noticed by the librsync library on which libdar relies for
              that feature. Dar adds a second level of checksum, to detect data corruption inside
              the  archive  and  to check that the file the delta patch is about to be applied is
              the expected base file, this reduces the risk of "collision" but does not remove it
              completely.  After  these  warnings,  let's now see the best practices about binary
              delta:

              Once a full backup has been done using --delta sig, any  differential  backup  made
              based  on  this  archive  will  use  binary  diff for file having a delta signature
              present in the full backup. If  you  always  make  differential  (not  incremental)
              backups based on such full backup you have nothing more specific to do in regard to
              binary delta, dar will handle it transparently. In particular you do  not  need  to
              invoke  --delta sig at subsequent backup, this saves space in differential archives
              as well as CPU cycles.

              However, When doing incremental (not differential) backups this time, if  you  want
              to  have  dar  using  binary  delta  at  each  subsequent incremental backup, delta
              signatures must be present in the successive incremental backups. This is  done  by
              using --delta sig option for each new incremental backup created.

              If  you  were  used  to  use  isolated  catalogues before release 2.6.0 you can add
              --delta sig option while isolating a catalogue from  an  archive  containing  delta
              signatures. Such isolated catalogue will be much larger than what it can be without
              this option but it can be used as  reference  for  a  new  differential/incremental
              backup  letting  dar  relying on binary delta. Isolated catalogue generated without
              --delta sig do not  contain  delta  signature  and  cannot  lead  to  binary  delta
              operation when used as reference for an incremental or decremental backup.

              Another  way  of  doing differential backup is to make a normal full backup without
              --delta sig option, and only add delta signatures at archive isolation  time  using
              --delta  sig  --include-delta-sig  "*" options. Binary delta signature will then be
              calculated based on the saved files. Then, using the resulting  isolated  catalogue
              as  reference  dar  will  be  able  to proceed to binary delta for the differential
              backup. If this works pretty well for differential backup (or the first incremental
              backup)  which  is  based  on  a  full  backup, for incremental backup this is less
              adapted as a file that has not changed since the archive of reference was made does
              not  hold  any  data and calculating the delta signature is not possible. The first
              method explained two paragraphs above is better as the incremental  backup  fetches
              the  already  calculated  delta  signature  from  the  reference  to keep it in the
              resulting incremental backup, so even without data, binary delta is still possible.

              Isolated catalogue using the --delta sig option, can still be used as backup of the
              internal  catalogue  they  have been isolated from. However, as they hold their own
              delta signatures, such isolated catalogue can only have access to its own ones, not
              to  those  of  the  archive of reference. In particular when testing an archive (-t
              option), using -A option to rescue the archive internal catalogue using an isolated
              catalogue  containing delta signatures, dar will not be able to check that there is
              no corruption in the delta signatures fields of the archive under  test.  For  that
              type of testing either use the internal catalogue of the archive or rescue it using
              an isolated catalogue built without --delta sig option.

       -az, --alter=zeroing-negative-dates
                           dar/libdar saves dates as a number of seconds since the  beginning  of
                           year  1970,  the  well known "Unix time" (plus a positive fraction for
                           sub-second time-stamping). Some systems may return a  negative  number
                           as  the Unix time of a given file (files having dates before 1970), in
                           that situation by default and since release 2.5.12 dar pauses and asks
                           the  user  whether  to  assume  the  date  as being zero. But with -az
                           option, dar/libdar automatically assumes such  negative  dates  to  be
                           zero and just issue a warning about the problem met.

       -\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]]
                           When  dar  reach  an  inode  which  is  part  of  this provided column
                           separated list, if this inode is not a  symlink  this  option  has  no
                           effect,  but if it is a symlinks dar saves the file the symlink points
                           to and not the symlink itself as dar does by default.  In  particular,
                           if the pointed to inode is a directory dar recurses in that directory.
                           You can also pass this list as argument to the  DAR_IGNORED_AS_SYMLINK
                           environment   instead   of  using  --ignored-as-symlink  (which  takes
                           precedence over the environment variable).

       -'\'',  --modified-data-detection=any-inode-change,   --modified-data-detection=mtime-and-
       size
                           Before  release 2.6.0, during a differential/incremental backup if any
                           part of a file's inode metadata changed (ownership,  permission,  ...)
                           even  if  the  mtime  (last modification time) and file size stood the
                           same, dar had no choice than resaving the whole  file  for  backup  to
                           record  the  metadata changes. This lead to a waste of backup time and
                           space if in fact and for example only the ownership had been modified.
                           You   can   still  keep  this  historical  behavior  by  invoking  the
                           --modified-data-detection=any-inode-change  option.    Since   release
                           2.6.0  a  new  entry status ("inode-only") has been added. Dar can now
                           resave only metadata when the inode change does not concern the  data.
                           To  know  whether  the  data  has  changed  or  not,  by  default  (no
                           --modified-data-detection option given) dar  looks  at  mtime  and  at
                           file's  size only. Specifying --modified-data-detection=mtime-and-size
                           (which is the default behavior) can be used to revert  the  action  of
                           --modified-data-detection=any-inode-change  for  example  when playing
                           with included files (DCF files): the latest met takes precedence.

       -T, --kdf-param <integer>[:<hash algo>]
                           At the difference of the listing context (see below), in  the  context
                           of  archive  creation, merging and isolation, -T option let you define
                           the  interation  count  used  to  derive  the  archive  key  from  the
                           passphrase  you  provided  (archive  encryption  context) and the hash
                           algorithm used for that. The default value is 200,000  iterations  and
                           sha1  algorithm.  -T  has  another  older  meaning  when doing archive
                           listing, but due to the lack of free character to  create  a  new  CLI
                           option,  there  was  no other choice than recycling an existing option
                           not used in the context  of  archive  creation/merging/isolation.  The
                           consequence  is  that  the  -T  option  must appear after the -+/-c/-C
                           options for the operational context to be known at  the  time  the  -T
                           option is met and its --kdf-param meaning to be taken into account. As
                           --kdf-param is an alias to -T, this long form of this option must also
                           be  found  after  the  use of either -c, -C or -+ option. The suffixes
                           described for -s option are also available here (k, M, G, T,  P,  ...)
                           however  pay  attention  to  the  -aSI/-abinary  mode which default to
                           binary, in which case "-T 1k" is equivalent to "-T 1024".

       RESTORATION SPECIFIC 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 files 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!

       -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, in --sequential-read, once a file
                           has  been  restored,  if  it  is  found to be dirty it will be removed
                           unless dirty-behavior is set to "no-warn".

       -/, --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.

       -A, --ref [[<URL>]<path>]/<basename>
                           The --ref option can be used with an isolated catalogue to  rescue  an
                           archive  that  has  a  corruption  in  the catalogue part, see GENERAL
                           OPTIONS above for more details.

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

       -ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime
                           With this option set, when comparing a symlink, no message shows  when
                           symlink  in  archive and symlink on filesystem do only differ 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 in GENERAL OPTIONS to backup of internal catalogue of the archive (assuming  you
       have a previously isolated catalogue available).

       Doing  a difference in sequential read mode is possible 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 | slicing>
                           By  default, listing provides a tar-like output (the 'normal' output).
                           You can however get a tree-like output, an XML structured output or an
                           output  focusing  on  slice(s)  where  each file's data, EA and FSA is
                           located in. 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)

                           the  -Tslicing  option  can  also  be  used  with  isolated  catalogue
                           generated with dar 2.5.0 or above, as isolated catalogues now  contain
                           a  copy of the slicing layout of the archive of reference. However, if
                           the archive of reference has been resliced (using dar_xform) after the
                           isolated  catalogue  has been built, the slicing information would not
                           be correct. For that corner case, you can use the -s  and  -S  options
                           with  -Tslicing to specify what are the new slice sizes of the archive
                           of reference. Last, -Tslicing and --sequential-read  options  are  not
                           compatible except for isolated catalogues.

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

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

       -ay, --alter=byte, --alter=bytes
                           by  default  files  size is displayed to occupy the shortest number of
                           characters by using the largest unit possible (KiB, MiB, GiB,  and  so
                           on).  With  this  option  instead,  the size is displayed with maximum
                           precision using the exact number of bytes used for each file.

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

       -aheader            displays the header (when --sequential-read is used) or the trailer of
                           the  archive  and then stops. This archive header/trailer is always in
                           clear text even when the archive is ciphered. This option is  here  to
                           let you access to these fields without providing the encryption key.

       From the general options it seems only -vm and -b stay useful here. Note that -vm 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] or
                           [Inode] or [Delta]. [     ] 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 completely, and thus this archive is able
                           to  restore  the  file without other help. [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. [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.  [Inode]  means  only
                           permission  ownership  and  ctime  data  changed  since the archive of
                           reference was done is recorded  in  the  archive,  the  data  did  not
                           changed  according  to  the  --comparison-field  set  or not set. Last
                           [Delta] means the file's data is saved as a  binary  delta  (or  delta
                           patch),  which is much shorter than the full data as what is done with
                           [Saved]. It also means that you can only restore the file if it exists
                           on  filesystem  in  the state it had when the archive of reference was
                           done, for the patch to be possible to apply on it. This  is  the  case
                           for  example  if  you  just  restored  this  file  from the archive of
                           reference.

                 [D]       possible values are [-], [ ] or [D]. [D] means  that  delta  signature
                           associate with this file is present in the archive. [ ] means that the
                           file has no associated delta signature and thus binary diff  will  not
                           be  possible  for it. [-] is used for non plain files inodes for which
                           delta signature is not applicable.

                 [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.

                 [FSA]     Each character represent a FSA Family:

                           "L"  is the first character (L/l/-) representing ext2/3/4 FSA family

                           "H"  is the second character (H/h/-) representing HFS+ FSA family

                           "-"  the  third  character  is  reserved  for future FSA family and is
                                always a dash for now.

                           Uppercase means the FSA set is  saved,  lowercase  means  the  FSA  is
                           present  in  the  archive  of reference and has not changed since that
                           time. Last a dash (-) means no FSA of that family has been  saved  for
                           that file.

                 [compr]   possible values are [....%] or [-----] or [     ] or [worse]. Shows if
                           the file has  been  compressed  ([...%])  and  the  compression  ratio
                           reached  "(uncompressed-compressed)/uncompressed",  for example [ 33%]
                           means that the compressed data uses only 66% of the space required  to
                           store uncompressed data (33% of space saved thanks to compression), or
                           if the file is stored without compression ([    ] see -m,  -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  1%  compression  ratio  brings  quite  no  data
                           reduction,  while  obviously  98%  is  a  very  performant compression
                           (compressed  file  takes  only  2%  of  the  size  required   by   the
                           uncompressed date).

                 [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.

                 Extended Attributes
                           When using -alist-ea option, for hard linked inode,  the  filename  is
                           followed by an integer between braces: Entries with the same number do
                           point the the same inode.

                 Slice(s)  In -Tslice mode, each file is given the range of slices it is  located
                           in.  If  slice  size  is  chosen  particularily small, some slices may
                           contain no file, EA, FSA data but only  tape  marks  or  the  internal
                           catalogue, leading the aggregation of reported slices not to cover all
                           available slices of the archive.

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

       -5                  must be replaced by -5 ""

       -p                  must be replaced by -p 1

       -v                  must be replaced by -v all

       -k                  must be replaced by -k ignore

       -5                  must be replaced by -5 user.libdar_no_backup

       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 or DCF included file

       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  from
                 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 bug).

       8         the version of dar used is based on 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. The exception caching code to take care of
                 new  exceptions has probably been forgotten to be update ... 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. This is
                 known as a "dirty" file in the archive.

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 below, 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  options  listed  after  this  condition get used if previously on
                           command line or file the -x command has been used

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

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

       test:               if -t command has been used

       diff:               if -d command has been used

       isolate:            if -C command has been used

       merge:              if -+ command has been used

       repair:             if -y command 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, but they
       will be activated in starting the next -B file. 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.

       DAR_SFTP_KNOWNHOSTS_FILE
                 if set, dar will not use the $HOME/.ssh/known_hosts file to  check  sftp  remote
                 server  authenticity  but the file given as value for this environment variable.
                 Note that setting this variable to  an  empty  string  completely  disable  host
                 validation,  which  is  not recommended. Dar, the command line interface program
                 for dar archive relies on libdar for archive format management which  relies  on
                 libcurl  for  network  transfer  which  in  turn  relies on libssh2 for all that
                 concerns sftp protocol. In the known_hosts file, libssh2 does not support recent
                 lines like those with "ecdsa-sha2-nistp256" in second argument but only supports
                 "ssh-rsa" lines. Check libssh2 documentations and litterature for  more  details
                 about  that  limitation. To workaround this limitation you need to disable known
                 hosts validation or set up a restricted known hosts file  without  any  "ecdsa*"
                 entry and have DAR_SFTP_KNOWNHOSTS_FILE pointing to it.

       DAR_SFTP_PUBLIC_KEYFILE
                 by  default dar will fetch the public key file in $HOME/.ssh/id_rsa.pub file. If
                 you use the former id_dsa.pub or more recent key types  you  need  to  set  this
                 environment variable to point to the appropriated filename

       DAR_SFTP_PRIVATE_KEYFILE
                 by  default dar will fetch the public key file in $HOME/.ssh/id_rsa file. If you
                 use the former id_dsa.pub or  more  recent  key  types  you  need  to  set  this
                 environment variable to point to the appropriated filename

       DAR_IGNORED_AS_SYMLINK
                 receive  a  column  separated list of absolute paths, which if they are symlinks
                 are not saved as symlink but as the inode they point to. For  more  details  see
                 the --ignored-as-symlink option above.

       GNUPGHOME for  asymetric  encryption  and  signature,  the keyring used is $HOME/.gnupg by
                 default. You can change this default  by  setting  GNUPGHOME  to  the  directory
                 containing  the keyring. For example, if you are running dar as root and want to
                 use your unprivileged account keyring use the following:

                 export GNUPGHOME=~myaccount/.gnupg

                 dar -K gnupg:...@...,...@... --sign:...@... etc.

CAPABILITIES

       dar fully supports the cap_chown capability, but by design, dar only uses this  capability
       to  restore  files  at  their original ownership. Dar will thus not use this capability to
       access files and directories the caller would normally not have access to. In other words,
       it  should be ok to set the cap_chown capability to the dar executable (setcap cap_chown+p
       dar). Calling dar from a process having the cap_chown in the inheritable  set  would  lead
       the  system  to  grant  this  capability to the dar process while other users would not be
       granted this capability and would not be able to modify ownership of files at  restoration
       time.  This  can  be  used for the system account that has the role of restoring data upon
       user requests, without giving root privilege to this restoration process.

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

SEE ALSO

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

KNOWN LIMITATIONS

       dar  saves  and  restores  atime,  mtime,  birthtime  but cannot restore ctime (last inode
       change), there does not seems to be a standard call to do that under UNIX. An up  to  date
       list of known limitation is at http://dar.linux.free.fr/doc/Limitations.html

KNOWN BUGS

       http://sourceforge.net/p/dar/bugs/

AUTHOR

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