BACKUPST --- A backup program for the Atari ST F.J.R. Appelman, University of Utrecht, 3D Computer Vision Research Group, The Netherlands. email: fred@cv.ruu.nl 1. Info BackupST is a backup program for the Atari-ST. BackupST writes the hard disk data to floppy disks. BackupST has 3 modes in which it works; creation (backup), listing or extraction (restore). The floppies written by BackupST are in a proprietary format, and are NOT readable by GEMDOS. You need BackupST again to read the floppies. 2. STARTING THE PROGRAM BackupST can be started by double clicking on the application from the desktop, and typing the parameters in the presented box. Note: BackupST is NOT case sensitive; this because the OS converts all input from the desktop to uppercase before passing it to the application. After execution BackupST will wait for a keypress before it returns to the desktop. BackupST will also work from a command interpretator like the Craft shell. If you set the environment variable BACKUPSTPAUSE=NO BackupST wil not wait for a keypress after execution. The program can also be started by the GEM interface program bfront. This document does NOT describe the bfront program. 3. CREATION (BACKUP) MODE The ``-c'' flag sets BackupST in Creation mode. backupst -c [options] files Files can be: 1. Plain files. 2. directories 3. disks 4. regular expressions Slashes (/) are automatically converted to backslashes (\). Relative addressing is supported. Regular expressions are full regular expressions, not the GEMDOS regular expressions. The options supported in creation mode in alphabetical order are: -b0 Set the archived bit. ``Setting'' the archived bit is a little bit symbolic since TOS 1.4 is introduced. The introduction of TOS 1.4 inverted the meaning of the archived bit. Before TOS 1.4 the bit was set to ``1'' to indicate the file was archived. Before TOS 1.4 this bit was automatically cleared by the OS once the file was changed. Since the introduction of TOS 1.4 this bit is set to ``0'' to indicate the file is archived. In TOS 1.4 this bit is set to ``1'' by the OS if the file is changed. BackupST will automatically adjust its behavior to the present TOS version. This is a default option. -b1 Don't set the archived bit. -f0 Never format a track. If a disk I/O error occurs, BackupST is aborted with an error message. -f1 Format every track before trying to write on the track. After formatting of the track the behavior of BackupST is as if the -f2 option was typed. -f2 Format a track if an I/O error occurs. After formatting of this track, writing to the track is tried again. Up to 5 retries will take place. If the retries have no effect, BackupST is aborted. When every track needs reformatting, it turns out to be a time consuming proces. If more than 3 tracks need formatting on a particular side of a disk the remaining tracks on that side will be formatted before trying to write on that side. This is a default option. -l0 Incremental backup. Only files which have been changed since the last backup are stored on disk. -l1 Full backup. All files specified are stored. This is a default option. -r Read file names from stdin. You can either type the filenames by hand, or put BackupST in a pipeline. find c: '*.c' | backupst -cr -u0 Don't verify after write. This is a default option. -u1 Verify after write. The following options are available in all modes: -da Use drive A as the backup drive. This is a default option. -db Use drive B as the backup drive -s1 Use single sided floppies -s2 Use double sided floppies. This is a default option. -v Verbose mode. This option has no use to the normal user, only to the programmer. You are not advised to use this option, it will slow down the backup. -j# No of sectors per track. The only valid numbers are 9 and 10. If you restore or list an archive, this option may be supplied but is overruled by the values stored in the archive info. 9 sectors per track is the default value. -k# No of tracks per side. The only valid numbers are 80-84. If you restore or list an archive, this option may be supplied but is overruled by the values stored in the archive info. 80 tracks per sector is the default value. After writing the ``written and archived'' flag on the hard disk is set. So if you make an incremental backup, BackupST knows which files are changed, and which are not. This ``written and archived'' flag is automatically reset by GEMDOS if the file is changed. (see also the description of the ``-b0'' flag) BackupST first checks all the arguments entered. If one file could not be found, an error message is printed. First all the files are written to floppy. The space used by the archive index is known and skipped on the first disk. If all data is written to disk, you are asked to reinstall disk #1. The archive index is now written to disk. This ``strange'' aproach is taken, because future versions of BackupST will compress the data, when it is written to disk. If data is compressed, BackupST will not know where exactly the file data is written on the floppies, and this information is stored in the archive index. A backup archive index is stored behind the data. This backup archive index is used by the ``-y'' option (See extract mode). Examples: backupst -c c: # Backup disk C: backupst -c . # Backup the current directory backupst -cl0das1 c: d: # Store all changed files on disk # C: and disk D: on floppy A:, and use # single sided floppies. backupst -c c:/bin # Store all file in the # directory c:/bin backupst -c *.[ch] # Store all C-files and H-files in the # current directory Note1: If you use regular expressions, be aware of the fact that most shells already expand regular expression patterns. If you want to use the regular expression, quote the regular pattern, e.g. backupst -c '*.[ch]' Note2: It's strongly advised you use the FOLDRxxx program, because the 40-folder bug is still present. 4. LIST MODE The ``-t'' flag sets the program in List mode. backupst -t [options] The List mode does not have special options. Only the general options apply. The following options are available in all modes: -da Use drive A as the backup drive. This is a default option. -db Use drive B as the backup drive -s1 Use single sided floppies -s2 Use double sided floppies. This is a default option. -v Verbose mode. This option has no use to the normal user, only to the programmer. You are not advised to use this option, it will slow down the backup. -j# No of sectors per track. The only valid numbers are 9 and 10. If you restore or list an archive, this option may be supplied but is overruled by the values stored in the archive info. 9 sectors per track is the default value. -k# No of tracks per side. The only valid numbers are 80-84. If you restore or list an archive, this option may be supplied but is overruled by the values stored in the archive info. 80 tracks per sector is the default value. BackupST will list all the data found in the archive. If BackupST is functioning in list mode, the data listed will be piped through more. After every full page of data, you must press a key to see the next page full of data. 5. EXTRACT MODE The ``-x'' flag sets the program in Extract mode. backupst -x [options] The options supported in extract mode are: -h path Set root of restore path to ``path''. If this option is used, BackupST will not write back the data at the position it was originally stored. Suppose you have stored a directory named ``c:/bin''. If you restore the data by using the command backupst -xh d:/tmp the data will be stored in the directory d:/tmp/bin. The directory structure is still maintained. -o0 Restore the original creation date. After writing to the file to harddisk, the creation date is set to ``today''. With this option the creation date is reset to the original date. This is a default option. -o1 Set creation date at ``today''. (See -o0) -i Interactive mode. After reading the archive index BackupST will go into interative mode. The following command are available: ls [directory] dir [directory] This command will list the contents of a directory. If you don't specify a directory, the current directory is listed by instead. By default, no files are extracted in interactive mode. Only the files specifically ``added'' (see command add) by the user are extracted. Files to be extracted are marked by a ``+''. Directories are marked by a ``\''. Directories are never marked by a ``+'', only the contents of a directory is. If you list the contents of a directory, you see the contents of a fictive disk. There is absolute no relation with the current contents of the hard disk. This so fictive disk has a root directory under which all disks are mounted. If you type ``ls'' at the root level you probably only see the volume label(s) of the disks you have stored in this archive. If only one ``disk'' is available, an automatic ``cd disk'' will be done when the program is started. ll [directory] The ``ll'' command will make a long directory listing. (see ls) quit stop exit This will abort the program without extracting the marked files. help [command] h [command] This command gives a list of all commands available. If an argument is given, an explanation of this command is given. cd [directory] chdir [directory] Change directory to ``directory''. If no argument is given, the new directory is the root directory of the ramdirectory. add [files] Add files to the list of files to be extracted. If the argument is a directory, all files in this directory are added to the list. Regular expressions are also valid. Added files are marked by a ``+'' in front of the filename in a ``ls'' command. (see ``ls'') rm [files] Opposite of add command. Same syntax. extract retrieve go Retrieve all marked files from the archive. -w Overwrite existent files silently. Normally BackupST will not overwrite an existing file without asking permission to do so. If you give the ``-w'' argument, will overwrite all files without asking. -y Same as ``-x'', only instead of using the main archive index, an attempt is made to read the backup archive index from disk. This mode is slow (and not thoroughly tested), and scans the disk for the backup archive index. The backup archive index is always written at the end of the archive. If you use this option, you will be asked to install the the disk on which you expect the backup archive is written. If the backup archive is not broken into two parts, this is the last disk of the archive. The disk# the backup archive is written on, is reported during the creation of the archive. If you have a small archive which fits on a single disk, the main archive info, which is written before the archive will be skipped in the search for the backup archive info. -z0 Never create subdirs. This means that all the files are restored at the root disk of the ``original'' disk the files were located on. This command is usually used in conjuction with the ``-h'' flag. For example the command backupst -xz0 -h d:/tmp will restore all the files in the directory d:/tmp without creating the subdirectories in d:/tmp. If needed the directory d:/tmp will be created. -z1 Create subdirs if needed. This is the default mode of the program. The following options are available in all modes: -da Use drive A as the backup drive. This is a default option. -db Use drive B as the backup drive -s1 Use single sided floppies -s2 Use double sided floppies. This is a default option. -v Verbose mode. This option has no use to the normal user, only to the programmer. You are not advised to use this option, it will slow down the backup. -j# No of sectors per track. The only valid numbers are 9 and 10. If you restore or list an archive, this option may be supplied but is overruled by the values stored in the archive info. 9 sectors per track is the default value. -k# No of tracks per side. The only valid numbers are 80-84. If you restore or list an archive, this option may be supplied but is overruled by the values stored in the archive info. 80 tracks per sector is the default value. If BackupST in extract mode is not started in interactive mode, all files in the archive will be extracted. If BackupST is started in interactive mode, no file is extracted unless you specifically tell BackupST to do so. 6. Remarks I probably forgot a lot in this documentation. If you have any further questions or wishes for the program please let me know. I can be reached at the Atari bulletin board or by email. BackupST does not work properly with Turbo--ST. (The software blitter) BackupST only uses regular library calls, and does not effect any vectors. The only low level I/O BackupST uses are some BIOS calls for screen output, and keyboard input. Some of the options are not so logical. The next version should support options like -tracks 80 instead of -k 80 Fortunally when using the GEM frontend bfront, you don't have to remember the options.