Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 336.lha / Ash / Reference.doc < prev next >

Wrap

Text File | 1989-12-27 | 100.6 KB | 5,875 lines

Reference Manual ASH A ksh-like Shell for the Amiga Version 1.0 (Copyright) 1989 Steve Koren November 7, 1989 Table of Contents Introduction......................................4 !, !!.............................................5 _ANSI.............................................6 alias.............................................7 aliases...........................................8 argcount..........................................9 ASHINIT...........................................10 ash...............................................11 basename..........................................12 break.............................................13 builtins..........................................14 cat...............................................15 cd................................................16 clear, cls........................................17 CLINUM............................................18 CMDNUM............................................19 COLUMNS...........................................21 continue..........................................22 cp................................................23 ctpri.............................................24 date..............................................25 dec...............................................26 dirname...........................................27 echo..............................................28 exit..............................................29 export............................................30 false.............................................32 for/do/done.......................................33 force.............................................34 function..........................................35 functions.........................................36 getenv............................................37 head..............................................38 history...........................................39 HISTSIZE..........................................40 HOME..............................................41 IFS...............................................43 inc...............................................44 info..............................................45 LINES.............................................46 local.............................................47 LOGOUT............................................48 ls................................................49 match.............................................50 mem...............................................51 mkdir.............................................52 mv................................................53 OLDPWD............................................54 options...........................................55 PATH..............................................57 path..............................................58 ASH Amiga Shell Page 2 Reference Manual PNPC..............................................59 ps................................................60 PS1...............................................61 PS2...............................................62 PWD...............................................63 pwd...............................................64 read..............................................65 return............................................66 rm................................................67 rmdir.............................................68 set...............................................69 SHELL.............................................70 shift.............................................71 sleep.............................................72 source............................................73 stack.............................................74 SYSNAME...........................................76 tail..............................................77 time..............................................78 true..............................................79 unalias...........................................80 unfunc............................................81 unset.............................................82 variables.........................................83 version...........................................84 wc................................................85 whence............................................86 which.............................................87 while/do/done.....................................88 xd................................................89 ASH Amiga Shell Page 3 Reference Manual Introduction This reference manual describes each Ash command, variable, alias, or function in a concise manner. Each page contains the following information: Name: The name of the command, alias, etc. Type: Variable, Alias, Function, Builtin, Keyword, or External Command. Default: The default value for variables, or definition for aliases. Usage: Command syntax Range: Legal values for variables or parameters About: Text describing the command, variable, etc. Example: A brief example usage. See Also: Other related commands, variables, etc. When reading the command syntax, anything in square brackets is optional. Anything followed by three dots can be repeated any number of times. A vertical bar is used to separate option where one or the other, but not both, can be used. In general, options to commands are preceded by a dash ('- '). The dash character passed alone tells a command to stop reading options. This can be useful to pass a dash as a parameter. For example, echo - - would print a single dash. ASH Amiga Shell Page 4 Reference Manual _________________________________________________________________ Name: !, !! Type: Alias Default: history -e history -e -1 Usage: ! [ pattern | abs_num | rel_num ] !! Range: n/a About: These two aliases provide an easy way to use the history -e command. !! will execute the previous command from the history list by executing history -e -1. ! will execute a specified command from the history list. This command can either specify an absolute number, a relative offset from the most recent command (the offset should be negative), or a partial line or pattern to search for. If a search pattern is given, it should be enclosed in quotes so that Ash does not attempt file name generation on the wildcard pattern. Example: ! cc See Also: history _________________________________________________________________ ASH Amiga Shell Page 5 Reference Manual _________________________________________________________________ Name: _ANSI_BS _ANSI_BE _ANSI_P1 _ANSI_P2 _ANSI_P3 _ANSI_CLEAR Type: Variable Default: "^[[1m" "^[[m" "^[[0;31;40m" "^[[0;32;40m" "^[[0;33;40m" "^[[H^[[2J" Usage: $_ANSI_?? Range: n/a About: These variables are set by Ash to valid ANSI escape sequences which control the Amiga console device. They can be used in echo statements or prompts. Since these variables, when output, affect the console device, they are not normally output by the set command. Example: echo $_ANSI_CLEAR # clear the screen See Also: echo _________________________________________________________________ ASH Amiga Shell Page 6 Reference Manual _________________________________________________________________ Name: alias Type: Builtin Default: n/a Usage: alias [ pattern | string [ '=' ] string ] Range: n/a About: The alias builtin command (not to be confused with 'aliases', which is itself an alias) is used to set and list aliases. If given no parameters, it simply acts as a 'set -a' command. If given one parameter, which is a pattern, all aliases matching that pattern are printed. If given two parameters (or there where the second is a '='), the first string becomes an alias with the second string as its definition. Aliases are expanded when used as a command. Any arguments are appended to the text of the aliases and the resulting string is executed. Unlike ksh and sh, there can be spaces surrounding the '=' sign, which is itself optional. Example: alias foo='echo "This is the foo alias"' See Also: set, alias, unalias _________________________________________________________________ ASH Amiga Shell Page 7 Reference Manual _________________________________________________________________ Name: aliases Type: Alias Default: set -a Usage: aliases [-s] [pattern] Range: n/a About: This alias lists defined aliases. The pattern uses normal wildcards, but must be quoted to avoid being interpreted by the filename expansion mechanism. If the pattern is omitted, all aliases in the current context are listed except those beginning with an underscore (hidden aliases). Only aliases for the current context are listed, so this command may have a different effect inside of a subshell or function than when typed manually. Example: aliases -s '[a-h]*' See Also: set, alias _________________________________________________________________ ASH Amiga Shell Page 8 Reference Manual _________________________________________________________________ Name: argcount Type: Builtin Default: n/a Usage: argcount [ parameter ... ] Range: n/a About: argcount simply prints a count of its arguments. Example: argcount should 'print two' See Also: _________________________________________________________________ ASH Amiga Shell Page 9 Reference Manual _________________________________________________________________ Name: ASHINIT Type: Variable Default: "s:.ashrc" Usage: $ASHINIT Range: n/a About: This variable is set in the .ashinit file to the name of a user modifiable configuration file. Normally this is "s:.ashrc". The user configuration file is sourced (not executed!) for interactive Ash sessions. The s:.ashrc file is provided for user modification. Users should not modify s:.ashinit. If you wish to change something that is defined in s:.ashinit, simply redefine it in s:.ashrc. s:.ashrc is sourced after s:.ashinit. Your s:.ashrc file may optionally source other files. Example: See Also: ash, source _________________________________________________________________ ASH Amiga Shell Page 10 Reference Manual _________________________________________________________________ Name: ash Type: External Command Default: n/a Usage: ash [ -c string | fspec ... ] Range: n/a About: This is, of course, the main Ash binary. If invoked with no parameters, an interactive Ash session is started. If invoked with the '-c' option followed by a string, the string is executed by Ash as if it had been typed, and Ash exits when the operation is complete. If the string contains spaces, it must be surrounded by quotes (although this depends on the invoking shell or environment). If invoked with filespec arguments, each file in turn is executed (not sourced). Ash then exits when finished executing all the files. If Ash is invoked non-interactively, it will still read the .ashinit file, but not the .ashrc file. This allows you to have output statements in the .ashrc file without having this output appear when non-interacrive scripts are run. If you really want to run the .ashrc file first, use: ash s:.ashrc my_file.ash Example: ash -c "expr 21 * 2" See Also: source _________________________________________________________________ ASH Amiga Shell Page 11 Reference Manual _________________________________________________________________ Name: basename Type: Builtin Default: n/a Usage: basename [ fspec ... ] Range: n/a About: basename prints the "base" name of a given path. For example, the basename of sys:System/Format is simply Format. Note that the basename may be a directory and not a file; for example, the basename of sys:usr/bin is bin, even though bin is a directory. If basename is passed more than one parameter, it prints the basename of each parameter in turn. Example: basename sys:usr/bin/wc See Also: dirname _________________________________________________________________ ASH Amiga Shell Page 12 Reference Manual _________________________________________________________________ Name: break Type: Builtin Default: n/a Usage: break [ num ] Range: n/a About: break exits gracefully from an enclosing for or while loop. If a numeric argument is given, it breaks from that many enclosing levels of for or while. Example: for a in a b c d e f do echo $a if [ "$a" = "c" ] then break; fi done See Also: continue _________________________________________________________________ ASH Amiga Shell Page 13 Reference Manual _________________________________________________________________ Name: builtins Type: Alias Default: set -b Usage: builtins [-s] [pattern] Range: n/a About: This aliases lists Ash builtin commands. The pattern uses normal wildcards, but must be quoted to avoid being interpreted by the filename expansion mechanism. If the pattern is omitted, all builtins are listed except those beginning with an underscore character (hidden builtins). There are currently no hidden builtins. Example: builtins -s '[a-h]*' See Also: set _________________________________________________________________ ASH Amiga Shell Page 14 Reference Manual _________________________________________________________________ Name: cat Type: Builtin Default: n/a Usage: cat [ fspec ... ] Range: n/a About: cat prints the contents of each file passed to it on the command line, or the standard input if no files are passed. The contents of each file are concatenated, and are not separated by blank lines. In Ash, cat cannot be used to transfer binary files, only ASCII data. Also, the sequence: cat my_file.txt > my_file1.txt can be faster accomplished with the cp command. Example: cat my_file.txt See Also: cp _________________________________________________________________ ASH Amiga Shell Page 15 Reference Manual _________________________________________________________________ Name: cd Type: Builtin Default: n/a Usage: cd [ -p | dirname ] Range: n/a About: cd changes the current working directory to dirname, or to the previous directory (the contents of the OLDPWD variable) if the -p flag is set. If no parameters are passed, cd moves to the directory indicated by the HOME variable. This is convenient when you are doing most of your work in one place, and wish to return there easily. Under AmigaDos, the HOME variable can be changed very easily with: HOME=. That is, you do not have to worry about certain files being in the HOME directory as you do in a multi-user operating system such as UNIX. Example: cd -p # go back to old directory See Also: PWD, pwd, OLDDIR _________________________________________________________________ ASH Amiga Shell Page 16 Reference Manual _________________________________________________________________ Name: clear, cls Type: Alias Default: echo -n $_ANSI_CLEAR Usage: clear Range: n/a About: These aliases both clear the screen by echoing $_ANSI_CLEAR. Example: clear See Also: _ANSI_CLEAR _________________________________________________________________ ASH Amiga Shell Page 17 Reference Manual _________________________________________________________________ Name: CLINUM Type: Variable Default: n/a Usage: $CLINUM Range: 1 to maximum process number limit About: This variable is set to the CLI process number of Ash when it is started. Example: echo "Process # = $CLINUM" See Also: _________________________________________________________________ ASH Amiga Shell Page 18 Reference Manual _________________________________________________________________ Name: CMDNUM Type: Variable Default: n/a Usage: $CMDNUM Range: 1 to 16 million About: Each time Ash inputs a line from the keyboard, this variable is incremented. Example: echo "$CMDNUM lines have been entered so far." See Also: history _________________________________________________________________ ASH Amiga Shell Page 19 Reference Manual _________________________________________________________________ Name: cmp Type: External Command Default: n/a Usage: cmp [ -s ] file1 file2 Range: n/a About: cmp compares two files for equality. It can be used on binary as well as textual data. cmp is fast in that if the files are not the same size, it won't even bother comparing the contents of the files. cmp normally outputs a message that indicates whether the files are the same, different, or one is shorter than the other. If the -s option is used, compare does not output this information, but simply returns a zero exit status if the files were the same, or non-zero if they were not. Example: if cmp -s file1 file2 then echo 'file1 is the same as file2' else echo 'file1 is different than file2' fi See Also: _________________________________________________________________ ASH Amiga Shell Page 20 Reference Manual _________________________________________________________________ Name: COLUMNS Type: Variable Default: 72 Usage: $COLUMNS Range: 15 to 130 About: This variable is one of several responsible for controlling the actions of Ash line editing and display output. If line editing is enabled, and the cursor moves beyond the column indicated by this variable, Ash slides the line to the left by 12 characters. Ash also uses this variable to truncate the output of certain internal Ash commands (such as History). This creates a cleaner display. Example: COLUMNS=78 See Also: PNPC, LINES, options _________________________________________________________________ ASH Amiga Shell Page 21 Reference Manual _________________________________________________________________ Name: continue Type: Builtin Default: n/a Usage: continue [ num ] Range: n/a About: continue resumes execution with the next iteration of the surrounding loop, or the nth subsequent iteration if given a numeric argument. Example: for a in a b c d e f do echo $a if [ "$a" = "c" ] then continue; fi echo "This is not echoed when $a = c" done See Also: break _________________________________________________________________ ASH Amiga Shell Page 22 Reference Manual _________________________________________________________________ Name: cp Type: Builtin Default: n/a Usage: cp file1 file2 cp file1 [ file2 ... ] dir cp -r dir1 dir2 Range: n/a About: cp copies files from one place to another, optionally renaming them in the process. If the destination is a directory, the files have the same name in the destination directory. If more than one file is copied, the destination must be a directory. The -r flag means do a recursive copy. Example: cp my_file1 m_file2 my_file3 my_directory See Also: mv _________________________________________________________________ ASH Amiga Shell Page 23 Reference Manual _________________________________________________________________ Name: ctpri Type: Alias Default: ChangeTaskPri Usage: ctpri ctpri num Range: -31 <= num <= 31 About: This alias is provided as a shorter alternative to the AmigaDos ChangeTaskPri command. Its use is identical. Example: ctpri 1 See Also: stack _________________________________________________________________ ASH Amiga Shell Page 24 Reference Manual _________________________________________________________________ Name: date Type: Builtin Default: n/a Usage: date [-aDmdty] Range: n/a About: Date prints the current date as a 24 character string: DDD mmm dd hh:mm:ss yyyy Date with the -a (all) option is identical to date with no parameters, (which prints the date as above). Date -D prints a three character representation of the day of the week. Date -m prints a three character representation of the month. Date -d prints the day number as two digits. Date -t prints the time string, and date -y prints the year as four digits. Example: date -y # find the year See Also: time _________________________________________________________________ ASH Amiga Shell Page 25 Reference Manual _________________________________________________________________ Name: dec Type: Builtin Default: n/a Usage: dec var [ count ] Range: n/a About: dec decrements the contents of the variable by count, or 1 if count is not given. It is equivalent to, but faster than, 'var=$(expr $var - $count)' Example: dec my_var 3 See Also: inc _________________________________________________________________ ASH Amiga Shell Page 26 Reference Manual _________________________________________________________________ Name: dirname Type: Builtin Default: n/a Usage: dirname [ fspec ... ] Range: n/a About: dirname prints the "directory" name of a given path. For example, the dirname of sys:System/Format is simply sys:System. If dirname is passed more than one parameter, it prints the dirname of each parameter in turn. Example: dirname sys:usr/bin/wc See Also: basename _________________________________________________________________ ASH Amiga Shell Page 27 Reference Manual _________________________________________________________________ Name: echo Type: Builtin Default: n/a Usage: echo [-nc] [ parameter ... ] Range: n/a About: The echo command simply prints its arguments to standard output. If given no arguments, it prints a newline. Otherwise, it prints its arguments, separated by a single space, unless the -c option is set, in which case no separating spaces are printed (concatenation mode). Echo normally prints a trailing newline, unless the -n option is set, in which case no trailing newline is printed. 'echo -c' is useful for concatenating strings: result = $(echo -c This '+' That) Example: echo 'These' 'arguments' are "echoed" See Also: _________________________________________________________________ ASH Amiga Shell Page 28 Reference Manual _________________________________________________________________ Name: exit Type: Builtin Default: n/a Usage: exit [ code ] Range: n/a About: exit leaves Ash, returning execution back to the invoking shell. If invoked with a numeric argument, it returns that exit code to the invoking shell or program. Note that exit always exits Ash entirely. To simply exit a script or function, use the return statement. If the LOGOUT variable is defined, exit will execute that string before terminating. Example: exit # exits successfully See Also: return, LOGOUT _________________________________________________________________ ASH Amiga Shell Page 29 Reference Manual _________________________________________________________________ Name: export Type: Builtin Default: n/a Usage: export [ var ... ] Range: n/a About: export does two things. It sets the value of the indicated variables in the topmost symbol table in Ash, and it sets an AmigaDos environment variable with the same name and value. This is the only way to transfer variable values between executions of Ash. Example: export my_var1 my_var2 See Also: getenv _________________________________________________________________ ASH Amiga Shell Page 30 Reference Manual _________________________________________________________________ Name: expr Type: Keyword Default: n/a Usage: expr length string expr num_expression expr index str pattern expr substr num1 num2 Range: n/a About: expr evaluates and prints the results of an expression. expr length string prints the length in characters of the string expr num_expression prints the result of evaluating num_expression. num_expression is an integer expression computed with 32 bit integers. '+', '-', '*', '/', and '%' can be used. '*', '/', and '%' have a higher precedence than '+' and '-'; otherwise, the expression is evaluated left to right. Parentheses can be used. expr index str pattern prints the index of pattern if found in the string, or 0 if not found. The first position in string is 1, not 0. Unlike ksh, pattern can be more than one character. expr substr string num1 num2 prints the substring of the string starting at the position indicated by num1 and extending for num2 characters. The beginning of the string is at position one, not 0. Example: expr 3 * ( 1 + 4 ) See Also: _________________________________________________________________ ASH Amiga Shell Page 31 Reference Manual _________________________________________________________________ Name: false Type: Builtin Default: n/a Usage: false Range: n/a About: false simply returns a false exit code, and does nothing else. Example: if false then echo 'This will never echo' fi See Also: true _________________________________________________________________ ASH Amiga Shell Page 32 Reference Manual _________________________________________________________________ Name: for/do/done Type: Keywords Default: n/a Usage: for var in list do stmt_list done Range: n/a About: The variable is set to each value in list, and for each value, the statement list is executed. Example: for file in *.h *.c do cp $file $file.bak done See Also: while _________________________________________________________________ ASH Amiga Shell Page 33 Reference Manual _________________________________________________________________ Name: force Type: Keyword Default: n/a Usage: force [ -fba ] command [ parameter ... ] Range: n/a About: force forces Ash to interpret command as a function, builtin, or alias. Exactly one of the 'f', 'b', and 'a' flags must be present. force is useful if the builtin commands are redefined. Example: function date { echo -n 'The date is: ' force -b date } See Also: _________________________________________________________________ ASH Amiga Shell Page 34 Reference Manual _________________________________________________________________ Name: function Type: Keyword Default: n/a Usage: function name { stmt_list } Range: n/a About: function defines an Ash function called name, and with the definition given by the statement list. Example: function my_func { echo "I was passed $# parameters" See Also: functions _________________________________________________________________ ASH Amiga Shell Page 35 Reference Manual _________________________________________________________________ Name: functions Type: Alias Default: set -f Usage: functions [pattern] Range: n/a About: This alias lists defined functions. The pattern uses normal wildcards, but must be quoted to avoid being interpreted by the filename expansion mechanism. If the pattern is omitted, all functions are listed except those beginning with an underscore character (hidden functions). Only functions for the current context are listed, so this command may have a different effect inside of a subshell or function than when typed manually. Example: functions '[a-h]*' See Also: set _________________________________________________________________ ASH Amiga Shell Page 36 Reference Manual _________________________________________________________________ Name: getenv Type: Builtin Default: n/a Usage: getenv [ var ... ] Range: n/a About: getenv imports the values of the indicated variable from AmigaDos environment variables with the same names. This command, coupled with export command, allows variables to be transferred between executions of Ash. Example: getenv my_var1 my_var2 See Also: export _________________________________________________________________ ASH Amiga Shell Page 37 Reference Manual _________________________________________________________________ Name: head Type: External Command Default: n/a Usage: head [ -num ] [ file ... ] Range: 0 <= num About: head prints the first num lines of each named file, or the standard input if no files are indicated. If num is not explicitly set, it has a default value of 10. Example: head -5 my_file.c my_other_file.c See Also: tail _________________________________________________________________ ASH Amiga Shell Page 38 Reference Manual _________________________________________________________________ Name: history Type: Builtin Default: n/a Usage: history history -n history -e [ pattern | number | offset ] Range: n/a About: Ash maintains the HISTSIZE previous commands in a list so that they may later be recalled or edited for re-execution. history with no parameters simply prints the history list, with each line prefixed by the number of the associated command. The -n parameter leaves out the line numbers. history -e is used to execute commands from the history list. If given a positive numeric argument, it executes the history command at that number (note that these numbers are derived from CMDNUM and do not always begin at 1 if CMDNUM > HISTSIZE). If given a negative numeric argument, the line executed is the 'nth' before the current; thus, the example below executes the previous command. If the argument is a string or pattern, the most recent command containing that string or pattern is executed. Example: history -e -1 # execute previous command See Also: HISTSIZE, !, !!, CMDNUM, command line editing in the User's Manual. _________________________________________________________________ ASH Amiga Shell Page 39 Reference Manual _________________________________________________________________ Name: HISTSIZE Type: Variable Default: 32 Usage: $HISTSIZE Range: 0 to 256 About: Ash keeps a list of the $HISTSIZE most recent commands available for editing and re-entry. Example: HISTSIZE=64 See Also: history, options _________________________________________________________________ ASH Amiga Shell Page 40 Reference Manual _________________________________________________________________ Name: HOME Type: Variable Default: : Usage: $HOME Range: n/a About: This variable represents the default destination for the cd command. It can be set to any valid directory name. Example: HOME=. See Also: cd _________________________________________________________________ ASH Amiga Shell Page 41 Reference Manual _________________________________________________________________ Name: if/then/elif/else/fi Type: Keywords Default: n/a Usage: if expr then stmt_list [ [ elif expr then stmt_list ] ... ] [ else stmt_list ] fi Range: n/a About: If the expression is true (that is, it returns a zero exit status), then the first statement list is executed. If any elif statements are present, each expression is executed, and if it is true, execution procedes for the associated statement list. If none of the expressions were true, the else statement_list is executed. The expressions can be any command, or a test expression surrounded by square brackets (see the user's manual for details). Example: if [ ! -f name -a ! -d name ] then mkdir name else echo "$name exists already!" fi See Also: while _________________________________________________________________ ASH Amiga Shell Page 42 Reference Manual _________________________________________________________________ Name: IFS Type: Variable Default: " \n\t" Usage: $IFS Range: n/a About: Characters in IFS are used to break substituted text (from variables and command substitution) into parameters. If IFS is set to the null string (''), all substituted text will be a single parameter. If the 'i' option to Ash is set (see the options command), the IFS characters will also be used to break text from $( ) style command substitution. Example: [dh0:]: IFS=" \n\t" [dh0:]: a='Now is the time' [dh0:]: echo $a Now is the time [dh0:]: IFS='' [dh0:]: echo $a Now is the time See Also: _________________________________________________________________ ASH Amiga Shell Page 43 Reference Manual _________________________________________________________________ Name: inc Type: Builtin Default: n/a Usage: inc var [ count ] Range: n/a About: inc increments the contents of the variable by count, or 1 if count is not given. It is equivalent to, but faster than, 'var=$(expr $var + $count)' Example: inc my_var 3 See Also: dec _________________________________________________________________ ASH Amiga Shell Page 44 Reference Manual _________________________________________________________________ Name: info Type: Builtin Default: n/a Usage: info [ device | directory ] ... Range: n/a About: info reports the amount of free space available on a given device or directory. It prints total space in kilobytes, used space in kilobytes, the number of bytes per block, the percentage capacity utilization, the total number of errors, and the volume name. If info is given a directory name as an argument, the free space for the directory is the same as the free space for the device on which the directory resides. The Ash info command reports data in 1024 byte kilobytes, not 1000 byte kilobytes. This may lead to a slightly different answer than other info commands. The Ash info command will deal correctly with file systems of up to several gigabytes (should you happen to have one of those). Example: info sys: ram: df0: See Also: _________________________________________________________________ ASH Amiga Shell Page 45 Reference Manual _________________________________________________________________ Name: LINES Type: Variable Default: 24 Usage: $LINES Range: 3 to anything About: This variable is currently not used by Ash; it is provided for future expansion, and for other applications or programs which might be interested. Example: if [ $COLUMNS -lt 20 ] then echo "We require at least 20 lines!" fi See Also: COLUMNS _________________________________________________________________ ASH Amiga Shell Page 46 Reference Manual _________________________________________________________________ Name: local Type: Builtin Default: n/a Usage: local [ varname ... ] Range: n/a About: The local command can be used to enforce the creation of local variables if the 'N' option and the 'l' to Ash are set (see the options command). Normally with the 'N' option set, local variables are created only if they had not been created first in an enclosing context. The local command makes them local even if there had been a previously defined variable of the same name in an enclosing context. Note that this command will have no effect if Ash local variables are disabled by turning off the 'l' option. Example: function my_func { local answer; answer = 42 } See Also: options _________________________________________________________________ ASH Amiga Shell Page 47 Reference Manual _________________________________________________________________ Name: LOGOUT Type: Variable Default: 'echo "\nBye!\n"' Usage: $LOGOUT Range: n/a About: This variable is executed by Ash when the exit command is used to terminate execution. Example: LOGOUT=''; # do nothing See Also: exit _________________________________________________________________ ASH Amiga Shell Page 48 Reference Manual _________________________________________________________________ Name: ls Type: Builtin Default: n/a Usage: ls [ -aldi1bv ] [ dirname | fname ] ... Range: n/a About: This command is used to obtain information about files or directories. With no arguments, it simply lists the contents of the current working directory, leaving out files beginning with a dot. If the 'I' option to Ash is set (see the options command), all .info files are also left out (this feature exists because I hate .info files). The 'a' option causes ls to list files beginning with a dot. Similarly, the 'i' option lists .info files even if the 'I' option to Ash is set. The 'l' option creates a long format list, with filename, protection status, byte size, block size, and modification date listed. (The ll command has been aliased to 'ls -l' to make this easier). The '1' option creates a short format list with one column instead of three (useful for piping filenames into a command). The 'd' option forces directories to be printed as such. Normally if the ls command is given a directory as an argument, it prints the contents of that directory. The 'd' option prints information on the directory itself. This is useful with the 'l' option to find the modification date or protection status of a directory. The 'b' option causes only the basename of each file to be printed. Normally, if a path to a file is given, Ash will print the path information in each entry in the ls output. The 'b' option leaves out the path information, printing only the basename. The 'v' option prints a count of entries listed after the listing itself. Example: ls -li my_dir # list my_dir including info files See Also: options _________________________________________________________________ ASH Amiga Shell Page 49 Reference Manual _________________________________________________________________ Name: match Type: Builtin Default: n/a Usage: match [ -v ] pattern [ string ... ] Range: n/a About: match prints each string that matches the pattern given in the first argument. The pattern is of the same type used by Ash for filename wildcards, but it must be quoted to avoid being expanded in that manner. If the 'v' flag is set, only strings not matching the pattern are printed. Example: match '*.[ch]' file1.foo file1.c file2.h my_file See Also: _________________________________________________________________ ASH Amiga Shell Page 50 Reference Manual _________________________________________________________________ Name: mem Type: Builtin Default: n/a Usage: mem [ -tcf ] Range: n/a About: mem reports the amount of free chip and fast memory, as well as a total. If the 't' flag is set, only the total is printed. If the 'c' is set, only chip memory is listed, and if the 'f' flag is set, only fast memory is listed. Example: if [ $(mem -t ] -lt 400000 ] then echo 'you must have at least 400K free' fi See Also: _________________________________________________________________ ASH Amiga Shell Page 51 Reference Manual _________________________________________________________________ Name: mkdir Type: Builtin Default: n/a Usage: mkdir [ dirname ... ] Range: n/a About: mkdir creates directories with names identical to the parameters passed to it. Example: mkdir my_dir sys:system/my_other_dir See Also: rmdir _________________________________________________________________ ASH Amiga Shell Page 52 Reference Manual _________________________________________________________________ Name: mv Type: Builtin Default: n/a Usage: mv file1 file2 mv file | dir [ file | dir ] ... dir Range: n/a About: mv moves files or directories by renaming them. Thus, it cannot be used to move data cross devices. If more than one source is given, the destination must be a directory, and the sources have the same names in the destination directory. mv can move files or directories. Example: mv my_dir sys:another_dir/my_other_dir See Also: cp _________________________________________________________________ ASH Amiga Shell Page 53 Reference Manual _________________________________________________________________ Name: OLDPWD Type: Variable Default: old present working directory string Usage: $OLDPWD Range: n/a About: When the present working directory is changed, Ash puts the old PWD value into OLDPWD. The cd -p command can be used to return to OLDPWD. Example: echo $PWD; cd c:; echo $OLDPWD See Also: PWD, pwd, cd _________________________________________________________________ ASH Amiga Shell Page 54 Reference Manual _________________________________________________________________ Name: options Type: Builtin Default: n/a Usage: options [ -opts | +opts ] ... Range: n/a About: The options command provides a way to change the default behavior of Ash in a number of areas. If the command is entered with no parameters, simply prints the current options string, which is a series of letters and digits. Otherwise, it examines each parameter in turn. Each parameter can begin with a '+' or '-'; a '+' turns "on" the options corresponding each letter, and a '-' turns them "off". +e If set, disable command line editing. This might be useful for using Ash from a terminal that does not support the ANSI escape sequences Ash uses for line editing. Note that is flag is SET in .ashinit. You must reset it in .ashrc if you wish to use line editing (the .ashrc file supplied with Ash does this). +f If set, disable wildcard filename expansion. +h If set, always create a new history line, even if an old command was executed with 'history -e' or the interactive editing facility. If not set, executing old lines will not create a new history entry. +i If set, use IFS to split $( ) command substitution text, much as it is used to split variable value expansion text. +l If set, variables referenced in functions or parenthetical subshells will be local (although this also depends on the 'n' option). If not set, there will be no local variables. Note that resetting this flag may have large side effects when running scripts and functions. The advantage is that it takes less memory and is faster. +n If set, only read scripts, but do not execute their commands. This is ignored for ASH Amiga Shell Page 55 Reference Manual interactive use. +p If set, use the exec prompt string mode. This tells ash not to use the prompt string as the prompt directly, but rather to pass it through the command interpreter first, and use the results as the prompt. This is slower, but more powerful. +s If set, sort filename parameters from wildcard expansion. +x If set, print each lines as it is executed. Moderately useful for debugging scripts. +E If set, the tab key will expand filenames like <esc><esc>. This is easier to type, and closer to the emacs completion mechanism. (This also requires the 'e' option be reset). +F If set, map UNIX style filenames to AmigaDos style file names. A leading '/' becomes a ':', a '~' inserts the contents of the HOME variable, a '.' becomes the current directory, and two dots become a slash. +I If set, leave out the .info files from directory listings unless the 'i' option to 'ls' is explicitly set. +N Create new variables in a subshell or function only if a variable with the same name does not exist in an outer context. If one does exist, that one will be used instead of making a new local variable. This flag changes the scoping rules, and can have a large effect in the execution of scripts and functions; it should be used with care. +S Insert a single blank line before and after the prompt when typing commands interactively. For interlace screens where more than 36 or so lines are displayed, using the S option can create a more visually appealing and "tidy" display. Example: # reset all options options $(echo -c - '-' $(options)) See Also: _________________________________________________________________ ASH Amiga Shell Page 56 Reference Manual _________________________________________________________________ Name: PATH Type: Variable Default: '.,c:' Usage: $PATH Range: n/a About: This variable contains a comma separated list of directory names. When Ash executes a file, it searches for it in these directories. Note that the current working directory must be specified explicitly ("."). This lets you change the order of the search. For example, you could move "." to the end of the path to search it last. The directory names in the path do not need to be terminated by a slash; Ash will add one if it is not there. If Ash finds the file name in the search path, and the file has its script bit set, Ash will attempt to execute this file as a script instead of a binary. The PATH variable is also used by the which and whence commands. Example: c:run $(which emacs) my_file See Also: path, which, whence _________________________________________________________________ ASH Amiga Shell Page 57 Reference Manual _________________________________________________________________ Name: path Type: Function Default: see the .ashinit file Usage: path path name path -add [ name ... ] Range: n/a About: This function is provided to make the PATH variable easier to set up and manipulate. With no arguments, path simply prints the current path definition. The second form above sets the path variable to name. The third form above adds each name to the path variable list, provided that it is not there already. If the name is already a component of the path, it is ignored. Example: path -add sys:bin sys:pd/bin See Also: PATH _________________________________________________________________ ASH Amiga Shell Page 58 Reference Manual _________________________________________________________________ Name: PNPC Type: Variable Default: 21 Usage: $PNPC Range: 0 to 63 About: This variable is one of several responsible for controlling the actions of Ash line editing and display output. PNPC tells Ash how many non- printing control characters there are in the currently defined prompt strings (both PS1 and PS2). Ash needs to know this so that it can find the actual printing width of the prompt string from the actual character length. You will only have to change PNPC if you change the number of ANSI control sequences in your prompt. Example: PNPC=0 See Also: COLUMNS, PS1, PS2, options _________________________________________________________________ ASH Amiga Shell Page 59 Reference Manual _________________________________________________________________ Name: ps Type: Builtin Default: n/a Usage: ps Range: n/a About: ps prints, for each CLI process, the process number, the address of the process, the priority of the process, the command name associated with the process, and the current working directory for the process. Example: ps See Also: _________________________________________________________________ ASH Amiga Shell Page 60 Reference Manual _________________________________________________________________ Name: PS1 Type: Variable Default: '$_ANSI_P3[$PWD]: $_ANSI_P1' Usage: $PS1 Range: n/a About: This variable controls the primary prompt string displayed by Ash. If the 'p' Ash option is not set (see options), Ash expands the variables in the string, and outputs it as the primary prompt. For this reason, PS1 should be defined to a single quoted string, so that the variables are expanded at the proper time and not when PS1 is defined. If the 'p' option to Ash is set, Ash sends the contents of the PS1 variable through the command interpreter, and displays the result as the primary prompt. In this case, PS1 should contain a string which when executed, will print the desired prompt. This is slower than the default method above. Example: PS1='$ '; PNPC=0 See Also: PS2, PNPC, options _________________________________________________________________ ASH Amiga Shell Page 61 Reference Manual _________________________________________________________________ Name: PS2 Type: Variable Default: '$_ANSI_P3> $_ANSI_P1' Usage: $PS2 Range: n/a About: This variable controls the secondary prompt string displayed by Ash. This is the prompt string displayed when Ash expects more input, such as the continuation of a for statement or unterminated string. If the 'p' Ash option is not set (see options), Ash expands the variables in the string, and outputs it as the secondary prompt. For this reason, PS2 should be defined to a single quoted string, so that the variables are expanded at the proper time and not when PS2 is defined. If the 'p' option to Ash is set, Ash sends the contents of the PS2 variable through the command interpreter, and displays the result as the secondary prompt. In this case, PS2 should contain a string which when executed, will print the desired prompt. This is slower than the default method above. Example: PS2=': '; PNPC=0 See Also: PS1, PNPC, options _________________________________________________________________ ASH Amiga Shell Page 62 Reference Manual _________________________________________________________________ Name: PWD Type: Variable Default: present working directory string Usage: $PWD Range: n/a About: Ash maintains the contents of this variable such that it always represents the current working directory. Example: old_dir="$PWD"; # save old directory See Also: OLDPWD, pwd, cd _________________________________________________________________ ASH Amiga Shell Page 63 Reference Manual _________________________________________________________________ Name: pwd Type: Alias Default: echo "$PWD" Usage: pwd Range: n/a About: This alias simply prints the present working directory string. Example: pwd See Also: PWD, OLDPWD _________________________________________________________________ ASH Amiga Shell Page 64 Reference Manual _________________________________________________________________ Name: read Type: Builtin Default: n/a Usage: read var Range: n/a About: The read command sets the value of the variable by reading exactly one command from the standard input. This can be used to accept input from the keyboard, or it can have its own standard input redirected to read lines from a file. Read returns a non-zero return code when it encounters an end-of-file; this is useful in loops. Example: while read in_line do echo "We read: $in_line" done < my_input_file.txt See Also: _________________________________________________________________ ASH Amiga Shell Page 65 Reference Manual _________________________________________________________________ Name: return Type: Builtin Default: n/a Usage: return [ num ] Range: n/a About: The return command exits from an enclosing script, subshell, or function. If given a numeric argument, it exits from the nth enclosing script, subshell, or function. Example: ( echo foo; return; echo 'This is not echoed' ) See Also: continue, break _________________________________________________________________ ASH Amiga Shell Page 66 Reference Manual _________________________________________________________________ Name: rm Type: Builtin Default: n/a Usage: rm [ file ... ] Range: n/a About: This command simply removes the named files. It will not remove directories; use rmdir for that. Example: rm scrap_file.c See Also: rmdir _________________________________________________________________ ASH Amiga Shell Page 67 Reference Manual _________________________________________________________________ Name: rmdir Type: Builtin Default: n/a Usage: rmdir [ dir ... ] Range: n/a About: This command simply removes the named directories. It will not remove files or directories which are not empty. Example: rmdir scrap_dir See Also: rmdir _________________________________________________________________ ASH Amiga Shell Page 68 Reference Manual _________________________________________________________________ Name: set Type: Builtin Default: n/a Usage: set [ -fabvs ] [ pattern ... ] Range: n/a About: With no options, set lists each variable and its definition. If pattern arguments, each one is listed. The 'f' options forces interpretation as function names, the 'a' option as alias names, the 'b' option as builtin command names, and the 'v' option as variables names (the default). The 's' option leaves out the definition, printing only the name on a single line. In any case, function definitions are not listed in this version of Ash. If the 's' option is used, the 'v' option must explicitly be set to list variables. Also, more than one of 'f', 'a', 'b', and 'v' may be set. Ash will not list any function, alias, builtin, or variable whose name begins with an underscore (hidden variables, etc). This is useful to either hide definitions from users, or in cases where printing the contents of a variable would corrupt the display (such as the _ANSI_CLEAR variable). The definition of builtin commands is printed as a short description of the command. The set command cannot be used to set variables, as in csh. Use the assignment operator ('=') for that. Example: set -b '[a-d]*' See Also: unset _________________________________________________________________ ASH Amiga Shell Page 69 Reference Manual _________________________________________________________________ Name: SHELL Type: Variable Default: ash Usage: $SHELL Range: n/a About: This variable is set by Ash to the string "ash". It can be used to test which shell is running, provided that the alternate shell has a similar syntax. Example: if [ "$ash" != 'ash' ] then echo "This runs only under Ash!" fi See Also: SYSNAME _________________________________________________________________ ASH Amiga Shell Page 70 Reference Manual _________________________________________________________________ Name: shift Type: Builtin Default: n/a Usage: shift [ num ] Range: n/a About: This command is used inside of scripts or functions to shift the parametric arguments. For example, if $1 = 'foo' and $2 = 'bar', after a shift, $1 would be 'bar' and $2 would not be set. The '$#' and '$*' variables are also modified appropriately. If shift is given a numeric parameter, it acts as though num consecutive shifts took place. Example: function my_func { echo "$2, $#" shift echo "$2, $#" } See Also: function _________________________________________________________________ ASH Amiga Shell Page 71 Reference Manual _________________________________________________________________ Name: sleep Type: Builtin Default: n/a Usage: sleep n Range: n/a About: Sleep delays execution for n seconds. If n is omitted, zero, or negative, the command does not pause. Sleep takes virtually no CPU time. It will wake up once per second to check for the break key. Sleep is not guaranteed to be a delay of exactly n seconds; it may be more on a loaded system, or if Ash is preempted by a higher priority process. It is, however, guaranteed to be a delay of at least n seconds. Example: time sleep 5 See Also: time _________________________________________________________________ ASH Amiga Shell Page 72 Reference Manual _________________________________________________________________ Name: source Type: Builtin Default: n/a Usage: source [ file ... ] Range: n/a About: This command "sources" the named files; that is, they are executed, but not in a subshell, so that any variables, alias, etc, that they define are really defined in the parent's environment. A single dot ('.') may be used to source a file as well; this is compatible with ksh and sh. A file which is sourced does not have to have its script bit set (although it won't hurt). However, a script file which is to be executed by typing its name must have its script bit set. Executing a file is equivalent to: ( source file ) Example: source my_init_file.ash See Also: _________________________________________________________________ ASH Amiga Shell Page 73 Reference Manual _________________________________________________________________ Name: stack Type: Function Default: see the .ashinit file Usage: stack stack size Range: 4000 <= size <= 128000 About: This function is provided to set or examine the stack size. With no arguments, it prints the current stack size using c:stack. With one argument, it sets the stack size to 12000 bytes plus the argument. This is necessary because Ash itself requires 12000 bytes of memory, and executed programs require their stack in addition to this. Example: stack 16000 See Also: _________________________________________________________________ ASH Amiga Shell Page 74 Reference Manual _________________________________________________________________ Name: strings Type: External Command Default: n/a Usage: strings [ -num ] [ file ... ] Range: 0 <= num About: strings searches the named files for strings of at least num consecutive printable characters. If found, it prints them. If num is not set, it defaults to 6. Example: strings -10 my_file.o binary_file See Also: _________________________________________________________________ ASH Amiga Shell Page 75 Reference Manual _________________________________________________________________ Name: SYSNAME Type: Variable Default: 'Amiga' Usage: $SYSNAME Range: n/a About: This variable describes the system on which Ash is currently being run. There is currently only one version of Ash, so this variable will contain "Amiga". If Ash is ported to other systems, this variable can be used to determine the name of the system. Example: if [ "$SYSNAME" != 'Amiga' ] then echo "This script runs only on Amigas." fi See Also: SHELL _________________________________________________________________ ASH Amiga Shell Page 76 Reference Manual _________________________________________________________________ Name: tail Type: External Command Default: n/a Usage: tail [ -num | +num ] [ file ... ] Range: 0 <= num <= 1024 About: tail prints the last num lines of each named file, or the standard input if no files are named. If a '+' precedes num instead of a '-', tail instead skips num lines and prints the rest of the file. Since tail uses a temporary ram buffer to store lines, num is limited to 1024. If num is set to a larger number, it will be silently truncated to 1024. Example: tail -15 my_file.c my_other_file.c See Also: head _________________________________________________________________ ASH Amiga Shell Page 77 Reference Manual _________________________________________________________________ Name: time Type: Keyword Default: n/a Usage: time statement Range: n/a About: time executes the statement and prints the execution time in seconds. Example: time ( dir; sleep 2 ) See Also: _________________________________________________________________ ASH Amiga Shell Page 78 Reference Manual _________________________________________________________________ Name: true Type: Builtin Default: n/a Usage: true Range: n/a About: true simply returns a true exit code, and does nothing else. Example: while true do echo 'repeat forever!' sleep 1 done See Also: false _________________________________________________________________ ASH Amiga Shell Page 79 Reference Manual _________________________________________________________________ Name: unalias Type: Alias Default: unset -a Usage: unalias [ name ... ] Range: n/a About: This alias removes existing aliases from the current context. If no names are given, the command has no effect. Otherwise, each alias listed is removed, if it was in fact an alias. Ash supplied aliases may be removed, but this is not recommended. Example: unalias my_alias my_other_alias See Also: unset _________________________________________________________________ ASH Amiga Shell Page 80 Reference Manual _________________________________________________________________ Name: unfunc Type: Alias Default: unset -f Usage: unfunc [ name ... ] Range: n/a About: This alias removes existing functions from the current context. If no names are given, the command has no effect. Otherwise, each function listed is removed, if it was in fact an function. Ash supplied functions may be removed, but this is not recommended. Example: function my_function my_other_function See Also: unset _________________________________________________________________ ASH Amiga Shell Page 81 Reference Manual _________________________________________________________________ Name: unset Type: Builtin Default: n/a Usage: unset [ -fav ] [ name ... ] Range: n/a About: This command removes the definition of functions, aliases, or variables (controlled by the f, a, or v flags). If no flag is given, the default is to remove variable definitions. Example: unset -f my_func1 my_func2 See Also: unfunc, unalias _________________________________________________________________ ASH Amiga Shell Page 82 Reference Manual _________________________________________________________________ Name: variables Type: Alias Default: set -v Usage: variables [-s] [pattern] Range: n/a About: This alias lists defined variables. The pattern uses normal wildcards, but must be quoted to avoid being interpreted by the filename expansion mechanism. If the pattern is omitted, all variables are listed except those beginning with an underscore character (hidden variables). For example, _ANSI_P1 is a hidden variable; if it was printed in the normal variable list, the display pen would be changed. Only variables for the current context are listed, so this command may have a different effect inside of a subshell or function than when typed manually. Example: variables -s '[A-H]*' See Also: set _________________________________________________________________ ASH Amiga Shell Page 83 Reference Manual _________________________________________________________________ Name: version Type: Builtin Default: n/a Usage: version [ -ds ] Range: n/a About: version with no options prints the Ash version string and copyright notice. The 'd' option echoes the compile date of Ash, and the 's' option prints a single numeric value that will be incremented for each release of Ash. This is useful in tests, as below. Example: if [ $(version -s) -lt 3 ] then echo 'This script requires a later Ash version' fi See Also: _________________________________________________________________ ASH Amiga Shell Page 84 Reference Manual _________________________________________________________________ Name: wc Type: External Command Default: n/a Usage: wc [ -hcwlqt ] [ file ... ] Range: n/a About: wc is a utility which counts characters, words, or lines in a given series of files (or the standard input, if no files are indicated). It normally produces information on all three counts, preceded by a title for each column. If the c, w, or l flags are set, only information on characters, words, or lines is printed. (These can be combined; for example 'wc -cl'). If the q flag is set, wc does its work quietly; that is, it leaves out titles and file names, only reporting the actual counts. The t flag can be used to obtain a total at the end, and the h flag prints a helpful usage message. Example: if [ $(wc -lq my_file) -lt 10 ] then echo "There must be at least 10 lines" fi See Also: _________________________________________________________________ ASH Amiga Shell Page 85 Reference Manual _________________________________________________________________ Name: whence Type: Builtin Default: n/a Usage: whence [ name ... ] Range: n/a About: whence reports how each name would be interpreted if it was used as a command. It will report whether the name will be interpreted as a builtin command, an alias, a function, or an external statement. If the command is interpreted as an external statement, a path to the command is printed. Example: whence whence if path ll See Also: which _________________________________________________________________ ASH Amiga Shell Page 86 Reference Manual _________________________________________________________________ Name: which Type: Builtin Default: n/a Usage: which [ name ... ] Range: n/a About: which searches the current PATH variable for an occurrence of name. If it finds one, the path to name is printed. Multiple names are accepted, in which case the process is repeated for each one. Although which does not know about aliases or functions, it is often more useful in scripts or from the command line. For example, if you know that "my_file" is in the search path, you can say: ll $(which my_file) to print information on my_file without knowing where it is. The example below is another possible use. In the function, which is used both to avoid interpreting "run" recursively as a function, and to find the desired binary. Example: function run { cmd="$1" shift $(which run) $(which $cmd) $* } See Also: whence _________________________________________________________________ ASH Amiga Shell Page 87 Reference Manual _________________________________________________________________ Name: while/do/done Type: Keywords Default: n/a Usage: while expr do stmt_list done Range: n/a About: The statement list is executed while the expression is true (returns a zero exit status). Example: a=1 while [ $a -le 10 ] do echo "a = $a" done See Also: for _________________________________________________________________ ASH Amiga Shell Page 88 Reference Manual _________________________________________________________________ Name: xd Type: External Command Default: n/a Usage: xd [ file ... ] Range: n/a About: xd (hex dump) prints a hexadecimal dump of each named file, or the standard input if no files are named. It prints the hex address of the current offset as 8 digits, then a hex dump of 16 bytes separated into groups of 2 bytes, then an ASCII representation of the 16 bytes, or '.' if the byte is not a printable character. Example: xd any_old_file See Also: _________________________________________________________________ ASH Amiga Shell Page 89 Reference Manual