home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / diskutil / dbackup / dbackup.man next >
Text File  |  1993-08-03  |  15KB  |  291 lines
  1. NAME
  2.     dbackup - a backup program for people with removable hard disks
  3.  
  4. SYNOPSIS
  5.     dbackup [options] [source] [destination]
  6.     dbackup [-fhktvy]  [-[o|x] <suffixes>]              [source] <destination>
  7.     dbackup [-l <format>] [-fhvy] [-[o|x] <suffixes>]   [source]
  8.     dbackup [-a <utility> <line>] [-r <size>] [-efhkvy] [source] <destination>
  9.     dbackup [-[c|s|m]fhvy] [-[o|x] <suffixes>]          [source]
  10.     dbackup [-b <mode>]
  11.  
  12. DESCRIPTION
  13.     dbackup is a program primarily targetted at people who have relatively
  14.     large removable medias. Normally, a backup program is often dedicated for
  15.     a specific removable media which, in face of evolution, at some time from
  16.     the point of design and creation cannot support a new media. What I'm
  17.     particulary refering to is, of course, backup programs relying totally on
  18.     floppy disks. Since this was one of the objectives with this project, I
  19.     have tried to eliminate any such dependencies and it should work on any
  20.     media that I know of. It has been tried with mixes of hard disks,
  21.     floppies, and a 10 Mbyte removable floppy disk unit (a Supra FD-10 based
  22.     on a Konica mechanism). In respect with this specification, this program
  23.     now have many similarites to simple copy statements found in most shells
  24.     and command line interpreters, indeed it does work best if called from
  25.     such an environment, but it may be used from the GEM desktop without
  26.     problems.
  27.  
  28.     As seen above in the synopsis there is 4 versions of the command line,
  29.     each of which is a derivate of the first general synopsis. The 4 versions
  30.     are shown since, depending upon which options are chosen, some arguments
  31.     are required to be specified, most notably the requirement of the {source}
  32.     and {destination} arguments wary. It should also be noted that limited
  33.     checking is performed on the mixes of options - so care should be taken
  34.     not to specify contradictory options.
  35.  
  36.     In the synopsis {source} specify where the directories and files to backup
  37.     are located and {destination} specify where files, which match backup
  38.     criteria, are to be copied to. If copying is to be done, during a backup
  39.     session, a check is always made to ensure that neither of these arguments
  40.     are equal as well as throughout the session. This means that {destination}
  41.     may be a sub-directory of the {source} directory and that this program
  42.     will not hang due to an endless copying loop.
  43.  
  44.     The default mode of this program is incremental backup, ie. only files
  45.     which has been written match backup criteria. For this purpose the state
  46.     of the "archive" flag is checked upon and if set files are copied. A flag
  47.     is also available if a full backup is desired.
  48.  
  49. OPTIONS
  50.     -a <utility> <line>
  51.         backup files via an archive utility (see ARCHIVE UTILITIES)
  52.         This option also needs two additional arguments, {utility, line}:
  53.         utility     is the filename of the archive utility to be used
  54.         line        is the format of the command line
  55.     -b <mode>
  56.         batch mode, in this mode it tries to find a definition of what is to
  57.         be done in this mode in a file called dbackup.inf
  58.         (see below for a description on how to make definition)
  59.     -c [source]
  60.         clear archive flag status on all files without copying files.
  61.         It does not need a {destination} argument.
  62.     -e
  63.         use extended command lines to get higher performance when calling
  64.         archive utilities
  65.     -h
  66.         hold screen after backup, Primarily useful when called from the GEM
  67.         desktop.
  68.     -f
  69.         full backup, ignores the archive flag and copies everything
  70.     -k
  71.         keep archive flag status on source files
  72.     -l <format>
  73.         A list is produced of files to backup. The list format is specified
  74.         using the compulsory {format} (see LIST FORMAT) argument. The list is
  75.         sent to a file in the current working directory, called "dbackup.xxx".
  76.         It does not need a {destination} argument.
  77.     -m [source]
  78.         mark files for backup (ie. set archive flag on all files)
  79.         It does not need a {destination} argument.
  80.     -o <suffixes>
  81.         copy only files which have any of the defined suffixes. The suffixes
  82.         to be copied is specified by {suffixes}. If the list is started with a
  83.         dot ("."), files which do not have a suffix is also copied. Suffixes
  84.         in the list are delimited by dots eg. bak.tmp would copy the files
  85.         ending with ".bak" or ".tmp".
  86.     -r <size>
  87.         This option is only useful when the "-a" option has been specified.
  88.         The argument {size} (Kbytes) specifies how large an archive may
  89.         become. Any files larger than the specified size will be skipped, so
  90.         the algorithms do not try to estimate the compression rate, but are
  91.         rather conservative in their assumptions. Also, it assumes that an
  92.         archive may be duplicated on the destination drive, so it may be that
  93.         you end up with archives 50% smaller if free space on the destination
  94.         media is scarce. The algorithm, being conservative, in this way
  95.         ensures that no "out of memory" problems occurs and that archives
  96.         won't become larger than the specified size, provided that, if for
  97.         instance compression is performed, an archived file is not larger than
  98.         it was originally. Normally archived files will be significantly
  99.         smaller.
  100.     -s [source]
  101.         This gives you a report on how much memory is needed in order to
  102.         perform a backup. It does not need a {destination} argument.
  103.     -t
  104.         Normally files copied to the destination media will inherit the date &
  105.         time stamp from the original. This option overrides this by stamping
  106.         files with the date & time when the backup was invoked.
  107.     -v
  108.         verbose mode, normally progress reporting will overwrite itself, but
  109.         with this option it will scroll for every sub-directory found in the
  110.         source path as well as inform you of the free internal memory left in
  111.         your machine, which is useful if you suspect that an archive utility
  112.         is stealing memory which might cause the machine to hang if a large
  113.         filesystem is being searched.
  114.     -x <suffixes>
  115.         This option will exclude suffixes specified by the argument
  116.         {suffixes}. If the list is begun with a dot ("."), files which do not
  117.         have a suffix will also be excluded. Suffixes in this list are
  118.         delimited by dots eg. bak.tmp would exclude files foo.bak and foo.tmp
  119.     -y
  120.         backup root only, skip sub-directories
  121.  
  122. LIST FORMAT
  123.     The {format} argument used whenever the "-l" option is specified defines
  124.     what the list is to be composed by:
  125.  
  126.     a   file attributes     (4 character number)
  127.     d   file modify date    (6 characters eg. 910730)
  128.     f   filename            (path + node + suffix)
  129.     n   node                (node + suffix excluding path)
  130.     p   path                (path to file)
  131.     s   size of file        (number)
  132.     t   file modify time    (6 characters eg. 235700)
  133.     u   unix modify time    (seconds since 1 Jan 1970)
  134.     x   default list        (same as -f)
  135.  
  136. ARCHIVE UTILITIES
  137.     When using the Archive utility option you have to specify the filename of
  138.     the archive utility, with the {utility} argument. You also have to specify
  139.     the way dbackup should call the archive utility, which is specified with
  140.     the {line} argument. When specifying this tilde "~" is used as a special
  141.     formating sequence, which is listed below:
  142.         ~a<xxx>
  143.             expands to the runtime archive name with a suffix defined by {xxx}
  144.             eg. "~alzh" would expand to an archive filename with a suffix
  145.             ".LZH". {xxx} must not contain a leading dot.
  146.         ~f  expands to the files to be backup:ed
  147.         ~~  expands to a single tilde (~)
  148.  
  149.     Please note that the {line} argument must be a single one which means that
  150.     if it contains spaces, the argument must be within quotes.
  151.  
  152.     Arhive filenames names will be in the form:
  153.         DBAK????.xxx
  154.     where ???? denote a decimal sequence number. The sequence number will
  155.     usually starts at 0001 or the next sequence number found in the
  156.     corresponding sub-directory on the destination media of the source
  157.     sub-directory.
  158.  
  159.     Normally when an archive utility error occurs, dbackup will report that
  160.     files have been skipped due to an archive error and the archive flag of
  161.     these files will be untouched. If such an error occurs it is necessary to
  162.     run dbackup again, or otherwise the backup will not be complete.
  163.  
  164.     Since some archive utilities may introduce errors in a previous archive
  165.     when an error occurs when it is trying to add files, I decided that if you
  166.     had instructed dbackup to do a FULL BACKUP the sequence number will be
  167.     increased between every call to the archive utility. This means that this
  168.     problem will not occur during such sessions, but they still can happen if
  169.     you're doing INCREMENTAL BACKUP.
  170.  
  171.     Below I list some {line} arguments for some of the common archive
  172.     utilities in use:
  173.         zoo   V2.1:     "ah: ~azoo ~f"
  174.         lharc V2.01b:   "a -a+ ~alzh ~f"
  175.  
  176.     Since ARC doesn't like hidden or system files it is not possible to use
  177.     this utility. This problem also exists with some versions of LHarc. I also
  178.     recommend users of LHarc V2.01b to restrict sizes of archives to below
  179.     800Kbytes or so, because when I was testing this utility with dbackup I
  180.     found that LHarc V2.01b suddenly doubled the size of an archive when it
  181.     reached the 1Mbyte mark. When using dbackup with "-r720", though, I did
  182.     not encounter this problem.
  183.  
  184.     Warning! Please ensure that the partition which your archiver use as a
  185.              temporary storage have enough memory free to hold the temporary
  186.              files - otherwise the archiver may go nuts!
  187.  
  188. INFO FILE DESCRIPTION
  189.     You can instead of supplying all the options to dbackup make a file called
  190.     "dbackup.inf" which defines what to do. It is possible to define any number
  191.     of operating modes this way and it is quite a lot easier, especially if
  192.     you run dbackup from the desktop or from a chaotic shell, to use dbackup
  193.     with such a definition. Modes are invoked by using the command line switch
  194.     "-b". Below is a description of what to put in the info file:
  195.  
  196.     Definition:         Description:
  197.     mode=<name>         user-defined name by which you invoke this entry   (-b)
  198.     opmode=<name>       name should be one of the following below:
  199.                 normal  normal mode (copy from source to destination)
  200.                         (destination directory must be defined)
  201.                 size    report size that a backup will take                (-s)
  202.                 clear   clear archive flag                                 (-c)
  203.                 mark    set archive flag on files                          (-m)
  204.                 list    list files which have the archive flag set         (-l)
  205.                 arc     use an archive utility when doing a backup         (-a)
  206.                         (destination, arcutil and arcline must be defined)
  207.     source=<dir>        defines source directory (can be omitted)
  208.     destination=<dir>   destination directory (normal and arc opmodes)
  209.     arcutil=<name>      name of archive utility to use                     (-a)
  210.     arcline=<line>      line to send to archive utility                    (-a)
  211.     arcxargs=           archive utility can handle extended command lines  (-e)
  212.     restrict=<size>     defines maximum size of archives                   (-r)
  213.     list=<format>       list format to use                                 (-l)
  214.     fullbackup=         backup all files                                   (-f)
  215.     keepstatus=         do not clear archive flag after backup             (-k)
  216.     holdscreen=         hold screen before exiting                         (-h)
  217.     timefiles=          set the time on destination copies                 (-t)
  218.     verbose=            verbose mode                                       (-v)
  219.     rootonly=           backup root only, skip sub-directories             (-y)
  220.     copyonly=<suffixes> copy only defined suffixes                         (-o)
  221.     skip=<suffixes>     skip defined suffixes                              (-x)
  222.  
  223.     Everything after the definition "mode" describes what to do for that
  224.     particular mode until dbackup finds a new "mode" definition (ie. modes are
  225.     separated with the "mode" definition).
  226.  
  227.     Please note that a valid definition must have a '=' after its keyword and
  228.     that no spaces should come after the '=' if a definition should follow.
  229.     Comments can be added after semi-colons (';')
  230.  
  231. INFO FILE EXAMPLES
  232.  
  233.     Below is an example of a "dbackup.inf" file:
  234.  
  235.     mode=fsize      ; get size report for file size backup
  236.     opmode=size
  237.     source=c:\
  238.     fullbackup=
  239.  
  240.     mode=full       ; full backup
  241.     opmode=normal
  242.     source=c:\
  243.     destination=h:\c
  244.     fullbackup=
  245.  
  246.     mode=phase1
  247.     opmode=arc
  248.     source=c:\
  249.     destination=h:\c
  250.     arcutil=c:\bin\zoo.ttp
  251.     arcline="ah: ~azoo ~f"
  252.     arcxargs=
  253.     skip=zoo.zip.arc.lzh.arj.z.bak  ; no use trying to compress the compressed
  254.  
  255.     mode=phase2
  256.     opmode=normal
  257.     source=c:\
  258.     destination=h:\c
  259.     copyonly=zoo.zip.arc.lzh.arj.z  ; now do a normal copy of the compressed
  260.  
  261. RESTRICTED LICENCE
  262.     See the "LICENCE" file for details
  263.  
  264. BUGS
  265.     When using dbackup to copy files it doesn't try to copy as much as
  266.     possible to a disk before it asks the user to swap disks, which means that
  267.     you probably have to cycle through disks whenever prompted to swap disks.
  268.     Users who want to store backups on 720 Kbyte disks are therefore
  269.     recommended to use a dedicated floppy disk backup program eg. Turtle.
  270.     This problem is not present when using the "-a" option, though.
  271.  
  272.     If you plan to use this program with the "-a" option I recommend that you
  273.     use "-x" to exclude all files with suffixes known to indicate compressed
  274.     archives ie. ".ARC", ".LZH" etc and with a second pass use the "-o" with
  275.     the same list to copy the files. This will speedup the backup process
  276.     considerably! Also, when about to do a FULL BACKUP, it is probably best to
  277.     "-m" mark source files before backing them up so that if a fatal error
  278.     occurs you can simply re-start the process, otherwise it would be rather
  279.     difficult to know which files were archived and which were not.
  280.  
  281.     When using the batch mode, the "mode" keyword must be written in lower-case
  282.     whereas all other keywords can be mixed upper-/lower-case.
  283.  
  284. AUTHOR
  285.     Andrew Olausson, Gothenburg, Sweden
  286.     FIDONET:    2:203/203.2
  287.     INTERNET:   dxper@dtek.chalmers.se
  288.     INTERNET:   pa-ola@proxxi.se
  289.  
  290.  
  291.