bin/sh/TOUR

   1 #       @(#)TOUR        8.1 (Berkeley) 5/31/93
   2 # $FreeBSD: src/bin/sh/TOUR,v 1.6 1999/08/27 23:15:07 peter Exp $
   3 # $DragonFly: src/bin/sh/TOUR,v 1.2 2003/06/17 04:22:50 dillon Exp $
   4
   5 NOTE -- This is the original TOUR paper distributed with ash and
   6 does not represent the current state of the shell.  It is provided anyway
   7 since it provides helpful information for how the shell is structured,
   8 but be warned that things have changed -- the current shell is
   9 still under development.
  10
  11 ================================================================
  12
  13                        A Tour through Ash
  14
  15                Copyright 1989 by Kenneth Almquist.
  16
  17
  18 DIRECTORIES:  The subdirectory bltin contains commands which can
  19 be compiled stand-alone.  The rest of the source is in the main
  20 ash directory.
  21
  22 SOURCE CODE GENERATORS:  Files whose names begin with "mk" are
  23 programs that generate source code.  A complete list of these
  24 programs is:
  25
  26         program         intput files        generates
  27         -------         ------------        ---------
  28         mkbuiltins      builtins            builtins.h builtins.c
  29         mkinit          *.c                 init.c
  30         mknodes         nodetypes           nodes.h nodes.c
  31         mksignames          -               signames.h signames.c
  32         mksyntax            -               syntax.h syntax.c
  33         mktokens            -               token.h
  34         bltin/mkexpr    unary_op binary_op  operators.h operators.c
  35
  36 There are undoubtedly too many of these.  Mkinit searches all the
  37 C source files for entries looking like:
  38
  39         INIT {
  40               x = 1;    /* executed during initialization */
  41         }
  42
  43         RESET {
  44               x = 2;    /* executed when the shell does a longjmp
  45                            back to the main command loop */
  46         }
  47
  48         SHELLPROC {
  49               x = 3;    /* executed when the shell runs a shell procedure */
  50         }
  51
  52 It pulls this code out into routines which are when particular
  53 events occur.  The intent is to improve modularity by isolating
  54 the information about which modules need to be explicitly
  55 initialized/reset within the modules themselves.
  56
  57 Mkinit recognizes several constructs for placing declarations in
  58 the init.c file.
  59         INCLUDE "file.h"
  60 includes a file.  The storage class MKINIT makes a declaration
  61 available in the init.c file, for example:
  62         MKINIT int funcnest;    /* depth of function calls */
  63 MKINIT alone on a line introduces a structure or union declara-
  64 tion:
  65         MKINIT
  66         struct redirtab {
  67               short renamed[10];
  68         };
  69 Preprocessor #define statements are copied to init.c without any
  70 special action to request this.
  71
  72 INDENTATION:  The ash source is indented in multiples of six
  73 spaces.  The only study that I have heard of on the subject con-
  74 cluded that the optimal amount to indent is in the range of four
  75 to six spaces.  I use six spaces since it is not too big a jump
  76 from the widely used eight spaces.  If you really hate six space
  77 indentation, use the adjind (source included) program to change
  78 it to something else.
  79
  80 EXCEPTIONS:  Code for dealing with exceptions appears in
  81 exceptions.c.  The C language doesn't include exception handling,
  82 so I implement it using setjmp and longjmp.  The global variable
  83 exception contains the type of exception.  EXERROR is raised by
  84 calling error.  EXINT is an interrupt.  EXSHELLPROC is an excep-
  85 tion which is raised when a shell procedure is invoked.  The pur-
  86 pose of EXSHELLPROC is to perform the cleanup actions associated
  87 with other exceptions.  After these cleanup actions, the shell
  88 can interpret a shell procedure itself without exec'ing a new
  89 copy of the shell.
  90
  91 INTERRUPTS:  In an interactive shell, an interrupt will cause an
  92 EXINT exception to return to the main command loop.  (Exception:
  93 EXINT is not raised if the user traps interrupts using the trap
  94 command.)  The INTOFF and INTON macros (defined in exception.h)
  95 provide uninterruptable critical sections.  Between the execution
  96 of INTOFF and the execution of INTON, interrupt signals will be
  97 held for later delivery.  INTOFF and INTON can be nested.
  98
  99 MEMALLOC.C:  Memalloc.c defines versions of malloc and realloc
 100 which call error when there is no memory left.  It also defines a
 101 stack oriented memory allocation scheme.  Allocating off a stack
 102 is probably more efficient than allocation using malloc, but the
 103 big advantage is that when an exception occurs all we have to do
 104 to free up the memory in use at the time of the exception is to
 105 restore the stack pointer.  The stack is implemented using a
 106 linked list of blocks.
 107
 108 STPUTC:  If the stack were contiguous, it would be easy to store
 109 strings on the stack without knowing in advance how long the
 110 string was going to be:
 111         p = stackptr;
 112         *p++ = c;       /* repeated as many times as needed */
 113         stackptr = p;
 114 The folloing three macros (defined in memalloc.h) perform these
 115 operations, but grow the stack if you run off the end:
 116         STARTSTACKSTR(p);
 117         STPUTC(c, p);   /* repeated as many times as needed */
 118         grabstackstr(p);
 119
 120 We now start a top-down look at the code:
 121
 122 MAIN.C:  The main routine performs some initialization, executes
 123 the user's profile if necessary, and calls cmdloop.  Cmdloop is
 124 repeatedly parses and executes commands.
 125
 126 OPTIONS.C:  This file contains the option processing code.  It is
 127 called from main to parse the shell arguments when the shell is
 128 invoked, and it also contains the set builtin.  The -i and -j op-
 129 tions (the latter turns on job control) require changes in signal
 130 handling.  The routines setjobctl (in jobs.c) and setinteractive
 131 (in trap.c) are called to handle changes to these options.
 132
 133 PARSING:  The parser code is all in parser.c.  A recursive des-
 134 cent parser is used.  Syntax tables (generated by mksyntax) are
 135 used to classify characters during lexical analysis.  There are
 136 three tables:  one for normal use, one for use when inside single
 137 quotes, and one for use when inside double quotes.  The tables
 138 are machine dependent because they are indexed by character vari-
 139 ables and the range of a char varies from machine to machine.
 140
 141 PARSE OUTPUT:  The output of the parser consists of a tree of
 142 nodes.  The various types of nodes are defined in the file node-
 143 types.
 144
 145 Nodes of type NARG are used to represent both words and the con-
 146 tents of here documents.  An early version of ash kept the con-
 147 tents of here documents in temporary files, but keeping here do-
 148 cuments in memory typically results in significantly better per-
 149 formance.  It would have been nice to make it an option to use
 150 temporary files for here documents, for the benefit of small
 151 machines, but the code to keep track of when to delete the tem-
 152 porary files was complex and I never fixed all the bugs in it.
 153 (AT&T has been maintaining the Bourne shell for more than ten
 154 years, and to the best of my knowledge they still haven't gotten
 155 it to handle temporary files correctly in obscure cases.)
 156
 157 The text field of a NARG structure points to the text of the
 158 word.  The text consists of ordinary characters and a number of
 159 special codes defined in parser.h.  The special codes are:
 160
 161         CTLVAR              Variable substitution
 162         CTLENDVAR           End of variable substitution
 163         CTLBACKQ            Command substitution
 164         CTLBACKQ|CTLQUOTE   Command substitution inside double quotes
 165         CTLESC              Escape next character
 166
 167 A variable substitution contains the following elements:
 168
 169         CTLVAR type name '=' [ alternative-text CTLENDVAR ]
 170
 171 The type field is a single character specifying the type of sub-
 172 stitution.  The possible types are:
 173
 174         VSNORMAL            $var
 175         VSMINUS             ${var-text}
 176         VSMINUS|VSNUL       ${var:-text}
 177         VSPLUS              ${var+text}
 178         VSPLUS|VSNUL        ${var:+text}
 179         VSQUESTION          ${var?text}
 180         VSQUESTION|VSNUL    ${var:?text}
 181         VSASSIGN            ${var=text}
 182         VSASSIGN|VSNUL      ${var=text}
 183
 184 In addition, the type field will have the VSQUOTE flag set if the
 185 variable is enclosed in double quotes.  The name of the variable
 186 comes next, terminated by an equals sign.  If the type is not
 187 VSNORMAL, then the text field in the substitution follows, ter-
 188 minated by a CTLENDVAR byte.
 189
 190 Commands in back quotes are parsed and stored in a linked list.
 191 The locations of these commands in the string are indicated by
 192 CTLBACKQ and CTLBACKQ+CTLQUOTE characters, depending upon whether
 193 the back quotes were enclosed in double quotes.
 194
 195 The character CTLESC escapes the next character, so that in case
 196 any of the CTL characters mentioned above appear in the input,
 197 they can be passed through transparently.  CTLESC is also used to
 198 escape '*', '?', '[', and '!' characters which were quoted by the
 199 user and thus should not be used for file name generation.
 200
 201 CTLESC characters have proved to be particularly tricky to get
 202 right.  In the case of here documents which are not subject to
 203 variable and command substitution, the parser doesn't insert any
 204 CTLESC characters to begin with (so the contents of the text
 205 field can be written without any processing).  Other here docu-
 206 ments, and words which are not subject to splitting and file name
 207 generation, have the CTLESC characters removed during the vari-
 208 able and command substitution phase.  Words which are subject
 209 splitting and file name generation have the CTLESC characters re-
 210 moved as part of the file name phase.
 211
 212 EXECUTION:  Command execution is handled by the following files:
 213         eval.c     The top level routines.
 214         redir.c    Code to handle redirection of input and output.
 215         jobs.c     Code to handle forking, waiting, and job control.
 216         exec.c     Code to to path searches and the actual exec sys call.
 217         expand.c   Code to evaluate arguments.
 218         var.c      Maintains the variable symbol table.  Called from expand.c.
 219
 220 EVAL.C:  Evaltree recursively executes a parse tree.  The exit
 221 status is returned in the global variable exitstatus.  The alter-
 222 native entry evalbackcmd is called to evaluate commands in back
 223 quotes.  It saves the result in memory if the command is a buil-
 224 tin; otherwise it forks off a child to execute the command and
 225 connects the standard output of the child to a pipe.
 226
 227 JOBS.C:  To create a process, you call makejob to return a job
 228 structure, and then call forkshell (passing the job structure as
 229 an argument) to create the process.  Waitforjob waits for a job
 230 to complete.  These routines take care of process groups if job
 231 control is defined.
 232
 233 REDIR.C:  Ash allows file descriptors to be redirected and then
 234 restored without forking off a child process.  This is accom-
 235 plished by duplicating the original file descriptors.  The redir-
 236 tab structure records where the file descriptors have be dupli-
 237 cated to.
 238
 239 EXEC.C:  The routine find_command locates a command, and enters
 240 the command in the hash table if it is not already there.  The
 241 third argument specifies whether it is to print an error message
 242 if the command is not found.  (When a pipeline is set up,
 243 find_command is called for all the commands in the pipeline be-
 244 fore any forking is done, so to get the commands into the hash
 245 table of the parent process.  But to make command hashing as
 246 transparent as possible, we silently ignore errors at that point
 247 and only print error messages if the command cannot be found
 248 later.)
 249
 250 The routine shellexec is the interface to the exec system call.
 251
 252 EXPAND.C:  Arguments are processed in three passes.  The first
 253 (performed by the routine argstr) performs variable and command
 254 substitution.  The second (ifsbreakup) performs word splitting
 255 and the third (expandmeta) performs file name generation.  If the
 256 "/u" directory is simulated, then when "/u/username" is replaced
 257 by the user's home directory, the flag "didudir" is set.  This
 258 tells the cd command that it should print out the directory name,
 259 just as it would if the "/u" directory were implemented using
 260 symbolic links.
 261
 262 VAR.C:  Variables are stored in a hash table.  Probably we should
 263 switch to extensible hashing.  The variable name is stored in the
 264 same string as the value (using the format "name=value") so that
 265 no string copying is needed to create the environment of a com-
 266 mand.  Variables which the shell references internally are preal-
 267 located so that the shell can reference the values of these vari-
 268 ables without doing a lookup.
 269
 270 When a program is run, the code in eval.c sticks any environment
 271 variables which precede the command (as in "PATH=xxx command") in
 272 the variable table as the simplest way to strip duplicates, and
 273 then calls "environment" to get the value of the environment.
 274 There are two consequences of this.  First, if an assignment to
 275 PATH precedes the command, the value of PATH before the assign-
 276 ment must be remembered and passed to shellexec.  Second, if the
 277 program turns out to be a shell procedure, the strings from the
 278 environment variables which preceded the command must be pulled
 279 out of the table and replaced with strings obtained from malloc,
 280 since the former will automatically be freed when the stack (see
 281 the entry on memalloc.c) is emptied.
 282
 283 BUILTIN COMMANDS:  The procedures for handling these are scat-
 284 tered throughout the code, depending on which location appears
 285 most appropriate.  They can be recognized because their names al-
 286 ways end in "cmd".  The mapping from names to procedures is
 287 specified in the file builtins, which is processed by the mkbuil-
 288 tins command.
 289
 290 A builtin command is invoked with argc and argv set up like a
 291 normal program.  A builtin command is allowed to overwrite its
 292 arguments.  Builtin routines can call nextopt to do option pars-
 293 ing.  This is kind of like getopt, but you don't pass argc and
 294 argv to it.  Builtin routines can also call error.  This routine
 295 normally terminates the shell (or returns to the main command
 296 loop if the shell is interactive), but when called from a builtin
 297 command it causes the builtin command to terminate with an exit
 298 status of 2.
 299
 300 The directory bltins contains commands which can be compiled in-
 301 dependently but can also be built into the shell for efficiency
 302 reasons.  The makefile in this directory compiles these programs
 303 in the normal fashion (so that they can be run regardless of
 304 whether the invoker is ash), but also creates a library named
 305 bltinlib.a which can be linked with ash.  The header file bltin.h
 306 takes care of most of the differences between the ash and the
 307 stand-alone environment.  The user should call the main routine
 308 "main", and #define main to be the name of the routine to use
 309 when the program is linked into ash.  This #define should appear
 310 before bltin.h is included; bltin.h will #undef main if the pro-
 311 gram is to be compiled stand-alone.
 312
 313 CD.C:  This file defines the cd and pwd builtins.  The pwd com-
 314 mand runs /bin/pwd the first time it is invoked (unless the user
 315 has already done a cd to an absolute pathname), but then
 316 remembers the current directory and updates it when the cd com-
 317 mand is run, so subsequent pwd commands run very fast.  The main
 318 complication in the cd command is in the docd command, which
 319 resolves symbolic links into actual names and informs the user
 320 where the user ended up if he crossed a symbolic link.
 321
 322 SIGNALS:  Trap.c implements the trap command.  The routine set-
 323 signal figures out what action should be taken when a signal is
 324 received and invokes the signal system call to set the signal ac-
 325 tion appropriately.  When a signal that a user has set a trap for
 326 is caught, the routine "onsig" sets a flag.  The routine dotrap
 327 is called at appropriate points to actually handle the signal.
 328 When an interrupt is caught and no trap has been set for that
 329 signal, the routine "onint" in error.c is called.
 330
 331 OUTPUT:  Ash uses it's own output routines.  There are three out-
 332 put structures allocated.  "Output" represents the standard out-
 333 put, "errout" the standard error, and "memout" contains output
 334 which is to be stored in memory.  This last is used when a buil-
 335 tin command appears in backquotes, to allow its output to be col-
 336 lected without doing any I/O through the UNIX operating system.
 337 The variables out1 and out2 normally point to output and errout,
 338 respectively, but they are set to point to memout when appropri-
 339 ate inside backquotes.
 340
 341 INPUT:  The basic input routine is pgetc, which reads from the
 342 current input file.  There is a stack of input files; the current
 343 input file is the top file on this stack.  The code allows the
 344 input to come from a string rather than a file.  (This is for the
 345 -c option and the "." and eval builtin commands.)  The global
 346 variable plinno is saved and restored when files are pushed and
 347 popped from the stack.  The parser routines store the number of
 348 the current line in this variable.
 349
 350 DEBUGGING:  If DEBUG is defined in shell.h, then the shell will
 351 write debugging information to the file $HOME/trace.  Most of
 352 this is done using the TRACE macro, which takes a set of printf
 353 arguments inside two sets of parenthesis.  Example:
 354 "TRACE(("n=%d0, n))".  The double parenthesis are necessary be-
 355 cause the preprocessor can't handle functions with a variable
 356 number of arguments.  Defining DEBUG also causes the shell to
 357 generate a core dump if it is sent a quit signal.  The tracing
 358 code is in show.c.