% Created February 6, 1993
% Copyright (C) 1993 Torsten Poulin
% Everyone is permitted to copy and distribute verbatim copies
% of this LaTeX file, but changing it is not allowed.
%
% RCS ID:
% $Id: Manual.tex,v 1.1 93/10/22 09:13:38 Torsten Rel Locker: Torsten $
%
% $Log:	Manual.tex,v $
% Revision 1.1  93/10/22  09:13:38  Torsten
% Initial revision
% 
%

\documentstyle[11pt,mymanpage]{report}

\newcommand{\TITLE}{Torsten's AmigaDOS Shell Commands}
\newcommand{\RELEASE}{Release 2$\beta$}
\newcommand{\FORMAT}{\subtitle*{FORMAT}}
\newcommand{\TEMPLATE}{\subtitle*{TEMPLATE}}
\newcommand{\PURPOSE}{\subtitle*{PURPOSE}}
\newcommand{\SPEC}{\subtitle*{SPECIFICATION}}
\newcommand{\ALSO}{\subtitle*{SEE ALSO}}
\newcommand{\EXAMPLE}{\subtitle*{EXAMPLE}}
\newcommand{\EXAMPLES}{\subtitle*{EXAMPLES}}
\newcommand{\UNIX}{\subtitle*{UNIX EQUIVALENT}}
\newcommand{\BUGS}{\subtitle*{BUGS}}

\newfont{\ssqfnt}{cmssq8}
\newfont{\ssqifnt}{cmssqi8}

\title{Torsten's AmigaDOS Shell Commands \\ User's Reference Manual}
\author{\copyright\ 1993 Torsten Poulin\thanks{Everyone is permitted
to copy and distribute verbatim copies of this document, but changing
it is not allowed.}}
\date{Revised October 22, 1993 \\ Printed \today}

\begin{document}
\maketitle
\tableofcontents
\newpage

\chapter{About the package}
\header{}{}{\em\TITLE}
\footer{\RELEASE}{\thepage}{\today}
\pagestyle{headings}

\begin{flushright}
\ssqfnt
``I said it in Hebrew --- I said it in Dutch --- \\
I said it in German and Greek: \\
But I wholly forgot (and it vexes me much) \\
That English is what you speak!'' \\
\vspace{1ex}
--- LEWIS CARROLL, {\ssqifnt The Hunting of the Snark\/} (1876)
\end{flushright}

\section{Copying}
The programs described in this manual are free software; you can
redistribute them and/or modify them under the terms of the GNU
General Public Licence as published by the Free Software Foundation;
either version 2 of the Licence, or (at your option) any later
version.

These programs are distributed in the hope that they will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public Licence for more details.

You should have received a copy of the GNU General Public Licence
along with these programs; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Except where stated otherwise, all the programs and other files
included in this distribution are Copyright \copyright 1989, 1990,
1991, 1992, 1993 Torsten Poulin.

The copyright messages in the commands can be displayed by typing the
following command:

\verb+    1> COPYRIGHT+ {\em command}

{\sc copyright} is one of the commands included in this distribution.


\section{Introduction}
I wrote the commands described in this manual simply because I felt
they would be useful to have around. They are meant to be a supplement
to the ones supplied with the operating system, not as a replacement
for them. They are generally able to read from their default input, an
ability sadly missing from the standard AmigaDOS commands making them
rather awkward to use with pipes.

At present Commodore's shell does not support pipes, but some third
party shells do. I recommend that you purchase William Hawes'
excellent WShell~2.0. It has pipes, the backtick stuff is improved,
and it also has better ARexx support, to name but a few things.

If you don't want to get a new shell or simply can't afford it, I will
suggest that you get hold of Andy Finkel's ``ShellTools'' from Fish
disk 673:
\begin{quote}
Four small useful programs. {\sc pipe} provides command line pipes,
{\sc history} allows the history to be loaded, saved, and listed, {\sc
foreach} is a fancy loop and variable expansion command, and {\sc
recorder} saves all console input and output in a file. Binary only.
\end{quote}

Actually you should get them even if you have WShell or something
equivalent, because Mr. Finkel's {\sc pipe} command addresses the
problem of the AmigaDOS commands that can't read their default input
(and really pathological cases, like {\sc sort}, that can't write to
their default output either), and his {\sc foreach} command opens a
whole new world of possibilities with shell scripts.

All the commands are `pure' and can be made resident.  If the p-flags
are not set when you recieve the package you can set them with the
{\sc protect} command.

If you have any questions or bug reports, you can send them to me at
the following address:
\begin{verse}
Torsten Poulin \\
Banebrinken 99, 2, -77 \\
DK--2400 K{\o}benhavn NV \\
Denmark \\
Phone: +45 39663111 \\
e-mail: torsten@diku.dk
\end{verse}

\section{About the source code}
The source code for the commands may look a bit unusual. The reason
for this is that I wanted the resulting executables to be both
relatively small and ``pure'', just like Commodore's, without
resorting to assembler. Therefore they are written to be linked
without any startup code and they don't use global variables, only
constants. To emphasize the lack of startup code, there are no {\tt
main()} functions. Instead each program starts with a function, that
has to be the first one, called {\tt entrypoint()} where execution
will begin. Add the built-in ANSI C string functions and the
{\tt\#pragma libcall} and {\tt\#pragma syscall} capability of SAS/C
5.10 and you end up with little programs that don't have to be linked
with anything, apart from the small linker library containing
functions common to several of the commands (except {\sc find}, which
is linked with SAS {\tt lcr.lib} and {\tt amiga.lib} because it calls
{\tt setjmp(), longjmp()}, and {\tt amiga.lib/SetRexxVar()}).

Even though the use of {\tt\#pragma}s make the source code somewhat
SAS/C specific (global library base pointers are unnecessary), it
shouldn't be too difficult to port it to other compilers like DICE or
GNU~C. Should you decide to port it, please note that the {\tt\#pragma
syscall}s have made it unnecessary for me to set the {\tt
exec.library} base pointer, {\tt SysBase}, at all.

\section{Caveat}
If you use release 2.1 (V38) or 3.x (V39) of the operating system,
please note that the commands included in this release were written
for OS 2.04 (V37). The fact that they are blissfully unaware of the
existence of the {\tt locale.library} doesn't mean that they don't
become fairly localized. This is because {\tt locale.library} patches
a number of system date and character comparison functions to match
the current locale specified by the user. This is arguably a good
thing, though it does mean that you will have to specify some
arguments, like the parameters of the {\sc since} and {\sc upto}
functions used by {\sc find}, in the currently selected language
(e.g., assuming it is Danish, `{\sc i dag}', `{\sc i g{\aa}r}', `{\sc
fremtid}', `{\sc mandag}', etc.\ for `{\sc today}', `{\sc yesterday}',
`{\sc future}', `{\sc monday}', etc.

\section{Acknowledgement}
The wording of the following manual pages owes quite a lot to various
AmigaDOS and {\sc unix} manuals.

\chapter{Command Specifications}
\header{}{}{\TITLE}
\footer{\RELEASE}{\thepage}{\today}
\pagestyle{headings}

\section{About the specifications}
In this chapter, each command is explained following a standard outline:
\begin{description}
\item[FORMAT]\mbox{}\newline
All the arguments and options the command accepts. Arguments that must
be provided are printed like {\em argument\/}. Optional arguments and
keywords are surrounded by square brackets, []. Items that can be
given once or repeated any number of times are surrounded by braces,
like \{{\em argument\/}\}. Finally, a vertical bar, $|$, is used to
separate items of which you can choose only one.

Please note that the brackets are not to be typed as part of the
command.
\item[TEMPLATE]\mbox{}\newline
A reminder of the command's format. If you type a command followed by
a question mark, the template will appear on the screen.
\item[PURPOSE]\mbox{}\newline
A brief explanation of the command's function.
\item[SPECIFICATION]\mbox{}\newline
A concise description of the command and all of its arguments.
\item[EXAMPLE(S)]\mbox{}\newline
One or more examples showing the use of the command. The command and
any screen output are indented from the main text. A generic {\tt 1>}
prompt indicates what should be typed at the shell prompt.
\item[SEE ALSO]\mbox{}\newline
A list of related commands. This can include the standard AmigaDOS
commands documented in for example ``The AmigaDOS Manual'', 3rd.
Edition, Bantam Books, 1991 and the ``Using The System Software''
manual distributed with Release 2.04.
\item[UNIX EQUIVALENT]\mbox{}\newline
Simply tells you where I got the inspiration from. It points you to
the relevant entry in the {\sc unix system v} manuals.
\end{description}

There may be other fields as well, but they are pretty
self-explanatory.

For a more complete description of how to use the templates and how to
use patterns to match file names, please refer to the aforementioned
books on AmigaDOS.
\clearpage % makes sure we get the right page# in the TOC

\begin{manpage}{(\TITLE)}{Common(V37)}{\RELEASE}
\FORMAT
COMMON [FILE1] "file1" [[FILE2] "file2"] [-1] [-2] [-3]
\TEMPLATE
FILE1/A,FILE2,-1/S,-2/S,-3/S
\PURPOSE
To select or reject lines common to two sorted files.
\SPEC
The command {\sc common} reads "file1" and "file2", which should be
ordered in the collating sequence of {\sc sort}, and produces a
three-column output: lines only in "file1"; lines only in "file2"; and
lines in both files.

Switches -1, -2, or -3 suppress printing of the corresponding column.
Thus {\sc common} -1 -2 prints only the lines common to the two files;
{\sc common} -2 -3 prints only the lines in the first file but not in
the second; {\sc common} -1 -2 -3 is a no-op.

If "file2" is not given, the default input will be used.
\ALSO
{\sc compare, prepare, sort, unique}
\UNIX
comm(BU_CMD)
\end{manpage}


\begin{manpage}{(\TITLE)}{Compare(V37)}{\RELEASE}
\FORMAT
COMPARE [[FILE1] "file"] [[FILE2] "file"]
[[SKIP1] "n"] [[SKIP2] "n"] [QUIET]
\TEMPLATE
FILE1,FILE2,SKIP1/N,SKIP2/N,QUIET/S
\PURPOSE
To perform a byte-by-byte comparison of two files.
\SPEC
{\sc compare} compares the two files given by {\sc file1} and {\sc
file2}. If only one file is given, the default input is used for the
other. It is an error if both {\sc file1} and {\sc file2} are omitted.
{\sc compare} makes no comment if the files are the same; if they
differ, it reports the byte (in both decimal and hex) and line number
at which the difference occured, or, that one file is an initial
subsequence of the other.  {\sc skip1} and {\sc skip2} are initial
decimal byte offsets into {\sc file1} and {\sc file2} respectively. If
the {\sc quiet} switch is used, {\sc compare} will print nothing for
differing files; it will set the condition flag only. {\sc quiet} does
not suppress the printing of error messages.

The condition flag, RC, is set to 0 for identical files, 5 (WARN) for
different files, and 10 (ERROR) for bogus arguments like inaccessible
files.
\EXAMPLE
If you want to express an offset in octal or hexadecimal, you can use
{\sc EVAL}:
\begin{verbatim}
    1> COMPARE Foo Bar `EVAL 0x1FE`
\end{verbatim}
\ALSO
{\sc common}
\UNIX
cmp(BU_CMD)
\end{manpage}


\begin{manpage}{(\TITLE)}{Concat(V37)}{\RELEASE}
\FORMAT
CONCAT [[FROM] \{"file|pattern"\}] [AS|TO "name"] [SORT]\\[0pt]
[VISIBLE [TABS] [EOL]]
\TEMPLATE
FROM/M,AS=TO/K,SORT/S,VISIBLE/S,TABS/S,EOL/S
\PURPOSE
To concatenate and print files.
\SPEC
{\sc concat} reads each of the specified {\sc from} files and writes
it to the destination specified by the {\sc to} option. If no {\sc
from} option is given {\sc concat} reads from its default input;
likewise if no {\sc to} option is specified it writes to its default
output.

The following switches apply to {\sc concat}.
\begin{description}
\item[{\sc sort}]\mbox{}\newline
The {\sc from} files are read in alphabetical order.  Useful when
concatenating files split with {\sc split}.
\item[{\sc visible}]\mbox{}\newline
Causes non-printing characters (with the exception of tabs and
new-lines) to be printed visibly.  Control characters are printed as
^X (control-x); the DEL character (hex 0x7d) is printed as ^?.
Non-ASCII characters (with the high bit set) are printed as M-x, where
x is the character specified by the seven low order bits.
\end{description}
When used with the {\sc visible} switch, the following switches may be
used.
\begin{description}
\item[{\sc tabs}]\mbox{}\newline
Causes tabs to be printed as ^I's.
\item[{\sc eol}]\mbox{}\newline
Causes a \$ character to be printed at the end of each line (prior to
the new-line).
\end{description}
The {\sc tabs} and {\sc eol} switches are ignored if the {\sc visible}
switch is not specified.
\ALSO
{\sc copy, join, more, split, type}
\end{manpage}


\begin{manpage}{(\TITLE)}{Copyright(V37)}{\RELEASE}
\FORMAT
COPYRIGHT [FILE] \{"file|pattern"\}
\TEMPLATE
FILE/M/A
\PURPOSE
To find and print embedded copyright messages.
\SPEC
{\sc copyright} finds embedded copyright messages in the given files.
The embedded messages have the following format:

{\tt \$COPYRIGHT:} "message string" {\tt \$}|NUL

They are terminated by either a NUL byte (0x0) or another \$
character.  Thus it is possible to output multi-line messages if you
use something like

% The next line is long
{\tt char msg[]=\dq\$COPYRIGHT: \copyright\ 19xx J. Random Hacker%
\verb+\+nThis is...\$\dq;}

in your source code. Leading spaces in the message are skipped.

It is recommended that you always use the terminating \$ character.
The NUL byte is accepted mainly to be compatible with a similar
copyright string used in software like the XFH-Handler by Kristian
Nielsen (bombadil@diku.dk).

No diagnostic is printed if a copyright message can't be found.
\ALSO
{\sc version}
\end{manpage}


\begin{manpage}{(\TITLE)}{Count(V37)}{\RELEASE}
\FORMAT
COUNT [[FROM] \{"name|pattern"\}] [LINES] [WORDS] [BYTES|CHARS]
\TEMPLATE
FROM/M,LINES/S,WORDS/S,BYTES=CHARS/S
\PURPOSE
To count lines, words, and characters.
\SPEC
{\sc count} counts lines, words, and characters in the named files, or
in the default input if no names appear.  It also keeps a total count
for all named files.  A word is a maximal string of characters
delimited by spaces, tabs, or new-lines.

The switches {\sc lines}, {\sc words}, and {\sc chars} may be used to
specify that a subset of lines, words, and characters are to be
reported.  If no switches are given {\sc count} defaults to all of
them.

When names are specified on the command line, they will be
printed along with the counts.
\end{manpage}


\begin{manpage}{(\TITLE)}{DirTree(V37)}{\RELEASE}
\FORMAT
DIRTREE [[DIR] \{"directory"\}] [NOHEAD] [FILES]
\TEMPLATE
DIR/M,NOHEAD/S,FILES/S
\PURPOSE
To show directory hierarchy trees.
\SPEC
{\sc dirtree} shows the directory hierarchy trees for each of the
specified directories or volumes. If no names are given, the current
directory is used. The {\sc nohead} switch suppresses the printing of
the header information. Files are only included in the listing, if the
{\sc files} switch is used. {\sc dirtree} will neither follow soft nor
hard links; it will, however, append {\tt <sl>} or {\tt <hl>} to their
names.

Pressing Ctrl-C aborts the directory tree listing.
\EXAMPLE
\begin{verbatim}
    1> DIRTREE ram:
    Directory tree "ram:" on Saturday 22-Feb-92

    Ram Disk
    +---Clipboards
    +---env
    |   `---sys
    |  
    `---T
\end{verbatim}
\BUGS
Soft links causes weird behaviour.
\ALSO
{\sc dir, list}
\end{manpage}


\begin{manpage}{(\TITLE)}{Find(V37)}{\RELEASE}
\FORMAT
FIND [DIR] "directory" [DEPTH] [EXPRESSION] "expression"
\TEMPLATE
DIR/A,DEPTH/S,EXPRESSION/F/A
\PURPOSE
To find files and directories.
\SPEC
{\sc find} recursively descends the directory hierarchy for
"directory" seeking files and directories that match the "expression"
written using the functions given below. In the descriptions, the
argument "n" is used as a decimal integer. {\sc gt} "n" means greater
than "n", {\sc lt} "n" means less than "n", and {\sc eq} "n", or
simply "n", means exactly "n". The {\sc depth} switch causes the
descent of the directory hierarchy to be done so that all entries in a
directory are acted on before the directory itself. The function and
operator names are not case sensitive.

The "expression" is made up of:
\begin{description}
\item[{\sc comment} "pattern"]\mbox{}\newline
True if "pattern" matches the comment attached to the current name.

\item[{\sc days [gt|lt|eq]} "n"]\mbox{}\newline
True if the file or directory has been modified in "n" days

\item[{\sc exec} "commmand"]\mbox{}\newline
True if the executed "command" returns a zero value as its return
code. A "command" line containing whitespace must either have the
whitespace escaped, or be surrounded by quotes. A command argument
\{\} is replaced by the current name (with its relative path).

\item[{\sc execok} "command"]\mbox{}\newline
As {\sc exec} except that the generated command line is printed with a
question mark, and is executed only if the user responds by typing a
{\tt y}.

\item[{\sc flags} "flags"]\mbox{}\newline
True if "flags" matches the protection bits of the current name.  The
"flags" argument is a string of letters representing the protection
bits:
\begin{description}
\item[\tt r] The file can be read.
\item[\tt w] The file can be written to.
\item[\tt e] The file is an executable program.
\item[\tt d] The file can be deleted.
\item[\tt s] The file is a script.
\item[\tt p] The file can be made resident.
\item[\tt a] The file has been archived.
\end{description}
If a letter is preceded by a `{\tt -}', it means that in order to
match, the corresponding file bit must not be set. Unspecified bits
are ignored in the comparison. Whitespace is not allowed in "flags".

\item[{\sc lformat} "fmtstring"]\mbox{}\newline
Always true; prints "fmtstring" replacing occurences of \%N with the
name of the object, \%R with its relative path, \%L with its length in
bytes (this is only useful for file type objects), and \%C with any
attached comments. To print a \% character use \%\%.

\item[{\sc name} "pattern"]\mbox{}\newline
True if "pattern" matches the current name.

\item[\sc print]\mbox{}\newline
Always true; causes the current name to be printed (with its relative
path).

\item[\sc prune]\mbox{}\newline
Always true. Has the side effect of pruning the search tree at the
current name. Necessary if the {\sc depth} switch isn't used and the
directory currently being matched is deleted.

\item[{\sc rexx} "string-file"]\mbox{}\newline
True if the ARexx "string-file" returns with a zero return code. An
Arexx string-file is a one line program given directly on the command
line. The ARexx interface supports one command: {\sc getattr} "stem.",
where "stem." (remember the trailing dot) is the name of the ARexx
stem variable the information about the current name is to be placed
in.  The resulting compound symbol will have the following nodes:
\begin{description}
\item[\sc .name]\mbox{}\newline
The current name without its path.
\item[\sc .relname]\mbox{}\newline
The current name with its relative path.
\item[\sc .fullname]\mbox{}\newline
The current name with its full path.
\item[\sc .comment]\mbox{}\newline
The optional attached comment or an empty string.
\item[\sc .type]\mbox{}\newline
The type: {\sc file, linkfile, dir, linkdir, softlink} or {\sc
unknown}.
\item[\sc .size]\mbox{}\newline
The size in bytes. Only meaningful for files.
\item[\sc .day]\mbox{}\newline
The name of the day of the last modification.
\item[\sc .date]\mbox{}\newline
The last modification date in the standard Amiga format.
\item[\sc .time]\mbox{}\newline
The last modification time in the standard Amiga format.
\item[{\sc .days, .mins,} {\rm and} {\sc .ticks}]\mbox{}\newline
The time of the last modification expressed as the number of days
since January 1, 1978, the number of minutes past midnight, and the
number of ``ticks'' past the minute.
\end{description}

\item[{\sc since} "date"]\mbox{}\newline
True if the file or directory has been modified on or after "date".
The format for "date" is either {\tt dd-mmm-yy} or one of {\sc
tomorrow, today, yesterday, monday, tuesday, wednesday, thursday,
friday, saturday,} or {\sc sunday}.

\item[{\sc size [gt|lt|eq]} "n"]\mbox{}\newline
True if the file is "n" bytes long. Always false if the current name
is not a (hard link to a) file.

\item[{\sc type} "type"]\mbox{}\newline
True if the type of the filesystem object is "type", where "type" is
one of {\sc file, linkfile, dir, linkdir}, or {\sc softlink} for file,
hard link to file, directory, hard link to directory, or soft link to
a file or directory, respectively.

\item[{\sc upto} "date"]\mbox{}\newline
True if the file or directory has been modified on or before "date".

\item[\{"expression"\}]\mbox{}\newline
True if the expression inside the braces is true.
\end{description}

The functions may be combined using the following operators:
\begin{description}
\item[\sc not]\mbox{}\newline
The negation of a function.
\item[\sc and]\mbox{}\newline
Concatenation of functions. The keyword {\sc and} is optional, as it
is implied by the juxtaposition of two functions.
\item[\sc or]\mbox{}\newline
Alternation of functions.
\end{description}

{\sc find} uses `{\tt *}' as an escape character to remove the special
meaning of characters, so to get an `{\tt *}', you will have to enter
`{\tt **}'. The special escape sequences `{\tt *N}' and `{\tt *T}'
mean the new-line and tab characters, respectively. Escaping works
everywhere in the "expression", not just inside double quotes. You can
even escape the space character: \verb+exec delete* *{*}+ gives
exactly the same result as \verb+exec +\dq\verb+delete {}+\dq.

\EXAMPLES
To remove all files ending in {\tt !} or {\tt .bak}:

\verb+    1> FIND SYS: {NAME #?! OR NAME #?.bak} EXEC +\dq\verb+DELETE {}+\dq

To find all files ending in {\tt .c} on DH0: without searching the
sub-tree starting at the directory ``{\tt user}'':
\begin{verbatim}
    1> FIND DH0: {TYPE DIR NAME user PRUNE} OR NAME #?.c PRINT
\end{verbatim}
\subtitle*{DIAGNOSTICS}
Should really be more informative.

ARexx is inaccessible: Either the ARexx interpreter ({\sc rexxmast})
isn't running or {\sc find} was unable to create its communications
port. {\sc find} will not complain about this if the {\sc rexx}
function isn't used. Thus it is possible to use {\sc find} on a system
without Arexx.
\BUGS
It may take several Ctrl-C's to halt {\sc find} when {\sc exec,
execok}, or {\sc rexx} is used.

Specifying the {\sc depth} switch is an effective way of defeating the
purpose of {\sc prune}. That may change in the future. (If you can
think of a good reason for making {\sc depth} a function, as in {\sc
unix} {\tt find}, instead of a command line switch, please send me a
post-card explaining why).
\ALSO
{\sc list, rx, search}

The section on ARexx in the ``Using The System Software'' manual.
\UNIX
find(BU_CMD)
\end{manpage}


\begin{manpage}{(\TITLE)}{Head(V37)}{\RELEASE}
\FORMAT
HEAD [[FROM] \{"file|pattern"\}] [TO "file"] [NUM|NUMBER "n"]
\TEMPLATE
FROM/M,TO/K,NUM=NUMBER/N/K
\PURPOSE
To display first few lines of specified files.
\SPEC
{\sc head} copies the first {\sc number} lines of each {\sc from} file
to the default output or the {\sc to} file if one is given. If no {\sc
from} files are given, {\sc head} copies lines from the default input.
The default number of lines is 10.

When more than one file is specified, the start of each file looks
like:
\begin{verbatim}
    ==>filename<==
\end{verbatim}
\EXAMPLE
A way to display a set of short files, identifying each one, is:
\begin{verbatim}
    1> HEAD filename1 filename2 NUMBER 9999
\end{verbatim}
\ALSO
{\sc concat, tail, type}
\UNIX
head(BU_CMD)
\end{manpage}


\begin{manpage}{(\TITLE)}{Lower(V37)}{\RELEASE}
\FORMAT
LOWER [BY "value"] [STACK "size"] [COMMAND] "command line"
\TEMPLATE
BY/K/N,STACK/K/N,COMMAND/F/A
\PURPOSE
To run a command at a nice, possibly lower, priority.
\SPEC
Since the Amiga is multitasking, it uses priority numbers to determine
the order in which current tasks should be serviced.  Normally, most
tasks have a priority of 0, and the time and instruction cycles of the
CPU are divided equally among them.

{\sc lower} executes the specified command line with the priority
lowered by "value".  If no {\sc by} option is specified a default
value of 1 is used.  If a negative value is specified the priority
will be raised instead.  The resulting priority will be between -128
and +10.  This is enforced silently.

The {\sc stack} option sets the stack size of the command to be
executed.  Default is to use the current stack size.

The "command line" is any valid shell command line; i.e. it is
possible to use redirection, aliases, resident commands etc.

{\sc lower} leaves the value of the executed command in the condition
flags RC and Result2.  Ctrl-C, D, E, and F are sent to the executed
command.
\EXAMPLE
To print the file Text at lower priority, type:
\begin{verbatim}
    1> LOWER COPY Text TO PRT:
\end{verbatim}
\ALSO
{\sc changetaskpri, stack, status}
\UNIX
nice(AS_CMD)
\end{manpage}


\begin{manpage}{(\TITLE)}{Prepare(V37)}{\RELEASE}
\FORMAT
PREPARE [[FROM] "file|pattern"] [TO "file"] [TOLOWER|TOUPPER] [HYPHEN]
\TEMPLATE
FROM/M,TO/K,TOLOWER/S,TOUPPER/S,HYPHEN/S
\PURPOSE
To extract the words of files and print them one per line.
\SPEC
{\sc prepare} extracts the words of the given files, or the default
input, and prints them, one per line, to the default output, or to the
destination specified by the {\sc to} argument. A word is a maximal
string of letters from the ISO Latin 1 character set. A compound made
with hyphens, `-', is split up into its constituent parts unless the
{\sc hyphen} switch is specified. In-word apostrophes are recognized,
so words like `doesn't' etc. are printed correctly. If the {\sc
tolower} or the {\sc toupper} switch is given, the characters are
folded to lower or upper case respectively. It is an error if both are
given.

{\sc prepare} can, for example, be used with {\sc sort} and {\sc
unique} to produce word lists.
\EXAMPLE
It is possible to make a ``poor man's'' spelling checker (should be
entered as one line):
\begin{verbatim}
    1> PIPE PREPARE foo TOLOWER | SORT IN: OUT: | UNIQUE
            | COMMON dict -1 -3
\end{verbatim}
where `{\tt foo}' is the file to be checked, and `{\tt dict}' is a
sorted dictionary of words in lower case. The words reported to the
default output are not in the dictionary, and are therefore possible
spelling mistakes. This example assumes you have Andy Finkel's {\sc
pipe} command. Use temporary files if you don't.
\end{manpage}


\begin{manpage}{(\TITLE)}{SCD(V37)}{\RELEASE}
\FORMAT
SCD [DIR] "name|pattern"
\TEMPLATE
DIR/A
\PURPOSE
To change directory in a short and convenient way.
\SPEC
{\sc scd} attemps to locate the specified directory in a lookup table.
If it cannot be found, a ``Can't find "name"'' error message is
displayed.  If there is more than one matching directory, a screen
allowing the user to select the correct one will pop up. Pressing
`{\tt s}' will move to the next name, `{\tt S}' to the previous. Press
`{\tt d}' to change to that directory, `{\tt c}' to cancel.

{\sc scd} expects its lookup table to be in {\tt ENV:SCD/Table} unless
told otherwise by the variable {\sc scdtable}. The easiest way to
create the table is with {\sc find} or {\sc list}:
\begin{verbatim}
    1> FIND dh0: TYPE DIR PRINT > ENVARC:SCD/Table
    1> FIND dh1: TYPE DIR PRINT >> ENVARC:SCD/Table

    1> LIST dh0: DIRS LFORMAT %s%s ALL TO ENVARC:SCD/Table
\end{verbatim}
If the variable {\sc scdcommand} is set to the name of a command---or
the empty string if you want to use the implicit {\sc cd} feature of
the shell---{\sc scd} will attempt to queue it for execution rather
than use its own change directory code. It is recommended that you use
this method if you use WShell (set {\sc scdcommand} to {\sc cd} or
{\sc pushcd}). In order for this to work the {\sc dos} handler
associated with the {\sc stdin} stream must support the {\sc
action_queue} command. As of release 2.04 Commodore's {\sc con:}
handler does that.

If queueing is used in a script the result may not be what you expect.
\ALSO
{\sc cd, find, list}
\end{manpage}


\begin{manpage}{(\TITLE)}{Split(V37)}{\RELEASE}
\FORMAT
SPLIT [[FROM] "file"] [TO "name"] [LINES|BYTES|PARTS "n"] [PROMPT]
\TEMPLATE
FROM,TO/K,LINES/K/N,BYTES/K/N,PARTS/K/N,PROMPT/S
\PURPOSE
To split a file into pieces.
\SPEC
{\sc split} reads "file" and writes it onto a set of output files.
The name of the first output file is "name" with aa appended, and so
on lexicographically, up to zz (a maximum of 676 files). If no "name"
is given, x is default.

The {\sc lines} argument results in "n"-line pieces, the {\sc bytes}
argument in "n"-byte pieces, and the {\sc parts} argument splits the
input file into "n" parts. Only one of the arguments {\sc lines,
bytes}, and {\sc parts} may be given. If none of them are given, {\sc
split} will default to 1000-line pieces.

If the {\sc prompt} switch is specified, the user will be prompted
before each output file is written, to make it possible to change
disks.

If no input file is given then the default input is used making it
possible to use {\sc split} as the end of a pipe-line.

It is unwise to use the {\sc parts} switch when reading from a pipe.
\EXAMPLE
If the file `myfile' is split up with a command like this:
\begin{verbatim}
    1> SPLIT myfile TO splitfile.
\end{verbatim}
it can be assembled again with the following command:
\begin{verbatim}
    1> CONCAT splitfile.?? TO newfile SORT
\end{verbatim}
\BUGS
Does not check to see if there is room for the appended letters in the
file part of "name". The length of the file part should not exceed 28
characters for {\sc ofs} and {\sc ffs} (and a lot less for the {\sc
ms-dos} file system, sigh!).
\ALSO
{\sc concat, join, type}
\end{manpage}


\begin{manpage}{(\TITLE)}{SplitName(V37)}{\RELEASE}
\FORMAT
SPLITNAME [NAME] "name" [[PATH] "var"] [[BASE] "var"]
[[EXT|EXTENSION] "var"]
\TEMPLATE
NAME/A,PATH,BASE,EXT=EXTENSION
\PURPOSE
To split a filename into its components.
\SPEC
{\sc splitname} splits "name" into its components and stores the
results in the local variables specified by the options {\sc path},
{\sc base}, and {\sc extension}.

The name {\tt foo/bar.baz.qux} will be split into ``{\tt foo/}'',
``{\tt bar.baz}'', and ``{\tt .qux}''. If you want to strip {\tt .baz}
too, you must do something like
\begin{verbatim}
    1> SPLITNAME foo/bar.baz.qux BASE mybase EXT myext
    1> SPLITNAME $mybase BASE mybase
\end{verbatim}
\ALSO
{\sc set, unset}
\end{manpage}


\begin{manpage}{(\TITLE)}{Tee(V37)}{\RELEASE}
\FORMAT
TEE [[TO] \{"file"\}] [APPEND]
\TEMPLATE
TO/M,APPEND/S
\PURPOSE
Tee is a pipe fitting.
\SPEC
{\sc tee} transcribes the default input to the default output and
makes copies in the files specified by the {\sc to} option.

The {\sc append} switch causes the output to be appended to the files rather
than overwriting them.
\end{manpage}


\begin{manpage}{(\TITLE)}{TestBits(V37)}{\RELEASE}
\FORMAT
TESTBITS [NAME] "file|directory" [FLAGS] "flags"
\TEMPLATE
NAME/A,FLAGS/A
\PURPOSE
To test whether one or more protection flags are set.
\SPEC
{\sc testbits} is used to to test the state of one or more of the
protection bits. This can be useful in scripts. The protection bits
are represented by letters:
\begin{description}
\item[\tt r] The file can be read.
\item[\tt w] The file can be written to.
\item[\tt e] The file is an executable program.
\item[\tt d] The file can be deleted.
\item[\tt s] The file is a script.
\item[\tt p] The file can be made resident.
\item[\tt a] The file has been archived.
\end{description}
If a letter is preceded by a `{\tt -}', it means that in order to
match, the corresponding file bit must {\em not\/} be set. Whitespace is
not allowed between the letters representing the bits. If the state of
all the bits given in the "flags" argument match the file's protection
bits, {\sc testbits} sets the condition flag to 5 (WARN), otherwise it
is set to 0. To check the response, an {\sc if} statement can be used.
\EXAMPLE
\begin{verbatim}
    .KEY myfile/A
    TESTBITS <myfile> s
    IF WARN
      ECHO <myfile> is a script
    ELSE
      ECHO <myfile> is not a script
    ENDIF
\end{verbatim}
\ALSO
{\sc if, protect}
\end{manpage}


\begin{manpage}{(\TITLE)}{TimeCom(V37)}{\RELEASE}
\FORMAT
TIMECOM [ON|TO "log file" [APPEND]] [COMMAND] "command line"
\TEMPLATE
ON=TO/K,APPEND/S,COMMAND/F/A
\PURPOSE
To time a command.
\SPEC
The "command line" is executed; after it is complete, {\sc timecom}
prints the elapsed time during the command.  The time is reported in
seconds.

The time is printed on CONSOLE: unless the {\sc to} option is used to
specify an output file.  The {\sc append} switch adds the output to
the end of the specified output file.  This is useful for keeping a
log of the execution times of several commands.

\EXAMPLES
\begin{verbatim}
    1> TIMECOM MyProgram
    Elapsed time: 23 seconds.

    1> TIMECOM TO timelog APPEND MyProgram
    1> TYPE timelog
    Elapsed time: 23 seconds. Command: MyProgram
\end{verbatim}
\BUGS
The time value is not extremely accurate.
\ALSO
intuition.library/CurrentTime() in ``ROM Kernel Reference Manual:
Includes and Autodocs.''
\UNIX
The inspiration for {\sc timecom} came from the much more powerful
{\sc unix} command timex(AS_CMD)
\end{manpage}


\begin{manpage}{(\TITLE)}{Unique(V37)}{\RELEASE}
\FORMAT
UNIQUE [[FROM] "file"] [[TO] "file"] [REPEATED] [UNIQUE|ONCE] [COUNT]
\TEMPLATE
FROM,TO,REPEATED/S,UNIQUE=ONCE/S,COUNT/S
\PURPOSE
To report repeated lines in a file.
\SPEC
The command {\sc unique} reads the {\sc from} file comparing adjacent
lines.  In the normal case, the second and succeeding copies of
repeated lines are removed; the remainder is written on the {\sc to}
file.  Note that repeated lines must be adjacent to be found (see {\sc
sort}).  If the {\sc once} switch is used, just the lines that are not
repeated in the original file are output.  The {\sc repeated} switch
specifies that one copy of just the repeated lines is to be written.
The normal mode ouput is the union of the {\sc once} and {\sc
repeated} mode outputs.

%The argument to the {\sc skipfields} keyword specify the number of
%fields, together with any blanks before each, to skip, before
%beginning the comparison. A field is defined as a string of non-space,
%non-tab characters separated by spaces and tabs from its neighbours.
%The {\sc skipchars} keyword, allows you to specify the number of
%characters to skip. Fields are skipped before characters.

%The {\sc colstart} keyword specifies an absolute character column at
%which to begin the comparison. It will override any {\sc skipfields}
%or {\sc skipchars} arguments. If no {\sc skipfields} argument is
%given, {\sc colstart} "n" gives the same result as {\sc skipchars}
%"n"\/-1.  It is provided for convenience.

The synonym {\sc unique} for {\sc once} is kept in this release for
compatibility with older versions.

The {\sc count} switch generates an output report with each line
preceeded by a count of the number of times it occured.

If no {\sc from} file is given input is read from the default input;
likewise if no {\sc to} file is given output is written to the default
output.
\ALSO
{\sc common, count, sort}
\BUGS
Unique will fail to function correctly given input lines longer than
512 characters.
\UNIX
uniq(BU_CMD)
\end{manpage}

\begin{manpage}{(\TITLE)}{Usage(V37)}{\RELEASE}
\FORMAT
USAGE [[DIR] \{"directory"\}] [BRIEF] [NOHEAD] [NOTOTAL]
\TEMPLATE
DIR/M,BRIEF/S,NOHEAD/S,NOTOTAL/S
\PURPOSE
To estimate disk space usage.
\SPEC
The command {\sc usage} gives an estimate, in blocks, of the disk
space occupied by the directories given on the command line.
Sub-directories are traversed recursively. If no directory is
specified, the current directory is used. The total number of bytes
stored in all the files contained in the directories are reported as
well.

The {\sc brief} switch causes only the total, for each of the
specified directories, to be given. The {\sc nohead} switch suppresses
the printing of the headline. If more than one directory is given, the
grand total will be printed as the bottom line, unless suppressed by
the {\sc nototal} switch.

Hard links to other files or directories in the specified directories,
will cause them to be counted more than once. This may lead to an
incorrectly high estimate. Soft links are completely ignored for now.
\end{manpage}

\end{document}