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