From b98072777fd86407714cb3492ac38a2908dc6af3 Mon Sep 17 00:00:00 2001 From: Jilles Tjoelker Date: Sat, 6 May 2017 13:28:42 +0000 Subject: [PATCH] sh: Update TOUR and comments for some code changes, some of them old. Also, improve some terminology in TOUR and comments. --- bin/sh/TOUR | 77 ++++++++++++++++++++++++++++-------------------- bin/sh/eval.c | 2 +- bin/sh/exec.c | 5 ++-- bin/sh/expand.c | 12 ++++---- bin/sh/options.c | 6 ++-- 5 files changed, 58 insertions(+), 44 deletions(-) diff --git a/bin/sh/TOUR b/bin/sh/TOUR index e9bbe9b121b5..14dc3458b65c 100644 --- a/bin/sh/TOUR +++ b/bin/sh/TOUR @@ -24,7 +24,7 @@ programs is: program input files generates ------- ----------- --------- - mkbuiltins builtins builtins.h builtins.c + mkbuiltins builtins.def builtins.h builtins.c mknodes nodetypes nodes.h nodes.c mksyntax - syntax.h syntax.c mktokens - token.h @@ -108,10 +108,12 @@ The text field of a NARG structure points to the text of the word. The text consists of ordinary characters and a number of special codes defined in parser.h. The special codes are: - CTLVAR Variable substitution - CTLENDVAR End of variable substitution + CTLVAR Parameter expansion + CTLENDVAR End of parameter expansion CTLBACKQ Command substitution CTLBACKQ|CTLQUOTE Command substitution inside double quotes + CTLARI Arithmetic expansion + CTLENDARI End of arithmetic expansion CTLESC Escape next character A variable substitution contains the following elements: @@ -130,18 +132,31 @@ stitution. The possible types are: VSQUESTION|VSNUL ${var:?text} VSASSIGN ${var=text} VSASSIGN|VSNUL ${var:=text} + VSTRIMLEFT ${var#text} + VSTRIMLEFTMAX ${var##text} + VSTRIMRIGHT ${var%text} + VSTRIMRIGHTMAX ${var%%text} + VSLENGTH ${#var} + VSERROR delayed error In addition, the type field will have the VSQUOTE flag set if the -variable is enclosed in double quotes. The name of the variable -comes next, terminated by an equals sign. If the type is not -VSNORMAL, then the text field in the substitution follows, ter- -minated by a CTLENDVAR byte. +variable is enclosed in double quotes and the VSLINENO flag if +LINENO is being expanded (the parameter name is the decimal line +number). The parameter's name comes next, terminated by an equals +sign. If the type is not VSNORMAL (including when it is VSLENGTH), +then the text field in the substitution follows, terminated by a +CTLENDVAR byte. + +The type VSERROR is used to allow parsing bad substitutions like +${var[7]} and generate an error when they are expanded. Commands in back quotes are parsed and stored in a linked list. The locations of these commands in the string are indicated by CTLBACKQ and CTLBACKQ+CTLQUOTE characters, depending upon whether the back quotes were enclosed in double quotes. +Arithmetic expansion starts with CTLARI and ends with CTLENDARI. + The character CTLESC escapes the next character, so that in case any of the CTL characters mentioned above appear in the input, they can be passed through transparently. CTLESC is also used to @@ -153,11 +168,11 @@ right. In the case of here documents which are not subject to variable and command substitution, the parser doesn't insert any CTLESC characters to begin with (so the contents of the text field can be written without any processing). Other here docu- -ments, and words which are not subject to splitting and file name -generation, have the CTLESC characters removed during the vari- -able and command substitution phase. Words which are subject to -splitting and file name generation have the CTLESC characters re- -moved as part of the file name phase. +ments, and words which are not subject to file name generation, +have the CTLESC characters removed during the variable and command +substitution phase. Words which are subject to file name +generation have the CTLESC characters removed as part of the file +name phase. EXECUTION: Command execution is handled by the following files: eval.c The top level routines. @@ -199,10 +214,10 @@ later.) The routine shellexec is the interface to the exec system call. -EXPAND.C: Arguments are processed in three passes. The first -(performed by the routine argstr) performs variable and command -substitution. The second (ifsbreakup) performs word splitting -and the third (expandmeta) performs file name generation. +EXPAND.C: As the routine argstr generates words by parameter +expansion, command substitution and arithmetic expansion, it +performs word splitting on the result. As each word is output, +the routine expandmeta performs file name generation (if enabled). VAR.C: Variables are stored in a hash table. Probably we should switch to extensible hashing. The variable name is stored in the @@ -221,8 +236,8 @@ BUILTIN COMMANDS: The procedures for handling these are scat- tered throughout the code, depending on which location appears most appropriate. They can be recognized because their names al- ways end in "cmd". The mapping from names to procedures is -specified in the file builtins, which is processed by the mkbuilt- -ins command. +specified in the file builtins.def, which is processed by the +mkbuiltins command. A builtin command is invoked with argc and argv set up like a normal program. A builtin command is allowed to overwrite its @@ -230,22 +245,20 @@ arguments. Builtin routines can call nextopt to do option pars- ing. This is kind of like getopt, but you don't pass argc and argv to it. Builtin routines can also call error. This routine normally terminates the shell (or returns to the main command -loop if the shell is interactive), but when called from a builtin -command it causes the builtin command to terminate with an exit -status of 2. +loop if the shell is interactive), but when called from a non- +special builtin command it causes the builtin command to +terminate with an exit status of 2. The directory bltins contains commands which can be compiled in- dependently but can also be built into the shell for efficiency -reasons. The makefile in this directory compiles these programs -in the normal fashion (so that they can be run regardless of -whether the invoker is ash), but also creates a library named -bltinlib.a which can be linked with ash. The header file bltin.h -takes care of most of the differences between the ash and the -stand-alone environment. The user should call the main routine -"main", and #define main to be the name of the routine to use -when the program is linked into ash. This #define should appear -before bltin.h is included; bltin.h will #undef main if the pro- -gram is to be compiled stand-alone. +reasons. The header file bltin.h takes care of most of the +differences between the ash and the stand-alone environment. +The user should call the main routine "main", and #define main to +be the name of the routine to use when the program is linked into +ash. This #define should appear before bltin.h is included; +bltin.h will #undef main if the program is to be compiled +stand-alone. A similar approach is used for a few utilities from +bin and usr.bin. CD.C: This file defines the cd and pwd builtins. @@ -258,7 +271,7 @@ is called at appropriate points to actually handle the signal. When an interrupt is caught and no trap has been set for that signal, the routine "onint" in error.c is called. -OUTPUT: Ash uses it's own output routines. There are three out- +OUTPUT: Ash uses its own output routines. There are three out- put structures allocated. "Output" represents the standard out- put, "errout" the standard error, and "memout" contains output which is to be stored in memory. This last is used when a buil- diff --git a/bin/sh/eval.c b/bin/sh/eval.c index a327ba6f048e..e09549295f66 100644 --- a/bin/sh/eval.c +++ b/bin/sh/eval.c @@ -1222,7 +1222,7 @@ bltincmd(int argc, char **argv) return 127; } /* - * Preserve exitstatus of a previous possible redirection + * Preserve exitstatus of a previous possible command substitution * as POSIX mandates */ return exitstatus; diff --git a/bin/sh/exec.c b/bin/sh/exec.c index b8fb41c390ce..fb0868f5c889 100644 --- a/bin/sh/exec.c +++ b/bin/sh/exec.c @@ -338,7 +338,7 @@ find_command(const char *name, struct cmdentry *entry, int act, cd = 0; - /* If name is in the table, and not invalidated by cd, we're done */ + /* If name is in the table, we're done */ if ((cmdp = cmdlookup(name, 0)) != NULL) { if (cmdp->cmdtype == CMDFUNCTION && act & DO_NOFUNC) cmdp = NULL; @@ -485,8 +485,7 @@ changepath(const char *newval __unused) /* - * Clear out command entries. The argument specifies the first entry in - * PATH which has changed. + * Clear out cached utility locations. */ void diff --git a/bin/sh/expand.c b/bin/sh/expand.c index 30f0ec50ec58..74bb63e1f67e 100644 --- a/bin/sh/expand.c +++ b/bin/sh/expand.c @@ -222,9 +222,9 @@ stputs_split(const char *data, const char *syntax, int flag, char *p, * The result is left in the stack string. * When arglist is NULL, perform here document expansion. * - * Caution: this function uses global state and is not reentrant. - * However, a new invocation after an interrupted invocation is safe - * and will reset the global state for the new call. + * When doing something that may cause this to be re-entered, make sure + * the stack string is empty via grabstackstr() and do not assume expdest + * remains valid. */ void expandarg(union node *arg, struct arglist *arglist, int flag) @@ -476,7 +476,7 @@ expbackq(union node *cmd, int quoted, int flag, struct worddest *dst) ifs = ifsset() ? ifsval() : " \t\n"; else ifs = ""; - /* Don't copy trailing newlines */ + /* Remove trailing newlines */ for (;;) { if (--in.nleft < 0) { if (in.fd < 0) @@ -821,7 +821,7 @@ evalvar(const char *p, struct nodelist **restrict argbackq, int flag, /* - * Test whether a specialized variable is set. + * Test whether a special or positional parameter is set. */ static int @@ -918,7 +918,7 @@ reprocess(int startloc, int flag, int subtype, int quoted, } /* - * Add the value of a specialized variable to the stack string. + * Add the value of a special or positional parameter to the stack string. */ static void diff --git a/bin/sh/options.c b/bin/sh/options.c index 8b501f2d1b6a..2ac1a4bb46b0 100644 --- a/bin/sh/options.c +++ b/bin/sh/options.c @@ -141,6 +141,8 @@ optschanged(void) /* * Process shell options. The global variable argptr contains a pointer * to the argument list; we advance it past the options. + * If cmdline is true, process the shell's argv; otherwise, process arguments + * to the set special builtin. */ static void @@ -392,7 +394,7 @@ shiftcmd(int argc, char **argv) /* - * The set command builtin. + * The set builtin command. */ int @@ -558,7 +560,7 @@ getopts(char *optstr, char *optvar, char **optfirst, char ***optnext, /* * Standard option processing (a la getopt) for builtin routines. The * only argument that is passed to nextopt is the option string; the - * other arguments are unnecessary. It return the character, or '\0' on + * other arguments are unnecessary. It returns the option, or '\0' on * end of input. */