Amiga-Request@cs.odu.edu (Amiga Sources/Binaries Moderator) (01/16/90)
Submitted-by: PERUGIA@ICNUCEVM.CNUCE.CNR.IT (Carlo & Cesare)
Posting-number: Volume 90, Issue 017
Archive-name: unix/cshell-4.00a/part04
#! /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 4 (of 4)."
# Contents: shell.doc
# Wrapped by tadguy@xanth on Mon Jan 15 11:28:12 1990
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'\" \(44520 characters\)
sed "s/^X//" >'shell.doc' <<'END_OF_FILE'
X
X INSTRUCTIONS FOR SHELL Version: 4.00A 13-Jan-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 login file
X XII. Example source files
X XIII. Default values
X XIV. Why ARP ?
X
X
X*********************************************************************************
X* NOTE TO VERSION 4.00: THIS VERSION HAS A LOT OF IMPROVEMENTS OVER THE *
X* PREVIOUS ONES; WE EXPECT IT TO HAVE A BIT MORE BUGS THAN USUAL. *
X* WE HOPE ALL OF YOU WILL CONTINUE TO HELP US WITH SUGGESTIONS AND BUG REPORTS. *
X* *
X* THANKS *
X* CARLO & CESARE *
X*********************************************************************************
X
X
XO. Changes over old version
X ------------------------
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
XNew to 3.01A:
X
X- Fixed bug with strings: before it printed strings with lenght 1 more
X than specified lenght.
X- Made some additions and corrected many errors in Shell.doc (this file).
X- Modified handler of external commands to allow things like DATE "?"
X (always use quotes).
X- Corrected cat: it didn't work with STDIN before.
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 and V3.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/23.0@FIDONET
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 for non-profit only.
X
X Attributions
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 o AmigaDos execute command will not work. Alternative is to use shell
X own script language (which is more powerful) or to do a 'run execute'.
X o VDK handler has a bug with setting file dates so when using the copy
X command and VDK you should use the -d switch otherwise your file date
X in vdk: will be bad. (This is not a bug with shell)
X o 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
X conmans instead.
X
X
XIV. NOTES ON PIPES
X --------------
X
X PIPES have been implimented 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 simultaniously.
X
X My favorite new feature is the fact that you can now redirect to and
X 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 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 o Command line can be upto 255 chars.
X o Inserts and deletes are handled correctly over multiple screen lines.
X o Shell will keep track of the line width should the window get 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 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 useful for
X when running shell over AUX:, and necessary if you are running
X CONMAN.
X
X -c allows execution of one command line and then exits out of shell.
X This is useful for running a internal shell commands in the
X background or from an external application. 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 imediatley 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 Shell
X 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 a
X .sh suffix. Thus, if you say 'stuff' and the file 'stuff.sh' exists in
X your current or anywhere in Shell search path, it will be SOURCED with
X any arguments you have placed in the $_passed variable.
X This is equivalent to typing 'source stuff.sh'
X
X Wild card expansions:
X Most shell commands will accept multiple arguments that can
X be as a result of wild card expansion. Also when the 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 Wild card expansions:
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 expansions,
X 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
X LIST 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
X (CP)
X Usage : copy [-u][-d] file file
X or : copy [-u][-d] file1 file2...fileN dir
X or : copy [-r][-u][-d] 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
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 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
X (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
X (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 n2.
X If more than one command is specified, or command is redirected,
X 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 a
X source file. Labels may now be forward or reverse from current
X position.
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
X the first command that matches that name in this list is the one
X executed. Generally, you should specify enough of a command so that
X 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
X in 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 MEM
X Usage : mem
X
X Display current memory statistics for CHIP memory and
X FAST memory (if any installed).
X
X MKDIR
X (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
X as you like, then close it.
X Filename is any valid AmigaDOS filename, filemode is either r
X for 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 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
X (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 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 for 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 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 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
X by 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. This can contain escape sequences if you wish, or
X you can include a %p in path definition to get CD in your
X 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
XX. ADVANCED TOPICS
X ---------------
X
X EXCEPTION_PROCESSING:
X
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 required
X to cause an error. Whenever a command returns a code which is
X larger or equal to nnn, the commands in _except are executed before
X anything. WHEN _except EXISTS, THE COMMAND LINE DOES NOT ABORT
X AUTOMATICALLY. Thus, if you want the current line being executed
X to be aborted, the last command in _except should be an "abortline".
X
X exception handling is disabled while in the exception handling routine
X (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 LOGIN FILE
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 alias and setting that you want in ALL
XShells.
XIf you are a CLI user, your startup-sequence may be as simple as:
X
X C:Shell S:login.sh
X
XHere is, my startup code:
X
X### Example S:login.sh ###
X
Xwindow -l # if you are on a PAL machine, or use overscan
X
Xset _prompt ^[[33m[$_clinumber].%p>" "
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
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 -a LC:Blink LC:lc1 LC:lc2 >NIL:
X
XC:PopCli 300 C:Newcli
XC:FF -1 Siesta.font >NIL:
XC:Patch_1 >NIL:
Xstack 8000 # lc1 and lc2 need this
X
Xsource S:setdate.sh # this is listed in next chapter
X
X### End of example login.sh ###
X
X
XXII. Example Source files
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 -r $len 1 > ; date $d ; endif
Xecho -n "New date: " ; date
X
X### End of setdate.sh ###
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
XXIII. Default Values
X --------------
X
XTo make things easier, some aliases are predefined whenever you start a
Xnew Shell. These are:
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
XMoreover, many variables have default values, and many function keys are
Xpredefined. You can use set command to determine all of these.
X
XXIV. Why ARP ?
X ---------
X
XFor those of you curious enough, the A in "3.xxA" means ARP. The most
Xrecent versions of Shell use ARP.library. This has been very useful in:
X
X - Implementing commands like ASET, ASSIGN, INFO, RESIDENT, RBACK, RUN.
X - Keeping executable code small.
X
XARP.library is really public domain, so one can include it in any package,
Xboth commercial or public domain, like I am doing with Shell.
XThe ARP team is trying to wipe out the BCPL from AMIGA. This is a very
Xgood idea, I think. And there is a lot of people hoping that Commodore
Xwill put ARP.library in ROM, before or after. This would make the AMIGA
Xa very mory friendly computer to use and program.
XI encourage programmers to get ARP development package: you can find it
Xon many BBS, and is really public domain. Users can look for a replacement
Xof C: commands from ARP (but, of course, if you use this Shell you won't
Xneed them anymore, except for ARUN).
X
END_OF_FILE
if test 44520 -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 4 \(of 4\).
cp /dev/null ark4isdone
MISSING=""
for I in 1 2 3 4 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 4 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
--
Submissions to comp.sources.amiga and comp.binaries.amiga should be sent to:
amiga@cs.odu.edu
or amiga@xanth.cs.odu.edu ( obsolescent mailers may need this address )
or ...!uunet!xanth!amiga ( very obsolescent mailers need this address )
Comments, questions, and suggestions s should be addressed to ``amiga-request''
(only use ``amiga'' for submissions) at the above addresses.