home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / zip / mint / mntutl95.lzh / MNTUTL95 / MINTSHEL.DOC < prev    next >
Text File  |  1993-08-03  |  10KB  |  229 lines
  1. This file is not an "official" part of MiNT, but please distribute it
  2. with mintshel.ttp.
  3. -----------------------------------------------------------------------
  4. mintshel.ttp: by Allan Pratt and Eric Smith
  5.  
  6. Here is a sample shell that can be used with MiNT. There's nothing
  7. particularly special about this shell (there are plenty of others that
  8. also work under MiNT), but it is small and it does understand job
  9. control, both of which are useful features.
  10.  
  11. When started, mintshel looks in the current directory for the file
  12. "mintshel.rc"; if this file is found, the lines in it are read and processed
  13. just as if they had been typed at the keyboard. A prompt is then printed, and
  14. lines are read from the keyboard until an end of file character (^D) is
  15. encountered. Commands on a line may be separated by the ";" character (in
  16. which case they are executed one after another), the "&" character (in
  17. which case they are executed concurrently), or by the "|" character (in
  18. which case they are executed concurrently with the standard output of the
  19. first command connected to the standard input of the second command). Any
  20. line starting with a "#" character is treated as a comment, and ignored.
  21.  
  22. External commands are searched for using the environment variable PATH,
  23. which should consist of directories separated by commas. See the sample
  24. mintshel.rc for an example. Arguments are passed to external commands using
  25. the Atari extended argument passing convention.
  26.  
  27. I/O redirection is supported for external commands; to redirect the output
  28. of a command to a file, use ">file"; to append to a file use ">>file"; and
  29. to redirect input from a file use "<file".
  30.  
  31. Command-line Arguments
  32. ============ =========
  33.  
  34.   -v        Causes all commands to be echoed to the screen before they're
  35.         executed.
  36.  
  37.   -s        Causes batch files to be aborted if a command in the batch 
  38.         file exits with nonzero $STATUS.
  39.  
  40.   -c args ...    All args after -c are collected into a line, and that line
  41.         is executed by the shell. Then the shell exits with that
  42.         command's $STATUS code.
  43.  
  44.  
  45. Variables
  46. =========
  47. Variables are set with setenv, and are referenced by prefixing their names
  48. with a "$", e.g.:
  49.    echo $PATH
  50. will echo the value of the environment variable PATH. The name may be
  51. enclosed in parentheses or braces; thus
  52.    setenv FOO foo
  53.    echo $(FOO)bar ${FOO}bar 
  54. will echo "foobar foobar". If there are no
  55. parentheses or braces, the name of the environment variable ends with the
  56. first character not in the set [A-Za-z0-9_?*], so "echo $FOO\bar" yields
  57. "foo\bar" and "echo $FOO*" does not yield files matching "foo*" but rather
  58. the value of the variable 'FOO*'.
  59.  
  60. Typing "setenv" with no arguments will show the values of all environment
  61. variables.
  62.  
  63. The following variables have special meaning to the shell:
  64.     $PATH: as mentioned above, is used to find programs.  Setting this
  65. causes an automatic "rehash" (see below).
  66.     $PROMPT: printed before each line of input in an interactive shell.
  67.     $BATCH_EXIT: the value of this variable should be a number.
  68. When nonzero, batch files (and even the shell itself) will exit when
  69. any command returns a nonzero exit code.
  70.     $VERBOSITY: when nonzero, all commands are displayed on the screen
  71. after being alias-expanded, wildcard-expanded, and variable-substituted,
  72. but before being executed.
  73.  
  74. In addition, the following things can be used like environment variables,
  75. but they are not truly in your environment:
  76.     $CWD: yields your current working directory.
  77.     $STATUS: yields the exit code of the last command or batch file.
  78.         (the exit code of a batch file is the exit code of the
  79.         last command executed from that batch file.)
  80.  
  81. If there is no variable with the name you give, an error message is printed
  82. and the command is not run.
  83.  
  84. Wildcards
  85. =========
  86. It is possible to refer to a group of files with similar names by means
  87. of special characters ("wildcards"). For example, the pattern "*.c" means
  88. "all files that have the extension .c". Thus, if the current directory
  89. contains the files "foo", "foo.c", "bar.c", and "bar.doc", the command
  90.     echo *.c
  91. would be exactly equivalent to
  92.     echo foo.c bar.c
  93. and
  94.     echo *c
  95. would be the same as
  96.     echo foo.c bar.c bar.doc
  97. (Note that the files appear in their "true" order on the disk, not necessarily
  98. in alphabetical order).
  99.  
  100. The following wildcards are supported:
  101. *:    matches any sequence of 0 or more characters
  102. ?:    matches any 1 character
  103. [...]:  matches one character inside the brackets; if two characters are
  104.     seperated by a minus sign ('-') then all characters between those
  105.     two are also matched
  106. Examples:
  107. [ad-gz]*    matches all files beginning with 'a', 'd', 'e', 'f', 'g', or
  108.         'z' (read as "(a, or d through g, or z) followed by anything").
  109. *.*        matches all files containing a period. Note the difference
  110.         from some wildcard matching, in which '*.*' matches ALL files.
  111. a*.[ch]        matches all files starting with 'a' and having an extension
  112.         of '.c' or '.h'.
  113.  
  114. If you have any wildcards in a command line, and none of them actually
  115. matches any files, an error message is printed and the command is not run.
  116.  
  117. Batch Files
  118. ===========
  119. Init commands may be placed in a file with a ".bat" extension; typing the
  120. filename (with or without the ".bat" extension) will then run those
  121. commands.
  122.  
  123. Arguments to batch files are accessed in a way similar to environment
  124. variables: $1 yields the first argument to the batch file, $2 the second,
  125. and so on.  $0 yields to the name of the batch file itself, $* yields to
  126. all arguments from $1 on, $? yields to the number of arguments, and the
  127. built-in command 'shift' shifts $3 to $2, $2 to $1, and so on, and
  128. decrements $?.  'shift' leaves $0 alone.  Example of a simple batch file
  129. which executes the command named in its first argument, giving it the
  130. string "fixed_args" as its first argument and the rest of the batch-file
  131. command line as the rest of its args:
  132.  
  133.     echo This is batch file $0, which will execute the command $1.
  134.     setenv cmdHOLD $1
  135.     shift
  136.     $cmdHOLD fixed_args $*
  137.  
  138. Batch file arguments do nest, but each one is executed by the same shell,
  139. with the same environment and so on, so they can affect the global shell
  140. state (i.e. current directory, environment, aliases, etc.).  This is a lose
  141. and should be re-done.  In the meantime, if you want to execute a batch
  142. file in its own shell, use "mintshel -c batch_file_name batch_file_args ..."
  143.  
  144. [Note to shell hackers: the ability to use $? relies on dollar substitution
  145. being done before wildcard substitution, because ? is a wildcard character.
  146. Also, the ability to use $? (and $STATUS) is useless without an "if"
  147. command.]
  148.  
  149. Version note: arguments to batch files are new as of 2/91.
  150.  
  151. Grubby details department: if a string starting with a digit gets to dollar
  152. substitution, atoi is called on it and that's what you get. The
  153. substitution for $1one is the first argument to the batch file, not
  154. getenv("1one").  $x where (x > $?) yields an error message and the command
  155. is abandoned.
  156.  
  157. Builtin Commands
  158. ================
  159. The following commands are built in:
  160.  
  161. alias [string [command]]
  162.     With no arguments, prints a list of all aliases.
  163.     With one argument, shows what command the given string is aliased to.
  164.     With two or more arguments, the first argument ("string") becomes an
  165.     alias for the command consisting of all the other arguments. After this,
  166.     typing "string" is the same as typing that command.
  167.     Example:
  168.     alias c d:\bin\gcc.ttp -O -c
  169.     c foo.c
  170.     c bar.c
  171.     is the same as
  172.     d:\bin\gcc.ttp -O -c foo.c
  173.     d:\bin\gcc.ttp -O -c bar.c
  174.  
  175. bg [pid]
  176.     Restart the job with process group "pid", but leave it in the background.
  177.     If "pid" is omitted, the last job in the list of jobs is used.
  178.  
  179. cd [path]
  180.     Change the current directory to "path"; if no path is given, print
  181.     the current directory.
  182.  
  183. echo [-n] [args]
  184.     Print the given arguments (if any) on the standard output, followed by
  185.     a newline character.  Suppress the newline character if -n is present.
  186.  
  187. exit [code]
  188.     Leave the shell.  Exits with status code 'code' if present, else zero.
  189.  
  190. fg [pid]
  191.     Bring the job with process group "pid" to the foreground. The process
  192.     group is the number in brackets reported by the "jobs" command. If
  193.     "pid" is omitted, the last job in the list of jobs is used.
  194.  
  195. jobs
  196.     Print a list of all jobs that the shell knows about.
  197.  
  198. kill [-sig] pid
  199.     Send the signal whose number is "sig" to process group "pid". The default
  200.     value for sig is 15 (SIGTERM); 9 (SIGKILL) is also useful, since it
  201.     cannot be caught or ignored.
  202.  
  203. rehash [-l] [-v]
  204.     Scans the directories listed in the PATH environment variable for
  205.     executable programs and batch files, and adds them to a "hash buffer"
  206.     so they can be found quickly when used as commands.  With -l, the hash
  207.     buffer is then  listed to stdout.  With -v, it prints statistics
  208.     (currently just the number of file names in each "hash bucket"). This
  209.     happens automatically when the shell finds a PATH in its initial
  210.     environment, and any time the environment variable PATH it set.
  211.  
  212. setenv [name [val]]
  213.     With no arguments, print the current environment; with 1 argument,
  214.     print the current value of that environment variable; with 2 arguments,
  215.     set the named variable to have value "val".
  216.  
  217. shift
  218.     Shifts the args to a batch file, such that the old $1 is lost, the new
  219.     $1 is the old $2, and so on.
  220.  
  221. which <name>
  222.     Prints the full pathname of the program or batch file which will be run
  223.     if <name> is used as a command, provided <name> is in the hash buffer. 
  224.     If it's not there, <name> itself is printed.
  225.  
  226. BUGS:
  227.  
  228. The output of built-in commands and batch files may not be redirected.
  229.