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

NAME

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

SYNOPSIS

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

       dar -h

       dar -V

DESCRIPTION

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

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

       But the most important feature of dar is its ability to make differential and  decremental
       backups.  In  other  words, backups that contain only new files or files that have changed
       from a backup of reference.  Moreover with differential backup, dar also stores files that
       have  been  deleted  since  the  backup  of  reference. Thus, when restoring, first a full
       backup, then additional differential backups, at each restoration you get the exact  state
       of  the  filesystem  at  the  time  the  differential  backup was made. And of course, the
       reference backup may be a full or a differential backup itself, so you can make  the  same
       way incremental backups.

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

       Unlike  the  tar  command,  dar  has not to read a whole archive nor to stick together the
       different parts (the slices) to get its contents: dar archive contains a table of contents
       (aka  "catalogue")  located  at the end of the archive, so it seeks into the archive forth
       and backward to extract only the required files, which is much faster  than  what  tar  is
       used  to do. 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, all along the
       archive used for tar-like behavior suitable for sequential access media (tapes) and at the
       end  for  faster  access, suitable for random access media (disks).  However note that tar
       archive and dar archive are not compatible. Dar does not know anything about  tar  archive
       structure,  neither  tar  knows anything about dar archive structure. So keep using tar if
       you are used to it or find no advantage in  using  dar.  Note  also  that  the  sequential
       reading  mode  let you extract data from a partially written archive (those that failed to
       complete due to a lack of disk space for example).

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

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

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

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

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

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

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

       The rest of this document is organized that way:

              COMMANDS
                   The seven actions you can performs with dar

              GENERAL OPTIONS
                   A set of options common to all actions

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

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

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

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

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

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

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

              FILES
                   List configuration files that dar checks for

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

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

              ENVIRONMENT
                   Dar may rely on environment variables to look for DCF files and DUC files

OPTIONS

       COMMANDS:

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

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

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

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

       -x, --extract [<path>/]<basename>
                           extracts files from the given backup. Slices are expected to be in the
                           current  directory  or  in  the  directory given by <path>. It is also
                           possible to use symbolic links to gather slices that are  not  in  the
                           same directory. Path may also point to a removable device (floppy, CD,
                           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-
                           mode is used on command-line), dar will read the archive from standard
                           input (see also -i option), this can eventually be used in combination
                           with dar_split.

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

       -t, --test [<path>/]<basename>
                           checks  the backup integrity. Even without compression, dar is able to
                           detect at least one error  per  file  in  the  archive,  thanks  to  a
                           variable  length  CRC  recorded per file data, file EA and file FSA in
                           the  catalogue.  Archive  structure  (slice  header,  archive  header,
                           catalogue)  is  also protected by CRC to be able to detect any kind of
                           archive corruption. Same remark here, "-" may be used as basename (see
                           -x option above for details).

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

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

       -h, --help          displays help usage.

       -V, --version       displays version information.

       GENERAL OPTIONS:

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

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

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

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

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

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

       -va, --verbose=all  activates  all  the  previously described verbose options, 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).

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

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

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

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

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

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

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

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

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

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

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

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

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

                                  - a plus sign ("+") which makes the reference  be  the  current
                                  directory  status.  This argument is only available for archive
                                  creation (-c option). In other word, no  file's  data  will  be
                                  saved,  just  the current status of the inodes will be recorded
                                  in the catalogue. This  feature  is  known  as  the  "snapshot"
                                  backup.  A snapshot backup can be used as reference later on to
                                  detect or save only the  files  that  have  changed  since  the
                                  snapshot was made.

                                  -  a  <date>,  if  -af  option has been placed before -A on the
                                  command-line or in a included file (see -B  option).  For  more
                                  about  that  feature  see  -af  option below. This form is only
                                  available for archive creation (-c option).

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

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

                           During Catalogue isolation (-C option), dar will create  the  isolated
                           catalogue from the one given with -A option.

                           During   testing,   diff   or   extraction,  (-t,  -d  or  -x  options
                           respectively), the table of contents (the catalogue) will be read from
                           the  archive  given with -A instead of using the internal catalogue of
                           the archive. The archive given for rescue  must  has  been  previously
                           isolated  from this same archive (else the contents will not match and
                           dar will refuse to proceed to this operation). This acts as  a  backup
                           solution  to  the  case  of  corruption inside an archive's catalogue,
                           while the best way is still to  use  Parchive  to  protect  your  data
                           against media error.

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

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

                                  - a number of second since Jan 1st, 1970

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

                           Here are some examples of date:
                                  91836383927108078

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

                                  20:20 Which is 8 PM of the current day

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

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

       -@, --aux [<path>]/<basename>, --on-fly-isolate [<path>]/<basename>
                           specifies  an  auxiliary archive of reference (merging context) or the
                           name of the on-fly isolated catalogue (creation context). This  option
                           is thus only available with -+ option (merging) and -c option (archive
                           creation). Note that --aux and --on-fly-isolate are really aliases  to
                           the  same  option,  this  is  the  context of use (archive creation or
                           merging) which lead it to behave a way or another.

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

                           In a backup context -@ option let the user specify  the  archive  name
                           for  an  on-fly  isolation. With on-fly isolation, you can also use -$
                           option (to define encryption algorithm and passphrase), -~ option  (to
                           execute a command once the on-fly isolated catalogue is completed) and
                           -% option (crypto block size). On-fly  isolated  catalogue  is  always
                           bzip2  if  possible  else  gzip else lzo compressed (using compression
                           level 9) else not compressed, and it is also always  a  single  sliced
                           archive.  Due  to  command-line exiguity, it is not possible to change
                           compression algo nor slice size for the on-fly isolation. If you  need
                           a more complicated isolation, either look for a GUI over libdar, or do
                           a normal (= not an on-fly) isolation  operation  (By  the  way  it  is
                           possible  to isolate an already isolated catalogue, this is equivalent
                           to doing a  copy,  but  you  can  change  encryption,  compression  or
                           slicing,  for  example),  you  can  also  use dar_xform on an isolated
                           catalogue if you only want to change slices size (this is faster as no
                           decompression/re-compression  nor encryption/decryption is necessary).
                           Using the merging  operation  on  an  isolated  catalogue  instead  of
                           isolating  the  isolated catalogue, leads the resulting archive to not
                           be able to be used as a rescue for internal catalogue of the  original
                           archive. --aux-ref is a synonym to --aux.

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

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

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

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

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

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

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

       File selection in brief:

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

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

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

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

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

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

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

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

       Note concerning Extended Attributes (EA)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

                           %%        will be replaced by %

                           %p        will be replaced by the slice path

                           %b        will be replaced by the slice basename

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

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

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

                           %c        will  be  replaced  by  the context. Actually three possible
                                     values exist: "init",  "operation"  and  "last_slice".  When
                                     reading  an archive for (testing, extraction, diff, listing,
                                     or while reading the archive of reference, see below the  -F
                                     option),  the  "init" context takes place from the beginning
                                     up to the time the catalogue is  retrieved.  On  a  multiple
                                     slice  archive  this  correspond  to the last slice request.
                                     After, that point  comes  the  "operation"  context.   While
                                     creating  an  archive,  the  context  is  always "operation"
                                     except when the last slice has been created, in  which  case
                                     the context is set to "last_slice".
       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. Such file 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.

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

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

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

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

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

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

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

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

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

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

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

       -#, --crypto-block <size>
                           to  be able to randomly access data in an archive, it is not encrypted
                           globally but block by block. You can define the encryption block  size
                           thanks  to  this  argument which default to 10240 bytes. Note that the
                           syntax used for -s option is also available here (k, M, G, etc.). Note
                           also  that  crypto-block  is  stored  as  a 32 bits integer thus value
                           larger than 4GB will cause an error. Note last, that  the  block  size
                           given here must be provided when reading this resulting archive, using
                           the -* option if the archive is the archive of reference (given to  -A
                           option)  using  -%  options if the archive is the auxiliary archive of
                           reference (given to -@ option) or using this -# option if  it  is  the
                           subject  of  the operation (listing, comparing, testing that archive).
                           If the value is not the default and the given value is not correct  in
                           regard  to  the value given at archive creation time, the archive will
                           not be possible to decrypt, it is thus safer to keep the default value
                           (and not using at all the -#, -*, -% options).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       -z[[algo:]level], --compression[=[algo][:][level]]
                           add  compression  within slices using gzip, bzip2, lzo or xz algorithm
                           (if -z is not specified, no compression is performed). The compression
                           level  (an  integer  from 1 to 9) is optional, and is 9 by default. Be
                           careful when using xz algorithm better  specify  a  compression  ratio
                           less  than  or  equal  to  6 to avoid important memory requirements. A
                           ratio of 1 means less compression and faster processing, while at  the
                           opposite a ratio of 9 gives the best compression but longest procesing
                           time. "Algo" is optional, it specifies the  compression  algorithm  to
                           use  and can take the following values "gzip", "bzip2", "lzo" or "xz".
                           "gzip" algorithm is used by default (for historical reasons see --gzip
                           below).  If  both  algorithm  and compression are given, a ':' must be
                           placed between them. Valid usage of -z option is for example: -z, -z9,
                           -zlzo,  -zgzip,  -zbzip2,  -zlzo:6, -zbzip2:2, -zgzip:1, -zxz:6 and so
                           on. Usage for long option is the same: --compression, --compression=9,
                           --compression=lzo,       --compression=gzip,      --compression=bzip2,
                           --compression=lzo:6,    --compression=bzip2:2,    --compression=gzip:1
                           --compression=xz:9 and so on.

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

       -s, --slice <number>
                           Size of the slices in bytes. If the number is appended by k (or K), M,
                           G,  T,  P  E,  Z  or Y the size is in kilobytes, megabytes, gigabytes,
                           terabytes, petabytes, exabytes, zettabytes or yottabytes respectively.
                           Example:  "20M"  means  20  megabytes,  by  default, it is the same as
                           giving 20971520 as argument (see also -aSI and -abinary  options).  If
                           -s  is  not  present  the  backup  will  be  written to a single slice
                           whatever the size of the backup may be (assuming your operating system
                           can support arbitrarily large files).

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

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

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

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

       -Y, --include-compression <mask>
                           Filenames  covered  by  this  mask  (and not covered 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

                           p    means 'Preserve', same as 'P' (but lowercase letter) preserve the
                                whole EA set and FSA. When merging two archives,  the  Attributes
                                set of the resulting file will be the ones of the 'in place' file
                                (whatever is the overwriting action taken for  its  data).  While
                                when  extracting  files to filesystem, the Attributes of the file
                                in filesystem will not be changed (whatever  is  the  overwriting
                                action  taken  for its data, unless the file is removed using the
                                'R' policy, which would  remove  the  inode  and  thus  also  any
                                Attributes it had).

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

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

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

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

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

                           r    means  'remove',  same as 'R' but for the Attribute set (thus all
                                EA and FSA entries) of a given  file  ('r'  is  lowercase  letter
                                here). The file of the resulting archive during merging operation
                                will not own any EA nor any FSA, even if the  'in  place'  and/or
                                the  'to be added' files did have some. For file extraction, this
                                means that the file in the filesystem will loose all its EA  set.
                                The  FSA cannot be 'removed' from a filesystem and may not always
                                have a default value, thus this action does not modify FSA at all
                                in case of archive extraction. But in case of merging the FSA are
                                removed as previously described. As for all the  previous  tests,
                                this  Attribute  operation is independent of the operation chosen
                                for file's data (uppercase letters).

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

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

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

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

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

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

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

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

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

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

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

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

                           Well  so far it seems useless. But instead of the "if <condition> then
                           <action> else <action>" paradigm common to programming languages,  due
                           to  the  command  line  context  it has been chosen to instead use and
                           implicit  "OR"  operator  between  actions.   Thus  you  can   "stack"
                           conditional    statements    this    way:    {<condition1>}[<action1>]
                           {<condition2>}[<action2>] <action3>. In this example, if  <condition1>
                           is true then <action1> will be used, ELSE if <condition2> is true then
                           <action2> will be used ELSE <action3> will be used.  This leads to the
                           same  possibilities  as  what is available with programming languages,
                           but with a slightly more simple syntax. Seen this,  the  recursion  of
                           conditional  syntax  is  more  interesting.   For readability, you are
                           allowed to add any space or tab in the  overwriting  policy,  but  the
                           resulting  overwriting  policy  must  be given as a single argument to
                           dar, thus the use of quotes (either simple ´arg´ or double  "arg")  is
                           necessary.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       -_, --retry-on-change count[:max-byte]
                           When  a  file  has changed at the time it was read for backup, you can
                           ask dar to retry saving it again. By default a file can be re-saved up
                           to  3  times  (this  is  the 'count' field), you can set it to zero to
                           disable this feature. In option the overall  maximum  amount  of  byte
                           allowed  to be wasted due to retry changing file's backup can be given
                           after a column charactrer  (:),  this  is  the  'max-byte'  field.  By
                           default  (no  --retry-on-change  option specified) a limit of 1 wasted
                           byte is allowed which is the mininum. Specifying zero for max-byte set
                           no  limit  on the amount of wasted bytes (same as if no 'max-byte' was
                           specified), each changing file is then saved up to  'count'  times  if
                           necessary.

                           A  file  is  considered as changed when the last modification time has
                           changed between the time the file has been opened for backup  and  the
                           time it has been completely read. In some situation it is not possible
                           to replace the already saved data for a file  (writing  archive  to  a
                           pipe  for  example), in that situation only, a second copy of the file
                           is added just after the first previous try which leads  that  previous
                           try  to  becomes  inaccessible,  however  it  holds  some place in the
                           archive, where from the designation of "wasted bytes". You can  remove
                           all  wasted  bytes from an archive using the merging/fitering feature:
                           dar -+ new_arch -A old_arch -ak.

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

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

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

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

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

                           %d   this is the current date and time

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

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

                           %h   the hostname on which the archive has been created

                           %%   the % character.

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

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

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

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

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

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

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

                           %%        will be replaced by a literal %

                           %p        will be replaced by the full path under backup

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

                           %u        will be replaced by the UID of the file

                           %g        will be replaced by the GID of the file

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

                           %c        and  most  interesting, %c (c for context), will be replaced
                                     by "start" or by "end" when the command is  executed  before
                                     or after the backup respectively.
       This  way, one can stop a database just before it is about to be backed up, and restart it
       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 file in that directory or subdirectories have been saved, the command is  ran
       a second time (with the context "end"). During that time, if any file do match the backup-
       hook masks, no command will be executed for these. It is assumed that when a directory has
       been  asked  for  a  backup-hook to be executed this hook (or user command) is prepare for
       backup all data located in that directory.  The  environment  variable  DAR_DUC_PATH  also
       applies to these user commands (see -E above, or the ENVIRONMENT paragraph below).

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

       RESTORATION SPECIFIC OPTIONS (to use with -x)

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

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

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

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

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

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

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

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

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

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

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

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

       LISTING OPTIONS (to use with -l)

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

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

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

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

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

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

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

                 [FSA]     Each character represent a FSA Family:

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

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

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

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

                 [compr]   possible values are [....%] or [-----] or [     ] or [worse]. Shows if
                           the  file  has  been  compressed  ([...%])  and  the compression ratio
                           reached "(uncompressed-compressed)/uncompressed", for example  [  33%]
                           means  that the compressed data uses only 66% of the space required to
                           store uncompressed data (33% of space saved thanks to compression), or
                           if  the  file  is stored without compression ([    ] see -m, -Y and -Z
                           options) or if the file is not subject to compression  because  it  is
                           not  a  saved  regular  file ([----]), or if the file takes more space
                           compressed than  its  original  size  ([worse]),  due  to  compression
                           overhead.  Note  that  1%  compression  ratio  brings  quite  no  data
                           reduction, while  obviously  98%  is  a  very  performant  compression
                           (compressed   file   takes  only  2%  of  the  size  required  by  the
                           uncompressed date).

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

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

                 user      owner of the file

                 group     group owner of the file

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

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

                 filename  The name of the file.

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

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

EXPLICIT OPTIONAL ARGUMENTS

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

       -z                  must be replaced by -z 9

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

       -H                  must be replaced by -H 1

       -0                  must be replaced by -0 ref

       -5                  must be replaced by -5 ""

       -p                  must be replaced by -p 1

       -v                  must be replaced by -v all

       -k                  must be replaced by -k ignore

       -5                  must be replaced by -5 user.libdar_no_backup

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

EXIT CODES

       dar exits with the following code:

       0         Operation successful.

       1         Syntax error on command-line or DCF included file

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

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

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

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

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

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

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

       9         this code indicates an unknown error. The exception caching code to take care of
                 new exceptions has probably been forgotten to be update ... this is a minor  bug
                 you are welcome to report.

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

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

SIGNALS

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

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

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

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

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

       SIGUSR1   This signal can be generated by the kill command

       SIGUSR2   This signal can be generated by the kill command

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

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

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

FILES

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

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

CONDITIONAL SYNTAX

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

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

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

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

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

       test:               if -t option has been used

       diff:               if -d option has been used

       isolate:            if -C option has been used

       merge:              if -+ option has been used

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

       auxiliary:          if -@ option has been used

       all:                in any case

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

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

       Here is an example of conditional syntax

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

              all:
              -b
              -p

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

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

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

USER TARGETS

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

       Let's see an example of use:

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

              # normal set of files considered for backup

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

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

              home:
                 -g home

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

              verbose:
                -v
                -vs

       Then we could run dar in the following ways:

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

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

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

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

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

              # cat first.dcf
                target3:
                  -K toto

                target1:
                  target2
                  -B second.dcf
                  target3

                target2:
                  #never reached
                  -s 10k

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

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

ENVIRONMENT

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

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

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

                 export GNUPGHOME=~myaccount/.gnupg

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

EXAMPLES

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

SEE ALSO

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

KNOWN LIMITATIONS

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

KNOWN BUGS

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

AUTHOR

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