diff options
| -rw-r--r-- | ChangeLog | 22 | ||||
| -rw-r--r-- | POSIX.STD | 15 | ||||
| -rw-r--r-- | awkgram.c | 10 | ||||
| -rw-r--r-- | awkgram.y | 10 | ||||
| -rwxr-xr-x | configure | 6 | ||||
| -rw-r--r-- | configure.ac | 6 | ||||
| -rw-r--r-- | doc/ChangeLog | 20 | ||||
| -rw-r--r-- | doc/gawk.info | 2146 | ||||
| -rw-r--r-- | doc/gawk.texi | 883 | ||||
| -rw-r--r-- | doc/gawktexi.in | 883 | ||||
| -rw-r--r-- | extension/ChangeLog | 4 | ||||
| -rw-r--r-- | extension/filefuncs.c | 2 | ||||
| -rw-r--r-- | gawkapi.h | 2 | ||||
| -rw-r--r-- | profile.c | 1 | ||||
| -rw-r--r-- | test/ChangeLog | 5 | ||||
| -rw-r--r-- | test/Makefile.am | 10 | ||||
| -rw-r--r-- | test/Makefile.in | 10 | ||||
| -rw-r--r-- | test/profile0.awk | 1 | ||||
| -rw-r--r-- | test/profile0.in | 2 | ||||
| -rw-r--r-- | test/profile0.ok | 6 |
20 files changed, 2107 insertions, 1937 deletions
@@ -1,3 +1,25 @@ +2015-02-13 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y (yylex): Be more careful about passing true to + nextc() when collecting a regexp. Some systems' iscntrl() + are not as forgiving as GLIBC's. E.g., Solaris. + Thanks to Dagobert Michelsen <dam@baltic-online.de> for + the bug report and access to systems to check the fix. + +2015-02-12 Arnold D. Robbins <arnold@skeeve.com> + + * POSIX.STD: Update with info about function parameters. + * configure.ac: Remove test for / use of dbug library. + +2015-02-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawkapi.h: Fix spelling error in comment. + +2015-02-10 Arnold D. Robbins <arnold@skeeve.com> + + * profile.c (pprint): Restore printing of count for rules. + Bug report by Hermann Peifer. + 2015-02-07 Arnold D. Robbins <arnold@skeeve.com> * regcomp.c, regex.c, regex.h, regex_internal.c, regex_internal.h, @@ -5,7 +5,7 @@ are permitted in any medium without royalty provided the copyright notice and this notice are preserved. -------------------------------------------------------------------------- -Thu Mar 31 22:31:57 IST 2011 +Thu Feb 12 08:51:22 IST 2015 ============================ This file documents several things related to the 2008 POSIX standard that I noted after reviewing it. @@ -30,6 +30,19 @@ that I noted after reviewing it. sequence into account. By default gawk doesn't do this. Rather, gawk will do this only if --posix is in effect. +4. According to POSIX, the function parameters of one function may not have + the same name as another function, making this invalid: + + function foo() { ... } + function bar(foo) { ...} + + Or even: + + function bar(foo) { ...} + function foo() { ... } + + Gawk enforces this only with --posix. + The following things aren't described by POSIX but ought to be: 1. The value of $0 in an END rule @@ -5535,7 +5535,7 @@ yylex(void) if (lasttok == LEX_EOF) /* error earlier in current source, must give up !! */ return 0; - c = nextc(true); + c = nextc(! want_regexp); if (c == END_SRC) return 0; if (c == END_FILE) @@ -5577,12 +5577,12 @@ yylex(void) want_regexp = false; tok = tokstart; for (;;) { - c = nextc(true); + c = nextc(false); if (gawk_mb_cur_max == 1 || nextc_is_1stbyte) switch (c) { case '[': /* one day check for `.' and `=' too */ - if (nextc(true) == ':' || in_brack == 0) + if (nextc(false) == ':' || in_brack == 0) in_brack++; pushback(); break; @@ -5594,7 +5594,7 @@ yylex(void) in_brack--; break; case '\\': - if ((c = nextc(true)) == END_FILE) { + if ((c = nextc(false)) == END_FILE) { pushback(); yyerror(_("unterminated regexp ends with `\\' at end of file")); goto end_regexp; /* kludge */ @@ -5812,7 +5812,7 @@ retry: return lasttok = '*'; case '/': - if (nextc(true) == '=') { + if (nextc(false) == '=') { pushback(); return lasttok = SLASH_BEFORE_EQUAL; } @@ -3197,7 +3197,7 @@ yylex(void) if (lasttok == LEX_EOF) /* error earlier in current source, must give up !! */ return 0; - c = nextc(true); + c = nextc(! want_regexp); if (c == END_SRC) return 0; if (c == END_FILE) @@ -3239,12 +3239,12 @@ yylex(void) want_regexp = false; tok = tokstart; for (;;) { - c = nextc(true); + c = nextc(false); if (gawk_mb_cur_max == 1 || nextc_is_1stbyte) switch (c) { case '[': /* one day check for `.' and `=' too */ - if (nextc(true) == ':' || in_brack == 0) + if (nextc(false) == ':' || in_brack == 0) in_brack++; pushback(); break; @@ -3256,7 +3256,7 @@ yylex(void) in_brack--; break; case '\\': - if ((c = nextc(true)) == END_FILE) { + if ((c = nextc(false)) == END_FILE) { pushback(); yyerror(_("unterminated regexp ends with `\\' at end of file")); goto end_regexp; /* kludge */ @@ -3474,7 +3474,7 @@ retry: return lasttok = '*'; case '/': - if (nextc(true) == '=') { + if (nextc(false) == '=') { pushback(); return lasttok = SLASH_BEFORE_EQUAL; } @@ -5837,11 +5837,7 @@ if test -f $srcdir/.developing then # add other debug flags as appropriate, save GAWKDEBUG for emergencies CFLAGS="$CFLAGS -DARRAYDEBUG -DYYDEBUG -DLOCALEDEBUG" - if grep dbug $srcdir/.developing - then - CFLAGS="$CFLAGS -DDBUG" - LIBS="$LIBS dbug/libdbug.a" - fi + # turn on compiler warnings if we're doing development # enable debugging using macros also if test "$GCC" = yes diff --git a/configure.ac b/configure.ac index 548a3ce3..008c2780 100644 --- a/configure.ac +++ b/configure.ac @@ -88,11 +88,7 @@ if test -f $srcdir/.developing then # add other debug flags as appropriate, save GAWKDEBUG for emergencies CFLAGS="$CFLAGS -DARRAYDEBUG -DYYDEBUG -DLOCALEDEBUG" - if grep dbug $srcdir/.developing - then - CFLAGS="$CFLAGS -DDBUG" - LIBS="$LIBS dbug/libdbug.a" - fi + # turn on compiler warnings if we're doing development # enable debugging using macros also if test "$GCC" = yes diff --git a/doc/ChangeLog b/doc/ChangeLog index 1e3f1551..093b25bb 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,23 @@ +2015-02-13 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: O'Reilly fixes. Through QC1 review. + +2015-02-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: O'Reilly fixes. + +2015-02-10 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor fixes, O'Reilly fixes. + +2015-02-09 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Restore a lost sentence. O'Reilly fixes. + +2015-02-08 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: O'Reilly fixes. + 2015-02-06 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: O'Reilly fixes. diff --git a/doc/gawk.info b/doc/gawk.info index fad0fce3..afdc99b9 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1375,6 +1375,12 @@ also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities. + +Arnold Robbins +Nof Ayalon +Israel +February 2015 + File: gawk.info, Node: Getting Started, Next: Invoking Gawk, Prev: Preface, Up: Top @@ -9072,9 +9078,10 @@ accepts any record with a first field that contains `li': -| 555-5553 -| 555-6699 - pattern. The expression `/li/' has the value one if `li' appears in -the current input record. Thus, as a pattern, `/li/' matches any record -containing `li'. + A regexp constant as a pattern is also a special case of an +expression pattern. The expression `/li/' has the value one if `li' +appears in the current input record. Thus, as a pattern, `/li/' matches +any record containing `li'. Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions @@ -20088,7 +20095,7 @@ File: gawk.info, Node: I18N and L10N, Next: Explaining gettext, Up: Internati "Internationalization" means writing (or modifying) a program once, in such a way that it can use multiple languages without requiring further -source-code changes. "Localization" means providing the data necessary +source code changes. "Localization" means providing the data necessary for an internationalized program to work in a particular language. Most typically, these terms refer to features such as the language used for printing error messages, the language used to read responses, and @@ -20102,7 +20109,7 @@ File: gawk.info, Node: Explaining gettext, Next: Programmer i18n, Prev: I18N ================== `gawk' uses GNU `gettext' to provide its internationalization features. -The facilities in GNU `gettext' focus on messages; strings printed by a +The facilities in GNU `gettext' focus on messages: strings printed by a program, either directly or via formatting with `printf' or `sprintf()'.(1) @@ -20231,8 +20238,7 @@ File: gawk.info, Node: Programmer i18n, Next: Translator i18n, Prev: Explaini 13.3 Internationalizing `awk' Programs ====================================== -`gawk' provides the following variables and functions for -internationalization: +`gawk' provides the following variables for internationalization: `TEXTDOMAIN' This variable indicates the application's text domain. For @@ -20244,6 +20250,8 @@ internationalization: for translation at runtime. String constants without a leading underscore are not translated. + `gawk' provides the following functions for internationalization: + ``dcgettext(STRING' [`,' DOMAIN [`,' CATEGORY]]`)'' Return the translation of STRING in text domain DOMAIN for locale category CATEGORY. The default value for DOMAIN is the current @@ -20282,8 +20290,7 @@ internationalization: the null string (`""'), then `bindtextdomain()' returns the current binding for the given DOMAIN. - To use these facilities in your `awk' program, follow the steps -outlined in *note Explaining gettext::, like so: + To use these facilities in your `awk' program, follow these steps: 1. Set the variable `TEXTDOMAIN' to the text domain of your program. This is best done in a `BEGIN' rule (*note BEGIN/END::), or it can @@ -20505,7 +20512,7 @@ actually almost portable, requiring very little change: its value, leaving the original string constant as the result. * By defining "dummy" functions to replace `dcgettext()', - `dcngettext()' and `bindtextdomain()', the `awk' program can be + `dcngettext()', and `bindtextdomain()', the `awk' program can be made to run, but all the messages are output in the original language. For example: @@ -20640,8 +20647,8 @@ File: gawk.info, Node: Gawk I18N, Next: I18N Summary, Prev: I18N Example, Up `gawk' itself has been internationalized using the GNU `gettext' package. (GNU `gettext' is described in complete detail in *note (GNU -`gettext' utilities)Top:: gettext, GNU gettext tools.) As of this -writing, the latest version of GNU `gettext' is version 0.19.4 +`gettext' utilities)Top:: gettext, GNU `gettext' utilities.) As of +this writing, the latest version of GNU `gettext' is version 0.19.4 (ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.4.tar.gz). If a translation of `gawk''s messages exists, then `gawk' produces @@ -20654,7 +20661,7 @@ File: gawk.info, Node: I18N Summary, Prev: Gawk I18N, Up: Internationalizatio ============ * Internationalization means writing a program such that it can use - multiple languages without requiring source-code changes. + multiple languages without requiring source code changes. Localization means providing the data necessary for an internationalized program to work in a particular language. @@ -20668,10 +20675,10 @@ File: gawk.info, Node: I18N Summary, Prev: Gawk I18N, Up: Internationalizatio file, and the `.po' files are compiled into `.gmo' files for use at runtime. - * You can use position specifications with `sprintf()' and `printf' - to rearrange the placement of argument values in formatted strings - and output. This is useful for the translations of format control - strings. + * You can use positional specifications with `sprintf()' and + `printf' to rearrange the placement of argument values in formatted + strings and output. This is useful for the translation of format + control strings. * The internationalization features have been designed so that they can be easily worked around in a standard `awk'. @@ -20727,8 +20734,7 @@ File: gawk.info, Node: Debugging Concepts, Next: Debugging Terms, Up: Debuggi --------------------------- (If you have used debuggers in other languages, you may want to skip -ahead to the next section on the specific features of the `gawk' -debugger.) +ahead to *note Awk Debugging::.) Of course, a debugging program cannot remove bugs for you, because it has no way of knowing what you or your users consider a "bug" versus @@ -20815,11 +20821,11 @@ defines terms used throughout the rest of this major node: File: gawk.info, Node: Awk Debugging, Prev: Debugging Terms, Up: Debugging -14.1.3 Awk Debugging --------------------- +14.1.3 `awk' Debugging +---------------------- Debugging an `awk' program has some specific aspects that are not -shared with other programming languages. +shared with programs written in other languages. First of all, the fact that `awk' programs usually take input line by line from a file or files and operate on those lines using specific @@ -20837,8 +20843,8 @@ commands. File: gawk.info, Node: Sample Debugging Session, Next: List of Debugger Commands, Prev: Debugging, Up: Debugger -14.2 Sample Debugging Session -============================= +14.2 Sample `gawk' Debugging Session +==================================== In order to illustrate the use of `gawk' as a debugger, let's look at a sample debugging session. We will use the `awk' implementation of the @@ -20857,8 +20863,8 @@ File: gawk.info, Node: Debugger Invocation, Next: Finding The Bug, Up: Sample -------------------------------- Starting the debugger is almost exactly like running `gawk' normally, -except you have to pass an additional option `--debug', or the -corresponding short option `-D'. The file(s) containing the program +except you have to pass an additional option, `--debug', or the +corresponding short option, `-D'. The file(s) containing the program and any supporting code are given on the command line as arguments to one or more `-f' options. (`gawk' is not designed to debug command-line programs, only programs contained in files.) In our case, we invoke @@ -20868,7 +20874,7 @@ the debugger like this: where both `getopt.awk' and `uniq.awk' are in `$AWKPATH'. (Experienced users of GDB or similar debuggers should note that this syntax is -slightly different from what they are used to. With the `gawk' +slightly different from what you are used to. With the `gawk' debugger, you give the arguments for running the program in the command line to the debugger rather than as part of the `run' command at the debugger prompt.) The `-1' is an option to `uniq.awk'. @@ -20992,10 +20998,10 @@ typing `n' (for "next"): -| 66 if (fcount > 0) { This tells us that `gawk' is now ready to execute line 66, which -decides whether to give the lines the special "field skipping" treatment +decides whether to give the lines the special "field-skipping" treatment indicated by the `-1' command-line option. (Notice that we skipped -from where we were before at line 63 to here, because the condition in -line 63 `if (fcount == 0 && charcount == 0)' was false.) +from where we were before, at line 63, to here, because the condition +in line 63, `if (fcount == 0 && charcount == 0)', was false.) Continuing to step, we now get to the splitting of the current and last records: @@ -21053,15 +21059,15 @@ mentioned): Well, here we are at our error (sorry to spoil the suspense). What we had in mind was to join the fields starting from the second one to -make the virtual record to compare, and if the first field was numbered -zero, this would work. Let's look at what we've got: +make the virtual record to compare, and if the first field were +numbered zero, this would work. Let's look at what we've got: gawk> p cline clast -| cline = "gawk is a wonderful program!" -| clast = "awk is a wonderful program!" Hey, those look pretty familiar! They're just our original, -unaltered, input records. A little thinking (the human brain is still +unaltered input records. A little thinking (the human brain is still the best debugging tool), and we realize that we were off by one! We get out of the debugger: @@ -21098,11 +21104,11 @@ categories: * Miscellaneous Each of these are discussed in the following subsections. In the -following descriptions, commands which may be abbreviated show the +following descriptions, commands that may be abbreviated show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to automatically repeat the previous command -just by hitting <Enter>. This works for the commands `list', `next', +just by hitting `Enter'. This works for the commands `list', `next', `nexti', `step', `stepi', and `continue' executed without any argument. * Menu: @@ -21142,8 +21148,8 @@ The commands for controlling breakpoints are: Set a breakpoint at entry to (the first instruction of) function FUNCTION. - Each breakpoint is assigned a number which can be used to delete - it from the breakpoint list using the `delete' command. + Each breakpoint is assigned a number that can be used to delete it + from the breakpoint list using the `delete' command. With a breakpoint, you may also supply a condition. This is an `awk' expression (enclosed in double quotes) that the debugger @@ -21181,26 +21187,26 @@ The commands for controlling breakpoints are: `delete' [N1 N2 ...] [N-M] `d' [N1 N2 ...] [N-M] - Delete specified breakpoints or a range of breakpoints. Deletes - all defined breakpoints if no argument is supplied. + Delete specified breakpoints or a range of breakpoints. Delete all + defined breakpoints if no argument is supplied. `disable' [N1 N2 ... | N-M] Disable specified breakpoints or a range of breakpoints. Without - any argument, disables all breakpoints. + any argument, disable all breakpoints. `enable' [`del' | `once'] [N1 N2 ...] [N-M] `e' [`del' | `once'] [N1 N2 ...] [N-M] Enable specified breakpoints or a range of breakpoints. Without - any argument, enables all breakpoints. Optionally, you can - specify how to enable the breakpoint: + any argument, enable all breakpoints. Optionally, you can specify + how to enable the breakpoints: `del' - Enable the breakpoint(s) temporarily, then delete it when the - program stops at the breakpoint. + Enable the breakpoints temporarily, then delete each one when + the program stops at it. `once' - Enable the breakpoint(s) temporarily, then disable it when - the program stops at the breakpoint. + Enable the breakpoints temporarily, then disable each one when + the program stops at it. `ignore' N COUNT Ignore breakpoint number N the next COUNT times it is hit. @@ -21246,7 +21252,7 @@ execution of the program than we saw in our earlier example: `continue' [COUNT] `c' [COUNT] Resume program execution. If continued from a breakpoint and COUNT - is specified, ignores the breakpoint at that location the next + is specified, ignore the breakpoint at that location the next COUNT times before stopping. `finish' @@ -21281,10 +21287,10 @@ execution of the program than we saw in our earlier example: `step' [COUNT] `s' [COUNT] Continue execution until control reaches a different source line - in the current stack frame. `step' steps inside any function - called within the line. If the argument COUNT is supplied, steps - that many times before stopping, unless it encounters a breakpoint - or watchpoint. + in the current stack frame, stepping inside any function called + within the line. If the argument COUNT is supplied, steps that + many times before stopping, unless it encounters a breakpoint or + watchpoint. `stepi' [COUNT] `si' [COUNT] @@ -21365,13 +21371,13 @@ AWK STATEMENTS (`"'...`"'). You can also set special `awk' variables, such as `FS', `NF', - `NR', and son on. + `NR', and so on. `watch' VAR | `$'N [`"EXPRESSION"'] `w' VAR | `$'N [`"EXPRESSION"'] Add variable VAR (or field `$N') to the watch list. The debugger then stops whenever the value of the variable or field changes. - Each watched item is assigned a number which can be used to delete + Each watched item is assigned a number that can be used to delete it from the watch list using the `unwatch' command. With a watchpoint, you may also supply a condition. This is an @@ -21395,11 +21401,11 @@ File: gawk.info, Node: Execution Stack, Next: Debugger Info, Prev: Viewing An 14.3.4 Working with the Stack ----------------------------- -Whenever you run a program which contains any function calls, `gawk' +Whenever you run a program that contains any function calls, `gawk' maintains a stack of all of the function calls leading up to where the program is right now. You can see how you got to where you are, and also move around in the stack to see what the state of things was in the -functions which called the one you are in. The commands for doing this +functions that called the one you are in. The commands for doing this are: `backtrace' [COUNT] @@ -21419,8 +21425,8 @@ are: `frame' [N] `f' [N] Select and print stack frame N. Frame 0 is the currently - executing, or "innermost", frame (function call), frame 1 is the - frame that called the innermost one. The highest numbered frame is + executing, or "innermost", frame (function call); frame 1 is the + frame that called the innermost one. The highest-numbered frame is the one for the main program. The printed information consists of the frame number, function and argument names, source file, and the source line. @@ -21437,7 +21443,7 @@ File: gawk.info, Node: Debugger Info, Next: Miscellaneous Debugger Commands, Besides looking at the values of variables, there is often a need to get other sorts of information about the state of your program and of the -debugging environment itself. The `gawk' debugger has one command which +debugging environment itself. The `gawk' debugger has one command that provides this information, appropriately called `info'. `info' is used with one of a number of arguments that tell it exactly what you want to know: @@ -21494,11 +21500,12 @@ from a file. The commands are: option. The available options are: `history_size' - The maximum number of lines to keep in the history file + Set the maximum number of lines to keep in the history file `./.gawk_history'. The default is 100. `listsize' - The number of lines that `list' prints. The default is 15. + Specify the number of lines that `list' prints. The default + is 15. `outfile' Send `gawk' output to a file; debugger output still goes to @@ -21506,7 +21513,7 @@ from a file. The commands are: standard output. `prompt' - The debugger prompt. The default is `gawk> '. + Change the debugger prompt. The default is `gawk> '. `save_history' [`on' | `off'] Save command history to file `./.gawk_history'. The default @@ -21514,8 +21521,8 @@ from a file. The commands are: `save_options' [`on' | `off'] Save current options to file `./.gawkrc' upon exit. The - default is `on'. Options are read back in to the next - session upon startup. + default is `on'. Options are read back into the next session + upon startup. `trace' [`on' | `off'] Turn instruction tracing on or off. The default is `off'. @@ -21534,7 +21541,7 @@ from a file. The commands are: commands; however, the `gawk' debugger will not source the same file more than once in order to avoid infinite recursion. - In addition to, or instead of the `source' command, you can use + In addition to, or instead of, the `source' command, you can use the `-D FILE' or `--debug=FILE' command-line options to execute commands from a file non-interactively (*note Options::). @@ -21544,13 +21551,13 @@ File: gawk.info, Node: Miscellaneous Debugger Commands, Prev: Debugger Info, 14.3.6 Miscellaneous Commands ----------------------------- -There are a few more commands which do not fit into the previous +There are a few more commands that do not fit into the previous categories, as follows: `dump' [FILENAME] - Dump bytecode of the program to standard output or to the file + Dump byte code of the program to standard output or to the file named in FILENAME. This prints a representation of the internal - instructions which `gawk' executes to implement the `awk' commands + instructions that `gawk' executes to implement the `awk' commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (*note Signature Program::) demonstrates: @@ -21634,22 +21641,21 @@ categories, as follows: FILENAME. This command may change the current source file. FUNCTION - Print lines centered around beginning of the function + Print lines centered around the beginning of the function FUNCTION. This command may change the current source file. `quit' `q' Exit the debugger. Debugging is great fun, but sometimes we all have to tend to other obligations in life, and sometimes we find - the bug, and are free to go on to the next one! As we saw - earlier, if you are running a program, the debugger warns you if - you accidentally type `q' or `quit', to make sure you really want - to quit. + the bug and are free to go on to the next one! As we saw earlier, + if you are running a program, the debugger warns you when you type + `q' or `quit', to make sure you really want to quit. `trace' [`on' | `off'] - Turn on or off a continuous printing of instructions which are - about to be executed, along with printing the `awk' line which they - implement. The default is `off'. + Turn on or off continuous printing of the instructions that are + about to be executed, along with the `awk' lines they implement. + The default is `off'. It is to be hoped that most of the "opcodes" in these instructions are fairly self-explanatory, and using `stepi' and `nexti' while @@ -21662,7 +21668,7 @@ File: gawk.info, Node: Readline Support, Next: Limitations, Prev: List of Deb 14.4 Readline Support ===================== -If `gawk' is compiled with the `readline' library +If `gawk' is compiled with the GNU Readline library (http://cnswww.cns.cwru.edu/php/chet/readline/readline.html), you can take advantage of that library's command completion and history expansion features. The following types of completion are available: @@ -21692,7 +21698,7 @@ File: gawk.info, Node: Limitations, Next: Debugging Summary, Prev: Readline S We hope you find the `gawk' debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has -some limitations. A few which are worth being aware of are: +some limitations. A few that it's worth being aware of are: * At this point, the debugger does not give a detailed explanation of what you did wrong when you type in something it doesn't like. @@ -21703,13 +21709,13 @@ some limitations. A few which are worth being aware of are: Commands:: (or if you are already familiar with `gawk' internals), you will realize that much of the internal manipulation of data in `gawk', as in many interpreters, is done on a stack. `Op_push', - `Op_pop', and the like, are the "bread and butter" of most `gawk' + `Op_pop', and the like are the "bread and butter" of most `gawk' code. Unfortunately, as of now, the `gawk' debugger does not allow you to examine the stack's contents. That is, the intermediate results of expression evaluation are on the stack, but cannot be - printed. Rather, only variables which are defined in the program + printed. Rather, only variables that are defined in the program can be printed. Of course, a workaround for this is to use more explicit variables at the debugging stage and then change back to obscure, perhaps more optimal code later. @@ -21721,12 +21727,12 @@ some limitations. A few which are worth being aware of are: * The `gawk' debugger is designed to be used by running a program (with all its parameters) on the command line, as described in *note Debugger Invocation::. There is no way (as of now) to - attach or "break in" to a running program. This seems reasonable - for a language which is used mainly for quickly executing, short + attach or "break into" a running program. This seems reasonable + for a language that is used mainly for quickly executing, short programs. - * The `gawk' debugger only accepts source supplied with the `-f' - option. + * The `gawk' debugger only accepts source code supplied with the + `-f' option. File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger @@ -21735,8 +21741,8 @@ File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger ============ * Programs rarely work correctly the first time. Finding bugs is - "debugging" and a program that helps you find bugs is a - "debugger". `gawk' has a built-in debugger that works very + called debugging, and a program that helps you find bugs is a + debugger. `gawk' has a built-in debugger that works very similarly to the GNU Debugger, GDB. * Debuggers let you step through your program one statement at a @@ -21752,8 +21758,8 @@ File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger breakpoints, execution, viewing and changing data, working with the stack, getting information, and other tasks. - * If the `readline' library is available when `gawk' is compiled, it - is used by the debugger to provide command-line history and + * If the GNU Readline library is available when `gawk' is compiled, + it is used by the debugger to provide command-line history and editing. @@ -21814,7 +21820,7 @@ Decimal arithmetic sides) of the decimal point, and the results of a computation are always exact. - Some modern system can do decimal arithmetic in hardware, but + Some modern systems can do decimal arithmetic in hardware, but usually you need a special software library to provide access to these instructions. There are also libraries that do decimal arithmetic entirely in software. @@ -21868,12 +21874,6 @@ Numeric representation Minimum value Maximum value 32-bit unsigned integer 0 4,294,967,295 64-bit signed integer -9,223,372,036,854,775,8089,223,372,036,854,775,807 64-bit unsigned integer 0 18,446,744,073,709,551,615 -Single-precision `1.175494e-38' `3.402823e+38' -floating point -(approximate) -Double-precision `2.225074e-308' `1.797693e+308' -floating point -(approximate) Table 15.1: Value ranges for different numeric representations @@ -21889,7 +21889,7 @@ File: gawk.info, Node: Math Definitions, Next: MPFR features, Prev: Computer The rest of this major node uses a number of terms. Here are some informal definitions that should help you work your way through the -material here. +material here: "Accuracy" A floating-point calculation's accuracy is how close it comes to @@ -21909,7 +21909,7 @@ material here. number and infinity produce infinity. "NaN" - "Not A Number."(1) A special value that results from attempting a + "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 @@ -21935,15 +21935,15 @@ material here. PREC = 3.322 * DPS - Here, PREC denotes the binary precision (measured in bits) and DPS - (short for decimal places) is the decimal digits. + Here, _prec_ denotes the binary precision (measured in bits) and + _dps_ (short for decimal places) is the decimal digits. "Rounding mode" How numbers are rounded up or down when necessary. More details are provided later. "Significand" - A floating-point value consists the significand multiplied by 10 + A floating-point value consists of the significand multiplied by 10 to the power of the exponent. For example, in `1.2345e67', the significand is `1.2345'. @@ -21965,7 +21965,7 @@ precision formats to allow greater precisions and larger exponent ranges. (`awk' uses only the 64-bit double-precision format.) *note table-ieee-formats:: lists the precision and exponent field -values for the basic IEEE 754 binary formats: +values for the basic IEEE 754 binary formats. Name Total bits Precision Minimum Maximum exponent exponent @@ -22030,7 +22030,7 @@ File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers, P Math class is tough! -- Teen Talk Barbie, July 1992 - This minor node provides a high level overview of the issues + This minor node provides a high-level overview of the issues involved when doing lots of floating-point arithmetic.(1) The discussion applies to both hardware and arbitrary-precision floating-point arithmetic. @@ -22051,8 +22051,8 @@ floating-point arithmetic. (1) There is a very nice paper on floating-point arithmetic (http://www.validlab.com/goldberg/paper.pdf) by David Goldberg, "What -Every Computer Scientist Should Know About Floating-point Arithmetic," -`ACM Computing Surveys' *23*, 1 (1991-03), 5-48. This is worth reading +Every Computer Scientist Should Know About Floating-Point Arithmetic," +`ACM Computing Surveys' *23*, 1 (1991-03): 5-48. This is worth reading if you are interested in the details, but it does require a background in computer science. @@ -22106,7 +22106,7 @@ number as you assigned to it: Often the error is so small you do not even notice it, and if you do, you can always specify how much precision you would like in your output. -Usually this is a format string like `"%.15g"', which when used in the +Usually this is a format string like `"%.15g"', which, when used in the previous example, produces an output identical to the input. @@ -22146,7 +22146,7 @@ File: gawk.info, Node: Errors accumulate, Prev: Comparing FP Values, Up: Inex The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating-point operations, +value that is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of pi using one of its many series representations: @@ -22197,7 +22197,7 @@ easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may be important for your computation. Rounding error, cumulative precision -loss and underflow are often troublesome. +loss, and underflow are often troublesome. When `gawk' tests the expressions `0.1 + 12.2' and `12.3' for equality using the machine double-precision arithmetic, it decides that @@ -22232,8 +22232,9 @@ illustrated by our earlier attempt to compute the value of pi. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. - Repeated addition is not necessarily equivalent to multiplication in -floating-point arithmetic. In the example in *note Errors accumulate::: + Additionally, you should understand that repeated addition is not +necessarily equivalent to multiplication in floating-point arithmetic. +In the example in *note Errors accumulate::: $ gawk 'BEGIN { > for (d = 1.1; d <= 1.5; d += 0.1) # loop five times (?) @@ -22288,7 +22289,7 @@ set the value to one of the predefined case-insensitive strings shown in *note table-predefined-precision-strings::, to emulate an IEEE 754 binary format. -`PREC' IEEE 754 Binary Format +`PREC' IEEE 754 binary format --------------------------------------------------- `"half"' 16-bit half-precision `"single"' Basic 32-bit single precision @@ -22321,14 +22322,14 @@ on arithmetic operations: example illustrates the differences among various ways to print a floating-point constant: - $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 0.1) }' - -| 0.1000000000000000055511151 - $ gawk -M -v PREC=113 'BEGIN { printf("%0.25f\n", 0.1) }' - -| 0.1000000000000000000000000 - $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", "0.1") }' - -| 0.1000000000000000000000000 - $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 1/10) }' - -| 0.1000000000000000000000000 + $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 0.1) }' + -| 0.1000000000000000055511151 + $ gawk -M -v PREC=113 'BEGIN { printf("%0.25f\n", 0.1) }' + -| 0.1000000000000000000000000 + $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", "0.1") }' + -| 0.1000000000000000000000000 + $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 1/10) }' + -| 0.1000000000000000000000000 File: gawk.info, Node: Setting the rounding mode, Prev: Setting precision, Up: FP Math Caution @@ -22336,15 +22337,15 @@ File: gawk.info, Node: Setting the rounding mode, Prev: Setting precision, Up 15.4.5 Setting the Rounding Mode -------------------------------- -The `ROUNDMODE' variable provides program level control over the +The `ROUNDMODE' variable provides program-level control over the rounding mode. The correspondence between `ROUNDMODE' and the IEEE rounding modes is shown in *note table-gawk-rounding-modes::. -Rounding Mode IEEE Name `ROUNDMODE' +Rounding mode IEEE name `ROUNDMODE' --------------------------------------------------------------------------- Round to nearest, ties to even `roundTiesToEven' `"N"' or `"n"' -Round toward plus Infinity `roundTowardPositive' `"U"' or `"u"' -Round toward negative Infinity `roundTowardNegative' `"D"' or `"d"' +Round toward positive infinity `roundTowardPositive' `"U"' or `"u"' +Round toward negative infinity `roundTowardNegative' `"D"' or `"d"' Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero @@ -22395,8 +22396,8 @@ distributes upward and downward rounds of exact halves, which might cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. - The other rounding modes are rarely used. Round toward positive -infinity (`roundTowardPositive') and round toward negative infinity + The other rounding modes are rarely used. Rounding toward positive +infinity (`roundTowardPositive') and toward negative infinity (`roundTowardNegative') are often used to implement interval arithmetic, where you adjust the rounding mode to calculate upper and lower bounds for the range of output. The `roundTowardZero' mode can be @@ -22444,7 +22445,7 @@ floating-point values: If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for -correct output (using the formula `prec = 3.322 * dps'), would be 3.322 +correct output (using the formula `prec = 3.322 * dps') would be 3.322 x 183231, or 608693. The result from an arithmetic operation with an integer and a @@ -22475,7 +22476,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or -want, you can employ a subterfuge, and convert the integer to floating +want, you can employ a subterfuge and convert the integer to floating point first, like this: gawk -M 'BEGIN { n = 13; print (n + 0.0) % 2.0 }' @@ -22558,7 +22559,7 @@ File: gawk.info, Node: POSIX Floating Point Problems, Next: Floating point sum 15.6 Standards Versus Existing Practice ======================================= -Historically, `awk' has converted any non-numeric looking string to the +Historically, `awk' has converted any nonnumeric-looking string to the numeric value zero, when required. Furthermore, the original definition of the language and the original POSIX standards specified that `awk' only understands decimal numbers (base 10), and not octal @@ -22572,8 +22573,8 @@ These features are: hexadecimal notation (e.g., `0xDEADBEEF'). (Note: data values, _not_ source code constants.) - * Support for the special IEEE 754 floating-point values "Not A - Number" (NaN), positive Infinity ("inf"), and negative Infinity + * Support for the special IEEE 754 floating-point values "not a + number" (NaN), positive infinity ("inf"), and negative infinity ("-inf"). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @@ -22590,21 +22591,21 @@ historical practice: values is also a very severe departure from historical practice. The second problem is that the `gawk' maintainer feels that this -interpretation of the standard, which requires a certain amount of +interpretation of the standard, which required a certain amount of "language lawyering" to arrive at in the first place, was not even -intended by the standard developers. In other words, "we see how you +intended by the standard developers. In other words, "We see how you got where you are, but we don't think that that's where you want to be." Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that `awk' support -hexadecimal floating-point values and special values for "Not A Number" +hexadecimal floating-point values and special values for "not a number" and infinity. Although the `gawk' maintainer continues to feel that providing those features is inadvisable, nevertheless, on systems that support IEEE floating point, it seems reasonable to provide _some_ way to -support NaN and Infinity values. The solution implemented in `gawk' is +support NaN and infinity values. The solution implemented in `gawk' is as follows: * With the `--posix' command-line option, `gawk' becomes "hands @@ -22619,7 +22620,7 @@ as follows: $ echo 0xDeadBeef | gawk --posix '{ print $1 + 0 }' -| 3735928559 - * Without `--posix', `gawk' interprets the four strings `+inf', + * Without `--posix', `gawk' interprets the four string values `+inf', `-inf', `+nan', and `-nan' specially, producing the corresponding special numeric values. The leading sign acts a signal to `gawk' (and the user) that the value is really numeric. Hexadecimal @@ -22633,7 +22634,7 @@ as follows: $ echo 0xDeadBeef | gawk '{ print $1 + 0 }' -| 0 - `gawk' ignores case in the four special values. Thus `+nan' and + `gawk' ignores case in the four special values. Thus, `+nan' and `+NaN' are the same. ---------- Footnotes ---------- @@ -22650,9 +22651,9 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob floating-point values. Standard `awk' uses double-precision floating-point values. - * In the early 1990s, Barbie mistakenly said "Math class is tough!" + * In the early 1990s Barbie mistakenly said, "Math class is tough!" Although math isn't tough, floating-point arithmetic isn't the same - as pencil and paper math, and care must be taken: + as pencil-and-paper math, and care must be taken: - Not all numbers can be represented exactly. @@ -22673,7 +22674,7 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob rounding mode. * With `-M', `gawk' performs arbitrary-precision integer arithmetic - using the GMP library. This is faster and more space efficient + using the GMP library. This is faster and more space-efficient than using MPFR for the same calculations. * There are several "dark corners" with respect to floating-point @@ -22684,7 +22685,7 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and paper. In order to take advantage of - the power of computer floating point, you need to know its + the power of floating-point arithmetic, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the @@ -22743,7 +22744,7 @@ the rest of this Info file. `gawk''s functionality. For example, they can provide access to system calls (such as `chdir()' to change directory) and to other C library routines that could be of use. As with most software, "the sky is the -limit;" if you can imagine something that you might want to do and can +limit"; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the "application @@ -22751,7 +22752,7 @@ programming interface" (API) defined for this purpose by the `gawk' developers. The rest of this major node explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents the sample extensions included in -the `gawk' distribution, and describes the `gawkextlib' project. *Note +the `gawk' distribution and describes the `gawkextlib' project. *Note Extension Design::, for a discussion of the extension mechanism goals and design. @@ -22869,7 +22870,7 @@ Example::) and also in 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. @@ -22915,8 +22916,8 @@ File: gawk.info, Node: Extension API Functions Introduction, Next: General Dat 16.4.1 Introduction ------------------- -Access to facilities within `gawk' are made available by calling -through function pointers passed into your extension. +Access to facilities within `gawk' is achieved by calling through +function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -22937,7 +22938,7 @@ operations: - Two-way processors - All of these are discussed in detail, later in this major node. + All of these are discussed in detail later in this major node. * Printing fatal, warning, and "lint" warning messages. @@ -22963,7 +22964,7 @@ operations: - Clearing an array - - Flattening an array for easy C style looping over all its + - Flattening an array for easy C-style looping over all its indices and elements Some points about using the API: @@ -22972,7 +22973,7 @@ operations: `gawkapi.h'. For correct use, you must therefore include the corresponding standard header file _before_ including `gawkapi.h': - C Entity Header File + C entity Header file ------------------------------------------- `EOF' `<stdio.h>' Values for `errno' `<errno.h>' @@ -22996,13 +22997,13 @@ operations: * Although the API only uses ISO C 90 features, there is an exception; the "constructor" functions use the `inline' keyword. If your compiler does not support this keyword, you should either - place `-Dinline=''' on your command line, or use the GNU Autotools + place `-Dinline=''' on your command line or use the GNU Autotools and include a `config.h' file in your extensions. * All pointers filled in by `gawk' point to memory managed by `gawk' and should be treated by the extension as read-only. Memory for _all_ strings passed into `gawk' from the extension _must_ come - from calling one of `gawk_malloc()', `gawk_calloc()' or + from calling one of `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()', and is managed by `gawk' from then on. * The API defines several simple `struct's that map values as seen @@ -23015,7 +23016,7 @@ operations: multibyte encoding (as defined by `LC_XXX' environment variables) and not using wide characters. This matches how `gawk' stores strings internally and also how characters are - likely to be input and output from files. + likely to be input into and output from files. * When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type @@ -23052,6 +23053,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent minor nodes, together with the functions that use them. + The general-purpose types and structures are as follows: + `typedef void *awk_ext_id_t;' A value of this type is received from `gawk' when an extension is loaded. That value must then be passed back to `gawk' as the @@ -23067,7 +23070,7 @@ use them. ` awk_false = 0,' ` awk_true' `} awk_bool_t;' - A simple boolean type. + A simple Boolean type. `typedef struct awk_string {' ` char *str; /* data */' @@ -23111,8 +23114,8 @@ use them. `#define array_cookie u.a' `#define scalar_cookie u.scl' `#define value_cookie u.vc' - These macros make accessing the fields of the `awk_value_t' more - readable. + Using these macros makes accessing the fields of the `awk_value_t' + more readable. `typedef void *awk_scalar_t;' Scalars can be represented as an opaque type. These values are @@ -23132,8 +23135,8 @@ indicates what is in the `union'. Representing numbers is easy--the API uses a C `double'. Strings require more work. Because `gawk' allows embedded NUL bytes in string -values, a string must be represented as a pair containing a -data-pointer and length. This is the `awk_string_t' type. +values, a string must be represented as a pair containing a data +pointer and length. This is the `awk_string_t' type. Identifiers (i.e., the names of global variables) can be associated with either scalar values or with arrays. In addition, `gawk' provides @@ -23145,12 +23148,12 @@ Manipulation::. of the `union' as if they were fields in a `struct'; this is a common coding practice in C. Such code is easier to write and to read, but it remains _your_ responsibility to make sure that the `val_type' member -correctly reflects the type of the value in the `awk_value_t'. +correctly reflects the type of the value in the `awk_value_t' struct. Conceptually, the first three members of the `union' (number, string, and array) are all that is needed for working with `awk' values. However, because the API provides routines for accessing and changing -the value of global scalar variables only by using the variable's name, +the value of a global scalar variable only by using the variable's name, there is a performance penalty: `gawk' must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -23159,17 +23162,19 @@ just a theoretical one. reading and/or changing the value of one or more scalar variables, you can obtain a "scalar cookie"(1) object for that variable, and then use the cookie for getting the variable's value or for changing the -variable's value. This is the `awk_scalar_t' type and `scalar_cookie' -macro. Given a scalar cookie, `gawk' can directly retrieve or modify -the value, as required, without having to find it first. +variable's value. The `awk_scalar_t' type holds a scalar cookie, and +the `scalar_cookie' macro provides access to the value of that type in +the `awk_value_t' struct. Given a scalar cookie, `gawk' can directly +retrieve or modify the value, as required, without having to find it +first. The `awk_value_cookie_t' type and `value_cookie' macro are similar. If you know that you wish to use the same numeric or string _value_ for one or more variables, you can create the value once, retaining a "value cookie" for it, and then pass in that value cookie whenever you -wish to set the value of a variable. This saves both storage space -within the running `gawk' process as well as the time needed to create -the value. +wish to set the value of a variable. This saves storage space within +the running `gawk' process and reduces the time needed to create the +value. ---------- Footnotes ---------- @@ -23204,7 +23209,7 @@ prototypes, in the way that extension code would use them: `void gawk_free(void *ptr);' Call the correct version of `free()' to release storage that was - allocated with `gawk_malloc()', `gawk_calloc()' or + allocated with `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()'. The API has to provide these functions because it is possible for an @@ -23216,7 +23221,7 @@ version of `malloc()', unexpected behavior would likely result. Two convenience macros may be used for allocating storage from `gawk_malloc()' and `gawk_realloc()'. If the allocation fails, they cause `gawk' to exit with a fatal error message. They should be used -as if they were procedure calls that do not return a value. +as if they were procedure calls that do not return a value: `#define emalloc(pointer, type, size, message) ...' The arguments to this macro are as follows: @@ -23246,13 +23251,13 @@ as if they were procedure calls that do not return a value. make_malloced_string(message, strlen(message), & result); `#define erealloc(pointer, type, size, message) ...' - This is like `emalloc()', but it calls `gawk_realloc()', instead - of `gawk_malloc()'. The arguments are the same as for the + This is like `emalloc()', but it calls `gawk_realloc()' instead of + `gawk_malloc()'. The arguments are the same as for the `emalloc()' macro. ---------- Footnotes ---------- - (1) This is more common on MS-Windows systems, but can happen on + (1) This is more common on MS-Windows systems, but it can happen on Unix-like systems as well. @@ -23278,7 +23283,7 @@ extension code would use them: This function creates a string value in the `awk_value_t' variable pointed to by `result'. It expects `string' to be a `char *' value pointing to data previously obtained from `gawk_malloc()', - `gawk_calloc()' or `gawk_realloc()'. The idea here is that the + `gawk_calloc()', or `gawk_realloc()'. The idea here is that the data is passed directly to `gawk', which assumes responsibility for it. It returns `result'. @@ -23328,7 +23333,7 @@ Extension functions are described by the following record: The fields are: `const char *name;' - The name of the new function. `awk' level code calls the function + The name of the new function. `awk'-level code calls the function by this name. This is a regular C string. Function names must obey the rules for `awk' identifiers. That is, @@ -23340,7 +23345,7 @@ Extension functions are described by the following record: This is a pointer to the C function that provides the extension's functionality. The function must fill in `*result' with either a number or a string. `gawk' takes ownership of any string memory. - As mentioned earlier, string memory *must* come from one of + As mentioned earlier, string memory _must_ come from one of `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()'. The `num_actual_args' argument tells the C function how many @@ -23387,10 +23392,10 @@ function with `gawk' using the following function: `gawk' intends to pass to the `exit()' system call. `arg0' - A pointer to private data which `gawk' saves in order to pass + A pointer to private data that `gawk' saves in order to pass to the function pointed to by `funcp'. - Exit callback functions are called in last-in-first-out (LIFO) + Exit callback functions are called in last-in, first-out (LIFO) order--that is, in the reverse order in which they are registered with `gawk'. @@ -23400,8 +23405,8 @@ File: gawk.info, Node: Extension Version String, Next: Input Parsers, Prev: E 16.4.5.3 Registering An Extension Version String ................................................ -You can register a version string which indicates the name and version -of your extension, with `gawk', as follows: +You can register a version string that indicates the name and version +of your extension with `gawk', as follows: `void register_ext_version(const char *version);' Register the string pointed to by `version' with `gawk'. Note @@ -23424,7 +23429,7 @@ Files::). Additionally, it sets the value of `RT' (*note Built-in Variables::). If you want, you can provide your own custom input parser. An input -parser's job is to return a record to the `gawk' record processing +parser's job is to return a record to the `gawk' record-processing code, along with indicators for the value and length of the data to be used for `RT', if any. @@ -23441,10 +23446,10 @@ used for `RT', if any. `awk_bool_t XXX_take_control_of(awk_input_buf_t *iobuf);' When `gawk' decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill - in certain fields in the `awk_input_buf_t' structure, and ensure + in certain fields in the `awk_input_buf_t' structure and ensure that certain conditions are true. It should then return true. If - an error of some kind occurs, it should not fill in any fields, - and should return false; then `gawk' will not use the input parser. + an error of some kind occurs, it should not fill in any fields and + should return false; then `gawk' will not use the input parser. The details are presented shortly. Your extension should package these functions inside an @@ -23521,10 +23526,10 @@ the `struct stat', or any combination of these factors. Once `XXX_can_take_file()' has returned true, and `gawk' has decided to use your input parser, it calls `XXX_take_control_of()'. That -function then fills one of either the `get_record' field or the -`read_func' field in the `awk_input_buf_t'. It must also ensure that -`fd' is _not_ set to `INVALID_HANDLE'. The following list describes -the fields that may be filled by `XXX_take_control_of()': +function then fills either the `get_record' field or the `read_func' +field in the `awk_input_buf_t'. It must also ensure that `fd' is _not_ +set to `INVALID_HANDLE'. The following list describes the fields that +may be filled by `XXX_take_control_of()': `void *opaque;' This is used to hold any state information needed by the input @@ -23541,22 +23546,22 @@ the fields that may be filled by `XXX_take_control_of()': Its behavior is described in the text following this list. `ssize_t (*read_func)();' - This function pointer should point to function that has the same + This function pointer should point to a function that has the same behavior as the standard POSIX `read()' system call. It is an alternative to the `get_record' pointer. Its behavior is also described in the text following this list. `void (*close_func)(struct awk_input *iobuf);' This function pointer should point to a function that does the - "tear down." It should release any resources allocated by + "teardown." It should release any resources allocated by `XXX_take_control_of()'. It may also close the file. If it does so, it should set the `fd' field to `INVALID_HANDLE'. If `fd' is still not `INVALID_HANDLE' after the call to this function, `gawk' calls the regular `close()' system call. - Having a "tear down" function is optional. If your input parser - does not need it, do not set this field. Then, `gawk' calls the + Having a "teardown" function is optional. If your input parser does + not need it, do not set this field. Then, `gawk' calls the regular `close()' system call on the file descriptor, so it should be valid. @@ -23564,7 +23569,7 @@ the fields that may be filled by `XXX_take_control_of()': records. The parameters are as follows: `char **out' - This is a pointer to a `char *' variable which is set to point to + This is a pointer to a `char *' variable that is set to point to the record. `gawk' makes its own copy of the data, so the extension must manage this storage. @@ -23613,16 +23618,16 @@ explicitly. NOTE: You must choose one method or the other: either a function that returns a record, or one that returns raw data. In particular, if you supply a function to get a record, `gawk' will - call it, and never call the raw read function. + call it, and will never call the raw read function. `gawk' ships with a sample extension that reads directories, -returning records for each entry in the directory (*note Extension -Sample Readdir::). You may wish to use that code as a guide for writing -your own input parser. +returning records for each entry in a directory (*note Extension Sample +Readdir::). You may wish to use that code as a guide for writing your +own input parser. When writing an input parser, you should think about (and document) how it is expected to interact with `awk' code. You may want it to -always be called, and take effect as appropriate (as the `readdir' +always be called, and to take effect as appropriate (as the `readdir' extension does). Or you may want it to take effect based upon the value of an `awk' variable, as the XML extension from the `gawkextlib' project does (*note gawkextlib::). In the latter case, code in a @@ -23722,17 +23727,17 @@ in the `awk_output_buf_t'. The data members are as follows: These pointers should be set to point to functions that perform the equivalent function as the `<stdio.h>' functions do, if appropriate. `gawk' uses these function pointers for all output. - `gawk' initializes the pointers to point to internal, "pass - through" functions that just call the regular `<stdio.h>' - functions, so an extension only needs to redefine those functions - that are appropriate for what it does. + `gawk' initializes the pointers to point to internal "pass-through" + functions that just call the regular `<stdio.h>' functions, so an + extension only needs to redefine those functions that are + appropriate for what it does. The `XXX_can_take_file()' function should make a decision based upon the `name' and `mode' fields, and any additional state (such as `awk' variable values) that is appropriate. When `gawk' calls `XXX_take_control_of()', that function should fill -in the other fields, as appropriate, except for `fp', which it should +in the other fields as appropriate, except for `fp', which it should just use normally. You register your output wrapper with the following function: @@ -23769,16 +23774,17 @@ structures as described earlier. The name of the two-way processor. `awk_bool_t (*can_take_two_way)(const char *name);' - This function returns true if it wants to take over two-way I/O - for this file name. It should not change any state (variable - values, etc.) within `gawk'. + The function pointed to by this field should return true if it + wants to take over two-way I/O for this file name. It should not + change any state (variable values, etc.) within `gawk'. `awk_bool_t (*take_control_of)(const char *name,' ` awk_input_buf_t *inbuf,' ` awk_output_buf_t *outbuf);' - This function should fill in the `awk_input_buf_t' and - `awk_outut_buf_t' structures pointed to by `inbuf' and `outbuf', - respectively. These structures were described earlier. + The function pointed to by this field should fill in the + `awk_input_buf_t' and `awk_outut_buf_t' structures pointed to by + `inbuf' and `outbuf', respectively. These structures were + described earlier. `awk_const struct two_way_processor *awk_const next;' This is for use by `gawk'; therefore it is marked `awk_const' so @@ -23802,7 +23808,7 @@ File: gawk.info, Node: Printing Messages, Next: Updating `ERRNO', Prev: Regis You can print different kinds of warning messages from your extension, as described here. Note that for these functions, you must pass in the -extension id received from `gawk' when the extension was loaded:(1) +extension ID received from `gawk' when the extension was loaded:(1) `void fatal(awk_ext_id_t id, const char *format, ...);' Print a message and then cause `gawk' to exit immediately. @@ -23858,7 +23864,7 @@ value you expect. If the actual value matches what you requested, the function returns true and fills in the `awk_value_t' result. Otherwise, the function returns false, and the `val_type' member indicates the type of the actual value. You may then print an error -message, or reissue the request for the actual value type, as +message or reissue the request for the actual value type, as appropriate. This behavior is summarized in *note table-value-types-returned::. @@ -23867,15 +23873,15 @@ table-value-types-returned::. String Number Array Undefined ------------------------------------------------------------------------------ - String String String false false - Number Number if can Number false false + String String String False False + Number Number if can Number False False be converted, else false -Type Array false false Array false -Requested Scalar Scalar Scalar false false +Type Array False False Array False +Requested Scalar Scalar Scalar False False Undefined String Number Array Undefined - Value false false false false - Cookie + Value False False False False + cookie Table 16.1: API value types returned @@ -23892,16 +23898,16 @@ your extension function. They are: ` awk_valtype_t wanted,' ` awk_value_t *result);' Fill in the `awk_value_t' structure pointed to by `result' with - the `count''th argument. Return true if the actual type matches - `wanted', false otherwise. In the latter case, `result->val_type' - indicates the actual type (*note Table 16.1: - table-value-types-returned.). Counts are zero based--the first + the `count'th argument. Return true if the actual type matches + `wanted', and false otherwise. In the latter case, + `result->val_type' indicates the actual type (*note Table 16.1: + table-value-types-returned.). Counts are zero-based--the first argument is numbered zero, the second one, and so on. `wanted' indicates the type of value expected. `awk_bool_t set_argument(size_t count, awk_array_t array);' Convert a parameter that was undefined into an array; this provides - call-by-reference for arrays. Return false if `count' is too big, + call by reference for arrays. Return false if `count' is too big, or if the argument's type is not undefined. *Note Array Manipulation::, for more information on creating arrays. @@ -23929,8 +23935,8 @@ File: gawk.info, Node: Symbol table by name, Next: Symbol table by cookie, Up The following routines provide the ability to access and update global `awk'-level variables by name. In compiler terminology, identifiers of different kinds are termed "symbols", thus the "sym" in the routines' -names. The data structure which stores information about symbols is -termed a "symbol table". +names. The data structure that stores information about symbols is +termed a "symbol table". The functions are as follows: `awk_bool_t sym_lookup(const char *name,' ` awk_valtype_t wanted,' @@ -23938,14 +23944,14 @@ termed a "symbol table". Fill in the `awk_value_t' structure pointed to by `result' with the value of the variable named by the string `name', which is a regular C string. `wanted' indicates the type of value expected. - Return true if the actual type matches `wanted', false otherwise. - In the latter case, `result->val_type' indicates the actual type - (*note Table 16.1: table-value-types-returned.). + Return true if the actual type matches `wanted', and false + otherwise. In the latter case, `result->val_type' indicates the + actual type (*note Table 16.1: table-value-types-returned.). `awk_bool_t sym_update(const char *name, awk_value_t *value);' Update the variable named by the string `name', which is a regular C string. The variable is added to `gawk''s symbol table if it is - not there. Return true if everything worked, false otherwise. + not there. Return true if everything worked, and false otherwise. Changing types (scalar to array or vice versa) of an existing variable is _not_ allowed, nor may this routine be used to update @@ -23970,7 +23976,7 @@ File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Sym A "scalar cookie" is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in `gawk''s symbol table every time access is needed. This -was discussed earlier in *note General Data Types::. +was discussed earlier, in *note General Data Types::. The following functions let you work with scalar cookies: @@ -24081,7 +24087,7 @@ File: gawk.info, Node: Cached values, Prev: Symbol table by cookie, Up: Symbo .......................................... The routines in this section allow you to create and release cached -values. As with scalar cookies, in theory, cached values are not +values. Like scalar cookies, in theory, cached values are not necessary. You can create numbers and strings using the functions in *note Constructor Functions::. You can then assign those values to variables using `sym_update()' or `sym_update_scalar()', as you like. @@ -24152,7 +24158,7 @@ Using value cookies in this way saves considerable storage, as all of `VAR1' through `VAR100' share the same value. You might be wondering, "Is this sharing problematic? What happens -if `awk' code assigns a new value to `VAR1', are all the others changed +if `awk' code assigns a new value to `VAR1'; are all the others changed too?" That's a great question. The answer is that no, it's not a problem. @@ -24271,7 +24277,7 @@ File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev: Array 16.4.11.2 Array Functions ......................... -The following functions relate to individual array elements. +The following functions relate to individual array elements: `awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);' For the array represented by `a_cookie', place in `*count' the @@ -24289,13 +24295,14 @@ The following functions relate to individual array elements. (*note Table 16.1: table-value-types-returned.). The value for `index' can be numeric, in which case `gawk' - converts it to a string. Using non-integral values is possible, but + converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to - strings (*note Conversion::); thus using integral values is safest. + strings (*note Conversion::); thus, using integral values is + safest. As with _all_ strings passed into `gawk' from an extension, the string value of `index' must come from `gawk_malloc()', - `gawk_calloc()' or `gawk_realloc()', and `gawk' releases the + `gawk_calloc()', or `gawk_realloc()', and `gawk' releases the storage. `awk_bool_t set_array_element(awk_array_t a_cookie,' @@ -24339,9 +24346,9 @@ The following functions relate to individual array elements. `awk_bool_t release_flattened_array(awk_array_t a_cookie,' ` awk_flat_array_t *data);' When done with a flattened array, release the storage using this - function. You must pass in both the original array cookie, and - the address of the created `awk_flat_array_t' structure. The - function returns true upon success, false otherwise. + function. You must pass in both the original array cookie and the + address of the created `awk_flat_array_t' structure. The function + returns true upon success, false otherwise. File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array Functions, Up: Array Manipulation @@ -24351,8 +24358,8 @@ File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array To "flatten" an array is to create a structure that represents the full array in a fashion that makes it easy for C code to traverse the entire -array. Test code in `extension/testext.c' does this, and also serves -as a nice example showing how to use the APIs. +array. Some of the code in `extension/testext.c' does this, and also +serves as a nice example showing how to use the APIs. We walk through that part of the code one step at a time. First, the `gawk' script that drives the test extension: @@ -24401,9 +24408,8 @@ number of arguments: } The function then proceeds in steps, as follows. First, retrieve the -name of the array, passed as the first argument. Then retrieve the -array itself. If either operation fails, print error messages and -return: +name of the array, passed as the first argument, followed by the array +itself. If either operation fails, print an error message and return: /* get argument named array as flat array and print it */ if (get_argument(0, AWK_STRING, & value)) { @@ -24433,9 +24439,9 @@ count of elements in the array and print it: printf("dump_array_and_delete: incoming size is %lu\n", (unsigned long) count); - The third step is to actually flatten the array, and then to double -check that the count in the `awk_flat_array_t' is the same as the count -just retrieved: + The third step is to actually flatten the array, and then to +double-check that the count in the `awk_flat_array_t' is the same as +the count just retrieved: if (! flatten_array(value2.array_cookie, & flat_array)) { printf("dump_array_and_delete: could not flatten array\n"); @@ -24452,7 +24458,7 @@ just retrieved: The fourth step is to retrieve the index of the element to be deleted, which was passed as the second argument. Remember that -argument counts passed to `get_argument()' are zero-based, thus the +argument counts passed to `get_argument()' are zero-based, and thus the second argument is numbered one: if (! get_argument(1, AWK_STRING, & value3)) { @@ -24465,7 +24471,7 @@ over every element in the array, printing the index and element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the `AWK_ELEMENT_DELETE' bit in the `flags' field of the element. When the array is released, `gawk' -traverses the flattened array, and deletes any elements which have this +traverses the flattened array, and deletes any elements that have this flag bit set: for (i = 0; i < flat_array->count; i++) { @@ -24683,10 +24689,10 @@ The API provides both a "major" and a "minor" version number. The API versions are available at compile time as constants: `GAWK_API_MAJOR_VERSION' - The major version of the API. + The major version of the API `GAWK_API_MINOR_VERSION' - The minor version of the API. + The minor version of the API The minor version increases when new functions are added to the API. Such new functions are always added to the end of the API `struct'. @@ -24701,13 +24707,13 @@ For this reason, the major and minor API versions of the running `gawk' are included in the API `struct' as read-only constant integers: `api->major_version' - The major version of the running `gawk'. + The major version of the running `gawk' `api->minor_version' - The minor version of the running `gawk'. + The minor version of the running `gawk' It is up to the extension to decide if there are API -incompatibilities. Typically a check like this is enough: +incompatibilities. Typically, a check like this is enough: if (api->major_version != GAWK_API_MAJOR_VERSION || api->minor_version < GAWK_API_MINOR_VERSION) { @@ -24719,7 +24725,7 @@ incompatibilities. Typically a check like this is enough: } Such code is included in the boilerplate `dl_load_func()' macro -provided in `gawkapi.h' (discussed later, in *note Extension API +provided in `gawkapi.h' (discussed in *note Extension API Boilerplate::). @@ -24770,7 +24776,7 @@ functions) toward the top of your source file, using predefined names as described here. The boilerplate needed is also provided in comments in the `gawkapi.h' header file: - /* Boiler plate code: */ + /* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -24820,7 +24826,7 @@ in the `gawkapi.h' header file: to point to a string giving the name and version of your extension. `static awk_ext_func_t func_table[] = { ... };' - This is an array of one or more `awk_ext_func_t' structures as + This is an array of one or more `awk_ext_func_t' structures, as described earlier (*note Extension Functions::). It can then be looped over for multiple calls to `add_ext_func()'. @@ -24933,7 +24939,7 @@ appropriate information: `stat()' fails. It fills in the following elements: `"name"' - The name of the file that was `stat()''ed. + The name of the file that was `stat()'ed. `"dev"' `"ino"' @@ -24981,7 +24987,7 @@ appropriate information: The file is a directory. `"fifo"' - The file is a named-pipe (also known as a FIFO). + The file is a named pipe (also known as a FIFO). `"file"' The file is just a regular file. @@ -25001,7 +25007,7 @@ appropriate information: systems, "a priori" knowledge is used to provide a value. Where no value can be determined, it defaults to 512. - Several additional elements may be present depending upon the + Several additional elements may be present, depending upon the operating system and the type of the file. You can test for them in your `awk' program by using the `in' operator (*note Reference to Elements::): @@ -25030,9 +25036,9 @@ File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops, Prev Here is the C code for these extensions.(1) The file includes a number of standard header files, and then -includes the `gawkapi.h' header file which provides the API definitions. -Those are followed by the necessary variable declarations to make use -of the API macros and boilerplate code (*note Extension API +includes the `gawkapi.h' header file, which provides the API +definitions. Those are followed by the necessary variable declarations +to make use of the API macros and boilerplate code (*note Extension API Boilerplate::): #ifdef HAVE_CONFIG_H @@ -25068,9 +25074,9 @@ Boilerplate::): By convention, for an `awk' function `foo()', the C function that implements it is called `do_foo()'. The function should have two -arguments: the first is an `int' usually called `nargs', that +arguments. The first is an `int', usually called `nargs', that represents the number of actual arguments for the function. The second -is a pointer to an `awk_value_t', usually named `result': +is a pointer to an `awk_value_t' structure, usually named `result': /* do_chdir --- provide dynamically loaded chdir() function for gawk */ @@ -25106,8 +25112,8 @@ is numbered zero. } The `stat()' extension is more involved. First comes a function -that turns a numeric mode into a printable representation (e.g., 644 -becomes `-rw-r--r--'). This is omitted here for brevity: +that turns a numeric mode into a printable representation (e.g., octal +`0644' becomes `-rw-r--r--'). This is omitted here for brevity: /* format_mode --- turn a stat mode field into something readable */ @@ -25157,8 +25163,8 @@ contain the result of the `stat()': The following function does most of the work to fill in the `awk_array_t' result array with values obtained from a valid `struct -stat'. It is done in a separate function to support the `stat()' -function for `gawk' and also to support the `fts()' extension which is +stat'. This work is done in a separate function to support the `stat()' +function for `gawk' and also to support the `fts()' extension, which is included in the same file but whose code is not shown here (*note Extension Sample File Functions::). @@ -25270,8 +25276,8 @@ argument is optional. If present, it causes `do_stat()' to use the `stat()' system call instead of the `lstat()' system call. This is done by using a function pointer: `statfunc'. `statfunc' is initialized to point to `lstat()' (instead of `stat()') to get the file -information, in case the file is a symbolic link. However, if there -were three arguments, `statfunc' is set point to `stat()', instead. +information, in case the file is a symbolic link. However, if the third +argument is included, `statfunc' is set to point to `stat()', instead. Here is the `do_stat()' function, which starts with variable declarations and argument checking: @@ -25320,7 +25326,7 @@ returns: /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) { update_ERRNO_int(errno); @@ -25339,7 +25345,8 @@ When done, the function returns the result from `fill_stat_array()': function(s) into `gawk'. The `filefuncs' extension also provides an `fts()' function, which -we omit here. For its sake there is an initialization function: +we omit here (*note Extension Sample File Functions::). For its sake, +there is an initialization function: /* init_filefuncs --- initialization routine */ @@ -25463,9 +25470,9 @@ File: gawk.info, Node: Extension Samples, Next: gawkextlib, Prev: Extension E 16.7 The Sample Extensions in the `gawk' Distribution ===================================================== -This minor node provides brief overviews of the sample extensions that +This minor node provides a brief overview of the sample extensions that come in the `gawk' distribution. Some of them are intended for -production use (e.g., the `filefuncs', `readdir' and `inplace' +production use (e.g., the `filefuncs', `readdir', and `inplace' extensions). Others mainly provide example code that shows how to use the extension API. @@ -25502,13 +25509,13 @@ follows. The usage is: `result = chdir("/some/directory")' The `chdir()' function is a direct hook to the `chdir()' system call to change the current directory. It returns zero upon - success or less than zero upon error. In the latter case, it - updates `ERRNO'. + success or a value less than zero upon error. In the latter case, + it updates `ERRNO'. `result = stat("/some/path", statdata' [`, follow']`)' The `stat()' function provides a hook into the `stat()' system - call. It returns zero upon success or less than zero upon error. - In the latter case, it updates `ERRNO'. + call. It returns zero upon success or a value less than zero upon + error. In the latter case, it updates `ERRNO'. By default, it uses the `lstat()' system call. However, if passed a third argument, it uses `stat()' instead. @@ -25535,23 +25542,23 @@ follows. The usage is: `"minor"' `st_minor' Device files `"blksize"'`st_blksize' All `"pmode"' A human-readable version of the All - mode value, such as printed by - `ls'. For example, - `"-rwxr-xr-x"' + mode value, like that printed by + `ls' (for example, + `"-rwxr-xr-x"') `"linkval"'The value of the symbolic link Symbolic links - `"type"' The type of the file as a string. All - One of `"file"', `"blockdev"', - `"chardev"', `"directory"', - `"socket"', `"fifo"', `"symlink"', - `"door"', or `"unknown"'. Not - all systems support all file - types. + `"type"' The type of the file as a All + string--one of `"file"', + `"blockdev"', `"chardev"', + `"directory"', `"socket"', + `"fifo"', `"symlink"', `"door"', + or `"unknown"' (not all systems + support all file types) `flags = or(FTS_PHYSICAL, ...)' `result = fts(pathlist, flags, filedata)' Walk the file trees provided in `pathlist' and fill in the - `filedata' array as described next. `flags' is the bitwise OR of + `filedata' array, as described next. `flags' is the bitwise OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return -1. @@ -25604,10 +25611,11 @@ requested hierarchies. filesystem. `filedata' - The `filedata' array is first cleared. Then, `fts()' creates an - element in `filedata' for every element in `pathlist'. The index - is the name of the directory or file given in `pathlist'. The - element for this index is itself an array. There are two cases: + The `filedata' array holds the results. `fts()' first clears it. + Then it creates an element in `filedata' for every element in + `pathlist'. The index is the name of the directory or file given + in `pathlist'. The element for this index is itself an array. + There are two cases: _The path is a file_ In this case, the array contains two or three elements: @@ -25643,7 +25651,7 @@ requested hierarchies. elements as for a file: `"path"', `"stat"', and `"error"'. The `fts()' function returns zero if there were no errors. -Otherwise it returns -1. +Otherwise, it returns -1. NOTE: The `fts()' extension does not exactly mimic the interface of the C library `fts()' routines, choosing instead to provide an @@ -25682,14 +25690,14 @@ adds one constant (`FNM_NOMATCH'), and an array of flag values named The arguments to `fnmatch()' are: `pattern' - The file name wildcard to match. + The file name wildcard to match `string' - The file name string. + The file name string `flag' Either zero, or the bitwise OR of one or more of the flags in the - `FNM' array. + `FNM' array The flags are as follows: @@ -25723,13 +25731,13 @@ The `fork' extension adds three functions, as follows: `pid = fork()' This function creates a new process. The return value is zero in - the child and the process-ID number of the child in the parent, or + the child and the process ID number of the child in the parent, or -1 upon error. In the latter case, `ERRNO' indicates the problem. In the child, `PROCINFO["pid"]' and `PROCINFO["ppid"]' are updated to reflect the correct values. `ret = waitpid(pid)' - This function takes a numeric argument, which is the process-ID to + This function takes a numeric argument, which is the process ID to wait for. The return value is that of the `waitpid()' system call. `ret = wait()' @@ -25753,8 +25761,8 @@ File: gawk.info, Node: Extension Sample Inplace, Next: Extension Sample Ord, 16.7.4 Enabling In-Place File Editing ------------------------------------- -The `inplace' extension emulates GNU `sed''s `-i' option which performs -"in place" editing of each input file. It uses the bundled +The `inplace' extension emulates GNU `sed''s `-i' option, which +performs "in-place" editing of each input file. It uses the bundled `inplace.awk' include file to invoke the extension properly: # inplace --- load and invoke the inplace extension. @@ -25837,11 +25845,11 @@ returned as a record. The record consists of three fields. The first two are the inode number and the file name, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +has a third field (also separated by a slash), which is a single letter indicating the type of the file. The letters and their corresponding file types are shown in *note table-readdir-file-types::. -Letter File Type +Letter File type -------------------------------------------------------------------------- `b' Block device `c' Character device @@ -25888,7 +25896,7 @@ unwary. Here is an example: print "don't panic" > "/dev/stdout" } - The output from this program is: `cinap t'nod'. + The output from this program is `cinap t'nod'. File: gawk.info, Node: Extension Sample Rev2way, Next: Extension Sample Read write array, Prev: Extension Sample Revout, Up: Extension Samples @@ -25936,7 +25944,7 @@ The `rwarray' extension adds two functions, named `writea()' and `reada()' is the inverse of `writea()'; it reads the file named as its first argument, filling in the array named as the second argument. It clears the array first. Here too, the return value - is one on success and zero upon failure. + is one on success, or zero upon failure. The array created by `reada()' is identical to that written by `writea()' in the sense that the contents are the same. However, due to @@ -26020,7 +26028,7 @@ The `time' extension adds two functions, named `gettimeofday()' and Attempt to sleep for SECONDS seconds. If SECONDS is negative, or the attempt to sleep fails, return -1 and set `ERRNO'. Otherwise, return zero after sleeping for the indicated amount of time. Note - that SECONDS may be a floating-point (non-integral) value. + that SECONDS may be a floating-point (nonintegral) value. Implementation details: depending on platform availability, this function tries to use `nanosleep()' or `select()' to implement the delay. @@ -26048,7 +26056,9 @@ provides a number of `gawk' extensions, including one for processing XML files. This is the evolution of the original `xgawk' (XML `gawk') project. - As of this writing, there are six extensions: + As of this writing, there are seven extensions: + + * `errno' extension * GD graphics library extension @@ -26057,7 +26067,7 @@ project. * PostgreSQL extension * MPFR library extension (this provides access to a number of MPFR - functions which `gawk''s native MPFR support does not) + functions that `gawk''s native MPFR support does not) * Redis extension @@ -26098,7 +26108,7 @@ follows. First, build and install `gawk': If you have installed `gawk' in the standard way, then you will likely not need the `--with-gawk' option when configuring `gawkextlib'. -You may also need to use the `sudo' utility to install both `gawk' and +You may need to use the `sudo' utility to install both `gawk' and `gawkextlib', depending upon how your system works. If you write an extension that you wish to share with other `gawk' @@ -26120,7 +26130,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga a variable named `plugin_is_GPL_compatible'. * Communication between `gawk' and an extension is two-way. `gawk' - passes a `struct' to the extension which contains various data + passes a `struct' to the extension that contains various data fields and function pointers. The extension can then call into `gawk' via the supplied function pointers to accomplish certain tasks. @@ -26131,7 +26141,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga convention, implementation functions are named `do_XXXX()' for some `awk'-level function `XXXX()'. - * The API is defined in a header file named `gawkpi.h'. You must + * The API is defined in a header file named `gawkapi.h'. You must include a number of standard header files _before_ including it in your source file. @@ -26161,16 +26171,16 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * Manipulating arrays (retrieving, adding, deleting, and modifying elements; getting the count of elements in an array; creating a new array; clearing an array; and flattening an - array for easy C style looping over all its indices and + array for easy C-style looping over all its indices and elements) * The API defines a number of standard data types for representing `awk' values, array elements, and arrays. - * The API provide convenience functions for constructing values. It - also provides memory management functions to ensure compatibility - between memory allocated by `gawk' and memory allocated by an - extension. + * The API provides convenience functions for constructing values. + It also provides memory management functions to ensure + compatibility between memory allocated by `gawk' and memory + allocated by an extension. * _All_ memory passed from `gawk' to an extension must be treated as read-only by the extension. @@ -26188,8 +26198,8 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga header file make this easier to do. * The `gawk' distribution includes a number of small but useful - sample extensions. The `gawkextlib' project includes several more, - larger, extensions. If you wish to write an extension and + sample extensions. The `gawkextlib' project includes several more + (larger) extensions. If you wish to write an extension and contribute it to the community of `gawk' users, the `gawkextlib' project is the place to do so. @@ -26259,56 +26269,56 @@ available in System V Release 3.1 (1987). This minor node summarizes the changes, with cross-references to further details: * The requirement for `;' to separate rules on a line (*note - Statements/Lines::). + Statements/Lines::) * User-defined functions and the `return' statement (*note - User-defined::). + User-defined::) * The `delete' statement (*note Delete::). - * The `do'-`while' statement (*note Do Statement::). + * The `do'-`while' statement (*note Do Statement::) * The built-in functions `atan2()', `cos()', `sin()', `rand()', and - `srand()' (*note Numeric Functions::). + `srand()' (*note Numeric Functions::) * The built-in functions `gsub()', `sub()', and `match()' (*note - String Functions::). + String Functions::) * The built-in functions `close()' and `system()' (*note I/O - Functions::). + Functions::) * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP' - predefined variables (*note Built-in Variables::). + predefined variables (*note Built-in Variables::) - * Assignable `$0' (*note Changing Fields::). + * Assignable `$0' (*note Changing Fields::) * The conditional expression using the ternary operator `?:' (*note - Conditional Exp::). + Conditional Exp::) - * The expression `INDEX-VARIABLE in ARRAY' outside of `for' - statements (*note Reference to Elements::). + * The expression `INDX in ARRAY' outside of `for' statements (*note + Reference to Elements::) * The exponentiation operator `^' (*note Arithmetic Ops::) and its - assignment operator form `^=' (*note Assignment Ops::). + assignment operator form `^=' (*note Assignment Ops::) * C-compatible operator precedence, which breaks some old `awk' - programs (*note Precedence::). + programs (*note Precedence::) * Regexps as the value of `FS' (*note Field Separators::) and as the third argument to the `split()' function (*note String - Functions::), rather than using only the first character of `FS'. + Functions::), rather than using only the first character of `FS' * Dynamic regexps as operands of the `~' and `!~' operators (*note - Computed Regexps::). + Computed Regexps::) * The escape sequences `\b', `\f', and `\r' (*note Escape - Sequences::). + Sequences::) - * Redirection of input for the `getline' function (*note Getline::). + * Redirection of input for the `getline' function (*note Getline::) - * Multiple `BEGIN' and `END' rules (*note BEGIN/END::). + * Multiple `BEGIN' and `END' rules (*note BEGIN/END::) - * Multidimensional arrays (*note Multidimensional::). + * Multidimensional arrays (*note Multidimensional::) File: gawk.info, Node: SVR4, Next: POSIX, Prev: V7/SVR3.1, Up: Language History @@ -26319,37 +26329,37 @@ A.2 Changes Between SVR3.1 and SVR4 The System V Release 4 (1989) version of Unix `awk' added these features (some of which originated in `gawk'): - * The `ENVIRON' array (*note Built-in Variables::). + * The `ENVIRON' array (*note Built-in Variables::) - * Multiple `-f' options on the command line (*note Options::). + * Multiple `-f' options on the command line (*note Options::) * The `-v' option for assigning variables before program execution - begins (*note Options::). + begins (*note Options::) - * The `--' signal for terminating command-line options. + * The `--' signal for terminating command-line options * The `\a', `\v', and `\x' escape sequences (*note Escape - Sequences::). + Sequences::) * A defined return value for the `srand()' built-in function (*note - Numeric Functions::). + Numeric Functions::) * The `toupper()' and `tolower()' built-in string functions for case - translation (*note String Functions::). + translation (*note String Functions::) * A cleaner specification for the `%c' format-control letter in the - `printf' function (*note Control Letters::). + `printf' function (*note Control Letters::) * The ability to dynamically pass the field width and precision (`"%*.*d"') in the argument list of `printf' and `sprintf()' - (*note Control Letters::). + (*note Control Letters::) * The use of regexp constants, such as `/foo/', as expressions, where they are equivalent to using the matching operator, as in `$0 ~ - /foo/' (*note Using Constant Regexps::). + /foo/' (*note Using Constant Regexps::) * Processing of escape sequences inside command-line variable - assignments (*note Assignment Options::). + assignments (*note Assignment Options::) File: gawk.info, Node: POSIX, Next: BTL, Prev: SVR4, Up: Language History @@ -26361,30 +26371,30 @@ The POSIX Command Language and Utilities standard for `awk' (1992) introduced the following changes into the language: * The use of `-W' for implementation-specific options (*note - Options::). + Options::) * The use of `CONVFMT' for controlling the conversion of numbers to - strings (*note Conversion::). + strings (*note Conversion::) * The concept of a numeric string and tighter comparison rules to go - with it (*note Typing and Comparison::). + with it (*note Typing and Comparison::) * The use of predefined variables as function parameter names is - forbidden (*note Definition Syntax::). + forbidden (*note Definition Syntax::) * More complete documentation of many of the previously undocumented - features of the language. + features of the language In 2012, a number of extensions that had been commonly available for many years were finally added to POSIX. They are: * The `fflush()' built-in function for flushing buffered output - (*note I/O Functions::). + (*note I/O Functions::) - * The `nextfile' statement (*note Nextfile Statement::). + * The `nextfile' statement (*note Nextfile Statement::) * The ability to delete all of an array at once with `delete ARRAY' - (*note Delete::). + (*note Delete::) *Note Common Extensions::, for a list of common extensions not @@ -26406,13 +26416,13 @@ Other Versions::). in his version of `awk': * The `**' and `**=' operators (*note Arithmetic Ops:: and *note - Assignment Ops::). + Assignment Ops::) * The use of `func' as an abbreviation for `function' (*note - Definition Syntax::). + Definition Syntax::) * The `fflush()' built-in function for flushing buffered output - (*note I/O Functions::). + (*note I/O Functions::) *Note Common Extensions::, for a full list of the extensions @@ -26434,107 +26444,105 @@ the current version of `gawk'. * Additional predefined variables: - - The `ARGIND' `BINMODE', `ERRNO', `FIELDWIDTHS', `FPAT', + - The `ARGIND', `BINMODE', `ERRNO', `FIELDWIDTHS', `FPAT', `IGNORECASE', `LINT', `PROCINFO', `RT', and `TEXTDOMAIN' - variables (*note Built-in Variables::). + variables (*note Built-in Variables::) * Special files in I/O redirections: - - The `/dev/stdin', `/dev/stdout', `/dev/stderr' and - `/dev/fd/N' special file names (*note Special Files::). + - The `/dev/stdin', `/dev/stdout', `/dev/stderr', and + `/dev/fd/N' special file names (*note Special Files::) - The `/inet', `/inet4', and `/inet6' special files for TCP/IP networking using `|&' to specify which version of the IP - protocol to use (*note TCP/IP Networking::). + protocol to use (*note TCP/IP Networking::) * Changes and/or additions to the language: - - The `\x' escape sequence (*note Escape Sequences::). + - The `\x' escape sequence (*note Escape Sequences::) - - Full support for both POSIX and GNU regexps (*note Regexp::). + - Full support for both POSIX and GNU regexps (*note Regexp::) - The ability for `FS' and for the third argument to `split()' - to be null strings (*note Single Character Fields::). + to be null strings (*note Single Character Fields::) - - The ability for `RS' to be a regexp (*note Records::). + - The ability for `RS' to be a regexp (*note Records::) - The ability to use octal and hexadecimal constants in `awk' - program source code (*note Nondecimal-numbers::). + program source code (*note Nondecimal-numbers::) - The `|&' operator for two-way I/O to a coprocess (*note - Two-way I/O::). + Two-way I/O::) - - Indirect function calls (*note Indirect Calls::). + - 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: - The `BEGINFILE' and `ENDFILE' special patterns (*note - BEGINFILE/ENDFILE::). + BEGINFILE/ENDFILE::) - - The `switch' statement (*note Switch Statement::). + - The `switch' statement (*note Switch Statement::) * Changes to standard `awk' functions: - The optional second argument to `close()' that allows closing - one end of a two-way pipe to a coprocess (*note Two-way - I/O::). + one end of a two-way pipe to a coprocess (*note Two-way I/O::) - - POSIX compliance for `gsub()' and `sub()' with `--posix'. + - POSIX compliance for `gsub()' and `sub()' with `--posix' - The `length()' function accepts an array argument and returns - the number of elements in the array (*note String - Functions::). + the number of elements in the array (*note String Functions::) - The optional third argument to the `match()' function for capturing text-matching subexpressions within a regexp (*note - String Functions::). + String Functions::) - Positional specifiers in `printf' formats for making - translations easier (*note Printf Ordering::). + translations easier (*note Printf Ordering::) - - The `split()' function's additional optional fourth argument + - The `split()' function's additional optional fourth argument, which is an array to hold the text of the field separators - (*note String Functions::). + (*note String Functions::) * Additional functions only in `gawk': - The `gensub()', `patsplit()', and `strtonum()' functions for - more powerful text manipulation (*note String Functions::). + more powerful text manipulation (*note String Functions::) - The `asort()' and `asorti()' functions for sorting arrays - (*note Array Sorting::). + (*note Array Sorting::) - The `mktime()', `systime()', and `strftime()' functions for - working with timestamps (*note Time Functions::). + working with timestamps (*note Time Functions::) - The `and()', `compl()', `lshift()', `or()', `rshift()', and `xor()' functions for bit manipulation (*note Bitwise - Functions::). + Functions::) - The `isarray()' function to check if a variable is an array - or not (*note Type Functions::). + or not (*note Type Functions::) - - The `bindtextdomain()', `dcgettext()' and `dcngettext()' - functions for internationalization (*note Programmer i18n::). + - The `bindtextdomain()', `dcgettext()', and `dcngettext()' + functions for internationalization (*note Programmer i18n::) - The `div()' function for doing integer division and remainder - (*note Numeric Functions::). + (*note Numeric Functions::) * Changes and/or additions in the command-line options: - The `AWKPATH' environment variable for specifying a path - search for the `-f' command-line option (*note Options::). + search for the `-f' command-line option (*note Options::) - The `AWKLIBPATH' environment variable for specifying a path - search for the `-l' command-line option (*note Options::). + search for the `-l' command-line option (*note Options::) - The `-b', `-c', `-C', `-d', `-D', `-e', `-E', `-g', `-h', `-i', `-l', `-L', `-M', `-n', `-N', `-o', `-O', `-p', `-P', `-r', `-S', `-t', and `-V' short options. Also, the ability - to use GNU-style long-named options that start with `--' and + to use GNU-style long-named options that start with `--', and the `--assign', `--bignum', `--characters-as-bytes', `--copyright', `--debug', `--dump-variables', `--exec', `--field-separator', `--file', `--gen-pot', `--help', @@ -26572,8 +26580,8 @@ the current version of `gawk'. - GCC for VAX and Alpha has not been tested for a while. - * Support for the following obsolete systems was removed from the - code for `gawk' version 4.1: + * Support for the following obsolete system was removed from the code + for `gawk' version 4.1: - Ultrix @@ -26998,22 +27006,22 @@ The following table summarizes the common extensions supported by `gawk', Brian Kernighan's `awk', and `mawk', the three most widely used freely available versions of `awk' (*note Other Versions::). -Feature BWK Awk Mawk GNU Awk Now standard ------------------------------------------------------------------------ -`\x' Escape sequence X X X -`FS' as null string X X X -`/dev/stdin' special file X X X -`/dev/stdout' special file X X X -`/dev/stderr' special file X X X -`delete' without subscript X X X X -`fflush()' function X X X X -`length()' of an array X X X -`nextfile' statement X X X X -`**' and `**=' operators X X -`func' keyword X X -`BINMODE' variable X X -`RS' as regexp X X -Time-related functions X X +Feature BWK `awk' `mawk' `gawk' Now standard +-------------------------------------------------------------------------- +`\x' escape sequence X X X +`FS' as null string X X X +`/dev/stdin' special file X X X +`/dev/stdout' special file X X X +`/dev/stderr' special file X X X +`delete' without subscript X X X X +`fflush()' function X X X X +`length()' of an array X X X +`nextfile' statement X X X X +`**' and `**=' operators X X +`func' keyword X X +`BINMODE' variable X X +`RS' as regexp X X +Time-related functions X X File: gawk.info, Node: Ranges and Locales, Next: Contributors, Prev: Common Extensions, Up: Language History @@ -27033,7 +27041,7 @@ in the machine's native character set. Thus, on ASCII-based systems, `[a-z]' matched all the lowercase letters, and only the lowercase letters, as the numeric values for the letters from `a' through `z' were contiguous. (On an EBCDIC system, the range `[a-z]' includes -additional, non-alphabetic characters as well.) +additional nonalphabetic characters as well.) Almost all introductory Unix literature explained range expressions as working in this fashion, and in particular, would teach that the @@ -27057,7 +27065,7 @@ outside those locales, the ordering was defined to be based on What does that mean? In many locales, `A' and `a' are both less than `B'. In other words, these locales sort characters in dictionary order, and `[a-dx-z]' is typically not equivalent to `[abcdxyz]'; -instead it might be equivalent to `[ABCXYabcdxyz]', for example. +instead, it might be equivalent to `[ABCXYabcdxyz]', for example. This point needs to be emphasized: much literature teaches that you should use `[a-z]' to match a lowercase character. But on systems with @@ -27081,17 +27089,17 @@ is perfectly valid in ASCII, but is not valid in many Unicode locales, such as `en_US.UTF-8'. Early versions of `gawk' used regexp matching code that was not -locale aware, so ranges had their traditional interpretation. +locale-aware, so ranges had their traditional interpretation. When `gawk' switched to using locale-aware regexp matchers, the problems began; especially as both GNU/Linux and commercial Unix vendors started implementing non-ASCII locales, _and making them the default_. Perhaps the most frequently asked question became something -like "why does `[A-Z]' match lowercase letters?!?" +like, "Why does `[A-Z]' match lowercase letters?!?" This situation existed for close to 10 years, if not more, and the `gawk' maintainer grew weary of trying to explain that `gawk' was being -nicely standards compliant, and that the issue was in the user's +nicely standards-compliant, and that the issue was in the user's locale. During the development of version 4.0, he modified `gawk' to always treat ranges in the original, pre-POSIX fashion, unless `--posix' was used (*note Options::).(2) @@ -27103,18 +27111,18 @@ of range expressions was _undefined_.(3) By using this lovely technical term, the standard gives license to implementors to implement ranges in whatever way they choose. The -`gawk' maintainer chose to apply the pre-POSIX meaning in all cases: -the default regexp matching; with `--traditional' and with `--posix'; -in all cases, `gawk' remains POSIX compliant. +`gawk' maintainer chose to apply the pre-POSIX meaning both with the +default regexp matching and when `--traditional' or `--posix' are used. +In all cases `gawk' remains POSIX-compliant. ---------- Footnotes ---------- (1) And Life was good. (2) And thus was born the Campaign for Rational Range Interpretation -(or RRI). A number of GNU tools have either implemented this change, or -will soon. Thanks to Karl Berry for coining the phrase "Rational Range -Interpretation." +(or RRI). A number of GNU tools have already implemented this change, +or will soon. Thanks to Karl Berry for coining the phrase "Rational +Range Interpretation." (3) See the standard (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03_05) @@ -27146,7 +27154,7 @@ Info file, in approximate chronological order: * Richard Stallman helped finish the implementation and the initial draft of this Info file. He is also the founder of the FSF and - the GNU project. + the GNU Project. * John Woods contributed parts of the code (mostly fixes) in the initial version of `gawk'. @@ -27232,22 +27240,22 @@ Info file, in approximate chronological order: * John Haque made the following contributions: - The modifications to convert `gawk' into a byte-code - interpreter, including the debugger. + interpreter, including the debugger - - The addition of true arrays of arrays. + - The addition of true arrays of arrays - The additional modifications for support of - arbitrary-precision arithmetic. + arbitrary-precision arithmetic - - The initial text of *note Arbitrary Precision Arithmetic::. + - The initial text of *note Arbitrary Precision Arithmetic:: - The work to merge the three versions of `gawk' into one, for - the 4.1 release. + the 4.1 release - - Improved array internals for arrays indexed by integers. + - Improved array internals for arrays indexed by integers - - The improved array sorting features were driven by John - together with Pat Rankin. + - The improved array sorting features were also driven by John, + together with Pat Rankin * Panos Papadopoulos contributed the original text for *note Include Files::. @@ -27276,11 +27284,11 @@ A.10 Summary ============ * The `awk' language has evolved over time. The first release was - with V7 Unix circa 1978. In 1987, for System V Release 3.1, major - additions, including user-defined functions, were made to the - language. Additional changes were made for System V Release 4, in - 1989. Since then, further minor changes happen under the auspices - of the POSIX standard. + with V7 Unix, circa 1978. In 1987, for System V Release 3.1, + major additions, including user-defined functions, were made to + the language. Additional changes were made for System V Release + 4, in 1989. Since then, further minor changes have happened under + the auspices of the POSIX standard. * Brian Kernighan's `awk' provides a small number of extensions that are implemented in common with other versions of `awk'. @@ -27293,7 +27301,7 @@ A.10 Summary been confusing over the years. Today, `gawk' implements Rational Range Interpretation, where ranges of the form `[a-z]' match _only_ the characters numerically between `a' through `z' in the - machine's native character set. Usually this is ASCII but it can + machine's native character set. Usually this is ASCII, but it can be EBCDIC on IBM S/390 systems. * Many people have contributed to `gawk' development over the years. @@ -27371,7 +27379,7 @@ B.1.2 Extracting the Distribution `gawk' is distributed as several `tar' files compressed with different compression programs: `gzip', `bzip2', and `xz'. For simplicity, the rest of these instructions assume you are using the one compressed with -the GNU Zip program, `gzip'. +the GNU Gzip program (`gzip'). Once you have the distribution (e.g., `gawk-4.1.2.tar.gz'), use `gzip' to expand the file and then use `tar' to extract it. You can @@ -27411,10 +27419,10 @@ files, subdirectories, and files related to the configuration process to different non-Unix operating systems: Various `.c', `.y', and `.h' files - The actual `gawk' source code. + These files contain the actual `gawk' source code. `ABOUT-NLS' - Information about GNU `gettext' and translations. + A file containing information about GNU `gettext' and translations. `AUTHORS' A file with some information about the authorship of `gawk'. It @@ -27446,7 +27454,7 @@ Various `.c', `.y', and `.h' files The GNU General Public License. `POSIX.STD' - A description of behaviors in the POSIX standard for `awk' which + A description of behaviors in the POSIX standard for `awk' that are left undefined, or where `gawk' may not comply fully, as well as a list of things that the POSIX standard should describe but does not. @@ -27710,14 +27718,16 @@ command line when compiling `gawk' from scratch, including: do nothing. Similarly, setting the `LINT' variable (*note User-modified::) has no effect on the running `awk' program. - When used with GCC's automatic dead-code-elimination, this option - cuts almost 23K bytes off the size of the `gawk' executable on - GNU/Linux x86_64 systems. Results on other systems and with other - compilers are likely to vary. Using this option may bring you - some slight performance improvement. + When used with the GNU Compiler Collection's (GCC's) automatic + dead-code-elimination, this option cuts almost 23K bytes off the + size of the `gawk' executable on GNU/Linux x86_64 systems. + Results on other systems and with other compilers are likely to + vary. Using this option may bring you some slight performance + improvement. - Using this option will cause some of the tests in the test suite - to fail. This option may be removed at a later date. + CAUTION: Using this option will cause some of the tests in + the test suite to fail. This option may be removed at a + later date. `--disable-nls' Disable all message-translation facilities. This is usually not @@ -27801,10 +27811,10 @@ B.3.1 Installation on PC Operating Systems This minor node covers installation and usage of `gawk' on Intel architecture machines running MS-DOS, any version of MS-Windows, or OS/2. In this minor node, the term "Windows32" refers to any of -Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7/8. +Microsoft Windows 95/98/ME/NT/2000/XP/Vista/7/8. The limitations of MS-DOS (and MS-DOS shells under the other -operating systems) has meant that various "DOS extenders" are often +operating systems) have meant that various "DOS extenders" are often used with programs such as `gawk'. The varying capabilities of Microsoft Windows 3.1 and Windows32 can add to the confusion. For an overview of the considerations, refer to `README_d/README.pc' in the @@ -27999,7 +28009,7 @@ The DJGPP collection of tools includes an MS-DOS port of Bash, and several shells are available for OS/2, including `ksh'. Under MS-Windows, OS/2 and MS-DOS, `gawk' (and many other text -programs) silently translate end-of-line `\r\n' to `\n' on input and +programs) silently translates end-of-line `\r\n' to `\n' on input and `\n' to `\r\n' on output. A special `BINMODE' variable (c.e.) allows control over these translations and is interpreted as follows: @@ -28021,7 +28031,7 @@ The modes for standard input and standard output are set one time only program). Setting `BINMODE' for standard input or standard output is accomplished by using an appropriate `-v BINMODE=N' option on the command line. `BINMODE' is set at the time a file or pipe is opened -and cannot be changed mid-stream. +and cannot be changed midstream. The name `BINMODE' was chosen to match `mawk' (*note Other Versions::). `mawk' and `gawk' handle `BINMODE' similarly; however, @@ -28065,10 +28075,9 @@ B.3.1.5 Using `gawk' In The Cygwin Environment `gawk' can be built and used "out of the box" under MS-Windows if you are using the Cygwin environment (http://www.cygwin.com). This -environment provides an excellent simulation of GNU/Linux, using the -GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, -and other GNU programs. Compilation and installation for Cygwin is the -same as for a Unix system: +environment provides an excellent simulation of GNU/Linux, using Bash, +GCC, GNU Make, and other GNU programs. Compilation and installation +for Cygwin is the same as for a Unix system: tar -xvpzf gawk-4.1.2.tar.gz cd gawk-4.1.2 @@ -28086,7 +28095,7 @@ B.3.1.6 Using `gawk' In The MSYS Environment ............................................ In the MSYS environment under MS-Windows, `gawk' automatically uses -binary mode for reading and writing files. Thus there is no need to +binary mode for reading and writing files. Thus, there is no need to use the `BINMODE' variable. This can cause problems with other Unix-like components that have @@ -28141,9 +28150,9 @@ available from `https://github.com/endlesssoftware/mmk'. target parameter may need to be exact. `gawk' has been tested under VAX/VMS 7.3 and Alpha/VMS 7.3-1 using -Compaq C V6.4, and Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3. -The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both Alpha -and IA64 VMS 8.4 used HP C 7.3.(1) +Compaq C V6.4, and under Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS +8.3. The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both +Alpha and IA64 VMS 8.4 used HP C 7.3.(1) *Note VMS GNV::, for information on building `gawk' as a PCSI kit that is compatible with the GNV product. @@ -28186,7 +28195,7 @@ than 32 bits. /name=(as_is,short) - Compile time macros need to be defined before the first VMS-supplied + Compile-time macros need to be defined before the first VMS-supplied header file is included, as follows: #if (__CRTL_VER >= 70200000) && !defined (__VAX) @@ -28230,14 +28239,14 @@ directory tree, the program will be known as `GNV$GNU:[vms_help]gawk.hlp'. The PCSI kit also installs a `GNV$GNU:[vms_bin]gawk_verb.cld' file -which can be used to add `gawk' and `awk' as DCL commands. +that can be used to add `gawk' and `awk' as DCL commands. For just the current process you can use: $ set command gnv$gnu:[vms_bin]gawk_verb.cld Or the system manager can use `GNV$GNU:[vms_bin]gawk_verb.cld' to -add the `gawk' and `awk' to the system wide `DCLTABLES'. +add the `gawk' and `awk' to the system-wide `DCLTABLES'. The DCL syntax is documented in the `gawk.hlp' file. @@ -28297,14 +28306,14 @@ process) are present, there is no ambiguity and `--' can be omitted. status value when the program exits. The VMS severity bits will be set based on the `exit' value. A -failure is indicated by 1 and VMS sets the `ERROR' status. A fatal -error is indicated by 2 and VMS sets the `FATAL' status. All other +failure is indicated by 1, and VMS sets the `ERROR' status. A fatal +error is indicated by 2, and VMS sets the `FATAL' status. All other values will have the `SUCCESS' status. The exit value is encoded to comply with VMS coding standards and will have the `C_FACILITY_NO' of `0x350000' with the constant `0xA000' added to the number shifted over by 3 bits to make room for the severity codes. - To extract the actual `gawk' exit code from the VMS status use: + To extract the actual `gawk' exit code from the VMS status, use: unix_status = (vms_status .and. &x7f8) / 8 @@ -28320,7 +28329,7 @@ Function::. VMS reports time values in GMT unless one of the `SYS$TIMEZONE_RULE' or `TZ' logical names is set. Older versions of VMS, such as VAX/VMS -7.3 do not set these logical names. +7.3, do not set these logical names. The default search path, when looking for `awk' program files specified by the `-f' option, is `"SYS$DISK:[],AWK_LIBRARY:"'. The @@ -28337,7 +28346,7 @@ B.3.2.5 The VMS GNV Project The VMS GNV package provides a build environment similar to POSIX with ports of a collection of open source tools. The `gawk' found in the GNV -base kit is an older port. Currently the GNV project is being +base kit is an older port. Currently, the GNV project is being reorganized to supply individual PCSI packages for each component. See `https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/'. @@ -28371,7 +28380,7 @@ B.4 Reporting Problems and Bugs Douglas Adams, `The Hitchhiker's Guide to the Galaxy' If you have problems with `gawk' or think that you have found a bug, -report it to the developers; we cannot promise to do anything but we +report it to the developers; we cannot promise to do anything, but we might well want to fix it. Before reporting a bug, make sure you have really found a genuine @@ -28382,7 +28391,7 @@ documentation! Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible `awk' program and input data file that -reproduces the problem. Then send us the program and data file, some +reproduce the problem. Then send us the program and data file, some idea of what kind of Unix system you're using, the compiler you used to compile `gawk', and the exact results `gawk' gave you. Also say what you expected to occur; this helps us decide whether the problem is @@ -28394,7 +28403,7 @@ You can get this information with the command `gawk --version'. Once you have a precise problem description, send email to <bug-gawk@gnu.org>. - The `gawk' maintainers subscribe to this address and thus they will + The `gawk' maintainers subscribe to this address, and thus they will receive your bug report. Although you can send mail to the maintainers directly, the bug reporting address is preferred because the email list is archived at the GNU Project. _All email must be in English. This is @@ -28415,8 +28424,8 @@ the only language understood in common by all the maintainers._ forward bug reports "upstream" to the GNU mailing list, many don't, so there is a good chance that the `gawk' maintainers won't even see the bug report! Second, mail to the GNU list is - archived, and having everything at the GNU project keeps things - self-contained and not dependant on other organizations. + archived, and having everything at the GNU Project keeps things + self-contained and not dependent on other organizations. Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are @@ -28425,18 +28434,19 @@ if we can. If you find bugs in one of the non-Unix ports of `gawk', send an email to the bug list, with a copy to the person who maintains that -port. They are named in the following list, as well as in the `README' -file in the `gawk' distribution. Information in the `README' file -should be considered authoritative if it conflicts with this Info file. +port. The maintainers are named in the following list, as well as in +the `README' file in the `gawk' distribution. Information in the +`README' file should be considered authoritative if it conflicts with +this Info file. The people maintaining the various `gawk' ports are: -Unix and POSIX systems Arnold Robbins, <arnold@skeeve.com>. -MS-DOS with DJGPP Scott Deifik, <scottd.mail@sbcglobal.net>. -MS-Windows with MinGW Eli Zaretskii, <eliz@gnu.org>. -OS/2 Andreas Buening, <andreas.buening@nexgo.de>. -VMS John Malmberg, <wb8tyw@qsl.net>. -z/OS (OS/390) Dave Pitts, <dpitts@cozx.com>. +Unix and POSIX systems Arnold Robbins, <arnold@skeeve.com> +MS-DOS with DJGPP Scott Deifik, <scottd.mail@sbcglobal.net> +MS-Windows with MinGW Eli Zaretskii, <eliz@gnu.org> +OS/2 Andreas Buening, <andreas.buening@nexgo.de> +VMS John Malmberg, <wb8tyw@qsl.net> +z/OS (OS/390) Dave Pitts, <dpitts@cozx.com> If your bug is also reproducible under Unix, send a copy of your report to the <bug-gawk@gnu.org> email list as well. @@ -28447,7 +28457,7 @@ File: gawk.info, Node: Other Versions, Next: Installation summary, Prev: Bugs B.5 Other Freely Available `awk' Implementations ================================================ - It's kind of fun to put comments like this in your awk code. + It's kind of fun to put comments like this in your awk code: `// Do C++ comments work? answer: yes! of course' -- Michael Brennan @@ -28470,7 +28480,7 @@ Unix `awk' Zip file `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.zip' - You can also retrieve it from Git Hub: + You can also retrieve it from GitHub: git clone git://github.com/onetrueawk/awk bwkawk @@ -28512,7 +28522,7 @@ Unix `awk' `awka' Written by Andrew Sumner, `awka' translates `awk' programs into C, compiles them, and links them with a library of functions that - provides the core `awk' functionality. It also has a number of + provide the core `awk' functionality. It also has a number of extensions. The `awk' translator is released under the GPL, and the library is @@ -28526,14 +28536,14 @@ Unix `awk' `pawk' Nelson H.F. Beebe at the University of Utah has modified BWK `awk' to provide timing and profiling information. It is different from - `gawk' with the `--profile' option (*note Profiling::), in that it + `gawk' with the `--profile' option (*note Profiling::) in that it uses CPU-based profiling, not line-count profiling. You may find it at either `ftp://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz' or `http://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz'. -Busybox Awk - Busybox is a GPL-licensed program providing small versions of many +BusyBox `awk' + BusyBox is a GPL-licensed program providing small versions of many applications within a single executable. It is aimed at embedded systems. It includes a full implementation of POSIX `awk'. When building it, be careful not to do `make install' as it will @@ -28543,7 +28553,7 @@ Busybox Awk The OpenSolaris POSIX `awk' The versions of `awk' in `/usr/xpg4/bin' and `/usr/xpg6/bin' on - Solaris are more-or-less POSIX-compliant. They are based on the + Solaris are more or less POSIX-compliant. They are based on the `awk' from Mortice Kern Systems for PCs. We were able to make this code compile and work under GNU/Linux with 1-2 hours of work. Making it more generally portable (using GNU Autoconf and/or @@ -28575,7 +28585,7 @@ Libmawk information. (This is not related to Nelson Beebe's modified version of BWK `awk', described earlier.) -QSE Awk +QSE `awk' This is an embeddable `awk' interpreter. For more information, see `http://code.google.com/p/qse/' and `http://awk.info/?tools/qse'. @@ -28593,7 +28603,7 @@ Other versions See also the "Versions and implementations" section of the Wikipedia article (http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations) - for information on additional versions. + on `awk' for information on additional versions. @@ -28602,7 +28612,7 @@ File: gawk.info, Node: Installation summary, Prev: Other Versions, Up: Instal B.6 Summary =========== - * The `gawk' distribution is available from GNU project's main + * The `gawk' distribution is available from the GNU Project's main distribution site, `ftp.gnu.org'. The canonical build recipe is: wget http://ftp.gnu.org/gnu/gawk/gawk-4.1.2.tar.gz @@ -28611,17 +28621,17 @@ B.6 Summary ./configure && make && make check * `gawk' may be built on non-POSIX systems as well. The currently - supported systems are MS-Windows using DJGPP, MSYS, MinGW and + supported systems are MS-Windows using DJGPP, MSYS, MinGW, and Cygwin, OS/2 using EMX, and both Vax/VMS and OpenVMS. Instructions for each system are included in this major node. * Bug reports should be sent via email to <bug-gawk@gnu.org>. Bug - reports should be in English, and should include the version of + reports should be in English and should include the version of `gawk', how it was compiled, and a short program and data file - which demonstrate the problem. + that demonstrate the problem. * There are a number of other freely available `awk' - implementations. Many are POSIX compliant; others are less so. + implementations. Many are POSIX-compliant; others are less so. @@ -31673,7 +31683,7 @@ Index * --disable-lint configuration option: Additional Configuration Options. (line 15) * --disable-nls configuration option: Additional Configuration Options. - (line 30) + (line 32) * --dump-variables option: Options. (line 93) * --dump-variables option, using for library functions: Library Names. (line 45) @@ -31711,7 +31721,7 @@ Index * --use-lc-numeric option: Options. (line 220) * --version option: Options. (line 300) * --with-whiny-user-strftime configuration option: Additional Configuration Options. - (line 35) + (line 37) * -b option: Options. (line 68) * -C option: Options. (line 88) * -c option: Options. (line 81) @@ -31747,7 +31757,7 @@ Index * -W option: Options. (line 46) * . (period), regexp operator: Regexp Operators. (line 44) * .gmo files: Explaining gettext. (line 42) -* .gmo files, specifying directory of <1>: Programmer i18n. (line 47) +* .gmo files, specifying directory of <1>: Programmer i18n. (line 48) * .gmo files, specifying directory of: Explaining gettext. (line 54) * .mo files, converting from .po: I18N Example. (line 64) * .po files <1>: Translator i18n. (line 6) @@ -32129,7 +32139,7 @@ Index * BEGIN pattern, and profiling: Profiling. (line 62) * BEGIN pattern, assert() user-defined function and: Assert Function. (line 83) -* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 69) +* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 70) * BEGIN pattern, exit statement and: Exit Statement. (line 12) * BEGIN pattern, getline and: Getline Notes. (line 19) * BEGIN pattern, headings, adding: Print Examples. (line 43) @@ -32146,14 +32156,14 @@ Index * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. (line 60) * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. - (line 69) + (line 70) * beginfile() user-defined function: Filetrans Function. (line 62) * Bentley, Jon: Glossary. (line 207) * Benzinger, Michael: Contributors. (line 97) * Berry, Karl <1>: Ranges and Locales. (line 74) * Berry, Karl: Acknowledgments. (line 33) * binary input/output: User-modified. (line 15) -* bindtextdomain <1>: Programmer i18n. (line 47) +* bindtextdomain <1>: Programmer i18n. (line 48) * bindtextdomain: I18N Functions. (line 12) * bindtextdomain() function (C library): Explaining gettext. (line 50) * bindtextdomain() function (gawk), portability and: I18N Portability. @@ -32172,7 +32182,7 @@ Index * body, in actions: Statements. (line 10) * body, in loops: While Statement. (line 14) * Boolean expressions: Boolean Ops. (line 6) -* Boolean expressions, as patterns: Expression Patterns. (line 38) +* Boolean expressions, as patterns: Expression Patterns. (line 39) * Boolean operators, See Boolean expressions: Boolean Ops. (line 6) * Bourne shell, quoting rules for: Quoting. (line 18) * braces ({}): Profiling. (line 142) @@ -32232,7 +32242,7 @@ Index * Brown, Martin: Contributors. (line 82) * BSD-based operating systems: Glossary. (line 753) * bt debugger command (alias for backtrace): Execution Stack. (line 13) -* Buening, Andreas <1>: Bugs. (line 70) +* 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 52) @@ -32245,7 +32255,7 @@ Index * bug-gawk@gnu.org bug reporting address: Bugs. (line 30) * built-in functions: Functions. (line 6) * built-in functions, evaluation order: Calling Built-in. (line 30) -* Busybox Awk: Other Versions. (line 92) +* BusyBox Awk: Other Versions. (line 92) * c.e., See common extensions: Conventions. (line 51) * call by reference: Pass By Value/Reference. (line 44) @@ -32377,9 +32387,9 @@ Index * configuration option, --disable-lint: Additional Configuration Options. (line 15) * configuration option, --disable-nls: Additional Configuration Options. - (line 30) + (line 32) * configuration option, --with-whiny-user-strftime: Additional Configuration Options. - (line 35) + (line 37) * configuration options, gawk: Additional Configuration Options. (line 6) * constant regexps: Regexp Usage. (line 57) @@ -32487,11 +32497,11 @@ Index * Davies, Stephen <1>: Contributors. (line 74) * Davies, Stephen: Acknowledgments. (line 60) * Day, Robert P.J.: Acknowledgments. (line 78) -* dcgettext <1>: Programmer i18n. (line 19) +* dcgettext <1>: Programmer i18n. (line 20) * dcgettext: I18N Functions. (line 22) * dcgettext() function (gawk), portability and: I18N Portability. (line 33) -* dcngettext <1>: Programmer i18n. (line 36) +* dcngettext <1>: Programmer i18n. (line 37) * dcngettext: I18N Functions. (line 28) * dcngettext() function (gawk), portability and: I18N Portability. (line 33) @@ -32578,7 +32588,7 @@ Index * debugger commands, t (tbreak): Breakpoint Control. (line 90) * debugger commands, tbreak: Breakpoint Control. (line 90) * debugger commands, trace: Miscellaneous Debugger Commands. - (line 108) + (line 107) * debugger commands, u (until): Debugger Execution Control. (line 83) * debugger commands, undisplay: Viewing And Changing Data. @@ -32594,18 +32604,18 @@ Index (line 67) * debugger commands, where (backtrace): Execution Stack. (line 13) * debugger default list amount: Debugger Info. (line 69) -* debugger history file: Debugger Info. (line 80) +* debugger history file: Debugger Info. (line 81) * debugger history size: Debugger Info. (line 65) * debugger options: Debugger Info. (line 57) -* debugger prompt: Debugger Info. (line 77) +* debugger prompt: Debugger Info. (line 78) * debugger, how to start: Debugger Invocation. (line 6) -* debugger, read commands from a file: Debugger Info. (line 96) +* debugger, read commands from a file: Debugger Info. (line 97) * debugging awk programs: Debugger. (line 6) * debugging gawk, bug reports: Bugs. (line 9) * decimal point character, locale specific: Options. (line 270) * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) -* Deifik, Scott <1>: Bugs. (line 70) +* Deifik, Scott <1>: Bugs. (line 71) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) * delete ARRAY: Delete. (line 39) @@ -32757,7 +32767,7 @@ Index * END pattern, and profiling: Profiling. (line 62) * END pattern, assert() user-defined function and: Assert Function. (line 75) -* END pattern, Boolean patterns and: Expression Patterns. (line 69) +* END pattern, Boolean patterns and: Expression Patterns. (line 70) * END pattern, exit statement and: Exit Statement. (line 12) * END pattern, next/nextfile statements and <1>: Next Statement. (line 44) @@ -32766,7 +32776,7 @@ Index * END pattern, operators and: Using BEGIN/END. (line 17) * END pattern, print statement and: I/O And BEGIN/END. (line 16) * ENDFILE pattern: BEGINFILE/ENDFILE. (line 6) -* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 69) +* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 70) * endfile() user-defined function: Filetrans Function. (line 62) * endgrent() function (C library): Group Functions. (line 212) * endgrent() user-defined function: Group Functions. (line 215) @@ -32825,7 +32835,7 @@ Index (line 99) * exp: Numeric Functions. (line 33) * expand utility: Very Simple. (line 73) -* Expat XML parser library: gawkextlib. (line 33) +* Expat XML parser library: gawkextlib. (line 35) * exponent: Numeric Functions. (line 33) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) @@ -32930,7 +32940,7 @@ Index * FILENAME variable, getline, setting with: Getline Notes. (line 19) * filenames, assignments as: Ignoring Assigns. (line 6) * files, .gmo: Explaining gettext. (line 42) -* files, .gmo, specifying directory of <1>: Programmer i18n. (line 47) +* files, .gmo, specifying directory of <1>: Programmer i18n. (line 48) * files, .gmo, specifying directory of: Explaining gettext. (line 54) * files, .mo, converting from .po: I18N Example. (line 64) * files, .po <1>: Translator i18n. (line 6) @@ -32957,7 +32967,7 @@ Index * files, message object, converting from portable object files: I18N Example. (line 64) * files, message object, specifying directory of <1>: Programmer i18n. - (line 47) + (line 48) * files, message object, specifying directory of: Explaining gettext. (line 54) * files, multiple passes over: Other Arguments. (line 56) @@ -33245,7 +33255,7 @@ Index * git utility <2>: Accessing The Source. (line 10) * git utility <3>: Other Versions. (line 29) -* git utility: gawkextlib. (line 27) +* git utility: gawkextlib. (line 29) * Git, use of for gawk source code: Derived Files. (line 6) * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 51) @@ -33369,7 +33379,7 @@ Index * insomnia, cure for: Alarm Program. (line 6) * installation, VMS: VMS Installation. (line 6) * installing gawk: Installation. (line 6) -* instruction tracing, in debugger: Debugger Info. (line 89) +* instruction tracing, in debugger: Debugger Info. (line 90) * int: Numeric Functions. (line 38) * INT signal (MS-Windows): Profiling. (line 213) * integer array indices: Numeric Array Subscripts. @@ -33390,7 +33400,7 @@ Index * internationalization, localization, locale categories: Explaining gettext. (line 81) * internationalization, localization, marked strings: Programmer i18n. - (line 14) + (line 13) * internationalization, localization, portability and: I18N Portability. (line 6) * internationalizing a program: Explaining gettext. (line 6) @@ -33543,7 +33553,7 @@ Index * mail-list file: Sample Data Files. (line 6) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 52) -* Malmberg, John <1>: Bugs. (line 70) +* Malmberg, John <1>: Bugs. (line 71) * Malmberg, John: Acknowledgments. (line 60) * Malmberg, John E.: Contributors. (line 137) * mark parity: Ordinal Functions. (line 45) @@ -33571,7 +33581,7 @@ Index * message object files, converting from portable object files: I18N Example. (line 64) * message object files, specifying directory of <1>: Programmer i18n. - (line 47) + (line 48) * message object files, specifying directory of: Explaining gettext. (line 54) * messages from extensions: Printing Messages. (line 6) @@ -33782,7 +33792,7 @@ Index (line 6) * pipe, input: Getline/Pipe. (line 9) * pipe, output: Redirection. (line 57) -* Pitts, Dave <1>: Bugs. (line 70) +* Pitts, Dave <1>: Bugs. (line 71) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) * plug-in: Extension Intro. (line 6) @@ -33960,7 +33970,7 @@ Index * pwcat program: Passwd Functions. (line 23) * q debugger command (alias for quit): Miscellaneous Debugger Commands. (line 99) -* QSE Awk: Other Versions. (line 135) +* QSE awk: Other Versions. (line 135) * Quanstrom, Erik: Alarm Program. (line 8) * question mark (?), ?: operator: Precedence. (line 92) * question mark (?), regexp operator <1>: GNU Regexp Operators. @@ -34015,7 +34025,7 @@ Index * records, terminating: awk split records. (line 125) * records, treating files as: gawk split records. (line 93) * recursive functions: Definition Syntax. (line 88) -* redirect gawk output, in debugger: Debugger Info. (line 72) +* redirect gawk output, in debugger: Debugger Info. (line 73) * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) * reference counting, sorting arrays: Array Sorting Functions. @@ -34095,7 +34105,7 @@ Index * RLENGTH variable: Auto-set. (line 266) * RLENGTH variable, match() function and: String Functions. (line 228) * Robbins, Arnold <1>: Future Extensions. (line 6) -* Robbins, Arnold <2>: Bugs. (line 70) +* Robbins, Arnold <2>: Bugs. (line 71) * Robbins, Arnold <3>: Contributors. (line 144) * Robbins, Arnold <4>: General Data Types. (line 6) * Robbins, Arnold <5>: Alarm Program. (line 6) @@ -34134,7 +34144,7 @@ Index * sample debugging session: Sample Debugging Session. (line 6) * sandbox mode: Options. (line 286) -* save debugger options: Debugger Info. (line 84) +* save debugger options: Debugger Info. (line 85) * scalar or array: Type Functions. (line 11) * scalar values: Basic Data Typing. (line 13) * scanning arrays: Scanning an Array. (line 6) @@ -34286,7 +34296,7 @@ Index (line 94) * source code, awka: Other Versions. (line 68) * source code, Brian Kernighan's awk: Other Versions. (line 13) -* source code, Busybox Awk: Other Versions. (line 92) +* source code, BusyBox Awk: Other Versions. (line 92) * source code, gawk: Gawk Distribution. (line 6) * source code, Illumos awk: Other Versions. (line 109) * source code, jawk: Other Versions. (line 117) @@ -34295,7 +34305,7 @@ Index * source code, mixing: Options. (line 117) * source code, pawk: Other Versions. (line 82) * source code, pawk (Python version): Other Versions. (line 129) -* source code, QSE Awk: Other Versions. (line 135) +* source code, QSE awk: Other Versions. (line 135) * source code, QuikTrim Awk: Other Versions. (line 139) * source code, Solaris awk: Other Versions. (line 100) * source files, search path for: Programs Exercises. (line 70) @@ -34356,7 +34366,7 @@ Index * strings, converting, numbers to: User-modified. (line 30) * strings, empty, See null strings: awk split records. (line 115) * strings, extracting: String Extraction. (line 6) -* strings, for localization: Programmer i18n. (line 14) +* strings, for localization: Programmer i18n. (line 13) * strings, length limitations: Scalar Constants. (line 20) * strings, merging arrays into: Join Function. (line 6) * strings, null: Regexp Field Splitting. @@ -34416,7 +34426,7 @@ Index (line 6) * text, printing: Print. (line 22) * text, printing, unduplicated lines of: Uniq Program. (line 6) -* TEXTDOMAIN variable <1>: Programmer i18n. (line 9) +* TEXTDOMAIN variable <1>: Programmer i18n. (line 8) * TEXTDOMAIN variable: User-modified. (line 152) * TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n. (line 60) * TEXTDOMAIN variable, portability and: I18N Portability. (line 20) @@ -34444,7 +34454,7 @@ Index * toupper: String Functions. (line 530) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. - (line 108) + (line 107) * traceback, display in debugger: Execution Stack. (line 13) * translate string: I18N Functions. (line 22) * translate.awk program: Translate Program. (line 55) @@ -34624,7 +34634,7 @@ Index * xor: Bitwise Functions. (line 56) * XOR bitwise operation: Bitwise Functions. (line 6) * Yawitz, Efraim: Contributors. (line 131) -* Zaretskii, Eli <1>: Bugs. (line 70) +* Zaretskii, Eli <1>: Bugs. (line 71) * Zaretskii, Eli <2>: Contributors. (line 55) * Zaretskii, Eli: Acknowledgments. (line 60) * zerofile.awk program: Empty Files. (line 21) @@ -34674,543 +34684,543 @@ Ref: Manual History-Footnote-167073 Ref: Manual History-Footnote-267114 Node: How To Contribute67188 Node: Acknowledgments68317 -Node: Getting Started73134 -Node: Running gawk75573 -Node: One-shot76763 -Node: Read Terminal78027 -Node: Long80058 -Node: Executable Scripts81571 -Ref: Executable Scripts-Footnote-184360 -Node: Comments84463 -Node: Quoting86945 -Node: DOS Quoting92463 -Node: Sample Data Files93138 -Node: Very Simple95733 -Node: Two Rules100632 -Node: More Complex102518 -Node: Statements/Lines105380 -Ref: Statements/Lines-Footnote-1109835 -Node: Other Features110100 -Node: When111036 -Ref: When-Footnote-1112790 -Node: Intro Summary112855 -Node: Invoking Gawk113739 -Node: Command Line115253 -Node: Options116051 -Ref: Options-Footnote-1131846 -Ref: Options-Footnote-2132075 -Node: Other Arguments132100 -Node: Naming Standard Input135048 -Node: Environment Variables136141 -Node: AWKPATH Variable136699 -Ref: AWKPATH Variable-Footnote-1140106 -Ref: AWKPATH Variable-Footnote-2140151 -Node: AWKLIBPATH Variable140411 -Node: Other Environment Variables141667 -Node: Exit Status145185 -Node: Include Files145861 -Node: Loading Shared Libraries149450 -Node: Obsolete150877 -Node: Undocumented151569 -Node: Invoking Summary151836 -Node: Regexp153499 -Node: Regexp Usage154953 -Node: Escape Sequences156990 -Node: Regexp Operators163219 -Ref: Regexp Operators-Footnote-1170629 -Ref: Regexp Operators-Footnote-2170776 -Node: Bracket Expressions170874 -Ref: table-char-classes172889 -Node: Leftmost Longest175831 -Node: Computed Regexps177133 -Node: GNU Regexp Operators180562 -Node: Case-sensitivity184234 -Ref: Case-sensitivity-Footnote-1187119 -Ref: Case-sensitivity-Footnote-2187354 -Node: Regexp Summary187462 -Node: Reading Files188929 -Node: Records191022 -Node: awk split records191755 -Node: gawk split records196684 -Ref: gawk split records-Footnote-1201223 -Node: Fields201260 -Ref: Fields-Footnote-1204038 -Node: Nonconstant Fields204124 -Ref: Nonconstant Fields-Footnote-1206362 -Node: Changing Fields206565 -Node: Field Separators212496 -Node: Default Field Splitting215200 -Node: Regexp Field Splitting216317 -Node: Single Character Fields219667 -Node: Command Line Field Separator220726 -Node: Full Line Fields223943 -Ref: Full Line Fields-Footnote-1225464 -Ref: Full Line Fields-Footnote-2225510 -Node: Field Splitting Summary225611 -Node: Constant Size227685 -Node: Splitting By Content232268 -Ref: Splitting By Content-Footnote-1236233 -Node: Multiple Line236396 -Ref: Multiple Line-Footnote-1242277 -Node: Getline242456 -Node: Plain Getline244663 -Node: Getline/Variable247303 -Node: Getline/File248452 -Node: Getline/Variable/File249837 -Ref: Getline/Variable/File-Footnote-1251440 -Node: Getline/Pipe251527 -Node: Getline/Variable/Pipe254205 -Node: Getline/Coprocess255336 -Node: Getline/Variable/Coprocess256600 -Node: Getline Notes257339 -Node: Getline Summary260133 -Ref: table-getline-variants260545 -Node: Read Timeout261374 -Ref: Read Timeout-Footnote-1265211 -Node: Command-line directories265269 -Node: Input Summary266174 -Node: Input Exercises269559 -Node: Printing270287 -Node: Print272064 -Node: Print Examples273521 -Node: Output Separators276300 -Node: OFMT278318 -Node: Printf279673 -Node: Basic Printf280458 -Node: Control Letters282030 -Node: Format Modifiers286015 -Node: Printf Examples292025 -Node: Redirection294511 -Node: Special FD301349 -Ref: Special FD-Footnote-1304515 -Node: Special Files304589 -Node: Other Inherited Files305206 -Node: Special Network306206 -Node: Special Caveats307068 -Node: Close Files And Pipes308017 -Ref: Close Files And Pipes-Footnote-1315208 -Ref: Close Files And Pipes-Footnote-2315356 -Node: Output Summary315506 -Node: Output Exercises316504 -Node: Expressions317184 -Node: Values318373 -Node: Constants319050 -Node: Scalar Constants319741 -Ref: Scalar Constants-Footnote-1320603 -Node: Nondecimal-numbers320853 -Node: Regexp Constants323863 -Node: Using Constant Regexps324389 -Node: Variables327552 -Node: Using Variables328209 -Node: Assignment Options330120 -Node: Conversion331995 -Node: Strings And Numbers332519 -Ref: Strings And Numbers-Footnote-1335584 -Node: Locale influences conversions335693 -Ref: table-locale-affects338439 -Node: All Operators339031 -Node: Arithmetic Ops339660 -Node: Concatenation342165 -Ref: Concatenation-Footnote-1344984 -Node: Assignment Ops345091 -Ref: table-assign-ops350070 -Node: Increment Ops351380 -Node: Truth Values and Conditions354811 -Node: Truth Values355894 -Node: Typing and Comparison356943 -Node: Variable Typing357759 -Node: Comparison Operators361426 -Ref: table-relational-ops361836 -Node: POSIX String Comparison365331 -Ref: POSIX String Comparison-Footnote-1366403 -Node: Boolean Ops366542 -Ref: Boolean Ops-Footnote-1371020 -Node: Conditional Exp371111 -Node: Function Calls372849 -Node: Precedence376729 -Node: Locales380389 -Node: Expressions Summary382021 -Node: Patterns and Actions384592 -Node: Pattern Overview385712 -Node: Regexp Patterns387391 -Node: Expression Patterns387934 -Node: Ranges391643 -Node: BEGIN/END394750 -Node: Using BEGIN/END395511 -Ref: Using BEGIN/END-Footnote-1398247 -Node: I/O And BEGIN/END398353 -Node: BEGINFILE/ENDFILE400668 -Node: Empty403565 -Node: Using Shell Variables403882 -Node: Action Overview406155 -Node: Statements408481 -Node: If Statement410329 -Node: While Statement411824 -Node: Do Statement413852 -Node: For Statement415000 -Node: Switch Statement418158 -Node: Break Statement420540 -Node: Continue Statement422581 -Node: Next Statement424408 -Node: Nextfile Statement426789 -Node: Exit Statement429417 -Node: Built-in Variables431828 -Node: User-modified432961 -Ref: User-modified-Footnote-1440664 -Node: Auto-set440726 -Ref: Auto-set-Footnote-1454435 -Ref: Auto-set-Footnote-2454640 -Node: ARGC and ARGV454696 -Node: Pattern Action Summary458914 -Node: Arrays461347 -Node: Array Basics462676 -Node: Array Intro463520 -Ref: figure-array-elements465454 -Ref: Array Intro-Footnote-1468074 -Node: Reference to Elements468202 -Node: Assigning Elements470664 -Node: Array Example471155 -Node: Scanning an Array472914 -Node: Controlling Scanning475934 -Ref: Controlling Scanning-Footnote-1481328 -Node: Numeric Array Subscripts481644 -Node: Uninitialized Subscripts483829 -Node: Delete485446 -Ref: Delete-Footnote-1488195 -Node: Multidimensional488252 -Node: Multiscanning491349 -Node: Arrays of Arrays492938 -Node: Arrays Summary497692 -Node: Functions499783 -Node: Built-in500822 -Node: Calling Built-in501900 -Node: Numeric Functions503895 -Ref: Numeric Functions-Footnote-1508713 -Ref: Numeric Functions-Footnote-2509070 -Ref: Numeric Functions-Footnote-3509118 -Node: String Functions509390 -Ref: String Functions-Footnote-1532891 -Ref: String Functions-Footnote-2533020 -Ref: String Functions-Footnote-3533268 -Node: Gory Details533355 -Ref: table-sub-escapes535136 -Ref: table-sub-proposed536651 -Ref: table-posix-sub538013 -Ref: table-gensub-escapes539550 -Ref: Gory Details-Footnote-1540383 -Node: I/O Functions540534 -Ref: I/O Functions-Footnote-1547770 -Node: Time Functions547917 -Ref: Time Functions-Footnote-1558426 -Ref: Time Functions-Footnote-2558494 -Ref: Time Functions-Footnote-3558652 -Ref: Time Functions-Footnote-4558763 -Ref: Time Functions-Footnote-5558875 -Ref: Time Functions-Footnote-6559102 -Node: Bitwise Functions559368 -Ref: table-bitwise-ops559930 -Ref: Bitwise Functions-Footnote-1564258 -Node: Type Functions564430 -Node: I18N Functions565582 -Node: User-defined567229 -Node: Definition Syntax568034 -Ref: Definition Syntax-Footnote-1573693 -Node: Function Example573764 -Ref: Function Example-Footnote-1576685 -Node: Function Caveats576707 -Node: Calling A Function577225 -Node: Variable Scope578183 -Node: Pass By Value/Reference581176 -Node: Return Statement584673 -Node: Dynamic Typing587652 -Node: Indirect Calls588581 -Ref: Indirect Calls-Footnote-1599887 -Node: Functions Summary600015 -Node: Library Functions602717 -Ref: Library Functions-Footnote-1606325 -Ref: Library Functions-Footnote-2606468 -Node: Library Names606639 -Ref: Library Names-Footnote-1610097 -Ref: Library Names-Footnote-2610320 -Node: General Functions610406 -Node: Strtonum Function611509 -Node: Assert Function614531 -Node: Round Function617855 -Node: Cliff Random Function619396 -Node: Ordinal Functions620412 -Ref: Ordinal Functions-Footnote-1623475 -Ref: Ordinal Functions-Footnote-2623727 -Node: Join Function623938 -Ref: Join Function-Footnote-1625708 -Node: Getlocaltime Function625908 -Node: Readfile Function629652 -Node: Shell Quoting631624 -Node: Data File Management633025 -Node: Filetrans Function633657 -Node: Rewind Function637753 -Node: File Checking639139 -Ref: File Checking-Footnote-1640472 -Node: Empty Files640673 -Node: Ignoring Assigns642652 -Node: Getopt Function644202 -Ref: Getopt Function-Footnote-1655666 -Node: Passwd Functions655866 -Ref: Passwd Functions-Footnote-1664706 -Node: Group Functions664794 -Ref: Group Functions-Footnote-1672691 -Node: Walking Arrays672896 -Node: Library Functions Summary674496 -Node: Library Exercises675900 -Node: Sample Programs677180 -Node: Running Examples677950 -Node: Clones678678 -Node: Cut Program679902 -Node: Egrep Program689622 -Ref: Egrep Program-Footnote-1697125 -Node: Id Program697235 -Node: Split Program700911 -Ref: Split Program-Footnote-1704365 -Node: Tee Program704493 -Node: Uniq Program707282 -Node: Wc Program714701 -Ref: Wc Program-Footnote-1718951 -Node: Miscellaneous Programs719045 -Node: Dupword Program720258 -Node: Alarm Program722289 -Node: Translate Program727094 -Ref: Translate Program-Footnote-1731657 -Node: Labels Program731927 -Ref: Labels Program-Footnote-1735278 -Node: Word Sorting735362 -Node: History Sorting739432 -Node: Extract Program741267 -Node: Simple Sed748791 -Node: Igawk Program751861 -Ref: Igawk Program-Footnote-1766187 -Ref: Igawk Program-Footnote-2766388 -Ref: Igawk Program-Footnote-3766510 -Node: Anagram Program766625 -Node: Signature Program769686 -Node: Programs Summary770933 -Node: Programs Exercises772154 -Ref: Programs Exercises-Footnote-1776285 -Node: Advanced Features776376 -Node: Nondecimal Data778358 -Node: Array Sorting779948 -Node: Controlling Array Traversal780648 -Ref: Controlling Array Traversal-Footnote-1789014 -Node: Array Sorting Functions789132 -Ref: Array Sorting Functions-Footnote-1793018 -Node: Two-way I/O793214 -Ref: Two-way I/O-Footnote-1798159 -Ref: Two-way I/O-Footnote-2798345 -Node: TCP/IP Networking798427 -Node: Profiling801299 -Node: Advanced Features Summary809570 -Node: Internationalization811503 -Node: I18N and L10N812983 -Node: Explaining gettext813669 -Ref: Explaining gettext-Footnote-1818694 -Ref: Explaining gettext-Footnote-2818878 -Node: Programmer i18n819043 -Ref: Programmer i18n-Footnote-1823909 -Node: Translator i18n823958 -Node: String Extraction824752 -Ref: String Extraction-Footnote-1825883 -Node: Printf Ordering825969 -Ref: Printf Ordering-Footnote-1828755 -Node: I18N Portability828819 -Ref: I18N Portability-Footnote-1831274 -Node: I18N Example831337 -Ref: I18N Example-Footnote-1834140 -Node: Gawk I18N834212 -Node: I18N Summary834850 -Node: Debugger836189 -Node: Debugging837211 -Node: Debugging Concepts837652 -Node: Debugging Terms839505 -Node: Awk Debugging842077 -Node: Sample Debugging Session842971 -Node: Debugger Invocation843491 -Node: Finding The Bug844875 -Node: List of Debugger Commands851350 -Node: Breakpoint Control852683 -Node: Debugger Execution Control856379 -Node: Viewing And Changing Data859743 -Node: Execution Stack863121 -Node: Debugger Info864758 -Node: Miscellaneous Debugger Commands868775 -Node: Readline Support873804 -Node: Limitations874696 -Node: Debugging Summary876810 -Node: Arbitrary Precision Arithmetic877978 -Node: Computer Arithmetic879394 -Ref: table-numeric-ranges882992 -Ref: Computer Arithmetic-Footnote-1883851 -Node: Math Definitions883908 -Ref: table-ieee-formats887196 -Ref: Math Definitions-Footnote-1887800 -Node: MPFR features887905 -Node: FP Math Caution889576 -Ref: FP Math Caution-Footnote-1890626 -Node: Inexactness of computations890995 -Node: Inexact representation891954 -Node: Comparing FP Values893311 -Node: Errors accumulate894393 -Node: Getting Accuracy895826 -Node: Try To Round898488 -Node: Setting precision899387 -Ref: table-predefined-precision-strings900071 -Node: Setting the rounding mode901860 -Ref: table-gawk-rounding-modes902224 -Ref: Setting the rounding mode-Footnote-1905679 -Node: Arbitrary Precision Integers905858 -Ref: Arbitrary Precision Integers-Footnote-1910758 -Node: POSIX Floating Point Problems910907 -Ref: POSIX Floating Point Problems-Footnote-1914780 -Node: Floating point summary914818 -Node: Dynamic Extensions917012 -Node: Extension Intro918564 -Node: Plugin License919830 -Node: Extension Mechanism Outline920627 -Ref: figure-load-extension921055 -Ref: figure-register-new-function922535 -Ref: figure-call-new-function923539 -Node: Extension API Description925525 -Node: Extension API Functions Introduction926975 -Node: General Data Types931799 -Ref: General Data Types-Footnote-1937538 -Node: Memory Allocation Functions937837 -Ref: Memory Allocation Functions-Footnote-1940676 -Node: Constructor Functions940772 -Node: Registration Functions942506 -Node: Extension Functions943191 -Node: Exit Callback Functions945488 -Node: Extension Version String946736 -Node: Input Parsers947401 -Node: Output Wrappers957280 -Node: Two-way processors961795 -Node: Printing Messages963999 -Ref: Printing Messages-Footnote-1965075 -Node: Updating `ERRNO'965227 -Node: Requesting Values965967 -Ref: table-value-types-returned966695 -Node: Accessing Parameters967652 -Node: Symbol Table Access968883 -Node: Symbol table by name969397 -Node: Symbol table by cookie971378 -Ref: Symbol table by cookie-Footnote-1975522 -Node: Cached values975585 -Ref: Cached values-Footnote-1979084 -Node: Array Manipulation979175 -Ref: Array Manipulation-Footnote-1980273 -Node: Array Data Types980310 -Ref: Array Data Types-Footnote-1982965 -Node: Array Functions983057 -Node: Flattening Arrays986911 -Node: Creating Arrays993803 -Node: Extension API Variables998574 -Node: Extension Versioning999210 -Node: Extension API Informational Variables1001111 -Node: Extension API Boilerplate1002176 -Node: Finding Extensions1005985 -Node: Extension Example1006545 -Node: Internal File Description1007317 -Node: Internal File Ops1011384 -Ref: Internal File Ops-Footnote-11023054 -Node: Using Internal File Ops1023194 -Ref: Using Internal File Ops-Footnote-11025577 -Node: Extension Samples1025850 -Node: Extension Sample File Functions1027376 -Node: Extension Sample Fnmatch1035014 -Node: Extension Sample Fork1036505 -Node: Extension Sample Inplace1037720 -Node: Extension Sample Ord1039395 -Node: Extension Sample Readdir1040231 -Ref: table-readdir-file-types1041107 -Node: Extension Sample Revout1041918 -Node: Extension Sample Rev2way1042508 -Node: Extension Sample Read write array1043248 -Node: Extension Sample Readfile1045188 -Node: Extension Sample Time1046283 -Node: Extension Sample API Tests1047632 -Node: gawkextlib1048123 -Node: Extension summary1050781 -Node: Extension Exercises1054470 -Node: Language History1055192 -Node: V7/SVR3.11056848 -Node: SVR41059029 -Node: POSIX1060474 -Node: BTL1061863 -Node: POSIX/GNU1062597 -Node: Feature History1068386 -Node: Common Extensions1082112 -Node: Ranges and Locales1083436 -Ref: Ranges and Locales-Footnote-11088054 -Ref: Ranges and Locales-Footnote-21088081 -Ref: Ranges and Locales-Footnote-31088315 -Node: Contributors1088536 -Node: History summary1094077 -Node: Installation1095447 -Node: Gawk Distribution1096393 -Node: Getting1096877 -Node: Extracting1097700 -Node: Distribution contents1099335 -Node: Unix Installation1105400 -Node: Quick Installation1106083 -Node: Shell Startup Files1108494 -Node: Additional Configuration Options1109573 -Node: Configuration Philosophy1111312 -Node: Non-Unix Installation1113681 -Node: PC Installation1114139 -Node: PC Binary Installation1115458 -Node: PC Compiling1117306 -Ref: PC Compiling-Footnote-11120327 -Node: PC Testing1120436 -Node: PC Using1121612 -Node: Cygwin1125727 -Node: MSYS1126550 -Node: VMS Installation1127050 -Node: VMS Compilation1127842 -Ref: VMS Compilation-Footnote-11129064 -Node: VMS Dynamic Extensions1129122 -Node: VMS Installation Details1130806 -Node: VMS Running1133058 -Node: VMS GNV1135894 -Node: VMS Old Gawk1136628 -Node: Bugs1137098 -Node: Other Versions1140981 -Node: Installation summary1147405 -Node: Notes1148461 -Node: Compatibility Mode1149326 -Node: Additions1150108 -Node: Accessing The Source1151033 -Node: Adding Code1152468 -Node: New Ports1158625 -Node: Derived Files1163107 -Ref: Derived Files-Footnote-11168582 -Ref: Derived Files-Footnote-21168616 -Ref: Derived Files-Footnote-31169212 -Node: Future Extensions1169326 -Node: Implementation Limitations1169932 -Node: Extension Design1171180 -Node: Old Extension Problems1172334 -Ref: Old Extension Problems-Footnote-11173851 -Node: Extension New Mechanism Goals1173908 -Ref: Extension New Mechanism Goals-Footnote-11177268 -Node: Extension Other Design Decisions1177457 -Node: Extension Future Growth1179565 -Node: Old Extension Mechanism1180401 -Node: Notes summary1182163 -Node: Basic Concepts1183349 -Node: Basic High Level1184030 -Ref: figure-general-flow1184302 -Ref: figure-process-flow1184901 -Ref: Basic High Level-Footnote-11188130 -Node: Basic Data Typing1188315 -Node: Glossary1191643 -Node: Copying1223572 -Node: GNU Free Documentation License1261128 -Node: Index1286264 +Node: Getting Started73183 +Node: Running gawk75622 +Node: One-shot76812 +Node: Read Terminal78076 +Node: Long80107 +Node: Executable Scripts81620 +Ref: Executable Scripts-Footnote-184409 +Node: Comments84512 +Node: Quoting86994 +Node: DOS Quoting92512 +Node: Sample Data Files93187 +Node: Very Simple95782 +Node: Two Rules100681 +Node: More Complex102567 +Node: Statements/Lines105429 +Ref: Statements/Lines-Footnote-1109884 +Node: Other Features110149 +Node: When111085 +Ref: When-Footnote-1112839 +Node: Intro Summary112904 +Node: Invoking Gawk113788 +Node: Command Line115302 +Node: Options116100 +Ref: Options-Footnote-1131895 +Ref: Options-Footnote-2132124 +Node: Other Arguments132149 +Node: Naming Standard Input135097 +Node: Environment Variables136190 +Node: AWKPATH Variable136748 +Ref: AWKPATH Variable-Footnote-1140155 +Ref: AWKPATH Variable-Footnote-2140200 +Node: AWKLIBPATH Variable140460 +Node: Other Environment Variables141716 +Node: Exit Status145234 +Node: Include Files145910 +Node: Loading Shared Libraries149499 +Node: Obsolete150926 +Node: Undocumented151618 +Node: Invoking Summary151885 +Node: Regexp153548 +Node: Regexp Usage155002 +Node: Escape Sequences157039 +Node: Regexp Operators163268 +Ref: Regexp Operators-Footnote-1170678 +Ref: Regexp Operators-Footnote-2170825 +Node: Bracket Expressions170923 +Ref: table-char-classes172938 +Node: Leftmost Longest175880 +Node: Computed Regexps177182 +Node: GNU Regexp Operators180611 +Node: Case-sensitivity184283 +Ref: Case-sensitivity-Footnote-1187168 +Ref: Case-sensitivity-Footnote-2187403 +Node: Regexp Summary187511 +Node: Reading Files188978 +Node: Records191071 +Node: awk split records191804 +Node: gawk split records196733 +Ref: gawk split records-Footnote-1201272 +Node: Fields201309 +Ref: Fields-Footnote-1204087 +Node: Nonconstant Fields204173 +Ref: Nonconstant Fields-Footnote-1206411 +Node: Changing Fields206614 +Node: Field Separators212545 +Node: Default Field Splitting215249 +Node: Regexp Field Splitting216366 +Node: Single Character Fields219716 +Node: Command Line Field Separator220775 +Node: Full Line Fields223992 +Ref: Full Line Fields-Footnote-1225513 +Ref: Full Line Fields-Footnote-2225559 +Node: Field Splitting Summary225660 +Node: Constant Size227734 +Node: Splitting By Content232317 +Ref: Splitting By Content-Footnote-1236282 +Node: Multiple Line236445 +Ref: Multiple Line-Footnote-1242326 +Node: Getline242505 +Node: Plain Getline244712 +Node: Getline/Variable247352 +Node: Getline/File248501 +Node: Getline/Variable/File249886 +Ref: Getline/Variable/File-Footnote-1251489 +Node: Getline/Pipe251576 +Node: Getline/Variable/Pipe254254 +Node: Getline/Coprocess255385 +Node: Getline/Variable/Coprocess256649 +Node: Getline Notes257388 +Node: Getline Summary260182 +Ref: table-getline-variants260594 +Node: Read Timeout261423 +Ref: Read Timeout-Footnote-1265260 +Node: Command-line directories265318 +Node: Input Summary266223 +Node: Input Exercises269608 +Node: Printing270336 +Node: Print272113 +Node: Print Examples273570 +Node: Output Separators276349 +Node: OFMT278367 +Node: Printf279722 +Node: Basic Printf280507 +Node: Control Letters282079 +Node: Format Modifiers286064 +Node: Printf Examples292074 +Node: Redirection294560 +Node: Special FD301398 +Ref: Special FD-Footnote-1304564 +Node: Special Files304638 +Node: Other Inherited Files305255 +Node: Special Network306255 +Node: Special Caveats307117 +Node: Close Files And Pipes308066 +Ref: Close Files And Pipes-Footnote-1315257 +Ref: Close Files And Pipes-Footnote-2315405 +Node: Output Summary315555 +Node: Output Exercises316553 +Node: Expressions317233 +Node: Values318422 +Node: Constants319099 +Node: Scalar Constants319790 +Ref: Scalar Constants-Footnote-1320652 +Node: Nondecimal-numbers320902 +Node: Regexp Constants323912 +Node: Using Constant Regexps324438 +Node: Variables327601 +Node: Using Variables328258 +Node: Assignment Options330169 +Node: Conversion332044 +Node: Strings And Numbers332568 +Ref: Strings And Numbers-Footnote-1335633 +Node: Locale influences conversions335742 +Ref: table-locale-affects338488 +Node: All Operators339080 +Node: Arithmetic Ops339709 +Node: Concatenation342214 +Ref: Concatenation-Footnote-1345033 +Node: Assignment Ops345140 +Ref: table-assign-ops350119 +Node: Increment Ops351429 +Node: Truth Values and Conditions354860 +Node: Truth Values355943 +Node: Typing and Comparison356992 +Node: Variable Typing357808 +Node: Comparison Operators361475 +Ref: table-relational-ops361885 +Node: POSIX String Comparison365380 +Ref: POSIX String Comparison-Footnote-1366452 +Node: Boolean Ops366591 +Ref: Boolean Ops-Footnote-1371069 +Node: Conditional Exp371160 +Node: Function Calls372898 +Node: Precedence376778 +Node: Locales380438 +Node: Expressions Summary382070 +Node: Patterns and Actions384641 +Node: Pattern Overview385761 +Node: Regexp Patterns387440 +Node: Expression Patterns387983 +Node: Ranges391763 +Node: BEGIN/END394870 +Node: Using BEGIN/END395631 +Ref: Using BEGIN/END-Footnote-1398367 +Node: I/O And BEGIN/END398473 +Node: BEGINFILE/ENDFILE400788 +Node: Empty403685 +Node: Using Shell Variables404002 +Node: Action Overview406275 +Node: Statements408601 +Node: If Statement410449 +Node: While Statement411944 +Node: Do Statement413972 +Node: For Statement415120 +Node: Switch Statement418278 +Node: Break Statement420660 +Node: Continue Statement422701 +Node: Next Statement424528 +Node: Nextfile Statement426909 +Node: Exit Statement429537 +Node: Built-in Variables431948 +Node: User-modified433081 +Ref: User-modified-Footnote-1440784 +Node: Auto-set440846 +Ref: Auto-set-Footnote-1454555 +Ref: Auto-set-Footnote-2454760 +Node: ARGC and ARGV454816 +Node: Pattern Action Summary459034 +Node: Arrays461467 +Node: Array Basics462796 +Node: Array Intro463640 +Ref: figure-array-elements465574 +Ref: Array Intro-Footnote-1468194 +Node: Reference to Elements468322 +Node: Assigning Elements470784 +Node: Array Example471275 +Node: Scanning an Array473034 +Node: Controlling Scanning476054 +Ref: Controlling Scanning-Footnote-1481448 +Node: Numeric Array Subscripts481764 +Node: Uninitialized Subscripts483949 +Node: Delete485566 +Ref: Delete-Footnote-1488315 +Node: Multidimensional488372 +Node: Multiscanning491469 +Node: Arrays of Arrays493058 +Node: Arrays Summary497812 +Node: Functions499903 +Node: Built-in500942 +Node: Calling Built-in502020 +Node: Numeric Functions504015 +Ref: Numeric Functions-Footnote-1508833 +Ref: Numeric Functions-Footnote-2509190 +Ref: Numeric Functions-Footnote-3509238 +Node: String Functions509510 +Ref: String Functions-Footnote-1533011 +Ref: String Functions-Footnote-2533140 +Ref: String Functions-Footnote-3533388 +Node: Gory Details533475 +Ref: table-sub-escapes535256 +Ref: table-sub-proposed536771 +Ref: table-posix-sub538133 +Ref: table-gensub-escapes539670 +Ref: Gory Details-Footnote-1540503 +Node: I/O Functions540654 +Ref: I/O Functions-Footnote-1547890 +Node: Time Functions548037 +Ref: Time Functions-Footnote-1558546 +Ref: Time Functions-Footnote-2558614 +Ref: Time Functions-Footnote-3558772 +Ref: Time Functions-Footnote-4558883 +Ref: Time Functions-Footnote-5558995 +Ref: Time Functions-Footnote-6559222 +Node: Bitwise Functions559488 +Ref: table-bitwise-ops560050 +Ref: Bitwise Functions-Footnote-1564378 +Node: Type Functions564550 +Node: I18N Functions565702 +Node: User-defined567349 +Node: Definition Syntax568154 +Ref: Definition Syntax-Footnote-1573813 +Node: Function Example573884 +Ref: Function Example-Footnote-1576805 +Node: Function Caveats576827 +Node: Calling A Function577345 +Node: Variable Scope578303 +Node: Pass By Value/Reference581296 +Node: Return Statement584793 +Node: Dynamic Typing587772 +Node: Indirect Calls588701 +Ref: Indirect Calls-Footnote-1600007 +Node: Functions Summary600135 +Node: Library Functions602837 +Ref: Library Functions-Footnote-1606445 +Ref: Library Functions-Footnote-2606588 +Node: Library Names606759 +Ref: Library Names-Footnote-1610217 +Ref: Library Names-Footnote-2610440 +Node: General Functions610526 +Node: Strtonum Function611629 +Node: Assert Function614651 +Node: Round Function617975 +Node: Cliff Random Function619516 +Node: Ordinal Functions620532 +Ref: Ordinal Functions-Footnote-1623595 +Ref: Ordinal Functions-Footnote-2623847 +Node: Join Function624058 +Ref: Join Function-Footnote-1625828 +Node: Getlocaltime Function626028 +Node: Readfile Function629772 +Node: Shell Quoting631744 +Node: Data File Management633145 +Node: Filetrans Function633777 +Node: Rewind Function637873 +Node: File Checking639259 +Ref: File Checking-Footnote-1640592 +Node: Empty Files640793 +Node: Ignoring Assigns642772 +Node: Getopt Function644322 +Ref: Getopt Function-Footnote-1655786 +Node: Passwd Functions655986 +Ref: Passwd Functions-Footnote-1664826 +Node: Group Functions664914 +Ref: Group Functions-Footnote-1672811 +Node: Walking Arrays673016 +Node: Library Functions Summary674616 +Node: Library Exercises676020 +Node: Sample Programs677300 +Node: Running Examples678070 +Node: Clones678798 +Node: Cut Program680022 +Node: Egrep Program689742 +Ref: Egrep Program-Footnote-1697245 +Node: Id Program697355 +Node: Split Program701031 +Ref: Split Program-Footnote-1704485 +Node: Tee Program704613 +Node: Uniq Program707402 +Node: Wc Program714821 +Ref: Wc Program-Footnote-1719071 +Node: Miscellaneous Programs719165 +Node: Dupword Program720378 +Node: Alarm Program722409 +Node: Translate Program727214 +Ref: Translate Program-Footnote-1731777 +Node: Labels Program732047 +Ref: Labels Program-Footnote-1735398 +Node: Word Sorting735482 +Node: History Sorting739552 +Node: Extract Program741387 +Node: Simple Sed748911 +Node: Igawk Program751981 +Ref: Igawk Program-Footnote-1766307 +Ref: Igawk Program-Footnote-2766508 +Ref: Igawk Program-Footnote-3766630 +Node: Anagram Program766745 +Node: Signature Program769806 +Node: Programs Summary771053 +Node: Programs Exercises772274 +Ref: Programs Exercises-Footnote-1776405 +Node: Advanced Features776496 +Node: Nondecimal Data778478 +Node: Array Sorting780068 +Node: Controlling Array Traversal780768 +Ref: Controlling Array Traversal-Footnote-1789134 +Node: Array Sorting Functions789252 +Ref: Array Sorting Functions-Footnote-1793138 +Node: Two-way I/O793334 +Ref: Two-way I/O-Footnote-1798279 +Ref: Two-way I/O-Footnote-2798465 +Node: TCP/IP Networking798547 +Node: Profiling801419 +Node: Advanced Features Summary809690 +Node: Internationalization811623 +Node: I18N and L10N813103 +Node: Explaining gettext813789 +Ref: Explaining gettext-Footnote-1818814 +Ref: Explaining gettext-Footnote-2818998 +Node: Programmer i18n819163 +Ref: Programmer i18n-Footnote-1824039 +Node: Translator i18n824088 +Node: String Extraction824882 +Ref: String Extraction-Footnote-1826013 +Node: Printf Ordering826099 +Ref: Printf Ordering-Footnote-1828885 +Node: I18N Portability828949 +Ref: I18N Portability-Footnote-1831405 +Node: I18N Example831468 +Ref: I18N Example-Footnote-1834271 +Node: Gawk I18N834343 +Node: I18N Summary834987 +Node: Debugger836327 +Node: Debugging837349 +Node: Debugging Concepts837790 +Node: Debugging Terms839600 +Node: Awk Debugging842172 +Node: Sample Debugging Session843078 +Node: Debugger Invocation843612 +Node: Finding The Bug844997 +Node: List of Debugger Commands851476 +Node: Breakpoint Control852808 +Node: Debugger Execution Control856485 +Node: Viewing And Changing Data859844 +Node: Execution Stack863220 +Node: Debugger Info864855 +Node: Miscellaneous Debugger Commands868900 +Node: Readline Support873901 +Node: Limitations874795 +Node: Debugging Summary876910 +Node: Arbitrary Precision Arithmetic878084 +Node: Computer Arithmetic879500 +Ref: table-numeric-ranges883099 +Ref: Computer Arithmetic-Footnote-1883623 +Node: Math Definitions883680 +Ref: table-ieee-formats886975 +Ref: Math Definitions-Footnote-1887579 +Node: MPFR features887684 +Node: FP Math Caution889355 +Ref: FP Math Caution-Footnote-1890405 +Node: Inexactness of computations890774 +Node: Inexact representation891733 +Node: Comparing FP Values893091 +Node: Errors accumulate894173 +Node: Getting Accuracy895605 +Node: Try To Round898309 +Node: Setting precision899208 +Ref: table-predefined-precision-strings899892 +Node: Setting the rounding mode901721 +Ref: table-gawk-rounding-modes902085 +Ref: Setting the rounding mode-Footnote-1905537 +Node: Arbitrary Precision Integers905716 +Ref: Arbitrary Precision Integers-Footnote-1910614 +Node: POSIX Floating Point Problems910763 +Ref: POSIX Floating Point Problems-Footnote-1914642 +Node: Floating point summary914680 +Node: Dynamic Extensions916876 +Node: Extension Intro918428 +Node: Plugin License919693 +Node: Extension Mechanism Outline920490 +Ref: figure-load-extension920918 +Ref: figure-register-new-function922398 +Ref: figure-call-new-function923402 +Node: Extension API Description925389 +Node: Extension API Functions Introduction926839 +Node: General Data Types931660 +Ref: General Data Types-Footnote-1937560 +Node: Memory Allocation Functions937859 +Ref: Memory Allocation Functions-Footnote-1940698 +Node: Constructor Functions940797 +Node: Registration Functions942532 +Node: Extension Functions943217 +Node: Exit Callback Functions945514 +Node: Extension Version String946762 +Node: Input Parsers947425 +Node: Output Wrappers957300 +Node: Two-way processors961813 +Node: Printing Messages964076 +Ref: Printing Messages-Footnote-1965152 +Node: Updating `ERRNO'965304 +Node: Requesting Values966044 +Ref: table-value-types-returned966771 +Node: Accessing Parameters967728 +Node: Symbol Table Access968962 +Node: Symbol table by name969476 +Node: Symbol table by cookie971496 +Ref: Symbol table by cookie-Footnote-1975641 +Node: Cached values975704 +Ref: Cached values-Footnote-1979200 +Node: Array Manipulation979291 +Ref: Array Manipulation-Footnote-1980389 +Node: Array Data Types980426 +Ref: Array Data Types-Footnote-1983081 +Node: Array Functions983173 +Node: Flattening Arrays987032 +Node: Creating Arrays993934 +Node: Extension API Variables998705 +Node: Extension Versioning999341 +Node: Extension API Informational Variables1001232 +Node: Extension API Boilerplate1002297 +Node: Finding Extensions1006106 +Node: Extension Example1006666 +Node: Internal File Description1007438 +Node: Internal File Ops1011505 +Ref: Internal File Ops-Footnote-11023256 +Node: Using Internal File Ops1023396 +Ref: Using Internal File Ops-Footnote-11025779 +Node: Extension Samples1026052 +Node: Extension Sample File Functions1027580 +Node: Extension Sample Fnmatch1035261 +Node: Extension Sample Fork1036749 +Node: Extension Sample Inplace1037964 +Node: Extension Sample Ord1039640 +Node: Extension Sample Readdir1040476 +Ref: table-readdir-file-types1041353 +Node: Extension Sample Revout1042164 +Node: Extension Sample Rev2way1042753 +Node: Extension Sample Read write array1043493 +Node: Extension Sample Readfile1045433 +Node: Extension Sample Time1046528 +Node: Extension Sample API Tests1047876 +Node: gawkextlib1048367 +Node: Extension summary1051045 +Node: Extension Exercises1054734 +Node: Language History1055456 +Node: V7/SVR3.11057112 +Node: SVR41059265 +Node: POSIX1060699 +Node: BTL1062080 +Node: POSIX/GNU1062811 +Node: Feature History1068556 +Node: Common Extensions1082282 +Node: Ranges and Locales1083654 +Ref: Ranges and Locales-Footnote-11088273 +Ref: Ranges and Locales-Footnote-21088300 +Ref: Ranges and Locales-Footnote-31088535 +Node: Contributors1088756 +Node: History summary1094296 +Node: Installation1095675 +Node: Gawk Distribution1096621 +Node: Getting1097105 +Node: Extracting1097928 +Node: Distribution contents1099565 +Node: Unix Installation1105667 +Node: Quick Installation1106350 +Node: Shell Startup Files1108761 +Node: Additional Configuration Options1109840 +Node: Configuration Philosophy1111644 +Node: Non-Unix Installation1114013 +Node: PC Installation1114471 +Node: PC Binary Installation1115791 +Node: PC Compiling1117639 +Ref: PC Compiling-Footnote-11120660 +Node: PC Testing1120769 +Node: PC Using1121945 +Node: Cygwin1126060 +Node: MSYS1126830 +Node: VMS Installation1127331 +Node: VMS Compilation1128123 +Ref: VMS Compilation-Footnote-11129352 +Node: VMS Dynamic Extensions1129410 +Node: VMS Installation Details1131094 +Node: VMS Running1133345 +Node: VMS GNV1136185 +Node: VMS Old Gawk1136920 +Node: Bugs1137390 +Node: Other Versions1141279 +Node: Installation summary1147713 +Node: Notes1148772 +Node: Compatibility Mode1149637 +Node: Additions1150419 +Node: Accessing The Source1151344 +Node: Adding Code1152779 +Node: New Ports1158936 +Node: Derived Files1163418 +Ref: Derived Files-Footnote-11168893 +Ref: Derived Files-Footnote-21168927 +Ref: Derived Files-Footnote-31169523 +Node: Future Extensions1169637 +Node: Implementation Limitations1170243 +Node: Extension Design1171491 +Node: Old Extension Problems1172645 +Ref: Old Extension Problems-Footnote-11174162 +Node: Extension New Mechanism Goals1174219 +Ref: Extension New Mechanism Goals-Footnote-11177579 +Node: Extension Other Design Decisions1177768 +Node: Extension Future Growth1179876 +Node: Old Extension Mechanism1180712 +Node: Notes summary1182474 +Node: Basic Concepts1183660 +Node: Basic High Level1184341 +Ref: figure-general-flow1184613 +Ref: figure-process-flow1185212 +Ref: Basic High Level-Footnote-11188441 +Node: Basic Data Typing1188626 +Node: Glossary1191954 +Node: Copying1223883 +Node: GNU Free Documentation License1261439 +Node: Index1286575 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index e702f407..7136a7de 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -1301,7 +1301,7 @@ October 2014 <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> <affiliation><jobtitle>Israel</jobtitle></affiliation> </author> - <date>December 2014</date> + <date>February 2015</date> </prefaceinfo> @end docbook @@ -2285,14 +2285,14 @@ which they raised and educated me. Finally, I also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities. -@iftex +@ifnotdocbook @sp 2 @noindent Arnold Robbins @* Nof Ayalon @* Israel @* -December 2014 -@end iftex +February 2015 +@end ifnotdocbook @ifnotinfo @part @value{PART1}The @command{awk} Language @@ -13167,6 +13167,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as +A regexp constant as a pattern is also a special case of an expression pattern. The expression @code{/li/} has the value one if @samp{li} appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @@ -27969,7 +27970,7 @@ a requirement. @cindex localization @dfn{Internationalization} means writing (or modifying) a program once, in such a way that it can use multiple languages without requiring -further source-code changes. +further source code changes. @dfn{Localization} means providing the data necessary for an internationalized program to work in a particular language. Most typically, these terms refer to features such as the language @@ -27984,7 +27985,7 @@ monetary values are printed and read. @cindex @command{gettext} library @command{gawk} uses GNU @command{gettext} to provide its internationalization features. -The facilities in GNU @command{gettext} focus on messages; strings printed +The facilities in GNU @command{gettext} focus on messages: strings printed by a program, either directly or via formatting with @code{printf} or @code{sprintf()}.@footnote{For some operating systems, the @command{gawk} port doesn't support GNU @command{gettext}. @@ -28175,7 +28176,7 @@ All of the above. (Not too useful in the context of @command{gettext}.) @section Internationalizing @command{awk} Programs @cindex @command{awk} programs, internationalizing -@command{gawk} provides the following variables and functions for +@command{gawk} provides the following variables for internationalization: @table @code @@ -28191,7 +28192,12 @@ value is @code{"messages"}. String constants marked with a leading underscore are candidates for translation at runtime. String constants without a leading underscore are not translated. +@end table + +@command{gawk} provides the following functions for +internationalization: +@table @code @cindexgawkfunc{dcgettext} @item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category}]]@code{)} Return the translation of @var{string} in @@ -28248,15 +28254,7 @@ If @var{directory} is the null string (@code{""}), then given @var{domain}. @end table -To use these facilities in your @command{awk} program, follow the steps -outlined in -@ifnotinfo -the previous @value{SECTION}, -@end ifnotinfo -@ifinfo -@ref{Explaining gettext}, -@end ifinfo -like so: +To use these facilities in your @command{awk} program, follow these steps: @enumerate @cindex @code{BEGIN} pattern, @code{TEXTDOMAIN} variable and @@ -28539,7 +28537,7 @@ the null string (@code{""}) as its value, leaving the original string constant a the result. @item -By defining ``dummy'' functions to replace @code{dcgettext()}, @code{dcngettext()} +By defining ``dummy'' functions to replace @code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()}, the @command{awk} program can be made to run, but all the messages are output in the original language. For example: @@ -28723,11 +28721,11 @@ using the GNU @command{gettext} package. (GNU @command{gettext} is described in complete detail in @ifinfo -@inforef{Top, , GNU @command{gettext} utilities, gettext, GNU gettext tools}.) +@inforef{Top, , GNU @command{gettext} utilities, gettext, GNU @command{gettext} utilities}.) @end ifinfo @ifnotinfo @uref{http://www.gnu.org/software/gettext/manual/, -@cite{GNU gettext tools}}.) +@cite{GNU @command{gettext} utilities}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is @uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.4.tar.gz, @@ -28743,7 +28741,7 @@ and fatal errors in the local language. @itemize @value{BULLET} @item Internationalization means writing a program such that it can use multiple -languages without requiring source-code changes. Localization means +languages without requiring source code changes. Localization means providing the data necessary for an internationalized program to work in a particular language. @@ -28760,9 +28758,9 @@ file, and the @file{.po} files are compiled into @file{.gmo} files for use at runtime. @item -You can use position specifications with @code{sprintf()} and +You can use positional specifications with @code{sprintf()} and @code{printf} to rearrange the placement of argument values in formatted -strings and output. This is useful for the translations of format +strings and output. This is useful for the translation of format control strings. @item @@ -28818,8 +28816,7 @@ the discussion of debugging in @command{gawk}. @subsection Debugging in General (If you have used debuggers in other languages, you may want to skip -ahead to the next section on the specific features of the @command{gawk} -debugger.) +ahead to @ref{Awk Debugging}.) Of course, a debugging program cannot remove bugs for you, because it has no way of knowing what you or your users consider a ``bug'' versus a @@ -28910,10 +28907,10 @@ and usually find the errant code quite quickly. @end table @node Awk Debugging -@subsection Awk Debugging +@subsection @command{awk} Debugging Debugging an @command{awk} program has some specific aspects that are -not shared with other programming languages. +not shared with programs written in other languages. First of all, the fact that @command{awk} programs usually take input line by line from a file or files and operate on those lines using specific @@ -28929,7 +28926,7 @@ to look at the individual primitive instructions carried out by the higher-level @command{awk} commands. @node Sample Debugging Session -@section Sample Debugging Session +@section Sample @command{gawk} Debugging Session @cindex sample debugging session In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample @@ -28948,8 +28945,8 @@ as our example. @cindex debugger, how to start Starting the debugger is almost exactly like running @command{gawk} normally, -except you have to pass an additional option @option{--debug}, or the -corresponding short option @option{-D}. The file(s) containing the +except you have to pass an additional option, @option{--debug}, or the +corresponding short option, @option{-D}. The file(s) containing the program and any supporting code are given on the command line as arguments to one or more @option{-f} options. (@command{gawk} is not designed to debug command-line programs, only programs contained in files.) @@ -28962,7 +28959,7 @@ $ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile} @noindent where both @file{getopt.awk} and @file{uniq.awk} are in @env{$AWKPATH}. (Experienced users of GDB or similar debuggers should note that -this syntax is slightly different from what they are used to. +this syntax is slightly different from what you are used to. With the @command{gawk} debugger, you give the arguments for running the program in the command line to the debugger rather than as part of the @code{run} command at the debugger prompt.) @@ -29116,10 +29113,10 @@ gawk> @kbd{n} @end example This tells us that @command{gawk} is now ready to execute line 66, which -decides whether to give the lines the special ``field skipping'' treatment +decides whether to give the lines the special ``field-skipping'' treatment indicated by the @option{-1} command-line option. (Notice that we skipped -from where we were before at line 63 to here, because the condition in line 63 -@samp{if (fcount == 0 && charcount == 0)} was false.) +from where we were before, at line 63, to here, because the condition +in line 63, @samp{if (fcount == 0 && charcount == 0)}, was false.) Continuing to step, we now get to the splitting of the current and last records: @@ -29193,7 +29190,7 @@ gawk> @kbd{n} Well, here we are at our error (sorry to spoil the suspense). What we had in mind was to join the fields starting from the second one to make -the virtual record to compare, and if the first field was numbered zero, +the virtual record to compare, and if the first field were numbered zero, this would work. Let's look at what we've got: @example @@ -29202,7 +29199,7 @@ gawk> @kbd{p cline clast} @print{} clast = "awk is a wonderful program!" @end example -Hey, those look pretty familiar! They're just our original, unaltered, +Hey, those look pretty familiar! They're just our original, unaltered input records. A little thinking (the human brain is still the best debugging tool), and we realize that we were off by one! @@ -29252,11 +29249,11 @@ Miscellaneous @end itemize Each of these are discussed in the following subsections. -In the following descriptions, commands which may be abbreviated +In the following descriptions, commands that may be abbreviated show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to -automatically repeat the previous command just by hitting @key{Enter}. +automatically repeat the previous command just by hitting @kbd{Enter}. This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi}, and @code{continue} executed without any argument. @@ -29306,7 +29303,7 @@ Set a breakpoint at entry to (the first instruction of) function @var{function}. @end table -Each breakpoint is assigned a number which can be used to delete it from +Each breakpoint is assigned a number that can be used to delete it from the breakpoint list using the @code{delete} command. With a breakpoint, you may also supply a condition. This is an @@ -29358,7 +29355,7 @@ watchpoint is made unconditional). @cindex breakpoint, delete by number @item @code{delete} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{d} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] -Delete specified breakpoints or a range of breakpoints. Deletes +Delete specified breakpoints or a range of breakpoints. Delete all defined breakpoints if no argument is supplied. @cindex debugger commands, @code{disable} @@ -29367,7 +29364,7 @@ all defined breakpoints if no argument is supplied. @cindex breakpoint, how to disable or enable @item @code{disable} [@var{n1 n2} @dots{} | @var{n}--@var{m}] Disable specified breakpoints or a range of breakpoints. Without -any argument, disables all breakpoints. +any argument, disable all breakpoints. @cindex debugger commands, @code{e} (@code{enable}) @cindex debugger commands, @code{enable} @@ -29377,18 +29374,18 @@ any argument, disables all breakpoints. @item @code{enable} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{e} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] Enable specified breakpoints or a range of breakpoints. Without -any argument, enables all breakpoints. -Optionally, you can specify how to enable the breakpoint: +any argument, enable all breakpoints. +Optionally, you can specify how to enable the breakpoints: @c nested table @table @code @item del -Enable the breakpoint(s) temporarily, then delete it when -the program stops at the breakpoint. +Enable the breakpoints temporarily, then delete each one when +the program stops at it. @item once -Enable the breakpoint(s) temporarily, then disable it when -the program stops at the breakpoint. +Enable the breakpoints temporarily, then disable each one when +the program stops at it. @end table @cindex debugger commands, @code{ignore} @@ -29456,7 +29453,7 @@ gawk> @item @code{continue} [@var{count}] @itemx @code{c} [@var{count}] Resume program execution. If continued from a breakpoint and @var{count} is -specified, ignores the breakpoint at that location the next @var{count} times +specified, ignore the breakpoint at that location the next @var{count} times before stopping. @cindex debugger commands, @code{finish} @@ -29510,7 +29507,7 @@ automatic display variables, and debugger options. @item @code{step} [@var{count}] @itemx @code{s} [@var{count}] Continue execution until control reaches a different source line in the -current stack frame. @code{step} steps inside any function called within +current stack frame, stepping inside any function called within the line. If the argument @var{count} is supplied, steps that many times before stopping, unless it encounters a breakpoint or watchpoint. @@ -29623,7 +29620,7 @@ or field. String values must be enclosed between double quotes (@code{"}@dots{}@code{"}). You can also set special @command{awk} variables, such as @code{FS}, -@code{NF}, @code{NR}, and son on. +@code{NF}, @code{NR}, and so on. @cindex debugger commands, @code{w} (@code{watch}) @cindex debugger commands, @code{watch} @@ -29635,7 +29632,7 @@ You can also set special @command{awk} variables, such as @code{FS}, Add variable @var{var} (or field @code{$@var{n}}) to the watch list. The debugger then stops whenever the value of the variable or field changes. Each watched item is assigned a -number which can be used to delete it from the watch list using the +number that can be used to delete it from the watch list using the @code{unwatch} command. With a watchpoint, you may also supply a condition. This is an @@ -29663,11 +29660,11 @@ watch list. @node Execution Stack @subsection Working with the Stack -Whenever you run a program which contains any function calls, +Whenever you run a program that contains any function calls, @command{gawk} maintains a stack of all of the function calls leading up to where the program is right now. You can see how you got to where you are, and also move around in the stack to see what the state of things was in the -functions which called the one you are in. The commands for doing this are: +functions that called the one you are in. The commands for doing this are: @table @asis @cindex debugger commands, @code{bt} (@code{backtrace}) @@ -29702,8 +29699,8 @@ Then select and print the frame. @item @code{frame} [@var{n}] @itemx @code{f} [@var{n}] Select and print stack frame @var{n}. Frame 0 is the currently executing, -or @dfn{innermost}, frame (function call), frame 1 is the frame that -called the innermost one. The highest numbered frame is the one for the +or @dfn{innermost}, frame (function call); frame 1 is the frame that +called the innermost one. The highest-numbered frame is the one for the main program. The printed information consists of the frame number, function and argument names, source file, and the source line. @@ -29719,7 +29716,7 @@ Then select and print the frame. Besides looking at the values of variables, there is often a need to get other sorts of information about the state of your program and of the -debugging environment itself. The @command{gawk} debugger has one command which +debugging environment itself. The @command{gawk} debugger has one command that provides this information, appropriately called @code{info}. @code{info} is used with one of a number of arguments that tell it exactly what you want to know: @@ -29807,12 +29804,12 @@ The available options are: @table @asis @item @code{history_size} @cindex debugger history size -The maximum number of lines to keep in the history file @file{./.gawk_history}. -The default is 100. +Set the maximum number of lines to keep in the history file +@file{./.gawk_history}. The default is 100. @item @code{listsize} @cindex debugger default list amount -The number of lines that @code{list} prints. The default is 15. +Specify the number of lines that @code{list} prints. The default is 15. @item @code{outfile} @cindex redirect @command{gawk} output, in debugger @@ -29822,7 +29819,7 @@ standard output. @item @code{prompt} @cindex debugger prompt -The debugger prompt. The default is @samp{@w{gawk> }}. +Change the debugger prompt. The default is @samp{@w{gawk> }}. @item @code{save_history} [@code{on} | @code{off}] @cindex debugger history file @@ -29833,7 +29830,7 @@ The default is @code{on}. @cindex save debugger options Save current options to file @file{./.gawkrc} upon exit. The default is @code{on}. -Options are read back in to the next session upon startup. +Options are read back into the next session upon startup. @item @code{trace} [@code{on} | @code{off}] @cindex instruction tracing, in debugger @@ -29856,7 +29853,7 @@ command in the file. Also, the list of commands may include additional @code{source} commands; however, the @command{gawk} debugger will not source the same file more than once in order to avoid infinite recursion. -In addition to, or instead of the @code{source} command, you can use +In addition to, or instead of, the @code{source} command, you can use the @option{-D @var{file}} or @option{--debug=@var{file}} command-line options to execute commands from a file non-interactively (@pxref{Options}). @@ -29865,16 +29862,16 @@ options to execute commands from a file non-interactively @node Miscellaneous Debugger Commands @subsection Miscellaneous Commands -There are a few more commands which do not fit into the +There are a few more commands that do not fit into the previous categories, as follows: @table @asis @cindex debugger commands, @code{dump} @cindex @code{dump} debugger command @item @code{dump} [@var{filename}] -Dump bytecode of the program to standard output or to the file +Dump byte code of the program to standard output or to the file named in @var{filename}. This prints a representation of the internal -instructions which @command{gawk} executes to implement the @command{awk} +instructions that @command{gawk} executes to implement the @command{awk} commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (@pxref{Signature Program}) demonstrates: @@ -29971,7 +29968,7 @@ Print lines centered around line number @var{n} in source file @var{filename}. This command may change the current source file. @item @var{function} -Print lines centered around beginning of the +Print lines centered around the beginning of the function @var{function}. This command may change the current source file. @end table @@ -29983,16 +29980,16 @@ function @var{function}. This command may change the current source file. @item @code{quit} @itemx @code{q} Exit the debugger. Debugging is great fun, but sometimes we all have -to tend to other obligations in life, and sometimes we find the bug, +to tend to other obligations in life, and sometimes we find the bug and are free to go on to the next one! As we saw earlier, if you are -running a program, the debugger warns you if you accidentally type +running a program, the debugger warns you when you type @samp{q} or @samp{quit}, to make sure you really want to quit. @cindex debugger commands, @code{trace} @cindex @code{trace} debugger command @item @code{trace} [@code{on} | @code{off}] -Turn on or off a continuous printing of instructions which are about to -be executed, along with printing the @command{awk} line which they +Turn on or off continuous printing of the instructions that are about to +be executed, along with the @command{awk} lines they implement. The default is @code{off}. It is to be hoped that most of the ``opcodes'' in these instructions are @@ -30008,7 +30005,7 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while If @command{gawk} is compiled with @uref{http://cnswww.cns.cwru.edu/php/chet/readline/readline.html, -the @code{readline} library}, you can take advantage of that library's +the GNU Readline library}, you can take advantage of that library's command completion and history expansion features. The following types of completion are available: @@ -30045,7 +30042,7 @@ and We hope you find the @command{gawk} debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has -some limitations. A few which are worth being aware of are: +some limitations. A few that it's worth being aware of are: @itemize @value{BULLET} @item @@ -30061,13 +30058,13 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands} (or if you are already familiar with @command{gawk} internals), you will realize that much of the internal manipulation of data in @command{gawk}, as in many interpreters, is done on a stack. -@code{Op_push}, @code{Op_pop}, and the like, are the ``bread and butter'' of +@code{Op_push}, @code{Op_pop}, and the like are the ``bread and butter'' of most @command{gawk} code. Unfortunately, as of now, the @command{gawk} debugger does not allow you to examine the stack's contents. That is, the intermediate results of expression evaluation are on the -stack, but cannot be printed. Rather, only variables which are defined +stack, but cannot be printed. Rather, only variables that are defined in the program can be printed. Of course, a workaround for this is to use more explicit variables at the debugging stage and then change back to obscure, perhaps more optimal code later. @@ -30081,12 +30078,12 @@ programmer, you are expected to know the meaning of @item The @command{gawk} debugger is designed to be used by running a program (with all its parameters) on the command line, as described in @ref{Debugger Invocation}. -There is no way (as of now) to attach or ``break in'' to a running program. -This seems reasonable for a language which is used mainly for quickly +There is no way (as of now) to attach or ``break into'' a running program. +This seems reasonable for a language that is used mainly for quickly executing, short programs. @item -The @command{gawk} debugger only accepts source supplied with the @option{-f} option. +The @command{gawk} debugger only accepts source code supplied with the @option{-f} option. @end itemize @ignore @@ -30100,8 +30097,8 @@ be added, and of course feel free to try to add them yourself! @itemize @value{BULLET} @item Programs rarely work correctly the first time. Finding bugs -is @dfn{debugging} and a program that helps you find bugs is a -@dfn{debugger}. @command{gawk} has a built-in debugger that works very +is called debugging, and a program that helps you find bugs is a +debugger. @command{gawk} has a built-in debugger that works very similarly to the GNU Debugger, GDB. @item @@ -30121,7 +30118,7 @@ breakpoints, execution, viewing and changing data, working with the stack, getting information, and other tasks. @item -If the @code{readline} library is available when @command{gawk} is +If the GNU Readline library is available when @command{gawk} is compiled, it is used by the debugger to provide command-line history and editing. @@ -30185,7 +30182,7 @@ paper and pencil (and/or a calculator). In theory, numbers can have an arbitrary number of digits on either side (or both sides) of the decimal point, and the results of a computation are always exact. -Some modern system can do decimal arithmetic in hardware, but usually you +Some modern systems can do decimal arithmetic in hardware, but usually you need a special software library to provide access to these instructions. There are also libraries that do decimal arithmetic entirely in software. @@ -30241,8 +30238,34 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615 -@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} -@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} +@iftex +@item Single-precision floating point (approximate) @tab @math{1.175494^{-38}} @tab @math{3.402823^{38}} +@item Double-precision floating point (approximate) @tab @math{2.225074^{-308}} @tab @math{1.797693^{308}} +@end iftex +@ifnottex +@ifnotdocbook +@item Single-precision floating point (approximate) @tab 1.175494e-38 @tab 3.402823e38 +@item Double-precision floating point (approximate) @tab 2.225074e-308 @tab 1.797693e308 +@end ifnotdocbook +@end ifnottex +@ifdocbook +@item Single-precision floating point (approximate) @tab +@docbook +1.175494<superscript>-38</superscript> +@end docbook +@tab +@docbook +3.402823<superscript>38</superscript> +@end docbook +@item Double-precision floating point (approximate) @tab +@docbook +2.225074<superscript>-308</superscript> +@end docbook +@tab +@docbook +1.797693<superscript>308</superscript> +@end docbook +@end ifdocbook @end multitable @end float @@ -30251,7 +30274,7 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. The rest of this @value{CHAPTER} uses a number of terms. Here are some informal definitions that should help you work your way through the material -here. +here: @table @dfn @item Accuracy @@ -30272,7 +30295,7 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.''@footnote{Thanks to Michael Brennan for this description, +``Not a number.''@footnote{Thanks to Michael Brennan for this description, which we 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, @@ -30315,8 +30338,8 @@ formula: @end display @noindent -Here, @var{prec} denotes the binary precision -(measured in bits) and @var{dps} (short for decimal places) +Here, @emph{prec} denotes the binary precision +(measured in bits) and @emph{dps} (short for decimal places) is the decimal digits. @item Rounding mode @@ -30324,7 +30347,7 @@ How numbers are rounded up or down when necessary. More details are provided later. @item Significand -A floating-point value consists the significand multiplied by 10 +A floating-point value consists of the significand multiplied by 10 to the power of the exponent. For example, in @code{1.2345e67}, the significand is @code{1.2345}. @@ -30348,7 +30371,7 @@ to allow greater precisions and larger exponent ranges. (@command{awk} uses only the 64-bit double-precision format.) @ref{table-ieee-formats} lists the precision and exponent -field values for the basic IEEE 754 binary formats: +field values for the basic IEEE 754 binary formats. @float Table,table-ieee-formats @caption{Basic IEEE format values} @@ -30412,12 +30435,12 @@ for more information. @author Teen Talk Barbie, July 1992 @end quotation -This @value{SECTION} provides a high level overview of the issues +This @value{SECTION} provides a high-level overview of the issues involved when doing lots of floating-point arithmetic.@footnote{There is a very nice @uref{http://www.validlab.com/goldberg/paper.pdf, paper on floating-point arithmetic} by David Goldberg, ``What Every -Computer Scientist Should Know About Floating-point Arithmetic,'' -@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), 5-48. This is +Computer Scientist Should Know About Floating-Point Arithmetic,'' +@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03): 5-48. This is worth reading if you are interested in the details, but it does require a background in computer science.} The discussion applies to both hardware and arbitrary-precision @@ -30486,7 +30509,7 @@ $ @kbd{gawk 'BEGIN @{ x = 0.875; y = 0.425} Often the error is so small you do not even notice it, and if you do, you can always specify how much precision you would like in your output. -Usually this is a format string like @code{"%.15g"}, which when +Usually this is a format string like @code{"%.15g"}, which, when used in the previous example, produces an output identical to the input. @node Comparing FP Values @@ -30525,7 +30548,7 @@ else The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating-point operations, +value that is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of @value{PI} using one of its many series representations: @@ -30578,7 +30601,7 @@ no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may be important -for your computation. Rounding error, cumulative precision loss +for your computation. Rounding error, cumulative precision loss, and underflow are often troublesome. When @command{gawk} tests the expressions @samp{0.1 + 12.2} and @@ -30618,7 +30641,8 @@ by our earlier attempt to compute the value of @value{PI}. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. -Repeated addition is not necessarily equivalent to multiplication +Additionally, you should understand that +repeated addition is not necessarily equivalent to multiplication in floating-point arithmetic. In the example in @ref{Errors accumulate}: @@ -30681,7 +30705,7 @@ to emulate an IEEE 754 binary format. @float Table,table-predefined-precision-strings @caption{Predefined precision strings for @code{PREC}} @multitable {@code{"double"}} {12345678901234567890123456789012345} -@headitem @code{PREC} @tab IEEE 754 Binary Format +@headitem @code{PREC} @tab IEEE 754 binary format @item @code{"half"} @tab 16-bit half-precision @item @code{"single"} @tab Basic 32-bit single precision @item @code{"double"} @tab Basic 64-bit double precision @@ -30713,7 +30737,6 @@ 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: -@end quotation @example $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'} @@ -30725,22 +30748,23 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'} $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'} @print{} 0.1000000000000000000000000 @end example +@end quotation @node Setting the rounding mode @subsection Setting the Rounding Mode The @code{ROUNDMODE} variable provides -program level control over the rounding mode. +program-level control over the rounding mode. The correspondence between @code{ROUNDMODE} and the IEEE rounding modes is shown in @ref{table-gawk-rounding-modes}. @float Table,table-gawk-rounding-modes @caption{@command{gawk} rounding modes} @multitable @columnfractions .45 .30 .25 -@headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE} +@headitem Rounding mode @tab IEEE name @tab @code{ROUNDMODE} @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"} -@item Round toward plus Infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} -@item Round toward negative Infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} +@item Round toward positive infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} +@item Round toward negative infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} @item Round toward zero @tab @code{roundTowardZero} @tab @code{"Z"} or @code{"z"} @item Round to nearest, ties away from zero @tab @code{roundTiesToAway} @tab @code{"A"} or @code{"a"} @end multitable @@ -30801,8 +30825,8 @@ distributes upward and downward rounds of exact halves, which might cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. -The other rounding modes are rarely used. Round toward positive infinity -(@code{roundTowardPositive}) and round toward negative infinity +The other rounding modes are rarely used. Rounding toward positive infinity +(@code{roundTowardPositive}) and toward negative infinity (@code{roundTowardNegative}) are often used to implement interval arithmetic, where you adjust the rounding mode to calculate upper and lower bounds for the range of output. The @code{roundTowardZero} mode can @@ -30859,17 +30883,17 @@ If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for correct output (using the formula @iftex -@math{prec = 3.322 @cdot dps}), +@math{prec = 3.322 @cdot dps}) would be @math{3.322 @cdot 183231}, @end iftex @ifnottex @ifnotdocbook -@samp{prec = 3.322 * dps}), +@samp{prec = 3.322 * dps}) would be 3.322 x 183231, @end ifnotdocbook @end ifnottex @docbook -<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>), +<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>) would be <emphasis>prec</emphasis> = 3.322 ⋅ 183231, @c @end docbook @@ -30907,7 +30931,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or -want, you can employ a subterfuge, and convert the integer to floating +want, you can employ a subterfuge and convert the integer to floating point first, like this: @example @@ -31044,7 +31068,7 @@ word sizes. See @node POSIX Floating Point Problems @section Standards Versus Existing Practice -Historically, @command{awk} has converted any non-numeric looking string +Historically, @command{awk} has converted any nonnumeric-looking string to the numeric value zero, when required. Furthermore, the original definition of the language and the original POSIX standards specified that @command{awk} only understands decimal numbers (base 10), and not octal @@ -31061,8 +31085,8 @@ notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not} source code constants.) @item -Support for the special IEEE 754 floating-point values ``Not A Number'' -(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf''). +Support for the special IEEE 754 floating-point values ``not a number'' +(NaN), positive infinity (``inf''), and negative infinity (``@minus{}inf''). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}. @@ -31083,21 +31107,21 @@ values is also a very severe departure from historical practice. @end itemize The second problem is that the @command{gawk} maintainer feels that this -interpretation of the standard, which requires a certain amount of +interpretation of the standard, which required a certain amount of ``language lawyering'' to arrive at in the first place, was not even -intended by the standard developers. In other words, ``we see how you +intended by the standard developers. In other words, ``We see how you got where you are, but we don't think that that's where you want to be.'' Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that @command{awk} support hexadecimal floating-point values and -special values for ``Not A Number'' and infinity. +special values for ``not a number'' and infinity. Although the @command{gawk} maintainer continues to feel that providing those features is inadvisable, nevertheless, on systems that support IEEE floating point, it seems -reasonable to provide @emph{some} way to support NaN and Infinity values. +reasonable to provide @emph{some} way to support NaN and infinity values. The solution implemented in @command{gawk} is as follows: @itemize @value{BULLET} @@ -31117,7 +31141,7 @@ $ @kbd{echo 0xDeadBeef | gawk --posix '@{ print $1 + 0 @}'} @end example @item -Without @option{--posix}, @command{gawk} interprets the four strings +Without @option{--posix}, @command{gawk} interprets the four string values @samp{+inf}, @samp{-inf}, @samp{+nan}, @@ -31139,7 +31163,7 @@ $ @kbd{echo 0xDeadBeef | gawk '@{ print $1 + 0 @}'} @end example @command{gawk} ignores case in the four special values. -Thus @samp{+nan} and @samp{+NaN} are the same. +Thus, @samp{+nan} and @samp{+NaN} are the same. @end itemize @node Floating point summary @@ -31152,9 +31176,9 @@ values. Standard @command{awk} uses double-precision floating-point values. @item -In the early 1990s, Barbie mistakenly said ``Math class is tough!'' +In the early 1990s Barbie mistakenly said, ``Math class is tough!'' Although math isn't tough, floating-point arithmetic isn't the same -as pencil and paper math, and care must be taken: +as pencil-and-paper math, and care must be taken: @c nested list @itemize @value{MINUS} @@ -31187,7 +31211,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and @item With @option{-M}, @command{gawk} performs arbitrary-precision integer arithmetic using the GMP library. -This is faster and more space efficient than using MPFR for +This is faster and more space-efficient than using MPFR for the same calculations. @item @@ -31199,7 +31223,7 @@ It pays to be aware of them. Overall, there is no need to be unduly suspicious about the results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and -paper. In order to take advantage of the power of computer floating point, +paper. In order to take advantage of the power of floating-point arithmetic, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the correct number @@ -31260,7 +31284,7 @@ Extensions are useful because they allow you (of course) to extend @command{gawk}'s functionality. For example, they can provide access to system calls (such as @code{chdir()} to change directory) and to other C library routines that could be of use. As with most software, -``the sky is the limit;'' if you can imagine something that you might +``the sky is the limit''; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the @dfn{application programming @@ -31268,7 +31292,7 @@ interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents -the sample extensions included in the @command{gawk} distribution, +the sample extensions included in the @command{gawk} distribution and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @xref{Extension Design}, for a discussion of the extension mechanism @@ -31421,7 +31445,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 @@ -31465,7 +31489,7 @@ This (rather large) @value{SECTION} describes the API in detail. @node Extension API Functions Introduction @subsection Introduction -Access to facilities within @command{gawk} are made available +Access to facilities within @command{gawk} is achieved by calling through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -31493,7 +31517,7 @@ Output wrappers Two-way processors @end itemize -All of these are discussed in detail, later in this @value{CHAPTER}. +All of these are discussed in detail later in this @value{CHAPTER}. @item Printing fatal, warning, and ``lint'' warning messages. @@ -31531,7 +31555,7 @@ Creating a new array Clearing an array @item -Flattening an array for easy C style looping over all its indices and elements +Flattening an array for easy C-style looping over all its indices and elements @end itemize @end itemize @@ -31543,8 +31567,9 @@ The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: +@c FIXME: Make this is a float at some point. @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}} -@headitem C Entity @tab Header File +@headitem C entity @tab Header file @item @code{EOF} @tab @code{<stdio.h>} @item Values for @code{errno} @tab @code{<errno.h>} @item @code{FILE} @tab @code{<stdio.h>} @@ -31570,7 +31595,7 @@ Doing so, however, is poor coding practice. Although the API only uses ISO C 90 features, there is an exception; the ``constructor'' functions use the @code{inline} keyword. If your compiler does not support this keyword, you should either place -@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a +@samp{-Dinline=''} on your command line or use the GNU Autotools and include a @file{config.h} file in your extensions. @item @@ -31578,7 +31603,7 @@ All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} from the extension @emph{must} come from calling one of -@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -31592,7 +31617,7 @@ characters are allowed. By intent, strings are maintained using the current multibyte encoding (as defined by @env{LC_@var{xxx}} environment variables) and not using wide characters. This matches how @command{gawk} stores strings internally -and also how characters are likely to be input and output from files. +and also how characters are likely to be input into and output from files. @end quotation @item @@ -31637,6 +31662,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent @value{SECTION}s, together with the functions that use them. +The general-purpose types and structures are as follows: + @table @code @item typedef void *awk_ext_id_t; A value of this type is received from @command{gawk} when an extension is loaded. @@ -31653,7 +31680,7 @@ while allowing @command{gawk} to use them as it needs to. @itemx @ @ @ @ awk_false = 0, @itemx @ @ @ @ awk_true @itemx @} awk_bool_t; -A simple boolean type. +A simple Boolean type. @item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @@ -31699,7 +31726,7 @@ The @code{val_type} member indicates what kind of value the @itemx #define array_cookie@ @ @ u.a @itemx #define scalar_cookie@ @ u.scl @itemx #define value_cookie@ @ @ u.vc -These macros make accessing the fields of the @code{awk_value_t} more +Using these macros makes accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; @@ -31722,7 +31749,7 @@ indicates what is in the @code{union}. Representing numbers is easy---the API uses a C @code{double}. Strings require more work. Because @command{gawk} allows embedded @sc{nul} bytes in string values, a string must be represented as a pair containing a -data-pointer and length. This is the @code{awk_string_t} type. +data pointer and length. This is the @code{awk_string_t} type. Identifiers (i.e., the names of global variables) can be associated with either scalar values or with arrays. In addition, @command{gawk} @@ -31735,12 +31762,12 @@ of the @code{union} as if they were fields in a @code{struct}; this is a common coding practice in C. Such code is easier to write and to read, but it remains @emph{your} responsibility to make sure that the @code{val_type} member correctly reflects the type of the value in -the @code{awk_value_t}. +the @code{awk_value_t} struct. Conceptually, the first three members of the @code{union} (number, string, and array) are all that is needed for working with @command{awk} values. However, because the API provides routines for accessing and changing -the value of global scalar variables only by using the variable's name, +the value of a global scalar variable only by using the variable's name, there is a performance penalty: @command{gawk} must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -31758,7 +31785,9 @@ See also the entry for ``Cookie'' in the @ref{Glossary}. object for that variable, and then use the cookie for getting the variable's value or for changing the variable's value. -This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro. +The @code{awk_scalar_t} type holds a scalar cookie, and the +@code{scalar_cookie} macro provides access to the value of that type +in the @code{awk_value_t} struct. Given a scalar cookie, @command{gawk} can directly retrieve or modify the value, as required, without having to find it first. @@ -31767,8 +31796,8 @@ If you know that you wish to use the same numeric or string @emph{value} for one or more variables, you can create the value once, retaining a @dfn{value cookie} for it, and then pass in that value cookie whenever you wish to set the value of a -variable. This saves both storage space within the running @command{gawk} -process as well as the time needed to create the value. +variable. This saves storage space within the running @command{gawk} +process and reduces the time needed to create the value. @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @@ -31796,13 +31825,13 @@ be passed to @command{gawk}. @item void gawk_free(void *ptr); Call the correct version of @code{free()} to release storage that was -allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. +allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. @end table The API has to provide these functions because it is possible for an extension to be compiled and linked against a different version of the C library than was used for the @command{gawk} -executable.@footnote{This is more common on MS-Windows systems, but +executable.@footnote{This is more common on MS-Windows systems, but it can happen on Unix-like systems as well.} If @command{gawk} were to use its version of @code{free()} when the memory came from an unrelated version of @code{malloc()}, unexpected behavior would @@ -31812,7 +31841,7 @@ Two convenience macros may be used for allocating storage from @code{gawk_malloc()} and @code{gawk_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were -procedure calls that do not return a value. +procedure calls that do not return a value: @table @code @item #define emalloc(pointer, type, size, message) @dots{} @@ -31849,7 +31878,7 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +This is like @code{emalloc()}, but it calls @code{gawk_realloc()} instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -31874,7 +31903,7 @@ for storage in @code{result}. It returns @code{result}. @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) This function creates a string value in the @code{awk_value_t} variable pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -31925,7 +31954,7 @@ The fields are: @table @code @item const char *name; The name of the new function. -@command{awk} level code calls the function by this name. +@command{awk}-level code calls the function by this name. This is a regular C string. Function names must obey the rules for @command{awk} @@ -31939,7 +31968,7 @@ This is a pointer to the C function that provides the extension's functionality. The function must fill in @code{*result} with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from one of +As mentioned earlier, string memory @emph{must} come from one of @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many @@ -31991,20 +32020,20 @@ The @code{exit_status} parameter is the exit status value that @command{gawk} intends to pass to the @code{exit()} system call. @item arg0 -A pointer to private data which @command{gawk} saves in order to pass to +A pointer to private data that @command{gawk} saves in order to pass to the function pointed to by @code{funcp}. @end table @end table -Exit callback functions are called in last-in-first-out (LIFO) +Exit callback functions are called in last-in, first-out (LIFO) order---that is, in the reverse order in which they are registered with @command{gawk}. @node Extension Version String @subsubsection Registering An Extension Version String -You can register a version string which indicates the name and -version of your extension, with @command{gawk}, as follows: +You can register a version string that indicates the name and +version of your extension with @command{gawk}, as follows: @table @code @item void register_ext_version(const char *version); @@ -32026,7 +32055,7 @@ of @code{RS} to find the end of the record, and then uses @code{FS} Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}). If you want, you can provide your own custom input parser. An input -parser's job is to return a record to the @command{gawk} record processing +parser's job is to return a record to the @command{gawk} record-processing code, along with indicators for the value and length of the data to be used for @code{RT}, if any. @@ -32044,9 +32073,9 @@ It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf); When @command{gawk} decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill -in certain fields in the @code{awk_input_buf_t} structure, and ensure +in certain fields in the @code{awk_input_buf_t} structure and ensure that certain conditions are true. It should then return true. If an -error of some kind occurs, it should not fill in any fields, and should +error of some kind occurs, it should not fill in any fields and should return false; then @command{gawk} will not use the input parser. The details are presented shortly. @end table @@ -32139,7 +32168,7 @@ in the @code{struct stat}, or any combination of these factors. Once @code{@var{XXX}_can_take_file()} has returned true, and @command{gawk} has decided to use your input parser, it calls -@code{@var{XXX}_take_control_of()}. That function then fills one of +@code{@var{XXX}_take_control_of()}. That function then fills either the @code{get_record} field or the @code{read_func} field in the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not} set to @code{INVALID_HANDLE}. The following list describes the fields that @@ -32161,21 +32190,21 @@ records. Said function is the core of the input parser. Its behavior is described in the text following this list. @item ssize_t (*read_func)(); -This function pointer should point to function that has the +This function pointer should point to a function that has the same behavior as the standard POSIX @code{read()} system call. It is an alternative to the @code{get_record} pointer. Its behavior is also described in the text following this list. @item void (*close_func)(struct awk_input *iobuf); This function pointer should point to a function that does -the ``tear down.'' It should release any resources allocated by +the ``teardown.'' It should release any resources allocated by @code{@var{XXX}_take_control_of()}. It may also close the file. If it does so, it should set the @code{fd} field to @code{INVALID_HANDLE}. If @code{fd} is still not @code{INVALID_HANDLE} after the call to this function, @command{gawk} calls the regular @code{close()} system call. -Having a ``tear down'' function is optional. If your input parser does +Having a ``teardown'' function is optional. If your input parser does not need it, do not set this field. Then, @command{gawk} calls the regular @code{close()} system call on the file descriptor, so it should be valid. @@ -32186,7 +32215,7 @@ input records. The parameters are as follows: @table @code @item char **out -This is a pointer to a @code{char *} variable which is set to point +This is a pointer to a @code{char *} variable that is set to point to the record. @command{gawk} makes its own copy of the data, so the extension must manage this storage. @@ -32239,17 +32268,17 @@ set this field explicitly. You must choose one method or the other: either a function that returns a record, or one that returns raw data. In particular, if you supply a function to get a record, @command{gawk} will -call it, and never call the raw read function. +call it, and will never call the raw read function. @end quotation @command{gawk} ships with a sample extension that reads directories, -returning records for each entry in the directory (@pxref{Extension +returning records for each entry in a directory (@pxref{Extension Sample Readdir}). You may wish to use that code as a guide for writing your own input parser. When writing an input parser, you should think about (and document) how it is expected to interact with @command{awk} code. You may want -it to always be called, and take effect as appropriate (as the +it to always be called, and to take effect as appropriate (as the @code{readdir} extension does). Or you may want it to take effect based upon the value of an @command{awk} variable, as the XML extension from the @code{gawkextlib} project does (@pxref{gawkextlib}). @@ -32359,7 +32388,7 @@ a pointer to any private data associated with the file. These pointers should be set to point to functions that perform the equivalent function as the @code{<stdio.h>} functions do, if appropriate. @command{gawk} uses these function pointers for all output. -@command{gawk} initializes the pointers to point to internal, ``pass through'' +@command{gawk} initializes the pointers to point to internal ``pass-through'' functions that just call the regular @code{<stdio.h>} functions, so an extension only needs to redefine those functions that are appropriate for what it does. @@ -32370,7 +32399,7 @@ upon the @code{name} and @code{mode} fields, and any additional state (such as @command{awk} variable values) that is appropriate. When @command{gawk} calls @code{@var{XXX}_take_control_of()}, that function should fill -in the other fields, as appropriate, except for @code{fp}, which it should just +in the other fields as appropriate, except for @code{fp}, which it should just use normally. You register your output wrapper with the following function: @@ -32410,14 +32439,14 @@ The fields are as follows: The name of the two-way processor. @item awk_bool_t (*can_take_two_way)(const char *name); -This function returns true if it wants to take over two-way I/O for this @value{FN}. +The function pointed to by this field should return true if it wants to take over two-way I/O for this @value{FN}. It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t (*take_control_of)(const char *name, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_input_buf_t *inbuf, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_output_buf_t *outbuf); -This function should fill in the @code{awk_input_buf_t} and +The function pointed to by this field should fill in the @code{awk_input_buf_t} and @code{awk_outut_buf_t} structures pointed to by @code{inbuf} and @code{outbuf}, respectively. These structures were described earlier. @@ -32446,7 +32475,7 @@ Register the two-way processor pointed to by @code{two_way_processor} with You can print different kinds of warning messages from your extension, as described here. Note that for these functions, -you must pass in the extension id received from @command{gawk} +you must pass in the extension ID received from @command{gawk} when the extension was loaded:@footnote{Because the API uses only ISO C 90 features, it cannot make use of the ISO C 99 variadic macro feature to hide that parameter. More's the pity.} @@ -32499,7 +32528,7 @@ matches what you requested, the function returns true and fills in the @code{awk_value_t} result. Otherwise, the function returns false, and the @code{val_type} member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual +print an error message or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. @@ -32532,32 +32561,32 @@ value type, as appropriate. This behavior is summarized in <entry><para><emphasis role="bold">String</emphasis></para></entry> <entry><para>String</para></entry> <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> <entry><para><emphasis role="bold">Number</emphasis></para></entry> <entry><para>Number if can be converted, else false</para></entry> <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Type</emphasis></para></entry> <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> <entry><para>Array</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Requested</emphasis></para></entry> <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> <entry><para>Scalar</para></entry> <entry><para>Scalar</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> @@ -32569,11 +32598,11 @@ value type, as appropriate. This behavior is summarized in </row> <row> <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> + <entry><para><emphasis role="bold">Value cookie</emphasis></para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para> + </entry><entry><para>False</para></entry> </row> </tbody> </tgroup> @@ -32591,12 +32620,12 @@ value type, as appropriate. This behavior is summarized in @end tex @multitable @columnfractions .166 .166 .198 .15 .15 .166 @headitem @tab @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{String} @tab String @tab String @tab false @tab false -@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false -@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @tab @b{String} @tab String @tab String @tab False @tab False +@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab False @tab False +@item @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab False +@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab False @tab False @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false +@item @tab @b{Value cookie} @tab False @tab False @tab False @tab False @end multitable @end ifnotdocbook @end ifnotplaintext @@ -32607,21 +32636,21 @@ value type, as appropriate. This behavior is summarized in +------------+------------+-----------+-----------+ | String | Number | Array | Undefined | +-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | +| | String | String | String | False | False | | |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | +| | Number | Number if | Number | False | False | | | | can be | | | | | | | converted, | | | | | | | else false | | | | | |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | +| Type | Array | False | False | Array | False | | Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | +| | Scalar | Scalar | Scalar | False | False | | |-----------+------------+------------+-----------+-----------+ | | Undefined | String | Number | Array | Undefined | | |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | +| | Value | False | False | False | False | +| | cookie | | | | | +-----------+-----------+------------+------------+-----------+-----------+ @end example @end ifplaintext @@ -32638,16 +32667,16 @@ passed to your extension function. They are: @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Fill in the @code{awk_value_t} structure pointed to by @code{result} -with the @code{count}'th argument. Return true if the actual -type matches @code{wanted}, false otherwise. In the latter +with the @code{count}th argument. Return true if the actual +type matches @code{wanted}, and false otherwise. In the latter case, @code{result@w{->}val_type} indicates the actual type -(@pxref{table-value-types-returned}). Counts are zero based---the first +(@pxref{table-value-types-returned}). Counts are zero-based---the first argument is numbered zero, the second one, and so on. @code{wanted} indicates the type of value expected. @item awk_bool_t set_argument(size_t count, awk_array_t array); Convert a parameter that was undefined into an array; this provides -call-by-reference for arrays. Return false if @code{count} is too big, +call by reference for arrays. Return false if @code{count} is too big, or if the argument's type is not undefined. @DBXREF{Array Manipulation} for more information on creating arrays. @end table @@ -32671,8 +32700,9 @@ allows you to create and release cached values. The following routines provide the ability to access and update global @command{awk}-level variables by name. In compiler terminology, identifiers of different kinds are termed @dfn{symbols}, thus the ``sym'' -in the routines' names. The data structure which stores information +in the routines' names. The data structure that stores information about symbols is termed a @dfn{symbol table}. +The functions are as follows: @table @code @item awk_bool_t sym_lookup(const char *name, @@ -32681,14 +32711,14 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise. +Return true if the actual type matches @code{wanted}, and false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @item awk_bool_t sym_update(const char *name, awk_value_t *value); Update the variable named by the string @code{name}, which is a regular C string. The variable is added to @command{gawk}'s symbol table -if it is not there. Return true if everything worked, false otherwise. +if it is not there. Return true if everything worked, and false otherwise. Changing types (scalar to array or vice versa) of an existing variable is @emph{not} allowed, nor may this routine be used to update an array. @@ -32713,7 +32743,7 @@ populate it. A @dfn{scalar cookie} is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in @command{gawk}'s symbol table every time -access is needed. This was discussed earlier in @ref{General Data Types}. +access is needed. This was discussed earlier, in @ref{General Data Types}. The following functions let you work with scalar cookies: @@ -32829,7 +32859,7 @@ and carefully check the return values from the API functions. @subsubsection Creating and Using Cached Values The routines in this section allow you to create and release -cached values. As with scalar cookies, in theory, cached values +cached values. Like scalar cookies, in theory, cached values are not necessary. You can create numbers and strings using the functions in @ref{Constructor Functions}. You can then assign those values to variables using @code{sym_update()} @@ -32907,7 +32937,7 @@ Using value cookies in this way saves considerable storage, as all of @code{VAR1} through @code{VAR100} share the same value. You might be wondering, ``Is this sharing problematic? -What happens if @command{awk} code assigns a new value to @code{VAR1}, +What happens if @command{awk} code assigns a new value to @code{VAR1}; are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. @@ -33011,7 +33041,7 @@ modify them. @node Array Functions @subsubsection Array Functions -The following functions relate to individual array elements. +The following functions relate to individual array elements: @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); @@ -33030,13 +33060,13 @@ Return false if @code{wanted} does not match the actual type or if @code{index} is not in the array (@pxref{table-value-types-returned}). The value for @code{index} can be numeric, in which case @command{gawk} -converts it to a string. Using non-integral values is possible, but +converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to strings -(@pxref{Conversion}); thus using integral values is safest. +(@pxref{Conversion}); thus, using integral values is safest. As with @emph{all} strings passed into @command{gawk} from an extension, the string value of @code{index} must come from @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}, and +@code{gawk_calloc()}, or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -33092,7 +33122,7 @@ flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data); When done with a flattened array, release the storage using this function. -You must pass in both the original array cookie, and the address of +You must pass in both the original array cookie and the address of the created @code{awk_flat_array_t} structure. The function returns true upon success, false otherwise. @end table @@ -33102,7 +33132,7 @@ The function returns true upon success, false otherwise. To @dfn{flatten} an array is to create a structure that represents the full array in a fashion that makes it easy -for C code to traverse the entire array. Test code +for C code to traverse the entire array. Some of the code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. @@ -33159,9 +33189,9 @@ dump_array_and_delete(int nargs, awk_value_t *result) @end example The function then proceeds in steps, as follows. First, retrieve -the name of the array, passed as the first argument. Then -retrieve the array itself. If either operation fails, print -error messages and return: +the name of the array, passed as the first argument, followed by +the array itself. If either operation fails, print an +error message and return: @example /* get argument named array as flat array and print it */ @@ -33197,7 +33227,7 @@ and print it: @end example The third step is to actually flatten the array, and then -to double check that the count in the @code{awk_flat_array_t} +to double-check that the count in the @code{awk_flat_array_t} is the same as the count just retrieved: @example @@ -33218,7 +33248,7 @@ is the same as the count just retrieved: The fourth step is to retrieve the index of the element to be deleted, which was passed as the second argument. Remember that argument counts passed to @code{get_argument()} -are zero-based, thus the second argument is numbered one: +are zero-based, and thus the second argument is numbered one: @example if (! get_argument(1, AWK_STRING, & value3)) @{ @@ -33233,7 +33263,7 @@ element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the @code{AWK_ELEMENT_DELETE} bit in the @code{flags} field of the element. When the array is released, @command{gawk} -traverses the flattened array, and deletes any elements which +traverses the flattened array, and deletes any elements that have this flag bit set: @example @@ -33521,10 +33551,10 @@ The API versions are available at compile time as constants: @table @code @item GAWK_API_MAJOR_VERSION -The major version of the API. +The major version of the API @item GAWK_API_MINOR_VERSION -The minor version of the API. +The minor version of the API @end table The minor version increases when new functions are added to the API. Such @@ -33542,14 +33572,14 @@ constant integers: @table @code @item api->major_version -The major version of the running @command{gawk}. +The major version of the running @command{gawk} @item api->minor_version -The minor version of the running @command{gawk}. +The minor version of the running @command{gawk} @end table It is up to the extension to decide if there are API incompatibilities. -Typically a check like this is enough: +Typically, a check like this is enough: @example if (api->major_version != GAWK_API_MAJOR_VERSION @@ -33563,7 +33593,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION @end example Such code is included in the boilerplate @code{dl_load_func()} macro -provided in @file{gawkapi.h} (discussed later, in +provided in @file{gawkapi.h} (discussed in @ref{Extension API Boilerplate}). @node Extension API Informational Variables @@ -33610,7 +33640,7 @@ as described here. The boilerplate needed is also provided in comments in the @file{gawkapi.h} header file: @example -/* Boiler plate code: */ +/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -33669,7 +33699,7 @@ to @code{NULL}, or to point to a string giving the name and version of your extension. @item static awk_ext_func_t func_table[] = @{ @dots{} @}; -This is an array of one or more @code{awk_ext_func_t} structures +This is an array of one or more @code{awk_ext_func_t} structures, as described earlier (@pxref{Extension Functions}). It can then be looped over for multiple calls to @code{add_ext_func()}. @@ -33800,7 +33830,7 @@ the @code{stat()} fails. It fills in the following elements: @table @code @item "name" -The name of the file that was @code{stat()}'ed. +The name of the file that was @code{stat()}ed. @item "dev" @itemx "ino" @@ -33856,7 +33886,7 @@ interprocess communications). The file is a directory. @item "fifo" -The file is a named-pipe (also known as a FIFO). +The file is a named pipe (also known as a FIFO). @item "file" The file is just a regular file. @@ -33879,7 +33909,7 @@ For some other systems, @dfn{a priori} knowledge is used to provide a value. Where no value can be determined, it defaults to 512. @end table -Several additional elements may be present depending upon the operating +Several additional elements may be present, depending upon the operating system and the type of the file. You can test for them in your @command{awk} program by using the @code{in} operator (@pxref{Reference to Elements}): @@ -33909,7 +33939,7 @@ edited slightly for presentation. See @file{extension/filefuncs.c} in the @command{gawk} distribution for the complete version.} The file includes a number of standard header files, and then includes -the @file{gawkapi.h} header file which provides the API definitions. +the @file{gawkapi.h} header file, which provides the API definitions. Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code (@pxref{Extension API Boilerplate}): @@ -33950,9 +33980,9 @@ int plugin_is_GPL_compatible; @cindex programming conventions, @command{gawk} extensions By convention, for an @command{awk} function @code{foo()}, the C function that implements it is called @code{do_foo()}. The function should have -two arguments: the first is an @code{int} usually called @code{nargs}, +two arguments. The first is an @code{int}, usually called @code{nargs}, that represents the number of actual arguments for the function. -The second is a pointer to an @code{awk_value_t}, usually named +The second is a pointer to an @code{awk_value_t} structure, usually named @code{result}: @example @@ -33998,7 +34028,7 @@ Finally, the function returns the return value to the @command{awk} level: The @code{stat()} extension is more involved. First comes a function that turns a numeric mode into a printable representation -(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity: +(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for brevity: @example /* format_mode --- turn a stat mode field into something readable */ @@ -34054,9 +34084,9 @@ array_set_numeric(awk_array_t array, const char *sub, double num) The following function does most of the work to fill in the @code{awk_array_t} result array with values obtained -from a valid @code{struct stat}. It is done in a separate function +from a valid @code{struct stat}. This work is done in a separate function to support the @code{stat()} function for @command{gawk} and also -to support the @code{fts()} extension which is included in +to support the @code{fts()} extension, which is included in the same file but whose code is not shown here (@pxref{Extension Sample File Functions}). @@ -34177,8 +34207,8 @@ the @code{stat()} system call instead of the @code{lstat()} system call. This is done by using a function pointer: @code{statfunc}. @code{statfunc} is initialized to point to @code{lstat()} (instead of @code{stat()}) to get the file information, in case the file is a -symbolic link. However, if there were three arguments, @code{statfunc} -is set point to @code{stat()}, instead. +symbolic link. However, if the third argument is included, @code{statfunc} +is set to point to @code{stat()}, instead. Here is the @code{do_stat()} function, which starts with variable declarations and argument checking: @@ -34234,7 +34264,7 @@ Next, it gets the information for the file. If the called function /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) @{ update_ERRNO_int(errno); @@ -34256,7 +34286,9 @@ Finally, it's necessary to provide the ``glue'' that loads the new function(s) into @command{gawk}. The @code{filefuncs} extension also provides an @code{fts()} -function, which we omit here. For its sake there is an initialization +function, which we omit here +(@pxref{Extension Sample File Functions}). +For its sake, there is an initialization function: @example @@ -34381,9 +34413,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @section The Sample Extensions in the @command{gawk} Distribution @cindex extensions distributed with @command{gawk} -This @value{SECTION} provides brief overviews of the sample extensions +This @value{SECTION} provides a brief overview of the sample extensions that come in the @command{gawk} distribution. Some of them are intended -for production use (e.g., the @code{filefuncs}, @code{readdir} and +for production use (e.g., the @code{filefuncs}, @code{readdir}, and @code{inplace} extensions). Others mainly provide example code that shows how to use the extension API. @@ -34419,14 +34451,14 @@ This is how you load the extension. @item @code{result = chdir("/some/directory")} The @code{chdir()} function is a direct hook to the @code{chdir()} system call to change the current directory. It returns zero -upon success or less than zero upon error. In the latter case, it updates -@code{ERRNO}. +upon success or a value less than zero upon error. +In the latter case, it updates @code{ERRNO}. @cindex @code{stat()} extension function @item @code{result = stat("/some/path", statdata} [@code{, follow}]@code{)} The @code{stat()} function provides a hook into the @code{stat()} system call. -It returns zero upon success or less than zero upon error. +It returns zero upon success or a value less than zero upon error. In the latter case, it updates @code{ERRNO}. By default, it uses the @code{lstat()} system call. However, if passed @@ -34453,10 +34485,10 @@ array with information retrieved from the filesystem, as follows: @item @code{"major"} @tab @code{st_major} @tab Device files @item @code{"minor"} @tab @code{st_minor} @tab Device files @item @code{"blksize"} @tab @code{st_blksize} @tab All -@item @code{"pmode"} @tab A human-readable version of the mode value, such as printed by -@command{ls}. For example, @code{"-rwxr-xr-x"} @tab All +@item @code{"pmode"} @tab A human-readable version of the mode value, like that printed by +@command{ls} (for example, @code{"-rwxr-xr-x"}) @tab All @item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links -@item @code{"type"} @tab The type of the file as a string. One of +@item @code{"type"} @tab The type of the file as a string---one of @code{"file"}, @code{"blockdev"}, @code{"chardev"}, @@ -34466,15 +34498,15 @@ array with information retrieved from the filesystem, as follows: @code{"symlink"}, @code{"door"}, or -@code{"unknown"}. -Not all systems support all file types. @tab All +@code{"unknown"} +(not all systems support all file types) @tab All @end multitable @cindex @code{fts()} extension function @item @code{flags = or(FTS_PHYSICAL, ...)} @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the -@code{filedata} array as described next. @code{flags} is the bitwise +@code{filedata} array, as described next. @code{flags} is the bitwise OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -34530,7 +34562,8 @@ During a traversal, do not cross onto a different mounted filesystem. @end table @item filedata -The @code{filedata} array is first cleared. Then, @code{fts()} creates +The @code{filedata} array holds the results. +@code{fts()} first clears it. Then it creates an element in @code{filedata} for every element in @code{pathlist}. The index is the name of the directory or file given in @code{pathlist}. The element for this index is itself an array. There are two cases: @@ -34572,7 +34605,7 @@ for a file: @code{"path"}, @code{"stat"}, and @code{"error"}. @end table The @code{fts()} function returns zero if there were no errors. -Otherwise it returns @minus{}1. +Otherwise, it returns @minus{}1. @quotation NOTE The @code{fts()} extension does not exactly mimic the @@ -34614,14 +34647,14 @@ The arguments to @code{fnmatch()} are: @table @code @item pattern -The @value{FN} wildcard to match. +The @value{FN} wildcard to match @item string -The @value{FN} string. +The @value{FN} string @item flag Either zero, or the bitwise OR of one or more of the -flags in the @code{FNM} array. +flags in the @code{FNM} array @end table The flags are as follows: @@ -34658,14 +34691,14 @@ This is how you load the extension. @cindex @code{fork()} extension function @item pid = fork() This function creates a new process. The return value is zero in the -child and the process-ID number of the child in the parent, or @minus{}1 +child and the process ID number of the child in the parent, or @minus{}1 upon error. In the latter case, @code{ERRNO} indicates the problem. In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are updated to reflect the correct values. @cindex @code{waitpid()} extension function @item ret = waitpid(pid) -This function takes a numeric argument, which is the process-ID to +This function takes a numeric argument, which is the process ID to wait for. The return value is that of the @code{waitpid()} system call. @@ -34693,8 +34726,8 @@ else @subsection Enabling In-Place File Editing @cindex @code{inplace} extension -The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option -which performs ``in place'' editing of each input file. +The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option, +which performs ``in-place'' editing of each input file. It uses the bundled @file{inplace.awk} include file to invoke the extension properly: @@ -34790,14 +34823,14 @@ they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode number and the @value{FN}, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +has a third field (also separated by a slash), which is a single letter indicating the type of the file. The letters and their corresponding file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types @caption{File types returned by the @code{readdir} extension} @multitable @columnfractions .1 .9 -@headitem Letter @tab File Type +@headitem Letter @tab File type @item @code{b} @tab Block device @item @code{c} @tab Character device @item @code{d} @tab Directory @@ -34825,7 +34858,7 @@ Here is an example: @@load "readdir" @dots{} BEGIN @{ FS = "/" @} -@{ print "file name is", $2 @} +@{ print "@value{FN} is", $2 @} @end example @node Extension Sample Revout @@ -34846,8 +34879,7 @@ BEGIN @{ @} @end example -The output from this program is: -@samp{cinap t'nod}. +The output from this program is @samp{cinap t'nod}. @node Extension Sample Rev2way @subsection Two-Way I/O Example @@ -34902,7 +34934,7 @@ success, or zero upon failure. @code{reada()} is the inverse of @code{writea()}; it reads the file named as its first argument, filling in the array named as the second argument. It clears the array first. -Here too, the return value is one on success and zero upon failure. +Here too, the return value is one on success, or zero upon failure. @end table The array created by @code{reada()} is identical to that written by @@ -34990,7 +35022,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}. Attempt to sleep for @var{seconds} seconds. If @var{seconds} is negative, or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}. Otherwise, return zero after sleeping for the indicated amount of time. -Note that @var{seconds} may be a floating-point (non-integral) value. +Note that @var{seconds} may be a floating-point (nonintegral) value. Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table @@ -35017,10 +35049,13 @@ project provides a number of @command{gawk} extensions, including one for processing XML files. This is the evolution of the original @command{xgawk} (XML @command{gawk}) project. -As of this writing, there are six extensions: +As of this writing, there are seven extensions: @itemize @value{BULLET} @item +@code{errno} extension + +@item GD graphics library extension @item @@ -35031,7 +35066,7 @@ PostgreSQL extension @item MPFR library extension -(this provides access to a number of MPFR functions which @command{gawk}'s +(this provides access to a number of MPFR functions that @command{gawk}'s native MPFR support does not) @item @@ -35085,7 +35120,7 @@ make install @ii{Install the extensions} If you have installed @command{gawk} in the standard way, then you will likely not need the @option{--with-gawk} option when configuring -@code{gawkextlib}. You may also need to use the @command{sudo} utility +@code{gawkextlib}. You may need to use the @command{sudo} utility to install both @command{gawk} and @code{gawkextlib}, depending upon how your system works. @@ -35110,7 +35145,7 @@ named @code{plugin_is_GPL_compatible}. @item Communication between @command{gawk} and an extension is two-way. -@command{gawk} passes a @code{struct} to the extension which contains +@command{gawk} passes a @code{struct} to the extension that contains various data fields and function pointers. The extension can then call into @command{gawk} via the supplied function pointers to accomplish certain tasks. @@ -35123,7 +35158,7 @@ By convention, implementation functions are named @code{do_@var{XXXX}()} for some @command{awk}-level function @code{@var{XXXX}()}. @item -The API is defined in a header file named @file{gawkpi.h}. You must include +The API is defined in a header file named @file{gawkapi.h}. You must include a number of standard header files @emph{before} including it in your source file. @item @@ -35168,7 +35203,7 @@ getting the count of elements in an array; creating a new array; clearing an array; and -flattening an array for easy C style looping over all its indices and elements) +flattening an array for easy C-style looping over all its indices and elements) @end itemize @item @@ -35176,7 +35211,7 @@ The API defines a number of standard data types for representing @command{awk} values, array elements, and arrays. @item -The API provide convenience functions for constructing values. +The API provides convenience functions for constructing values. It also provides memory management functions to ensure compatibility between memory allocated by @command{gawk} and memory allocated by an extension. @@ -35202,8 +35237,8 @@ file make this easier to do. @item The @command{gawk} distribution includes a number of small but useful -sample extensions. The @code{gawkextlib} project includes several more, -larger, extensions. If you wish to write an extension and contribute it +sample extensions. The @code{gawkextlib} project includes several more +(larger) extensions. If you wish to write an extension and contribute it to the community of @command{gawk} users, the @code{gawkextlib} project is the place to do so. @@ -35331,81 +35366,81 @@ cross-references to further details: @itemize @value{BULLET} @item The requirement for @samp{;} to separate rules on a line -(@pxref{Statements/Lines}). +(@pxref{Statements/Lines}) @item User-defined functions and the @code{return} statement -(@pxref{User-defined}). +(@pxref{User-defined}) @item The @code{delete} statement (@pxref{Delete}). @item The @code{do}-@code{while} statement -(@pxref{Do Statement}). +(@pxref{Do Statement}) @item The built-in functions @code{atan2()}, @code{cos()}, @code{sin()}, @code{rand()}, and -@code{srand()} (@pxref{Numeric Functions}). +@code{srand()} (@pxref{Numeric Functions}) @item The built-in functions @code{gsub()}, @code{sub()}, and @code{match()} -(@pxref{String Functions}). +(@pxref{String Functions}) @item The built-in functions @code{close()} and @code{system()} -(@pxref{I/O Functions}). +(@pxref{I/O Functions}) @item The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART}, -and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}). +and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}) @item -Assignable @code{$0} (@pxref{Changing Fields}). +Assignable @code{$0} (@pxref{Changing Fields}) @item The conditional expression using the ternary operator @samp{?:} -(@pxref{Conditional Exp}). +(@pxref{Conditional Exp}) @item -The expression @samp{@var{index-variable} in @var{array}} outside of @code{for} -statements (@pxref{Reference to Elements}). +The expression @samp{@var{indx} in @var{array}} outside of @code{for} +statements (@pxref{Reference to Elements}) @item The exponentiation operator @samp{^} (@pxref{Arithmetic Ops}) and its assignment operator -form @samp{^=} (@pxref{Assignment Ops}). +form @samp{^=} (@pxref{Assignment Ops}) @item C-compatible operator precedence, which breaks some old @command{awk} -programs (@pxref{Precedence}). +programs (@pxref{Precedence}) @item Regexps as the value of @code{FS} (@pxref{Field Separators}) and as the third argument to the @code{split()} function (@pxref{String Functions}), rather than using only the first character -of @code{FS}. +of @code{FS} @item Dynamic regexps as operands of the @samp{~} and @samp{!~} operators -(@pxref{Computed Regexps}). +(@pxref{Computed Regexps}) @item The escape sequences @samp{\b}, @samp{\f}, and @samp{\r} -(@pxref{Escape Sequences}). +(@pxref{Escape Sequences}) @item Redirection of input for the @code{getline} function -(@pxref{Getline}). +(@pxref{Getline}) @item Multiple @code{BEGIN} and @code{END} rules -(@pxref{BEGIN/END}). +(@pxref{BEGIN/END}) @item Multidimensional arrays -(@pxref{Multidimensional}). +(@pxref{Multidimensional}) @end itemize @node SVR4 @@ -35417,54 +35452,54 @@ The System V Release 4 (1989) version of Unix @command{awk} added these features @itemize @value{BULLET} @item -The @code{ENVIRON} array (@pxref{Built-in Variables}). +The @code{ENVIRON} array (@pxref{Built-in Variables}) @c gawk and MKS awk @item Multiple @option{-f} options on the command line -(@pxref{Options}). +(@pxref{Options}) @c MKS awk @item The @option{-v} option for assigning variables before program execution begins -(@pxref{Options}). +(@pxref{Options}) @c GNU, Bell Laboratories & MKS together @item -The @option{--} signal for terminating command-line options. +The @option{--} signal for terminating command-line options @item The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences -(@pxref{Escape Sequences}). +(@pxref{Escape Sequences}) @c GNU, for ANSI C compat @item A defined return value for the @code{srand()} built-in function -(@pxref{Numeric Functions}). +(@pxref{Numeric Functions}) @item The @code{toupper()} and @code{tolower()} built-in string functions for case translation -(@pxref{String Functions}). +(@pxref{String Functions}) @item A cleaner specification for the @samp{%c} format-control letter in the @code{printf} function -(@pxref{Control Letters}). +(@pxref{Control Letters}) @item The ability to dynamically pass the field width and precision (@code{"%*.*d"}) in the argument list of @code{printf} and @code{sprintf()} -(@pxref{Control Letters}). +(@pxref{Control Letters}) @item The use of regexp constants, such as @code{/foo/}, as expressions, where they are equivalent to using the matching operator, as in @samp{$0 ~ /foo/} -(@pxref{Using Constant Regexps}). +(@pxref{Using Constant Regexps}) @item Processing of escape sequences inside command-line variable assignments -(@pxref{Assignment Options}). +(@pxref{Assignment Options}) @end itemize @node POSIX @@ -35478,23 +35513,23 @@ introduced the following changes into the language: @itemize @value{BULLET} @item The use of @option{-W} for implementation-specific options -(@pxref{Options}). +(@pxref{Options}) @item The use of @code{CONVFMT} for controlling the conversion of numbers -to strings (@pxref{Conversion}). +to strings (@pxref{Conversion}) @item The concept of a numeric string and tighter comparison rules to go -with it (@pxref{Typing and Comparison}). +with it (@pxref{Typing and Comparison}) @item The use of predefined variables as function parameter names is forbidden -(@pxref{Definition Syntax}). +(@pxref{Definition Syntax}) @item More complete documentation of many of the previously undocumented -features of the language. +features of the language @end itemize In 2012, a number of extensions that had been commonly available for @@ -35503,15 +35538,15 @@ many years were finally added to POSIX. They are: @itemize @value{BULLET} @item The @code{fflush()} built-in function for flushing buffered output -(@pxref{I/O Functions}). +(@pxref{I/O Functions}) @item The @code{nextfile} statement -(@pxref{Nextfile Statement}). +(@pxref{Nextfile Statement}) @item The ability to delete all of an array at once with @samp{delete @var{array}} -(@pxref{Delete}). +(@pxref{Delete}) @end itemize @@ -35541,22 +35576,22 @@ originally appeared in his version of @command{awk}: The @samp{**} and @samp{**=} operators (@pxref{Arithmetic Ops} and -@ref{Assignment Ops}). +@ref{Assignment Ops}) @item The use of @code{func} as an abbreviation for @code{function} -(@pxref{Definition Syntax}). +(@pxref{Definition Syntax}) @item The @code{fflush()} built-in function for flushing buffered output -(@pxref{I/O Functions}). +(@pxref{I/O Functions}) @ignore @item The @code{SYMTAB} array, that allows access to @command{awk}'s internal symbol table. This feature was never documented for his @command{awk}, largely because it is somewhat shakily implemented. For instance, you cannot access arrays -or array elements through it. +or array elements through it @end ignore @end itemize @@ -35586,7 +35621,7 @@ Additional predefined variables: @itemize @value{MINUS} @item The -@code{ARGIND} +@code{ARGIND}, @code{BINMODE}, @code{ERRNO}, @code{FIELDWIDTHS}, @@ -35598,7 +35633,7 @@ The and @code{TEXTDOMAIN} variables -(@pxref{Built-in Variables}). +(@pxref{Built-in Variables}) @end itemize @item @@ -35606,15 +35641,15 @@ Special files in I/O redirections: @itemize @value{MINUS} @item -The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and +The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr}, and @file{/dev/fd/@var{N}} special @value{FN}s -(@pxref{Special Files}). +(@pxref{Special Files}) @item The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for TCP/IP networking using @samp{|&} to specify which version of the IP protocol to use -(@pxref{TCP/IP Networking}). +(@pxref{TCP/IP Networking}) @end itemize @item @@ -35623,37 +35658,37 @@ Changes and/or additions to the language: @itemize @value{MINUS} @item The @samp{\x} escape sequence -(@pxref{Escape Sequences}). +(@pxref{Escape Sequences}) @item Full support for both POSIX and GNU regexps -(@pxref{Regexp}). +(@pxref{Regexp}) @item The ability for @code{FS} and for the third argument to @code{split()} to be null strings -(@pxref{Single Character Fields}). +(@pxref{Single Character Fields}) @item The ability for @code{RS} to be a regexp -(@pxref{Records}). +(@pxref{Records}) @item The ability to use octal and hexadecimal constants in @command{awk} program source code -(@pxref{Nondecimal-numbers}). +(@pxref{Nondecimal-numbers}) @item The @samp{|&} operator for two-way I/O to a coprocess -(@pxref{Two-way I/O}). +(@pxref{Two-way I/O}) @item Indirect function calls -(@pxref{Indirect Calls}). +(@pxref{Indirect Calls}) @item Directories on the command line produce a warning and are skipped -(@pxref{Command-line directories}). +(@pxref{Command-line directories}) @end itemize @item @@ -35662,11 +35697,11 @@ New keywords: @itemize @value{MINUS} @item The @code{BEGINFILE} and @code{ENDFILE} special patterns -(@pxref{BEGINFILE/ENDFILE}). +(@pxref{BEGINFILE/ENDFILE}) @item The @code{switch} statement -(@pxref{Switch Statement}). +(@pxref{Switch Statement}) @end itemize @item @@ -35676,30 +35711,30 @@ Changes to standard @command{awk} functions: @item The optional second argument to @code{close()} that allows closing one end of a two-way pipe to a coprocess -(@pxref{Two-way I/O}). +(@pxref{Two-way I/O}) @item -POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix}. +POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix} @item The @code{length()} function accepts an array argument and returns the number of elements in the array -(@pxref{String Functions}). +(@pxref{String Functions}) @item The optional third argument to the @code{match()} function for capturing text-matching subexpressions within a regexp -(@pxref{String Functions}). +(@pxref{String Functions}) @item Positional specifiers in @code{printf} formats for making translations easier -(@pxref{Printf Ordering}). +(@pxref{Printf Ordering}) @item The @code{split()} function's additional optional fourth -argument which is an array to hold the text of the field separators -(@pxref{String Functions}). +argument, which is an array to hold the text of the field separators +(@pxref{String Functions}) @end itemize @item @@ -35709,16 +35744,16 @@ Additional functions only in @command{gawk}: @item The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions for more powerful text manipulation -(@pxref{String Functions}). +(@pxref{String Functions}) @item The @code{asort()} and @code{asorti()} functions for sorting arrays -(@pxref{Array Sorting}). +(@pxref{Array Sorting}) @item The @code{mktime()}, @code{systime()}, and @code{strftime()} functions for working with timestamps -(@pxref{Time Functions}). +(@pxref{Time Functions}) @item The @@ -35730,22 +35765,22 @@ The and @code{xor()} functions for bit manipulation -(@pxref{Bitwise Functions}). +(@pxref{Bitwise Functions}) @c In 4.1, and(), or() and xor() grew the ability to take > 2 arguments @item The @code{isarray()} function to check if a variable is an array or not -(@pxref{Type Functions}). +(@pxref{Type Functions}) @item -The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()} +The @code{bindtextdomain()}, @code{dcgettext()}, and @code{dcngettext()} functions for internationalization -(@pxref{Programmer i18n}). +(@pxref{Programmer i18n}) @item The @code{div()} function for doing integer division and remainder -(@pxref{Numeric Functions}). +(@pxref{Numeric Functions}) @end itemize @item @@ -35755,12 +35790,12 @@ Changes and/or additions in the command-line options: @item The @env{AWKPATH} environment variable for specifying a path search for the @option{-f} command-line option -(@pxref{Options}). +(@pxref{Options}) @item The @env{AWKLIBPATH} environment variable for specifying a path search for the @option{-l} command-line option -(@pxref{Options}). +(@pxref{Options}) @item The @@ -35789,7 +35824,7 @@ The and @option{-V} short options. Also, the -ability to use GNU-style long-named options that start with @option{--} +ability to use GNU-style long-named options that start with @option{--}, and the @option{--assign}, @option{--bignum}, @@ -35869,7 +35904,7 @@ GCC for VAX and Alpha has not been tested for a while. @end itemize @item -Support for the following obsolete systems was removed from the code +Support for the following obsolete system was removed from the code for @command{gawk} @value{PVERSION} 4.1: @c nested table @@ -36549,9 +36584,9 @@ by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk}, the three most widely used freely available versions of @command{awk} (@pxref{Other Versions}). -@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} -@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @tab Now standard -@item @samp{\x} Escape sequence @tab X @tab X @tab X @tab +@multitable {@file{/dev/stderr} special file} {BWK @command{awk}} {@command{mawk}} {@command{gawk}} {Now standard} +@headitem Feature @tab BWK @command{awk} @tab @command{mawk} @tab @command{gawk} @tab Now standard +@item @samp{\x} escape sequence @tab X @tab X @tab X @tab @item @code{FS} as null string @tab X @tab X @tab X @tab @item @file{/dev/stdin} special file @tab X @tab X @tab X @tab @item @file{/dev/stdout} special file @tab X @tab X @tab X @tab @@ -36582,7 +36617,7 @@ in the machine's native character set. Thus, on ASCII-based systems, @samp{[a-z]} matched all the lowercase letters, and only the lowercase letters, as the numeric values for the letters from @samp{a} through @samp{z} were contiguous. (On an EBCDIC system, the range @samp{[a-z]} -includes additional, non-alphabetic characters as well.) +includes additional nonalphabetic characters as well.) Almost all introductory Unix literature explained range expressions as working in this fashion, and in particular, would teach that the @@ -36607,7 +36642,7 @@ What does that mean? In many locales, @samp{A} and @samp{a} are both less than @samp{B}. In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; -instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. +instead, it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. This point needs to be emphasized: much literature teaches that you should use @samp{[a-z]} to match a lowercase character. But on systems with @@ -36636,23 +36671,23 @@ is perfectly valid in ASCII, but is not valid in many Unicode locales, such as @code{en_US.UTF-8}. Early versions of @command{gawk} used regexp matching code that was not -locale aware, so ranges had their traditional interpretation. +locale-aware, so ranges had their traditional interpretation. When @command{gawk} switched to using locale-aware regexp matchers, the problems began; especially as both GNU/Linux and commercial Unix vendors started implementing non-ASCII locales, @emph{and making them the default}. Perhaps the most frequently asked question became something -like ``why does @samp{[A-Z]} match lowercase letters?!?'' +like, ``Why does @samp{[A-Z]} match lowercase letters?!?'' @cindex Berry, Karl This situation existed for close to 10 years, if not more, and the @command{gawk} maintainer grew weary of trying to explain that -@command{gawk} was being nicely standards compliant, and that the issue +@command{gawk} was being nicely standards-compliant, and that the issue was in the user's locale. During the development of @value{PVERSION} 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And thus was born the Campaign for Rational Range Interpretation (or -RRI). A number of GNU tools have either implemented this change, +RRI). A number of GNU tools have already implemented this change, or will soon. Thanks to Karl Berry for coining the phrase ``Rational Range Interpretation.''} @@ -36666,9 +36701,10 @@ and By using this lovely technical term, the standard gives license to implementors to implement ranges in whatever way they choose. -The @command{gawk} maintainer chose to apply the pre-POSIX meaning in all -cases: the default regexp matching; with @option{--traditional} and with -@option{--posix}; in all cases, @command{gawk} remains POSIX compliant. +The @command{gawk} maintainer chose to apply the pre-POSIX meaning +both with the default regexp matching and when @option{--traditional} or +@option{--posix} are used. +In all cases @command{gawk} remains POSIX-compliant. @node Contributors @appendixsec Major Contributors to @command{gawk} @@ -36714,7 +36750,7 @@ to around 90 pages. Richard Stallman helped finish the implementation and the initial draft of this @value{DOCUMENT}. -He is also the founder of the FSF and the GNU project. +He is also the founder of the FSF and the GNU Project. @item @cindex Woods, John @@ -36878,28 +36914,28 @@ John Haque made the following contributions: @itemize @value{MINUS} @item The modifications to convert @command{gawk} -into a byte-code interpreter, including the debugger. +into a byte-code interpreter, including the debugger @item -The addition of true arrays of arrays. +The addition of true arrays of arrays @item -The additional modifications for support of arbitrary-precision arithmetic. +The additional modifications for support of arbitrary-precision arithmetic @item The initial text of -@ref{Arbitrary Precision Arithmetic}. +@ref{Arbitrary Precision Arithmetic} @item The work to merge the three versions of @command{gawk} -into one, for the 4.1 release. +into one, for the 4.1 release @item -Improved array internals for arrays indexed by integers. +Improved array internals for arrays indexed by integers @item -The improved array sorting features were driven by John together -with Pat Rankin. +The improved array sorting features were also driven by John, together +with Pat Rankin @end itemize @cindex Papadopoulos, Panos @@ -36940,10 +36976,10 @@ helping David Trueman, and as the primary maintainer since around 1994. @itemize @value{BULLET} @item The @command{awk} language has evolved over time. The first release -was with V7 Unix circa 1978. In 1987, for System V Release 3.1, +was with V7 Unix, circa 1978. In 1987, for System V Release 3.1, major additions, including user-defined functions, were made to the language. Additional changes were made for System V Release 4, in 1989. -Since then, further minor changes happen under the auspices of the +Since then, further minor changes have happened under the auspices of the POSIX standard. @item @@ -36959,7 +36995,7 @@ options. The interaction of POSIX locales and regexp matching in @command{gawk} has been confusing over the years. Today, @command{gawk} implements Rational Range Interpretation, where ranges of the form @samp{[a-z]} match @emph{only} the characters numerically between -@samp{a} through @samp{z} in the machine's native character set. Usually this is ASCII +@samp{a} through @samp{z} in the machine's native character set. Usually this is ASCII, but it can be EBCDIC on IBM S/390 systems. @item @@ -37044,7 +37080,7 @@ will be less busy, and you can usually find one closer to your site. @command{gawk} is distributed as several @code{tar} files compressed with different compression programs: @command{gzip}, @command{bzip2}, and @command{xz}. For simplicity, the rest of these instructions assume -you are using the one compressed with the GNU Zip program, @code{gzip}. +you are using the one compressed with the GNU Gzip program (@command{gzip}). Once you have the distribution (e.g., @file{gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz}), @@ -37095,12 +37131,12 @@ operating systems: @table @asis @item Various @samp{.c}, @samp{.y}, and @samp{.h} files -The actual @command{gawk} source code. +These files contain the actual @command{gawk} source code. @end table @table @file @item ABOUT-NLS -Information about GNU @command{gettext} and translations. +A file containing information about GNU @command{gettext} and translations. @item AUTHORS A file with some information about the authorship of @command{gawk}. @@ -37130,7 +37166,7 @@ An older list of changes to @command{gawk}. The GNU General Public License. @item POSIX.STD -A description of behaviors in the POSIX standard for @command{awk} which +A description of behaviors in the POSIX standard for @command{awk} that are left undefined, or where @command{gawk} may not comply fully, as well as a list of things that the POSIX standard should describe but does not. @@ -37440,14 +37476,17 @@ Similarly, setting the @code{LINT} variable (@pxref{User-modified}) has no effect on the running @command{awk} program. -When used with GCC's automatic dead-code-elimination, this option +When used with the GNU Compiler Collection's (GCC's) +automatic dead-code-elimination, this option cuts almost 23K bytes off the size of the @command{gawk} executable on GNU/Linux x86_64 systems. Results on other systems and with other compilers are likely to vary. Using this option may bring you some slight performance improvement. +@quotation CAUTION Using this option will cause some of the tests in the test suite to fail. This option may be removed at a later date. +@end quotation @cindex @option{--disable-nls} configuration option @cindex configuration option, @code{--disable-nls} @@ -37544,10 +37583,10 @@ running MS-DOS, any version of MS-Windows, or OS/2. running MS-DOS and any version of MS-Windows. @end ifset In this @value{SECTION}, the term ``Windows32'' -refers to any of Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7/8. +refers to any of Microsoft Windows 95/98/ME/NT/2000/XP/Vista/7/8. The limitations of MS-DOS (and MS-DOS shells under the other operating -systems) has meant that various ``DOS extenders'' are often used with +systems) have meant that various ``DOS extenders'' are often used with programs such as @command{gawk}. The varying capabilities of Microsoft Windows 3.1 and Windows32 can add to the confusion. For an overview of the considerations, refer to @file{README_d/README.pc} in @@ -37806,7 +37845,7 @@ Under MS-Windows, OS/2 and MS-DOS, Under MS-Windows and MS-DOS, @end ifset @command{gawk} (and many other text programs) silently -translate end-of-line @samp{\r\n} to @samp{\n} on input and @samp{\n} +translates end-of-line @samp{\r\n} to @samp{\n} on input and @samp{\n} to @samp{\r\n} on output. A special @code{BINMODE} variable @value{COMMONEXT} allows control over these translations and is interpreted as follows: @@ -37840,7 +37879,7 @@ Setting @code{BINMODE} for standard input or standard output is accomplished by using an appropriate @samp{-v BINMODE=@var{N}} option on the command line. @code{BINMODE} is set at the time a file or pipe is opened and cannot be -changed mid-stream. +changed midstream. The name @code{BINMODE} was chosen to match @command{mawk} (@pxref{Other Versions}). @@ -37896,8 +37935,8 @@ moved into the @code{BEGIN} rule. @command{gawk} can be built and used ``out of the box'' under MS-Windows if you are using the @uref{http://www.cygwin.com, Cygwin environment}. -This environment provides an excellent simulation of GNU/Linux, using the -GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, +This environment provides an excellent simulation of GNU/Linux, using +Bash, GCC, GNU Make, and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: @@ -37916,7 +37955,7 @@ and then the @samp{make} proceeds as usual. @appendixsubsubsec Using @command{gawk} In The MSYS Environment In the MSYS environment under MS-Windows, @command{gawk} automatically -uses binary mode for reading and writing files. Thus there is no +uses binary mode for reading and writing files. Thus, there is no need to use the @code{BINMODE} variable. This can cause problems with other Unix-like components that have @@ -37980,7 +38019,7 @@ With ODS-5 volumes and extended parsing enabled, the case of the target parameter may need to be exact. @command{gawk} has been tested under VAX/VMS 7.3 and Alpha/VMS 7.3-1 -using Compaq C V6.4, and Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3. +using Compaq C V6.4, and under Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3. The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both Alpha and IA64 VMS 8.4 used HP C 7.3.@footnote{The IA64 architecture is also known as ``Itanium.''} @@ -38028,7 +38067,7 @@ For VAX: /name=(as_is,short) @end example -Compile time macros need to be defined before the first VMS-supplied +Compile-time macros need to be defined before the first VMS-supplied header file is included, as follows: @example @@ -38075,7 +38114,7 @@ If your @command{gawk} was installed by a PCSI kit into the @file{GNV$GNU:[vms_help]gawk.hlp}. The PCSI kit also installs a @file{GNV$GNU:[vms_bin]gawk_verb.cld} file -which can be used to add @command{gawk} and @command{awk} as DCL commands. +that can be used to add @command{gawk} and @command{awk} as DCL commands. For just the current process you can use: @@ -38084,7 +38123,7 @@ $ @kbd{set command gnv$gnu:[vms_bin]gawk_verb.cld} @end example Or the system manager can use @file{GNV$GNU:[vms_bin]gawk_verb.cld} to -add the @command{gawk} and @command{awk} to the system wide @samp{DCLTABLES}. +add the @command{gawk} and @command{awk} to the system-wide @samp{DCLTABLES}. The DCL syntax is documented in the @file{gawk.hlp} file. @@ -38150,14 +38189,14 @@ The @code{exit} value is a Unix-style value and is encoded into a VMS exit status value when the program exits. The VMS severity bits will be set based on the @code{exit} value. -A failure is indicated by 1 and VMS sets the @code{ERROR} status. -A fatal error is indicated by 2 and VMS sets the @code{FATAL} status. +A failure is indicated by 1, and VMS sets the @code{ERROR} status. +A fatal error is indicated by 2, and VMS sets the @code{FATAL} status. All other values will have the @code{SUCCESS} status. The exit value is encoded to comply with VMS coding standards and will have the @code{C_FACILITY_NO} of @code{0x350000} with the constant @code{0xA000} added to the number shifted over by 3 bits to make room for the severity codes. -To extract the actual @command{gawk} exit code from the VMS status use: +To extract the actual @command{gawk} exit code from the VMS status, use: @example unix_status = (vms_status .and. &x7f8) / 8 @@ -38176,7 +38215,7 @@ VAX/VMS floating point uses unbiased rounding. @xref{Round Function}. VMS reports time values in GMT unless one of the @code{SYS$TIMEZONE_RULE} or @code{TZ} logical names is set. Older versions of VMS, such as VAX/VMS -7.3 do not set these logical names. +7.3, do not set these logical names. @c @cindex directory search @c @cindex path, search @@ -38194,7 +38233,7 @@ translation and not a multitranslation @code{RMS} searchlist. The VMS GNV package provides a build environment similar to POSIX with ports of a collection of open source tools. The @command{gawk} found in the GNV -base kit is an older port. Currently the GNV project is being reorganized +base kit is an older port. Currently, the GNV project is being reorganized to supply individual PCSI packages for each component. See @w{@uref{https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/}.} @@ -38267,7 +38306,7 @@ recommend compiling and using the current version. @cindex debugging @command{gawk}, bug reports @cindex troubleshooting, @command{gawk}, bug reports If you have problems with @command{gawk} or think that you have found a bug, -report it to the developers; we cannot promise to do anything +report it to the developers; we cannot promise to do anything, but we might well want to fix it. Before reporting a bug, make sure you have really found a genuine bug. @@ -38277,7 +38316,7 @@ to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible @command{awk} program and input @value{DF} that -reproduces the problem. Then send us the program and @value{DF}, +reproduce the problem. Then send us the program and @value{DF}, some idea of what kind of Unix system you're using, the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps @@ -38292,7 +38331,7 @@ You can get this information with the command @samp{gawk --version}. Once you have a precise problem description, send email to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. -The @command{gawk} maintainers subscribe to this address and +The @command{gawk} maintainers subscribe to this address, and thus they will receive your bug report. Although you can send mail to the maintainers directly, the bug reporting address is preferred because the @@ -38319,8 +38358,8 @@ bug reporting system, you should also send a copy to This is for two reasons. First, although some distributions forward bug reports ``upstream'' to the GNU mailing list, many don't, so there is a good chance that the @command{gawk} maintainers won't even see the bug report! Second, -mail to the GNU list is archived, and having everything at the GNU project -keeps things self-contained and not dependant on other organizations. +mail to the GNU list is archived, and having everything at the GNU Project +keeps things self-contained and not dependent on other organizations. @end quotation Non-bug suggestions are always welcome as well. If you have questions @@ -38329,7 +38368,7 @@ features, ask on the bug list; we will try to help you out if we can. If you find bugs in one of the non-Unix ports of @command{gawk}, send an email to the bug list, with a copy to the -person who maintains that port. They are named in the following list, +person who maintains that port. The maintainers are named in the following list, as well as in the @file{README} file in the @command{gawk} distribution. Information in the @file{README} file should be considered authoritative if it conflicts with this @value{DOCUMENT}. @@ -38344,19 +38383,19 @@ The people maintaining the various @command{gawk} ports are: @cindex Robbins, Arnold @cindex Zaretskii, Eli @multitable {MS-Windows with MinGW} {123456789012345678901234567890123456789001234567890} -@item Unix and POSIX systems @tab Arnold Robbins, @EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. +@item Unix and POSIX systems @tab Arnold Robbins, @EMAIL{arnold@@skeeve.com,arnold at skeeve dot com} -@item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. +@item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net} -@item MS-Windows with MinGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. +@item MS-Windows with MinGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org} @c Leave this in the print version on purpose. @c OS/2 is not mentioned anywhere else in the print version though. -@item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. +@item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de} -@item VMS @tab John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. +@item VMS @tab John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net} -@item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. +@item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com} @end multitable If your bug is also reproducible under Unix, send a copy of your @@ -38375,7 +38414,7 @@ Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) @cindex Brennan, Michael @ifnotdocbook @quotation -@i{It's kind of fun to put comments like this in your awk code.}@* +@i{It's kind of fun to put comments like this in your awk code:}@* @ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course} @author Michael Brennan @end quotation @@ -38416,7 +38455,7 @@ It is available in several archive formats: @end table @cindex @command{git} utility -You can also retrieve it from Git Hub: +You can also retrieve it from GitHub: @example git clone git://github.com/onetrueawk/awk bwkawk @@ -38476,7 +38515,7 @@ for a list of extensions in @command{mawk} that are not in POSIX @command{awk}. @item @command{awka} Written by Andrew Sumner, @command{awka} translates @command{awk} programs into C, compiles them, -and links them with a library of functions that provides the core +and links them with a library of functions that provide the core @command{awk} functionality. It also has a number of extensions. @@ -38497,17 +38536,17 @@ since approximately 2001. Nelson H.F.@: Beebe at the University of Utah has modified BWK @command{awk} to provide timing and profiling information. It is different from @command{gawk} with the @option{--profile} option -(@pxref{Profiling}), +(@pxref{Profiling}) in that it uses CPU-based profiling, not line-count profiling. You may find it at either @uref{ftp://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz} or @uref{http://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz}. -@item Busybox Awk -@cindex Busybox Awk -@cindex source code, Busybox Awk -Busybox is a GPL-licensed program providing small versions of many +@item BusyBox @command{awk} +@cindex BusyBox Awk +@cindex source code, BusyBox Awk +BusyBox is a GPL-licensed program providing small versions of many applications within a single executable. It is aimed at embedded systems. It includes a full implementation of POSIX @command{awk}. When building it, be careful not to do @samp{make install} as it will overwrite @@ -38519,7 +38558,7 @@ information, see the @uref{http://busybox.net, project's home page}. @cindex source code, Solaris @command{awk} @item The OpenSolaris POSIX @command{awk} The versions of @command{awk} in @file{/usr/xpg4/bin} and -@file{/usr/xpg6/bin} on Solaris are more-or-less POSIX-compliant. +@file{/usr/xpg6/bin} on Solaris are more or less POSIX-compliant. They are based on the @command{awk} from Mortice Kern Systems for PCs. We were able to make this code compile and work under GNU/Linux with 1--2 hours of work. Making it more generally portable (using @@ -38560,9 +38599,9 @@ features to Python. See @uref{https://github.com/alecthomas/pawk} for more information. (This is not related to Nelson Beebe's modified version of BWK @command{awk}, described earlier.) -@item @w{QSE Awk} -@cindex QSE Awk -@cindex source code, QSE Awk +@item @w{QSE @command{awk}} +@cindex QSE @command{awk} +@cindex source code, QSE @command{awk} This is an embeddable @command{awk} interpreter. For more information, see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}. @@ -38581,7 +38620,7 @@ since approximately 2008. @item Other versions See also the ``Versions and implementations'' section of the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, -Wikipedia article} for information on additional versions. +Wikipedia article} on @command{awk} for information on additional versions. @end table @@ -38590,7 +38629,7 @@ Wikipedia article} for information on additional versions. @itemize @value{BULLET} @item -The @command{gawk} distribution is available from GNU project's main +The @command{gawk} distribution is available from the GNU Project's main distribution site, @code{ftp.gnu.org}. The canonical build recipe is: @example @@ -38602,22 +38641,22 @@ cd gawk-@value{VERSION}.@value{PATCHLEVEL} @item @command{gawk} may be built on non-POSIX systems as well. The currently -supported systems are MS-Windows using DJGPP, MSYS, MinGW and Cygwin, +supported systems are MS-Windows using DJGPP, MSYS, MinGW, and Cygwin, @ifclear FOR_PRINT OS/2 using EMX, @end ifclear and both Vax/VMS and OpenVMS. -Instructions for each system are included in this @value{CHAPTER}. +Instructions for each system are included in this @value{APPENDIX}. @item Bug reports should be sent via email to @email{bug-gawk@@gnu.org}. -Bug reports should be in English, and should include the version of @command{gawk}, -how it was compiled, and a short program and @value{DF} which demonstrate +Bug reports should be in English and should include the version of @command{gawk}, +how it was compiled, and a short program and @value{DF} that demonstrate the problem. @item There are a number of other freely available @command{awk} -implementations. Many are POSIX compliant; others are less so. +implementations. Many are POSIX-compliant; others are less so. @end itemize diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 0e100f69..1e3a7c83 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -1296,7 +1296,7 @@ October 2014 <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> <affiliation><jobtitle>Israel</jobtitle></affiliation> </author> - <date>December 2014</date> + <date>February 2015</date> </prefaceinfo> @end docbook @@ -2252,14 +2252,14 @@ which they raised and educated me. Finally, I also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities. -@iftex +@ifnotdocbook @sp 2 @noindent Arnold Robbins @* Nof Ayalon @* Israel @* -December 2014 -@end iftex +February 2015 +@end ifnotdocbook @ifnotinfo @part @value{PART1}The @command{awk} Language @@ -12495,6 +12495,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as +A regexp constant as a pattern is also a special case of an expression pattern. The expression @code{/li/} has the value one if @samp{li} appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @@ -27060,7 +27061,7 @@ a requirement. @cindex localization @dfn{Internationalization} means writing (or modifying) a program once, in such a way that it can use multiple languages without requiring -further source-code changes. +further source code changes. @dfn{Localization} means providing the data necessary for an internationalized program to work in a particular language. Most typically, these terms refer to features such as the language @@ -27075,7 +27076,7 @@ monetary values are printed and read. @cindex @command{gettext} library @command{gawk} uses GNU @command{gettext} to provide its internationalization features. -The facilities in GNU @command{gettext} focus on messages; strings printed +The facilities in GNU @command{gettext} focus on messages: strings printed by a program, either directly or via formatting with @code{printf} or @code{sprintf()}.@footnote{For some operating systems, the @command{gawk} port doesn't support GNU @command{gettext}. @@ -27266,7 +27267,7 @@ All of the above. (Not too useful in the context of @command{gettext}.) @section Internationalizing @command{awk} Programs @cindex @command{awk} programs, internationalizing -@command{gawk} provides the following variables and functions for +@command{gawk} provides the following variables for internationalization: @table @code @@ -27282,7 +27283,12 @@ value is @code{"messages"}. String constants marked with a leading underscore are candidates for translation at runtime. String constants without a leading underscore are not translated. +@end table + +@command{gawk} provides the following functions for +internationalization: +@table @code @cindexgawkfunc{dcgettext} @item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category}]]@code{)} Return the translation of @var{string} in @@ -27339,15 +27345,7 @@ If @var{directory} is the null string (@code{""}), then given @var{domain}. @end table -To use these facilities in your @command{awk} program, follow the steps -outlined in -@ifnotinfo -the previous @value{SECTION}, -@end ifnotinfo -@ifinfo -@ref{Explaining gettext}, -@end ifinfo -like so: +To use these facilities in your @command{awk} program, follow these steps: @enumerate @cindex @code{BEGIN} pattern, @code{TEXTDOMAIN} variable and @@ -27630,7 +27628,7 @@ the null string (@code{""}) as its value, leaving the original string constant a the result. @item -By defining ``dummy'' functions to replace @code{dcgettext()}, @code{dcngettext()} +By defining ``dummy'' functions to replace @code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()}, the @command{awk} program can be made to run, but all the messages are output in the original language. For example: @@ -27814,11 +27812,11 @@ using the GNU @command{gettext} package. (GNU @command{gettext} is described in complete detail in @ifinfo -@inforef{Top, , GNU @command{gettext} utilities, gettext, GNU gettext tools}.) +@inforef{Top, , GNU @command{gettext} utilities, gettext, GNU @command{gettext} utilities}.) @end ifinfo @ifnotinfo @uref{http://www.gnu.org/software/gettext/manual/, -@cite{GNU gettext tools}}.) +@cite{GNU @command{gettext} utilities}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is @uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.4.tar.gz, @@ -27834,7 +27832,7 @@ and fatal errors in the local language. @itemize @value{BULLET} @item Internationalization means writing a program such that it can use multiple -languages without requiring source-code changes. Localization means +languages without requiring source code changes. Localization means providing the data necessary for an internationalized program to work in a particular language. @@ -27851,9 +27849,9 @@ file, and the @file{.po} files are compiled into @file{.gmo} files for use at runtime. @item -You can use position specifications with @code{sprintf()} and +You can use positional specifications with @code{sprintf()} and @code{printf} to rearrange the placement of argument values in formatted -strings and output. This is useful for the translations of format +strings and output. This is useful for the translation of format control strings. @item @@ -27909,8 +27907,7 @@ the discussion of debugging in @command{gawk}. @subsection Debugging in General (If you have used debuggers in other languages, you may want to skip -ahead to the next section on the specific features of the @command{gawk} -debugger.) +ahead to @ref{Awk Debugging}.) Of course, a debugging program cannot remove bugs for you, because it has no way of knowing what you or your users consider a ``bug'' versus a @@ -28001,10 +27998,10 @@ and usually find the errant code quite quickly. @end table @node Awk Debugging -@subsection Awk Debugging +@subsection @command{awk} Debugging Debugging an @command{awk} program has some specific aspects that are -not shared with other programming languages. +not shared with programs written in other languages. First of all, the fact that @command{awk} programs usually take input line by line from a file or files and operate on those lines using specific @@ -28020,7 +28017,7 @@ to look at the individual primitive instructions carried out by the higher-level @command{awk} commands. @node Sample Debugging Session -@section Sample Debugging Session +@section Sample @command{gawk} Debugging Session @cindex sample debugging session In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample @@ -28039,8 +28036,8 @@ as our example. @cindex debugger, how to start Starting the debugger is almost exactly like running @command{gawk} normally, -except you have to pass an additional option @option{--debug}, or the -corresponding short option @option{-D}. The file(s) containing the +except you have to pass an additional option, @option{--debug}, or the +corresponding short option, @option{-D}. The file(s) containing the program and any supporting code are given on the command line as arguments to one or more @option{-f} options. (@command{gawk} is not designed to debug command-line programs, only programs contained in files.) @@ -28053,7 +28050,7 @@ $ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile} @noindent where both @file{getopt.awk} and @file{uniq.awk} are in @env{$AWKPATH}. (Experienced users of GDB or similar debuggers should note that -this syntax is slightly different from what they are used to. +this syntax is slightly different from what you are used to. With the @command{gawk} debugger, you give the arguments for running the program in the command line to the debugger rather than as part of the @code{run} command at the debugger prompt.) @@ -28207,10 +28204,10 @@ gawk> @kbd{n} @end example This tells us that @command{gawk} is now ready to execute line 66, which -decides whether to give the lines the special ``field skipping'' treatment +decides whether to give the lines the special ``field-skipping'' treatment indicated by the @option{-1} command-line option. (Notice that we skipped -from where we were before at line 63 to here, because the condition in line 63 -@samp{if (fcount == 0 && charcount == 0)} was false.) +from where we were before, at line 63, to here, because the condition +in line 63, @samp{if (fcount == 0 && charcount == 0)}, was false.) Continuing to step, we now get to the splitting of the current and last records: @@ -28284,7 +28281,7 @@ gawk> @kbd{n} Well, here we are at our error (sorry to spoil the suspense). What we had in mind was to join the fields starting from the second one to make -the virtual record to compare, and if the first field was numbered zero, +the virtual record to compare, and if the first field were numbered zero, this would work. Let's look at what we've got: @example @@ -28293,7 +28290,7 @@ gawk> @kbd{p cline clast} @print{} clast = "awk is a wonderful program!" @end example -Hey, those look pretty familiar! They're just our original, unaltered, +Hey, those look pretty familiar! They're just our original, unaltered input records. A little thinking (the human brain is still the best debugging tool), and we realize that we were off by one! @@ -28343,11 +28340,11 @@ Miscellaneous @end itemize Each of these are discussed in the following subsections. -In the following descriptions, commands which may be abbreviated +In the following descriptions, commands that may be abbreviated show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to -automatically repeat the previous command just by hitting @key{Enter}. +automatically repeat the previous command just by hitting @kbd{Enter}. This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi}, and @code{continue} executed without any argument. @@ -28397,7 +28394,7 @@ Set a breakpoint at entry to (the first instruction of) function @var{function}. @end table -Each breakpoint is assigned a number which can be used to delete it from +Each breakpoint is assigned a number that can be used to delete it from the breakpoint list using the @code{delete} command. With a breakpoint, you may also supply a condition. This is an @@ -28449,7 +28446,7 @@ watchpoint is made unconditional). @cindex breakpoint, delete by number @item @code{delete} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{d} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] -Delete specified breakpoints or a range of breakpoints. Deletes +Delete specified breakpoints or a range of breakpoints. Delete all defined breakpoints if no argument is supplied. @cindex debugger commands, @code{disable} @@ -28458,7 +28455,7 @@ all defined breakpoints if no argument is supplied. @cindex breakpoint, how to disable or enable @item @code{disable} [@var{n1 n2} @dots{} | @var{n}--@var{m}] Disable specified breakpoints or a range of breakpoints. Without -any argument, disables all breakpoints. +any argument, disable all breakpoints. @cindex debugger commands, @code{e} (@code{enable}) @cindex debugger commands, @code{enable} @@ -28468,18 +28465,18 @@ any argument, disables all breakpoints. @item @code{enable} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{e} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] Enable specified breakpoints or a range of breakpoints. Without -any argument, enables all breakpoints. -Optionally, you can specify how to enable the breakpoint: +any argument, enable all breakpoints. +Optionally, you can specify how to enable the breakpoints: @c nested table @table @code @item del -Enable the breakpoint(s) temporarily, then delete it when -the program stops at the breakpoint. +Enable the breakpoints temporarily, then delete each one when +the program stops at it. @item once -Enable the breakpoint(s) temporarily, then disable it when -the program stops at the breakpoint. +Enable the breakpoints temporarily, then disable each one when +the program stops at it. @end table @cindex debugger commands, @code{ignore} @@ -28547,7 +28544,7 @@ gawk> @item @code{continue} [@var{count}] @itemx @code{c} [@var{count}] Resume program execution. If continued from a breakpoint and @var{count} is -specified, ignores the breakpoint at that location the next @var{count} times +specified, ignore the breakpoint at that location the next @var{count} times before stopping. @cindex debugger commands, @code{finish} @@ -28601,7 +28598,7 @@ automatic display variables, and debugger options. @item @code{step} [@var{count}] @itemx @code{s} [@var{count}] Continue execution until control reaches a different source line in the -current stack frame. @code{step} steps inside any function called within +current stack frame, stepping inside any function called within the line. If the argument @var{count} is supplied, steps that many times before stopping, unless it encounters a breakpoint or watchpoint. @@ -28714,7 +28711,7 @@ or field. String values must be enclosed between double quotes (@code{"}@dots{}@code{"}). You can also set special @command{awk} variables, such as @code{FS}, -@code{NF}, @code{NR}, and son on. +@code{NF}, @code{NR}, and so on. @cindex debugger commands, @code{w} (@code{watch}) @cindex debugger commands, @code{watch} @@ -28726,7 +28723,7 @@ You can also set special @command{awk} variables, such as @code{FS}, Add variable @var{var} (or field @code{$@var{n}}) to the watch list. The debugger then stops whenever the value of the variable or field changes. Each watched item is assigned a -number which can be used to delete it from the watch list using the +number that can be used to delete it from the watch list using the @code{unwatch} command. With a watchpoint, you may also supply a condition. This is an @@ -28754,11 +28751,11 @@ watch list. @node Execution Stack @subsection Working with the Stack -Whenever you run a program which contains any function calls, +Whenever you run a program that contains any function calls, @command{gawk} maintains a stack of all of the function calls leading up to where the program is right now. You can see how you got to where you are, and also move around in the stack to see what the state of things was in the -functions which called the one you are in. The commands for doing this are: +functions that called the one you are in. The commands for doing this are: @table @asis @cindex debugger commands, @code{bt} (@code{backtrace}) @@ -28793,8 +28790,8 @@ Then select and print the frame. @item @code{frame} [@var{n}] @itemx @code{f} [@var{n}] Select and print stack frame @var{n}. Frame 0 is the currently executing, -or @dfn{innermost}, frame (function call), frame 1 is the frame that -called the innermost one. The highest numbered frame is the one for the +or @dfn{innermost}, frame (function call); frame 1 is the frame that +called the innermost one. The highest-numbered frame is the one for the main program. The printed information consists of the frame number, function and argument names, source file, and the source line. @@ -28810,7 +28807,7 @@ Then select and print the frame. Besides looking at the values of variables, there is often a need to get other sorts of information about the state of your program and of the -debugging environment itself. The @command{gawk} debugger has one command which +debugging environment itself. The @command{gawk} debugger has one command that provides this information, appropriately called @code{info}. @code{info} is used with one of a number of arguments that tell it exactly what you want to know: @@ -28898,12 +28895,12 @@ The available options are: @table @asis @item @code{history_size} @cindex debugger history size -The maximum number of lines to keep in the history file @file{./.gawk_history}. -The default is 100. +Set the maximum number of lines to keep in the history file +@file{./.gawk_history}. The default is 100. @item @code{listsize} @cindex debugger default list amount -The number of lines that @code{list} prints. The default is 15. +Specify the number of lines that @code{list} prints. The default is 15. @item @code{outfile} @cindex redirect @command{gawk} output, in debugger @@ -28913,7 +28910,7 @@ standard output. @item @code{prompt} @cindex debugger prompt -The debugger prompt. The default is @samp{@w{gawk> }}. +Change the debugger prompt. The default is @samp{@w{gawk> }}. @item @code{save_history} [@code{on} | @code{off}] @cindex debugger history file @@ -28924,7 +28921,7 @@ The default is @code{on}. @cindex save debugger options Save current options to file @file{./.gawkrc} upon exit. The default is @code{on}. -Options are read back in to the next session upon startup. +Options are read back into the next session upon startup. @item @code{trace} [@code{on} | @code{off}] @cindex instruction tracing, in debugger @@ -28947,7 +28944,7 @@ command in the file. Also, the list of commands may include additional @code{source} commands; however, the @command{gawk} debugger will not source the same file more than once in order to avoid infinite recursion. -In addition to, or instead of the @code{source} command, you can use +In addition to, or instead of, the @code{source} command, you can use the @option{-D @var{file}} or @option{--debug=@var{file}} command-line options to execute commands from a file non-interactively (@pxref{Options}). @@ -28956,16 +28953,16 @@ options to execute commands from a file non-interactively @node Miscellaneous Debugger Commands @subsection Miscellaneous Commands -There are a few more commands which do not fit into the +There are a few more commands that do not fit into the previous categories, as follows: @table @asis @cindex debugger commands, @code{dump} @cindex @code{dump} debugger command @item @code{dump} [@var{filename}] -Dump bytecode of the program to standard output or to the file +Dump byte code of the program to standard output or to the file named in @var{filename}. This prints a representation of the internal -instructions which @command{gawk} executes to implement the @command{awk} +instructions that @command{gawk} executes to implement the @command{awk} commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (@pxref{Signature Program}) demonstrates: @@ -29062,7 +29059,7 @@ Print lines centered around line number @var{n} in source file @var{filename}. This command may change the current source file. @item @var{function} -Print lines centered around beginning of the +Print lines centered around the beginning of the function @var{function}. This command may change the current source file. @end table @@ -29074,16 +29071,16 @@ function @var{function}. This command may change the current source file. @item @code{quit} @itemx @code{q} Exit the debugger. Debugging is great fun, but sometimes we all have -to tend to other obligations in life, and sometimes we find the bug, +to tend to other obligations in life, and sometimes we find the bug and are free to go on to the next one! As we saw earlier, if you are -running a program, the debugger warns you if you accidentally type +running a program, the debugger warns you when you type @samp{q} or @samp{quit}, to make sure you really want to quit. @cindex debugger commands, @code{trace} @cindex @code{trace} debugger command @item @code{trace} [@code{on} | @code{off}] -Turn on or off a continuous printing of instructions which are about to -be executed, along with printing the @command{awk} line which they +Turn on or off continuous printing of the instructions that are about to +be executed, along with the @command{awk} lines they implement. The default is @code{off}. It is to be hoped that most of the ``opcodes'' in these instructions are @@ -29099,7 +29096,7 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while If @command{gawk} is compiled with @uref{http://cnswww.cns.cwru.edu/php/chet/readline/readline.html, -the @code{readline} library}, you can take advantage of that library's +the GNU Readline library}, you can take advantage of that library's command completion and history expansion features. The following types of completion are available: @@ -29136,7 +29133,7 @@ and We hope you find the @command{gawk} debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has -some limitations. A few which are worth being aware of are: +some limitations. A few that it's worth being aware of are: @itemize @value{BULLET} @item @@ -29152,13 +29149,13 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands} (or if you are already familiar with @command{gawk} internals), you will realize that much of the internal manipulation of data in @command{gawk}, as in many interpreters, is done on a stack. -@code{Op_push}, @code{Op_pop}, and the like, are the ``bread and butter'' of +@code{Op_push}, @code{Op_pop}, and the like are the ``bread and butter'' of most @command{gawk} code. Unfortunately, as of now, the @command{gawk} debugger does not allow you to examine the stack's contents. That is, the intermediate results of expression evaluation are on the -stack, but cannot be printed. Rather, only variables which are defined +stack, but cannot be printed. Rather, only variables that are defined in the program can be printed. Of course, a workaround for this is to use more explicit variables at the debugging stage and then change back to obscure, perhaps more optimal code later. @@ -29172,12 +29169,12 @@ programmer, you are expected to know the meaning of @item The @command{gawk} debugger is designed to be used by running a program (with all its parameters) on the command line, as described in @ref{Debugger Invocation}. -There is no way (as of now) to attach or ``break in'' to a running program. -This seems reasonable for a language which is used mainly for quickly +There is no way (as of now) to attach or ``break into'' a running program. +This seems reasonable for a language that is used mainly for quickly executing, short programs. @item -The @command{gawk} debugger only accepts source supplied with the @option{-f} option. +The @command{gawk} debugger only accepts source code supplied with the @option{-f} option. @end itemize @ignore @@ -29191,8 +29188,8 @@ be added, and of course feel free to try to add them yourself! @itemize @value{BULLET} @item Programs rarely work correctly the first time. Finding bugs -is @dfn{debugging} and a program that helps you find bugs is a -@dfn{debugger}. @command{gawk} has a built-in debugger that works very +is called debugging, and a program that helps you find bugs is a +debugger. @command{gawk} has a built-in debugger that works very similarly to the GNU Debugger, GDB. @item @@ -29212,7 +29209,7 @@ breakpoints, execution, viewing and changing data, working with the stack, getting information, and other tasks. @item -If the @code{readline} library is available when @command{gawk} is +If the GNU Readline library is available when @command{gawk} is compiled, it is used by the debugger to provide command-line history and editing. @@ -29276,7 +29273,7 @@ paper and pencil (and/or a calculator). In theory, numbers can have an arbitrary number of digits on either side (or both sides) of the decimal point, and the results of a computation are always exact. -Some modern system can do decimal arithmetic in hardware, but usually you +Some modern systems can do decimal arithmetic in hardware, but usually you need a special software library to provide access to these instructions. There are also libraries that do decimal arithmetic entirely in software. @@ -29332,8 +29329,34 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615 -@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} -@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} +@iftex +@item Single-precision floating point (approximate) @tab @math{1.175494^{-38}} @tab @math{3.402823^{38}} +@item Double-precision floating point (approximate) @tab @math{2.225074^{-308}} @tab @math{1.797693^{308}} +@end iftex +@ifnottex +@ifnotdocbook +@item Single-precision floating point (approximate) @tab 1.175494e-38 @tab 3.402823e38 +@item Double-precision floating point (approximate) @tab 2.225074e-308 @tab 1.797693e308 +@end ifnotdocbook +@end ifnottex +@ifdocbook +@item Single-precision floating point (approximate) @tab +@docbook +1.175494<superscript>-38</superscript> +@end docbook +@tab +@docbook +3.402823<superscript>38</superscript> +@end docbook +@item Double-precision floating point (approximate) @tab +@docbook +2.225074<superscript>-308</superscript> +@end docbook +@tab +@docbook +1.797693<superscript>308</superscript> +@end docbook +@end ifdocbook @end multitable @end float @@ -29342,7 +29365,7 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. The rest of this @value{CHAPTER} uses a number of terms. Here are some informal definitions that should help you work your way through the material -here. +here: @table @dfn @item Accuracy @@ -29363,7 +29386,7 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.''@footnote{Thanks to Michael Brennan for this description, +``Not a number.''@footnote{Thanks to Michael Brennan for this description, which we 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, @@ -29406,8 +29429,8 @@ formula: @end display @noindent -Here, @var{prec} denotes the binary precision -(measured in bits) and @var{dps} (short for decimal places) +Here, @emph{prec} denotes the binary precision +(measured in bits) and @emph{dps} (short for decimal places) is the decimal digits. @item Rounding mode @@ -29415,7 +29438,7 @@ How numbers are rounded up or down when necessary. More details are provided later. @item Significand -A floating-point value consists the significand multiplied by 10 +A floating-point value consists of the significand multiplied by 10 to the power of the exponent. For example, in @code{1.2345e67}, the significand is @code{1.2345}. @@ -29439,7 +29462,7 @@ to allow greater precisions and larger exponent ranges. (@command{awk} uses only the 64-bit double-precision format.) @ref{table-ieee-formats} lists the precision and exponent -field values for the basic IEEE 754 binary formats: +field values for the basic IEEE 754 binary formats. @float Table,table-ieee-formats @caption{Basic IEEE format values} @@ -29503,12 +29526,12 @@ for more information. @author Teen Talk Barbie, July 1992 @end quotation -This @value{SECTION} provides a high level overview of the issues +This @value{SECTION} provides a high-level overview of the issues involved when doing lots of floating-point arithmetic.@footnote{There is a very nice @uref{http://www.validlab.com/goldberg/paper.pdf, paper on floating-point arithmetic} by David Goldberg, ``What Every -Computer Scientist Should Know About Floating-point Arithmetic,'' -@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), 5-48. This is +Computer Scientist Should Know About Floating-Point Arithmetic,'' +@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03): 5-48. This is worth reading if you are interested in the details, but it does require a background in computer science.} The discussion applies to both hardware and arbitrary-precision @@ -29577,7 +29600,7 @@ $ @kbd{gawk 'BEGIN @{ x = 0.875; y = 0.425} Often the error is so small you do not even notice it, and if you do, you can always specify how much precision you would like in your output. -Usually this is a format string like @code{"%.15g"}, which when +Usually this is a format string like @code{"%.15g"}, which, when used in the previous example, produces an output identical to the input. @node Comparing FP Values @@ -29616,7 +29639,7 @@ else The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating-point operations, +value that is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of @value{PI} using one of its many series representations: @@ -29669,7 +29692,7 @@ no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may be important -for your computation. Rounding error, cumulative precision loss +for your computation. Rounding error, cumulative precision loss, and underflow are often troublesome. When @command{gawk} tests the expressions @samp{0.1 + 12.2} and @@ -29709,7 +29732,8 @@ by our earlier attempt to compute the value of @value{PI}. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. -Repeated addition is not necessarily equivalent to multiplication +Additionally, you should understand that +repeated addition is not necessarily equivalent to multiplication in floating-point arithmetic. In the example in @ref{Errors accumulate}: @@ -29772,7 +29796,7 @@ to emulate an IEEE 754 binary format. @float Table,table-predefined-precision-strings @caption{Predefined precision strings for @code{PREC}} @multitable {@code{"double"}} {12345678901234567890123456789012345} -@headitem @code{PREC} @tab IEEE 754 Binary Format +@headitem @code{PREC} @tab IEEE 754 binary format @item @code{"half"} @tab 16-bit half-precision @item @code{"single"} @tab Basic 32-bit single precision @item @code{"double"} @tab Basic 64-bit double precision @@ -29804,7 +29828,6 @@ 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: -@end quotation @example $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'} @@ -29816,22 +29839,23 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'} $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'} @print{} 0.1000000000000000000000000 @end example +@end quotation @node Setting the rounding mode @subsection Setting the Rounding Mode The @code{ROUNDMODE} variable provides -program level control over the rounding mode. +program-level control over the rounding mode. The correspondence between @code{ROUNDMODE} and the IEEE rounding modes is shown in @ref{table-gawk-rounding-modes}. @float Table,table-gawk-rounding-modes @caption{@command{gawk} rounding modes} @multitable @columnfractions .45 .30 .25 -@headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE} +@headitem Rounding mode @tab IEEE name @tab @code{ROUNDMODE} @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"} -@item Round toward plus Infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} -@item Round toward negative Infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} +@item Round toward positive infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} +@item Round toward negative infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} @item Round toward zero @tab @code{roundTowardZero} @tab @code{"Z"} or @code{"z"} @item Round to nearest, ties away from zero @tab @code{roundTiesToAway} @tab @code{"A"} or @code{"a"} @end multitable @@ -29892,8 +29916,8 @@ distributes upward and downward rounds of exact halves, which might cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. -The other rounding modes are rarely used. Round toward positive infinity -(@code{roundTowardPositive}) and round toward negative infinity +The other rounding modes are rarely used. Rounding toward positive infinity +(@code{roundTowardPositive}) and toward negative infinity (@code{roundTowardNegative}) are often used to implement interval arithmetic, where you adjust the rounding mode to calculate upper and lower bounds for the range of output. The @code{roundTowardZero} mode can @@ -29950,17 +29974,17 @@ If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for correct output (using the formula @iftex -@math{prec = 3.322 @cdot dps}), +@math{prec = 3.322 @cdot dps}) would be @math{3.322 @cdot 183231}, @end iftex @ifnottex @ifnotdocbook -@samp{prec = 3.322 * dps}), +@samp{prec = 3.322 * dps}) would be 3.322 x 183231, @end ifnotdocbook @end ifnottex @docbook -<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>), +<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>) would be <emphasis>prec</emphasis> = 3.322 ⋅ 183231, @c @end docbook @@ -29998,7 +30022,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or -want, you can employ a subterfuge, and convert the integer to floating +want, you can employ a subterfuge and convert the integer to floating point first, like this: @example @@ -30135,7 +30159,7 @@ word sizes. See @node POSIX Floating Point Problems @section Standards Versus Existing Practice -Historically, @command{awk} has converted any non-numeric looking string +Historically, @command{awk} has converted any nonnumeric-looking string to the numeric value zero, when required. Furthermore, the original definition of the language and the original POSIX standards specified that @command{awk} only understands decimal numbers (base 10), and not octal @@ -30152,8 +30176,8 @@ notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not} source code constants.) @item -Support for the special IEEE 754 floating-point values ``Not A Number'' -(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf''). +Support for the special IEEE 754 floating-point values ``not a number'' +(NaN), positive infinity (``inf''), and negative infinity (``@minus{}inf''). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}. @@ -30174,21 +30198,21 @@ values is also a very severe departure from historical practice. @end itemize The second problem is that the @command{gawk} maintainer feels that this -interpretation of the standard, which requires a certain amount of +interpretation of the standard, which required a certain amount of ``language lawyering'' to arrive at in the first place, was not even -intended by the standard developers. In other words, ``we see how you +intended by the standard developers. In other words, ``We see how you got where you are, but we don't think that that's where you want to be.'' Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that @command{awk} support hexadecimal floating-point values and -special values for ``Not A Number'' and infinity. +special values for ``not a number'' and infinity. Although the @command{gawk} maintainer continues to feel that providing those features is inadvisable, nevertheless, on systems that support IEEE floating point, it seems -reasonable to provide @emph{some} way to support NaN and Infinity values. +reasonable to provide @emph{some} way to support NaN and infinity values. The solution implemented in @command{gawk} is as follows: @itemize @value{BULLET} @@ -30208,7 +30232,7 @@ $ @kbd{echo 0xDeadBeef | gawk --posix '@{ print $1 + 0 @}'} @end example @item -Without @option{--posix}, @command{gawk} interprets the four strings +Without @option{--posix}, @command{gawk} interprets the four string values @samp{+inf}, @samp{-inf}, @samp{+nan}, @@ -30230,7 +30254,7 @@ $ @kbd{echo 0xDeadBeef | gawk '@{ print $1 + 0 @}'} @end example @command{gawk} ignores case in the four special values. -Thus @samp{+nan} and @samp{+NaN} are the same. +Thus, @samp{+nan} and @samp{+NaN} are the same. @end itemize @node Floating point summary @@ -30243,9 +30267,9 @@ values. Standard @command{awk} uses double-precision floating-point values. @item -In the early 1990s, Barbie mistakenly said ``Math class is tough!'' +In the early 1990s Barbie mistakenly said, ``Math class is tough!'' Although math isn't tough, floating-point arithmetic isn't the same -as pencil and paper math, and care must be taken: +as pencil-and-paper math, and care must be taken: @c nested list @itemize @value{MINUS} @@ -30278,7 +30302,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and @item With @option{-M}, @command{gawk} performs arbitrary-precision integer arithmetic using the GMP library. -This is faster and more space efficient than using MPFR for +This is faster and more space-efficient than using MPFR for the same calculations. @item @@ -30290,7 +30314,7 @@ It pays to be aware of them. Overall, there is no need to be unduly suspicious about the results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and -paper. In order to take advantage of the power of computer floating point, +paper. In order to take advantage of the power of floating-point arithmetic, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the correct number @@ -30351,7 +30375,7 @@ Extensions are useful because they allow you (of course) to extend @command{gawk}'s functionality. For example, they can provide access to system calls (such as @code{chdir()} to change directory) and to other C library routines that could be of use. As with most software, -``the sky is the limit;'' if you can imagine something that you might +``the sky is the limit''; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the @dfn{application programming @@ -30359,7 +30383,7 @@ interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents -the sample extensions included in the @command{gawk} distribution, +the sample extensions included in the @command{gawk} distribution and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @xref{Extension Design}, for a discussion of the extension mechanism @@ -30512,7 +30536,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 @@ -30556,7 +30580,7 @@ This (rather large) @value{SECTION} describes the API in detail. @node Extension API Functions Introduction @subsection Introduction -Access to facilities within @command{gawk} are made available +Access to facilities within @command{gawk} is achieved by calling through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -30584,7 +30608,7 @@ Output wrappers Two-way processors @end itemize -All of these are discussed in detail, later in this @value{CHAPTER}. +All of these are discussed in detail later in this @value{CHAPTER}. @item Printing fatal, warning, and ``lint'' warning messages. @@ -30622,7 +30646,7 @@ Creating a new array Clearing an array @item -Flattening an array for easy C style looping over all its indices and elements +Flattening an array for easy C-style looping over all its indices and elements @end itemize @end itemize @@ -30634,8 +30658,9 @@ The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: +@c FIXME: Make this is a float at some point. @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}} -@headitem C Entity @tab Header File +@headitem C entity @tab Header file @item @code{EOF} @tab @code{<stdio.h>} @item Values for @code{errno} @tab @code{<errno.h>} @item @code{FILE} @tab @code{<stdio.h>} @@ -30661,7 +30686,7 @@ Doing so, however, is poor coding practice. Although the API only uses ISO C 90 features, there is an exception; the ``constructor'' functions use the @code{inline} keyword. If your compiler does not support this keyword, you should either place -@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a +@samp{-Dinline=''} on your command line or use the GNU Autotools and include a @file{config.h} file in your extensions. @item @@ -30669,7 +30694,7 @@ All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} from the extension @emph{must} come from calling one of -@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -30683,7 +30708,7 @@ characters are allowed. By intent, strings are maintained using the current multibyte encoding (as defined by @env{LC_@var{xxx}} environment variables) and not using wide characters. This matches how @command{gawk} stores strings internally -and also how characters are likely to be input and output from files. +and also how characters are likely to be input into and output from files. @end quotation @item @@ -30728,6 +30753,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent @value{SECTION}s, together with the functions that use them. +The general-purpose types and structures are as follows: + @table @code @item typedef void *awk_ext_id_t; A value of this type is received from @command{gawk} when an extension is loaded. @@ -30744,7 +30771,7 @@ while allowing @command{gawk} to use them as it needs to. @itemx @ @ @ @ awk_false = 0, @itemx @ @ @ @ awk_true @itemx @} awk_bool_t; -A simple boolean type. +A simple Boolean type. @item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @@ -30790,7 +30817,7 @@ The @code{val_type} member indicates what kind of value the @itemx #define array_cookie@ @ @ u.a @itemx #define scalar_cookie@ @ u.scl @itemx #define value_cookie@ @ @ u.vc -These macros make accessing the fields of the @code{awk_value_t} more +Using these macros makes accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; @@ -30813,7 +30840,7 @@ indicates what is in the @code{union}. Representing numbers is easy---the API uses a C @code{double}. Strings require more work. Because @command{gawk} allows embedded @sc{nul} bytes in string values, a string must be represented as a pair containing a -data-pointer and length. This is the @code{awk_string_t} type. +data pointer and length. This is the @code{awk_string_t} type. Identifiers (i.e., the names of global variables) can be associated with either scalar values or with arrays. In addition, @command{gawk} @@ -30826,12 +30853,12 @@ of the @code{union} as if they were fields in a @code{struct}; this is a common coding practice in C. Such code is easier to write and to read, but it remains @emph{your} responsibility to make sure that the @code{val_type} member correctly reflects the type of the value in -the @code{awk_value_t}. +the @code{awk_value_t} struct. Conceptually, the first three members of the @code{union} (number, string, and array) are all that is needed for working with @command{awk} values. However, because the API provides routines for accessing and changing -the value of global scalar variables only by using the variable's name, +the value of a global scalar variable only by using the variable's name, there is a performance penalty: @command{gawk} must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -30849,7 +30876,9 @@ See also the entry for ``Cookie'' in the @ref{Glossary}. object for that variable, and then use the cookie for getting the variable's value or for changing the variable's value. -This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro. +The @code{awk_scalar_t} type holds a scalar cookie, and the +@code{scalar_cookie} macro provides access to the value of that type +in the @code{awk_value_t} struct. Given a scalar cookie, @command{gawk} can directly retrieve or modify the value, as required, without having to find it first. @@ -30858,8 +30887,8 @@ If you know that you wish to use the same numeric or string @emph{value} for one or more variables, you can create the value once, retaining a @dfn{value cookie} for it, and then pass in that value cookie whenever you wish to set the value of a -variable. This saves both storage space within the running @command{gawk} -process as well as the time needed to create the value. +variable. This saves storage space within the running @command{gawk} +process and reduces the time needed to create the value. @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @@ -30887,13 +30916,13 @@ be passed to @command{gawk}. @item void gawk_free(void *ptr); Call the correct version of @code{free()} to release storage that was -allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. +allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. @end table The API has to provide these functions because it is possible for an extension to be compiled and linked against a different version of the C library than was used for the @command{gawk} -executable.@footnote{This is more common on MS-Windows systems, but +executable.@footnote{This is more common on MS-Windows systems, but it can happen on Unix-like systems as well.} If @command{gawk} were to use its version of @code{free()} when the memory came from an unrelated version of @code{malloc()}, unexpected behavior would @@ -30903,7 +30932,7 @@ Two convenience macros may be used for allocating storage from @code{gawk_malloc()} and @code{gawk_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were -procedure calls that do not return a value. +procedure calls that do not return a value: @table @code @item #define emalloc(pointer, type, size, message) @dots{} @@ -30940,7 +30969,7 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +This is like @code{emalloc()}, but it calls @code{gawk_realloc()} instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -30965,7 +30994,7 @@ for storage in @code{result}. It returns @code{result}. @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) This function creates a string value in the @code{awk_value_t} variable pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -31016,7 +31045,7 @@ The fields are: @table @code @item const char *name; The name of the new function. -@command{awk} level code calls the function by this name. +@command{awk}-level code calls the function by this name. This is a regular C string. Function names must obey the rules for @command{awk} @@ -31030,7 +31059,7 @@ This is a pointer to the C function that provides the extension's functionality. The function must fill in @code{*result} with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from one of +As mentioned earlier, string memory @emph{must} come from one of @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many @@ -31082,20 +31111,20 @@ The @code{exit_status} parameter is the exit status value that @command{gawk} intends to pass to the @code{exit()} system call. @item arg0 -A pointer to private data which @command{gawk} saves in order to pass to +A pointer to private data that @command{gawk} saves in order to pass to the function pointed to by @code{funcp}. @end table @end table -Exit callback functions are called in last-in-first-out (LIFO) +Exit callback functions are called in last-in, first-out (LIFO) order---that is, in the reverse order in which they are registered with @command{gawk}. @node Extension Version String @subsubsection Registering An Extension Version String -You can register a version string which indicates the name and -version of your extension, with @command{gawk}, as follows: +You can register a version string that indicates the name and +version of your extension with @command{gawk}, as follows: @table @code @item void register_ext_version(const char *version); @@ -31117,7 +31146,7 @@ of @code{RS} to find the end of the record, and then uses @code{FS} Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}). If you want, you can provide your own custom input parser. An input -parser's job is to return a record to the @command{gawk} record processing +parser's job is to return a record to the @command{gawk} record-processing code, along with indicators for the value and length of the data to be used for @code{RT}, if any. @@ -31135,9 +31164,9 @@ It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf); When @command{gawk} decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill -in certain fields in the @code{awk_input_buf_t} structure, and ensure +in certain fields in the @code{awk_input_buf_t} structure and ensure that certain conditions are true. It should then return true. If an -error of some kind occurs, it should not fill in any fields, and should +error of some kind occurs, it should not fill in any fields and should return false; then @command{gawk} will not use the input parser. The details are presented shortly. @end table @@ -31230,7 +31259,7 @@ in the @code{struct stat}, or any combination of these factors. Once @code{@var{XXX}_can_take_file()} has returned true, and @command{gawk} has decided to use your input parser, it calls -@code{@var{XXX}_take_control_of()}. That function then fills one of +@code{@var{XXX}_take_control_of()}. That function then fills either the @code{get_record} field or the @code{read_func} field in the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not} set to @code{INVALID_HANDLE}. The following list describes the fields that @@ -31252,21 +31281,21 @@ records. Said function is the core of the input parser. Its behavior is described in the text following this list. @item ssize_t (*read_func)(); -This function pointer should point to function that has the +This function pointer should point to a function that has the same behavior as the standard POSIX @code{read()} system call. It is an alternative to the @code{get_record} pointer. Its behavior is also described in the text following this list. @item void (*close_func)(struct awk_input *iobuf); This function pointer should point to a function that does -the ``tear down.'' It should release any resources allocated by +the ``teardown.'' It should release any resources allocated by @code{@var{XXX}_take_control_of()}. It may also close the file. If it does so, it should set the @code{fd} field to @code{INVALID_HANDLE}. If @code{fd} is still not @code{INVALID_HANDLE} after the call to this function, @command{gawk} calls the regular @code{close()} system call. -Having a ``tear down'' function is optional. If your input parser does +Having a ``teardown'' function is optional. If your input parser does not need it, do not set this field. Then, @command{gawk} calls the regular @code{close()} system call on the file descriptor, so it should be valid. @@ -31277,7 +31306,7 @@ input records. The parameters are as follows: @table @code @item char **out -This is a pointer to a @code{char *} variable which is set to point +This is a pointer to a @code{char *} variable that is set to point to the record. @command{gawk} makes its own copy of the data, so the extension must manage this storage. @@ -31330,17 +31359,17 @@ set this field explicitly. You must choose one method or the other: either a function that returns a record, or one that returns raw data. In particular, if you supply a function to get a record, @command{gawk} will -call it, and never call the raw read function. +call it, and will never call the raw read function. @end quotation @command{gawk} ships with a sample extension that reads directories, -returning records for each entry in the directory (@pxref{Extension +returning records for each entry in a directory (@pxref{Extension Sample Readdir}). You may wish to use that code as a guide for writing your own input parser. When writing an input parser, you should think about (and document) how it is expected to interact with @command{awk} code. You may want -it to always be called, and take effect as appropriate (as the +it to always be called, and to take effect as appropriate (as the @code{readdir} extension does). Or you may want it to take effect based upon the value of an @command{awk} variable, as the XML extension from the @code{gawkextlib} project does (@pxref{gawkextlib}). @@ -31450,7 +31479,7 @@ a pointer to any private data associated with the file. These pointers should be set to point to functions that perform the equivalent function as the @code{<stdio.h>} functions do, if appropriate. @command{gawk} uses these function pointers for all output. -@command{gawk} initializes the pointers to point to internal, ``pass through'' +@command{gawk} initializes the pointers to point to internal ``pass-through'' functions that just call the regular @code{<stdio.h>} functions, so an extension only needs to redefine those functions that are appropriate for what it does. @@ -31461,7 +31490,7 @@ upon the @code{name} and @code{mode} fields, and any additional state (such as @command{awk} variable values) that is appropriate. When @command{gawk} calls @code{@var{XXX}_take_control_of()}, that function should fill -in the other fields, as appropriate, except for @code{fp}, which it should just +in the other fields as appropriate, except for @code{fp}, which it should just use normally. You register your output wrapper with the following function: @@ -31501,14 +31530,14 @@ The fields are as follows: The name of the two-way processor. @item awk_bool_t (*can_take_two_way)(const char *name); -This function returns true if it wants to take over two-way I/O for this @value{FN}. +The function pointed to by this field should return true if it wants to take over two-way I/O for this @value{FN}. It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t (*take_control_of)(const char *name, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_input_buf_t *inbuf, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_output_buf_t *outbuf); -This function should fill in the @code{awk_input_buf_t} and +The function pointed to by this field should fill in the @code{awk_input_buf_t} and @code{awk_outut_buf_t} structures pointed to by @code{inbuf} and @code{outbuf}, respectively. These structures were described earlier. @@ -31537,7 +31566,7 @@ Register the two-way processor pointed to by @code{two_way_processor} with You can print different kinds of warning messages from your extension, as described here. Note that for these functions, -you must pass in the extension id received from @command{gawk} +you must pass in the extension ID received from @command{gawk} when the extension was loaded:@footnote{Because the API uses only ISO C 90 features, it cannot make use of the ISO C 99 variadic macro feature to hide that parameter. More's the pity.} @@ -31590,7 +31619,7 @@ matches what you requested, the function returns true and fills in the @code{awk_value_t} result. Otherwise, the function returns false, and the @code{val_type} member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual +print an error message or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. @@ -31623,32 +31652,32 @@ value type, as appropriate. This behavior is summarized in <entry><para><emphasis role="bold">String</emphasis></para></entry> <entry><para>String</para></entry> <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> <entry><para><emphasis role="bold">Number</emphasis></para></entry> <entry><para>Number if can be converted, else false</para></entry> <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Type</emphasis></para></entry> <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> <entry><para>Array</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Requested</emphasis></para></entry> <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> <entry><para>Scalar</para></entry> <entry><para>Scalar</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> @@ -31660,11 +31689,11 @@ value type, as appropriate. This behavior is summarized in </row> <row> <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> + <entry><para><emphasis role="bold">Value cookie</emphasis></para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para> + </entry><entry><para>False</para></entry> </row> </tbody> </tgroup> @@ -31682,12 +31711,12 @@ value type, as appropriate. This behavior is summarized in @end tex @multitable @columnfractions .166 .166 .198 .15 .15 .166 @headitem @tab @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{String} @tab String @tab String @tab false @tab false -@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false -@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @tab @b{String} @tab String @tab String @tab False @tab False +@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab False @tab False +@item @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab False +@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab False @tab False @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false +@item @tab @b{Value cookie} @tab False @tab False @tab False @tab False @end multitable @end ifnotdocbook @end ifnotplaintext @@ -31698,21 +31727,21 @@ value type, as appropriate. This behavior is summarized in +------------+------------+-----------+-----------+ | String | Number | Array | Undefined | +-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | +| | String | String | String | False | False | | |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | +| | Number | Number if | Number | False | False | | | | can be | | | | | | | converted, | | | | | | | else false | | | | | |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | +| Type | Array | False | False | Array | False | | Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | +| | Scalar | Scalar | Scalar | False | False | | |-----------+------------+------------+-----------+-----------+ | | Undefined | String | Number | Array | Undefined | | |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | +| | Value | False | False | False | False | +| | cookie | | | | | +-----------+-----------+------------+------------+-----------+-----------+ @end example @end ifplaintext @@ -31729,16 +31758,16 @@ passed to your extension function. They are: @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Fill in the @code{awk_value_t} structure pointed to by @code{result} -with the @code{count}'th argument. Return true if the actual -type matches @code{wanted}, false otherwise. In the latter +with the @code{count}th argument. Return true if the actual +type matches @code{wanted}, and false otherwise. In the latter case, @code{result@w{->}val_type} indicates the actual type -(@pxref{table-value-types-returned}). Counts are zero based---the first +(@pxref{table-value-types-returned}). Counts are zero-based---the first argument is numbered zero, the second one, and so on. @code{wanted} indicates the type of value expected. @item awk_bool_t set_argument(size_t count, awk_array_t array); Convert a parameter that was undefined into an array; this provides -call-by-reference for arrays. Return false if @code{count} is too big, +call by reference for arrays. Return false if @code{count} is too big, or if the argument's type is not undefined. @DBXREF{Array Manipulation} for more information on creating arrays. @end table @@ -31762,8 +31791,9 @@ allows you to create and release cached values. The following routines provide the ability to access and update global @command{awk}-level variables by name. In compiler terminology, identifiers of different kinds are termed @dfn{symbols}, thus the ``sym'' -in the routines' names. The data structure which stores information +in the routines' names. The data structure that stores information about symbols is termed a @dfn{symbol table}. +The functions are as follows: @table @code @item awk_bool_t sym_lookup(const char *name, @@ -31772,14 +31802,14 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise. +Return true if the actual type matches @code{wanted}, and false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @item awk_bool_t sym_update(const char *name, awk_value_t *value); Update the variable named by the string @code{name}, which is a regular C string. The variable is added to @command{gawk}'s symbol table -if it is not there. Return true if everything worked, false otherwise. +if it is not there. Return true if everything worked, and false otherwise. Changing types (scalar to array or vice versa) of an existing variable is @emph{not} allowed, nor may this routine be used to update an array. @@ -31804,7 +31834,7 @@ populate it. A @dfn{scalar cookie} is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in @command{gawk}'s symbol table every time -access is needed. This was discussed earlier in @ref{General Data Types}. +access is needed. This was discussed earlier, in @ref{General Data Types}. The following functions let you work with scalar cookies: @@ -31920,7 +31950,7 @@ and carefully check the return values from the API functions. @subsubsection Creating and Using Cached Values The routines in this section allow you to create and release -cached values. As with scalar cookies, in theory, cached values +cached values. Like scalar cookies, in theory, cached values are not necessary. You can create numbers and strings using the functions in @ref{Constructor Functions}. You can then assign those values to variables using @code{sym_update()} @@ -31998,7 +32028,7 @@ Using value cookies in this way saves considerable storage, as all of @code{VAR1} through @code{VAR100} share the same value. You might be wondering, ``Is this sharing problematic? -What happens if @command{awk} code assigns a new value to @code{VAR1}, +What happens if @command{awk} code assigns a new value to @code{VAR1}; are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. @@ -32102,7 +32132,7 @@ modify them. @node Array Functions @subsubsection Array Functions -The following functions relate to individual array elements. +The following functions relate to individual array elements: @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); @@ -32121,13 +32151,13 @@ Return false if @code{wanted} does not match the actual type or if @code{index} is not in the array (@pxref{table-value-types-returned}). The value for @code{index} can be numeric, in which case @command{gawk} -converts it to a string. Using non-integral values is possible, but +converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to strings -(@pxref{Conversion}); thus using integral values is safest. +(@pxref{Conversion}); thus, using integral values is safest. As with @emph{all} strings passed into @command{gawk} from an extension, the string value of @code{index} must come from @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}, and +@code{gawk_calloc()}, or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -32183,7 +32213,7 @@ flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data); When done with a flattened array, release the storage using this function. -You must pass in both the original array cookie, and the address of +You must pass in both the original array cookie and the address of the created @code{awk_flat_array_t} structure. The function returns true upon success, false otherwise. @end table @@ -32193,7 +32223,7 @@ The function returns true upon success, false otherwise. To @dfn{flatten} an array is to create a structure that represents the full array in a fashion that makes it easy -for C code to traverse the entire array. Test code +for C code to traverse the entire array. Some of the code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. @@ -32250,9 +32280,9 @@ dump_array_and_delete(int nargs, awk_value_t *result) @end example The function then proceeds in steps, as follows. First, retrieve -the name of the array, passed as the first argument. Then -retrieve the array itself. If either operation fails, print -error messages and return: +the name of the array, passed as the first argument, followed by +the array itself. If either operation fails, print an +error message and return: @example /* get argument named array as flat array and print it */ @@ -32288,7 +32318,7 @@ and print it: @end example The third step is to actually flatten the array, and then -to double check that the count in the @code{awk_flat_array_t} +to double-check that the count in the @code{awk_flat_array_t} is the same as the count just retrieved: @example @@ -32309,7 +32339,7 @@ is the same as the count just retrieved: The fourth step is to retrieve the index of the element to be deleted, which was passed as the second argument. Remember that argument counts passed to @code{get_argument()} -are zero-based, thus the second argument is numbered one: +are zero-based, and thus the second argument is numbered one: @example if (! get_argument(1, AWK_STRING, & value3)) @{ @@ -32324,7 +32354,7 @@ element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the @code{AWK_ELEMENT_DELETE} bit in the @code{flags} field of the element. When the array is released, @command{gawk} -traverses the flattened array, and deletes any elements which +traverses the flattened array, and deletes any elements that have this flag bit set: @example @@ -32612,10 +32642,10 @@ The API versions are available at compile time as constants: @table @code @item GAWK_API_MAJOR_VERSION -The major version of the API. +The major version of the API @item GAWK_API_MINOR_VERSION -The minor version of the API. +The minor version of the API @end table The minor version increases when new functions are added to the API. Such @@ -32633,14 +32663,14 @@ constant integers: @table @code @item api->major_version -The major version of the running @command{gawk}. +The major version of the running @command{gawk} @item api->minor_version -The minor version of the running @command{gawk}. +The minor version of the running @command{gawk} @end table It is up to the extension to decide if there are API incompatibilities. -Typically a check like this is enough: +Typically, a check like this is enough: @example if (api->major_version != GAWK_API_MAJOR_VERSION @@ -32654,7 +32684,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION @end example Such code is included in the boilerplate @code{dl_load_func()} macro -provided in @file{gawkapi.h} (discussed later, in +provided in @file{gawkapi.h} (discussed in @ref{Extension API Boilerplate}). @node Extension API Informational Variables @@ -32701,7 +32731,7 @@ as described here. The boilerplate needed is also provided in comments in the @file{gawkapi.h} header file: @example -/* Boiler plate code: */ +/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -32760,7 +32790,7 @@ to @code{NULL}, or to point to a string giving the name and version of your extension. @item static awk_ext_func_t func_table[] = @{ @dots{} @}; -This is an array of one or more @code{awk_ext_func_t} structures +This is an array of one or more @code{awk_ext_func_t} structures, as described earlier (@pxref{Extension Functions}). It can then be looped over for multiple calls to @code{add_ext_func()}. @@ -32891,7 +32921,7 @@ the @code{stat()} fails. It fills in the following elements: @table @code @item "name" -The name of the file that was @code{stat()}'ed. +The name of the file that was @code{stat()}ed. @item "dev" @itemx "ino" @@ -32947,7 +32977,7 @@ interprocess communications). The file is a directory. @item "fifo" -The file is a named-pipe (also known as a FIFO). +The file is a named pipe (also known as a FIFO). @item "file" The file is just a regular file. @@ -32970,7 +33000,7 @@ For some other systems, @dfn{a priori} knowledge is used to provide a value. Where no value can be determined, it defaults to 512. @end table -Several additional elements may be present depending upon the operating +Several additional elements may be present, depending upon the operating system and the type of the file. You can test for them in your @command{awk} program by using the @code{in} operator (@pxref{Reference to Elements}): @@ -33000,7 +33030,7 @@ edited slightly for presentation. See @file{extension/filefuncs.c} in the @command{gawk} distribution for the complete version.} The file includes a number of standard header files, and then includes -the @file{gawkapi.h} header file which provides the API definitions. +the @file{gawkapi.h} header file, which provides the API definitions. Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code (@pxref{Extension API Boilerplate}): @@ -33041,9 +33071,9 @@ int plugin_is_GPL_compatible; @cindex programming conventions, @command{gawk} extensions By convention, for an @command{awk} function @code{foo()}, the C function that implements it is called @code{do_foo()}. The function should have -two arguments: the first is an @code{int} usually called @code{nargs}, +two arguments. The first is an @code{int}, usually called @code{nargs}, that represents the number of actual arguments for the function. -The second is a pointer to an @code{awk_value_t}, usually named +The second is a pointer to an @code{awk_value_t} structure, usually named @code{result}: @example @@ -33089,7 +33119,7 @@ Finally, the function returns the return value to the @command{awk} level: The @code{stat()} extension is more involved. First comes a function that turns a numeric mode into a printable representation -(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity: +(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for brevity: @example /* format_mode --- turn a stat mode field into something readable */ @@ -33145,9 +33175,9 @@ array_set_numeric(awk_array_t array, const char *sub, double num) The following function does most of the work to fill in the @code{awk_array_t} result array with values obtained -from a valid @code{struct stat}. It is done in a separate function +from a valid @code{struct stat}. This work is done in a separate function to support the @code{stat()} function for @command{gawk} and also -to support the @code{fts()} extension which is included in +to support the @code{fts()} extension, which is included in the same file but whose code is not shown here (@pxref{Extension Sample File Functions}). @@ -33268,8 +33298,8 @@ the @code{stat()} system call instead of the @code{lstat()} system call. This is done by using a function pointer: @code{statfunc}. @code{statfunc} is initialized to point to @code{lstat()} (instead of @code{stat()}) to get the file information, in case the file is a -symbolic link. However, if there were three arguments, @code{statfunc} -is set point to @code{stat()}, instead. +symbolic link. However, if the third argument is included, @code{statfunc} +is set to point to @code{stat()}, instead. Here is the @code{do_stat()} function, which starts with variable declarations and argument checking: @@ -33325,7 +33355,7 @@ Next, it gets the information for the file. If the called function /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) @{ update_ERRNO_int(errno); @@ -33347,7 +33377,9 @@ Finally, it's necessary to provide the ``glue'' that loads the new function(s) into @command{gawk}. The @code{filefuncs} extension also provides an @code{fts()} -function, which we omit here. For its sake there is an initialization +function, which we omit here +(@pxref{Extension Sample File Functions}). +For its sake, there is an initialization function: @example @@ -33472,9 +33504,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @section The Sample Extensions in the @command{gawk} Distribution @cindex extensions distributed with @command{gawk} -This @value{SECTION} provides brief overviews of the sample extensions +This @value{SECTION} provides a brief overview of the sample extensions that come in the @command{gawk} distribution. Some of them are intended -for production use (e.g., the @code{filefuncs}, @code{readdir} and +for production use (e.g., the @code{filefuncs}, @code{readdir}, and @code{inplace} extensions). Others mainly provide example code that shows how to use the extension API. @@ -33510,14 +33542,14 @@ This is how you load the extension. @item @code{result = chdir("/some/directory")} The @code{chdir()} function is a direct hook to the @code{chdir()} system call to change the current directory. It returns zero -upon success or less than zero upon error. In the latter case, it updates -@code{ERRNO}. +upon success or a value less than zero upon error. +In the latter case, it updates @code{ERRNO}. @cindex @code{stat()} extension function @item @code{result = stat("/some/path", statdata} [@code{, follow}]@code{)} The @code{stat()} function provides a hook into the @code{stat()} system call. -It returns zero upon success or less than zero upon error. +It returns zero upon success or a value less than zero upon error. In the latter case, it updates @code{ERRNO}. By default, it uses the @code{lstat()} system call. However, if passed @@ -33544,10 +33576,10 @@ array with information retrieved from the filesystem, as follows: @item @code{"major"} @tab @code{st_major} @tab Device files @item @code{"minor"} @tab @code{st_minor} @tab Device files @item @code{"blksize"} @tab @code{st_blksize} @tab All -@item @code{"pmode"} @tab A human-readable version of the mode value, such as printed by -@command{ls}. For example, @code{"-rwxr-xr-x"} @tab All +@item @code{"pmode"} @tab A human-readable version of the mode value, like that printed by +@command{ls} (for example, @code{"-rwxr-xr-x"}) @tab All @item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links -@item @code{"type"} @tab The type of the file as a string. One of +@item @code{"type"} @tab The type of the file as a string---one of @code{"file"}, @code{"blockdev"}, @code{"chardev"}, @@ -33557,15 +33589,15 @@ array with information retrieved from the filesystem, as follows: @code{"symlink"}, @code{"door"}, or -@code{"unknown"}. -Not all systems support all file types. @tab All +@code{"unknown"} +(not all systems support all file types) @tab All @end multitable @cindex @code{fts()} extension function @item @code{flags = or(FTS_PHYSICAL, ...)} @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the -@code{filedata} array as described next. @code{flags} is the bitwise +@code{filedata} array, as described next. @code{flags} is the bitwise OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -33621,7 +33653,8 @@ During a traversal, do not cross onto a different mounted filesystem. @end table @item filedata -The @code{filedata} array is first cleared. Then, @code{fts()} creates +The @code{filedata} array holds the results. +@code{fts()} first clears it. Then it creates an element in @code{filedata} for every element in @code{pathlist}. The index is the name of the directory or file given in @code{pathlist}. The element for this index is itself an array. There are two cases: @@ -33663,7 +33696,7 @@ for a file: @code{"path"}, @code{"stat"}, and @code{"error"}. @end table The @code{fts()} function returns zero if there were no errors. -Otherwise it returns @minus{}1. +Otherwise, it returns @minus{}1. @quotation NOTE The @code{fts()} extension does not exactly mimic the @@ -33705,14 +33738,14 @@ The arguments to @code{fnmatch()} are: @table @code @item pattern -The @value{FN} wildcard to match. +The @value{FN} wildcard to match @item string -The @value{FN} string. +The @value{FN} string @item flag Either zero, or the bitwise OR of one or more of the -flags in the @code{FNM} array. +flags in the @code{FNM} array @end table The flags are as follows: @@ -33749,14 +33782,14 @@ This is how you load the extension. @cindex @code{fork()} extension function @item pid = fork() This function creates a new process. The return value is zero in the -child and the process-ID number of the child in the parent, or @minus{}1 +child and the process ID number of the child in the parent, or @minus{}1 upon error. In the latter case, @code{ERRNO} indicates the problem. In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are updated to reflect the correct values. @cindex @code{waitpid()} extension function @item ret = waitpid(pid) -This function takes a numeric argument, which is the process-ID to +This function takes a numeric argument, which is the process ID to wait for. The return value is that of the @code{waitpid()} system call. @@ -33784,8 +33817,8 @@ else @subsection Enabling In-Place File Editing @cindex @code{inplace} extension -The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option -which performs ``in place'' editing of each input file. +The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option, +which performs ``in-place'' editing of each input file. It uses the bundled @file{inplace.awk} include file to invoke the extension properly: @@ -33881,14 +33914,14 @@ they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode number and the @value{FN}, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +has a third field (also separated by a slash), which is a single letter indicating the type of the file. The letters and their corresponding file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types @caption{File types returned by the @code{readdir} extension} @multitable @columnfractions .1 .9 -@headitem Letter @tab File Type +@headitem Letter @tab File type @item @code{b} @tab Block device @item @code{c} @tab Character device @item @code{d} @tab Directory @@ -33916,7 +33949,7 @@ Here is an example: @@load "readdir" @dots{} BEGIN @{ FS = "/" @} -@{ print "file name is", $2 @} +@{ print "@value{FN} is", $2 @} @end example @node Extension Sample Revout @@ -33937,8 +33970,7 @@ BEGIN @{ @} @end example -The output from this program is: -@samp{cinap t'nod}. +The output from this program is @samp{cinap t'nod}. @node Extension Sample Rev2way @subsection Two-Way I/O Example @@ -33993,7 +34025,7 @@ success, or zero upon failure. @code{reada()} is the inverse of @code{writea()}; it reads the file named as its first argument, filling in the array named as the second argument. It clears the array first. -Here too, the return value is one on success and zero upon failure. +Here too, the return value is one on success, or zero upon failure. @end table The array created by @code{reada()} is identical to that written by @@ -34081,7 +34113,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}. Attempt to sleep for @var{seconds} seconds. If @var{seconds} is negative, or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}. Otherwise, return zero after sleeping for the indicated amount of time. -Note that @var{seconds} may be a floating-point (non-integral) value. +Note that @var{seconds} may be a floating-point (nonintegral) value. Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table @@ -34108,10 +34140,13 @@ project provides a number of @command{gawk} extensions, including one for processing XML files. This is the evolution of the original @command{xgawk} (XML @command{gawk}) project. -As of this writing, there are six extensions: +As of this writing, there are seven extensions: @itemize @value{BULLET} @item +@code{errno} extension + +@item GD graphics library extension @item @@ -34122,7 +34157,7 @@ PostgreSQL extension @item MPFR library extension -(this provides access to a number of MPFR functions which @command{gawk}'s +(this provides access to a number of MPFR functions that @command{gawk}'s native MPFR support does not) @item @@ -34176,7 +34211,7 @@ make install @ii{Install the extensions} If you have installed @command{gawk} in the standard way, then you will likely not need the @option{--with-gawk} option when configuring -@code{gawkextlib}. You may also need to use the @command{sudo} utility +@code{gawkextlib}. You may need to use the @command{sudo} utility to install both @command{gawk} and @code{gawkextlib}, depending upon how your system works. @@ -34201,7 +34236,7 @@ named @code{plugin_is_GPL_compatible}. @item Communication between @command{gawk} and an extension is two-way. -@command{gawk} passes a @code{struct} to the extension which contains +@command{gawk} passes a @code{struct} to the extension that contains various data fields and function pointers. The extension can then call into @command{gawk} via the supplied function pointers to accomplish certain tasks. @@ -34214,7 +34249,7 @@ By convention, implementation functions are named @code{do_@var{XXXX}()} for some @command{awk}-level function @code{@var{XXXX}()}. @item -The API is defined in a header file named @file{gawkpi.h}. You must include +The API is defined in a header file named @file{gawkapi.h}. You must include a number of standard header files @emph{before} including it in your source file. @item @@ -34259,7 +34294,7 @@ getting the count of elements in an array; creating a new array; clearing an array; and -flattening an array for easy C style looping over all its indices and elements) +flattening an array for easy C-style looping over all its indices and elements) @end itemize @item @@ -34267,7 +34302,7 @@ The API defines a number of standard data types for representing @command{awk} values, array elements, and arrays. @item -The API provide convenience functions for constructing values. +The API provides convenience functions for constructing values. It also provides memory management functions to ensure compatibility between memory allocated by @command{gawk} and memory allocated by an extension. @@ -34293,8 +34328,8 @@ file make this easier to do. @item The @command{gawk} distribution includes a number of small but useful -sample extensions. The @code{gawkextlib} project includes several more, -larger, extensions. If you wish to write an extension and contribute it +sample extensions. The @code{gawkextlib} project includes several more +(larger) extensions. If you wish to write an extension and contribute it to the community of @command{gawk} users, the @code{gawkextlib} project is the place to do so. @@ -34422,81 +34457,81 @@ cross-references to further details: @itemize @value{BULLET} @item The requirement for @samp{;} to separate rules on a line -(@pxref{Statements/Lines}). +(@pxref{Statements/Lines}) @item User-defined functions and the @code{return} statement -(@pxref{User-defined}). +(@pxref{User-defined}) @item The @code{delete} statement (@pxref{Delete}). @item The @code{do}-@code{while} statement -(@pxref{Do Statement}). +(@pxref{Do Statement}) @item The built-in functions @code{atan2()}, @code{cos()}, @code{sin()}, @code{rand()}, and -@code{srand()} (@pxref{Numeric Functions}). +@code{srand()} (@pxref{Numeric Functions}) @item The built-in functions @code{gsub()}, @code{sub()}, and @code{match()} -(@pxref{String Functions}). +(@pxref{String Functions}) @item The built-in functions @code{close()} and @code{system()} -(@pxref{I/O Functions}). +(@pxref{I/O Functions}) @item The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART}, -and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}). +and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}) @item -Assignable @code{$0} (@pxref{Changing Fields}). +Assignable @code{$0} (@pxref{Changing Fields}) @item The conditional expression using the ternary operator @samp{?:} -(@pxref{Conditional Exp}). +(@pxref{Conditional Exp}) @item -The expression @samp{@var{index-variable} in @var{array}} outside of @code{for} -statements (@pxref{Reference to Elements}). +The expression @samp{@var{indx} in @var{array}} outside of @code{for} +statements (@pxref{Reference to Elements}) @item The exponentiation operator @samp{^} (@pxref{Arithmetic Ops}) and its assignment operator -form @samp{^=} (@pxref{Assignment Ops}). +form @samp{^=} (@pxref{Assignment Ops}) @item C-compatible operator precedence, which breaks some old @command{awk} -programs (@pxref{Precedence}). +programs (@pxref{Precedence}) @item Regexps as the value of @code{FS} (@pxref{Field Separators}) and as the third argument to the @code{split()} function (@pxref{String Functions}), rather than using only the first character -of @code{FS}. +of @code{FS} @item Dynamic regexps as operands of the @samp{~} and @samp{!~} operators -(@pxref{Computed Regexps}). +(@pxref{Computed Regexps}) @item The escape sequences @samp{\b}, @samp{\f}, and @samp{\r} -(@pxref{Escape Sequences}). +(@pxref{Escape Sequences}) @item Redirection of input for the @code{getline} function -(@pxref{Getline}). +(@pxref{Getline}) @item Multiple @code{BEGIN} and @code{END} rules -(@pxref{BEGIN/END}). +(@pxref{BEGIN/END}) @item Multidimensional arrays -(@pxref{Multidimensional}). +(@pxref{Multidimensional}) @end itemize @node SVR4 @@ -34508,54 +34543,54 @@ The System V Release 4 (1989) version of Unix @command{awk} added these features @itemize @value{BULLET} @item -The @code{ENVIRON} array (@pxref{Built-in Variables}). +The @code{ENVIRON} array (@pxref{Built-in Variables}) @c gawk and MKS awk @item Multiple @option{-f} options on the command line -(@pxref{Options}). +(@pxref{Options}) @c MKS awk @item The @option{-v} option for assigning variables before program execution begins -(@pxref{Options}). +(@pxref{Options}) @c GNU, Bell Laboratories & MKS together @item -The @option{--} signal for terminating command-line options. +The @option{--} signal for terminating command-line options @item The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences -(@pxref{Escape Sequences}). +(@pxref{Escape Sequences}) @c GNU, for ANSI C compat @item A defined return value for the @code{srand()} built-in function -(@pxref{Numeric Functions}). +(@pxref{Numeric Functions}) @item The @code{toupper()} and @code{tolower()} built-in string functions for case translation -(@pxref{String Functions}). +(@pxref{String Functions}) @item A cleaner specification for the @samp{%c} format-control letter in the @code{printf} function -(@pxref{Control Letters}). +(@pxref{Control Letters}) @item The ability to dynamically pass the field width and precision (@code{"%*.*d"}) in the argument list of @code{printf} and @code{sprintf()} -(@pxref{Control Letters}). +(@pxref{Control Letters}) @item The use of regexp constants, such as @code{/foo/}, as expressions, where they are equivalent to using the matching operator, as in @samp{$0 ~ /foo/} -(@pxref{Using Constant Regexps}). +(@pxref{Using Constant Regexps}) @item Processing of escape sequences inside command-line variable assignments -(@pxref{Assignment Options}). +(@pxref{Assignment Options}) @end itemize @node POSIX @@ -34569,23 +34604,23 @@ introduced the following changes into the language: @itemize @value{BULLET} @item The use of @option{-W} for implementation-specific options -(@pxref{Options}). +(@pxref{Options}) @item The use of @code{CONVFMT} for controlling the conversion of numbers -to strings (@pxref{Conversion}). +to strings (@pxref{Conversion}) @item The concept of a numeric string and tighter comparison rules to go -with it (@pxref{Typing and Comparison}). +with it (@pxref{Typing and Comparison}) @item The use of predefined variables as function parameter names is forbidden -(@pxref{Definition Syntax}). +(@pxref{Definition Syntax}) @item More complete documentation of many of the previously undocumented -features of the language. +features of the language @end itemize In 2012, a number of extensions that had been commonly available for @@ -34594,15 +34629,15 @@ many years were finally added to POSIX. They are: @itemize @value{BULLET} @item The @code{fflush()} built-in function for flushing buffered output -(@pxref{I/O Functions}). +(@pxref{I/O Functions}) @item The @code{nextfile} statement -(@pxref{Nextfile Statement}). +(@pxref{Nextfile Statement}) @item The ability to delete all of an array at once with @samp{delete @var{array}} -(@pxref{Delete}). +(@pxref{Delete}) @end itemize @@ -34632,22 +34667,22 @@ originally appeared in his version of @command{awk}: The @samp{**} and @samp{**=} operators (@pxref{Arithmetic Ops} and -@ref{Assignment Ops}). +@ref{Assignment Ops}) @item The use of @code{func} as an abbreviation for @code{function} -(@pxref{Definition Syntax}). +(@pxref{Definition Syntax}) @item The @code{fflush()} built-in function for flushing buffered output -(@pxref{I/O Functions}). +(@pxref{I/O Functions}) @ignore @item The @code{SYMTAB} array, that allows access to @command{awk}'s internal symbol table. This feature was never documented for his @command{awk}, largely because it is somewhat shakily implemented. For instance, you cannot access arrays -or array elements through it. +or array elements through it @end ignore @end itemize @@ -34677,7 +34712,7 @@ Additional predefined variables: @itemize @value{MINUS} @item The -@code{ARGIND} +@code{ARGIND}, @code{BINMODE}, @code{ERRNO}, @code{FIELDWIDTHS}, @@ -34689,7 +34724,7 @@ The and @code{TEXTDOMAIN} variables -(@pxref{Built-in Variables}). +(@pxref{Built-in Variables}) @end itemize @item @@ -34697,15 +34732,15 @@ Special files in I/O redirections: @itemize @value{MINUS} @item -The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and +The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr}, and @file{/dev/fd/@var{N}} special @value{FN}s -(@pxref{Special Files}). +(@pxref{Special Files}) @item The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for TCP/IP networking using @samp{|&} to specify which version of the IP protocol to use -(@pxref{TCP/IP Networking}). +(@pxref{TCP/IP Networking}) @end itemize @item @@ -34714,37 +34749,37 @@ Changes and/or additions to the language: @itemize @value{MINUS} @item The @samp{\x} escape sequence -(@pxref{Escape Sequences}). +(@pxref{Escape Sequences}) @item Full support for both POSIX and GNU regexps -(@pxref{Regexp}). +(@pxref{Regexp}) @item The ability for @code{FS} and for the third argument to @code{split()} to be null strings -(@pxref{Single Character Fields}). +(@pxref{Single Character Fields}) @item The ability for @code{RS} to be a regexp -(@pxref{Records}). +(@pxref{Records}) @item The ability to use octal and hexadecimal constants in @command{awk} program source code -(@pxref{Nondecimal-numbers}). +(@pxref{Nondecimal-numbers}) @item The @samp{|&} operator for two-way I/O to a coprocess -(@pxref{Two-way I/O}). +(@pxref{Two-way I/O}) @item Indirect function calls -(@pxref{Indirect Calls}). +(@pxref{Indirect Calls}) @item Directories on the command line produce a warning and are skipped -(@pxref{Command-line directories}). +(@pxref{Command-line directories}) @end itemize @item @@ -34753,11 +34788,11 @@ New keywords: @itemize @value{MINUS} @item The @code{BEGINFILE} and @code{ENDFILE} special patterns -(@pxref{BEGINFILE/ENDFILE}). +(@pxref{BEGINFILE/ENDFILE}) @item The @code{switch} statement -(@pxref{Switch Statement}). +(@pxref{Switch Statement}) @end itemize @item @@ -34767,30 +34802,30 @@ Changes to standard @command{awk} functions: @item The optional second argument to @code{close()} that allows closing one end of a two-way pipe to a coprocess -(@pxref{Two-way I/O}). +(@pxref{Two-way I/O}) @item -POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix}. +POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix} @item The @code{length()} function accepts an array argument and returns the number of elements in the array -(@pxref{String Functions}). +(@pxref{String Functions}) @item The optional third argument to the @code{match()} function for capturing text-matching subexpressions within a regexp -(@pxref{String Functions}). +(@pxref{String Functions}) @item Positional specifiers in @code{printf} formats for making translations easier -(@pxref{Printf Ordering}). +(@pxref{Printf Ordering}) @item The @code{split()} function's additional optional fourth -argument which is an array to hold the text of the field separators -(@pxref{String Functions}). +argument, which is an array to hold the text of the field separators +(@pxref{String Functions}) @end itemize @item @@ -34800,16 +34835,16 @@ Additional functions only in @command{gawk}: @item The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions for more powerful text manipulation -(@pxref{String Functions}). +(@pxref{String Functions}) @item The @code{asort()} and @code{asorti()} functions for sorting arrays -(@pxref{Array Sorting}). +(@pxref{Array Sorting}) @item The @code{mktime()}, @code{systime()}, and @code{strftime()} functions for working with timestamps -(@pxref{Time Functions}). +(@pxref{Time Functions}) @item The @@ -34821,22 +34856,22 @@ The and @code{xor()} functions for bit manipulation -(@pxref{Bitwise Functions}). +(@pxref{Bitwise Functions}) @c In 4.1, and(), or() and xor() grew the ability to take > 2 arguments @item The @code{isarray()} function to check if a variable is an array or not -(@pxref{Type Functions}). +(@pxref{Type Functions}) @item -The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()} +The @code{bindtextdomain()}, @code{dcgettext()}, and @code{dcngettext()} functions for internationalization -(@pxref{Programmer i18n}). +(@pxref{Programmer i18n}) @item The @code{div()} function for doing integer division and remainder -(@pxref{Numeric Functions}). +(@pxref{Numeric Functions}) @end itemize @item @@ -34846,12 +34881,12 @@ Changes and/or additions in the command-line options: @item The @env{AWKPATH} environment variable for specifying a path search for the @option{-f} command-line option -(@pxref{Options}). +(@pxref{Options}) @item The @env{AWKLIBPATH} environment variable for specifying a path search for the @option{-l} command-line option -(@pxref{Options}). +(@pxref{Options}) @item The @@ -34880,7 +34915,7 @@ The and @option{-V} short options. Also, the -ability to use GNU-style long-named options that start with @option{--} +ability to use GNU-style long-named options that start with @option{--}, and the @option{--assign}, @option{--bignum}, @@ -34960,7 +34995,7 @@ GCC for VAX and Alpha has not been tested for a while. @end itemize @item -Support for the following obsolete systems was removed from the code +Support for the following obsolete system was removed from the code for @command{gawk} @value{PVERSION} 4.1: @c nested table @@ -35640,9 +35675,9 @@ by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk}, the three most widely used freely available versions of @command{awk} (@pxref{Other Versions}). -@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} -@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @tab Now standard -@item @samp{\x} Escape sequence @tab X @tab X @tab X @tab +@multitable {@file{/dev/stderr} special file} {BWK @command{awk}} {@command{mawk}} {@command{gawk}} {Now standard} +@headitem Feature @tab BWK @command{awk} @tab @command{mawk} @tab @command{gawk} @tab Now standard +@item @samp{\x} escape sequence @tab X @tab X @tab X @tab @item @code{FS} as null string @tab X @tab X @tab X @tab @item @file{/dev/stdin} special file @tab X @tab X @tab X @tab @item @file{/dev/stdout} special file @tab X @tab X @tab X @tab @@ -35673,7 +35708,7 @@ in the machine's native character set. Thus, on ASCII-based systems, @samp{[a-z]} matched all the lowercase letters, and only the lowercase letters, as the numeric values for the letters from @samp{a} through @samp{z} were contiguous. (On an EBCDIC system, the range @samp{[a-z]} -includes additional, non-alphabetic characters as well.) +includes additional nonalphabetic characters as well.) Almost all introductory Unix literature explained range expressions as working in this fashion, and in particular, would teach that the @@ -35698,7 +35733,7 @@ What does that mean? In many locales, @samp{A} and @samp{a} are both less than @samp{B}. In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; -instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. +instead, it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. This point needs to be emphasized: much literature teaches that you should use @samp{[a-z]} to match a lowercase character. But on systems with @@ -35727,23 +35762,23 @@ is perfectly valid in ASCII, but is not valid in many Unicode locales, such as @code{en_US.UTF-8}. Early versions of @command{gawk} used regexp matching code that was not -locale aware, so ranges had their traditional interpretation. +locale-aware, so ranges had their traditional interpretation. When @command{gawk} switched to using locale-aware regexp matchers, the problems began; especially as both GNU/Linux and commercial Unix vendors started implementing non-ASCII locales, @emph{and making them the default}. Perhaps the most frequently asked question became something -like ``why does @samp{[A-Z]} match lowercase letters?!?'' +like, ``Why does @samp{[A-Z]} match lowercase letters?!?'' @cindex Berry, Karl This situation existed for close to 10 years, if not more, and the @command{gawk} maintainer grew weary of trying to explain that -@command{gawk} was being nicely standards compliant, and that the issue +@command{gawk} was being nicely standards-compliant, and that the issue was in the user's locale. During the development of @value{PVERSION} 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And thus was born the Campaign for Rational Range Interpretation (or -RRI). A number of GNU tools have either implemented this change, +RRI). A number of GNU tools have already implemented this change, or will soon. Thanks to Karl Berry for coining the phrase ``Rational Range Interpretation.''} @@ -35757,9 +35792,10 @@ and By using this lovely technical term, the standard gives license to implementors to implement ranges in whatever way they choose. -The @command{gawk} maintainer chose to apply the pre-POSIX meaning in all -cases: the default regexp matching; with @option{--traditional} and with -@option{--posix}; in all cases, @command{gawk} remains POSIX compliant. +The @command{gawk} maintainer chose to apply the pre-POSIX meaning +both with the default regexp matching and when @option{--traditional} or +@option{--posix} are used. +In all cases @command{gawk} remains POSIX-compliant. @node Contributors @appendixsec Major Contributors to @command{gawk} @@ -35805,7 +35841,7 @@ to around 90 pages. Richard Stallman helped finish the implementation and the initial draft of this @value{DOCUMENT}. -He is also the founder of the FSF and the GNU project. +He is also the founder of the FSF and the GNU Project. @item @cindex Woods, John @@ -35969,28 +36005,28 @@ John Haque made the following contributions: @itemize @value{MINUS} @item The modifications to convert @command{gawk} -into a byte-code interpreter, including the debugger. +into a byte-code interpreter, including the debugger @item -The addition of true arrays of arrays. +The addition of true arrays of arrays @item -The additional modifications for support of arbitrary-precision arithmetic. +The additional modifications for support of arbitrary-precision arithmetic @item The initial text of -@ref{Arbitrary Precision Arithmetic}. +@ref{Arbitrary Precision Arithmetic} @item The work to merge the three versions of @command{gawk} -into one, for the 4.1 release. +into one, for the 4.1 release @item -Improved array internals for arrays indexed by integers. +Improved array internals for arrays indexed by integers @item -The improved array sorting features were driven by John together -with Pat Rankin. +The improved array sorting features were also driven by John, together +with Pat Rankin @end itemize @cindex Papadopoulos, Panos @@ -36031,10 +36067,10 @@ helping David Trueman, and as the primary maintainer since around 1994. @itemize @value{BULLET} @item The @command{awk} language has evolved over time. The first release -was with V7 Unix circa 1978. In 1987, for System V Release 3.1, +was with V7 Unix, circa 1978. In 1987, for System V Release 3.1, major additions, including user-defined functions, were made to the language. Additional changes were made for System V Release 4, in 1989. -Since then, further minor changes happen under the auspices of the +Since then, further minor changes have happened under the auspices of the POSIX standard. @item @@ -36050,7 +36086,7 @@ options. The interaction of POSIX locales and regexp matching in @command{gawk} has been confusing over the years. Today, @command{gawk} implements Rational Range Interpretation, where ranges of the form @samp{[a-z]} match @emph{only} the characters numerically between -@samp{a} through @samp{z} in the machine's native character set. Usually this is ASCII +@samp{a} through @samp{z} in the machine's native character set. Usually this is ASCII, but it can be EBCDIC on IBM S/390 systems. @item @@ -36135,7 +36171,7 @@ will be less busy, and you can usually find one closer to your site. @command{gawk} is distributed as several @code{tar} files compressed with different compression programs: @command{gzip}, @command{bzip2}, and @command{xz}. For simplicity, the rest of these instructions assume -you are using the one compressed with the GNU Zip program, @code{gzip}. +you are using the one compressed with the GNU Gzip program (@command{gzip}). Once you have the distribution (e.g., @file{gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz}), @@ -36186,12 +36222,12 @@ operating systems: @table @asis @item Various @samp{.c}, @samp{.y}, and @samp{.h} files -The actual @command{gawk} source code. +These files contain the actual @command{gawk} source code. @end table @table @file @item ABOUT-NLS -Information about GNU @command{gettext} and translations. +A file containing information about GNU @command{gettext} and translations. @item AUTHORS A file with some information about the authorship of @command{gawk}. @@ -36221,7 +36257,7 @@ An older list of changes to @command{gawk}. The GNU General Public License. @item POSIX.STD -A description of behaviors in the POSIX standard for @command{awk} which +A description of behaviors in the POSIX standard for @command{awk} that are left undefined, or where @command{gawk} may not comply fully, as well as a list of things that the POSIX standard should describe but does not. @@ -36531,14 +36567,17 @@ Similarly, setting the @code{LINT} variable (@pxref{User-modified}) has no effect on the running @command{awk} program. -When used with GCC's automatic dead-code-elimination, this option +When used with the GNU Compiler Collection's (GCC's) +automatic dead-code-elimination, this option cuts almost 23K bytes off the size of the @command{gawk} executable on GNU/Linux x86_64 systems. Results on other systems and with other compilers are likely to vary. Using this option may bring you some slight performance improvement. +@quotation CAUTION Using this option will cause some of the tests in the test suite to fail. This option may be removed at a later date. +@end quotation @cindex @option{--disable-nls} configuration option @cindex configuration option, @code{--disable-nls} @@ -36635,10 +36674,10 @@ running MS-DOS, any version of MS-Windows, or OS/2. running MS-DOS and any version of MS-Windows. @end ifset In this @value{SECTION}, the term ``Windows32'' -refers to any of Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7/8. +refers to any of Microsoft Windows 95/98/ME/NT/2000/XP/Vista/7/8. The limitations of MS-DOS (and MS-DOS shells under the other operating -systems) has meant that various ``DOS extenders'' are often used with +systems) have meant that various ``DOS extenders'' are often used with programs such as @command{gawk}. The varying capabilities of Microsoft Windows 3.1 and Windows32 can add to the confusion. For an overview of the considerations, refer to @file{README_d/README.pc} in @@ -36897,7 +36936,7 @@ Under MS-Windows, OS/2 and MS-DOS, Under MS-Windows and MS-DOS, @end ifset @command{gawk} (and many other text programs) silently -translate end-of-line @samp{\r\n} to @samp{\n} on input and @samp{\n} +translates end-of-line @samp{\r\n} to @samp{\n} on input and @samp{\n} to @samp{\r\n} on output. A special @code{BINMODE} variable @value{COMMONEXT} allows control over these translations and is interpreted as follows: @@ -36931,7 +36970,7 @@ Setting @code{BINMODE} for standard input or standard output is accomplished by using an appropriate @samp{-v BINMODE=@var{N}} option on the command line. @code{BINMODE} is set at the time a file or pipe is opened and cannot be -changed mid-stream. +changed midstream. The name @code{BINMODE} was chosen to match @command{mawk} (@pxref{Other Versions}). @@ -36987,8 +37026,8 @@ moved into the @code{BEGIN} rule. @command{gawk} can be built and used ``out of the box'' under MS-Windows if you are using the @uref{http://www.cygwin.com, Cygwin environment}. -This environment provides an excellent simulation of GNU/Linux, using the -GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, +This environment provides an excellent simulation of GNU/Linux, using +Bash, GCC, GNU Make, and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: @@ -37007,7 +37046,7 @@ and then the @samp{make} proceeds as usual. @appendixsubsubsec Using @command{gawk} In The MSYS Environment In the MSYS environment under MS-Windows, @command{gawk} automatically -uses binary mode for reading and writing files. Thus there is no +uses binary mode for reading and writing files. Thus, there is no need to use the @code{BINMODE} variable. This can cause problems with other Unix-like components that have @@ -37071,7 +37110,7 @@ With ODS-5 volumes and extended parsing enabled, the case of the target parameter may need to be exact. @command{gawk} has been tested under VAX/VMS 7.3 and Alpha/VMS 7.3-1 -using Compaq C V6.4, and Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3. +using Compaq C V6.4, and under Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3. The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both Alpha and IA64 VMS 8.4 used HP C 7.3.@footnote{The IA64 architecture is also known as ``Itanium.''} @@ -37119,7 +37158,7 @@ For VAX: /name=(as_is,short) @end example -Compile time macros need to be defined before the first VMS-supplied +Compile-time macros need to be defined before the first VMS-supplied header file is included, as follows: @example @@ -37166,7 +37205,7 @@ If your @command{gawk} was installed by a PCSI kit into the @file{GNV$GNU:[vms_help]gawk.hlp}. The PCSI kit also installs a @file{GNV$GNU:[vms_bin]gawk_verb.cld} file -which can be used to add @command{gawk} and @command{awk} as DCL commands. +that can be used to add @command{gawk} and @command{awk} as DCL commands. For just the current process you can use: @@ -37175,7 +37214,7 @@ $ @kbd{set command gnv$gnu:[vms_bin]gawk_verb.cld} @end example Or the system manager can use @file{GNV$GNU:[vms_bin]gawk_verb.cld} to -add the @command{gawk} and @command{awk} to the system wide @samp{DCLTABLES}. +add the @command{gawk} and @command{awk} to the system-wide @samp{DCLTABLES}. The DCL syntax is documented in the @file{gawk.hlp} file. @@ -37241,14 +37280,14 @@ The @code{exit} value is a Unix-style value and is encoded into a VMS exit status value when the program exits. The VMS severity bits will be set based on the @code{exit} value. -A failure is indicated by 1 and VMS sets the @code{ERROR} status. -A fatal error is indicated by 2 and VMS sets the @code{FATAL} status. +A failure is indicated by 1, and VMS sets the @code{ERROR} status. +A fatal error is indicated by 2, and VMS sets the @code{FATAL} status. All other values will have the @code{SUCCESS} status. The exit value is encoded to comply with VMS coding standards and will have the @code{C_FACILITY_NO} of @code{0x350000} with the constant @code{0xA000} added to the number shifted over by 3 bits to make room for the severity codes. -To extract the actual @command{gawk} exit code from the VMS status use: +To extract the actual @command{gawk} exit code from the VMS status, use: @example unix_status = (vms_status .and. &x7f8) / 8 @@ -37267,7 +37306,7 @@ VAX/VMS floating point uses unbiased rounding. @xref{Round Function}. VMS reports time values in GMT unless one of the @code{SYS$TIMEZONE_RULE} or @code{TZ} logical names is set. Older versions of VMS, such as VAX/VMS -7.3 do not set these logical names. +7.3, do not set these logical names. @c @cindex directory search @c @cindex path, search @@ -37285,7 +37324,7 @@ translation and not a multitranslation @code{RMS} searchlist. The VMS GNV package provides a build environment similar to POSIX with ports of a collection of open source tools. The @command{gawk} found in the GNV -base kit is an older port. Currently the GNV project is being reorganized +base kit is an older port. Currently, the GNV project is being reorganized to supply individual PCSI packages for each component. See @w{@uref{https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/}.} @@ -37358,7 +37397,7 @@ recommend compiling and using the current version. @cindex debugging @command{gawk}, bug reports @cindex troubleshooting, @command{gawk}, bug reports If you have problems with @command{gawk} or think that you have found a bug, -report it to the developers; we cannot promise to do anything +report it to the developers; we cannot promise to do anything, but we might well want to fix it. Before reporting a bug, make sure you have really found a genuine bug. @@ -37368,7 +37407,7 @@ to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible @command{awk} program and input @value{DF} that -reproduces the problem. Then send us the program and @value{DF}, +reproduce the problem. Then send us the program and @value{DF}, some idea of what kind of Unix system you're using, the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps @@ -37383,7 +37422,7 @@ You can get this information with the command @samp{gawk --version}. Once you have a precise problem description, send email to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. -The @command{gawk} maintainers subscribe to this address and +The @command{gawk} maintainers subscribe to this address, and thus they will receive your bug report. Although you can send mail to the maintainers directly, the bug reporting address is preferred because the @@ -37410,8 +37449,8 @@ bug reporting system, you should also send a copy to This is for two reasons. First, although some distributions forward bug reports ``upstream'' to the GNU mailing list, many don't, so there is a good chance that the @command{gawk} maintainers won't even see the bug report! Second, -mail to the GNU list is archived, and having everything at the GNU project -keeps things self-contained and not dependant on other organizations. +mail to the GNU list is archived, and having everything at the GNU Project +keeps things self-contained and not dependent on other organizations. @end quotation Non-bug suggestions are always welcome as well. If you have questions @@ -37420,7 +37459,7 @@ features, ask on the bug list; we will try to help you out if we can. If you find bugs in one of the non-Unix ports of @command{gawk}, send an email to the bug list, with a copy to the -person who maintains that port. They are named in the following list, +person who maintains that port. The maintainers are named in the following list, as well as in the @file{README} file in the @command{gawk} distribution. Information in the @file{README} file should be considered authoritative if it conflicts with this @value{DOCUMENT}. @@ -37435,19 +37474,19 @@ The people maintaining the various @command{gawk} ports are: @cindex Robbins, Arnold @cindex Zaretskii, Eli @multitable {MS-Windows with MinGW} {123456789012345678901234567890123456789001234567890} -@item Unix and POSIX systems @tab Arnold Robbins, @EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. +@item Unix and POSIX systems @tab Arnold Robbins, @EMAIL{arnold@@skeeve.com,arnold at skeeve dot com} -@item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. +@item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net} -@item MS-Windows with MinGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. +@item MS-Windows with MinGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org} @c Leave this in the print version on purpose. @c OS/2 is not mentioned anywhere else in the print version though. -@item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. +@item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de} -@item VMS @tab John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. +@item VMS @tab John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net} -@item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. +@item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com} @end multitable If your bug is also reproducible under Unix, send a copy of your @@ -37466,7 +37505,7 @@ Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) @cindex Brennan, Michael @ifnotdocbook @quotation -@i{It's kind of fun to put comments like this in your awk code.}@* +@i{It's kind of fun to put comments like this in your awk code:}@* @ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course} @author Michael Brennan @end quotation @@ -37507,7 +37546,7 @@ It is available in several archive formats: @end table @cindex @command{git} utility -You can also retrieve it from Git Hub: +You can also retrieve it from GitHub: @example git clone git://github.com/onetrueawk/awk bwkawk @@ -37567,7 +37606,7 @@ for a list of extensions in @command{mawk} that are not in POSIX @command{awk}. @item @command{awka} Written by Andrew Sumner, @command{awka} translates @command{awk} programs into C, compiles them, -and links them with a library of functions that provides the core +and links them with a library of functions that provide the core @command{awk} functionality. It also has a number of extensions. @@ -37588,17 +37627,17 @@ since approximately 2001. Nelson H.F.@: Beebe at the University of Utah has modified BWK @command{awk} to provide timing and profiling information. It is different from @command{gawk} with the @option{--profile} option -(@pxref{Profiling}), +(@pxref{Profiling}) in that it uses CPU-based profiling, not line-count profiling. You may find it at either @uref{ftp://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz} or @uref{http://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz}. -@item Busybox Awk -@cindex Busybox Awk -@cindex source code, Busybox Awk -Busybox is a GPL-licensed program providing small versions of many +@item BusyBox @command{awk} +@cindex BusyBox Awk +@cindex source code, BusyBox Awk +BusyBox is a GPL-licensed program providing small versions of many applications within a single executable. It is aimed at embedded systems. It includes a full implementation of POSIX @command{awk}. When building it, be careful not to do @samp{make install} as it will overwrite @@ -37610,7 +37649,7 @@ information, see the @uref{http://busybox.net, project's home page}. @cindex source code, Solaris @command{awk} @item The OpenSolaris POSIX @command{awk} The versions of @command{awk} in @file{/usr/xpg4/bin} and -@file{/usr/xpg6/bin} on Solaris are more-or-less POSIX-compliant. +@file{/usr/xpg6/bin} on Solaris are more or less POSIX-compliant. They are based on the @command{awk} from Mortice Kern Systems for PCs. We were able to make this code compile and work under GNU/Linux with 1--2 hours of work. Making it more generally portable (using @@ -37651,9 +37690,9 @@ features to Python. See @uref{https://github.com/alecthomas/pawk} for more information. (This is not related to Nelson Beebe's modified version of BWK @command{awk}, described earlier.) -@item @w{QSE Awk} -@cindex QSE Awk -@cindex source code, QSE Awk +@item @w{QSE @command{awk}} +@cindex QSE @command{awk} +@cindex source code, QSE @command{awk} This is an embeddable @command{awk} interpreter. For more information, see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}. @@ -37672,7 +37711,7 @@ since approximately 2008. @item Other versions See also the ``Versions and implementations'' section of the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, -Wikipedia article} for information on additional versions. +Wikipedia article} on @command{awk} for information on additional versions. @end table @@ -37681,7 +37720,7 @@ Wikipedia article} for information on additional versions. @itemize @value{BULLET} @item -The @command{gawk} distribution is available from GNU project's main +The @command{gawk} distribution is available from the GNU Project's main distribution site, @code{ftp.gnu.org}. The canonical build recipe is: @example @@ -37693,22 +37732,22 @@ cd gawk-@value{VERSION}.@value{PATCHLEVEL} @item @command{gawk} may be built on non-POSIX systems as well. The currently -supported systems are MS-Windows using DJGPP, MSYS, MinGW and Cygwin, +supported systems are MS-Windows using DJGPP, MSYS, MinGW, and Cygwin, @ifclear FOR_PRINT OS/2 using EMX, @end ifclear and both Vax/VMS and OpenVMS. -Instructions for each system are included in this @value{CHAPTER}. +Instructions for each system are included in this @value{APPENDIX}. @item Bug reports should be sent via email to @email{bug-gawk@@gnu.org}. -Bug reports should be in English, and should include the version of @command{gawk}, -how it was compiled, and a short program and @value{DF} which demonstrate +Bug reports should be in English and should include the version of @command{gawk}, +how it was compiled, and a short program and @value{DF} that demonstrate the problem. @item There are a number of other freely available @command{awk} -implementations. Many are POSIX compliant; others are less so. +implementations. Many are POSIX-compliant; others are less so. @end itemize diff --git a/extension/ChangeLog b/extension/ChangeLog index e94e2702..46c2a7d7 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,7 @@ +2015-02-11 Arnold D. Robbins <arnold@skeeve.com> + + * filefuncs.c: Punctuation fix. + 2015-01-24 Arnold D. Robbins <arnold@skeeve.com> Infrastructure updates. diff --git a/extension/filefuncs.c b/extension/filefuncs.c index a20e9ff7..ddb1ecda 100644 --- a/extension/filefuncs.c +++ b/extension/filefuncs.c @@ -490,7 +490,7 @@ do_stat(int nargs, awk_value_t *result) /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) { update_ERRNO_int(errno); @@ -846,7 +846,7 @@ make_number(double num, awk_value_t *result) extern int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id); #if 0 -/* Boiler plate code: */ +/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -226,6 +226,7 @@ pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header) if (do_profile && ! rule_count[rule]++) fprintf(prof_fp, _("\t# Rule(s)\n\n")); ip1 = pc->nexti; + indent(ip1->exec_count); if (ip1 != (pc + 1)->firsti) { /* non-empty pattern */ pprint(ip1->nexti, (pc + 1)->firsti, false); /* Allow for case where the "pattern" is just a comment */ diff --git a/test/ChangeLog b/test/ChangeLog index e9d5620a..ecbfaf0d 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,8 @@ +2015-02-10 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (profile0): New test. + * profile0.awk, profile0.in, profile0.ok: New files. + 2015-02-01 Arnold D. Robbins <arnold@skeeve.com> * Makefile.am (paramasfunc1, paramasfunc2): Now need --posix. diff --git a/test/Makefile.am b/test/Makefile.am index c4c0b8b3..4f78ddb4 100644 --- a/test/Makefile.am +++ b/test/Makefile.am @@ -710,6 +710,8 @@ EXTRA_DIST = \ prmreuse.ok \ procinfs.awk \ procinfs.ok \ + profile0.awk \ + profile0.ok \ profile2.ok \ profile3.awk \ profile3.ok \ @@ -1043,7 +1045,7 @@ GAWK_EXT_TESTS = \ manyfiles match1 match2 match3 mbstr1 \ nastyparm next nondec nondec2 \ patsplit posix printfbad1 printfbad2 printfbad3 printfbad4 printhuge procinfs \ - profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ + profile0 profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ profile8 pty1 \ rebuf regnul1 regnul2 regx8bit reginttrad reint reint2 rsgetline rsglstdin rsstart1 \ rsstart2 rsstart3 rstest6 shadow sortfor sortu split_after_fpat \ @@ -1694,6 +1696,12 @@ dumpvars:: @grep -v ENVIRON < awkvars.out | grep -v PROCINFO > _$@; rm awkvars.out @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +profile0: + @echo $@ + @$(AWK) --profile=ap-$@.out -f "$(srcdir)"/$@.awk "$(srcdir)"/$@.in > /dev/null + @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + profile1: @echo $@ @$(AWK) -f "$(srcdir)"/xref.awk "$(srcdir)"/dtdgport.awk > _$@.out1 diff --git a/test/Makefile.in b/test/Makefile.in index 212cb779..30c77b97 100644 --- a/test/Makefile.in +++ b/test/Makefile.in @@ -967,6 +967,8 @@ EXTRA_DIST = \ prmreuse.ok \ procinfs.awk \ procinfs.ok \ + profile0.awk \ + profile0.ok \ profile2.ok \ profile3.awk \ profile3.ok \ @@ -1299,7 +1301,7 @@ GAWK_EXT_TESTS = \ manyfiles match1 match2 match3 mbstr1 \ nastyparm next nondec nondec2 \ patsplit posix printfbad1 printfbad2 printfbad3 printfbad4 printhuge procinfs \ - profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ + profile0 profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ profile8 pty1 \ rebuf regnul1 regnul2 regx8bit reginttrad reint reint2 rsgetline rsglstdin rsstart1 \ rsstart2 rsstart3 rstest6 shadow sortfor sortu split_after_fpat \ @@ -2132,6 +2134,12 @@ dumpvars:: @grep -v ENVIRON < awkvars.out | grep -v PROCINFO > _$@; rm awkvars.out @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +profile0: + @echo $@ + @$(AWK) --profile=ap-$@.out -f "$(srcdir)"/$@.awk "$(srcdir)"/$@.in > /dev/null + @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + profile1: @echo $@ @$(AWK) -f "$(srcdir)"/xref.awk "$(srcdir)"/dtdgport.awk > _$@.out1 diff --git a/test/profile0.awk b/test/profile0.awk new file mode 100644 index 00000000..a42e94df --- /dev/null +++ b/test/profile0.awk @@ -0,0 +1 @@ +NR == 1 diff --git a/test/profile0.in b/test/profile0.in new file mode 100644 index 00000000..7bba8c8e --- /dev/null +++ b/test/profile0.in @@ -0,0 +1,2 @@ +line 1 +line 2 diff --git a/test/profile0.ok b/test/profile0.ok new file mode 100644 index 00000000..2e3c5728 --- /dev/null +++ b/test/profile0.ok @@ -0,0 +1,6 @@ + # Rule(s) + + 2 NR == 1 { # 1 + 1 print $0 + } + |