Provided by: dar_2.7.7-1_amd64 bug


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


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

       dar -h

       dar -V


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

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

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


       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.


       The rest of this document is organized that way:

                   The eight actions you can performs with dar

              GENERAL OPTIONS
                   A set of options common to all actions

                   A set of options that are specific  to  the  operation  of  backup,  catalogue
                   isolation and archive merging

                   A set of options that are specific to the restoration operation

                   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

                   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

                   details the signal and their action on a running dar process

                   List configuration files that dar checks for

                   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

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



       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

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

       -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  detect  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  certain
                           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 detailed 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:


                 is either ftp or sftp

                 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. Example: login is
                 host is  gives:  sftp://me\\
                 You  may  also need to escape the same way any other special characters like for
                 example colon (:) slash (/) if they are part of the login string.

                 if login is provided, the associated password may be given after a colon (:) 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.

                 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.

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

                 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


       -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

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

       -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

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

       -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

                                  -  a  dash  ("-")  in  direct  access  mode (default mode, when
                                  --sequential-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

                           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

                           <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

                           Here are some examples of date:
                                  1 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
                                  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 overridden if the TZ environment 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  (-+

       -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

              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

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

                                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

       -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

       -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

                           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

                           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

       -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

                           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

              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>]:keyid/email[,keyid/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 colon ':' 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

                           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 omit -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 colon ':'
                           . In that situation, the same set or symmetric  encryption  algorithms
                           as described above is available after the colon, 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 okkeyid (since
                           2.7.0) 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
                 ,"   will  generate  an  aes256
                           encrypted archive which passprhase randomly chosen by libdar  will  be
                           encrypted    with    the    public   keys   of   and
                  To use blowfish in place of ars256  one  could  use
                           "--key,". 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

       -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 flaky 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. Before release 2.7.0, when reading  an  archive,  you  were  also
                           requested  to  provide  this same argument else dar was unable finding
                           the slice. Since 2.7.0 dar auto-detects the mi-digits  value  to  use,
                           unless  there  is a mix of archive of the same basename with different
                           min-digits. In such conflicting context,  you  must  bypass  the  min-
                           digits  auto-detection mechanism and specify which min-digits value to
                           retain in order to read the archive, eventually followed  by  a  comma
                           and  the  number  of  digits  to  use to read the archive of reference
                           (given to -A option), eventually followed by a comma and the number of
                           digits  to  use  for  the  auxiliary archive of reference (given to -@

       --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 { <num> | <crypto>,<compression> }
                           When  libdar  is  compiled  against  libthreadar,  it  can make use of
                           several threads. If the argument is two numbers separated by  a  comma
                           the first defines the number of worker threads to cipher/decipher, the
                           second the number of threads to compress/decompress. If  the  argument
                           is  a single number (-G <n>) it is equivalent to giving this number as
                           the number of compression threads  and  giving  2  for  the  ciphering
                           threads  (-G  2,<n>).  The  use of multi-threading at archive creation
                           time leads to rely on per block compression  rather  than  the  legacy
                           streaming  compression  and if the block-size is not specified (see -z
                           option for details) it defaults to  240  KiB.  Not  providing  any  -G
                           option,  is  equivalent  to  providing  -G  2,1  when  libthreadar  is
                           available else -G 1,1. Note that if an archive has been  created  with
                           streaming compression, the decompression cannot use multi-threads, the
                           deciphering can always use multiple threads.

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


       -z, --compression={ [algo] | level | algo:level | algo:level:block-size }
            add compression within slices. If -z is not specified, no compression  is  performed,
            but if -z is specified without algorithm gzip will be assumed.

                 the  following  values  are  available  "gzip",  "bzip2", "lzo", "xz", "zstd" or

                 The compression level (an integer from 1 to 9 except for zstd which ranges  from
                 1  to  22)  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
                 processing time.

                 if  set  to zero (which is also the default value), you will get the legacy (and
                 performant) "streaming compression" mode that  was  the  only  available  up  to
                 release  2.7.0.  Since  then,  the "block compression" mode gives the ability to
                 leverage multi-threading (see -G option) by compressing  per  block  and  giving
                 different  blocks  to different threads. The larger the block is, the better the
                 compression ratio will be (it tends to be as good as the one  of  the  streaming
                 compression  mode,  when  block  size increases), but files smaller than a block
                 size can only be processed by a  single  thread.  The  memory  requirement  also
                 increases  by the product of the block size times the number of threads. Last, a
                 too small block-size will cost more CPU cycles (the  multi-threading  management
                 overhead will become important compared to the effective compression processing)
                 and independently, short blocks gives poor compression rates. It is thus advised
                 to  use  values  at  least  greater than 50 ~ 100 KiB (you can use the k,M,G,...
                 suffixes described for the -s option). If the block-size is  not  specified  and
                 given  -G option leads to a number of compression threads greater or equal to 2,
                 a block-size of 240 KiB is used. If you want the legacy  streaming  compression,
                 do not use -G option (or use it specifying only 1 compression thread) and do not
                 set the compression block size (or set it to zero).

            Valid usage of -z option is for example: -z, -z9, -zlzo,  -zgzip,  -zbzip2,  -zlzo:6,
            -zbzip2:2,  -zgzip:1, -zxz:6, -zlz4::10k -z::12000 -zbzip2:8:10k 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).

       -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

       -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

       -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  vice-versa, 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 repairing
                           --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, --mount-points={ I:<path to fs> | X:<path to fs> }
                           If the argument is of the I:<path to fs> form, the filesystem to which
                           this path points to is considered for the backup operation, that's  to
                           say,  other  file  filtering mechanism will be applied and some or all
                           files of that filesystem will be saved  for  backup.  While  with  the
                           X:<path  to  fs>  form,  no  file  in  that  filesystem  will  even be
                           considered for backup. both X: and I: forms must be provided  with  an
                           absolute  path.  -M  option  can be used several times on the command-
                           line. If only I:  forms  are  used,  the  filesystem  based  filtering
                           mechanism  behaves  as  a  white  list  (only  those  listed paths are
                           included). If only X: form is used,  the  filesystem  based  filtering
                           mechanism  behaves  as  a  black list (everything is considered except
                           those listed paths). Last, while a mix of I: and X:  forms  are  used,
                           filsystems that will be considered for backup will be those given with
                           an I: form and not also given with an  X:  form.  Note  that  this  is
                           filesystem   based  filtering,  not  path  based:  If  for  example  a
                           filesystem is mounted under /var directory and you specify  I:/var/log
                           all  /var filesystem will be considered for backup. If you rather want
                           to only save what is in /var/log  use  the  -P/-g/-X/-I/-[/-]  options
                           that  realise  the  file  filtering  by name and path+name. You cannot
                           exclude the filesystem which contains the path given to -R option. The
                           use  of -M option with argument erases any previous configuration done
                           with -M option without  argument  (see  below),  and  vice  versa.  By
                           default  (no -M option specified), no filtering based on filesystem is
                           performed, in other worlds all files are  considered  for  other  file
                           filtering  mechanism  (in  particular  -P/-g/-X/-I/-[/-]  options) and
                           eventually backed up.

                           example of use:
                           -MI:/var -MX:/var/spool
                           --mount-points=I:/var --mount-point=X:/var/spool

       -M, --no-mount-points
                           This is the legacy form of  the  option  described  just  above,  that
                           existed  before  release  2.7.0.  When  -M  option is provided without
                           argument, only files located on the filesystem pointed to by the  path
                           given  to  -R  option will be considered for backup. 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. The use of -M without option lead dar to ignore any
                           previous  -M  I:<path>  and  -M  X:<path> options that could have been
                           given on command-line or -B included file so far.

       -, ,  --cache-directory-tagging
                           don't save contents  of  directories  that  use  the  Cache  Directory
                           Tagging  Standard.  See
                           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 repairing.

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

                           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

                           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

                           {<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:

                           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

                           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 semicolon  ';'  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

                           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

                           I    true only if the 'in place' entry is  an  inode.  This  condition
                                does  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.  A 'detruit' entry, which record the fact that a file has
                                been removed since the archive of reference, is not an inode  for
                                example,  and  the  only  type of entry that is not an inode is a
                                'detruit'. Thus you can define an  action  on  'detruit'  objects
                                using  the "!I" expression for the 'in place' entry and "!~I" for
                                the 'to be added' entry.

                           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

                                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.

                                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

                           -/ "{!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]  {I&~I}[{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 semicolon ';') 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 colon character (:), 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

                           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/filtering  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 in 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

                           %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[,]]
                           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  summary  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  slightly
                           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 archive
                           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  length
                           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 len 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 available functions are:

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

                                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 closest to the file size
                                (base 2 logarithm).

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

                                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

       -{, --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 transferred 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  behavior  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  implicitly  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 incrementally 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 encouraged 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

              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 reaches an inode  which  is  part  of  this  provided  colon-
                           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-
                           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
                           re-save 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 iteration count used to derive the archive key from the passphrase
                           you provided (archive encryption context) and the hash algorithm  used
                           for  that  derivation. -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.

              Without  --kdf-param  the  KDF  fonction  uses 200,000 iterations for md5, sha1 and
              sha512 (PBKDF2 from PKCS#5 v2) but only 10,000 for argon2. If libargon2 is present,
              this is the default hash algorithm, else sha1 is used with PBKDF2. Valid parameters
              are "sha1", "sha512", "md5" and "argon2"  for  the  hash  algorithms  and  a  value
              greater  than  1 for the iteration count. However it is advise to use a value equal
              or greater to the default values mentionned previously. 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". Example of use: --kdf-param 20k:argon2

       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 "--deleted=ignore" option  which  is
                           ignored  when  the  -/  is  used).  Of  course  "--deleted=ignore" and
                           "--deleted=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

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

       -au, --alter=unix-sockets
                           Do  not  restore  unix-sockets.  By  default  saved  unix  sockets are
                           recreated at restoration time.

       -ap, --alter=place  Since version 2.7.1 libdar stores the filesystem root path  (given  -R
                           option)  used  when  creating  a backup, this is the known as the 'in-
                           place' path. At restoration time by default, dar uses the provided  -R
                           option  or  if  not  specified  uses  the  current  directory  as root
                           directory for the restoration operation. Using -ap option lead dar  to
                           read the in-place path from the backup and restore the data using this
                           path instead. This option is thus exclusive with  -R  option  and  may
                           lead dar to report an error if the archive has not stored any in-place
                           path (older archive format or backup resulting of the merging  of  two
                           backups having different in-place path).


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

       -ap, --alter=place  is also available as described just above for restoration options.

       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 re-sliced (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

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

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


       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

       -M                  must be replaced by -M I:/

       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


       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 answering a 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

       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

       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.


       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.


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


       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

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


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

              # 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 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 '_'

       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

                -R /
                -P proc
                -P sys
                -P mnt

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

                 -g home

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


       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
                  -K toto

                  -B second.dcf

                  #never reached
                  -s 10k

              # cat second.dcf

       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


                 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 colon (:) separated list of paths
                 and look in each of them in turn, up to the first file found under the requested

                 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 colon (:) separated list of paths and
                 looks in each of them in turn, up to the first file found  under  the  requested

                 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  disk 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  ssh/sftp  protocol.  In the known_hosts file, libssh2 does not support
                 recent lines like those with "ecdsa-sha2-nistp256" in second argument before its
                 release  1.9.0 (you will also need curl/libcurl 7.69.1 or more recent), in these
                 old versions you only have  support  for  "ssh-rsa"  lines.  Check  libssh2  and
                 libcurl  documentations  and  literature for more details about that limitation.
                 The workaround, if you have not yet libssh2 1.9.0 or more recent, is 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.

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

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

                 receive a colon 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 asymmetric 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.


       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.


       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


       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


       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


       Denis Corbin