DAR(1)

NAME
dar - disk archive

SYNOPSIS
dar [-c | -x | -l | -d | -t | -C] [<path>/]<basename> [options] [list of paths]

dar -h

dar -V

DESCRIPTION
dar is a full featured backup tool, aimed for disks (floppy, CD-R(W), DVD-R(W), zip, jazz, etc.)

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

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

At the difference of the tar command, dar is not suited to directly use tapes. So keep using tar for tape archives. Because, even using tar to write a slice on a tape, you will loose all the interest of another feature of dar which is its ability to directly access the data of saved file even when compression is used. This way and in contrast to the tar command, dar is able to extract a given file much faster from a backup and to also recover files that follow a data corruption (loosing just the file in which data corruption occurred).

 This has of course its limitations, in particular when a data corruption occurs in the vital part of the backup, i.e. the few first bytes of each slice, and the last part of the archive (the catalogue). In case you need to store archive on a bad quality medium, you could protect each slice with a Parchive recovery file. (see NOTES for more information about Parchive, and how to transparently run Parchive from dar)

Slices have a base name given on the command line, which is completed by a dot, a number, a dot and the extension (dar) to form a filename. On command line you will never have to give the full file name of a slice.

    Let's take an example :
        considering the base name "joe", dar will make one or several slices during backup. Theses are files with the names joe.1.dar joe.2.dar ... joe.10.dar ... etc. If you want to extract, list, or use these backup as reference, you will only have to use the base name which is the string "joe" here.

OPTIONS

COMMANDS :

Important note: Not all system actually support long options (Solaris, FreeBSD, ...). For example --create will not be available on theses 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.

    -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 slice is asked for (no -s) the archive is produced on the standard output.

    -x, --extract [<path>/]<basename>
        extracts files from the given backup. Slices are expected to be in the current directory or in the directory given by <path>. It is also possible to use symbolic links to gather slices that are not in the same directory. Path may also point to a removable device (floppy, CD, etc.), in this case, to be able to mount/unmount the device, you must not launch dar from that directory. In other words, the current directory must not be that directory (see tutorial for details).

    -l, --list [<path>/]<basename>
        lists the contents of the given backup. In general dar will only require the first and the last slice of the archive.

    -t, --test [<path>/]<basename>
        checks the backup integrity. Even without compression, dar is able to detect at least one error by data file, thanks to a 16 bits CRC recorded in the catalogue. If one error occurred in file's data stored the archive, dar will report it in 100% of all cases. If two error occurred, dar will see them in 93,8% of all cases. If three error occurred, dar will see them in 100% of all cases. If four errors occurred, dar will see them in 90.6% of all cases, etc.

    -d, --diff [<path>/]<basename>
        compares saved files in the backup with those in the filesystem.

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

    -h, --help
        displays help usage.

    -V, --version
        displays version information.

GENERAL OPTIONS:

    -v, --verbose
        verbose output

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

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

    -w, --no-warn
        Do not warn before overwriting file or slice. By default (no -n and no -w) overwriting is allowed but a warning is issued before proceeding. This option may receive 'a' as argument:

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

    -R, --fs-root <path>
        The path points to the directory tree containing all the files that will be enrolled in the operation (backup or restoration). 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).

    -X, --exclude <mask>
        The mask is a string with wild cards (like * and ?) 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.

    -I, --include <mask>
        The mask is applied to filenames which are not directories. 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.

    -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 -Roption) is considered. Note that <path> may contains wild-cards like * or ? see glob(7) man page for more informations.

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

    File selection in brief:

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

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

        the normal method is the default:
            A directory is elected for operation if no -P option excludes it. If at least one -g option is given one command line, one -g option must cover it, else it is not elected for operation. If a directory is not selected, no recursion is done in it (the directory is pruned). For non directories files, the same is true (P and -g 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 wild-cards).

        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 on one hand and of -P and -g in the other hand. In the ordered method the last argument take precedence on 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 (it begins by "toto") as well as "titi.txt" as well as "joe.mp3" (it 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 and -g act the same but as seen above they do not act on filename only, 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 options relatively to -P options.

        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 and -g options.

        -g option has been said to be equivalent to [list of paths]. This is true in the normal method, but false using the ordered method. Argument given in [list of paths] are usually moved after any other options, so they loose their relative position regarding -P options. In the ordered method this is annoying, thus -g option has been created to overcome this getopt() system call behavior.
    This ends the file selection explication let's continue with other options.

    -u, --no-user-EA
        Do not consider the Extended Attributes (EA) of the user namespace. By default, they are saved and restored, if the support for EA has been activated at compilation time. If not, this option is forced internally (you need not specify it).

    -U, --no-system-EA
        Do not consider the EA of the root (or system) namespace. By default, they are saved and restored, if the support for EA has been activated at compilation time. If not, this option is forced internally (you need not specify it).

    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.

    -i, --input <path>
        is available when reading from pipe (basename is "-" for -x, -l, -t, -d or for -A when -c or -C 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/NOTES for examples of use).

    -o, --output <path>
        is available when reading from pipe (basename is "-" for -x, -l, -t, -d or for -A when -c or -C 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/NOTES for examples of use.

    -O, --ignore-owner
        Do not consider user ID (uid) or group ID (gid), when comparing with archive of reference (-c -A) while doing a differential backup, when extracting (-x) or when comparing (-d). This is useful when dar is used by a non-privileged user. It will not consider a file has changed just because it has only the uid or gid changed, nor report a comparison mismatch if only uid or gid is different.

    -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, and at restoration time if the -r option (restore only more recent files) is used. 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).

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

        %%  will be replaced by %

        %p  will be replaced by the slice path

        %b  will be replaced by the slice basename

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

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

        %c  will be replaced by the context. Actually two possible value exist: "init" and "operation". When reading an archive for (testing, extraction, diff, listing, or while reading the archive of reference, see below the -F option), the "init" context takes place from the beginning up to the time the catalogue is retrieved. On a multiple slice archive this correspond to the first slice request and to the last slice requests. After, that point comes the "operation" context. While creating an archive, the context is always "operation".
    Several -E option can be given, given commands will then be called in the order they appear on the command line, and included files.

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

    -K, --key [[<algo>]:]<string>
        encrypt/decrypt the archive using the <algo> cypher with the <string> as pass phrase. An encrypted archive can only be read if the same pass phrase is given. Available cyphers are "blowfish" (alias "bf") for strong encryption and "scrambling" (alias "scram") for a very weak encryption. By default if no <algo> or no ':' is given, the blowfish cypher is assumed. If your password contains a column ':' you need to specify the cypher 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 cypher with the pass phrase asked at execution time.

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

    -#, --crypto-block <size>
        to be able to randomly access data in an archive, it is not encrypted globally but block by block. You can define the encryption block size thanks to this argument which default to 10240 bytes. Note that syntax used for -s option is also available here. Note also that crypto-block is stored as a 32 bits integer thus value larger than 4GB will cause an error.

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

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

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

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

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

    --alter=SI and --alter=binary can be used several times, they affect all prefix which follow even those found in file included by -B option up to the next --alter=... occurrence. Note that if in a file included by -B option an --alter=binary or --alter=SI is met, it affects all the following prefix even those outside the included files (for example in the following "-B some.dcf -s 1K" 1K may be equal to 1000 or 1024 depending on the presence of an --alter=SI or --alter=binary in the file some.dcf. By default (before any --alter=SI/binary argument has been reached), binary interpretation of suffix is done (for compatibility with older versions).

    -Q  Do not display initial warning on stderr when not launched from a terminal (for example when launched from an at job or crontab). Remains that any question to the user will be assumed a 'no' answer, which most of the time will abort the program. Important, this option cannot be used inside configuration files (see -B option), it must be present on the command line. Since version 2.2.2, giving this option on command-line also forces the non interactive mode even if dar is launched from terminal, this makes dar possible to run in background (it is recommended to then redirect the stdout and/or stderr to some files).

    -aa, --alter=atime
        when reading a filesystem, while doing a backup (-c option) or comparing (-d option) by default dar tries to be as much transparent as possible, and set back the last access time (atime) of read files and directories, as if they have not been read. But, preserving atime of read files, make their ctime to be changed (last inode change). There is no possibility to preserve both atime and ctime. If you want to overcome the default original behavior of dar and want to keep ctime unchanged, the --alter=atime is for you. Some security software rely on the ctime to be preserved, some other software rely on the atime to be preserved like leafnode NNTP caching software.

    -ac, --alter=ctime
        set back the date alteration to ctime (see --alter=atime above), this is the default behavior. The use of this switch is to override the -aa option in dar configuration files or command-line (see -B option). From -aa and -ac the one which is last parsed from command-line or included files takes the win.

    -am, --alter=mask
        set the ordered mode for mask. This affects the way -I and -X options are interpreted, as well as -g and -P options, and -Z and -Y options. It can take any place on the command-line and can be placed only once.

    -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 and -Y options.

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

    -j, --jog
        when virtual memory is exhausted, as user to make room before trying to continue. By default, when memory is exhausted dar aborts.

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

    -z[level], --gzip [level]
        compresses within slices using gzip algorithm (if not specified, no compression is performed). The compression level (an integer from 1 to 9) is optional. -z is equivalent to -z9 which is max compression/slow processing. At the opposite, 1 means less compression and faster processing.

    -y[level], --bzip2 [level]
        compresses using bzip2 algorithm. See -z above for usage details.

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

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

    -p, --pause
        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.

    -A, --ref [<path>]/<basename>
        specifies the archive to use as reference (mandatory with -C). By default no archive is used and all files are saved (in regards to -I -X -P and -g options). 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 first and the last slice are required to extract the catalogue of reference and the use of symbolic links is also possible here to gather slices that do not reside in the same directory. You can also point <path> to a floppy or any other mounted directory, because dar will pause and ask the user for required slices if they are not present.

    -D, --empty-dir
        When excluding directories either explicitly using -P option, or implicitly by giving a -g option dar does not store anything about theses. 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 theses directories (if necessary). This option has no meaning with -C and is ignored in that case.

    -Z, --exclude-compression <mask>
        Filenames covered by this mask are not compressed. It is only useful with -z or -y. 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.

    -Y, --include-compression <mask>
        Filenames covered by this mask (and not covered by -Z) are the only to be compressed. It is only available with -z no -y. 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.

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

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

    -G, --on-fly-isolate [<path>]/<basename>
        When creating a backup, perform a catalogue isolation of the resulting archive. This step is done after the backup has completed. The on-fly isolation is compressed with bzip2 (using compression level 9), and is a single sliced archive without encryption. Due to command-line exiguity, it is not possible to change compression algo, slice size or encryption scheme for the on-fly isolation. If you need a more complicated thing, either look for a GUI over libdar, or do a normal isolation (By the way it is possible to isolate an already isolated catalogue, this is equivalent to a copy, but you can add encryption, change compression, change slicing, etc.), you can also use dar_xform if you only want to change slices size (this is faster as no decompression/re-compression is done).

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

RESTORATION OPTIONS (to use with -x)

    -k, --no-deleted
        Do 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.

    -r, --recent
        restore only files that are absent or more recent than those present in filesystem. -r is useless if -n is present.

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

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

    No specific option, but all general options are available except -n and -w which are useless, as testing and comparing only read data.

LISTING OPTIONS (to use with -l)

    -T, --tar-format
        can be used to have a listing that displays the tree structure.

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

    -I and -X
        can be used to filter file to list base on their name. With -T the tree structure is not filtered unlike without -T. Note that -P and -g options are not available while listing.

    Else only -v and -b from general options are useful. Note that -v displays an archive summary first, where a lot of information about the archive can be obtained.

    displayed
        fields

        [data]
            possible values are [ ] or [Saved] or [InRef] . [ ] 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] is used when isolating a catalogue from an archive, and means the file was saved in the reference archive.

        [EA]
            possible values are " " (empty string) or [Saved] or [ ]. It Shows if Extended Attributes are present and saved ([Saved]), are present but not saved ([ ]) which means there is no change since backup of reference, or if there is no EA saved for this file (empty string).

        [compr]
            possible values are [....%] or [-----] or [ ] or [worse]. Shows if the file has been compressed and the compression rate reached ([...%]), or if the file is stored without compression ([ ] see -Y and -Z options) or if the file is not subject to compression because it is not a saved regular file ([----]), or if the file takes more space compressed than its original size ([worse]), due to compression overhead.

        permission
            see ls man page

        user
            owner of the file

        group
            group owner of the file

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

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

        filename
            The name of the file.

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

-z  must be replaced by -z 9

-y  must be replaced by -y 9

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

-H  must be replaced by -H 1

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" as member of [list of path]. In the other side, when using a non GNU getopt this time, "-z" becomes an option that always requires an argument, and thus "-z 9" is read as "-z" option with "9" as argument, while "-z9" will be rejected as a unknown option, and "-z" alone will generate an error as no argument is provided. In consequences, you need a space between the option (like "-z") and its argument (like "9"), when dar does not rely on a GNU getopt() call, which also imply you to explicitly use arguments to options listed just above.

EXIT CODES
dar exits with the following code:

0   Operation successful.

1   Syntax error on command-line.

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

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

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

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

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

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

8   the version used of dar 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 infinint) to avoid this error.

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

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

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 theses file need to be present, but if they are they are parsed AFTER any option on the command line and AFTER included files from the command line (files given to the -B option). NOTE: if $HOME is not defined $HOME/.darrc default to /.darrc (at the root of the filesystem). Else you can see conditional syntax bellow, and -N option above that leads dar to ignore the /etc/darrc and $HOME/.darrc files.

CONDITIONAL SYNTAX
configuration files (-B option, $HOME/.darrc and /etc/darrc) usually contain a simple list of command-line arguments, split or not over several lines, and eventually mixed with comments (see -B option for more). But, you can also use make-like targets to ask for a particular set of commands to be used in certain conditions. A condition takes the form of reserved word immediately followed by a colon ':'. This word + colon must stand alone on its line, eventually with spaces or tabs beside it. The available conditions are:

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

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

listing: (or list:)
    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

all:
    in any case

default:
    if no -c, -d, -x, -t, -C or -l 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.

SEE ALSO
dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1) see also TUTORIAL and NOTES files in the documentation.

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

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

AUTHOR
http://dar.linux.free.fr/
Denis Corbin (dar.linux@free.fr)
France
Europe