diff options
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 1437 | ||||
| -rw-r--r-- | doc/gawk.texi | 390 | ||||
| -rw-r--r-- | doc/gawktexi.in | 390 |
4 files changed, 1074 insertions, 1147 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 5ccab2db..d5eaa3a0 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2014-08-15 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Continuing on reviewer comments. + 2014-08-13 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Starting on reviewer comments. diff --git a/doc/gawk.info b/doc/gawk.info index 8035803b..8f91f3c0 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -190,7 +190,7 @@ entitled "GNU Free Documentation License". * Single Character Fields:: Making each character a separate field. * Command Line Field Separator:: Setting `FS' from the - command-line. + command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -216,7 +216,7 @@ entitled "GNU Free Documentation License". `getline'. * Getline Summary:: Summary of `getline' Variants. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -255,7 +255,7 @@ entitled "GNU Free Documentation License". * Variables:: Variables give names to values for later use. * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. * Conversion:: The conversion of strings to numbers @@ -884,7 +884,7 @@ contributed parts of the code as well. In 1988 and 1989, David Trueman, with help from me, thoroughly reworked `gawk' for compatibility with the newer `awk'. Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, performance improvements, -standards compliance, and occasionally, new features. +standards compliance and, occasionally, new features. In May of 1997, Ju"rgen Kahrs felt the need for network access from `awk', and with a little help from me, set about adding features to do @@ -1086,7 +1086,7 @@ formatting language. A single Texinfo source file is used to produce both the printed and online versions of the documentation. This minor node briefly documents the typographical conventions used in Texinfo. - Examples you would type at the command-line are preceded by the + Examples you would type at the command line are preceded by the common shell primary and secondary prompts, `$' and `>'. Input that you type is shown `like this'. Output from the command is preceded by the glyph "-|". This typically represents the command's standard @@ -1456,7 +1456,7 @@ end-of-file character may be different. For example, on OS/2, it is As an example, the following program prints a friendly piece of advice (from Douglas Adams's `The Hitchhiker's Guide to the Galaxy'), to keep you from worrying about the complexities of computer -programming(1) (`BEGIN' is a feature we haven't discussed yet): +programming (`BEGIN' is a feature we haven't discussed yet): $ awk "BEGIN { print \"Don't Panic!\" }" -| Don't Panic! @@ -1464,7 +1464,13 @@ programming(1) (`BEGIN' is a feature we haven't discussed yet): This program does not read any input. The `\' before each of the inner double quotes is necessary because of the shell's quoting rules--in particular because it mixes both single quotes and double -quotes.(2) +quotes.(1) + + NOTE: As a side note, if you use Bash as your shell, you should + execute the command `set +H' before running this program + interactively, to disable the C shell-style command history, which + treats `!' as a special character. We recommend putting this + command into your personal startup file. This next simple `awk' program emulates the `cat' utility; it copies whatever you type on the keyboard to its standard output (why this @@ -1483,12 +1489,7 @@ works is explained shortly). ---------- Footnotes ---------- - (1) If you use Bash as your shell, you should execute the command -`set +H' before running this program interactively, to disable the C -shell-style command history, which treats `!' as a special character. -We recommend putting this command into your personal startup file. - - (2) Although we generally recommend the use of single quotes around + (1) Although we generally recommend the use of single quotes around the program text, double quotes are needed here in order to put the single quote into the message. @@ -1719,9 +1720,9 @@ the quoting rules. Note that the single quote is not special within double quotes. * Null strings are removed when they occur as part of a non-null - command-line argument, while explicit non-null objects are kept. - For example, to specify that the field separator `FS' should be - set to the null string, use: + command-line argument, while explicit null objects are kept. For + example, to specify that the field separator `FS' should be set to + the null string, use: awk -F "" 'PROGRAM' FILES # correct @@ -1814,10 +1815,10 @@ one "record". In the data file `mail-list', each record contains the name of a person, his/her phone number, his/her email-address, and a code for -their relationship with the author of the list. An `A' in the last -column means that the person is an acquaintance. An `F' in the last -column means that the person is a friend. An `R' means that the person -is a relative: +their relationship with the author of the list. The columns are +aligned using spaces. An `A' in the last column means that the person +is an acquaintance. An `F' in the last column means that the person is +a friend. An `R' means that the person is a relative: Amelia 555-5553 amelia.zodiacusque@gmail.com F Anthony 555-3412 anthony.asserturo@hotmail.com A @@ -2505,8 +2506,8 @@ The following list describes options mandated by the POSIX standard: this option is intended to be used with code libraries, `gawk' does not recognize such files as constituting main program input. Thus, after processing an `-i' argument, `gawk' still expects to - find the main source code via the `-f' option or on the - command-line. + find the main source code via the `-f' option or on the command + line. `-l' EXT `--load' EXT @@ -2523,7 +2524,7 @@ The following list describes options mandated by the POSIX standard: `-L'[VALUE] `--lint'[`='VALUE] Warn about constructs that are dubious or nonportable to other - `awk' implementations. No space is allowed between the `-D' and + `awk' implementations. No space is allowed between the `-L' and VALUE, if VALUE is supplied. Some warnings are issued when `gawk' first reads your program. Others are issued at runtime, as your program executes. With an optional argument of `fatal', lint @@ -2603,7 +2604,7 @@ The following list describes options mandated by the POSIX standard: * Newlines are not allowed after `?' or `:' (*note Conditional Exp::). - * Specifying `-Ft' on the command-line does not set the value + * Specifying `-Ft' on the command line does not set the value of `FS' to be a single TAB character (*note Field Separators::). @@ -2785,7 +2786,7 @@ with `getline' (*note Getline/File::). In addition, `gawk' allows you to specify the special file name `/dev/stdin', both on the command line and with `getline'. Some other versions of `awk' also support this, but it is not standard. (Some -operating systems provide a `/dev/stdin' file in the file system; +operating systems provide a `/dev/stdin' file in the filesystem; however, `gawk' always processes this file name itself.) @@ -2811,7 +2812,7 @@ File: gawk.info, Node: AWKPATH Variable, Next: AWKLIBPATH Variable, Up: Envir ---------------------------------------- The previous minor node described how `awk' program files can be named -on the command-line with the `-f' option. In most `awk' +on the command line with the `-f' option. In most `awk' implementations, you must supply a precise path name for each program file, unless the file is in the current directory. But in `gawk', if the file name supplied to the `-f' or `-i' options does not contain a @@ -2898,7 +2899,7 @@ they are more specialized. Those in the following list are meant to be used by regular users. `POSIXLY_CORRECT' - Causes `gawk' to switch POSIX compatibility mode, disabling all + Causes `gawk' to switch to POSIX compatibility mode, disabling all traditional and GNU extensions. *Note Options::. `GAWK_SOCK_RETRIES' @@ -2926,7 +2927,7 @@ change. The variables are: the value should be a number, and `gawk' uses that number as the size of the buffer to allocate. (When this variable is not set, `gawk' uses the smaller of the file's size and the "default" - blocksize, which is usually the file systems I/O blocksize.) + blocksize, which is usually the filesystems I/O blocksize.) `AWK_HASH' If this variable exists with a value of `gst', `gawk' switches to @@ -3160,9 +3161,9 @@ File: gawk.info, Node: Invoking Summary, Prev: Undocumented, Up: Invoking Gaw * Use either `awk 'PROGRAM' FILES' or `awk -f PROGRAM-FILE FILES' to run `awk'. - * The three standard `awk' options are `-f', `-F' and `-v'. `gawk' - supplies these and many others, as well as corresponding GNU-style - long options. + * The three standard options for all versions of `awk' are `-f', + `-F' and `-v'. `gawk' supplies these and many others, as well as + corresponding GNU-style long options. * Non-option command-line arguments are usually treated as file names, unless they have the form `VAR=VALUE', in which case they @@ -3998,7 +3999,7 @@ File: gawk.info, Node: Regexp Summary, Prev: Computed Regexps, Up: Regexp `awk', regular expression constants are written enclosed between slashes: `/'...`/'. - * Regexp constants may be used by standalone in patterns and in + * Regexp constants may be used standalone in patterns and in conditional expressions, or as part of matching expressions using the `~' and `!~' operators. @@ -4022,8 +4023,8 @@ File: gawk.info, Node: Regexp Summary, Prev: Computed Regexps, Up: Regexp extent of the match, such as for text substitution and when the record separator is a regexp. - * Matching expressions may use dynamic regexps; that is string values - treated as regular expressions. + * Matching expressions may use dynamic regexps; that is, string + values treated as regular expressions. @@ -4064,7 +4065,7 @@ have to be named on the `awk' command line (*note Getline::). * Getline:: Reading files under explicit program control using the `getline' function. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on the +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -4246,16 +4247,16 @@ trailing whitespace: $ echo record 1 AAAA record 2 BBBB record 3 | > gawk 'BEGIN { RS = "\n|( *[[:upper:]]+ *)" } - > { print "Record =", $0, "and RT =", RT }' - -| Record = record 1 and RT = AAAA - -| Record = record 2 and RT = BBBB - -| Record = record 3 and RT = - -| + > { print "Record =", $0,"and RT = [" RT "]" }' + -| Record = record 1 and RT = [ AAAA ] + -| Record = record 2 and RT = [ BBBB ] + -| Record = record 3 and RT = [ + -| ] -The final line of output has an extra blank line. This is because the -value of `RT' is a newline, and the `print' statement supplies its own -terminating newline. *Note Simple Sed::, for a more useful example of -`RS' as a regexp and `RT'. +The square brackets delineate the contents of `RT', letting you see the +leading and trailing whitespace. The final value of `RT' `RT' is a +newline. *Note Simple Sed::, for a more useful example of `RS' as a +regexp and `RT'. If you set `RS' to a regular expression that allows optional trailing text, such as `RS = "abc(XYZ)?"' it is possible, due to @@ -4597,7 +4598,7 @@ File: gawk.info, Node: Field Separators, Next: Constant Size, Prev: Changing * Default Field Splitting:: How fields are normally separated. * Regexp Field Splitting:: Using regexps as the field separator. * Single Character Fields:: Making each character a separate field. -* Command Line Field Separator:: Setting `FS' from the command-line. +* Command Line Field Separator:: Setting `FS' from the command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -5761,7 +5762,7 @@ VAR Table 4.1: `getline' Variants and What They Set -File: gawk.info, Node: Read Timeout, Next: Command line directories, Prev: Getline, Up: Reading Files +File: gawk.info, Node: Read Timeout, Next: Command-line directories, Prev: Getline, Up: Reading Files 4.10 Reading Input With A Timeout ================================= @@ -5855,7 +5856,7 @@ writing. (1) This assumes that standard input is the keyboard. -File: gawk.info, Node: Command line directories, Next: Input Summary, Prev: Read Timeout, Up: Reading Files +File: gawk.info, Node: Command-line directories, Next: Input Summary, Prev: Read Timeout, Up: Reading Files 4.11 Directories On The Command Line ==================================== @@ -5878,7 +5879,7 @@ error. usable data from an `awk' program. -File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command line directories, Up: Reading Files +File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-line directories, Up: Reading Files 4.12 Summary ============ @@ -7362,12 +7363,12 @@ For example: } In this example, the programmer wants to pass a regexp constant to -the user-defined function `mysub', which in turn passes it on to either -`sub()' or `gsub()'. However, what really happens is that the `pat' -parameter is either one or zero, depending upon whether or not `$0' -matches `/hi/'. `gawk' issues a warning when it sees a regexp constant -used as a parameter to a user-defined function, since passing a truth -value in this way is probably not what was intended. +the user-defined function `mysub()', which in turn passes it on to +either `sub()' or `gsub()'. However, what really happens is that the +`pat' parameter is either one or zero, depending upon whether or not +`$0' matches `/hi/'. `gawk' issues a warning when it sees a regexp +constant used as a parameter to a user-defined function, since passing +a truth value in this way is probably not what was intended. File: gawk.info, Node: Variables, Next: Conversion, Prev: Using Constant Regexps, Up: Values @@ -7383,7 +7384,7 @@ on the `awk' command line. * Menu: * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line and a +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. @@ -12329,9 +12330,13 @@ File: gawk.info, Node: Gory Details, Up: String Functions 9.1.3.1 More About `\' and `&' with `sub()', `gsub()', and `gensub()' ..................................................................... -When using `sub()', `gsub()', or `gensub()', and trying to get literal -backslashes and ampersands into the replacement text, you need to -remember that there are several levels of "escape processing" going on. + CAUTION: This section has been known to cause headaches. You + might want to skip it upon first reading. + + When using `sub()', `gsub()', or `gensub()', and trying to get +literal backslashes and ampersands into the replacement text, you need +to remember that there are several levels of "escape processing" going +on. First, there is the "lexical" level, which is when `awk' reads your program and builds an internal copy of it to execute. Then there is @@ -12357,13 +12362,13 @@ is illustrated in *note table-sub-escapes::. You type `sub()' sees `sub()' generates ------- --------- -------------- - `\&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\&' `\&' a literal `&' - `\\\\&' `\\&' a literal `\&' - `\\\\\&' `\\&' a literal `\&' - `\\\\\\&' `\\\&' a literal `\\&' - `\\q' `\q' a literal `\q' + `\&' `&' The matched text + `\\&' `\&' A literal `&' + `\\\&' `\&' A literal `&' + `\\\\&' `\\&' A literal `\&' + `\\\\\&' `\\&' A literal `\&' + `\\\\\\&' `\\\&' A literal `\\&' + `\\q' `\q' A literal `\q' Table 9.1: Historical Escape Sequence Processing for `sub()' and `gsub()' @@ -12377,50 +12382,25 @@ backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal `\' followed by the matched text. - The 1992 POSIX standard attempted to fix this problem. That standard -says that `sub()' and `gsub()' look for either a `\' or an `&' after -the `\'. If either one follows a `\', that character is output -literally. The interpretation of `\' and `&' then becomes as shown in -*note table-sub-posix-92::. + Several editions of the POSIX standard attempted to fix this problem +but weren't successful. The details are irrelevant at this point in +time. - You type `sub()' sees `sub()' generates - ------- --------- -------------- - `&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\\&' `\\&' a literal `\', then the matched text - `\\\\\\&' `\\\&' a literal `\&' - -Table 9.2: 1992 POSIX Rules for `sub()' and `gsub()' Escape Sequence -Processing - -This appears to solve the problem. Unfortunately, the phrasing of the -standard is unusual. It says, in effect, that `\' turns off the special -meaning of any following character, but for anything other than `\' and -`&', such special meaning is undefined. This wording leads to two -problems: - - * Backslashes must now be doubled in the REPLACEMENT string, breaking - historical `awk' programs. - - * To make sure that an `awk' program is portable, _every_ character - in the REPLACEMENT string must be preceded with a backslash.(1) - - Because of the problems just listed, in 1996, the `gawk' maintainer -submitted proposed text for a revised standard that reverts to rules -that correspond more closely to the original existing practice. The -proposed rules have special cases that make it possible to produce a -`\' preceding the matched text. This is shown in *note -table-sub-proposed::. + At one point, the `gawk' maintainer submitted proposed text for a +revised standard that reverts to rules that correspond more closely to +the original existing practice. The proposed rules have special cases +that make it possible to produce a `\' preceding the matched text. +This is shown in *note table-sub-proposed::. You type `sub()' sees `sub()' generates ------- --------- -------------- - `\\\\\\&' `\\\&' a literal `\&' - `\\\\&' `\\&' a literal `\', followed by the matched text - `\\&' `\&' a literal `&' - `\\q' `\q' a literal `\q' + `\\\\\\&' `\\\&' A literal `\&' + `\\\\&' `\\&' A literal `\', followed by the matched text + `\\&' `\&' A literal `&' + `\\q' `\q' A literal `\q' `\\\\' `\\' `\\' -Table 9.3: Proposed Rules For `sub()' And Backslash +Table 9.2: GNU `awk' Rules For `sub()' And Backslash In a nutshell, at the runtime level, there are now three special sequences of characters (`\\\&', `\\&' and `\&') whereas historically @@ -12428,11 +12408,11 @@ there was only one. However, as in the historical case, any `\' that is not part of one of these three sequences is not special and appears in the output literally. - `gawk' 3.0 and 3.1 follow these proposed POSIX rules for `sub()' and -`gsub()'. The POSIX standard took much longer to be revised than was -expected in 1996. The 2001 standard does not follow the above rules. -Instead, the rules there are somewhat simpler. The results are similar -except for one case. + `gawk' 3.0 and 3.1 follow these rules for `sub()' and `gsub()'. The +POSIX standard took much longer to be revised than was expected. In +addition, the `gawk' maintainer's proposal was lost during the +standardization process. The final rules are somewhat simpler. The +results are similar except for one case. The POSIX rules state that `\&' in the replacement string produces a literal `&', `\\' produces a literal `\', and `\' followed by anything @@ -12441,25 +12421,25 @@ rules are presented in *note table-posix-sub::. You type `sub()' sees `sub()' generates ------- --------- -------------- - `\\\\\\&' `\\\&' a literal `\&' - `\\\\&' `\\&' a literal `\', followed by the matched text - `\\&' `\&' a literal `&' - `\\q' `\q' a literal `\q' + `\\\\\\&' `\\\&' A literal `\&' + `\\\\&' `\\&' A literal `\', followed by the matched text + `\\&' `\&' A literal `&' + `\\q' `\q' A literal `\q' `\\\\' `\\' `\' -Table 9.4: POSIX Rules For `sub()' And `gsub()' +Table 9.3: POSIX Rules For `sub()' And `gsub()' The only case where the difference is noticeable is the last one: `\\\\' is seen as `\\' and produces `\' instead of `\\'. Starting with version 3.1.4, `gawk' followed the POSIX rules when `--posix' is specified (*note Options::). Otherwise, it continued to -follow the 1996 proposed rules, since that had been its behavior for -many years. +follow the proposed rules, since that had been its behavior for many +years. When version 4.0.0 was released, the `gawk' maintainer made the POSIX rules the default, breaking well over a decade's worth of -backwards compatibility.(2) Needless to say, this was a bad idea, and +backwards compatibility.(1) Needless to say, this was a bad idea, and as of version 4.0.1, `gawk' resumed its historical behavior, and only follows the POSIX rules when `--posix' is given. @@ -12472,14 +12452,14 @@ the `\' does not, as shown in *note table-gensub-escapes::. You type `gensub()' sees `gensub()' generates ------- ------------ ----------------- - `&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\\' `\\' a literal `\' - `\\\\&' `\\&' a literal `\', then the matched text - `\\\\\\&' `\\\&' a literal `\&' - `\\q' `\q' a literal `q' + `&' `&' The matched text + `\\&' `\&' A literal `&' + `\\\\' `\\' A literal `\' + `\\\\&' `\\&' A literal `\', then the matched text + `\\\\\\&' `\\\&' A literal `\&' + `\\q' `\q' A literal `q' -Table 9.5: Escape Sequence Processing For `gensub()' +Table 9.4: Escape Sequence Processing For `gensub()' Because of the complexity of the lexical and runtime level processing and the special cases for `sub()' and `gsub()', we recommend the use of @@ -12498,9 +12478,7 @@ Although this makes a certain amount of sense, it can be surprising. ---------- Footnotes ---------- - (1) This consequence was certainly unintended. - - (2) This was rather naive of him, despite there being a note in this + (1) This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules. @@ -13031,7 +13009,7 @@ table-bitwise-ops::. 0 | 0 0 | 0 1 | 0 1 1 | 0 1 | 1 1 | 1 0 -Table 9.6: Bitwise Operations +Table 9.5: Bitwise Operations As you can see, the result of an AND operation is 1 only when _both_ bits are 1. The result of an OR operation is 1 if _either_ bit is 1. @@ -13385,22 +13363,22 @@ standard.) The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. -In this case, the recursion terminates when the starting position is -zero, i.e., when there are no more characters left in the string. +In this case, the recursion terminates when the input string is already +empty. - function rev(str, start) + function rev(str) { - if (start == 0) + if (str == "") return "" - return (substr(str, start, 1) rev(str, start - 1)) + return (rev(substr(str, 2)) substr(str, 1, 1)) } If this function is in a file named `rev.awk', it can be tested this way: $ echo "Don't Panic!" | - > gawk --source '{ print rev($0, length($0)) }' -f rev.awk + > gawk --source '{ print rev($0) }' -f rev.awk -| !cinaP t'noD The C `ctime()' function takes a timestamp and returns it in a @@ -13650,8 +13628,8 @@ function _are_ visible outside that function. a[1], a[2], a[3] } - prints `a[1] = 1, a[2] = two, a[3] = 3', because `changeit' stores - `"two"' in the second element of `a'. + prints `a[1] = 1, a[2] = two, a[3] = 3', because `changeit()' + stores `"two"' in the second element of `a'. Some `awk' implementations allow you to call a function that has not been defined. They only report a problem at runtime when the program @@ -19201,24 +19179,7 @@ File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Array Sort 12.3 Two-Way Communications with Another Process ================================================ - From: brennan@whidbey.com (Mike Brennan) - Newsgroups: comp.lang.awk - Subject: Re: Learn the SECRET to Attract Women Easily - Date: 4 Aug 1997 17:34:46 GMT - Message-ID: <5s53rm$eca@news.whidbey.com> - - On 3 Aug 1997 13:17:43 GMT, Want More Dates??? - <tracy78@kilgrona.com> wrote: - >Learn the SECRET to Attract Women Easily - > - >The SCENT(tm) Pheromone Sex Attractant For Men to Attract Women - - The scent of awk programmers is a lot more attractive to women than - the scent of perl programmers. - -- - Mike Brennan - - It is often useful to be able to send data to a separate program for +It is often useful to be able to send data to a separate program for processing and then read the result. This can always be done with temporary files: @@ -19237,12 +19198,11 @@ temporary files: This works, but not elegantly. Among other things, it requires that the program be run in a directory that cannot be shared among users; for example, `/tmp' will not do, as another user might happen to be -using a temporary file with the same name. - - However, with `gawk', it is possible to open a _two-way_ pipe to -another process. The second process is termed a "coprocess", since it -runs in parallel with `gawk'. The two-way connection is created using -the `|&' operator (borrowed from the Korn shell, `ksh'):(1) +using a temporary file with the same name.(1) However, with `gawk', it +is possible to open a _two-way_ pipe to another process. The second +process is termed a "coprocess", since it runs in parallel with `gawk'. +The two-way connection is created using the `|&' operator (borrowed +from the Korn shell, `ksh'):(2) do { print DATA |& "subprogram" @@ -19329,7 +19289,11 @@ using regular pipes. ---------- Footnotes ---------- - (1) This is very different from the same operator in the C shell and + (1) Michael Brennan suggests the use of `rand()' to generate unique +file names. This is a valid point; nevertheless, temporary files remain +more difficult than two-way pipes. + + (2) This is very different from the same operator in the C shell and in Bash. @@ -19352,7 +19316,7 @@ network connection. You can think of this as just a _very long_ two-way pipeline to a coprocess. The way `gawk' decides that you want to use TCP/IP networking is by recognizing special file names that begin with one of -`/inet/', `/inet4/' or `/inet6'. +`/inet/', `/inet4/' or `/inet6/'. The full syntax of the special file name is `/NET-TYPE/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT'. The @@ -21389,6 +21353,10 @@ in `gawk'. It continues on to present arbitrary precision integers, and concludes with a description of some points where `gawk' and the POSIX standard are not quite in agreement. + NOTE: Most users of `gawk' can safely skip this chapter. But if + you want to do scientific calculations with `gawk', this is the + place to be. + * Menu: * Computer Arithmetic:: A quick intro to computer math. @@ -21519,9 +21487,18 @@ material here. number and infinity produce infinity. "NaN" - "Not A Number." A special value indicating a result that can't - happen in real math, but that can happen in floating-point - computations. + "Not A Number."(1). A special value that results from attempting a + calculation that has no answer as a real number. In such a case, + programs can either receive a floating-point exception, or get + `NaN' back as the result. The IEEE 754 standard recommends that + systems return `NaN'. Some examples: + + `sqrt(-1)' + This makes sense in the range of complex numbers, but not in + the range of real numbers, so the result is `NaN'. + + `log(-8)' + -8 is out of the domain of `log()', so the result is `NaN'. "Normalized" How the significand (see later in this list) is usually stored. The @@ -21579,6 +21556,11 @@ Table 15.1: Basic IEEE Format Context Values NOTE: The precision numbers include the implied leading one that gives them one extra bit of significand. + ---------- Footnotes ---------- + + (1) Thanks to Michael Brennan for this description, which I have +paraphrased, and for the examples + File: gawk.info, Node: MPFR features, Next: FP Math Caution, Prev: Math Definitions, Up: Arbitrary Precision Arithmetic @@ -21906,7 +21888,7 @@ on arithmetic operations: of a constant. If you need to represent a floating-point constant at a higher - precision than the default and cannot use a command line + precision than the default and cannot use a command-line assignment to `PREC', you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a @@ -22401,7 +22383,7 @@ Example::) and also the `testext.c' code for testing the APIs. Some other bits and pieces: * The API provides access to `gawk''s `do_XXX' values, reflecting - command line options, like `do_lint', `do_profiling' and so on + command-line options, like `do_lint', `do_profiling' and so on (*note Extension API Variables::). These are informational: an extension cannot affect their values inside `gawk'. In addition, attempting to assign to them produces a compile-time error. @@ -25995,7 +25977,7 @@ the current version of `gawk'. - Indirect function calls (*note Indirect Calls::). - Directories on the command line produce a warning and are - skipped (*note Command line directories::). + skipped (*note Command-line directories::). * New keywords: @@ -26165,7 +26147,7 @@ in POSIX `awk', in the order they were added to `gawk'. * The ability to delete all of an array at once with `delete ARRAY' (*note Delete::). - * Command line option changes (*note Options::): + * Command-line option changes (*note Options::): - The ability to use GNU-style long-named options that start with `--'. @@ -26202,7 +26184,7 @@ in POSIX `awk', in the order they were added to `gawk'. * The `fflush()' function from Brian Kernighan's `awk' (then at Bell Laboratories; *note I/O Functions::). - * New command line options: + * New command-line options: - The `--lint-old' option to warn about constructs that are not available in the original Version 7 Unix version of `awk' @@ -26395,7 +26377,7 @@ in POSIX `awk', in the order they were added to `gawk'. * `switch' / `case' are enabled by default (*note Switch Statement::). - * Command line option changes (*note Options::): + * Command-line option changes (*note Options::): - The `-b' and `--characters-as-bytes' options which prevent `gawk' from treating input as a multibyte string. @@ -26413,7 +26395,7 @@ in POSIX `awk', in the order they were added to `gawk'. * Directories named on the command line now produce a warning, not a fatal error, unless `--posix' or `--traditional' are used (*note - Command line directories::). + Command-line directories::). * The `gawk' internals were rewritten, bringing the `dgawk' debugger and possibly improved performance (*note Debugger::). @@ -26462,10 +26444,10 @@ in POSIX `awk', in the order they were added to `gawk'. `PROCINFO["identifiers"]' (*note Auto-set::). * The three executables `gawk', `pgawk', and `dgawk', were merged - into one, named just `gawk'. As a result the command line options + into one, named just `gawk'. As a result the command-line options changed. - * Command line option changes (*note Options::): + * Command-line option changes (*note Options::): - The `-D' option invokes the debugger. @@ -30945,7 +30927,7 @@ Index * * (asterisk), * operator, as regexp operator: Regexp Operators. (line 88) * * (asterisk), * operator, null strings, matching: Gory Details. - (line 164) + (line 143) * * (asterisk), ** operator <1>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) * * (asterisk), **= operator <1>: Precedence. (line 95) @@ -31026,7 +31008,7 @@ Index * -F option: Options. (line 21) * -f option: Long. (line 12) * -F option, -Ft sets FS to TAB: Options. (line 308) -* -F option, command line: Command Line Field Separator. +* -F option, command-line: Command Line Field Separator. (line 6) * -f option, multiple uses: Options. (line 313) * -g option: Options. (line 147) @@ -31184,7 +31166,7 @@ Index * advanced features, network programming: TCP/IP Networking. (line 6) * advanced features, nondecimal input data: Nondecimal Data. (line 6) * advanced features, processes, communicating with: Two-way I/O. - (line 23) + (line 6) * advanced features, specifying field content: Splitting By Content. (line 10) * Aho, Alfred <1>: Contributors. (line 11) @@ -31304,7 +31286,7 @@ Index * asterisk (*), * operator, as regexp operator: Regexp Operators. (line 88) * asterisk (*), * operator, null strings, matching: Gory Details. - (line 164) + (line 143) * asterisk (*), ** operator <1>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) * asterisk (*), **= operator <1>: Precedence. (line 95) @@ -31507,12 +31489,11 @@ Index * breakpoint, how to disable or enable: Breakpoint Control. (line 69) * breakpoint, setting: Breakpoint Control. (line 11) * Brennan, Michael <1>: Other Versions. (line 6) -* Brennan, Michael <2>: Two-way I/O. (line 6) -* Brennan, Michael <3>: Simple Sed. (line 25) -* Brennan, Michael <4>: Delete. (line 56) +* Brennan, Michael <2>: Simple Sed. (line 25) +* Brennan, Michael <3>: Delete. (line 56) * Brennan, Michael: Foreword. (line 83) * Brian Kernighan's awk <1>: I/O Functions. (line 43) -* Brian Kernighan's awk <2>: Gory Details. (line 15) +* Brian Kernighan's awk <2>: Gory Details. (line 19) * Brian Kernighan's awk <3>: String Functions. (line 490) * Brian Kernighan's awk <4>: Delete. (line 48) * Brian Kernighan's awk <5>: Nextfile Statement. (line 47) @@ -31539,7 +31520,7 @@ Index * Buening, Andreas <1>: Bugs. (line 71) * Buening, Andreas <2>: Contributors. (line 92) * Buening, Andreas: Acknowledgments. (line 60) -* buffering, input/output <1>: Two-way I/O. (line 70) +* buffering, input/output <1>: Two-way I/O. (line 52) * buffering, input/output: I/O Functions. (line 140) * buffering, interactive vs. noninteractive: I/O Functions. (line 109) * buffers, flushing: I/O Functions. (line 32) @@ -31607,7 +31588,7 @@ Index (line 81) * close() function, return value: Close Files And Pipes. (line 131) -* close() function, two-way pipes and: Two-way I/O. (line 77) +* close() function, two-way pipes and: Two-way I/O. (line 59) * Close, Diane <1>: Contributors. (line 20) * Close, Diane: Manual History. (line 34) * Collado, Manuel: Acknowledgments. (line 60) @@ -31622,7 +31603,7 @@ Index * command line, arguments <1>: ARGC and ARGV. (line 6) * command line, arguments <2>: Auto-set. (line 15) * command line, arguments: Other Arguments. (line 6) -* command line, directories on: Command line directories. +* command line, directories on: Command-line directories. (line 6) * command line, formats: Running gawk. (line 12) * command line, FS on, setting: Command Line Field Separator. @@ -31714,7 +31695,7 @@ Index * CONVFMT variable, and array subscripts: Numeric Array Subscripts. (line 6) * cookie: Glossary. (line 149) -* coprocesses <1>: Two-way I/O. (line 44) +* coprocesses <1>: Two-way I/O. (line 25) * coprocesses: Redirection. (line 102) * coprocesses, closing: Close Files And Pipes. (line 6) @@ -31724,7 +31705,7 @@ Index * counting: Wc Program. (line 6) * csh utility: Statements/Lines. (line 44) * csh utility, POSIXLY_CORRECT environment variable: Options. (line 355) -* csh utility, |& operator, comparison with: Two-way I/O. (line 44) +* csh utility, |& operator, comparison with: Two-way I/O. (line 25) * ctime() user-defined function: Function Example. (line 73) * currency symbols, localization: Explaining gettext. (line 104) * current system time: Time Functions. (line 66) @@ -31800,7 +31781,7 @@ Index * dcngettext: I18N Functions. (line 28) * dcngettext() function (gawk), portability and: I18N Portability. (line 33) -* deadlocks: Two-way I/O. (line 70) +* deadlocks: Two-way I/O. (line 52) * debugger commands, b (break): Breakpoint Control. (line 11) * debugger commands, backtrace: Execution Stack. (line 13) * debugger commands, break: Breakpoint Control. (line 11) @@ -31943,7 +31924,7 @@ Index (line 15) * differences in awk and gawk, close() function: Close Files And Pipes. (line 81) -* differences in awk and gawk, command line directories: Command line directories. +* differences in awk and gawk, command-line directories: Command-line directories. (line 6) * differences in awk and gawk, ERRNO variable: Auto-set. (line 74) * differences in awk and gawk, error messages: Special FD. (line 16) @@ -31996,7 +31977,7 @@ Index (line 152) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. (line 66) -* directories, command line: Command line directories. +* directories, command-line: Command-line directories. (line 6) * directories, searching: Programs Exercises. (line 63) * directories, searching for loadable extensions: AWKLIBPATH Variable. @@ -32464,7 +32445,7 @@ Index * gawk, newlines in: Statements/Lines. (line 12) * gawk, octal numbers and: Nondecimal-numbers. (line 42) * gawk, OS/2 version of: PC Using. (line 16) -* gawk, PROCINFO array in <1>: Two-way I/O. (line 117) +* gawk, PROCINFO array in <1>: Two-way I/O. (line 99) * gawk, PROCINFO array in <2>: Time Functions. (line 47) * gawk, PROCINFO array in: Auto-set. (line 128) * gawk, regexp constants and: Using Constant Regexps. @@ -32515,7 +32496,7 @@ Index (line 6) * getline command, coprocesses, using from: Getline/Coprocess. (line 6) -* getline command, deadlock and: Two-way I/O. (line 70) +* getline command, deadlock and: Two-way I/O. (line 52) * getline command, explicit input with: Getline. (line 6) * getline command, FILENAME variable and: Getline Notes. (line 19) * getline command, return values: Getline. (line 19) @@ -32661,7 +32642,7 @@ Index * input/output functions: I/O Functions. (line 6) * input/output, binary: User-modified. (line 15) * input/output, from BEGIN and END: I/O And BEGIN/END. (line 6) -* input/output, two-way: Two-way I/O. (line 44) +* input/output, two-way: Two-way I/O. (line 25) * insomnia, cure for: Alarm Program. (line 6) * installation, VMS: VMS Installation. (line 6) * installing gawk: Installation. (line 6) @@ -32852,7 +32833,7 @@ Index * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) -* matching, null strings: Gory Details. (line 164) +* matching, null strings: Gory Details. (line 143) * mawk utility <1>: Other Versions. (line 44) * mawk utility <2>: Nextfile Statement. (line 47) * mawk utility <3>: Concatenation. (line 36) @@ -32946,7 +32927,7 @@ Index (line 43) * null strings, converting numbers to strings: Strings And Numbers. (line 21) -* null strings, matching: Gory Details. (line 164) +* null strings, matching: Gory Details. (line 143) * number as string of bits: Bitwise Functions. (line 109) * number of array elements: String Functions. (line 197) * number sign (#), #! (executable scripts): Executable Scripts. @@ -33152,7 +33133,7 @@ Index * POSIX awk, field separators and: Fields. (line 6) * POSIX awk, FS variable and: User-modified. (line 60) * POSIX awk, function keyword in: Definition Syntax. (line 89) -* POSIX awk, functions and, gsub()/sub(): Gory Details. (line 54) +* POSIX awk, functions and, gsub()/sub(): Gory Details. (line 90) * POSIX awk, functions and, length(): String Functions. (line 176) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 136) @@ -33214,12 +33195,12 @@ Index * private variables: Library Names. (line 11) * process group idIDof gawk process: Auto-set. (line 175) * process ID of gawk process: Auto-set. (line 178) -* processes, two-way communications with: Two-way I/O. (line 23) +* processes, two-way communications with: Two-way I/O. (line 6) * processing data: Basic High Level. (line 6) * PROCINFO array <1>: Passwd Functions. (line 6) * PROCINFO array <2>: Time Functions. (line 47) * PROCINFO array: Auto-set. (line 128) -* PROCINFO array, and communications via ptys: Two-way I/O. (line 117) +* PROCINFO array, and communications via ptys: Two-way I/O. (line 99) * PROCINFO array, and group membership: Group Functions. (line 6) * PROCINFO array, and user and group ID numbers: Id Program. (line 15) * PROCINFO array, testing the field splitting: Passwd Functions. @@ -33231,7 +33212,6 @@ Index * profiling awk programs, dynamically: Profiling. (line 179) * program identifiers: Auto-set. (line 146) * program, definition of: Getting Started. (line 21) -* programmers, attractiveness of: Two-way I/O. (line 6) * programming conventions, --non-decimal-data option: Nondecimal Data. (line 36) * programming conventions, ARGC/ARGV variables: Auto-set. (line 35) @@ -33531,7 +33511,7 @@ Index (line 64) * sidebar, Interactive Versus Noninteractive Buffering: I/O Functions. (line 107) -* sidebar, Matching the Null String: Gory Details. (line 162) +* sidebar, Matching the Null String: Gory Details. (line 141) * sidebar, Operator Evaluation Order: Increment Ops. (line 58) * sidebar, Piping into sh: Redirection. (line 140) * sidebar, Portability Issues with #!: Executable Scripts. (line 31) @@ -33580,7 +33560,7 @@ Index * sort function, arrays, sorting: Array Sorting Functions. (line 6) * sort utility: Word Sorting. (line 50) -* sort utility, coprocesses and: Two-way I/O. (line 83) +* sort utility, coprocesses and: Two-way I/O. (line 65) * sorting characters in different languages: Explaining gettext. (line 94) * source code, awka: Other Versions. (line 64) @@ -33872,7 +33852,7 @@ Index * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) -* vertical bar (|), |& operator (I/O) <1>: Two-way I/O. (line 44) +* vertical bar (|), |& operator (I/O) <1>: Two-way I/O. (line 25) * vertical bar (|), |& operator (I/O) <2>: Precedence. (line 65) * vertical bar (|), |& operator (I/O): Getline/Coprocess. (line 6) * vertical bar (|), || operator <1>: Precedence. (line 89) @@ -33934,7 +33914,7 @@ Index * | (vertical bar), | operator (I/O) <1>: Precedence. (line 65) * | (vertical bar), | operator (I/O) <2>: Redirection. (line 57) * | (vertical bar), | operator (I/O): Getline/Pipe. (line 9) -* | (vertical bar), |& operator (I/O) <1>: Two-way I/O. (line 44) +* | (vertical bar), |& operator (I/O) <1>: Two-way I/O. (line 25) * | (vertical bar), |& operator (I/O) <2>: Precedence. (line 65) * | (vertical bar), |& operator (I/O) <3>: Redirection. (line 102) * | (vertical bar), |& operator (I/O): Getline/Coprocess. (line 6) @@ -33974,532 +33954,531 @@ Node: Getting Started70816 Node: Running gawk73250 Node: One-shot74440 Node: Read Terminal75665 -Ref: Read Terminal-Footnote-177315 -Ref: Read Terminal-Footnote-277591 -Node: Long77762 -Node: Executable Scripts79138 -Ref: Executable Scripts-Footnote-180971 -Ref: Executable Scripts-Footnote-281073 -Node: Comments81620 -Node: Quoting84093 -Node: DOS Quoting89409 -Node: Sample Data Files90084 -Node: Very Simple92599 -Node: Two Rules97372 -Node: More Complex99266 -Ref: More Complex-Footnote-1102198 -Node: Statements/Lines102283 -Ref: Statements/Lines-Footnote-1106739 -Node: Other Features107004 -Node: When107932 -Node: Intro Summary110102 -Node: Invoking Gawk110868 -Node: Command Line112383 -Node: Options113174 -Ref: Options-Footnote-1129003 -Node: Other Arguments129028 -Node: Naming Standard Input131690 -Node: Environment Variables132784 -Node: AWKPATH Variable133342 -Ref: AWKPATH Variable-Footnote-1136214 -Ref: AWKPATH Variable-Footnote-2136259 -Node: AWKLIBPATH Variable136519 -Node: Other Environment Variables137278 -Node: Exit Status140933 -Node: Include Files141608 -Node: Loading Shared Libraries145186 -Node: Obsolete146570 -Node: Undocumented147267 -Node: Invoking Summary147534 -Node: Regexp149114 -Node: Regexp Usage150564 -Node: Escape Sequences152597 -Node: Regexp Operators158264 -Ref: Regexp Operators-Footnote-1165744 -Ref: Regexp Operators-Footnote-2165891 -Node: Bracket Expressions165989 -Ref: table-char-classes167879 -Node: GNU Regexp Operators170819 -Node: Case-sensitivity174542 -Ref: Case-sensitivity-Footnote-1177434 -Ref: Case-sensitivity-Footnote-2177669 -Node: Leftmost Longest177777 -Node: Computed Regexps178978 -Node: Regexp Summary182350 -Node: Reading Files183821 -Node: Records185913 -Node: awk split records186656 -Node: gawk split records191514 -Ref: gawk split records-Footnote-1196035 -Node: Fields196072 -Ref: Fields-Footnote-1199036 -Node: Nonconstant Fields199122 -Ref: Nonconstant Fields-Footnote-1201352 -Node: Changing Fields201554 -Node: Field Separators207508 -Node: Default Field Splitting210210 -Node: Regexp Field Splitting211327 -Node: Single Character Fields214668 -Node: Command Line Field Separator215727 -Node: Full Line Fields219069 -Ref: Full Line Fields-Footnote-1219577 -Node: Field Splitting Summary219623 -Ref: Field Splitting Summary-Footnote-1222722 -Node: Constant Size222823 -Node: Splitting By Content227430 -Ref: Splitting By Content-Footnote-1231180 -Node: Multiple Line231220 -Ref: Multiple Line-Footnote-1237076 -Node: Getline237255 -Node: Plain Getline239471 -Node: Getline/Variable241566 -Node: Getline/File242713 -Node: Getline/Variable/File244097 -Ref: Getline/Variable/File-Footnote-1245696 -Node: Getline/Pipe245783 -Node: Getline/Variable/Pipe248482 -Node: Getline/Coprocess249589 -Node: Getline/Variable/Coprocess250841 -Node: Getline Notes251578 -Node: Getline Summary254382 -Ref: table-getline-variants254790 -Node: Read Timeout255702 -Ref: Read Timeout-Footnote-1259529 -Node: Command line directories259587 -Node: Input Summary260491 -Node: Input Exercises263628 -Node: Printing264361 -Node: Print266083 -Node: Print Examples267424 -Node: Output Separators270203 -Node: OFMT272219 -Node: Printf273577 -Node: Basic Printf274483 -Node: Control Letters276022 -Node: Format Modifiers280013 -Node: Printf Examples286040 -Node: Redirection288504 -Node: Special Files295476 -Node: Special FD296007 -Ref: Special FD-Footnote-1299604 -Node: Special Network299678 -Node: Special Caveats300528 -Node: Close Files And Pipes301324 -Ref: Close Files And Pipes-Footnote-1308485 -Ref: Close Files And Pipes-Footnote-2308633 -Node: Output Summary308783 -Node: Output exercises309780 -Node: Expressions310460 -Node: Values311645 -Node: Constants312321 -Node: Scalar Constants313001 -Ref: Scalar Constants-Footnote-1313860 -Node: Nondecimal-numbers314110 -Node: Regexp Constants317110 -Node: Using Constant Regexps317585 -Node: Variables320655 -Node: Using Variables321310 -Node: Assignment Options323034 -Node: Conversion324909 -Node: Strings And Numbers325433 -Ref: Strings And Numbers-Footnote-1328495 -Node: Locale influences conversions328604 -Ref: table-locale-affects331321 -Node: All Operators331909 -Node: Arithmetic Ops332539 -Node: Concatenation335044 -Ref: Concatenation-Footnote-1337863 -Node: Assignment Ops337983 -Ref: table-assign-ops342966 -Node: Increment Ops344283 -Node: Truth Values and Conditions347721 -Node: Truth Values348804 -Node: Typing and Comparison349853 -Node: Variable Typing350646 -Node: Comparison Operators354296 -Ref: table-relational-ops354706 -Node: POSIX String Comparison358256 -Ref: POSIX String Comparison-Footnote-1359340 -Node: Boolean Ops359478 -Ref: Boolean Ops-Footnote-1363548 -Node: Conditional Exp363639 -Node: Function Calls365366 -Node: Precedence369246 -Node: Locales372915 -Node: Expressions Summary374546 -Node: Patterns and Actions377087 -Node: Pattern Overview378203 -Node: Regexp Patterns379880 -Node: Expression Patterns380423 -Node: Ranges384204 -Node: BEGIN/END387310 -Node: Using BEGIN/END388072 -Ref: Using BEGIN/END-Footnote-1390808 -Node: I/O And BEGIN/END390914 -Node: BEGINFILE/ENDFILE393199 -Node: Empty396130 -Node: Using Shell Variables396447 -Node: Action Overview398730 -Node: Statements401057 -Node: If Statement402905 -Node: While Statement404403 -Node: Do Statement406447 -Node: For Statement407603 -Node: Switch Statement410755 -Node: Break Statement412858 -Node: Continue Statement414913 -Node: Next Statement416706 -Node: Nextfile Statement419096 -Node: Exit Statement421751 -Node: Built-in Variables424155 -Node: User-modified425282 -Ref: User-modified-Footnote-1432971 -Node: Auto-set433033 -Ref: Auto-set-Footnote-1445615 -Ref: Auto-set-Footnote-2445820 -Node: ARGC and ARGV445876 -Node: Pattern Action Summary449730 -Node: Arrays451953 -Node: Array Basics453502 -Node: Array Intro454328 -Ref: figure-array-elements456301 -Node: Reference to Elements458708 -Node: Assigning Elements460981 -Node: Array Example461472 -Node: Scanning an Array463204 -Node: Controlling Scanning466219 -Ref: Controlling Scanning-Footnote-1471392 -Node: Delete471708 -Ref: Delete-Footnote-1474473 -Node: Numeric Array Subscripts474530 -Node: Uninitialized Subscripts476713 -Node: Multidimensional478338 -Node: Multiscanning481431 -Node: Arrays of Arrays483020 -Node: Arrays Summary487683 -Node: Functions489788 -Node: Built-in490661 -Node: Calling Built-in491739 -Node: Numeric Functions493727 -Ref: Numeric Functions-Footnote-1497669 -Ref: Numeric Functions-Footnote-2498026 -Ref: Numeric Functions-Footnote-3498074 -Node: String Functions498343 -Ref: String Functions-Footnote-1521354 -Ref: String Functions-Footnote-2521483 -Ref: String Functions-Footnote-3521731 -Node: Gory Details521818 -Ref: table-sub-escapes523487 -Ref: table-sub-posix-92524841 -Ref: table-sub-proposed526192 -Ref: table-posix-sub527546 -Ref: table-gensub-escapes529091 -Ref: Gory Details-Footnote-1530267 -Ref: Gory Details-Footnote-2530318 -Node: I/O Functions530469 -Ref: I/O Functions-Footnote-1537592 -Node: Time Functions537739 -Ref: Time Functions-Footnote-1548203 -Ref: Time Functions-Footnote-2548271 -Ref: Time Functions-Footnote-3548429 -Ref: Time Functions-Footnote-4548540 -Ref: Time Functions-Footnote-5548652 -Ref: Time Functions-Footnote-6548879 -Node: Bitwise Functions549145 -Ref: table-bitwise-ops549707 -Ref: Bitwise Functions-Footnote-1553952 -Node: Type Functions554136 -Node: I18N Functions555278 -Node: User-defined556923 -Node: Definition Syntax557727 -Ref: Definition Syntax-Footnote-1562906 -Node: Function Example562975 -Ref: Function Example-Footnote-1565619 -Node: Function Caveats565641 -Node: Calling A Function566159 -Node: Variable Scope567114 -Node: Pass By Value/Reference570102 -Node: Return Statement573610 -Node: Dynamic Typing576594 -Node: Indirect Calls577523 -Node: Functions Summary587236 -Node: Library Functions589775 -Ref: Library Functions-Footnote-1593393 -Ref: Library Functions-Footnote-2593536 -Node: Library Names593707 -Ref: Library Names-Footnote-1597180 -Ref: Library Names-Footnote-2597400 -Node: General Functions597486 -Node: Strtonum Function598514 -Node: Assert Function601294 -Node: Round Function604620 -Node: Cliff Random Function606161 -Node: Ordinal Functions607177 -Ref: Ordinal Functions-Footnote-1610254 -Ref: Ordinal Functions-Footnote-2610506 -Node: Join Function610717 -Ref: Join Function-Footnote-1612488 -Node: Getlocaltime Function612688 -Node: Readfile Function616424 -Node: Data File Management618263 -Node: Filetrans Function618895 -Node: Rewind Function622964 -Node: File Checking624522 -Ref: File Checking-Footnote-1625654 -Node: Empty Files625855 -Node: Ignoring Assigns627834 -Node: Getopt Function629388 -Ref: Getopt Function-Footnote-1640691 -Node: Passwd Functions640894 -Ref: Passwd Functions-Footnote-1649873 -Node: Group Functions649961 -Ref: Group Functions-Footnote-1657902 -Node: Walking Arrays658115 -Node: Library Functions Summary659718 -Node: Library exercises661106 -Node: Sample Programs662386 -Node: Running Examples663156 -Node: Clones663884 -Node: Cut Program665108 -Node: Egrep Program674976 -Ref: Egrep Program-Footnote-1682947 -Node: Id Program683057 -Node: Split Program686721 -Ref: Split Program-Footnote-1690259 -Node: Tee Program690387 -Node: Uniq Program693194 -Node: Wc Program700624 -Ref: Wc Program-Footnote-1704889 -Node: Miscellaneous Programs704981 -Node: Dupword Program706194 -Node: Alarm Program708225 -Node: Translate Program713039 -Ref: Translate Program-Footnote-1717430 -Ref: Translate Program-Footnote-2717700 -Node: Labels Program717834 -Ref: Labels Program-Footnote-1721205 -Node: Word Sorting721289 -Node: History Sorting725332 -Node: Extract Program727168 -Node: Simple Sed734704 -Node: Igawk Program737766 -Ref: Igawk Program-Footnote-1752077 -Ref: Igawk Program-Footnote-2752278 -Node: Anagram Program752416 -Node: Signature Program755484 -Node: Programs Summary756731 -Node: Programs Exercises757946 -Node: Advanced Features761597 -Node: Nondecimal Data763545 -Node: Array Sorting765122 -Node: Controlling Array Traversal765819 -Node: Array Sorting Functions774099 -Ref: Array Sorting Functions-Footnote-1778006 -Node: Two-way I/O778200 -Ref: Two-way I/O-Footnote-1783716 -Node: TCP/IP Networking783798 -Node: Profiling786642 -Node: Advanced Features Summary794184 -Node: Internationalization796048 -Node: I18N and L10N797528 -Node: Explaining gettext798214 -Ref: Explaining gettext-Footnote-1803354 -Ref: Explaining gettext-Footnote-2803538 -Node: Programmer i18n803703 -Node: Translator i18n807928 -Node: String Extraction808722 -Ref: String Extraction-Footnote-1809683 -Node: Printf Ordering809769 -Ref: Printf Ordering-Footnote-1812551 -Node: I18N Portability812615 -Ref: I18N Portability-Footnote-1815064 -Node: I18N Example815127 -Ref: I18N Example-Footnote-1817849 -Node: Gawk I18N817921 -Node: I18N Summary818559 -Node: Debugger819898 -Node: Debugging820920 -Node: Debugging Concepts821361 -Node: Debugging Terms823217 -Node: Awk Debugging825814 -Node: Sample Debugging Session826706 -Node: Debugger Invocation827226 -Node: Finding The Bug828559 -Node: List of Debugger Commands835041 -Node: Breakpoint Control836373 -Node: Debugger Execution Control840037 -Node: Viewing And Changing Data843397 -Node: Execution Stack846755 -Node: Debugger Info848268 -Node: Miscellaneous Debugger Commands852262 -Node: Readline Support857446 -Node: Limitations858338 -Node: Debugging Summary860612 -Node: Arbitrary Precision Arithmetic861776 -Node: Computer Arithmetic863105 -Ref: Computer Arithmetic-Footnote-1867492 -Node: Math Definitions867549 -Ref: table-ieee-formats870433 -Node: MPFR features870937 -Node: FP Math Caution872579 -Ref: FP Math Caution-Footnote-1873620 -Node: Inexactness of computations873989 -Node: Inexact representation874937 -Node: Comparing FP Values876292 -Node: Errors accumulate877256 -Node: Getting Accuracy878689 -Node: Try To Round881348 -Node: Setting precision882247 -Ref: table-predefined-precision-strings882929 -Node: Setting the rounding mode884722 -Ref: table-gawk-rounding-modes885086 -Ref: Setting the rounding mode-Footnote-1888540 -Node: Arbitrary Precision Integers888719 -Ref: Arbitrary Precision Integers-Footnote-1891722 -Node: POSIX Floating Point Problems891871 -Ref: POSIX Floating Point Problems-Footnote-1895747 -Node: Floating point summary895785 -Node: Dynamic Extensions898002 -Node: Extension Intro899554 -Node: Plugin License900819 -Node: Extension Mechanism Outline901504 -Ref: figure-load-extension901928 -Ref: figure-load-new-function903413 -Ref: figure-call-new-function904415 -Node: Extension API Description906399 -Node: Extension API Functions Introduction907849 -Node: General Data Types912714 -Ref: General Data Types-Footnote-1918407 -Node: Requesting Values918706 -Ref: table-value-types-returned919443 -Node: Memory Allocation Functions920401 -Ref: Memory Allocation Functions-Footnote-1923148 -Node: Constructor Functions923244 -Node: Registration Functions925002 -Node: Extension Functions925687 -Node: Exit Callback Functions927989 -Node: Extension Version String929238 -Node: Input Parsers929888 -Node: Output Wrappers939702 -Node: Two-way processors944218 -Node: Printing Messages946422 -Ref: Printing Messages-Footnote-1947499 -Node: Updating `ERRNO'947651 -Node: Accessing Parameters948390 -Node: Symbol Table Access949620 -Node: Symbol table by name950134 -Node: Symbol table by cookie952110 -Ref: Symbol table by cookie-Footnote-1956243 -Node: Cached values956306 -Ref: Cached values-Footnote-1959810 -Node: Array Manipulation959901 -Ref: Array Manipulation-Footnote-1960999 -Node: Array Data Types961038 -Ref: Array Data Types-Footnote-1963741 -Node: Array Functions963833 -Node: Flattening Arrays967707 -Node: Creating Arrays974559 -Node: Extension API Variables979290 -Node: Extension Versioning979926 -Node: Extension API Informational Variables981827 -Node: Extension API Boilerplate982913 -Node: Finding Extensions986717 -Node: Extension Example987277 -Node: Internal File Description988007 -Node: Internal File Ops992098 -Ref: Internal File Ops-Footnote-11003530 -Node: Using Internal File Ops1003670 -Ref: Using Internal File Ops-Footnote-11006017 -Node: Extension Samples1006285 -Node: Extension Sample File Functions1007809 -Node: Extension Sample Fnmatch1015377 -Node: Extension Sample Fork1016859 -Node: Extension Sample Inplace1018072 -Node: Extension Sample Ord1019747 -Node: Extension Sample Readdir1020583 -Ref: table-readdir-file-types1021439 -Node: Extension Sample Revout1022238 -Node: Extension Sample Rev2way1022829 -Node: Extension Sample Read write array1023570 -Node: Extension Sample Readfile1025449 -Node: Extension Sample API Tests1026549 -Node: Extension Sample Time1027074 -Node: gawkextlib1028389 -Node: Extension summary1031202 -Node: Extension Exercises1034895 -Node: Language History1035617 -Node: V7/SVR3.11037260 -Node: SVR41039580 -Node: POSIX1041022 -Node: BTL1042408 -Node: POSIX/GNU1043142 -Node: Feature History1048885 -Node: Common Extensions1062015 -Node: Ranges and Locales1063327 -Ref: Ranges and Locales-Footnote-11067944 -Ref: Ranges and Locales-Footnote-21067971 -Ref: Ranges and Locales-Footnote-31068205 -Node: Contributors1068426 -Node: History summary1073851 -Node: Installation1075220 -Node: Gawk Distribution1076171 -Node: Getting1076655 -Node: Extracting1077479 -Node: Distribution contents1079121 -Node: Unix Installation1084838 -Node: Quick Installation1085455 -Node: Additional Configuration Options1087897 -Node: Configuration Philosophy1089635 -Node: Non-Unix Installation1091986 -Node: PC Installation1092444 -Node: PC Binary Installation1093755 -Node: PC Compiling1095603 -Ref: PC Compiling-Footnote-11098602 -Node: PC Testing1098707 -Node: PC Using1099883 -Node: Cygwin1104041 -Node: MSYS1104850 -Node: VMS Installation1105364 -Node: VMS Compilation1106160 -Ref: VMS Compilation-Footnote-11107382 -Node: VMS Dynamic Extensions1107440 -Node: VMS Installation Details1108813 -Node: VMS Running1111065 -Node: VMS GNV1113899 -Node: VMS Old Gawk1114622 -Node: Bugs1115092 -Node: Other Versions1119096 -Node: Installation summary1125351 -Node: Notes1126407 -Node: Compatibility Mode1127272 -Node: Additions1128054 -Node: Accessing The Source1128979 -Node: Adding Code1130415 -Node: New Ports1136593 -Node: Derived Files1141074 -Ref: Derived Files-Footnote-11146155 -Ref: Derived Files-Footnote-21146189 -Ref: Derived Files-Footnote-31146785 -Node: Future Extensions1146899 -Node: Implementation Limitations1147505 -Node: Extension Design1148753 -Node: Old Extension Problems1149907 -Ref: Old Extension Problems-Footnote-11151424 -Node: Extension New Mechanism Goals1151481 -Ref: Extension New Mechanism Goals-Footnote-11154841 -Node: Extension Other Design Decisions1155030 -Node: Extension Future Growth1157136 -Node: Old Extension Mechanism1157972 -Node: Notes summary1159734 -Node: Basic Concepts1160920 -Node: Basic High Level1161601 -Ref: figure-general-flow1161873 -Ref: figure-process-flow1162472 -Ref: Basic High Level-Footnote-11165701 -Node: Basic Data Typing1165886 -Node: Glossary1169214 -Node: Copying1194366 -Node: GNU Free Documentation License1231922 -Node: Index1257058 +Ref: Read Terminal-Footnote-177628 +Node: Long77799 +Node: Executable Scripts79175 +Ref: Executable Scripts-Footnote-181008 +Ref: Executable Scripts-Footnote-281110 +Node: Comments81657 +Node: Quoting84130 +Node: DOS Quoting89443 +Node: Sample Data Files90118 +Node: Very Simple92672 +Node: Two Rules97445 +Node: More Complex99339 +Ref: More Complex-Footnote-1102271 +Node: Statements/Lines102356 +Ref: Statements/Lines-Footnote-1106812 +Node: Other Features107077 +Node: When108005 +Node: Intro Summary110175 +Node: Invoking Gawk110941 +Node: Command Line112456 +Node: Options113247 +Ref: Options-Footnote-1129076 +Node: Other Arguments129101 +Node: Naming Standard Input131763 +Node: Environment Variables132856 +Node: AWKPATH Variable133414 +Ref: AWKPATH Variable-Footnote-1136286 +Ref: AWKPATH Variable-Footnote-2136331 +Node: AWKLIBPATH Variable136591 +Node: Other Environment Variables137350 +Node: Exit Status141007 +Node: Include Files141682 +Node: Loading Shared Libraries145260 +Node: Obsolete146644 +Node: Undocumented147341 +Node: Invoking Summary147608 +Node: Regexp149208 +Node: Regexp Usage150658 +Node: Escape Sequences152691 +Node: Regexp Operators158358 +Ref: Regexp Operators-Footnote-1165838 +Ref: Regexp Operators-Footnote-2165985 +Node: Bracket Expressions166083 +Ref: table-char-classes167973 +Node: GNU Regexp Operators170913 +Node: Case-sensitivity174636 +Ref: Case-sensitivity-Footnote-1177528 +Ref: Case-sensitivity-Footnote-2177763 +Node: Leftmost Longest177871 +Node: Computed Regexps179072 +Node: Regexp Summary182444 +Node: Reading Files183913 +Node: Records186005 +Node: awk split records186748 +Node: gawk split records191606 +Ref: gawk split records-Footnote-1196127 +Node: Fields196164 +Ref: Fields-Footnote-1199128 +Node: Nonconstant Fields199214 +Ref: Nonconstant Fields-Footnote-1201444 +Node: Changing Fields201646 +Node: Field Separators207600 +Node: Default Field Splitting210302 +Node: Regexp Field Splitting211419 +Node: Single Character Fields214760 +Node: Command Line Field Separator215819 +Node: Full Line Fields219161 +Ref: Full Line Fields-Footnote-1219669 +Node: Field Splitting Summary219715 +Ref: Field Splitting Summary-Footnote-1222814 +Node: Constant Size222915 +Node: Splitting By Content227522 +Ref: Splitting By Content-Footnote-1231272 +Node: Multiple Line231312 +Ref: Multiple Line-Footnote-1237168 +Node: Getline237347 +Node: Plain Getline239563 +Node: Getline/Variable241658 +Node: Getline/File242805 +Node: Getline/Variable/File244189 +Ref: Getline/Variable/File-Footnote-1245788 +Node: Getline/Pipe245875 +Node: Getline/Variable/Pipe248574 +Node: Getline/Coprocess249681 +Node: Getline/Variable/Coprocess250933 +Node: Getline Notes251670 +Node: Getline Summary254474 +Ref: table-getline-variants254882 +Node: Read Timeout255794 +Ref: Read Timeout-Footnote-1259621 +Node: Command-line directories259679 +Node: Input Summary260583 +Node: Input Exercises263720 +Node: Printing264453 +Node: Print266175 +Node: Print Examples267516 +Node: Output Separators270295 +Node: OFMT272311 +Node: Printf273669 +Node: Basic Printf274575 +Node: Control Letters276114 +Node: Format Modifiers280105 +Node: Printf Examples286132 +Node: Redirection288596 +Node: Special Files295568 +Node: Special FD296099 +Ref: Special FD-Footnote-1299696 +Node: Special Network299770 +Node: Special Caveats300620 +Node: Close Files And Pipes301416 +Ref: Close Files And Pipes-Footnote-1308577 +Ref: Close Files And Pipes-Footnote-2308725 +Node: Output Summary308875 +Node: Output exercises309872 +Node: Expressions310552 +Node: Values311737 +Node: Constants312413 +Node: Scalar Constants313093 +Ref: Scalar Constants-Footnote-1313952 +Node: Nondecimal-numbers314202 +Node: Regexp Constants317202 +Node: Using Constant Regexps317677 +Node: Variables320749 +Node: Using Variables321404 +Node: Assignment Options323128 +Node: Conversion325003 +Node: Strings And Numbers325527 +Ref: Strings And Numbers-Footnote-1328589 +Node: Locale influences conversions328698 +Ref: table-locale-affects331415 +Node: All Operators332003 +Node: Arithmetic Ops332633 +Node: Concatenation335138 +Ref: Concatenation-Footnote-1337957 +Node: Assignment Ops338077 +Ref: table-assign-ops343060 +Node: Increment Ops344377 +Node: Truth Values and Conditions347815 +Node: Truth Values348898 +Node: Typing and Comparison349947 +Node: Variable Typing350740 +Node: Comparison Operators354390 +Ref: table-relational-ops354800 +Node: POSIX String Comparison358350 +Ref: POSIX String Comparison-Footnote-1359434 +Node: Boolean Ops359572 +Ref: Boolean Ops-Footnote-1363642 +Node: Conditional Exp363733 +Node: Function Calls365460 +Node: Precedence369340 +Node: Locales373009 +Node: Expressions Summary374640 +Node: Patterns and Actions377181 +Node: Pattern Overview378297 +Node: Regexp Patterns379974 +Node: Expression Patterns380517 +Node: Ranges384298 +Node: BEGIN/END387404 +Node: Using BEGIN/END388166 +Ref: Using BEGIN/END-Footnote-1390902 +Node: I/O And BEGIN/END391008 +Node: BEGINFILE/ENDFILE393293 +Node: Empty396224 +Node: Using Shell Variables396541 +Node: Action Overview398824 +Node: Statements401151 +Node: If Statement402999 +Node: While Statement404497 +Node: Do Statement406541 +Node: For Statement407697 +Node: Switch Statement410849 +Node: Break Statement412952 +Node: Continue Statement415007 +Node: Next Statement416800 +Node: Nextfile Statement419190 +Node: Exit Statement421845 +Node: Built-in Variables424249 +Node: User-modified425376 +Ref: User-modified-Footnote-1433065 +Node: Auto-set433127 +Ref: Auto-set-Footnote-1445709 +Ref: Auto-set-Footnote-2445914 +Node: ARGC and ARGV445970 +Node: Pattern Action Summary449824 +Node: Arrays452047 +Node: Array Basics453596 +Node: Array Intro454422 +Ref: figure-array-elements456395 +Node: Reference to Elements458802 +Node: Assigning Elements461075 +Node: Array Example461566 +Node: Scanning an Array463298 +Node: Controlling Scanning466313 +Ref: Controlling Scanning-Footnote-1471486 +Node: Delete471802 +Ref: Delete-Footnote-1474567 +Node: Numeric Array Subscripts474624 +Node: Uninitialized Subscripts476807 +Node: Multidimensional478432 +Node: Multiscanning481525 +Node: Arrays of Arrays483114 +Node: Arrays Summary487777 +Node: Functions489882 +Node: Built-in490755 +Node: Calling Built-in491833 +Node: Numeric Functions493821 +Ref: Numeric Functions-Footnote-1497763 +Ref: Numeric Functions-Footnote-2498120 +Ref: Numeric Functions-Footnote-3498168 +Node: String Functions498437 +Ref: String Functions-Footnote-1521448 +Ref: String Functions-Footnote-2521577 +Ref: String Functions-Footnote-3521825 +Node: Gory Details521912 +Ref: table-sub-escapes523699 +Ref: table-sub-proposed525219 +Ref: table-posix-sub526583 +Ref: table-gensub-escapes528123 +Ref: Gory Details-Footnote-1529299 +Node: I/O Functions529450 +Ref: I/O Functions-Footnote-1536573 +Node: Time Functions536720 +Ref: Time Functions-Footnote-1547184 +Ref: Time Functions-Footnote-2547252 +Ref: Time Functions-Footnote-3547410 +Ref: Time Functions-Footnote-4547521 +Ref: Time Functions-Footnote-5547633 +Ref: Time Functions-Footnote-6547860 +Node: Bitwise Functions548126 +Ref: table-bitwise-ops548688 +Ref: Bitwise Functions-Footnote-1552933 +Node: Type Functions553117 +Node: I18N Functions554259 +Node: User-defined555904 +Node: Definition Syntax556708 +Ref: Definition Syntax-Footnote-1561887 +Node: Function Example561956 +Ref: Function Example-Footnote-1564520 +Node: Function Caveats564542 +Node: Calling A Function565060 +Node: Variable Scope566015 +Node: Pass By Value/Reference569003 +Node: Return Statement572513 +Node: Dynamic Typing575497 +Node: Indirect Calls576426 +Node: Functions Summary586139 +Node: Library Functions588678 +Ref: Library Functions-Footnote-1592296 +Ref: Library Functions-Footnote-2592439 +Node: Library Names592610 +Ref: Library Names-Footnote-1596083 +Ref: Library Names-Footnote-2596303 +Node: General Functions596389 +Node: Strtonum Function597417 +Node: Assert Function600197 +Node: Round Function603523 +Node: Cliff Random Function605064 +Node: Ordinal Functions606080 +Ref: Ordinal Functions-Footnote-1609157 +Ref: Ordinal Functions-Footnote-2609409 +Node: Join Function609620 +Ref: Join Function-Footnote-1611391 +Node: Getlocaltime Function611591 +Node: Readfile Function615327 +Node: Data File Management617166 +Node: Filetrans Function617798 +Node: Rewind Function621867 +Node: File Checking623425 +Ref: File Checking-Footnote-1624557 +Node: Empty Files624758 +Node: Ignoring Assigns626737 +Node: Getopt Function628291 +Ref: Getopt Function-Footnote-1639594 +Node: Passwd Functions639797 +Ref: Passwd Functions-Footnote-1648776 +Node: Group Functions648864 +Ref: Group Functions-Footnote-1656805 +Node: Walking Arrays657018 +Node: Library Functions Summary658621 +Node: Library exercises660009 +Node: Sample Programs661289 +Node: Running Examples662059 +Node: Clones662787 +Node: Cut Program664011 +Node: Egrep Program673879 +Ref: Egrep Program-Footnote-1681850 +Node: Id Program681960 +Node: Split Program685624 +Ref: Split Program-Footnote-1689162 +Node: Tee Program689290 +Node: Uniq Program692097 +Node: Wc Program699527 +Ref: Wc Program-Footnote-1703792 +Node: Miscellaneous Programs703884 +Node: Dupword Program705097 +Node: Alarm Program707128 +Node: Translate Program711942 +Ref: Translate Program-Footnote-1716333 +Ref: Translate Program-Footnote-2716603 +Node: Labels Program716737 +Ref: Labels Program-Footnote-1720108 +Node: Word Sorting720192 +Node: History Sorting724235 +Node: Extract Program726071 +Node: Simple Sed733607 +Node: Igawk Program736669 +Ref: Igawk Program-Footnote-1750980 +Ref: Igawk Program-Footnote-2751181 +Node: Anagram Program751319 +Node: Signature Program754387 +Node: Programs Summary755634 +Node: Programs Exercises756849 +Node: Advanced Features760500 +Node: Nondecimal Data762448 +Node: Array Sorting764025 +Node: Controlling Array Traversal764722 +Node: Array Sorting Functions773002 +Ref: Array Sorting Functions-Footnote-1776909 +Node: Two-way I/O777103 +Ref: Two-way I/O-Footnote-1782047 +Ref: Two-way I/O-Footnote-2782226 +Node: TCP/IP Networking782308 +Node: Profiling785153 +Node: Advanced Features Summary792695 +Node: Internationalization794559 +Node: I18N and L10N796039 +Node: Explaining gettext796725 +Ref: Explaining gettext-Footnote-1801865 +Ref: Explaining gettext-Footnote-2802049 +Node: Programmer i18n802214 +Node: Translator i18n806439 +Node: String Extraction807233 +Ref: String Extraction-Footnote-1808194 +Node: Printf Ordering808280 +Ref: Printf Ordering-Footnote-1811062 +Node: I18N Portability811126 +Ref: I18N Portability-Footnote-1813575 +Node: I18N Example813638 +Ref: I18N Example-Footnote-1816360 +Node: Gawk I18N816432 +Node: I18N Summary817070 +Node: Debugger818409 +Node: Debugging819431 +Node: Debugging Concepts819872 +Node: Debugging Terms821728 +Node: Awk Debugging824325 +Node: Sample Debugging Session825217 +Node: Debugger Invocation825737 +Node: Finding The Bug827070 +Node: List of Debugger Commands833552 +Node: Breakpoint Control834884 +Node: Debugger Execution Control838548 +Node: Viewing And Changing Data841908 +Node: Execution Stack845266 +Node: Debugger Info846779 +Node: Miscellaneous Debugger Commands850773 +Node: Readline Support855957 +Node: Limitations856849 +Node: Debugging Summary859123 +Node: Arbitrary Precision Arithmetic860287 +Node: Computer Arithmetic861774 +Ref: Computer Arithmetic-Footnote-1866161 +Node: Math Definitions866218 +Ref: table-ieee-formats869507 +Ref: Math Definitions-Footnote-1870047 +Node: MPFR features870150 +Node: FP Math Caution871792 +Ref: FP Math Caution-Footnote-1872833 +Node: Inexactness of computations873202 +Node: Inexact representation874150 +Node: Comparing FP Values875505 +Node: Errors accumulate876469 +Node: Getting Accuracy877902 +Node: Try To Round880561 +Node: Setting precision881460 +Ref: table-predefined-precision-strings882142 +Node: Setting the rounding mode883935 +Ref: table-gawk-rounding-modes884299 +Ref: Setting the rounding mode-Footnote-1887753 +Node: Arbitrary Precision Integers887932 +Ref: Arbitrary Precision Integers-Footnote-1890935 +Node: POSIX Floating Point Problems891084 +Ref: POSIX Floating Point Problems-Footnote-1894960 +Node: Floating point summary894998 +Node: Dynamic Extensions897215 +Node: Extension Intro898767 +Node: Plugin License900032 +Node: Extension Mechanism Outline900717 +Ref: figure-load-extension901141 +Ref: figure-load-new-function902626 +Ref: figure-call-new-function903628 +Node: Extension API Description905612 +Node: Extension API Functions Introduction907062 +Node: General Data Types911927 +Ref: General Data Types-Footnote-1917620 +Node: Requesting Values917919 +Ref: table-value-types-returned918656 +Node: Memory Allocation Functions919614 +Ref: Memory Allocation Functions-Footnote-1922361 +Node: Constructor Functions922457 +Node: Registration Functions924215 +Node: Extension Functions924900 +Node: Exit Callback Functions927202 +Node: Extension Version String928451 +Node: Input Parsers929101 +Node: Output Wrappers938915 +Node: Two-way processors943431 +Node: Printing Messages945635 +Ref: Printing Messages-Footnote-1946712 +Node: Updating `ERRNO'946864 +Node: Accessing Parameters947603 +Node: Symbol Table Access948833 +Node: Symbol table by name949347 +Node: Symbol table by cookie951323 +Ref: Symbol table by cookie-Footnote-1955456 +Node: Cached values955519 +Ref: Cached values-Footnote-1959023 +Node: Array Manipulation959114 +Ref: Array Manipulation-Footnote-1960212 +Node: Array Data Types960251 +Ref: Array Data Types-Footnote-1962954 +Node: Array Functions963046 +Node: Flattening Arrays966920 +Node: Creating Arrays973772 +Node: Extension API Variables978503 +Node: Extension Versioning979139 +Node: Extension API Informational Variables981040 +Node: Extension API Boilerplate982126 +Node: Finding Extensions985930 +Node: Extension Example986490 +Node: Internal File Description987220 +Node: Internal File Ops991311 +Ref: Internal File Ops-Footnote-11002743 +Node: Using Internal File Ops1002883 +Ref: Using Internal File Ops-Footnote-11005230 +Node: Extension Samples1005498 +Node: Extension Sample File Functions1007022 +Node: Extension Sample Fnmatch1014590 +Node: Extension Sample Fork1016072 +Node: Extension Sample Inplace1017285 +Node: Extension Sample Ord1018960 +Node: Extension Sample Readdir1019796 +Ref: table-readdir-file-types1020652 +Node: Extension Sample Revout1021451 +Node: Extension Sample Rev2way1022042 +Node: Extension Sample Read write array1022783 +Node: Extension Sample Readfile1024662 +Node: Extension Sample API Tests1025762 +Node: Extension Sample Time1026287 +Node: gawkextlib1027602 +Node: Extension summary1030415 +Node: Extension Exercises1034108 +Node: Language History1034830 +Node: V7/SVR3.11036473 +Node: SVR41038793 +Node: POSIX1040235 +Node: BTL1041621 +Node: POSIX/GNU1042355 +Node: Feature History1048098 +Node: Common Extensions1061228 +Node: Ranges and Locales1062540 +Ref: Ranges and Locales-Footnote-11067157 +Ref: Ranges and Locales-Footnote-21067184 +Ref: Ranges and Locales-Footnote-31067418 +Node: Contributors1067639 +Node: History summary1073064 +Node: Installation1074433 +Node: Gawk Distribution1075384 +Node: Getting1075868 +Node: Extracting1076692 +Node: Distribution contents1078334 +Node: Unix Installation1084051 +Node: Quick Installation1084668 +Node: Additional Configuration Options1087110 +Node: Configuration Philosophy1088848 +Node: Non-Unix Installation1091199 +Node: PC Installation1091657 +Node: PC Binary Installation1092968 +Node: PC Compiling1094816 +Ref: PC Compiling-Footnote-11097815 +Node: PC Testing1097920 +Node: PC Using1099096 +Node: Cygwin1103254 +Node: MSYS1104063 +Node: VMS Installation1104577 +Node: VMS Compilation1105373 +Ref: VMS Compilation-Footnote-11106595 +Node: VMS Dynamic Extensions1106653 +Node: VMS Installation Details1108026 +Node: VMS Running1110278 +Node: VMS GNV1113112 +Node: VMS Old Gawk1113835 +Node: Bugs1114305 +Node: Other Versions1118309 +Node: Installation summary1124564 +Node: Notes1125620 +Node: Compatibility Mode1126485 +Node: Additions1127267 +Node: Accessing The Source1128192 +Node: Adding Code1129628 +Node: New Ports1135806 +Node: Derived Files1140287 +Ref: Derived Files-Footnote-11145368 +Ref: Derived Files-Footnote-21145402 +Ref: Derived Files-Footnote-31145998 +Node: Future Extensions1146112 +Node: Implementation Limitations1146718 +Node: Extension Design1147966 +Node: Old Extension Problems1149120 +Ref: Old Extension Problems-Footnote-11150637 +Node: Extension New Mechanism Goals1150694 +Ref: Extension New Mechanism Goals-Footnote-11154054 +Node: Extension Other Design Decisions1154243 +Node: Extension Future Growth1156349 +Node: Old Extension Mechanism1157185 +Node: Notes summary1158947 +Node: Basic Concepts1160133 +Node: Basic High Level1160814 +Ref: figure-general-flow1161086 +Ref: figure-process-flow1161685 +Ref: Basic High Level-Footnote-11164914 +Node: Basic Data Typing1165099 +Node: Glossary1168427 +Node: Copying1193579 +Node: GNU Free Documentation License1231135 +Node: Index1256271 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 89a212c3..2a5565c9 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -51,7 +51,7 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH June, 2014 +@set UPDATE-MONTH August, 2014 @set VERSION 4.1 @set PATCHLEVEL 1 @@ -546,7 +546,7 @@ particular records in a file and perform operations upon them. * Single Character Fields:: Making each character a separate field. * Command Line Field Separator:: Setting @code{FS} from the - command-line. + command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -572,7 +572,7 @@ particular records in a file and perform operations upon them. @code{getline}. * Getline Summary:: Summary of @code{getline} Variants. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -611,7 +611,7 @@ particular records in a file and perform operations upon them. * Variables:: Variables give names to values for later use. * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. * Conversion:: The conversion of strings to numbers @@ -1404,7 +1404,7 @@ help from me, thoroughly reworked @command{gawk} for compatibility with the newer @command{awk}. Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, -performance improvements, standards compliance, and occasionally, new features. +performance improvements, standards compliance and, occasionally, new features. In May of 1997, J@"urgen Kahrs felt the need for network access from @command{awk}, and with a little help from me, set about adding @@ -1697,7 +1697,7 @@ are slightly different than in other books you may have read. This @value{SECTION} briefly documents the typographical conventions used in Texinfo. @end ifinfo -Examples you would type at the command-line are preceded by the common +Examples you would type at the command line are preceded by the common shell primary and secondary prompts, @samp{$} and @samp{>}. Input that you type is shown @kbd{like this}. Output from the command is preceded by the glyph ``@print{}''. @@ -2335,12 +2335,7 @@ For example, on OS/2, it is @kbd{Ctrl-z}.) As an example, the following program prints a friendly piece of advice (from Douglas Adams's @cite{The Hitchhiker's Guide to the Galaxy}), to keep you from worrying about the complexities of computer -programming@footnote{If you use Bash as your shell, you should execute -the command @samp{set +H} before running this program interactively, -to disable the C shell-style command history, which treats -@samp{!} as a special character. We recommend putting this command into -your personal startup file.} -(@code{BEGIN} is a feature we haven't discussed yet): +programming (@code{BEGIN} is a feature we haven't discussed yet): @example $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @@ -2359,6 +2354,14 @@ double quotes.@footnote{Although we generally recommend the use of single quotes around the program text, double quotes are needed here in order to put the single quote into the message.} +@quotation NOTE +As a side note, if you use Bash as your shell, you should execute the +command @samp{set +H} before running this program interactively, to +disable the C shell-style command history, which treats @samp{!} as a +special character. We recommend putting this command into your personal +startup file. +@end quotation + This next simple @command{awk} program emulates the @command{cat} utility; it copies whatever you type on the keyboard to its standard output (why this works is explained shortly). @@ -2715,7 +2718,7 @@ Note that the single quote is not special within double quotes. @item Null strings are removed when they occur as part of a non-null -command-line argument, while explicit non-null objects are kept. +command-line argument, while explicit null objects are kept. For example, to specify that the field separator @code{FS} should be set to the null string, use: @@ -2862,7 +2865,9 @@ each line is considered to be one @dfn{record}. In the @value{DF} @file{mail-list}, each record contains the name of a person, his/her phone number, his/her email-address, and a code for their relationship -with the author of the list. An @samp{A} in the last column +with the author of the list. +The columns are aligned using spaces. +An @samp{A} in the last column means that the person is an acquaintance. An @samp{F} in the last column means that the person is a friend. An @samp{R} means that the person is a relative: @@ -3780,7 +3785,7 @@ Second, because this option is intended to be used with code libraries, @command{gawk} does not recognize such files as constituting main program input. Thus, after processing an @option{-i} argument, @command{gawk} still expects to find the main source code via the @option{-f} option -or on the command-line. +or on the command line. @item @option{-l} @var{ext} @itemx @option{--load} @var{ext} @@ -3804,7 +3809,7 @@ a shared library. This feature is described in detail in @ref{Dynamic Extension @cindex warnings, issuing Warn about constructs that are dubious or nonportable to other @command{awk} implementations. -No space is allowed between the @option{-D} and @var{value}, if +No space is allowed between the @option{-L} and @var{value}, if @var{value} is supplied. Some warnings are issued when @command{gawk} first reads your program. Others are issued at runtime, as your program executes. @@ -3925,7 +3930,7 @@ Newlines are not allowed after @samp{?} or @samp{:} @cindex @code{FS} variable, as TAB character @item -Specifying @samp{-Ft} on the command-line does not set the value +Specifying @samp{-Ft} on the command line does not set the value of @code{FS} to be a single TAB character (@pxref{Field Separators}). @@ -4171,7 +4176,7 @@ with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file -in the file system; however, @command{gawk} always processes +in the filesystem; however, @command{gawk} always processes this @value{FN} itself.) @node Environment Variables @@ -4197,7 +4202,7 @@ behaves. @cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable @ifinfo The previous @value{SECTION} described how @command{awk} program files can be named -on the command-line with the @option{-f} option. +on the command line with the @option{-f} option. @end ifinfo In most @command{awk} implementations, you must supply a precise path name for each program @@ -4292,7 +4297,7 @@ list are meant to be used by regular users. @table @env @item POSIXLY_CORRECT -Causes @command{gawk} to switch POSIX compatibility +Causes @command{gawk} to switch to POSIX compatibility mode, disabling all traditional and GNU extensions. @xref{Options}. @@ -4325,7 +4330,7 @@ file as the size of the memory buffer to allocate for I/O. Otherwise, the value should be a number, and @command{gawk} uses that number as the size of the buffer to allocate. (When this variable is not set, @command{gawk} uses the smaller of the file's size and the ``default'' -blocksize, which is usually the file systems I/O blocksize.) +blocksize, which is usually the filesystems I/O blocksize.) @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} @@ -4663,9 +4668,9 @@ or to run @command{awk}. @item -The three standard @command{awk} options are @option{-f}, @option{-F} -and @option{-v}. @command{gawk} supplies these and many others, as well -as corresponding GNU-style long options. +The three standard options for all versions of @command{awk} are +@option{-f}, @option{-F} and @option{-v}. @command{gawk} supplies these +and many others, as well as corresponding GNU-style long options. @item Non-option command-line arguments are usually treated as @value{FN}s, @@ -6001,7 +6006,7 @@ In @command{awk}, regular expression constants are written enclosed between slashes: @code{/}@dots{}@code{/}. @item -Regexp constants may be used by standalone in patterns and +Regexp constants may be used standalone in patterns and in conditional expressions, or as part of matching expressions using the @samp{~} and @samp{!~} operators. @@ -6031,7 +6036,7 @@ the match, such as for text substitution and when the record separator is a regexp. @item -Matching expressions may use dynamic regexps; that is string values +Matching expressions may use dynamic regexps; that is, string values treated as regular expressions. @end itemize @@ -6083,7 +6088,7 @@ used with it do not have to be named on the @command{awk} command line * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on the +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -6314,17 +6319,17 @@ with optional leading and/or trailing whitespace: @example $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} > @kbd{gawk 'BEGIN @{ RS = "\n|( *[[:upper:]]+ *)" @}} -> @kbd{@{ print "Record =", $0, "and RT =", RT @}'} -@print{} Record = record 1 and RT = AAAA -@print{} Record = record 2 and RT = BBBB -@print{} Record = record 3 and RT = -@print{} +> @kbd{@{ print "Record =", $0,"and RT = [" RT "]" @}'} +@print{} Record = record 1 and RT = [ AAAA ] +@print{} Record = record 2 and RT = [ BBBB ] +@print{} Record = record 3 and RT = [ +@print{} ] @end example @noindent -The final line of output has an extra blank line. This is because the -value of @code{RT} is a newline, and the @code{print} statement -supplies its own terminating newline. +The square brackets delineate the contents of @code{RT}, letting you +see the leading and trailing whitespace. The final value of @code{RT} +@code{RT} is a newline. @xref{Simple Sed}, for a more useful example of @code{RS} as a regexp and @code{RT}. @@ -6838,7 +6843,7 @@ with a statement such as @samp{$1 = $1}, as described earlier. * Default Field Splitting:: How fields are normally separated. * Regexp Field Splitting:: Using regexps as the field separator. * Single Character Fields:: Making each character a separate field. -* Command Line Field Separator:: Setting @code{FS} from the command-line. +* Command Line Field Separator:: Setting @code{FS} from the command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @end menu @@ -7094,7 +7099,7 @@ behaves this way. @node Command Line Field Separator @subsection Setting @code{FS} from the Command Line -@cindex @option{-F} option, command line +@cindex @option{-F} option, command-line @cindex field separator, on command line @cindex command line, @code{FS} on@comma{} setting @cindex @code{FS} variable, setting from command line @@ -8529,10 +8534,10 @@ a connection before it can start reading any data, or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. -@node Command line directories +@node Command-line directories @section Directories On The Command Line -@cindex differences in @command{awk} and @command{gawk}, command line directories -@cindex directories, command line +@cindex differences in @command{awk} and @command{gawk}, command-line directories +@cindex directories, command-line @cindex command line, directories on According to the POSIX standard, files named on the @command{awk} @@ -10570,7 +10575,7 @@ function mysub(pat, repl, str, global) @c @cindex automatic warnings @c @cindex warnings, automatic In this example, the programmer wants to pass a regexp constant to the -user-defined function @code{mysub}, which in turn passes it on to +user-defined function @code{mysub()}, which in turn passes it on to either @code{sub()} or @code{gsub()}. However, what really happens is that the @code{pat} parameter is either one or zero, depending upon whether or not @code{$0} matches @code{/hi/}. @@ -10591,7 +10596,7 @@ on the @command{awk} command line. @menu * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line and a +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. @end menu @@ -17483,6 +17488,12 @@ Nonalphabetic characters are left unchanged. For example, @cindex backslash (@code{\}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex @code{&} (ampersand), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and + +@quotation CAUTION +This section has been known to cause headaches. +You might want to skip it upon first reading. +@end quotation + When using @code{sub()}, @code{gsub()}, or @code{gensub()}, and trying to get literal backslashes and ampersands into the replacement text, you need to remember that there are several levels of @dfn{escape processing} going on. @@ -17525,26 +17536,26 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{\&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\&}_cr - @code{\\\\\&}! @code{\\&}!a literal @samp{\&}_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\\&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr + @code{\&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\&}_cr + @code{\\\\\&}! @code{\\&}!A literal @samp{\&}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\\&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @end multitable @end ifdocbook @ifnottex @@ -17552,13 +17563,13 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- - @code{\&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\&} - @code{\\\\\&} @code{\\&} a literal @samp{\&} -@code{\\\\\\&} @code{\\\&} a literal @samp{\\&} - @code{\\q} @code{\q} a literal @samp{\q} + @code{\&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\&} @code{\&} A literal @samp{&} + @code{\\\\&} @code{\\&} A literal @samp{\&} + @code{\\\\\&} @code{\\&} A literal @samp{\&} +@code{\\\\\\&} @code{\\\&} A literal @samp{\\&} + @code{\\q} @code{\q} A literal @samp{\q} @end display @end ifnotdocbook @end ifnottex @@ -17574,86 +17585,19 @@ case of even numbers of backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal @samp{\} followed by the matched text. -@c @cindex @command{awk} language, POSIX version -@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} -The 1992 POSIX standard attempted to fix this problem. That standard -says that @code{sub()} and @code{gsub()} look for either a @samp{\} or an @samp{&} -after the @samp{\}. If either one follows a @samp{\}, that character is -output literally. The interpretation of @samp{\} and @samp{&} then becomes -as shown in @ref{table-sub-posix-92}. - -@float Table,table-sub-posix-92 -@caption{1992 POSIX Rules for @code{sub()} and @code{gsub()} Escape Sequence Processing} -@c thanks to Karl Berry for formatting this table -@tex -\vbox{\bigskip -% We need more characters for escape and tab ... -\catcode`_ = 0 -\catcode`! = 4 -% ... since this table has lots of &'s and \'s, so we unspecialize them. -\catcode`\& = \other \catcode`\\ = \other -_halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr - You type!@code{sub()} sees!@code{sub()} generates_cr -_hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -} -_bigskip} -@end tex -@ifdocbook -@multitable @columnfractions .20 .20 .60 -@headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@end multitable -@end ifdocbook -@ifnottex -@ifnotdocbook -@display - You type @code{sub()} sees @code{sub()} generates - -------- ---------- --------------- - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} -@end display -@end ifnotdocbook -@end ifnottex -@end float - -@noindent -This appears to solve the problem. -Unfortunately, the phrasing of the standard is unusual. It -says, in effect, that @samp{\} turns off the special meaning of any -following character, but for anything other than @samp{\} and @samp{&}, -such special meaning is undefined. This wording leads to two problems: - -@itemize @value{BULLET} -@item -Backslashes must now be doubled in the @var{replacement} string, breaking -historical @command{awk} programs. - -@item -To make sure that an @command{awk} program is portable, @emph{every} character -in the @var{replacement} string must be preceded with a -backslash.@footnote{This consequence was certainly unintended.} -@c I can say that, 'cause I was involved in making this change -@end itemize +Several editions of the POSIX standard attempted to fix this problem +but weren't successful. The details are irrelevant at this point in time. -Because of the problems just listed, -in 1996, the @command{gawk} maintainer submitted +At one point, the @command{gawk} maintainer submitted proposed text for a revised standard that reverts to rules that correspond more closely to the original existing practice. The proposed rules have special cases that make it possible -to produce a @samp{\} preceding the matched text. This is shown in +to produce a @samp{\} preceding the matched text. +This is shown in @ref{table-sub-proposed}. @float Table,table-sub-proposed -@caption{Proposed Rules For @code{sub()} And Backslash} +@caption{GNU @command{awk} Rules For @code{sub()} And Backslash} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17664,10 +17608,10 @@ to produce a @samp{\} preceding the matched text. This is shown in _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\\}_cr } _bigskip} @@ -17675,10 +17619,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\\} @end multitable @end ifdocbook @@ -17687,10 +17631,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\\} @end display @end ifnotdocbook @@ -17703,13 +17647,13 @@ there was only one. However, as in the historical case, any @samp{\} that is not part of one of these three sequences is not special and appears in the output literally. -@command{gawk} 3.0 and 3.1 follow these proposed POSIX rules for @code{sub()} and -@code{gsub()}. -@c As much as we think it's a lousy idea. You win some, you lose some. Sigh. -The POSIX standard took much longer to be revised than was expected in 1996. -The 2001 standard does not follow the above rules. Instead, the rules -there are somewhat simpler. The results are similar except for one case. +@command{gawk} 3.0 and 3.1 follow these rules for @code{sub()} and +@code{gsub()}. The POSIX standard took much longer to be revised than +was expected. In addition, the @command{gawk} maintainer's proposal was +lost during the standardization process. The final rules are +somewhat simpler. The results are similar except for one case. +@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} The POSIX rules state that @samp{\&} in the replacement string produces a literal @samp{&}, @samp{\\} produces a literal @samp{\}, and @samp{\} followed by anything else is not special; the @samp{\} is placed straight into the output. @@ -17727,10 +17671,10 @@ These rules are presented in @ref{table-posix-sub}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\}_cr } _bigskip} @@ -17738,10 +17682,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\} @end multitable @end ifdocbook @@ -17750,10 +17694,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\} @end display @end ifnotdocbook @@ -17765,7 +17709,7 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, -it continued to follow the 1996 proposed rules, since +it continued to follow the proposed rules, since that had been its behavior for many years. When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer @@ -17796,24 +17740,24 @@ as shown in @ref{table-gensub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{gensub()} sees!@code{gensub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\}! @code{\\}!a literal @samp{\}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr - @code{\\q}! @code{\q}!a literal @samp{q}_cr + @code{&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\}! @code{\\}!A literal @samp{\}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\}, then the matched text_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr + @code{\\q}! @code{\q}!A literal @samp{q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{gensub()} sees @tab @code{gensub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\} @tab @code{\\} @tab a literal @samp{\} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{q} +@item @code{&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\} @tab @code{\\} @tab A literal @samp{\} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, then the matched text +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{q} @end multitable @end ifdocbook @ifnottex @@ -17821,12 +17765,12 @@ _bigskip} @display You type @code{gensub()} sees @code{gensub()} generates -------- ------------- ------------------ - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\} @code{\\} a literal @samp{\} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\q} @code{\q} a literal @samp{q} + @code{&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\\} @code{\\} A literal @samp{\} + @code{\\\\&} @code{\\&} A literal @samp{\}, then the matched text +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\q} @code{\q} A literal @samp{q} @end display @end ifnotdocbook @end ifnottex @@ -19250,17 +19194,18 @@ addition to the POSIX standard.) The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. -In this case, the recursion terminates when the starting position -is zero, i.e., when there are no more characters left in the string. +In this case, the recursion terminates when the input string is +already empty. +@c 8/2014: Thanks to Mike Brennan for the improved formulation @cindex @code{rev()} user-defined function @example -function rev(str, start) +function rev(str) @{ - if (start == 0) + if (str == "") return "" - return (substr(str, start, 1) rev(str, start - 1)) + return (rev(substr(str, 2)) substr(str, 1, 1)) @} @end example @@ -19269,7 +19214,7 @@ this way: @example $ @kbd{echo "Don't Panic!" |} -> @kbd{gawk --source '@{ print rev($0, length($0)) @}' -f rev.awk} +> @kbd{gawk --source '@{ print rev($0) @}' -f rev.awk} @print{} !cinaP t'noD @end example @@ -19554,7 +19499,7 @@ BEGIN @{ @noindent prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because -@code{changeit} stores @code{"two"} in the second element of @code{a}. +@code{changeit()} stores @code{"two"} in the second element of @code{a}. @end quotation @cindex undefined functions @@ -25909,7 +25854,7 @@ The program should exit without reading any @value{DF}s. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the -command-line. Reading from @file{/dev/null} always returns an immediate +command line. Reading from @file{/dev/null} always returns an immediate end of file indication. @c Hmm. Add /dev/null if $# is 0? Still messes up ARGV. Sigh. @@ -26931,6 +26876,9 @@ Caveat Emptor. @node Two-way I/O @section Two-Way Communications with Another Process + +@c 8/2014. Neither Mike nor BWK saw this as relevant. Commenting it out. +@ignore @cindex Brennan, Michael @cindex programmers, attractiveness of @smallexample @@ -26960,6 +26908,7 @@ the scent of perl programmers. Mike Brennan @c brennan@@whidbey.com @end smallexample +@end ignore @cindex advanced features, processes@comma{} communicating with @cindex processes, two-way communications with @@ -26986,7 +26935,10 @@ system("rm " tempfile) This works, but not elegantly. Among other things, it requires that the program be run in a directory that cannot be shared among users; for example, @file{/tmp} will not do, as another user might happen -to be using a temporary file with the same name. +to be using a temporary file with the same name.@footnote{Michael +Brennan suggests the use of @command{rand()} to generate unique +@value{FN}s. This is a valid point; nevertheless, temporary files +remain more difficult than two-way pipes.} @c 8/2014 @cindex coprocesses @cindex input/output, two-way @@ -27141,7 +27093,7 @@ You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is by recognizing special @value{FN}s that begin with one of @samp{/inet/}, -@samp{/inet4/} or @samp{/inet6}. +@samp{/inet4/} or @samp{/inet6/}. The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. @@ -29774,6 +29726,12 @@ arbitrary precision integers, and concludes with a description of some points where @command{gawk} and the POSIX standard are not quite in agreement. +@quotation NOTE +Most users of @command{gawk} can safely skip this chapter. +But if you want to do scientific calculations with @command{gawk}, +this is the place to be. +@end quotation + @menu * Computer Arithmetic:: A quick intro to computer math. * Math Definitions:: Defining terms used. @@ -29893,8 +29851,23 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.'' A special value indicating a result that can't -happen in real math, but that can happen in floating-point computations. +``Not A Number.''@footnote{Thanks +to Michael Brennan for this description, which I have paraphrased, and +for the examples}. +A special value that results from attempting a +calculation that has no answer as a real number. In such a case, +programs can either receive a floating-point exception, or get @code{NaN} +back as the result. The IEEE 754 standard recommends that systems return +@code{NaN}. Some examples: + +@table @code +@item sqrt(-1) +This makes sense in the range of complex numbers, but not in the +range of real numbers, so the result is @code{NaN}. + +@item log(-8) +@minus{}8 is out of the domain of @code{log()}, so the result is @code{NaN}. +@end table @item Normalized How the significand (see later in this list) is usually stored. The @@ -30312,7 +30285,7 @@ internally as a MPFR number. Changing the precision using @code{PREC} in the program text does @emph{not} change the precision of a constant. If you need to represent a floating-point constant at a higher precision -than the default and cannot use a command line assignment to @code{PREC}, +than the default and cannot use a command-line assignment to @code{PREC}, you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a floating-point constant: @@ -30907,7 +30880,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling} and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -35123,7 +35096,7 @@ Indirect function calls @item Directories on the command line produce a warning and are skipped -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @end itemize @item @@ -35470,7 +35443,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}} (@pxref{Delete}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -35533,7 +35506,7 @@ Brian Kernighan's @command{awk} @pxref{I/O Functions}). @item -New command line options: +New command-line options: @itemize @value{MINUS} @item @@ -35823,7 +35796,7 @@ Indirect function calls (@pxref{Switch Statement}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -35848,7 +35821,7 @@ All long options acquired corresponding short options, for use in @samp{#!} scri @item Directories named on the command line now produce a warning, not a fatal error, unless @option{--posix} or @option{--traditional} are used -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @item The @command{gawk} internals were rewritten, bringing the @command{dgawk} @@ -35924,10 +35897,10 @@ Three new arrays: @item The three executables @command{gawk}, @command{pgawk}, and @command{dgawk}, were merged into -one, named just @command{gawk}. As a result the command line options changed. +one, named just @command{gawk}. As a result the command-line options changed. @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -41303,13 +41276,14 @@ Consistency issues: Use "zeros" instead of "zeroes". Use "nonzero" not "non-zero". Use "runtime" not "run time" or "run-time". - Use "command-line" not "command line". + Use "command-line" as an adjective and "command line" as a noun. Use "online" not "on-line". Use "whitespace" not "white space". Use "Input/Output", not "input/output". Also "I/O", not "i/o". Use "lefthand"/"righthand", not "left-hand"/"right-hand". Use "workaround", not "work-around". Use "startup"/"cleanup", not "start-up"/"clean-up" + Use "filesystem", not "file system" Use @code{do}, and not @code{do}-@code{while}, except where actually discussing the do-while. Use "versus" in text and "vs." in index entries @@ -41324,8 +41298,6 @@ Consistency issues: The numbers zero through ten should be spelled out, except when talking about file descriptor numbers. > 10 and < 0, it's ok to use numbers. - In tables, put command-line options in @code, while in the text, - put them in @option. For most cases, do NOT put a comma before "and", "or" or "but". But exercise taste with this rule. Don't show the awk command with a program in quotes when it's diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 56f119a8..22f9d410 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -46,7 +46,7 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH June, 2014 +@set UPDATE-MONTH August, 2014 @set VERSION 4.1 @set PATCHLEVEL 1 @@ -541,7 +541,7 @@ particular records in a file and perform operations upon them. * Single Character Fields:: Making each character a separate field. * Command Line Field Separator:: Setting @code{FS} from the - command-line. + command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -567,7 +567,7 @@ particular records in a file and perform operations upon them. @code{getline}. * Getline Summary:: Summary of @code{getline} Variants. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -606,7 +606,7 @@ particular records in a file and perform operations upon them. * Variables:: Variables give names to values for later use. * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. * Conversion:: The conversion of strings to numbers @@ -1371,7 +1371,7 @@ help from me, thoroughly reworked @command{gawk} for compatibility with the newer @command{awk}. Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, -performance improvements, standards compliance, and occasionally, new features. +performance improvements, standards compliance and, occasionally, new features. In May of 1997, J@"urgen Kahrs felt the need for network access from @command{awk}, and with a little help from me, set about adding @@ -1664,7 +1664,7 @@ are slightly different than in other books you may have read. This @value{SECTION} briefly documents the typographical conventions used in Texinfo. @end ifinfo -Examples you would type at the command-line are preceded by the common +Examples you would type at the command line are preceded by the common shell primary and secondary prompts, @samp{$} and @samp{>}. Input that you type is shown @kbd{like this}. Output from the command is preceded by the glyph ``@print{}''. @@ -2302,12 +2302,7 @@ For example, on OS/2, it is @kbd{Ctrl-z}.) As an example, the following program prints a friendly piece of advice (from Douglas Adams's @cite{The Hitchhiker's Guide to the Galaxy}), to keep you from worrying about the complexities of computer -programming@footnote{If you use Bash as your shell, you should execute -the command @samp{set +H} before running this program interactively, -to disable the C shell-style command history, which treats -@samp{!} as a special character. We recommend putting this command into -your personal startup file.} -(@code{BEGIN} is a feature we haven't discussed yet): +programming (@code{BEGIN} is a feature we haven't discussed yet): @example $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @@ -2326,6 +2321,14 @@ double quotes.@footnote{Although we generally recommend the use of single quotes around the program text, double quotes are needed here in order to put the single quote into the message.} +@quotation NOTE +As a side note, if you use Bash as your shell, you should execute the +command @samp{set +H} before running this program interactively, to +disable the C shell-style command history, which treats @samp{!} as a +special character. We recommend putting this command into your personal +startup file. +@end quotation + This next simple @command{awk} program emulates the @command{cat} utility; it copies whatever you type on the keyboard to its standard output (why this works is explained shortly). @@ -2643,7 +2646,7 @@ Note that the single quote is not special within double quotes. @item Null strings are removed when they occur as part of a non-null -command-line argument, while explicit non-null objects are kept. +command-line argument, while explicit null objects are kept. For example, to specify that the field separator @code{FS} should be set to the null string, use: @@ -2790,7 +2793,9 @@ each line is considered to be one @dfn{record}. In the @value{DF} @file{mail-list}, each record contains the name of a person, his/her phone number, his/her email-address, and a code for their relationship -with the author of the list. An @samp{A} in the last column +with the author of the list. +The columns are aligned using spaces. +An @samp{A} in the last column means that the person is an acquaintance. An @samp{F} in the last column means that the person is a friend. An @samp{R} means that the person is a relative: @@ -3708,7 +3713,7 @@ Second, because this option is intended to be used with code libraries, @command{gawk} does not recognize such files as constituting main program input. Thus, after processing an @option{-i} argument, @command{gawk} still expects to find the main source code via the @option{-f} option -or on the command-line. +or on the command line. @item @option{-l} @var{ext} @itemx @option{--load} @var{ext} @@ -3732,7 +3737,7 @@ a shared library. This feature is described in detail in @ref{Dynamic Extension @cindex warnings, issuing Warn about constructs that are dubious or nonportable to other @command{awk} implementations. -No space is allowed between the @option{-D} and @var{value}, if +No space is allowed between the @option{-L} and @var{value}, if @var{value} is supplied. Some warnings are issued when @command{gawk} first reads your program. Others are issued at runtime, as your program executes. @@ -3853,7 +3858,7 @@ Newlines are not allowed after @samp{?} or @samp{:} @cindex @code{FS} variable, as TAB character @item -Specifying @samp{-Ft} on the command-line does not set the value +Specifying @samp{-Ft} on the command line does not set the value of @code{FS} to be a single TAB character (@pxref{Field Separators}). @@ -4099,7 +4104,7 @@ with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file -in the file system; however, @command{gawk} always processes +in the filesystem; however, @command{gawk} always processes this @value{FN} itself.) @node Environment Variables @@ -4125,7 +4130,7 @@ behaves. @cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable @ifinfo The previous @value{SECTION} described how @command{awk} program files can be named -on the command-line with the @option{-f} option. +on the command line with the @option{-f} option. @end ifinfo In most @command{awk} implementations, you must supply a precise path name for each program @@ -4220,7 +4225,7 @@ list are meant to be used by regular users. @table @env @item POSIXLY_CORRECT -Causes @command{gawk} to switch POSIX compatibility +Causes @command{gawk} to switch to POSIX compatibility mode, disabling all traditional and GNU extensions. @xref{Options}. @@ -4253,7 +4258,7 @@ file as the size of the memory buffer to allocate for I/O. Otherwise, the value should be a number, and @command{gawk} uses that number as the size of the buffer to allocate. (When this variable is not set, @command{gawk} uses the smaller of the file's size and the ``default'' -blocksize, which is usually the file systems I/O blocksize.) +blocksize, which is usually the filesystems I/O blocksize.) @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} @@ -4591,9 +4596,9 @@ or to run @command{awk}. @item -The three standard @command{awk} options are @option{-f}, @option{-F} -and @option{-v}. @command{gawk} supplies these and many others, as well -as corresponding GNU-style long options. +The three standard options for all versions of @command{awk} are +@option{-f}, @option{-F} and @option{-v}. @command{gawk} supplies these +and many others, as well as corresponding GNU-style long options. @item Non-option command-line arguments are usually treated as @value{FN}s, @@ -5802,7 +5807,7 @@ In @command{awk}, regular expression constants are written enclosed between slashes: @code{/}@dots{}@code{/}. @item -Regexp constants may be used by standalone in patterns and +Regexp constants may be used standalone in patterns and in conditional expressions, or as part of matching expressions using the @samp{~} and @samp{!~} operators. @@ -5832,7 +5837,7 @@ the match, such as for text substitution and when the record separator is a regexp. @item -Matching expressions may use dynamic regexps; that is string values +Matching expressions may use dynamic regexps; that is, string values treated as regular expressions. @end itemize @@ -5884,7 +5889,7 @@ used with it do not have to be named on the @command{awk} command line * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on the +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -6115,17 +6120,17 @@ with optional leading and/or trailing whitespace: @example $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} > @kbd{gawk 'BEGIN @{ RS = "\n|( *[[:upper:]]+ *)" @}} -> @kbd{@{ print "Record =", $0, "and RT =", RT @}'} -@print{} Record = record 1 and RT = AAAA -@print{} Record = record 2 and RT = BBBB -@print{} Record = record 3 and RT = -@print{} +> @kbd{@{ print "Record =", $0,"and RT = [" RT "]" @}'} +@print{} Record = record 1 and RT = [ AAAA ] +@print{} Record = record 2 and RT = [ BBBB ] +@print{} Record = record 3 and RT = [ +@print{} ] @end example @noindent -The final line of output has an extra blank line. This is because the -value of @code{RT} is a newline, and the @code{print} statement -supplies its own terminating newline. +The square brackets delineate the contents of @code{RT}, letting you +see the leading and trailing whitespace. The final value of @code{RT} +@code{RT} is a newline. @xref{Simple Sed}, for a more useful example of @code{RS} as a regexp and @code{RT}. @@ -6552,7 +6557,7 @@ with a statement such as @samp{$1 = $1}, as described earlier. * Default Field Splitting:: How fields are normally separated. * Regexp Field Splitting:: Using regexps as the field separator. * Single Character Fields:: Making each character a separate field. -* Command Line Field Separator:: Setting @code{FS} from the command-line. +* Command Line Field Separator:: Setting @code{FS} from the command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @end menu @@ -6808,7 +6813,7 @@ behaves this way. @node Command Line Field Separator @subsection Setting @code{FS} from the Command Line -@cindex @option{-F} option, command line +@cindex @option{-F} option, command-line @cindex field separator, on command line @cindex command line, @code{FS} on@comma{} setting @cindex @code{FS} variable, setting from command line @@ -8148,10 +8153,10 @@ a connection before it can start reading any data, or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. -@node Command line directories +@node Command-line directories @section Directories On The Command Line -@cindex differences in @command{awk} and @command{gawk}, command line directories -@cindex directories, command line +@cindex differences in @command{awk} and @command{gawk}, command-line directories +@cindex directories, command-line @cindex command line, directories on According to the POSIX standard, files named on the @command{awk} @@ -10060,7 +10065,7 @@ function mysub(pat, repl, str, global) @c @cindex automatic warnings @c @cindex warnings, automatic In this example, the programmer wants to pass a regexp constant to the -user-defined function @code{mysub}, which in turn passes it on to +user-defined function @code{mysub()}, which in turn passes it on to either @code{sub()} or @code{gsub()}. However, what really happens is that the @code{pat} parameter is either one or zero, depending upon whether or not @code{$0} matches @code{/hi/}. @@ -10081,7 +10086,7 @@ on the @command{awk} command line. @menu * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line and a +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. @end menu @@ -16788,6 +16793,12 @@ Nonalphabetic characters are left unchanged. For example, @cindex backslash (@code{\}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex @code{&} (ampersand), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and + +@quotation CAUTION +This section has been known to cause headaches. +You might want to skip it upon first reading. +@end quotation + When using @code{sub()}, @code{gsub()}, or @code{gensub()}, and trying to get literal backslashes and ampersands into the replacement text, you need to remember that there are several levels of @dfn{escape processing} going on. @@ -16830,26 +16841,26 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{\&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\&}_cr - @code{\\\\\&}! @code{\\&}!a literal @samp{\&}_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\\&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr + @code{\&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\&}_cr + @code{\\\\\&}! @code{\\&}!A literal @samp{\&}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\\&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @end multitable @end ifdocbook @ifnottex @@ -16857,13 +16868,13 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- - @code{\&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\&} - @code{\\\\\&} @code{\\&} a literal @samp{\&} -@code{\\\\\\&} @code{\\\&} a literal @samp{\\&} - @code{\\q} @code{\q} a literal @samp{\q} + @code{\&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\&} @code{\&} A literal @samp{&} + @code{\\\\&} @code{\\&} A literal @samp{\&} + @code{\\\\\&} @code{\\&} A literal @samp{\&} +@code{\\\\\\&} @code{\\\&} A literal @samp{\\&} + @code{\\q} @code{\q} A literal @samp{\q} @end display @end ifnotdocbook @end ifnottex @@ -16879,86 +16890,19 @@ case of even numbers of backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal @samp{\} followed by the matched text. -@c @cindex @command{awk} language, POSIX version -@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} -The 1992 POSIX standard attempted to fix this problem. That standard -says that @code{sub()} and @code{gsub()} look for either a @samp{\} or an @samp{&} -after the @samp{\}. If either one follows a @samp{\}, that character is -output literally. The interpretation of @samp{\} and @samp{&} then becomes -as shown in @ref{table-sub-posix-92}. - -@float Table,table-sub-posix-92 -@caption{1992 POSIX Rules for @code{sub()} and @code{gsub()} Escape Sequence Processing} -@c thanks to Karl Berry for formatting this table -@tex -\vbox{\bigskip -% We need more characters for escape and tab ... -\catcode`_ = 0 -\catcode`! = 4 -% ... since this table has lots of &'s and \'s, so we unspecialize them. -\catcode`\& = \other \catcode`\\ = \other -_halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr - You type!@code{sub()} sees!@code{sub()} generates_cr -_hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -} -_bigskip} -@end tex -@ifdocbook -@multitable @columnfractions .20 .20 .60 -@headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@end multitable -@end ifdocbook -@ifnottex -@ifnotdocbook -@display - You type @code{sub()} sees @code{sub()} generates - -------- ---------- --------------- - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} -@end display -@end ifnotdocbook -@end ifnottex -@end float - -@noindent -This appears to solve the problem. -Unfortunately, the phrasing of the standard is unusual. It -says, in effect, that @samp{\} turns off the special meaning of any -following character, but for anything other than @samp{\} and @samp{&}, -such special meaning is undefined. This wording leads to two problems: - -@itemize @value{BULLET} -@item -Backslashes must now be doubled in the @var{replacement} string, breaking -historical @command{awk} programs. - -@item -To make sure that an @command{awk} program is portable, @emph{every} character -in the @var{replacement} string must be preceded with a -backslash.@footnote{This consequence was certainly unintended.} -@c I can say that, 'cause I was involved in making this change -@end itemize +Several editions of the POSIX standard attempted to fix this problem +but weren't successful. The details are irrelevant at this point in time. -Because of the problems just listed, -in 1996, the @command{gawk} maintainer submitted +At one point, the @command{gawk} maintainer submitted proposed text for a revised standard that reverts to rules that correspond more closely to the original existing practice. The proposed rules have special cases that make it possible -to produce a @samp{\} preceding the matched text. This is shown in +to produce a @samp{\} preceding the matched text. +This is shown in @ref{table-sub-proposed}. @float Table,table-sub-proposed -@caption{Proposed Rules For @code{sub()} And Backslash} +@caption{GNU @command{awk} Rules For @code{sub()} And Backslash} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -16969,10 +16913,10 @@ to produce a @samp{\} preceding the matched text. This is shown in _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\\}_cr } _bigskip} @@ -16980,10 +16924,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\\} @end multitable @end ifdocbook @@ -16992,10 +16936,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\\} @end display @end ifnotdocbook @@ -17008,13 +16952,13 @@ there was only one. However, as in the historical case, any @samp{\} that is not part of one of these three sequences is not special and appears in the output literally. -@command{gawk} 3.0 and 3.1 follow these proposed POSIX rules for @code{sub()} and -@code{gsub()}. -@c As much as we think it's a lousy idea. You win some, you lose some. Sigh. -The POSIX standard took much longer to be revised than was expected in 1996. -The 2001 standard does not follow the above rules. Instead, the rules -there are somewhat simpler. The results are similar except for one case. +@command{gawk} 3.0 and 3.1 follow these rules for @code{sub()} and +@code{gsub()}. The POSIX standard took much longer to be revised than +was expected. In addition, the @command{gawk} maintainer's proposal was +lost during the standardization process. The final rules are +somewhat simpler. The results are similar except for one case. +@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} The POSIX rules state that @samp{\&} in the replacement string produces a literal @samp{&}, @samp{\\} produces a literal @samp{\}, and @samp{\} followed by anything else is not special; the @samp{\} is placed straight into the output. @@ -17032,10 +16976,10 @@ These rules are presented in @ref{table-posix-sub}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\}_cr } _bigskip} @@ -17043,10 +16987,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\} @end multitable @end ifdocbook @@ -17055,10 +16999,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\} @end display @end ifnotdocbook @@ -17070,7 +17014,7 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, -it continued to follow the 1996 proposed rules, since +it continued to follow the proposed rules, since that had been its behavior for many years. When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer @@ -17101,24 +17045,24 @@ as shown in @ref{table-gensub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{gensub()} sees!@code{gensub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\}! @code{\\}!a literal @samp{\}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr - @code{\\q}! @code{\q}!a literal @samp{q}_cr + @code{&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\}! @code{\\}!A literal @samp{\}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\}, then the matched text_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr + @code{\\q}! @code{\q}!A literal @samp{q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{gensub()} sees @tab @code{gensub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\} @tab @code{\\} @tab a literal @samp{\} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{q} +@item @code{&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\} @tab @code{\\} @tab A literal @samp{\} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, then the matched text +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{q} @end multitable @end ifdocbook @ifnottex @@ -17126,12 +17070,12 @@ _bigskip} @display You type @code{gensub()} sees @code{gensub()} generates -------- ------------- ------------------ - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\} @code{\\} a literal @samp{\} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\q} @code{\q} a literal @samp{q} + @code{&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\\} @code{\\} A literal @samp{\} + @code{\\\\&} @code{\\&} A literal @samp{\}, then the matched text +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\q} @code{\q} A literal @samp{q} @end display @end ifnotdocbook @end ifnottex @@ -18394,17 +18338,18 @@ addition to the POSIX standard.) The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. -In this case, the recursion terminates when the starting position -is zero, i.e., when there are no more characters left in the string. +In this case, the recursion terminates when the input string is +already empty. +@c 8/2014: Thanks to Mike Brennan for the improved formulation @cindex @code{rev()} user-defined function @example -function rev(str, start) +function rev(str) @{ - if (start == 0) + if (str == "") return "" - return (substr(str, start, 1) rev(str, start - 1)) + return (rev(substr(str, 2)) substr(str, 1, 1)) @} @end example @@ -18413,7 +18358,7 @@ this way: @example $ @kbd{echo "Don't Panic!" |} -> @kbd{gawk --source '@{ print rev($0, length($0)) @}' -f rev.awk} +> @kbd{gawk --source '@{ print rev($0) @}' -f rev.awk} @print{} !cinaP t'noD @end example @@ -18698,7 +18643,7 @@ BEGIN @{ @noindent prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because -@code{changeit} stores @code{"two"} in the second element of @code{a}. +@code{changeit()} stores @code{"two"} in the second element of @code{a}. @end quotation @cindex undefined functions @@ -25024,7 +24969,7 @@ The program should exit without reading any @value{DF}s. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the -command-line. Reading from @file{/dev/null} always returns an immediate +command line. Reading from @file{/dev/null} always returns an immediate end of file indication. @c Hmm. Add /dev/null if $# is 0? Still messes up ARGV. Sigh. @@ -26046,6 +25991,9 @@ Caveat Emptor. @node Two-way I/O @section Two-Way Communications with Another Process + +@c 8/2014. Neither Mike nor BWK saw this as relevant. Commenting it out. +@ignore @cindex Brennan, Michael @cindex programmers, attractiveness of @smallexample @@ -26075,6 +26023,7 @@ the scent of perl programmers. Mike Brennan @c brennan@@whidbey.com @end smallexample +@end ignore @cindex advanced features, processes@comma{} communicating with @cindex processes, two-way communications with @@ -26101,7 +26050,10 @@ system("rm " tempfile) This works, but not elegantly. Among other things, it requires that the program be run in a directory that cannot be shared among users; for example, @file{/tmp} will not do, as another user might happen -to be using a temporary file with the same name. +to be using a temporary file with the same name.@footnote{Michael +Brennan suggests the use of @command{rand()} to generate unique +@value{FN}s. This is a valid point; nevertheless, temporary files +remain more difficult than two-way pipes.} @c 8/2014 @cindex coprocesses @cindex input/output, two-way @@ -26256,7 +26208,7 @@ You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is by recognizing special @value{FN}s that begin with one of @samp{/inet/}, -@samp{/inet4/} or @samp{/inet6}. +@samp{/inet4/} or @samp{/inet6/}. The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. @@ -28889,6 +28841,12 @@ arbitrary precision integers, and concludes with a description of some points where @command{gawk} and the POSIX standard are not quite in agreement. +@quotation NOTE +Most users of @command{gawk} can safely skip this chapter. +But if you want to do scientific calculations with @command{gawk}, +this is the place to be. +@end quotation + @menu * Computer Arithmetic:: A quick intro to computer math. * Math Definitions:: Defining terms used. @@ -29008,8 +28966,23 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.'' A special value indicating a result that can't -happen in real math, but that can happen in floating-point computations. +``Not A Number.''@footnote{Thanks +to Michael Brennan for this description, which I have paraphrased, and +for the examples}. +A special value that results from attempting a +calculation that has no answer as a real number. In such a case, +programs can either receive a floating-point exception, or get @code{NaN} +back as the result. The IEEE 754 standard recommends that systems return +@code{NaN}. Some examples: + +@table @code +@item sqrt(-1) +This makes sense in the range of complex numbers, but not in the +range of real numbers, so the result is @code{NaN}. + +@item log(-8) +@minus{}8 is out of the domain of @code{log()}, so the result is @code{NaN}. +@end table @item Normalized How the significand (see later in this list) is usually stored. The @@ -29427,7 +29400,7 @@ internally as a MPFR number. Changing the precision using @code{PREC} in the program text does @emph{not} change the precision of a constant. If you need to represent a floating-point constant at a higher precision -than the default and cannot use a command line assignment to @code{PREC}, +than the default and cannot use a command-line assignment to @code{PREC}, you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a floating-point constant: @@ -30022,7 +29995,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling} and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -34238,7 +34211,7 @@ Indirect function calls @item Directories on the command line produce a warning and are skipped -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @end itemize @item @@ -34585,7 +34558,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}} (@pxref{Delete}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -34648,7 +34621,7 @@ Brian Kernighan's @command{awk} @pxref{I/O Functions}). @item -New command line options: +New command-line options: @itemize @value{MINUS} @item @@ -34938,7 +34911,7 @@ Indirect function calls (@pxref{Switch Statement}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -34963,7 +34936,7 @@ All long options acquired corresponding short options, for use in @samp{#!} scri @item Directories named on the command line now produce a warning, not a fatal error, unless @option{--posix} or @option{--traditional} are used -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @item The @command{gawk} internals were rewritten, bringing the @command{dgawk} @@ -35039,10 +35012,10 @@ Three new arrays: @item The three executables @command{gawk}, @command{pgawk}, and @command{dgawk}, were merged into -one, named just @command{gawk}. As a result the command line options changed. +one, named just @command{gawk}. As a result the command-line options changed. @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -40418,13 +40391,14 @@ Consistency issues: Use "zeros" instead of "zeroes". Use "nonzero" not "non-zero". Use "runtime" not "run time" or "run-time". - Use "command-line" not "command line". + Use "command-line" as an adjective and "command line" as a noun. Use "online" not "on-line". Use "whitespace" not "white space". Use "Input/Output", not "input/output". Also "I/O", not "i/o". Use "lefthand"/"righthand", not "left-hand"/"right-hand". Use "workaround", not "work-around". Use "startup"/"cleanup", not "start-up"/"clean-up" + Use "filesystem", not "file system" Use @code{do}, and not @code{do}-@code{while}, except where actually discussing the do-while. Use "versus" in text and "vs." in index entries @@ -40439,8 +40413,6 @@ Consistency issues: The numbers zero through ten should be spelled out, except when talking about file descriptor numbers. > 10 and < 0, it's ok to use numbers. - In tables, put command-line options in @code, while in the text, - put them in @option. For most cases, do NOT put a comma before "and", "or" or "but". But exercise taste with this rule. Don't show the awk command with a program in quotes when it's |