manpagez: man pages & more
man dar(1)
Home | html | info | man
dar(1)                                                                  dar(1)




NAME

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


SYNOPSIS

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

       dar -h

       dar -V


DESCRIPTION

       dar  is  a  full featured backup tool, aimed for local and remote disks
       (floppy, CD-R(W), DVD-R(W), zip, jazz, hard-disks, usb keys,  etc.  and
       cloud  storage  by  mean  of ftp or sftp protocols) and also adapted to
       tapes.


       dar can store a backup in several files (called "slices" in the follow-
       ing)  of  a  given  size,  eventually  pausing  or  running a user com-
       mand/script before starting the next slice. This can allow for example,
       the  burning  of the last generated slice on a DVD-R(W), Blue-ray Disk,
       or changing of usb key before continuing on the  next  one.   Like  its
       grand-brother,  the  great "tar" command, dar may also use compression,
       at the difference that compression is used inside  the  archive  to  be
       able to have compressed slices of the defined size.

       But  the most important feature of dar is its ability to make differen-
       tial, incremental and decremental backups. In other words, backups that
       contain only new files or files that have changed from a backup of ref-
       erence. Binary delta is available but not activated by default: in com-
       bination  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, "ar-
       chive" 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 ar-
       chive 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 ar-
       chive  are  not  compatible. Note also that the sequential reading mode
       let you extract data from  a  partially  written  archive  (those  that
       failed  to  complete due to a lack of disk space for example) and since
       release 2.6.0 such truncated archive can be repaired to become a normal
       archive (the "catalogue" is rebuilt from inlined information).

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

       Dar  format is quite robust against corruption: Only the file where the
       corruption took place in the archive will not be possible  to  restore.
       To have the possibility to repair a corrupted archive dar can work with
       par2  seamlessly  just   specifying   "par2"   on   command-line   (see
       /etc/darrc).  Last a "relax" reading mode is available which let dar to
       either ignore some  incoherence  in  archive  structure,  use  internal
       redundant  information  to  overcome  data corruption or in last resort
       asking the user on what to do when some archive  structure  information
       is  missing (-al option). This relax mode can be used with both sequen-
       tial and direct access read modes. Note  that  you  should  rather  use
       Parchive  to  protect your data rather than just relying on the "relax"
       mode, which has to be seen as a the last chance solution.

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

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

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

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




WARNING

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




DOCUMENT STRUCTURE

       The rest of this document is organized that way:

              COMMANDS
                   The eight actions you can performs with dar

              GENERAL OPTIONS
                   A set of options common to all actions

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

              RESTORATION SPECIFIC OPTIONS
                   A set of options that are specific to the restoration oper-
                   ation

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

              LISTING OPTIONS
                   A set of options that are specific to archive listing oper-
                   ation

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

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

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

              FILES
                   List configuration files that dar checks for

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

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

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



COMMANDS AND OPTIONS

       COMMANDS:

       Only  eight  commands  define  what action will be done by dar: Archive
       creation, archive extraction, archive listing, archive testing, archive
       comparison  with  filesystem,  catalogue isolation, archive merging and
       archive repairing. These commands are described here below.

       Once defined, a large set of options can be used to modify the way  the
       command  is  performed. These options are described just after the com-
       mands chapter.

       Important note: Not all systems actually support long options (Solaris,
       FreeBSD, ...). For example --create will not be available on these sys-
       tems, 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 num-
       ber  between  the dots is the slice number, which starts from 1 and may
       be arbitrary large (as large as your system can support the correspond-
       ing  filename). For example "my_first_archive.42.dar" is the 42th slice
       of the archive which basename is "my_first_archive".


       -c, --create [[<URL>]<path>/]<basename>
                           creates a backup with the name based on <basename>.
                           All  the  slices  will  be created in the directory
                           <path> if specified, details about the  <URL>  syn-
                           taxe 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  con-
                           tinue  its  operation. To make free space, the only
                           thing you cannot do is to  touch  the  slice  being
                           written. If the filename is "-" *and* no slicing is
                           asked for (no -s option) the archive is produced on
                           the  standard  output allowing the user to send the
                           resulting archive through a pipe (or  into  a  tape
                           device directly or using the dar_split command).

       -x, --extract [[<URL>]<path>/]<basename>
                           extracts  files  from  the given backup. Slices are
                           expected to be in the current directory or  in  the
                           directory  given by <path> (see also Remote reposi-
                           tory syntax below). It is also possible to use sym-
                           bolic  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 stan-
                           dard input (see also -i option), this  can  eventu-
                           ally 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  compres-
                           sion,  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, ar-
                           chive  header,  catalogue) is also protected by CRC
                           to be able to detect any kind  of  archive  corrup-
                           tion. 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 cata-
                           logue'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 iso-
                           lated catalogue is produced on the standard output,
                           allowing the user to  send  the  resulting  archive
                           through a pipe. Note that there is quite no differ-
                           ence 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 differen-
                           tial 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  dec-
                           tect  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 argu-
                           ment to this command). The dar file selection mech-
                           anism  (see  GENERAL  OPTIONS)  let the user decide
                           which files will be present in  the  resulting  ar-
                           chive  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 base-
                           name 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 con-
                           tention 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-com-
                           pressed.  Thus the merging operation can be used to
                           change compression algorithm of  given  archive  as
                           well as change its encryption. But, for better per-
                           formance it is also  possible  thanks  to  the  -ak
                           option (see below the -ak option for usage restric-
                           tions) 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 con-
                           tent of the archive and once its end is reached, to
                           recreate  the  missing  table of content (aka cata-
                           logue) 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 sim-
                           pler to implement allowing to reuse routines of the
                           merging  operation, second by precaution for dar to
                           not mess an existing archive due to a bug and last,
                           it would not be compatible with archive signing and
                           gpg encryption under certains  conditions  (several
                           recipients or the archive is signed and you are not
                           the one who signed it).

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

       -h, --help          displays help usage.

       -V, --version       displays version information.

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

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

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


              proto
                 is either ftp or sftp

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

              password
                 if  login  is  provided, the associated password may be given
                 after a column (:) but this exposes the  secret  password  to
                 other  users of the current system having access the table of
                 process (using top, ps, /proc or other ways). If the login is
                 given  without  password, the password will be asked interac-
                 tively by dar at run time, which is much more secure.  Alter-
                 natives  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-authentica-
                 tion  in  that  case to avoid a password being asked interac-
                 tively). Note that passphrase support for  sftp  key  is  not
                 (yet) supported.

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

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

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

       GENERAL OPTIONS:

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

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

       -vt, --verbose=treated
                           Display  treated  files  because  of file filtering
                           inclusion specified by the user or no file  filter-
                           ing  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 use-
                           less 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 cur-
                           rently performing  but  not  related  to  currently
                           treated or skipped files and directories

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

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

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


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


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

       -B, --batch <filename>
                           In the file which name is given in argument to this
                           option, You can put any option or argument as  used
                           on  command  line,  that  will be parsed as if they
                           were in place of the "-B <filename>"  option.  This
                           way  you can overcome the command line size limita-
                           tion. Commands in the file may be disposed on  sev-
                           eral  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 char-
                           acter must be  the  first  character  of  the  line
                           (space or tab can still precede the hash). See Con-
                           ditional Syntax below for a richer syntax  in  this
                           type  of configuration files known as DCF file (Dar
                           Configuration File). See also the environment vari-
                           able 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  nor-
       mal character in the file you will have to double it ("c:\\windows" for
       example)

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

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

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

                           If an  overwriting  policy  is  specified  (see  -/
                           option) -n option do only apply to slices overwrit-
                           ing, the overwriting of files during restoration or
                           merging is handled by the overwriting policy. With-
                           out overwriting  policy,  -n  applies  to  restored
                           files as well as generated slices.

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

       -wa, --no-warn=all  This implies the -w option,  and  means  that  over
                           avoiding  warning  for  file  overwriting, DAR also
                           avoids signaling a file about to  be  removed  when
                           its  type is not the expected one. File are removed
                           when they have been recorded as deleted  since  the
                           archive of reference. At restoration of the differ-
                           ential 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 com-
                           mand) 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  cur-
                           rent  directory  by  default. Usually only the last
                           slice is required to extract the catalogue of  ref-
                           erence.  If  necessary the use of symbolic links is
                           also possible here to gather  slices  that  do  not
                           reside  in  the  same directory. You can also point
                           <path> to a USB key, DVD-R(W) or any other  mounted
                           directory,  because dar will pause and ask the user
                           for required slices if they are  not  present.  The
                           argument to -A may be of four types:

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

                                  -   a  dash  ("-")  in  direct  access  mode
                                  (default mode,  when  --senquential-read  is
                                  not  used) it may imply the use of -o and -i
                                  options, this allows the archive  of  refer-
                                  ence  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 refer-
                                  ence be the current directory  status.  This
                                  argument  is only available for archive cre-
                                  ation (-c option). In other word, no  file's
                                  data  will be saved, just the current status
                                  of the inodes will be recorded in the  cata-
                                  logue.  This  feature is known as the "snap-
                                  shot" backup. A snapshot backup can be  used
                                  as reference later on to detect or save only
                                  the files that have changed since the  snap-
                                  shot 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 cre-
                                  ation (-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 filesys-
                           tem. 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 ref-
                           erence is a full backup some call it a differential
                           backup,  while  if the archive of reference is dif-
                           ferential 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 "dif-
                           ferential" backup in the documentation.

                           During merging operation (-+ option), the  contents
                           of  the -A given archive will been taken eventually
                           with the contents of the -@  auxiliary  archive  if
                           specified  (see  below), to form a new archive from
                           files of this or these archives. Note that you  can
                           filter  out files from the operation and setup sub-
                           set 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  ar-
                           chive'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 modi-
                           fication  is newer or equal to <date>, and which to
                           consider unchanged: those older than  <date>.  This
                           option  has only a meaning when creating an archive
                           (-c option) and must be placed before -A option  to
                           have an effect.

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

                                  - a number of second since Jan 1st, 1970

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

                           Here are some examples of date:
                                  91836383927108078

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

                                  20:20 Which is 8 PM of the current day

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

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

                           Note that the provided date is relative to the sys-
                           tem timezone which is overriden if the TZ environe-
                           ment  variable  is  set  (see  tzselect(1) for more
                           details)

       -@, --aux [[<URL>]<path>]/<basename>, --on-fly-isolate  [<path>]/<base-
       name>
                           specifies an auxiliary archive of reference  (merg-
                           ing  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  cre-
                           ation  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 refer-
                           ence 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 con-
                           cerning 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  iso-
                           lated 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  iso-
                           lation,  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 iso-
                           lated 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  neces-
                           sary). Using the merging operation on  an  isolated
                           catalogue  instead  of isolating the isolated cata-
                           logue, 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  opera-
                           tion   (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  cur-
                           rent  directory if -R is not present). Note that -R
                           is useless for testing (-t  option)  isolation  (-C
                           option) and merging (-+ option)

       -X, --exclude <mask>
                           The  mask  is a string with wildcards (like * and ?
                           see glob(7) for details) which is applied to  file-
                           names  which  are  not directories. If a given file
                           matches the mask, it is excluded  from  the  opera-
                           tion.  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  direc-
                           tory,  which  defaults to current directory.  Warn-
                           ing, -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  inter-
                           preted  in  the listing file, the null character is
                           not allowed and the carriage return is used to sep-
                           arate 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 direc-
                           tory (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 direc-
                           tories). As for -[ option, -] listing file can con-
                           tain   absolute   paths,   but  wildcards  are  not
                           expanded, neither.

       File selection in brief:

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

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

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

              the ordered method (when -am option is given on command-line):
                   The  ordered  method  takes  care  of the order of presence
                   between -X and -I in one hand and of -P, -g, -[ and  -]  in
                   the  other hand (note that it has also the same action con-
                   cerning 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  char-
                        acter),  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 posi-
                        tions 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>  gener-
              ates 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  acti-
                           vated  at compilation time. This option can be used
                           multiple times.

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

       Note concerning Extended Attributes (EA)

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

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

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

              the -am flag here also enables the ordered method, for EA selec-
              tion 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 (accord-
              ing 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 sensitiv-
              ity 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 privi-
                                leged 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,  syn-
                                chronous-update,   top-of-directory-hierarchy.
                                Note  that  "extx"  and  "ext" are aliases for
                                this FSA family. In spite of  its  name,  this
                                family   of   attributes  is  not  limited  to
                                ext2/3/4 filesystems.

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

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

                           By  default  no  restriction is done and FSA of all
                           families are considered at restoration time, but if
                           a family has not been activated at compilation time
                           a warning is issued for each file that cannot  have
                           its  FSA restored completely (unless this family is
                           excluded from the scope thanks to the  -4  option).
                           At backup time, if an FSA family has not been acti-
                           vated 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  inci-
                           dence  on  the  --backup-hook-exclude and --backup-
                           hook-include options.

       -an, --alter=no-case
                           set the filters in case insensitive mode. This con-
                           cerns  only  masks specified after this option (see
                           also -acase option below). This changes the  behav-
                           ior 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  envi-
       ronment  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  environ-
       ment 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 conse-
       quence, if different locales are used on your system and you are  doing
       a  system  wide  backup,  using  --alter=no-case option may lead dar to
       detect invalid wide character, in that case it falls back to a byte  by
       byte  case  sensitivity comparison (ASCII characters), which may not be
       what you would expect at first sight: Most of the time, an  upper  case
       wide  character (stored on several bytes) does not match the equivalent
       lower case wide character (several bytes too),  when  case  sensitivity
       comparison is performed byte by byte.

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

       -ar, --alter=regex  set  the  filters  to  be  interpreted  as  regular
                           expressions (man regex(7) ) instead of the  default
                           glob  expression  (man  glob(7) ) This modifies the
                           -I, -X, -g, -P, -Z, -Y, -u and -U options that fol-
                           lows 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> (usu-
                           ally 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 interac-
                           tive messages). See doc/usage_notes.html for  exam-
                           ples  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  cer-
                           tain 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 mis-
                                          match and at  restoration  dar  will
                                          not  even try to set the file owner-
                                          ship.

                           mtime          only inode type and  last  modifica-
                                          tion  date  is considered as well as
                                          inode specific attributes like  file
                                          size  for  plain files. Ownership is
                                          ignored, permission is ignored. Dur-
                                          ing comparison, difference on owner-
                                          ship or permission is ignored and at
                                          restoration time dar will not try to
                                          set the inode permission and  owner-
                                          ship.

                           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  owner-
                                          ship,  permission,  and dates and at
                                          restoration dar will not try to  set
                                          the ownership, permission and dates.

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

       -H[num], --hour[=num]
                           if  -H  is  used, two dates are considered equal if
                           they differ from a integer  number  of  hours,  and
                           that  number is less than or equal to [num]. If not
                           specified, num defaults to 1.  This  is  used  when
                           making a differential backup, to compare last_modi-
                           fication 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 hav-
                           ing gone from or  to  daylight  saving  time  (win-
                           ter/summer time). Note that -H option has influence
                           on the overwriting policy (see -/ option)  only  if
                           it  is  found  before  on  command-line  or  in  an
                           included file (using -B option).

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

                           %%        will be replaced by %

                           %p        will be replaced by the slice path

                           %b        will be replaced by the slice basename

                           %n        will  be replaced by the slice number (to
                                     be read or just  written).  For  reading,
                                     dar  often needs the last slice, but ini-
                                     tially 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 read-
                                     ing an archive for (testing,  extraction,
                                     diff,  listing,  or while reading the ar-
                                     chive 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 "opera-
                                     tion" except when the last slice has been
                                     created, in which case the context is set
                                     to "last_slice".

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

       Several  -E  option can be given, given commands will then be called in
       the order they appear on the command line and -B included  files.  Note
       that  having  '-E  script1  -E  script2'  is  totally equivalent to '-E
       "script1 ; script2"'. In other words if  script1  fails,  script2  fill
       still  be  executed and dar will only be notified of the exit status of
       the last -E option. Exit status of previous -E given commands  will  be
       ignored.  If  this  does  not  match your need, consider using a single
       -aduc option (see below). More generally you can  use  any  shell  con-
       struction 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  com-
                           mands  to always being executed. --aduc option com-
                           bines the different DUC commands  using  the  shell
                           "&&"  operator,  which  execute the next command if
                           and only if  the  previous  command  succeeded.  In
                           other  words,  dar  get notified of an error in any
                           given DUC command but due to an error not  all  DUC
                           commands may be executed.

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

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

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

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

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

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

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

                           Note that giving the passphrase as argument  to  -K
                           (or -J or '-$' see below) may let other users learn
                           pass phrase (thanks to the ps, or top  program  for
                           examples).  It  is thus wise to either use an empty
                           pass which will make dar ask the pass  phrase  when
                           needed, or use -K (or -J option) from a Dar Command
                           File (see -B option), assuming it has the appropri-
                           ated  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" mem-
                           ory (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  exe-
                           cution time, dar then makes use of secured (locked)
                           memory from the beginning.

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

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

                           Note that if you have set a passphrase on your pri-
                           vate  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 nec-
                           essary, 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 refer-
                           ence (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  avail-
                           able  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 ar-
                           chive is the auxiliary archive of reference  (given
                           to  -@ option) or using this -# option if it is the
                           subject of the operation (listing, comparing, test-
                           ing  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 syn-
                           onym.

       -%, --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: multi-
                           ple of 2^10  (a Mega is 1,048,576).

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

       -ac, --alter=ctime  When reading a filesystem (during a backup or  com-
                           parison),  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 sys-
                           tems, 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 pro-
                           gram Beagle). Ctimes on the  other  hand,  are  the
                           only  way  for security software to detect if files
                           on your system have been  replaced  (by  so  called
                           root-kits  mostly). This means, that should you run
                           dar with -ac, security software which  uses  ctimes
                           to  check,  will  mark every file on your system as
                           compromised after the backup. In short, this  means
                           this  option should only be used by people who know
                           what they are  doing.  It's  the  opinion  of  this
                           writer  that  any  software  susceptible  to  atime
                           changes is flakey or even broken  (because  of  the
                           afore  mentioned  reasons  why  atimes can change).
                           But, that doesn't take away that there are programs
                           who  rely on atimes remaining the same, like Leafn-
                           ode 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  accor-
                           dance  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 modi-
       fied while dar reads each file and directory. This provides also better
       performances as nothing has to be wrote back to disk. A known Unix ker-
       nel 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 compi-
       lation 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 infor-
                           mation  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 behav-
                           ior  is to ignore these escape sequences and rather
                           rely on the catalogue located at the end of the ar-
                           chive.  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 read-
                           ing 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  dur-
                           ing  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 start-
                           ing revision "08" (i.e.: since release  2.4.0)  and
                           if  -at option has no been used during archive cre-
                           ation or merging. This option is available for  ar-
                           chive  testing  (-t),  comparison (-d), restoration
                           (-x), listing (-l) and to read the archive of  ref-
                           erence  (-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  exam-
                           ple,  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 exam-
                           ple, if you provide 3 for  that  number,  dar  will
                           store  the  slice number as 001, 002, 003, ... 999.
                           Well, next slice will be 1000, thus it  will  break
                           again  the alphabetical sorting order. You are thus
                           advised to use a number large enough to convert the
                           number of slice you expect to use. Then, when read-
                           ing your archive, you will  also  need  to  provide
                           this  same argument, else dar will fail finding the
                           slice. In effect, when  looking  for  slice  1  for
                           example,  dar  should  try  opening the file "base-
                           name.1.dar", but if it fails, it should try opening
                           the    file    "basename.01.dar",    then    "base-
                           name.001.dar", ... up to infinity. If the slice  is
                           just  missing,  dar  would never ask you to provide
                           it, being still looking for a slice  name  with  an
                           additional  leading  zero.  The  problem also arise
                           when doing differential backup, merging  or  on-fly
                           isolation,  dar  must  know  the  number of zero to
                           prepend for each of these archive. This is why  the
                           --min-digits option may receive up to three integer
                           values, the first for  the  archive  to  create  or
                           read,  the  second for the archive of reference (-A
                           option), the third for  the  auxiliary  archive  of
                           reference  (-@  option).   By  default,  no zero is
                           added, and it is also well working  this  way.  But
                           you might well set for example "--min-digits 5,5,5"
                           in your ($HOME)/.darrc file to do it once  and  for
                           all.

       --pipe-fd <num>     will  read further arguments from the file-descrip-
                           tor <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  over-
                           come 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 cor-
                           ruption or even saved file's data  corruption  (dar
                           will detect but will not correct such event).

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

       -j, --network-retry-delay <seconds>
                           When a temporary network error occurs (lack of con-
                           nectivity, 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  net-
                           work error.

       -afile-auth, --alter=file-authentication
                           With  this  option,  When reading or writing an ar-
                           chive 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 pub-
                           lic key that has also been signed have correct sig-
                           natures.

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


       -z[[algo:]level], --compression[=[algo][:][level]]
                           add  compression  within  slices using gzip, bzip2,
                           lzo or xz algorithm (if -z  is  not  specified,  no
                           compression  is  performed).  The compression level
                           (an integer from 1 to 9) is optional, and is  9  by
                           default.  Be careful when using xz algorithm better
                           specify a compression ratio less than or equal to 6
                           to  avoid important memory requirements. A ratio of
                           1 means less  compression  and  faster  processing,
                           while  at  the opposite a ratio of 9 gives the best
                           compression but longest procesing time.  "Algo"  is
                           optional, it specifies the compression algorithm to
                           use and  can  take  the  following  values  "gzip",
                           "bzip2", "lzo" or "xz". "gzip" algorithm is used by
                           default (for historical reasons see --gzip  below).
                           If  both algorithm and compression are given, a ':'
                           must be placed between  them.  Valid  usage  of  -z
                           option  is  for  example:  -z,  -z9, -zlzo, -zgzip,
                           -zbzip2, -zlzo:6, -zbzip2:2, -zgzip:1,  -zxz:6  and
                           so  on.  Usage  for long option is the same: --com-
                           pression,    --compression=9,    --compression=lzo,
                           --compression=gzip, --compression=bzip2, --compres-
                           sion=lzo:6,    --compression=bzip2:2,    --compres-
                           sion=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  com-
              pression  level  1 of lzop, use the lzop-1 algorithm in place of
              lzo with dar/libdar. If you want to get  the  behavior  of  lzop
              compression  level  3,  use the lzop-3 algorithm in place of the
              lzo algorithm. Lzop compression levels 2, 4, 5  and  6  are  the
              same  as level 3. last, there is no difference about compression
              level 7, 8 and 9 between dar and lzop.  The  lzop-1  and  lzop-3
              algorithms do not make use of any compression level (compression
              level is ignored with these algorithms).

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

       -s, --slice <number>
                           Size  of  the  slices  in  bytes.  If the number is
                           appended by k (or K), M, G, T, P, E,  Z  or  Y  the
                           size  is  in  kilobytes, megabytes, gigabytes, ter-
                           abytes, petabytes,  exabytes,  zettabytes  or  yot-
                           tabytes   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  con-
                           tinue  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  inte-
                           ger 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 direc-
                           tory 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 use-
                           ful, 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  SPE-
                           CIFIC 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 (eventu-
                           ally/probably using wildcards).  This  option  used
                           while  merging or repairing allow one to change the
                           compression of files.

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

       -m, --mincompr <number>
                           files  which  size  is below this value will not be
                           compressed. If -m is not specified it is equivalent
                           to  giving  -m 100 as argument. If you want to com-
                           press 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 exten-
                           sions  as  those  used  with -s or -S are available
                           here, if you want to specify the size in  kilobyte,
                           megabyte, gigabyte etc.

       -1, --sparse-file-min-size <number>
                           Define  the  minimum  length  of  zeroed  bytes  to
                           replace by "holes". By  default,  this  feature  is
                           activated  with  a value of 15 bytes. To completely
                           disable it, set the size to  zero.  Disabling  this
                           feature  will  bring some noticeable speed improve-
                           ment 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 imple-
                           mentation  of any particular filesystem, where from
                           its portability),  when  it  finds  a  sequence  of
                           zeroed bytes larger than the given threshold it can
                           assume that it is in presence of a hole. Doing  so,
                           it  does  not store the given zeroed bytes into the
                           archive, but place a tag beside the saved  data  to
                           record the size of the hole and thus where to place
                           the next non zeroed bytes. This makes  dar  archive
                           disk  space  requirement much smaller when a sparse
                           files is met. At restoration time, dar will restore
                           holes writing normal data and seeking over the hole
                           to write down the normal data after each  hole.  If
                           the  underlying  file system supports sparse files,
                           this will restore the holes. Note that there is  no
                           difference  for  applications  whether  a  file  is
                           sparse or not, thus dar may well  transform  normal
                           files  into  sparse  files  and viceversa, only the
                           disk requirement will change. Last  point,  if  dar
                           can  reduce disk requirement for archive with holes
                           as small as 15 bytes (smaller value works  but  the
                           overhead  cost  more than what is required to store
                           the zeroed bytes normally), it may not be the  same
                           at  restoration, because filesystem allocation unit
                           is usually  several  kilobytes  (a  page),  however
                           restored file will never be larger than it could be
                           without holes. The only drawback of this feature is
                           the additional CPU cycle it requires.

       -ak, --alter=keep-compressed
                           During  merging and repairing operation, keep files
                           compressed, this has several restrictions : -z, -Z,
                           -Y,  -m  are  ignored,  if  two archives have to be
                           merged, both must use the  same  compression  algo-
                           rithm  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  usu-
                           ally CPU intensive).

       -ah, --alter=holes-recheck
                           For  merging  and repairing, the sparse file detec-
                           tion 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 detec-
                           tion  mechanism.  Then  for  merging  and  reparing
                           --sparse-file-min-size can  be  used  as  described
                           above  for  archive  creation. In addition, you can
                           have files stored as sparse file in the archive  of
                           reference  be  stored as normal files in the merged
                           archive using -ah and passing to --sparse-file-min-
                           size an value larger than all file sizes, for exam-
                           ple 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  com-
                           piled  on  did  not provide support for ext2 flags.
                           Note that this option does nothing with  -+  option
                           (merging)  as no filesystem is used for that opera-
                           tion.

       -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  com-
                           mand:  "setfattr  -n  user.libdar_no_backup  <file-
                           name>",  to  remove  it:  "setfattr  -x   user.lib-
                           dar_no_backup <filename>". Last, to check the pres-
                           ence this EA: "getfattr <filename>"

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

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

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

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

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

                           P    means 'Preserve'. When merging  two  archives,
                                the  data  of  the  resulting  archive will be
                                taken from the 'in  place'  file.  While  when
                                extracting,  the data of the inode in filesys-
                                tem 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  filesys-
                                tem  will  be overwritten by data from the ar-
                                chive.

                           S    means 'mark Saved and preserve'. When  merging
                                two  archives,  the  data of the resulting ar-
                                chive will be marked as already saved  in  the
                                archive  of reference (making thus a differen-
                                tial archive, even if none of the original ar-
                                chive  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  con-
                                sidered equal to "Preserve" (P) in that situa-
                                tion.

                           T    means 'mark Saved and overwrite'. When merging
                                two  archives,  the  data of the resulting ar-
                                chive will be marked as already saved (same as
                                'S'  action):  all data will be dropped in the
                                resulting archive, however the last  modifica-
                                tion  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 con-
                                flict. 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  con-
                                sidered  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 extract-
                                ing 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  filesys-
                                tem,  but its already existing Attributes will
                                stay untouched.

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

                           r    means  'remove',  same  as  'R'  but  for  the
                                Attribute set (thus all EA and FSA entries) of
                                a  given  file ('r' is lowercase letter here).
                                The file of the resulting archive during merg-
                                ing 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 extrac-
                                tion, this means that the file in the filesys-
                                tem  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  merg-
                                ing,  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 applica-
                                tion  interaction  let  the  user  define  the
                                action  for  each file in conflict. Note, that
                                this action if used alone may become very bor-
                                ing  or painful. The idea is to use it in con-
                                ditional  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 speci-
                           fied. Note that -w option stays untouched, in  con-
                           sequences, 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 filesys-
                                tem  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  over-
                           writing policy is evaluated first, then the filter-
                           ing mechanism is applied *after* it. Thus for exam-
                           ple,  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 end-
                           ing 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  filesys-
                           tem  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 how-
                           ever   that  any  FSA  present  on  filesystem  and
                           excluded from the FSA scope are not touched.

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

                           {<condition>}[<action if condition is true>]
                                This syntax let you place an  action  (as  the
                                ones  we  saw  just above) inside the brackets
                                '[' and ']' (for example [Pp]) that will  take
                                effect  only  if the evaluation of the <condi-
                                tion> is true.  Stated that a  such  statement
                                is  a new type of action, you may have guessed
                                that you  may  use  it  recursively:  {<condi-
                                tion1>}[{<condition2>}[<action>]).

                           Well  so  far  it seems useless. But instead of the
                           "if <condition> then <action> else <action>"  para-
                           digm  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>]       {<condi-
                           tion2>}[<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  condi-
                           tional  syntax  is more interesting.  For readabil-
                           ity, 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 dou-
                           ble "arg") is necessary.

                           The last operator we will see is the 'chain' opera-
                           tor. Once an expression is evaluated, the resulting
                           couple of action  may  contain  an  '*'  (undefined
                           action  for EA or data). Further evaluation must be
                           done. The chain operator which is represented by  a
                           semi-column  ';'  let one to separate several inde-
                           pendent 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 evalu-
                           ation in  the  chain,  however  if  the  action  is
                           defined  it  cannot  be set back to undefined, thus
                           '*'  will  never  overwrite  a  previously  defined
                           action.  If  at the end of the policy the couple of
                           action is not fully defined, the 'preserve'  action
                           is  used  ('P'  or  'p' depending on which of EA or
                           Data is left undefined). Here follow a  example  of
                           syntax:

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

                           We  now  have  one last thing to see: the available
                           conditions (what to place between  braces  '{'  and
                           '}').  Conditions  are  defined  each  by a letter,
                           eventually followed by an argument  between  paren-
                           thesis.  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 opera-
                           tor 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  nega-
                           tion  of  the  result  of the evaluation. All these
                           operators follow the usual precedence: unary opera-
                           tors  ('!'  and  '~') are evaluated first, then the
                           conjunction '&' then the disjunction '|'. To  over-
                           ride  this,  you  can  use  parenthesis '(' and ')'
                           inside the condition. Over these logical operators,
                           the  conditions  are  based on atomic operator that
                           compare the 'in place' file to the  'to  be  added'
                           file. Here they follow:

                           I    true  only if the 'in place' entry is an inode
                                (a 'detruit' which record the fact that a file
                                has  been  removed since the archive of refer-
                                ence is not an inode for example). This condi-
                                tion  do not have any consideration toward the
                                to be added object. Note that ~I can  be  used
                                to  check  the  nature  of  the  'to be added'
                                object.

                           D    true only if the 'in place' entry is a  direc-
                                tory.  To  know whether the 'to be added' is a
                                directory or not, one would  use  the  "inver-
                                sion" 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 sev-
                                eral times to the directory tree)

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

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

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

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

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

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

                           Y    true  only if the 'in place' data is saved but
                                dirty (plain file having its data  changed  at
                                the  time  it was read for backup). Note, that
                                restoring in sequential read mode, it  is  not
                                possible  to known whether a file is dirty (it
                                is possible to know it once  having  read  its
                                data,  but  sequential reading does not allows
                                then to skip forward to get the dirty state of
                                the  file  and  skip  backward  to  eventually
                                restore that file, depending on the  overwrit-
                                ing 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  refer-
                                ence was done), and so on). Note that the num-
                                ber 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 compari-
                                son is done on ctime dates.

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

                           m    true only if 'in place' has more or equal num-
                                ber 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,  what-
                                ever  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 readabil-
                                ity. 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 over-
                                write its EA. Else (if 'in place' has not  the
                                more  recent  data), if it has the more recent
                                EA then overwrite the data but  keep  its  EA,
                                else  overwrite  both  its  data and EA.  This
                                policy tends to preserve the most recent  data
                                or  EA,  but it does not take into account the
                                fact that EA or Data is effectively saved into
                                the  archive of just marked as unchanged since
                                the archive of reference.

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

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

                           -/ "{!T|!I}[{R}[Pp] Oo]  {S}[{~S}[{R}[P*]  O*]  P*]
                           {~S}[O*]  {R}[P*]  O*]  ;  {s}[{~s}[{r}[*p] *o] *p]
                           {~s}[*o] {r}[*p] *o]"
                                Well this may seems a bit too complex but just
                                see  it as an illustration of what is possible
                                to do: If both 'in place' and  'to  be  added'
                                are  not  of the same type we keep data and EA
                                of the most  recent  file  (last  modification
                                date).  Else,  both  are  of the same type. If
                                both are inode we evaluate a  two  expressions
                                chain  (expressions  are  separated by a semi-
                                column ';') we will  see  in  detail  further.
                                Else  if  they  are  of  same type but are not
                                inode we take the EA  and  data  of  the  most
                                recent entry (this is the last 10 chars of the
                                string). Well,  now  let's  see  the  case  of
                                inode:  The first expression in the chain sets
                                the action for data and keep the action for EA
                                undefined.  While  the  seconds,  is the exact
                                equivalent but instead it  leaves  the  action
                                for  data undefined '*' and set the action for
                                EA. These  two  expressions  follow  the  same
                                principle: If both entries are saved (by oppo-
                                sition to be marked as unchanged since the ar-
                                chive  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 permis-
                           sion  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  permis-
                           sion  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 max-
                           imum  amount  of  byte  allowed to be wasted due to
                           retry changing file's backup can be given  after  a
                           column  charactrer  (:),  this  is  the  'max-byte'
                           field.  By  default  (no  --retry-on-change  option
                           specified)  a  limit  of  1  wasted byte is allowed
                           which is the mininum. Specifying zero for  max-byte
                           set no limit on the amount of wasted bytes (same as
                           if no 'max-byte' was specified), each changing file
                           is then saved up to 'count' times if necessary.

                           A file is considered as changed when the last modi-
                           fication 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 possi-
                           ble  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  merg-
                           ing/fitering  feature:  dar -+ new_arch -A old_arch
                           -ak.

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


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

       -asecu, --alter=secu
                           This option disable the ctime check done by default
                           during an differential backup: If the ctime  of  an
                           plain  file has changed since the archive of refer-
                           ence was done while all other values stay unchanged
                           (inode  type, ownership, permission, last modifica-
                           tion 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 dif-
                           ferential backup of a just restored data (a differ-
                           ential 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 posi-
                           tive).

       -., --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 <ar-
                           chive> -q). Some macro can be used inside the <mes-
                           sage>:

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

                           %d   this is the current date and time

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

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

                           %h   the hostname on which  the  archive  has  been
                                created

                           %%   the % character.

       -3, --hash <algo>   With  this  option  set,  when creating, isolating,
                           merging or repairing an archive, beside each gener-
                           ated  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  com-
                           pute  the  hash  result  on a possibly already cor-
                           rupted file, thus the corruption will not  be  seen
                           when  testing  the file against the hash at a later
                           time. Note also that the creation of a hash file is
                           not  available when producing the archive on a pipe
                           ("dar -c -").

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

                           A summay information about the  signature  informa-
                           tion  is displayed while listing an archive in sum-
                           mary 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  sig-
                           nature  check  failed,  no  message is displayed in
                           case of successful signature  check.  This  warning
                           may  be  disabled using the --alter=blind-to-signa-
                           tures 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. IMPOR-
                           TANT:  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  sensitiv-
                           ity  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 correspond-
                                     ing 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  para-
       graph 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 con-
                           tents and failing on that unknown inode type  (fil-
                           tering  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, isola-
                           tion 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  signa-
                           ture,  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 sig-
                           nature transfer is not possible when the archive of
                           reference  is  read  in sequential mode, thus delta
                           signature is disabled when the archive of reference
                           is read in sequential mode.

                           For  isolation and merging operations, the behavior
                           is sligthly different: --delta sig option  let  dar
                           transfer  existing delta signatures from the origi-
                           nal 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   trans-
                           fered/dropped and if not present calculated accord-
                           ingly 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  con-
                           cernes  sparse  files, it is not possible to calcu-
                           late 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 miss-
                           ing in the reference archive. In short: if you want
                           recalculation  of delta signature while merging, do
                           not keep file compressed (do not  use  -ak  option)
                           and  if  you  want  to  avoid  having  sparse files
                           excluded from the  delta  signature  recalcutation,
                           activate  sparse  file  detection (use -ah option).
                           Delta signature transfer is not possible for on-fly
                           isolation,  you need to do normal atchive isolation
                           to obtain an isolated catalogue with  delta  signa-
                           tures.

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

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

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

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

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

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

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


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

                           For merging or isolation operations,  when  --delta
                           sig  is  used  no  delta signature is computed only
                           existing ones are transfered as is without restric-
                           tion.  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 combi-
                           nation 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 can-
                           not  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 refer-
                           ence 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 sig-
                           nature could be found or  if  --delta  no-patch  is
                           used, the normal behavoir is done, which consist of
                           saving that whole file in the archive. Note that if
                           the  archive  of  reference  is  read in sequential
                           mode, the --delta no patch is implicitely  used  as
                           reading  in sequential mode an archive does not let
                           skipping backward to fetch the delta signature nec-
                           essary to setup a delta patch.

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

              Once a full backup has been done using --delta sig, any  differ-
              ential  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  subse-
              quent  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  sig-
              natures  at  archive isolation time using --delta sig --include-
              delta-sig "*" options. Binary delta signature will then be  cal-
              culated based on the saved files. Then, using the resulting iso-
              lated 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 cor-
              ruption 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 hav-
                           ing  dates  before  1970),  in  that  situation  by
                           default  and  since  release  2.5.12 dar pauses and
                           asks the user whether to assume the date  as  being
                           zero. But with -az option, dar/libdar automatically
                           assumes such negative dates to  be  zero  and  just
                           issue a warning about the problem met.

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

       -'\'',   --modified-data-detection=any-inode-change,   --modified-data-
       detection=mtime-and-size
                           Before  release 2.6.0, during a differential/incre-
                           mental backup if any part of a file's  inode  meta-
                           data  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 histori-
                           cal behavior by invoking the --modified-data-detec-
                           tion=any-inode-change  option.  Since release 2.6.0
                           a new entry status ("inode-only") has  been  added.
                           Dar  can  now  resave  only metadata when the inode
                           change does not concern the data. To  know  whether
                           the data has changed or not, by default (no --modi-
                           fied-data-detection  option  given)  dar  looks  at
                           mtime  and  at file's size only. Specifying --modi-
                           fied-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 intera-
                           tion  count used to derive the archive key from the
                           passphrase you provided  (archive  encryption  con-
                           text)  and  the  hash  algorithm used for that. The
                           default value is 200,000 iterations and sha1  algo-
                           rithm.  -T has another older meaning when doing ar-
                           chive listing, but due to the lack of free  charac-
                           ter  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/isola-
                           tion. The consequence is that the  -T  option  must
                           appear  after  the  -+/-c/-C options for the opera-
                           tional context to be  known  at  the  time  the  -T
                           option  is  met  and  its --kdf-param meaning to be
                           taken into account. As --kdf-param is an  alias  to
                           -T,  this  long  form  of  this option must also be
                           found after the use of either -c, -C or -+  option.
                           The  suffixes  described  for  -s  option  are also
                           available here (k, M, G, T,  P,  ...)  however  pay
                           attention  to  the -aSI/-abinary mode which default
                           to binary, in which case "-T 1k" is  equivalent  to
                           "-T 1024".


       RESTORATION SPECIFIC OPTIONS (to use with -x)

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

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

       -f, --flat          do  not restore directory structure. All files will
                           be restored in the directory given to  -R,  if  two
                           files  of  the  same  name have to be restored, the
                           usual scheme for warning (-w option) and  overwrit-
                           ing  (-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 confirma-
                           tion  before restoring it. Specifying "ignore" will
                           skip  those  dirty  files,  while  "no-warn"   will
                           restore  them  without user confirmation. This fea-
                           ture 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 restora-
                           tion  to  define  when and how file overwriting can
                           occur. See above the description of this option.

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

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


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

       No other specific option, but all general options are available  except
       for  example  -w  which  is useless, as testing and comparing only read
       data. -A option is available as described in GENERAL OPTIONS to  backup
       of  internal  catalogue  of the archive (assuming you have a previously
       isolated catalogue available).

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

       LISTING OPTIONS (to use with -l)


       -T, --list-format=<normal | tree | xml | slicing>
                           By default, listing provides a tar-like output (the
                           'normal' output). You can however get  a  tree-like
                           output,  an  XML  structured  output  or  an output
                           focusing on slice(s) where each file's data, EA and
                           FSA  is  located in. The option --tree-format is an
                           alias to --list-format=tree  (backward  compatibil-
                           ity).  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 slic-
                           ing layout of the archive of reference. However, if
                           the  archive  of reference has been resliced (using
                           dar_xform) after the isolated  catalogue  has  been
                           built,  the  slicing  information would not be cor-
                           rect. 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 pro-
                           viding the encryption key.

       From the general options it seems only -vm and  -b  stay  useful  here.
       Note  that  -vm  displays an archive summary first, where a detailed of
       information about the archive can be obtained. If you want  to  display
       only this summary use -q with -l option.

       displayed fields

                 [Data]    possible  values  are [     ] or [Saved] or [InRef]
                           or [DIRTY] or [Inode] or  [Delta].  [      ]  means
                           that  the  data has not been saved because there is
                           no change since backup of reference. [Saved]  means
                           that  the  data has been saved completely, and thus
                           this archive is able to restore  the  file  without
                           other  help.  [InRef] was used in archive generated
                           by dar version 2.3.x and before  when  isolating  a
                           catalogue  from an archive, and means that the file
                           was saved in the reference archive.  [DIRTY]  means
                           that  data  is saved (like [Saved]) but has changed
                           at the time dar was reading it for backup,  leading
                           dar  to possibly store the file in a state it never
                           had. [Inode] means only  permission  ownership  and
                           ctime  data  changed since the archive of reference
                           was done is recorded in the archive, the  data  did
                           not changed according to the --comparison-field set
                           or not set. Last [Delta] means the file's  data  is
                           saved  as a binary delta (or delta patch), which is
                           much shorter than the full data  as  what  is  done
                           with  [Saved].  It  also  means  that  you can only
                           restore the file if it exists on filesystem in  the
                           state  it  had  when  the  archive of reference was
                           done, for the patch to be possible to apply on  it.
                           This  is  the case for example if you just restored
                           this file from the archive of reference.

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

                 [EA]      possible values are " " (empty string) or  [      ]
                           or  [InRef],  [Saved]  or [Suppr]. It Shows whether
                           Extended   Attributes   are   present   and   saved
                           ([Saved]),  are  present  but  not  saved ([     ])
                           which means there is no change since backup of ref-
                           erence,  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 avail-
                           able ([Suppr]). [InRef] was used when  isolating  a
                           catalogue  (release  2.3.x  and before) from an ar-
                           chive and means that the file was saved in the ref-
                           erence 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 refer-
                           ence 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 "(uncom-
                           pressed-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  sub-
                           ject to compression because it is not a saved regu-
                           lar 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 obvi-
                           ously 98% is a very  performant  compression  (com-
                           pressed  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 cir-
                           cumstances (saving an dar archive inside a dar  ar-
                           chive  without compression or encryption, for exam-
                           ple) a file without hole may be marked [X] as if it
                           had  holes  and  will be longer by on byte for each
                           data sequence looking like an escape sequence.

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

                 user      owner of the file

                 group     group owner of the file

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

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

                 filename  The name of the file.

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

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



EXPLICIT OPTIONAL ARGUMENTS

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

       -z                  must be replaced by -z 9

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

       -H                  must be replaced by -H 1

       -0                  must be replaced by -0 ref

       -5                  must be replaced by -5 ""

       -p                  must be replaced by -p 1

       -v                  must be replaced by -v all

       -k                  must be replaced by -k ignore

       -5                  must be replaced by -5 user.libdar_no_backup

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



EXIT CODES

       dar exits with the following code:

       0         Operation successful.

       1         Syntax error on command-line or DCF included file

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

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

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

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

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

       7         an  error  has  occurred  when calling a libdar routine. This
                 means the caller (dar program), did not respect the  specifi-
                 cation 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 forgot-
                 ten to be update ... this is a minor bug you are  welcome  to
                 report.

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

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



SIGNALS

       If dar receives a signal (see  kill(2)  man  page)  it  will  take  the
       default  behavior  which  most of the time will abruptly abort the pro-
       gram, 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 gener-
                 ated 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 gener-
                 ated 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 ar-
       chive 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 isola-
       tion,  dar's behavior is the same: For restoration, all opened directo-
       ries 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 opera-
       tion. 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 sig-
       nal is received a second time, dar will abort immediately.



FILES

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

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



CONDITIONAL SYNTAX

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

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

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

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

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

       test:               if -t command has been used

       diff:               if -d command has been used

       isolate:            if -C command has been used

       merge:              if -+ command has been used

       repair:             if -y command has been used

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

       auxiliary:          if -@ option has been used

       all:                in any case

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

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

       Here is an example of conditional syntax

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

              all:
              -b
              -p

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

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

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



USER TARGETS

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

       Let's see an example of use:

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

              # normal set of files considered for backup

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

              #  if the "home" user target is applied on command line the fol-
              lowing command get added

              home:
                 -g home

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

              verbose:
                -v
                -vs

       Then we could run dar in the following ways:

       dar -c test -B example.dcf
                           in that case only the command in the "create:" sec-
                           tion 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 condi-
       tional 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  sec-
       ond.dcf:

              # cat first.dcf
                target3:
                  -K toto

                target1:
                  target2
                  -B second.dcf
                  target3

                target2:
                  #never reached
                  -s 10k

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

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




ENVIRONMENT

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

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

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

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

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

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

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

                 export GNUPGHOME=~myaccount/.gnupg

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



CAPABILITIES

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



EXAMPLES

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



SEE ALSO

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



KNOWN LIMITATIONS

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



KNOWN BUGS

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



AUTHOR

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



3rd Berkeley Distribution       May 25th, 2019                          dar(1)

dar 2.6.4 - Generated Fri May 31 06:08:13 CDT 2019
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.