\scrollmode
\documentstyle[11pt]{article}

\setlength{\topmargin}{0cm}
\setlength{\textheight}{21cm}
\setlength{\oddsidemargin}{0.5cm}
\setlength{\evensidemargin}{0.5cm}
\setlength{\textwidth}{15cm}
\setlength{\parindent}{0cm}
\pagestyle{headings}

\newcommand{\note}[2]{\begin{description} \item{\sl #1:}{\\#2}\end{description}}
\newcommand{\bsl}{$\backslash$}
\newcommand{\bup}{{\tt Backup\-ST}}
\newcommand{\bai}{{\it archive index}}

\title{BACKUPST --- A backup program for the Atari ST}
\author{
	F.J.R. Appelman,\\
	University of Utrecht,\\
	3D Computer Vision Research Group,\\
	The Netherlands. \\
	email: fred@cv.ruu.nl
	}
	
\begin{document}
\maketitle

\section{Info}
	\bup\ is a backup program for the Atari-ST. \bup\ writes the 
	hard disk data to floppy disks. \bup\ has 3 modes in which it 
	works; creation (backup), listing or extraction (restore).
	
	The floppies written by \bup\ are in a proprietary format, and 
	are NOT readable by {\tt GEMDOS}. You need \bup\ again to read 
	the floppies.

\section{STARTING THE PROGRAM}
	\bup\ can be started by double clicking on the application 
	from the desktop, and typing the parameters in the presented 
	box. 

	\note{Note}
	{
		\bup\ is NOT {\it case sensitive}; this because the 
		{\tt OS} converts all input from the desktop to 
		uppercase before passing it to the application.
	}
	
	After execution \bup\ will wait for a keypress before it 
	returns to the desktop. \bup\ will also work from a command 
	interpretator like the {\tt Craft} shell. If you set the 
	environment variable
	
	\begin{quote}
		{\tt BACKUPSTPAUSE=NO}
	\end{quote}
	
	\bup\ wil not wait for a keypress after execution.
	The program can also be started by the {\tt GEM} interface 
	program {\it bfront}. This document does NOT describe the 
	{\it bfront} program.
 
\section{CREATION (BACKUP) MODE}
	The ``-c'' flag sets \bup\ in Creation mode. 
	\begin{quote}
		backupst -c [options] files
	\end{quote}
	
	Files can be:
	\begin{enumerate}
		\item Plain files. 
		\item directories
		\item disks
		\item regular expressions
	\end{enumerate}
	
	Slashes (/) are automatically converted to backslashes (\bsl). 
	Relative addressing is supported.
	Regular expressions are full regular expressions, not the {\tt 
	GEMDOS} regular expressions.
	
	The options supported in creation mode in alphabetical order 
	are:
	\begin{description}
	
	\item{-b0}
		Set the archived bit. ``Setting'' the archived bit is a 
		little bit symbolic since {\tt TOS} 1.4 is introduced. 
		The introduction of {\tt TOS} 1.4 inverted the meaning 
		of the archived bit. Before {\tt TOS} 1.4 the bit was 
		set to ``1'' to indicate the file was archived. Before 
		{\tt TOS} 1.4 this bit was automatically cleared by 
		the {\tt OS} once the file was changed. Since the 
		introduction of {\tt TOS} 1.4 this bit is set to ``0'' 
		to indicate the file is archived. In {\tt TOS} 1.4 
		this bit is set to ``1'' by the {\tt OS} if the file is 
		changed. \bup\ will automatically adjust its behavior 
		to the present {\tt TOS} version. This is a default 
		option.
	\item{-b1}
		Don't set the archived bit.
	\item{-f0}
		Never format a track. If a disk {\tt I/O} error 
		occurs, \bup\ is aborted with an error 
		message.
	\item{-f1}
		Format every track before trying to write on the track.
		After formatting of the track the behavior of \bup\ is 
		as if the -f2 option was typed. 
	\item{-f2}
		Format a track if an {\tt 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, \bup\ 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.
	\item{-l0} 
		Incremental backup. Only files which have been 
		changed since the last backup are stored on disk.
	\item{-l1}
		Full backup. All files specified are stored. This is
		a default option.
	\item{-r}
		Read file names from stdin. You can either type the
		filenames by hand, or put \bup\ in a pipeline.
		\begin{quote}
			find c: '*.c' | backupst -cr
		\end{quote}
	\item{-u0}
		Don't verify after write. This is a default option.
	\item{-u1}
		Verify after write.
	\end{description}
	
	The following options are available in all modes:
        \begin{description}
        \item{-da}
        	Use drive A as the backup drive. This is a default option.
	\item{-db}
		Use drive B as the backup drive
	\item{-s1}
		Use single sided floppies
	\item{-s2}
		Use double sided floppies. This is a default option.
	\item{-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.
	\item{-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.
	\item{-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.
	\end{description}
	
	After writing the ``written and archived'' flag on the hard disk 
	is set. So if you make an incremental backup, \bup\ 
	knows which files are changed, and which are not. This 
	``written and archived'' flag is automatically reset by {\tt 
	GEMDOS} if the file is changed. (see also the description of 
	the ``-b0'' flag)

	\bup\ 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 \bai\ is 
	known and skipped on the first disk. If all data is written to 
	disk, you are asked to reinstall disk \#1. The \bai\ is now 
	written to disk. This ``strange'' aproach is taken, because 
	future versions of \bup\ will compress the data, when it is 
	written to disk. If data is compressed, \bup\ will not know 
	where exactly the file data is written on the floppies, and 
	this information is stored in the \bai. A backup \bai\ is 
	stored behind the data. This backup \bai\ is used by the ``-y'' 
	option (See extract mode).
	
	\note{Examples}
	{
		\begin{tabular}{l|l}
		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
		\end{tabular}
	}
	\note{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.
		\begin{quote}
			backupst -c '*.[ch]'
		\end{quote}
	}
	
	\note{Note2}
	{
		It's strongly advised you use the FOLDRxxx program,
		because the 40-folder bug is still present.
	}
	

\section{LIST MODE}
	The ``-t'' flag sets the program in List mode. 
	\begin{quote}
		backupst -t [options]
	\end{quote}
       
	The List mode does not have special options. Only the general 
	options apply.
	
	The following options are available in all modes:
	\begin{description}
        \item{-da}
        	Use drive A as the backup drive. This is a default option.
	\item{-db}
		Use drive B as the backup drive
	\item{-s1}
		Use single sided floppies
	\item{-s2}
		Use double sided floppies. This is a default option.
	\item{-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.
	\item{-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.
	\item{-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.
	\end{description}

	\bup\ will list all the data found in the archive. If 
	\bup\ 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.

\section{EXTRACT MODE}
	The ``-x'' flag sets the program in Extract mode. 
	\begin{quote}
		backupst -x [options]
	\end{quote}

	The options supported in extract mode are:
	\begin{description}
	\item{-h path}\\
		Set root of restore path to ``path''. If this option 
		is used, \bup\ 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 
		\begin{quote}
			backupst -xh d:/tmp
		\end{quote}
		the data will be stored in the directory d:/tmp/bin. 
		The directory structure is still maintained.
	\item{-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.
	\item{-o1}
		Set creation date at ``today''. (See -o0)
	\item{-i}
		Interactive mode. After reading the \bai\ \bup\ will 
		go into interative mode. The following command are 
		available:
		\begin{description}
		\item{ls [directory]}
		\item{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 ``\bsl''. 
			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.
		\item{ll [directory]}\\
			The ``ll'' command will make a long directory 
			listing. (see ls)
		\item{quit}
		\item{stop}
		\item{exit}\\
			This will abort the program without extracting 
			the marked files.
		\item{help [command]}
		\item{h [command]}\\
			This command gives a list of all commands 
			available. If an argument is given, an 
			explanation of this command is given.
		\item{cd [directory]}
		\item{chdir [directory]}\\
			Change directory to ``directory''. If no 
			argument is given, the new directory is the 
			root directory of the ramdirectory.
		\item{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'')
		\item{rm [files]}\\
			Opposite of add command. Same syntax.
		\item{extract}
		\item{retrieve}
		\item{go}\\
			Retrieve all marked files from the archive.
                \end{description}
        \item{-w}
        	Overwrite existent files silently. Normally \bup\ 
		will not overwrite an existing file without asking 
		permission to do so. If you give the ``-w'' argument, 
		will overwrite all files without asking. 
	\item{-y}
		Same as ``-x'', only instead of using the main \bai, an 
		attempt is made to read the backup \bai\ from disk. 
		This mode is slow (and not thoroughly tested), and 
		scans the disk for the backup \bai. The backup \bai
		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.
	\item{-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 
		\begin{quote}
			backupst -xz0 -h d:/tmp
		\end{quote}
		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. 
	\item{-z1}
		Create subdirs if needed. This is the default mode 
		of the program.
	\end{description}

	The following options are available in all modes:
        \begin{description}
        \item{-da}
        	Use drive A as the backup drive. This is a default option.
	\item{-db}
		Use drive B as the backup drive
	\item{-s1}
		Use single sided floppies
	\item{-s2}
		Use double sided floppies. This is a default option.
	\item{-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.
	\item{-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.
	\item{-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.
	\end{description}

	If \bup\ in extract mode is not started in interactive 
	mode, all files in the archive will be extracted. If \bup\ 
	is started in interactive mode, no file is extracted unless 
	you specifically tell \bup\ to do so.
	
\section{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.
	
	\bup\ does not work properly with Turbo--ST. (The 
	software blitter) \bup\ only uses regular library 
	calls, and does not effect any vectors. The only low level 
	{\tt I/O } \bup\ uses are some {\tt BIOS} calls for 
	screen output, and keyboard input. 

	Some of the options are not so logical. The next version 
	should support options like 
	\begin{quote}
		-tracks 80
	\end{quote}
	instead of
	\begin{quote}
		-k 80
	\end{quote}
	Fortunally when using the {\tt GEM} frontend {\it bfront}, you 
	don't have to remember the options.
	
\end{document}