amiga-request@ab20.larc.nasa.gov (Amiga Sources/Binaries Moderator) (02/07/91)
Submitted-by: Cesare.Dieni@p1.f602.n332.z2.fidonet.org (Cesare Dieni)
Posting-number: Volume 91, Issue 005
Archive-name: shells/cshell-4.02a/part03
#!/bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 3 (of 3)."
# Contents: shell.doc
# Wrapped by tadguy@ab20 on Wed Feb 6 19:54:19 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'shell.doc' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'shell.doc'\"
else
echo shar: Extracting \"'shell.doc'\" \(47293 characters\)
sed "s/^X//" >'shell.doc' <<'END_OF_FILE'
X
X INSTRUCTIONS FOR SHELL VERSION: 4.02A 18-Nov-90
X ===============================================
X
X Contents
X --------
X
X O. Changes over old versions
X I. Description
X II. Overview of Major features
X III. Restrictions
X IV. PIPES
X V. Command Pre-processor
X VI. Command Line Editing
X VII. Function Keys
X VIII. Shell Commands
X IX. Special Set Variables
X X. Advanced Topics
X XI. Example source files
X XII. Default values
X XIII. Why ARP ?
X
X
X
XO. Changes over old versions
X-----------------------------
X
XNew to 4.02A:
X- Fixed bug that caused loss of memory on exit.
X- cp now copies protection bits; use -f switch if you want to avoid this.
X- Added commands: man (and alias manlist), uniq, head, tail, tee.
X- This doc has been reformatted to work with man.
X
XNew to 4.01A:
X
X- This version features mostly bug fixes and corrections:
X * Window title is restored after quitting.
X * rxrec now answers to the 'bye' message.
X * rpn can now be redirected and piped; however, this causes
X some problem (see rpn for info).
X * resident list now works with ARP 1.3. To recompile source, you must
X modify include file "libraries/arpbase.h".
X Change definition of rpn_Usage in struct ResidentProgramNode from LONG
X to WORD.
X * pri no more assumes 20 CLI maximum.
X * you can now split long lines in source files even into more than 2 lines.
X- Added much info in this doc about source files (chapter XI)
X- Added copyright notice (see under restrictions).
X
XNew to 4.00A:
X
X- This version is called 4.00A because it is not 100% compatible with
X previous versions. We choose to accept this in order to better support
X the new ARP.library 1.3.
X- External commands are searched in a different order than before; Shell
X path is now searched AFTER current directory, AmigaDOS path and C:.
X- ARP pattern matching has been implemented (in part for line arg expanding,
X fully for search -w).
X- Internal changes for various optimizations.
X- Search command has been improved in several ways.
X- New commands: basename, tackon.
X- New options: if -v, resident -d, fornum -v -s, dir -n.
X- Fixed bugs with dir (some dirs remained locked), foreach -v, htype
X (blanks were treated as binary), info (for devices > 32M).
X- rback command now works ok (run, however, doesn't).
X- Oh, I forgot: it also has an AREXX port... And you don't even have to get
X AREXX to use it. See new commands rxsend, rxrec
X
XNew to 3.03A:
X
X- New filter commands fltlower, fltupper.
X- Added configuration file feature: now if you have a file named S:.login,
X it will be sourced for every Shell you start.
X- New option dir -c.
X- New editing feature: shift-left(right) arrow move cursor to previous(next)
X word.
X- Bugs fixed: alias command wasn't listed in help; typing a number as a
X command was interpreted like 'alias'.
X
XNew to 3.02A:
X
X- New commands: fornum, forline, strleft, strright, strmid, strlen, exec.
X- Improved commands: foreach, pri.
X- New system variable _clinumber.
X- You can now split long lines in source files (see source for details).
X- window -q now lists also position of screens/windows, not only dimension.
X- Since strings are handled directly from Shell with new commands,
X rpn is now used only for calculations; string commands are gone.
X However, now RPN is really usable.
X- Changed rawgets() to fix some problems with function keys, multi-line
X editing and window resizing; also, fixed bug with ^E.
X- cat now warns you if it can't find any file matching your pattern.
X- Now uses DOS packets to get ptr to CLI window; this fixes a bug that
X caused problems if Shell was run on unactive windows.
X- Fixed minor bugs (htype printed some more ASCII bytes, some commands
X returned random values, history didn't print CR's).
X- Heavy mods to this file.
X
X
XI. DESCRIPTION
X---------------
X
XThis version of Shell is the follow of:
X Shell V2.04 (C)Copyright 1986, Matthew Dillon, All Rights Reserved
X Shell V2.04M-V2.07M by Steve Drew
X Shell V2.08MI, V3.xxA and V4.xxA by Carlo Borreo & Cesare Dieni
X
XSend suggestions/criticism/anything else to Carlo Borreo or Cesare Dieni at:
X
X BITNET: PERUGIA@ICNUCEVM.BITNET
X FIDONET: 2:332/602.0@FIDONET # recently changed
X
Xor
X Carlo Borreo Cesare Dieni
X Via G. Berio 34 Via G. Taddei 3
X I-18100 Imperia I-56100 Pisa
X Italy Italy
X
XYou may distribute this program unmodified and for non-profit only.
X
X*** YOU MAY NOT MODIFY THIS PROGRAM AND REDISTRIBUTE IT ***
X
XIf everyone writes his own version of Shell and distributes it, we would be
Xcovered by Shell versions.
X
XIf you make a modification to Shell that you would like to share with other
Xusers, please send us a DIFF output, or a description of what you need.
X
XATTRIBUTIONS
X------------
X
XArexx is a program by William Hawes.
XCygnus Ed Professional (C) 1988 CygnusSoft Software.
X
XII. OVERVIEW
X------------
X
XShell provides a convient AmigaDos alternative command interface.
XAll its commands are internal and thus does not rely on the c:
Xcommands for any functionality.
X
XMajor features include:
X
X -command line editing
X -shell & Amigados search path support
X -simple history
X -redirection of any command
X -piping
X -aliases
X -variables & variable handling (embedded variables)
X -file name expansion via conventional wild carding ('?', '*' and more)
X -conditionals (if/else ect..)
X -source files (w/ gotos and labels)
X -many built in commands to speed things up
X
X
XIII. RESTRICTIONS
X-----------------
X
X AmigaDos execute command will not work. Alternative is to use shell own
Xscript language (which is more powerful) or to do a 'run execute'.
X VDK handler has a bug with setting file dates so when using the copy
Xcommand and VDK you should use the -d switch otherwise your file date in
Xvdk: will be bad. (This is not a bug with shell)
X If using with conman it may be best to start shell with the -a switch
X(shell -a .login) to turn off shell's command line editing and use conmans
Xinstead.
X You can't use chars with code > 127 (i.e., all national symbols,
Xstressed letters, and so on). 8th bit is used internally for a lot of
Xthings in Shell.
X
X
XIV. NOTES ON PIPES
X------------------
X
X PIPES
X PIPES have been implemented using temporary RAM: files. Thus, you
X should be careful when specifying a 'ram:*' expansion as it might
X include the temp. files. These files are deleted on completion of
X the pipe segment.
X
X The file names used are completely unique, even with multiple shell
X running simultaneously.
X
X My favorite new feature is the fact that you can now redirect to
X and from, and pipe internal commands. 'echo charlie >ram:x', for
X instance. Another favorite:
X
X echo "echo mem | shell" | shell
X
X To accomplish these new features, I completely re-wrote the command
X parser in execom.c
X
X NO BCPL program should be output-append redirected (>>).
X
X
XV. COMMAND PRE-PROCESSOR
X-------------------------
X
X PREPROCESSING
X Preprocessing is done on the command line before it is passed on to
X an internal or external routine:
X
X ^c where c is a character is converted to that control character.
X Thus, say '^l' for control-l.
X
X $name where name is a variable name. Variable names can consist of
X 0-9, a-z, A-Z, and underscore (_). The contents of the
X specified variable is used. If the variable doesn't exist,
X the specifier is used. That is, if the variable 'i' contains
X 'charlie', then '$i' -> 'charlie'. If the variable 'i' doesn't
X exist, then '$i'->'$i' .
X
X ; delimits commands. echo charlie ; echo ben.
X
X ' ' (a space). Spaces delimit arguments.
X
X "string" a quoted string. For instance, if you want to echo five spaces
X and an 'a':
X
X echo a -> a
X echo " a" -> a
X
X \c overide the meaning of special characters. '\^a' is a
X circumflex and an a rather than control-a. To get a backslash,
X you must say '\\'.
X
X also used to overide alias searching for commands.
X
X >file specify output redirection. All output from the command is
X placed in the specified file.
X
X >>file specify append redirection (Does not work with BCPL programs).
X
X <file specify input redirection. The command takes input from the
X file rather than the keyboard (note: not all commands require
X input; it makes no sense to say 'echo <charlie' since
X the 'echo' command only outputs its arguments).
X
X | PIPE specifier. The output from the command on the left becomes
X the input to the command on the right. The current SHELL
X implimentation uses temporary files to store the data.
X
X !! execute the previously executed command.
X !nn (nn is a number). Insert the history command numbered n (see
X the HISTORY command)
X !partial search backwards through the history list for a command which
X looks the same as 'partial', and execute it.
X
X # Enter comment. The rest of the line is discarded (note: \#
X will, of course, overide the comment character's special
X meaning)
X
X
XVI. COMMAND LINE EDITING
X------------------------
X
X EDITING
X o Command line can be up to 255 chars.
X o Inserts and deletes are handled correctly over multiple screen
X lines.
X o Shell will keep track of the line width should the window get
X resized.
X
X KEY DEFINITIONS:
X Up Arrow Recall previous commands
X Down Arrow Recall commands
X Left Arrow Move cursor about command line.
X Right Arrow " " " " "
X Shift-Up Arrow Get start of history
X Shift-Down Arrow " end " "
X Shift-Left Arrow Moves cursor a word left
X Shift-Right Arrow " " " " right
X ^A Toggle insert/overtype mode.
X ^D EOF (exits Shell)
X ^E Put cursor at end of text.
X ^K Delete to end of line.
X ^R Retype current line.
X ^U Erase entire line.
X ^X Erase entire line.
X ^Z Put cursor at start of text.
X f1 - f10 Execute command if variable exists.
X F1 - F10 More commands (Shifted f keys).
X Help Invokes help command
X
X
XVII. FUNCTION KEYS
X---- -------------
X
X FUNKEY
X Function keys now insert text to the current position on the command
X line. They maybe terminated with a ^M (return). f1 would be non shifted
X where as F1 is shifted.
X Most of functions key have a default definition, but it may be changed.
X
X $ set f1 dir df0:^M
X
X will add the text 'dir df0:<return>' to the current line.
X
X $ set f1 dir
X
X would only add 'dir' you could then enter ' df0:<return>'
X
X
XVIII. SHELL COMMANDS
X--------------------
X
X First to start shell from a CLI
X
X shell [-a] [-c command;command]
X
X where:
X -a disables all command line editing features. This is
X useful for when running shell over AUX:, and necessary if
X you are running CONMAN.
X
X -c allows execution of one command line and then exits out
X of shell. This is useful for running an internal shell
X commands in the background or from an external application.
X
X eg:
X
X Run shell -c dir df0:; copy -r df0: df1: >nil:; echo Done
X
X If you 'Run' shell in the background without the -c switch shell
X will detect this and imediately exit.
X
X Command execution:
X
X Internal shell commands maybe abreviated.
X
X The first argument is the command-name... here is (in order) how
X Shell tries to execute it:
X
X 1) Alias list is searched for an alias exactly matching name.
X 2) Internal commands list is scanned for a command even partially
X matching name (so you can, for instance, say resi for resident;
X however, you should specify enough of a command to be unique).
X 3) ARP resident list is scanned (you can use Shell's resident
X command to add/remove a file in this list).
X 4) At this point, command is supposed to be external (disk), and
X is searched before in current directory, then in AmigaDOS
X path, in C:, and finally in Shell path.
X 5) As a last chance, AUTOMATIC SOURCING is tried, first in
X current directory, then in Shell path.
X
X AUTOMATIC SOURCING may be accomplished by naming shell scripts with
X a .sh suffix. Thus, if you say 'stuff' and the file 'stuff.sh'
X exists in your current or anywhere in Shell search path, it will be
X SOURCED with any arguments you have placed in the $_passed
X variable. This is equivalent to typing 'source stuff.sh'
X
X WILDCARDS EXPANSION
X Most shell commands will accept multiple arguments that can
X be as a result of wild card expansion. Also when calling
X an external command shell will first expand any wild cards
X to seperate arguments. If you wish to have the external command
X handle it's own wild carding you will need to insert quotes
X around the special wild card characters.
X
X eg.
X arc a new.arc *.txt - shell will expand and pass to arc
X arc a new.arc "*.txt" - let arc expand the wild cards.
X
X Wildcards allowed:
X
X ? match any single character
X * match any string
X .../* recursive search down ALL sub directories from current level
X ~ exclude pattern matching specifier
X ! synonim for ~, supported for compatibility
X & prefixed to patterns, ask confirmation for each file
X [] character class
X
X Examples:
X
X df0:.../* all files in all directories on df0:
X df0:.../!*.info full directory tree of df0: but exclude
X any ugly .info files.
X !*.o !*.c will result in ALL files matching since what
X doesn't match the !*.o will match the !*.c
X df1:&* all files in root of df1:, but ask
X confirmation for each
X *.[co] all files ending in .c or .o
X ~*.[co] all files NOT ending in .c nor in .o
X
X
X The following symbols are not yet supported by wild card
X expansions, but are accepted in search -w.
X
X ( | ) OR matching
X # 0 or more times the pattern following
X
X Examples:
X
X k#a matches ka, kaa, kaaa, etc.
X hel(lo|p) matches hello or help.
X
X
XLIST OF COMMANDS:
X-----------------
X
X ABORTLINE
X Usage : abortline
X Example : echo a;abort;echo b
X Results : a
X
X Causes the rest of the line to be aborted. Intended for use in
X conjunction with exception handling.
X
X ADDBUFFERS
X Usage : addbuffers drive buffers
X Example : addbuffers df0: 24
X
X Just like AmigaDOS addbuffer command, causes new buffers to be
X allocated for disk I/O. Each buffer costs 512 bytes of CHIP memory.
X
X ALIAS
X Usage : alias [name [command string] ]
X Example : alias vt "echo Starting VT100;run sys:tools/vt100"
X
X Sets a name to be a string. You can alias a single name to a set
X of commands if you enclose them in quotes as above. By simply
X typing vt, the command line above would be executed.
X
X Argument Passing to an Alias:
X
X Usage : alias name "%var [command string]"
X Example : alias xx "%q echo hi $q, how are ya."
X xx Steve
X Results : hi Steve, how are ya.
X
X The second form of the alias command allows passing of arguments
X to any position within the command string via use of a variable
X name. To pass arguments to the end of a command string this method
X is actually not necessary.
X
X Typing "alias name" you will get the alias for that name, while with
X "alias" you get a list of all alias.
X
X ASET
X Usage : aset name value
X Example : aset INCLUDE include:
X
X Set a variable in a way that is compatible with Aztec SET command;
X this is completely different from Shell variable.
X May even be used to set ARP variables.
X
X ASSIGN
X Usage : assign [logical [physical] ]
X Example : assign C: df1:c
X
X Use it like AmigaDOS assign command to set, remove or list
X assignments of logical names to directories.
X
X BASENAME
X Usage : basename var path
X Example : basename x df0:c/Dir # sets x to "Dir"
X
X Sets var specified to basename of path.
X
X CAT
X Usage : cat [-n][file file....]
X Example : cat foo.txt
X
X Type the specified files onto the screen. If no file is specified,
X STDIN in used. CAT is meant to output text files only.
X Specifying -n option you will get numbered lines.
X
X CD
X Usage : cd [path]
X Example : cd df0:devs/printers
X
X Change your current working directory. You may specify '..' to go
X back one directory (this is a CD specific feature, and does not
X work with normal path specifications).
X
X CD without any arguments displays the path of the directory you
X are currently in.
X
X CLOSE
X Usage : close filenumber
X
X Close the specified file opened by open.
X See open and flist for more info.
X
X COPY (CP)
X Usage : copy [-u][-d][-f] file file
X or : copy [-u][-d][-f] file1 file2...fileN dir
X or : copy [-r][-u][-d][-f] dir1 dir2...dirN dir
X options :
X -r recursive, copy all subdirectories as well.
X -u update, if newer version exist on dest, don't copy
X -d don't set destination file date to that of source.
X -f don't set destination file bits to those of source.
X
X Example : copy -r df0: df1:
X
X Copy files or directories. When copying directories, the -r option
X must be specified to copy subdirectories as well. Otherwise, only
X top level files in the source directory are copied.
X
X All files will be displayed as they are copied and directory's
X displayed as they are created. This output can be suppessed by
X redirecting to nil: eg. copy -r >nil: df0: df1:
X
X Copy will abort after current file on Control-C.
X
X Copy by default sets the date of the destination file to that of
X the source file. To overide this feature use the -d switch.
X
X Similarly, it sets protection bits (flags) to those of source.
X To avoid this use -f.
X
X Another useful option is the -u (update) mode were copy will not
X copy any files which exists already in the destination directory
X if the destination file is newer or equal to the source file.
X This is useful when developing code say in ram: eg. 'copy *.c ram:'
X when done you can copy -u ram: df1: and only those modules you have
X modified will be copied back.
X
X Copy command will now create the destination directory if it does
X not exist when specified as 'copy [-r] dir dir'. If you specify
X copy file file file dir, then 'dir' must already exist.
X
X CP
X Equivalent to copy.
X
X DATE
X Usage : date [new date and/or time]
X Example : date Wednesday # this refers to NEXT wed, of course
X
X Used to read or set system date and/or time. All standard options
X may be used (yesterday, tomorrow, monday, etc.).
X Leading zero's are not necessary.
X Without parameters shows Dddddd DD-MMM-YY HH:MM:SS.
X
X DEC
X Usage : dec varname [value]
X Example : dec abc
X
X Decrement the numerical equivalent of the variable with specified
X value (default: 1) and place the ASCII-string result back into
X that variable.
X
X DELETE (RM)
X Usage : delete [-p][-r] file file file...
X Example : delete foo.txt test.c
X
X Remove (delete) the specified files. Remove always returns
X errorcode 0. You can remove empty directories. The '-r' option
X will remove non-empty directories by recursively removing all sub
X directories.
X You can remove delete-protected files specifying -p option.
X If you specify any wildcard deletes the files will be listed as
X they are deleted. This can be suppressed by redirecting to nil:
X
X DIR (LS)
X Usage : dir [-sdfcn] [path path ... ]
X Example : dir df0:
X options :
X -s short multi(4) column display.
X -d list directories only
X -f list files only
X -c don't change colors for directories (useful to printer)
X -n display names only
X
X Displays a directory of specified files. Default output shows
X date, protection, block size, byte size and total space used.
X Protections flags include new 1.2/1.3 flags (see under protect).
X Files are alphabetically sorted, without case sensitivity, and
X directories are in red pen (unless you use -c).
X
X DISKCHANGE
X Usage : diskchange drive
X
X Like AmigaDOS diskchange.
X
X ECHO
X Usage : echo [-n] string
X Example : echo hi there
X Results : hi there
X
X Echo the string given. If -n switch given no newline is
X appended.
X
X ELSE
X Usage : else ; command
X Usage : if -f foo.c ; else ; echo "Not there" ; endif
X
X Else clause, must follow an IF statement.
X
X ENDIF
X Usage : endif
X
X The end of an if statement.
X
X Note: if you return from a script file with unterminated IF's
X and the last IF was false, prompt will be changed to an
X underscore ('_') and no commands will be executed until
X 'endif' is typed.
X
X EXEC
X Usage : exec command
X Example : set util SYS:sytem/utilities
X exec $util/make # would not work without exec
X
X Execute the command specified; exec command is equivalent to
X command, only you can use variables to specify command name.
X
X FAULT
X Usage : fault error1 .. errorN
X Example : fault 205 212
X
X Like AmigaDOS fault, prints specified error messages.
X
X FILENOTE
X Usage: filenote file1 .. filen note
X
X Set AMIGADOS comment of the specified file. This is not very useful,
X since in current implementation of Shell file comments are not listed
X in directory, but it was so easy to implement...
X
X FLIST
X Usage : flist
X
X Lists the filenumbers of files opened by open.
X See open and close for more info.
X
X FLTLOWER
X Usage : fltlower
X Example : dir | fltlower
X Or : fltlower <readme
X
X This is a filter command, i.e. it reads from stdin and writes to
X stdout. The more natural way to use it is a pipe, or it can be
X redirected.
X Its purpose is to convert all alphabetic to lower case.
X
X FLTUPPER
X The same of fltlower, only this converts to upper case.
X
X FOREACH
X Usage : foreach [-v] varname ( strings ) command
X Example : foreach i ( a b c d ) "echo -n $i;echo \" ha\""
X Result : a ha
X b ha
X c ha
X d ha
X
X 'strings' is broken up into arguments. Each argument is placed in
X the variable 'varname' in turn and 'command' executed. To execute
X multiple commands, place them in quotes.
X
X Foreach is especially useful when interpreting passed arguments in
X an alias.
X
X eg.
X foreach i ( *.pic ) viewilbm $i
X assuming a.pic and b.pic in current directory the following commands
X will occur:
X viewilbm a.pic
X viewilbm b.pic
X
X Flag -v causes arguments to be displayed every time command is
X executed.
X
X FOREVER
X Usage : forever command
X or : forever "command;command;command..."
X
X The specified commands are executed over and over again forever.
X
X -Execution stops if you hit ^C
X -If the commands return with an error code.
X
X FORLINE
X Usage : forline var filename command
X or : forline var filename "command;command..."
X Example : forline i RAM:temp "echo line $_linenum=$i"
X
X For each ASCII line of file specified commands are executed and
X var points to line content. You can check system variable _linenum
X to find the number of the line currently read.
X
X FORNUM
X Usage : fornum [-v] var n1 n2 command
X or : fornum [-v] -s var n1 n2 step command
X Example : fornum -v x 1 10 echo $1
X or : fornum -s x 10 1 -1 echo $i # counts backwards
X
X Executes command(s) for all numerical values of x between n1 and
X n2. If more than one command is specified, or command is
X redirected, include command(s) in quotes.
X Switch -v (verbose) causes printing of progressive numbers.
X Switch -s allows you to specify a step; if this is negative, the
X count will be backwards.
X
X GOTO
X Usage : goto label
X Example :
X label start
X echo "At start"
X dir ram:
X goto start
X
X Goto the specified label name. You can only use this command from
X a source file. Labels may be forward or reverse from current
X position.
X
X HEAD
X Usage : head filename [num]
X Example : head readme 20
X
X Display first "num" lines of "filename". If num is not specified,
X 10 is assumed.
X
X HELP
X Usage : help
X Example : help
X
X Simply displays all the available commands. The commands are
X displayed in search-order. That is, if you give a partial name the
X first command that matches that name in this list is the one
X executed. Generally, you should specify enough of a command so
X that it is completely unique.
X
X HISTORY
X Usage : history [partial_string]
X Example : history
X
X Displays the enumerated history list. The size of the list is
X controlled by the _history variable. If you specify a partial
X string, only those entries matching that string are displayed.
X
X HOWMANY
X Usage : howmany
X
X This command tells you how many instances of Shell are running in
X your system.
X
X HTYPE
X Usage : htype file1 .. filen
X
X Displays the specified files in hex and ASCII, just like the system
X command Type file opt h. Especially suitable for binary files.
X
X IF
X Usage : if [-n] argument conditional argument ;
X or : if [-n] argument
X or : if [-n] -f file
X or : if [-n] -d file/dir
X or : if [-n] -m
X or : if [-n] -t file file1 .. fileN
X or : if [-n] -r rpnexpression
X or : if [-n] -v varname
X
X If a single argument is something to another argument. Conditional
X clauses allowed:
X
X <, >, =, and combinations (wire or). Thus <> is not-equal, >=
X larger or equal, etc...
X
X If arguments are not numeric, they are compared as strings.
X
X Usually the argument is either a constant or a variable ($varname).
X
X The second form if IF is conditional on the existance of the argument.
X If the argument is a "" string, then FALSE, else TRUE.
X
X The third form of IF used by -f switch checks for existance of
X the specified file.
X
X Switch -d tests the type of the object specified: if it is a
X directory, then TRUE; if it is a file (or it doesn't exist)
X then FALSE.
X
X Switch -m is used to test if FAST memory is present, i.e. wheter
X more than 512K RAM are available.
X Example (to be included in a login.sh file):
X if -m; resident -d lc1 lc2 blink; endif
X
X Using -t form compares the date and time of the first file with
X all the others; if the first is younger than ALL the others, then
X FALSE, else TRUE. If a file doesn't exists, it is considered as
X being older.
X This feature is especially useful for building makefiles without
X using any MAKE utility.
X Example:
X if -t test.o test.asm test.i ; asm -o test.o test.asm ; endif
X
X Option -r evaluates a given RPN expression (see under RPN for more
X info): if value on top of stack is 0, then FALSE, else TRUE.
X
X Switch -n (NOT) reverses the result.
X
X To test if a given variable is defined, use if -v varname.
X
X When using 'IF' command interactively if you are entering commands
X following an 'IF' that was false, the prompt will be set to a
X underscore '_ ' to indicate all commands will be ignored until
X an 'ELSE' or 'ENDIF' command is seen.
X
X INC
X Usage : inc varname [value]
X Example : inc abc 5
X
X Increment the numerical equivalent of the variable with specified
X value (default: 1) and place the ascii-string result back into
X that variable.
X
X INFO
X Usage : info
X
X Display Device statistics for all the disk-type devices in system
X (DFk:, HDk, JHk:, RAM:, RDk: ...), just like the system command
X info. Gives block used/free, % used, errs, status and volume name.
X
X INPUT
X Usage : input var var ... var
X Example : input abc
X
X Input from STDIN (or a redirection, or a pipe) to a variable. The
X next input line is placed in the variable.
X
X JOIN
X Usage : join [-r] file1..fileN destfile
X Example : join part1 part2 part3 total
X
X Joins the specified files to get destfile. If destfile already
X exists, an error message is generated and operation is aborted,
X unless you specify -r (replace) option.
X
X LABEL
X Usage : label name
X
X Create a program label right here. Used in source files, can then
X GOTO a label.
X
X LS
X Equivalent to dir.
X
X MD
X Equivalent to mkdir.
X
X MAN
X Usage : man command(s)
X Example : man mkdir
X
X Get info about a Shell command, or others keywords. These include
X all special _variables, plus various keywords: WILDCARDS, PIPES,
X EDITING, and more.
X See special alias manlist to get a list of ALL keywords supported
X by man.
X You must assign DOC: to the directory containing Shell.doc (this
X file) to use this command.
X
X MEM
X Usage : mem
X
X Display current memory statistics for CHIP memory and FAST memory
X (if any installed).
X
X MKDIR (MD)
X Usage : mkdir name name name...
X Example : mkdir df0:stuff
X
X Create the specified directories.
X
X MV
X Equivalent to rename.
X
X OPEN
X Usage : open filename filemode filenumber
X Example : open RAM:data w 1
X
X This allows you to open a file, redirect to it as many commands as
X you like, then close it.
X Filename is any valid AmigaDOS filename, filemode is either "r" for
X read or "w" for write, filenumber is a number between 1 and 10.
X To redirect a program to or from an open file, use as your redir
X filename a dot followed by the filenumber.
X Here is a complete example:
X
X open RAM:data w 1
X echo -n 2+2= >.1
X rpn 2 2 + . CR >.1
X close 1
X type RAM:data # will display 2+2=4
X
X See also close, flist.
X
X PATH
X Usage : path
X
X Used to list AmigaDOS path. In current version can't be used to
X set it.
X
X PRI
X Usage : pri clinumber pri
X Example : pri 3 5 # set priority of cli #3 to 5
X
X Change the priority of the specified task (use PS command to
X determine clinumber). If you specify 0 as clinumber you can
X change priority of "this" task (the one executing shell).
X
X PROTECT
X Usage : protect file1 ... filen [flags]
X Example : protect myfile rwe
X
X Set AMIGADOS file protection flags for the file specified. Valid
X flags are h, s, p, a, r, w, e, d.
X If you don't specify the flags, all flags are cleared.
X Bit 'a' is new to WorkBench 1.2, while 'h', 's', 'p' are new to 1.3.
X
X PS
X Usage : ps
X
X Gives status of DOS processes. eg:
X
X Proc Command Name CLI Type Pri. Address Directory
X 1 SHELL Initial CLI 0 97b0 Stuff:shell
X 2 sys:c/clockmem Background -10 2101a8 Workdisk:
X 3 c:emacs Background 0 212f58 Stuff:shell
X 4 sys:c/VT100 Background 0 227328 Workdisk:
X
X Address is the addres of the task, directory is the process
X currently CD'd directory.
X
X PWD
X Usage : pwd
X
X Rebuild _cwd by backtracing from your current directory.
X
X QUIT
X Usage : quit
X
X Quit out of Shell back to CLI.
X
X RBACK
X Usage : rback command
X
X Start a new process executing the specified command, but can't do
X input/output. Equivalent to 'run command >NIL: <NIL:'.
X
X RENAME (MV)
X Usage : rename from to
X or : rename from from from ... from todir
X
X Allows you to rename a file or move it around within a disk.
X Allows you to move 1 or more files into a single directory.
X
X RESIDENT
X Usage : resident [-r][-d] [files]
X Example : resident lc1 lc2 blink # load these as resident
X resident -d lc1 lc2 blink # defer load when needed
X resident -r lc1 lc2 blink # remove these
X resident # list resident programs
X
X This is ARP resident. Commands are searched by Shell in resident
X list BEFORE of searching on any external device.
X Only PURE programs can run as resident, see ARP docs for more info.
X Option -d is very useful: you can say, in your startup file,
X resident -d file...file; programs will not be loaded immediately,
X but only when you will try to load them. This way, you will not
X waste memory and startup time if you don't use the programs.
X Old option -a has no more effect.
X
X RETURN
X Usage : return [n]
X Example : return 10
X
X Exit from a script file, or quit from shell with optional
X exit code.
X
X RM
X Equivalent to delete.
X
X RPN
X Usage : rpn expression
X Example : rpn 3 7 * # Prints the value 21
X
X Evaluate an RPN expression, using 32-bit values. In older versions
X of Shell RPN contained string functions too, but now that strings
X are handled by specifical commands, these are no more needed.
X At end of evaluation, RPN prints values on stack, so you can
X say for instance "rpn $x 2 * | input x" to double the value of
X variable x.
X Functions implemented are:
X
X + - * / Obvious meaning; / means integer division, of course
X % Module operator e.g. "rpn 7 3 %" answers 1
X & | ~ Bitwise and, or, not operators
X > < == Tests for greater-than, lower-than, equal. To get
X a test for >= (or <=), you can use < ! (or > !)
X ! Logical not operator
X DUP Duplicate value on top of stack
X DROP Drop value on top of stack
X SWAP Swap two values on top of stack
X
X To avoid confusion with redirections, > and < operators must be
X enclosed in quotes e.g.
X
X 3 2 ">" # Prints 1
X
X RUN
X Usage : run prgm args
X Example : run emacs test.c
X
X Start a new process executing the specified command.
X In current implementation run command can't be redirected.
X This command is not fully reliable: use at your own risk.
X See also rback.
X
X RXREC
X Usage : rxrec [portname]
X
X Create an AREXX-compatible port of the specified name (defaults to
X "rexx_csh"), then puts Shell to sleep waiting for messages on it.
X
X CAUTION: the only way to exit from this status is to send to the port
X the message "bye".
X
X Example:
X Open two Shell's in two separate CLI's. From the first, type:
X
X rxrec
X
X Now first Shell doesn't respond to keyboard input; instead, it waits
X for messages on a port called "rexx_csh". Now, from the other, type:
X
X rxsend rexx_csh "dir df0:"
X
X You will see the listing of df0: in the first Shell. Experiment as you
X like, then:
X
X rxsend rexx_csh bye
X
X And all will return to normal.
X
X RXSEND
X Usage : rxsend portname commands
X
X Send a command to any program with an AREXX-compatible port.
X You don't have to load anything to use these command (or rxrec):
X all you need is a program with the right port.
X
X An example is CygnusEdProfessional: here is, for instance, a command
X to wake it up, load the file test.c and jump to line 20:
X
X rxsend rexx_ced cedtofront "open test.c" "jmp to line 20"
X # rexx_ced is the name of AREXX port for CygnusEd
X
X Refer to your application manual for details and for the name of the
X port.
X
X SEARCH
X Usage : search [-w][-c][-n][-r][-e][-q] filelist string
X
X Search specified files for a string. Only lines containing the
X specified strings are displayed.
X
X If the filename is STDIN (in uppercase) the standard input is
X used, so you can use search as the destination for a pipe.
X Example:
X strings myprog 8 | search STDIN .library
X Lists all libraries used in "myprog".
X
X If you specify any directory in filelist, and use the -r (recurse)
X switch, all files in directory are recursively searched.
X
X Lines are numbered by default; use -n (number) switch to turn off
X line numbering.
X
X Search is normally not case sensitive; use -c (case) flag to turn ON
X case sensitivity.
X
X By specifying -e (exclude) switch, only lines NOT containing the
X specified string are listed.
X
X Using -w (wild) flag, only the lines matching with the string are
X listed.
X Notes to wild card matching;
X - Uses Shell standard matching.
X - All standard ARP wildcards are allowed * ? [] () | ~ ' #
X - The WHOLE line must match the string, not only a substring.
X - String MUST be enclosed in quotes to avoid wildcard expansion
X
X Flag -q (quiet) suppresses printing of file names.
X
X Examples:
X search -cr df0:include ACCESS
X Find all occurrencies of ACCESS (in uppercase) in all files
X contained in include directory.
X search -w shell.h "'#define*"
X Lists only lines of file beginning with (not simply containing)
X #define. Note the use of ' to escape the special symbol #.
X
X SET
X Usage : set [name] [string]
X Example : set abc hello
X
X Set with no args lists all current variable settings.
X Set with one arg lists the setting for that particular variable.
X Specifying name and string, stores the string into variable name.
X
X Also See the section on special _variables.
X
X
X SLEEP
X Usage : sleep timeout
X Example : sleep 10
X
X Sleep for 'timeout' seconds, or until ^C typed.
X
X STACK
X Usage : stack [number]
X Example : stack 8000
X
X Changes the default stack for this CLI. Without arguments, prints
X it.
X
X STRHEAD
X Usage : strhead varname breakchar string
X Example : strhead x . foobar.bas # Will set x to "foobar"
X
X Remove everything after and including the breakchar in 'string' and
X place in variable 'varname'.
X
X STRINGS
X Usage : strings file1..fileN minlenght
X Example : strings c:dir c:list shell 7
X
X Prints strings contained in specified files (usually binary)
X with lenght >= minlenght.
X
X STRLEFT
X Usage : strleft varname string n
X Example : strleft x LongString 5 # Will set x to "LongS"
X
X Place leftmost n chars of string in variable varname.
X
X STRLEN
X Usage : strlen varname string
X Example : strlen x Hello # Will set x to "5"
X
X Puts len of string in variable varname.
X
X STRMID
X Usage : strmid varname string n1 [n2]
X Example : strmid x LongString 5 3 # Will set x to "Str"
X
X Places n2 chars from string, starting at n1, in variable varname.
X By omitting n2, you get all chars from n1 to end of string.
X
X STRRIGHT
X Usage : strright varname string n
X Example : strright x LongString 5 # Will set x to "tring"
X
X Place rightmost n chars of string in variable varname.
X
X STRTAIL
X Usage : strtail varname breakchar string
X Example : strtail x . foobar.bas # Will set x to "bas"
X
X Remove everything before and including the breakchar in 'string' and
X place in variable 'varname'.
X
X SOURCE
X Usage : source file [arguments]
X Example : source mymake.sh all
X Result : source file 'mymake.sh' called with var _passed = 'all'
X
X Execute commands from a file. You can create SHELL programs in
X a file and then execute them with this command. Source'd files
X have the added advantage that you can have loops in your command
X files (see GOTO and LABEL). You can pass SOURCE files arguments
X by specifying arguments after the file name. Arguments are passed
X via the _passed variable (as a single string).
X
X Long lines may be split by appending a backslash (\) at end of
X first half. However, even joined lines cannot be longer than
X ~255 chars. See example of source files.
X
X Automatic 'sourcing' is accomplished by placing a .sh extension on
X the file and executing it as you would a C program:
X
X --------- file hello.sh ---------
X foreach i ( $_passed ) "echo yo $i"
X ---------------------------------
X
X $ hello a b c
X yo a
X yo b
X yo c
X
X TACKON
X Usage : tackon var pathname filename
X Example : tackon x df0:c Dir # sets x to "df0:c/Dir"
X or : tackon x df0: Preferences #sets x to "df0:Preferences"
X
X Correctly adds a filename to a pathname, and puts the result in
X variable specified.
X
X TAIL
X Usage : tail filename [num]
X Example : tail readme 20
X
X Display last "num" lines of "filename". If num is not specified,
X 10 is assumed.
X
X TEE
X Usage : tee
X Example : cc test.c | tee >error.list
X
X This one is a classic "pipe fitting": it copies standard input
X both to standard output and standard error.
X
X TYPE
X Equivalent to CAT.
X
X TOUCH
X Usage : touch file1 .. fileN
X
X Sets DateStamp on the specified files to the current date and time.
X
X UNALIAS
X Usage : unalias name .. name
X Example : unalias vt
X
X Delete aliases..
X
X UNIQ
X Usage : uniq
X
X This is a filter commands, that removed consecutive, duplicated
X lines in a file. It is most useful on a sorted file.
X
X UNSET
X Usage : unset name .. name
X Example : unset abc
X
X Unset one or more variables. Deletes them entirely.
X
X VER
X Usage : ver
X
X Show current version name, & authors.
X
X WINDOW
X Usage : window [-q][-f][-b][-l][-s] [dimensions]
X Options :
X -f (front) Window to front
X -b (back) Window to back
X -l (large) Window to maximum size
X -s (small) Window to minimum size
X -a (activate)
X -q (query) Lists screens and windows open
X
X Various operations on CLI window. If dimensions are specified,
X they must be in the form x y width height, with values separated by
X spaces.
X The command "window -l" may be very useful on PAL machines to
X get a full PAL window from your login sequence, or if you use
X overscan WorkBench.
X Option -q gives, for each Screen and Window currently open,
X title, left edge, top edge, width, height.
X
X
XIX. SPECIAL SET VARIABLES
X-------------------------
X
X _prompt
X This variable is set to the string you wish printed as your
X prompt.
X This can contain escape sequences if you wish, or you can
X include a %p in path definition to get CD in your prompt.
X Default prompt shows path specification in red pen, followed by
X a greater (>) sign and a space.
X The if command will set the prompt to a '_ ' if commands are
X disabled while waiting for a 'endif' or 'else' command (interactive
X mode only.
X
X _history
X This variable is set to a numerical value, and specifies how far
X back your history should extend.
X
X _debug
X Debug mode... use it if you dare. must be set to some value
X
X _verbose
X Verbose mode (for source files). display commands as they are
X executed.
X
X _maxerr
X The worst (highest) return value to date. To use this, you usually
X set it to '0', then do some set of commands, then check it.
X
X _lasterr
X Return code of last command executed. This includes internal
X commands as well as external comands, so to use this variables
X you must check it IMMEDIATELY after the command in question.
X
X _cwd
X Holds a string representing the current directory we are in from
X root. The SHELL can get confused as to its current directory if
X some external program changes the directory. Use PWD to rebuild
X the _cwd variable in these cases.
X
X _passed
X This variable contains the passed arguments when you SOURCE a file
X or execute a .sh file. For instance:
X
X test a b c d
X
X -------- file test.sh ----------
X echo $_passed
X foreach i ( $_passed ) "echo YO $i"
X --------------------------------
X
X _path
X This variable contains the search path when the shell is looking
X for external commands. The format is: DIR,DIR,DIR Each DIR must
X have a trailing ':' or '/'. The current directory is always
X searched first. The entire path will be searched first for the
X <command>, then for <command>.sh (automatic shell script sourcing).
X
X The default _path is set to
X ram:,ram:c/,df0:c/,df1:c/,df0:,df1:,sys:system/
X
X _insert
X Sets the default for insert/overtype mode for command line
X editing. ^A toggles between, but after <RET> the default is
X set back as indicated by this variable. By default _insert is 1
X indicating insert mode on setting to zero will make overtype
X the default.
X
X _titlebar
X Used to set window's title bar.
X
X _clinumber
X Contains the number (1-20) of current CLI.
X
X _except
X See EXCEPTION
X
XX. EXCEPTION PROCESSING
X------------------------
X
X EXCEPTION PROCESSING
X If no _except variable exists, any command which fails causes the
X rest of the line to abort as if an ABORTLINE had been executed. If
X the _except variable exists, it is of the form:
X
X "nnn;commands..."
X
X where nnn is some value representing the minimum return code
X required to cause an error. Whenever a command returns a code
X which is larger or equal to nnn, the commands in _except are
X executed before anything. WHEN _except EXISTS, THE COMMAND LINE
X DOES NOT ABORT AUTOMATICALLY. Thus, if you want the current line
X being executed to be aborted, the last command in _except should be
X an "abortline".
X
X Exception handling is disabled while in the exception handling
X routine (thus you can't get into any infinite loops this way).
X
X Thus if _except = ";", return codes are completely ignored.
X
X Example:
X
X set _except "20;abortline"
X
XXI. EXAMPLE SOURCE FILES
X------------------------
X
XIf from a CLI or the startup-script you say 'SHELL filename', that file is
Xsourced first.
XMoreover, if you have a file called S:.login, it will be sourced for every
XShell you run. This is useful for aliases and setting that you want in ALL
XShells.
X
X
X### Example S:.login ###
X
XHere is an example .login file:
X
Xset F5 "cdir WORK:"^M
Xset f9 "ed s:login.sh"^M
Xset F9 "ed df0:s/startup-sequence"^M
Xalias toram "%q foreach i ( $q ) \"cp -r $i: ram:$i >NIL:;\
X assign $i: ram:$i\""
Xalias ramop "md RAM:op; assign OP: ram:op"
Xalias noop "assign OP: ; rm -r ram:op"
Xalias newop "rm -r OP:*"
Xalias dc "dfc df0: to df1:"
Xalias go "%q assign WORK: Boot:$q; cd WORK:; source startme.sh"
Xalias get "%q cp $q RAM: >NIL:"
X
X#This one puts current directory and cli number on prompt !!!!!!
Xset _prompt ^[[33m[$_clinumber].%p>" "
X
X# this one puts current directory on window titlebar !!!!!!
Xalias cd "%q \\cd $q; set _titlebar CWD: $_cwd"
X
X# This file will be sourced for every Shell you start
X
X### End of example .login ###
X
X****************************************************************************
X
XIf you are a CLI user, your startup-sequence may be as simple as:
X
X C:Shell S:startup.sh
X
XHere is, my startup code:
X
X### Example S:startup.sh ###
X
Xwind -l # if you are on a PAL machine, or use overscan
X # note that commands may be abbreviated (wind=window)
X
Xassign LC: Stuff:c
Xassign INCLUDE: Stuff:include
Xassign LIB: Boot:lib
Xassign QUAD: RAM:
X
Xrback C:FaccII; sleep 1
X # after spawning a process, it is always better to allow it
X # to load the command, to avoid excessive drive head movement
X
Xresident -d blink lc1 lc2 >NIL:
X #defer loading
X
XC:PopCli 300 C:Newcli
X #using full pathname loads faster (even without Shell)
XC:FF -1 Siesta.font >NIL:
XC:Patch_1 >NIL:
Xstack 8000
X # lc1 and lc2 need this
X
Xsource S:setdate.sh # this is listed in next chapter
X
X### End of example startup.sh ###
X
X****************************************************************************
X
XThe following is an example source file to set date and time; it may be
Xused at startup if you don't have an internal clock.
X
X### setdate.sh ###
X
Xopen CON:200/100/440/80/SetDate write 1
Xecho >.1 -n "Current date is "
Xdate >.1
Xecho >.1 -n "Please enter date: "
Xinput <.1 d
Xclose 1
Xstrlen len $d
Xif $len > 1 ; date $d ; endif
Xecho -n "New date: " ; date
X
X### End of setdate.sh ###
X
X***************************************************************************
X
XNext comes a makefile that needs no Make program: may be executed from
XShell directely!!!
X
X### make.sh ###
X
Xif -t Shell.syms Shell.h; cc +HShell.syms Shell.h; rm shell.o; endif
Xif -t RAM:Shell.syms Shell.syms; cp -d Shell.syms RAM:; endif
X
Xforeach i ( main comm1 comm2 comm3 execom globals rawconsole run set \
X sub ) "if -t $i.o $i.c; echo Compile $i...;cc +IRAM:shell.syms $i.c; endif"
X
Xif -t Shell run.o main.o comm1.o comm2.o comm3.o execom.o \
Xset.o sub.o globals.o rawconsole.o
X ln +q -m -o Shell run.o main.o comm1.o comm2.o comm3.o\
X execom.o set.o sub.o globals.o rawconsole.o -la -lc
Xendif
X
X### End of make.sh ###
X
X
XXII. Default Values
X--------------------
X
XTo make things easier, some aliases are predefined whenever you start a
Xnew Shell. These are:
X
X MANLIST
X Display a list of possible arguments to man. You can pipe this to
X sort to get a sorted output.
X
X CLS
X Simply clear the screen.
X
X CDIR
X Use "cdir directory" to clear the screen, set CD to directory,
X and list it.
X
X KR
X Deletes everything on RAM:. If you think this is dangerous,
X you can remove this alias.
X
X EXIT
X Leave Shell and exit CLI.
X
X LP
X List to printer one or more files.
X
XMoreover, many variables have default values, and many function keys are
Xpredefined. You can use set command to determine all of these.
X
XXIII. Why ARP ?
X----------------
X
X ARP
X For those of you curious enough, the A in "4.xxA" means ARP. The
X most recent versions of Shell use ARP.library. This has been very
X useful in:
X
X - Implementing commands like ASET, ASSIGN, INFO, RESIDENT, RBACK,
X RUN.
X - Keeping executable code small.
X
X ARP.library is really public domain, so one can include it in any
X package, both commercial or public domain, like I am doing with
X Shell. The ARP team is trying to wipe out the BCPL from AMIGA.
X This is a very good idea, I think. And there is a lot of people
X hoping that Commodore will put ARP.library in ROM, before or after.
X This would make the AMIGA a much more friendly computer to use and
X program. I encourage programmers to get ARP development package:
X you can find it on many BBS, and is really public domain. Users
X can look for a replacement of C: commands from ARP (but, of
X course, if you use this Shell you won't need them anymore, except
X for ARUN).
END_OF_FILE
if test 47293 -ne `wc -c <'shell.doc'`; then
echo shar: \"'shell.doc'\" unpacked with wrong size!
fi
# end of 'shell.doc'
fi
echo shar: End of archive 3 \(of 3\).
cp /dev/null ark3isdone
MISSING=""
for I in 1 2 3 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 3 archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
--
Mail submissions (sources or binaries) to <amiga@uunet.uu.net>.
Mail comments to the moderator at <amiga-request@uunet.uu.net>.
Post requests for sources, and general discussion to comp.sys.amiga.misc.