diff options
| -rw-r--r-- | ChangeLog | 11 | ||||
| -rw-r--r-- | NEWS | 3 | ||||
| -rw-r--r-- | command.c | 2 | ||||
| -rw-r--r-- | command.y | 2 | ||||
| -rw-r--r-- | dfa.c | 105 | ||||
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 663 | ||||
| -rw-r--r-- | doc/gawk.texi | 182 | ||||
| -rw-r--r-- | doc/gawktexi.in | 182 |
9 files changed, 649 insertions, 506 deletions
@@ -1,3 +1,12 @@ +2014-09-28 Arnold D. Robbins <arnold@skeeve.com> + + * command.y (cmdtab): Add "where" as an alias for "backtrace". + Finally! + + Unrelated: + + * dfa.c: Sync with GNU grep. + 2014-09-27 Arnold D. Robbins <arnold@skeeve.com> * awkgram.y (check_for_bad): Bitwise-and the bad character with 0xFF @@ -19,7 +28,7 @@ * awkgram.y (yylex): Don't check for junk characters inside quoted strings. Caused issues on DJGPP and Solaris. - Unrelated + Unrelated: * io.c (devopen): Straighten things out with respect to compatibility with BWK awk. @@ -60,6 +60,9 @@ Changes from 4.1.1 to 4.1.2 If you feel that you must have this misfeature, use `configure --help' to see what option to use when configuring gawk to reenable it. +7. The "where" command has been added to the debugger as an alias + for "backtrace". This will make life easier for long-time GDB users. + XX. A number of bugs have been fixed. See the ChangeLog. Changes from 4.1.0 to 4.1.1 @@ -2648,6 +2648,8 @@ struct cmdtoken cmdtab[] = { gettext_noop("up [N] - move N frames up the stack.") }, { "watch", "w", D_watch, D_WATCH, do_watch, gettext_noop("watch var - set a watchpoint for a variable.") }, +{ "where", "", D_backtrace, D_BACKTRACE, do_backtrace, + gettext_noop("where [N] - (same as backtrace) print trace of all or N innermost (outermost if N < 0) frames.") }, { NULL, NULL, D_illegal, 0, (Func_cmd) 0, NULL }, }; @@ -897,6 +897,8 @@ struct cmdtoken cmdtab[] = { gettext_noop("up [N] - move N frames up the stack.") }, { "watch", "w", D_watch, D_WATCH, do_watch, gettext_noop("watch var - set a watchpoint for a variable.") }, +{ "where", "", D_backtrace, D_BACKTRACE, do_backtrace, + gettext_noop("where [N] - (same as backtrace) print trace of all or N innermost (outermost if N < 0) frames.") }, { NULL, NULL, D_illegal, 0, (Func_cmd) 0, NULL }, }; @@ -367,6 +367,9 @@ struct dfa token utf8_anychar_classes[5]; /* To lower ANYCHAR in UTF-8 locales. */ mbstate_t mbs; /* Multibyte conversion state. */ + /* dfaexec implementation. */ + char *(*dfaexec) (struct dfa *, char const *, char *, int, size_t *, int *); + /* The following are valid only if MB_CUR_MAX > 1. */ /* The value of multibyte_prop[i] is defined by following rule. @@ -3309,6 +3312,24 @@ transit_state (struct dfa *d, state_num s, unsigned char const **pp, return s1; } +/* The initial state may encounter a byte which is not a single byte character + nor the first byte of a multibyte character. But it is incorrect for the + initial state to accept such a byte. For example, in Shift JIS the regular + expression "\\" accepts the codepoint 0x5c, but should not accept the second + byte of the codepoint 0x815c. Then the initial state must skip the bytes + that are not a single byte character nor the first byte of a multibyte + character. */ +static unsigned char const * +skip_remains_mb (struct dfa *d, unsigned char const *p, + unsigned char const *mbp, char const *end) +{ + wint_t wc; + while (mbp < p) + mbp += mbs_to_wchar (&wc, (char const *) mbp, + end - (char const *) mbp, d); + return mbp; +} + /* Search through a buffer looking for a match to the given struct dfa. Find the first occurrence of a string matching the regexp in the buffer, and the shortest possible version thereof. Return a pointer to @@ -3320,10 +3341,14 @@ transit_state (struct dfa *d, state_num s, unsigned char const **pp, If COUNT is non-NULL, increment *COUNT once for each newline processed. Finally, if BACKREF is non-NULL set *BACKREF to indicate whether we encountered a back-reference (1) or not (0). The caller may use this - to decide whether to fall back on a backtracking matcher. */ -char * -dfaexec (struct dfa *d, char const *begin, char *end, - int allow_nl, size_t *count, int *backref) + to decide whether to fall back on a backtracking matcher. + + If MULTIBYTE, the input consists of multibyte characters and/or + encoding-error bytes. Otherwise, the input consists of single-byte + characters. */ +static inline char * +dfaexec_main (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref, bool multibyte) { state_num s, s1; /* Current state. */ unsigned char const *p, *mbp; /* Current input character. */ @@ -3345,7 +3370,7 @@ dfaexec (struct dfa *d, char const *begin, char *end, saved_end = *(unsigned char *) end; *end = eol; - if (d->multibyte) + if (multibyte) { memset (&d->mbs, 0, sizeof d->mbs); if (! d->mb_match_lens) @@ -3357,7 +3382,7 @@ dfaexec (struct dfa *d, char const *begin, char *end, for (;;) { - if (d->multibyte) + if (multibyte) { while ((t = trans[s]) != NULL) { @@ -3365,27 +3390,18 @@ dfaexec (struct dfa *d, char const *begin, char *end, if (s == 0) { - /* The initial state may encounter a byte which is not - a single byte character nor the first byte of a - multibyte character. But it is incorrect for the - initial state to accept such a byte. For example, - in Shift JIS the regular expression "\\" accepts - the codepoint 0x5c, but should not accept the second - byte of the codepoint 0x815c. Then the initial - state must skip the bytes that are not a single - byte character nor the first byte of a multibyte - character. */ - wint_t wc; - while (mbp < p) - mbp += mbs_to_wchar (&wc, (char const *) mbp, - end - (char const *) mbp, d); - p = mbp; - - if ((char *) p > end) + if (d->states[s].mbps.nelem == 0) { - p = NULL; - goto done; + do + { + while (t[*p] == 0) + p++; + p = mbp = skip_remains_mb (d, p, mbp, end); + } + while (t[*p] == 0); } + else + p = mbp = skip_remains_mb (d, p, mbp, end); } if (d->states[s].mbps.nelem == 0) @@ -3413,6 +3429,13 @@ dfaexec (struct dfa *d, char const *begin, char *end, } else { + if (s == 0 && (t = trans[s]) != NULL) + { + while (t[*p] == 0) + p++; + s = t[*p++]; + } + while ((t = trans[s]) != NULL) { s1 = t[*p++]; @@ -3443,7 +3466,7 @@ dfaexec (struct dfa *d, char const *begin, char *end, } s1 = s; - if (d->multibyte) + if (multibyte) { /* Can match with a multibyte character (and multicharacter collating element). Transition table might be updated. */ @@ -3488,6 +3511,33 @@ dfaexec (struct dfa *d, char const *begin, char *end, return (char *) p; } +/* Specialized versions of dfaexec_main for multibyte and single-byte + cases. This is for performance. */ + +static char * +dfaexec_mb (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref) +{ + return dfaexec_main (d, begin, end, allow_nl, count, backref, true); +} + +static char * +dfaexec_sb (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref) +{ + return dfaexec_main (d, begin, end, allow_nl, count, backref, false); +} + +/* Like dfaexec_main (D, BEGIN, END, ALLOW_NL, COUNT, BACKREF, D->multibyte), + but faster. */ + +char * +dfaexec (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref) +{ + return d->dfaexec (d, begin, end, allow_nl, count, backref); +} + struct dfa * dfasuperset (struct dfa const *d) { @@ -3537,6 +3587,7 @@ dfainit (struct dfa *d) { memset (d, 0, sizeof *d); d->multibyte = MB_CUR_MAX > 1; + d->dfaexec = d->multibyte ? dfaexec_mb : dfaexec_sb; d->fast = !d->multibyte; } @@ -3577,6 +3628,7 @@ dfaoptimize (struct dfa *d) free_mbdata (d); d->multibyte = false; + d->dfaexec = dfaexec_sb; } static void @@ -3590,6 +3642,7 @@ dfassbuild (struct dfa *d) *sup = *d; sup->multibyte = false; + sup->dfaexec = dfaexec_sb; sup->multibyte_prop = NULL; sup->mbcsets = NULL; sup->superset = NULL; diff --git a/doc/ChangeLog b/doc/ChangeLog index 7693f5e5..e7faba83 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2014-09-28 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + Document the debugger's "where" command. + 2014-09-27 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Lots more fixes after reading through the MS. diff --git a/doc/gawk.info b/doc/gawk.info index c41ef683..a227afd6 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -19466,7 +19466,7 @@ File: gawk.info, Node: TCP/IP Networking, Next: Profiling, Prev: Two-way I/O, A host is a host from coast to coast, and no-one can talk to host that's close, unless the host that isn't close - is busy, hung, or dead. + is busy, hung, or dead. -- Mike O'Brien (aka Mr. Protocol) In addition to being able to open a two-way pipeline to a coprocess on the same system (*note Two-way I/O::), it is possible to make a two-way @@ -19595,9 +19595,9 @@ First, the `awk' program: profiler on this program and data. (This example also illustrates that `awk' programmers sometimes get up very early in the morning to work.) - # gawk profile, created Thu Feb 27 05:16:21 2014 + # gawk profile, created Mon Sep 29 05:16:21 2014 - # BEGIN block(s) + # BEGIN rule(s) BEGIN { 1 print "First BEGIN rule" @@ -19624,7 +19624,7 @@ profiler on this program and data. (This example also illustrates that } } - # END block(s) + # END rule(s) END { 1 print "First END rule" @@ -19710,7 +19710,7 @@ come out as: print $0 } -which is correct, but possibly surprising. +which is correct, but possibly unexpected. Besides creating profiles when a program has completed, `gawk' can produce a profile while it is running. This is useful if your `awk' @@ -19727,7 +19727,7 @@ The shell prints a job number and process ID number; in this case, $ kill -USR1 13992 As usual, the profiled version of the program is written to -`awkprof.out', or to a different file if one specified with the +`awkprof.out', or to a different file if one was specified with the `--profile' option. Along with the regular profile, as shown earlier, the profile file @@ -19771,7 +19771,8 @@ File: gawk.info, Node: Advanced Features Summary, Prev: Profiling, Up: Advanc * The `--non-decimal-data' option causes `gawk' to treat octal- and hexadecimal-looking input data as octal and hexadecimal. This option should be used with caution or not at all; use of - `strtonum()' is preferable. + `strtonum()' is preferable. Note that this option may disappear + in a future version of `gawk'. * You can take over complete control of sorting in `for (INDX in ARRAY)' array traversal by setting `PROCINFO["sorted_in"]' to the @@ -19790,9 +19791,9 @@ File: gawk.info, Node: Advanced Features Summary, Prev: Profiling, Up: Advanc coprocess completely, or optionally, close off one side of the two-way communications. - * By using special "file names" with the `|&' operator, you can open - a TCP/IP (or UDP/IP) connection to remote hosts in the Internet. - `gawk' supports both IPv4 an IPv6. + * By using special file names with the `|&' operator, you can open a + TCP/IP (or UDP/IP) connection to remote hosts in the Internet. + `gawk' supports both IPv4 and IPv6. * You can generate statement count profiles of your program. This can help you determine which parts of your program may be taking @@ -19953,7 +19954,7 @@ are: Character-type information (alphabetic, digit, upper- or lowercase, and so on) as well as character encoding. This information is accessed via the POSIX character classes in regular - expressions, such as `/[[:alnum:]]/' (*note Regexp Operators::). + expressions, such as `/[[:alnum:]]/' (*note Bracket Expressions::). `LC_MONETARY' Monetary information, such as the currency symbol, and whether the @@ -20021,8 +20022,8 @@ internationalization: Return the plural form used for NUMBER of the translation of STRING1 and STRING2 in text domain DOMAIN for locale category CATEGORY. STRING1 is the English singular variant of a message, - and STRING2 the English plural variant of the same message. The - default value for DOMAIN is the current value of `TEXTDOMAIN'. + and STRING2 is the English plural variant of the same message. + The default value for DOMAIN is the current value of `TEXTDOMAIN'. The default value for CATEGORY is `"LC_MESSAGES"'. The same remarks about argument order as for the `dcgettext()' @@ -20075,9 +20076,11 @@ outlined in *note Explaining gettext::, like so: one. This example would be better done with `dcngettext()': if (groggy) - message = dcngettext("%d customer disturbing me\n", "%d customers disturbing me\n", "adminprog") + message = dcngettext("%d customer disturbing me\n", + "%d customers disturbing me\n", "adminprog") else - message = dcngettext("enjoying %d customer\n", "enjoying %d customers\n", "adminprog") + message = dcngettext("enjoying %d customer\n", + "enjoying %d customers\n", "adminprog") printf(message, ncustomers) 4. During development, you might want to put the `.gmo' file in a @@ -20135,7 +20138,7 @@ marked and you've set (and perhaps bound) the text domain, it is time to produce translations. First, use the `--gen-pot' command-line option to create the initial `.pot' file: - $ gawk --gen-pot -f guide.awk > guide.pot + gawk --gen-pot -f guide.awk > guide.pot When run with `--gen-pot', `gawk' does not execute your program. Instead, it parses it as usual and prints all marked strings to @@ -20187,11 +20190,11 @@ example, `string' is the first argument and `length(string)' is the second: $ gawk 'BEGIN { - > string = "Dont Panic" + > string = "Don\47t Panic" > printf "%2$d characters live in \"%1$s\"\n", > string, length(string) > }' - -| 10 characters live in "Dont Panic" + -| 11 characters live in "Don't Panic" If present, positional specifiers come first in the format specification, before the flags, the field width, and/or the precision. @@ -20352,7 +20355,8 @@ Following are the translations: The next step is to make the directory to hold the binary message object file and then to create the `guide.mo' file. We pretend that -our file is to be used in the `en_US.UTF-8' locale. The directory +our file is to be used in the `en_US.UTF-8' locale, since we have to +use a locale name known to the C `gettext' routines. The directory layout shown here is standard for GNU `gettext' on GNU/Linux systems. Other versions of `gettext' may use a different layout: @@ -20361,7 +20365,7 @@ Other versions of `gettext' may use a different layout: The `msgfmt' utility does the conversion from human-readable `.po' file to machine-readable `.mo' file. By default, `msgfmt' creates a file named `messages'. This file must be renamed and placed in the -proper directory so that `gawk' can find it: +proper directory (using the `-o' option) so that `gawk' can find it: $ msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo @@ -20394,8 +20398,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.1 -(ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.1.tar.gz). +writing, the latest version of GNU `gettext' is version 0.19.2 +(ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.2.tar.gz). If a translation of `gawk''s messages exists, then `gawk' produces usage messages, warnings, and fatal errors in the local language. @@ -20480,7 +20484,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 `awk' +ahead to the next section on the specific features of the `gawk' debugger.) Of course, a debugging program cannot remove bugs for you, since it @@ -20516,8 +20520,8 @@ functional program that you or someone else wrote). File: gawk.info, Node: Debugging Terms, Next: Awk Debugging, Prev: Debugging Concepts, Up: Debugging -14.1.2 Additional Debugging Concepts ------------------------------------- +14.1.2 Debugging Concepts +------------------------- Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list @@ -20609,13 +20613,13 @@ File: gawk.info, Node: Debugger Invocation, Next: Finding The Bug, Up: Sample 14.2.1 How to Start the Debugger -------------------------------- -Starting the debugger is almost exactly like running `gawk', 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 the debugger like -this: +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 +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 +the debugger like this: $ gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile @@ -20624,7 +20628,7 @@ users of GDB or similar debuggers should note that this syntax is slightly different from what they 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.) +debugger prompt.) The `-1' is an option to `uniq.awk'. Instead of immediately running the program on `inputfile', as `gawk' would ordinarily do, the debugger merely loads all the program source @@ -20772,9 +20776,9 @@ split into, so we try to look: This is kind of disappointing, though. All we found out is that there are five elements in `alast'; `m' and `aline' don't have values -yet since we are at line 68 but haven't executed it yet. This -information is useful enough (we now know that none of the words were -accidentally left out), but what if we want to see inside the array? +since we are at line 68 but haven't executed it yet. This information +is useful enough (we now know that none of the words were accidentally +left out), but what if we want to see inside the array? The first choice would be to use subscripts: @@ -20924,13 +20928,13 @@ controlling breakpoints are: `condition' N `"EXPRESSION"' Add a condition to existing breakpoint or watchpoint N. The - condition is an `awk' expression that the debugger evaluates - whenever the breakpoint or watchpoint is reached. If the condition - is true, then the debugger stops execution and prompts for a - command. Otherwise, the debugger continues executing the program. - If the condition expression is not specified, any existing - condition is removed; i.e., the breakpoint or watchpoint is made - unconditional. + condition is an `awk' expression _enclosed in double quotes_ that + the debugger evaluates whenever the breakpoint or watchpoint is + reached. If the condition is true, then the debugger stops + execution and prompts for a command. Otherwise, the debugger + continues executing the program. If the condition expression is + not specified, any existing condition is removed; i.e., the + breakpoint or watchpoint is made unconditional. `delete' [N1 N2 ...] [N-M] `d' [N1 N2 ...] [N-M] @@ -21049,9 +21053,9 @@ execution of the program than we saw in our earlier example: `until' [[FILENAME`:']N | FUNCTION] `u' [[FILENAME`:']N | FUNCTION] Without any argument, continue execution until a line past the - current line in current stack frame is reached. With an argument, - continue execution until the specified location is reached, or the - current stack frame returns. + current line in the current stack frame is reached. With an + argument, continue execution until the specified location is + reached, or the current stack frame returns. File: gawk.info, Node: Viewing And Changing Data, Next: Execution Stack, Prev: Debugger Execution Control, Up: List of Debugger Commands @@ -21098,9 +21102,9 @@ AWK STATEMENTS This prints the third field in the input record (if the specified field does not exist, it prints `Null field'). A variable can be - an array element, with the subscripts being constant values. To - print the contents of an array, prefix the name of the array with - the `@' symbol: + an array element, with the subscripts being constant string + values. To print the contents of an array, prefix the name of the + array with the `@' symbol: gawk> print @a @@ -21145,7 +21149,7 @@ AWK STATEMENTS File: gawk.info, Node: Execution Stack, Next: Debugger Info, Prev: Viewing And Changing Data, Up: List of Debugger Commands -14.3.4 Dealing with the Stack +14.3.4 Working with the Stack ----------------------------- Whenever you run a program which contains any function calls, `gawk' @@ -21157,11 +21161,13 @@ are: `backtrace' [COUNT] `bt' [COUNT] +`where' [COUNT] Print a backtrace of all function calls (stack frames), or innermost COUNT frames if COUNT > 0. Print the outermost COUNT frames if COUNT < 0. The backtrace displays the name and arguments to each function, the source file name, and the line - number. + number. The alias `where' for `backtrace' is provided for + long-time GDB users who may be used to that command. `down' [COUNT] Move COUNT (default 1) frames down the stack toward the innermost @@ -21198,7 +21204,7 @@ know: The value for WHAT should be one of the following: `args' - Arguments of the selected frame. + List arguments of the selected frame. `break' List all currently set breakpoints. @@ -21207,19 +21213,19 @@ know: List all items in the automatic display list. `frame' - Description of the selected stack frame. + Give a description of the selected stack frame. `functions' List all function definitions including source file names and line numbers. `locals' - Local variables of the selected frame. + List local variables of the selected frame. `source' - The name of the current source file. Each time the program - stops, the current source file is the file containing the - current instruction. When the debugger first starts, the + Print the name of the current source file. Each time the + program stops, the current source file is the file containing + the current instruction. When the debugger first starts, the current source file is the first file included via the `-f' option. The `list FILENAME:LINENO' command can be used at any time to change the current source. @@ -21367,7 +21373,7 @@ categories, as follows: or the file named FILENAME. The possible arguments to `list' are as follows: - `-' + `-' (Minus) Print lines before the lines last printed. `+' @@ -21438,8 +21444,8 @@ Variable name completion File: gawk.info, Node: Limitations, Next: Debugging Summary, Prev: Readline Support, Up: Debugger -14.5 Limitations and Future Plans -================================= +14.5 Limitations +================ 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 @@ -21478,10 +21484,6 @@ some limitations. A few which are worth being aware of are: * The `gawk' debugger only accepts source supplied with the `-f' option. - Look forward to a future release when these and other missing -features may be added, and of course feel free to try to add them -yourself! - File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger @@ -21518,8 +21520,7 @@ File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic Extension ************************************************************ This major node introduces some basic concepts relating to how -computers do arithmetic and briefly lists the features in `gawk' for -performing arbitrary precision floating point computations. It then +computers do arithmetic and defines some important terms. It then proceeds to describe floating-point arithmetic, which is what `awk' uses for all its computations, including a discussion of arbitrary precision floating point arithmetic, which is a feature available only @@ -21614,7 +21615,8 @@ Floating point arithmetic ranges. Integer values are usually either 32 or 64 bits in size. Single precision floating point values occupy 32 bits, whereas double precision floating point values occupy 64 bits. Floating point values are always -signed. The possible ranges of values are shown in the following table. +signed. The possible ranges of values are shown in *note +table-numeric-ranges::. Numeric representation Miniumum value Maximum value --------------------------------------------------------------------------- @@ -21629,6 +21631,8 @@ Double precision `2.225074e-308' `1.797693e+308' floating point (approximate) +Table 15.1: Value Ranges for Different Numeric Representations + ---------- Footnotes ---------- (1) We don't know why they expect this, but they do. @@ -21661,7 +21665,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 @@ -21719,21 +21723,22 @@ 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: -Name Total bits Precision emin emax +Name Total bits Precision Minimum Maximum + exponent exponent --------------------------------------------------------------------------- Single 32 24 -126 +127 Double 64 53 -1022 +1023 Quadruple 128 113 -16382 +16383 -Table 15.1: Basic IEEE Format Context Values +Table 15.2: Basic IEEE Format Values NOTE: The precision numbers include the implied leading one that gives them one extra bit of significand. ---------- Footnotes ---------- - (1) Thanks to Michael Brennan for this description, which I have -paraphrased, and for the examples + (1) Thanks to Michael Brennan for this description, which we have +paraphrased, and for the examples. File: gawk.info, Node: MPFR features, Next: FP Math Caution, Prev: Math Definitions, Up: Arbitrary Precision Arithmetic @@ -21741,15 +21746,15 @@ File: gawk.info, Node: MPFR features, Next: FP Math Caution, Prev: Math Defin 15.3 Arbitrary Precison Arithmetic Features In `gawk' ===================================================== -By default, `gawk' uses the double precision floating point values +By default, `gawk' uses the double precision floating-point values supplied by the hardware of the system it runs on. However, if it was -compiled to do, `gawk' uses the GNU MPFR (http://www.mpfr.org) and GNU -MP (http://gmplib.org) (GMP) libraries for arbitrary precision +compiled to do so, `gawk' uses the `http://www.mpfr.org GNU MPFR' and +GNU MP (http://gmplib.org) (GMP) libraries for arbitrary precision arithmetic on numbers. You can see if MPFR support is available like so: $ gawk --version - -| GNU Awk 4.1.1, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) + -| GNU Awk 4.1.2, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) -| Copyright (C) 1989, 1991-2014 Free Software Foundation. ... @@ -21770,7 +21775,8 @@ results to any desired precision level supported by MPFR. Two built-in variables, `PREC' and `ROUNDMODE', provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. *Note -Auto-set::, for more information. +Setting precision::, and *note Setting the rounding mode::, for more +information. File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers, Prev: MPFR features, Up: Arbitrary Precision Arithmetic @@ -21884,6 +21890,9 @@ you. Code to do this looks something like this: else # not ok +(We assume that you have a simple absolute value function named `abs()' +defined elsewhere in your program.) + File: gawk.info, Node: Errors accumulate, Prev: Comparing FP Values, Up: Inexactness of computations @@ -21966,7 +21975,7 @@ forget that the finite number of bits used to store the value is often just an approximation after proper rounding. The test for equality succeeds if and only if _all_ bits in the two operands are exactly the same. Since this is not necessarily true after floating-point -computations with a particular precision and effective rounding rule, a +computations with a particular precision and effective rounding mode, a straight test for equality may not work. Instead, compare the two numbers to see if they are within the desirable delta of each other. @@ -22042,7 +22051,7 @@ binary format. `"quad"' Basic 128-bit quadruple precision. `"oct"' 256-bit octuple precision. -Table 15.2: Predefined Precision Strings For `PREC' +Table 15.3: Predefined Precision Strings For `PREC' The following example illustrates the effects of changing precision on arithmetic operations: @@ -22056,7 +22065,7 @@ on arithmetic operations: floating-point constant from program source code, `gawk' uses the default precision (that of a C `double'), unless overridden by an assignment to the special variable `PREC' on the command line, to - store it internally as a MPFR number. Changing the precision + store it internally as an MPFR number. Changing the precision using `PREC' in the program text does _not_ change the precision of a constant. @@ -22095,10 +22104,10 @@ Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero -Table 15.3: `gawk' Rounding Modes +Table 15.4: `gawk' Rounding Modes `ROUNDMODE' has the default value `"N"', which selects the IEEE 754 -rounding mode `roundTiesToEven'. In *note Table 15.3: +rounding mode `roundTiesToEven'. In *note Table 15.4: table-gawk-rounding-modes, the value `"A"' selects `roundTiesToAway'. This is only available if your version of the MPFR library supports it; otherwise setting `ROUNDMODE' to `"A"' has no effect. @@ -22177,15 +22186,15 @@ using GMP arbitrary precision integers. Any number that looks like an integer in a source or data file is stored as an arbitrary precision integer. The size of the integer is limited only by the available memory. For example, the following computes 5^4^3^2, the result of -which is beyond the limits of ordinary hardware double-precision +which is beyond the limits of ordinary hardware double precision floating point values: $ gawk -M 'BEGIN { > x = 5^4^3^2 - > print "# of digits =", length(x) + > print "number of digits =", length(x) > print substr(x, 1, 20), "...", substr(x, length(x) - 19, 20) > }' - -| # of digits = 183231 + -| number of digits = 183231 -| 62060698786608744707 ... 92256259918212890625 If instead you were to compute the same value using arbitrary @@ -22360,8 +22369,8 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob ============ * Most computer arithmetic is done using either integers or - floating-point values. The default for `awk' is to use - double-precision floating-point values. + floating-point values. Standard `awk' uses double precision + floating-point values. * In the early 1990's, Barbie mistakenly said "Math class is tough!" While math isn't tough, floating-point arithmetic isn't the same @@ -22462,7 +22471,7 @@ write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the "Application 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 sample +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 Extension Design::, for a discussion of the extension mechanism goals @@ -22474,10 +22483,13 @@ File: gawk.info, Node: Plugin License, Next: Extension Mechanism Outline, Pre 16.2 Extension Licensing ======================== -Every dynamic extension should define the global symbol -`plugin_is_GPL_compatible' to assert that it has been licensed under a -GPL-compatible license. If this symbol does not exist, `gawk' emits a -fatal error and exits when it tries to load your extension. +Every dynamic extension must be distributed under a license that is +compatible with the GNU GPL (*note Copying::). + + In order for the extension to tell `gawk' that it is properly +licensed, the extension must define the global symbol +`plugin_is_GPL_compatible'. If this symbol does not exist, `gawk' +emits a fatal error and exits when it tries to load your extension. The declared type of the symbol should be `int'. It does not need to be in any allocated section, though. The code merely asserts that @@ -22492,7 +22504,7 @@ File: gawk.info, Node: Extension Mechanism Outline, Next: Extension API Descri ================================= Communication between `gawk' and an extension is two-way. First, when -an extension is loaded, it is passed a pointer to a `struct' whose +an extension is loaded, `gawk' passes it a pointer to a `struct' whose fields are function pointers. This is shown in *note figure-load-extension::. @@ -22525,8 +22537,8 @@ Figure 16.1: Loading The Extension The extension can call functions inside `gawk' through these function pointers, at runtime, without needing (link-time) access to `gawk''s symbols. One of these function pointers is to a function for -"registering" new built-in functions. This is shown in *note -figure-load-new-function::. +"registering" new functions. This is shown in *note +figure-register-new-function::. register_ext_func({ "chdir", do_chdir, 1 }); @@ -22540,7 +22552,7 @@ figure-load-new-function::. +-------+-+---+-+---+-+------------------+--------------+-+---+ gawk Main Program Address Space Extension -Figure 16.2: Loading The New Function +Figure 16.2: Registering A New Function In the other direction, the extension registers its new functions with `gawk' by passing function pointers to the functions that provide @@ -22573,8 +22585,8 @@ and understandable. Although all of this sounds somewhat complicated, the result is that extension code is quite straightforward to write and to read. You can -see this in the sample extensions `filefuncs.c' (*note Extension -Example::) and also the `testext.c' code for testing the APIs. +see this in the sample extension `filefuncs.c' (*note Extension +Example::) and also in the `testext.c' code for testing the APIs. Some other bits and pieces: @@ -22728,7 +22740,7 @@ operations: * When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type - (number, string, scalars, value cookie, array, or "undefined"). + (number, string, scalar, value cookie, array, or "undefined"). When the request is "undefined," the returned value will have the real underlying type. @@ -22872,7 +22884,7 @@ 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 first find it. +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 @@ -31239,10 +31251,10 @@ Index * .gmo files: Explaining gettext. (line 42) * .gmo files, specifying directory of <1>: Programmer i18n. (line 47) * .gmo files, specifying directory of: Explaining gettext. (line 54) -* .mo files, converting from .po: I18N Example. (line 63) +* .mo files, converting from .po: I18N Example. (line 64) * .po files <1>: Translator i18n. (line 6) * .po files: Explaining gettext. (line 37) -* .po files, converting to .mo: I18N Example. (line 63) +* .po files, converting to .mo: I18N Example. (line 64) * .pot files: Explaining gettext. (line 31) * / (forward slash) to enclose regular expressions: Regexp. (line 10) * / (forward slash), / operator: Precedence. (line 55) @@ -32005,7 +32017,7 @@ Index * debugger commands, disable: Breakpoint Control. (line 69) * debugger commands, display: Viewing And Changing Data. (line 8) -* debugger commands, down: Execution Stack. (line 21) +* debugger commands, down: Execution Stack. (line 23) * debugger commands, dump: Miscellaneous Debugger Commands. (line 9) * debugger commands, e (enable): Breakpoint Control. (line 73) @@ -32014,10 +32026,10 @@ Index (line 10) * debugger commands, eval: Viewing And Changing Data. (line 23) -* debugger commands, f (frame): Execution Stack. (line 25) +* debugger commands, f (frame): Execution Stack. (line 27) * debugger commands, finish: Debugger Execution Control. (line 39) -* debugger commands, frame: Execution Stack. (line 25) +* debugger commands, frame: Execution Stack. (line 27) * debugger commands, h (help): Miscellaneous Debugger Commands. (line 66) * debugger commands, help: Miscellaneous Debugger Commands. @@ -32079,11 +32091,12 @@ Index (line 83) * debugger commands, unwatch: Viewing And Changing Data. (line 84) -* debugger commands, up: Execution Stack. (line 34) +* debugger commands, up: Execution Stack. (line 36) * debugger commands, w (watch): Viewing And Changing Data. (line 67) * debugger commands, watch: Viewing And Changing Data. (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 size: Debugger Info. (line 65) @@ -32208,7 +32221,7 @@ Index * dollar sign ($), regexp operator: Regexp Operators. (line 35) * double quote ("), in regexp constants: Computed Regexps. (line 29) * double quote ("), in shell commands: Quoting. (line 54) -* down debugger command: Execution Stack. (line 21) +* down debugger command: Execution Stack. (line 23) * Drepper, Ulrich: Acknowledgments. (line 52) * dump all variables of a program: Options. (line 93) * dump debugger command: Miscellaneous Debugger Commands. @@ -32367,7 +32380,7 @@ Index * extract.awk program: Extract Program. (line 79) * extraction, of marked strings (internationalization): String Extraction. (line 6) -* f debugger command (alias for frame): Execution Stack. (line 25) +* f debugger command (alias for frame): Execution Stack. (line 27) * false, logical: Truth Values. (line 6) * FDL (Free Documentation License): GNU Free Documentation License. (line 7) @@ -32423,10 +32436,10 @@ Index * files, .gmo: Explaining gettext. (line 42) * files, .gmo, specifying directory of <1>: Programmer i18n. (line 47) * files, .gmo, specifying directory of: Explaining gettext. (line 54) -* files, .mo, converting from .po: I18N Example. (line 63) +* files, .mo, converting from .po: I18N Example. (line 64) * files, .po <1>: Translator i18n. (line 6) * files, .po: Explaining gettext. (line 37) -* files, .po, converting to .mo: I18N Example. (line 63) +* files, .po, converting to .mo: I18N Example. (line 64) * files, .pot: Explaining gettext. (line 31) * files, /dev/... special files: Special FD. (line 48) * files, /inet/... (gawk): TCP/IP Networking. (line 6) @@ -32446,7 +32459,7 @@ Index * files, managing, data file boundaries: Filetrans Function. (line 6) * files, message object: Explaining gettext. (line 42) * files, message object, converting from portable object files: I18N Example. - (line 63) + (line 64) * files, message object, specifying directory of <1>: Programmer i18n. (line 47) * files, message object, specifying directory of: Explaining gettext. @@ -32460,7 +32473,7 @@ Index * files, portable object: Explaining gettext. (line 37) * files, portable object template: Explaining gettext. (line 31) * files, portable object, converting to message object files: I18N Example. - (line 63) + (line 64) * files, portable object, generating: Options. (line 147) * files, processing, ARGIND variable and: Auto-set. (line 51) * files, reading: Rewind Function. (line 6) @@ -32511,7 +32524,7 @@ Index * FPAT variable <1>: User-modified. (line 43) * FPAT variable: Splitting By Content. (line 27) -* frame debugger command: Execution Stack. (line 25) +* frame debugger command: Execution Stack. (line 27) * Free Documentation License (FDL): GNU Free Documentation License. (line 7) * Free Software Foundation (FSF) <1>: Glossary. (line 296) @@ -32925,7 +32938,7 @@ Index * LC_CTYPE locale category: Explaining gettext. (line 98) * LC_MESSAGES locale category: Explaining gettext. (line 88) * LC_MESSAGES locale category, bindtextdomain() function (gawk): Programmer i18n. - (line 99) + (line 101) * LC_MONETARY locale category: Explaining gettext. (line 104) * LC_NUMERIC locale category: Explaining gettext. (line 108) * LC_TIME locale category: Explaining gettext. (line 112) @@ -33053,7 +33066,7 @@ Index * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 42) * message object files, converting from portable object files: I18N Example. - (line 63) + (line 64) * message object files, specifying directory of <1>: Programmer i18n. (line 47) * message object files, specifying directory of: Explaining gettext. @@ -33066,7 +33079,7 @@ Index * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 104) * Moore, Duncan: Getline Notes. (line 40) -* msgfmt utility: I18N Example. (line 63) +* msgfmt utility: I18N Example. (line 64) * multiple precision: Arbitrary Precision Arithmetic. (line 6) * multiple-line records: Multiple Line. (line 6) @@ -33307,7 +33320,7 @@ Index * portable object files <1>: Translator i18n. (line 6) * portable object files: Explaining gettext. (line 37) * portable object files, converting to message object files: I18N Example. - (line 63) + (line 64) * portable object files, generating: Options. (line 147) * portable object template files: Explaining gettext. (line 31) * porting gawk: New Ports. (line 6) @@ -34006,7 +34019,7 @@ Index (line 83) * unwatch debugger command: Viewing And Changing Data. (line 84) -* up debugger command: Execution Stack. (line 34) +* up debugger command: Execution Stack. (line 36) * user database, reading: Passwd Functions. (line 6) * user-defined functions: User-defined. (line 6) * user-defined, functions, counts, in a profile: Profiling. (line 137) @@ -34080,6 +34093,9 @@ Index * wc.awk program: Wc Program. (line 46) * Weinberger, Peter <1>: Contributors. (line 11) * Weinberger, Peter: History. (line 17) +* where debugger command: Execution Stack. (line 13) +* where debugger command (alias for backtrace): Execution Stack. + (line 13) * while statement: While Statement. (line 6) * while statement, use of regexps in: Regexp Usage. (line 19) * whitespace, as field separators: Default Field Splitting. @@ -34484,210 +34500,211 @@ Node: Two-way I/O784391 Ref: Two-way I/O-Footnote-1789335 Ref: Two-way I/O-Footnote-2789521 Node: TCP/IP Networking789603 -Node: Profiling792444 -Node: Advanced Features Summary799995 -Node: Internationalization801856 -Node: I18N and L10N803336 -Node: Explaining gettext804022 -Ref: Explaining gettext-Footnote-1809048 -Ref: Explaining gettext-Footnote-2809232 -Node: Programmer i18n809397 -Ref: Programmer i18n-Footnote-1814191 -Node: Translator i18n814240 -Node: String Extraction815034 -Ref: String Extraction-Footnote-1816167 -Node: Printf Ordering816253 -Ref: Printf Ordering-Footnote-1819035 -Node: I18N Portability819099 -Ref: I18N Portability-Footnote-1821548 -Node: I18N Example821611 -Ref: I18N Example-Footnote-1824317 -Node: Gawk I18N824389 -Node: I18N Summary825027 -Node: Debugger826366 -Node: Debugging827388 -Node: Debugging Concepts827829 -Node: Debugging Terms829685 -Node: Awk Debugging832282 -Node: Sample Debugging Session833174 -Node: Debugger Invocation833694 -Node: Finding The Bug835030 -Node: List of Debugger Commands841509 -Node: Breakpoint Control842841 -Node: Debugger Execution Control846505 -Node: Viewing And Changing Data849865 -Node: Execution Stack853223 -Node: Debugger Info854736 -Node: Miscellaneous Debugger Commands858730 -Node: Readline Support863914 -Node: Limitations864806 -Node: Debugging Summary867079 -Node: Arbitrary Precision Arithmetic868247 -Node: Computer Arithmetic869734 -Ref: Computer Arithmetic-Footnote-1874121 -Node: Math Definitions874178 -Ref: table-ieee-formats877467 -Ref: Math Definitions-Footnote-1878007 -Node: MPFR features878110 -Node: FP Math Caution879727 -Ref: FP Math Caution-Footnote-1880777 -Node: Inexactness of computations881146 -Node: Inexact representation882094 -Node: Comparing FP Values883449 -Node: Errors accumulate884413 -Node: Getting Accuracy885846 -Node: Try To Round888505 -Node: Setting precision889404 -Ref: table-predefined-precision-strings890086 -Node: Setting the rounding mode891879 -Ref: table-gawk-rounding-modes892243 -Ref: Setting the rounding mode-Footnote-1895697 -Node: Arbitrary Precision Integers895876 -Ref: Arbitrary Precision Integers-Footnote-1899649 -Node: POSIX Floating Point Problems899798 -Ref: POSIX Floating Point Problems-Footnote-1903674 -Node: Floating point summary903712 -Node: Dynamic Extensions905916 -Node: Extension Intro907468 -Node: Plugin License908733 -Node: Extension Mechanism Outline909418 -Ref: figure-load-extension909842 -Ref: figure-load-new-function911327 -Ref: figure-call-new-function912329 -Node: Extension API Description914313 -Node: Extension API Functions Introduction915763 -Node: General Data Types920630 -Ref: General Data Types-Footnote-1926323 -Node: Requesting Values926622 -Ref: table-value-types-returned927359 -Node: Memory Allocation Functions928317 -Ref: Memory Allocation Functions-Footnote-1931064 -Node: Constructor Functions931160 -Node: Registration Functions932918 -Node: Extension Functions933603 -Node: Exit Callback Functions935905 -Node: Extension Version String937153 -Node: Input Parsers937803 -Node: Output Wrappers947617 -Node: Two-way processors952133 -Node: Printing Messages954337 -Ref: Printing Messages-Footnote-1955414 -Node: Updating `ERRNO'955566 -Node: Accessing Parameters956305 -Node: Symbol Table Access957535 -Node: Symbol table by name958049 -Node: Symbol table by cookie960025 -Ref: Symbol table by cookie-Footnote-1964158 -Node: Cached values964221 -Ref: Cached values-Footnote-1967725 -Node: Array Manipulation967816 -Ref: Array Manipulation-Footnote-1968914 -Node: Array Data Types968953 -Ref: Array Data Types-Footnote-1971656 -Node: Array Functions971748 -Node: Flattening Arrays975622 -Node: Creating Arrays982474 -Node: Extension API Variables987205 -Node: Extension Versioning987841 -Node: Extension API Informational Variables989742 -Node: Extension API Boilerplate990828 -Node: Finding Extensions994632 -Node: Extension Example995192 -Node: Internal File Description995922 -Node: Internal File Ops1000013 -Ref: Internal File Ops-Footnote-11011445 -Node: Using Internal File Ops1011585 -Ref: Using Internal File Ops-Footnote-11013932 -Node: Extension Samples1014200 -Node: Extension Sample File Functions1015724 -Node: Extension Sample Fnmatch1023292 -Node: Extension Sample Fork1024774 -Node: Extension Sample Inplace1025987 -Node: Extension Sample Ord1027662 -Node: Extension Sample Readdir1028498 -Ref: table-readdir-file-types1029354 -Node: Extension Sample Revout1030153 -Node: Extension Sample Rev2way1030744 -Node: Extension Sample Read write array1031485 -Node: Extension Sample Readfile1033364 -Node: Extension Sample API Tests1034464 -Node: Extension Sample Time1034989 -Node: gawkextlib1036304 -Node: Extension summary1039117 -Node: Extension Exercises1042810 -Node: Language History1043532 -Node: V7/SVR3.11045175 -Node: SVR41047495 -Node: POSIX1048937 -Node: BTL1050323 -Node: POSIX/GNU1051057 -Node: Feature History1056833 -Node: Common Extensions1069924 -Node: Ranges and Locales1071236 -Ref: Ranges and Locales-Footnote-11075853 -Ref: Ranges and Locales-Footnote-21075880 -Ref: Ranges and Locales-Footnote-31076114 -Node: Contributors1076335 -Node: History summary1081760 -Node: Installation1083129 -Node: Gawk Distribution1084080 -Node: Getting1084564 -Node: Extracting1085388 -Node: Distribution contents1087030 -Node: Unix Installation1092800 -Node: Quick Installation1093417 -Node: Additional Configuration Options1095859 -Node: Configuration Philosophy1097597 -Node: Non-Unix Installation1099948 -Node: PC Installation1100406 -Node: PC Binary Installation1101717 -Node: PC Compiling1103565 -Ref: PC Compiling-Footnote-11106564 -Node: PC Testing1106669 -Node: PC Using1107845 -Node: Cygwin1111997 -Node: MSYS1112806 -Node: VMS Installation1113304 -Node: VMS Compilation1114100 -Ref: VMS Compilation-Footnote-11115322 -Node: VMS Dynamic Extensions1115380 -Node: VMS Installation Details1116753 -Node: VMS Running1119005 -Node: VMS GNV1121839 -Node: VMS Old Gawk1122562 -Node: Bugs1123032 -Node: Other Versions1127036 -Node: Installation summary1133260 -Node: Notes1134316 -Node: Compatibility Mode1135181 -Node: Additions1135963 -Node: Accessing The Source1136888 -Node: Adding Code1138324 -Node: New Ports1144502 -Node: Derived Files1148983 -Ref: Derived Files-Footnote-11154458 -Ref: Derived Files-Footnote-21154492 -Ref: Derived Files-Footnote-31155088 -Node: Future Extensions1155202 -Node: Implementation Limitations1155808 -Node: Extension Design1157056 -Node: Old Extension Problems1158210 -Ref: Old Extension Problems-Footnote-11159727 -Node: Extension New Mechanism Goals1159784 -Ref: Extension New Mechanism Goals-Footnote-11163144 -Node: Extension Other Design Decisions1163333 -Node: Extension Future Growth1165439 -Node: Old Extension Mechanism1166275 -Node: Notes summary1168037 -Node: Basic Concepts1169223 -Node: Basic High Level1169904 -Ref: figure-general-flow1170176 -Ref: figure-process-flow1170775 -Ref: Basic High Level-Footnote-11174004 -Node: Basic Data Typing1174189 -Node: Glossary1177517 -Node: Copying1202669 -Node: GNU Free Documentation License1240225 -Node: Index1265361 +Node: Profiling792480 +Node: Advanced Features Summary800033 +Node: Internationalization801966 +Node: I18N and L10N803446 +Node: Explaining gettext804132 +Ref: Explaining gettext-Footnote-1809161 +Ref: Explaining gettext-Footnote-2809345 +Node: Programmer i18n809510 +Ref: Programmer i18n-Footnote-1814376 +Node: Translator i18n814425 +Node: String Extraction815219 +Ref: String Extraction-Footnote-1816350 +Node: Printf Ordering816436 +Ref: Printf Ordering-Footnote-1819222 +Node: I18N Portability819286 +Ref: I18N Portability-Footnote-1821735 +Node: I18N Example821798 +Ref: I18N Example-Footnote-1824598 +Node: Gawk I18N824670 +Node: I18N Summary825308 +Node: Debugger826647 +Node: Debugging827669 +Node: Debugging Concepts828110 +Node: Debugging Terms829967 +Node: Awk Debugging832542 +Node: Sample Debugging Session833434 +Node: Debugger Invocation833954 +Node: Finding The Bug835338 +Node: List of Debugger Commands841813 +Node: Breakpoint Control843145 +Node: Debugger Execution Control846837 +Node: Viewing And Changing Data850201 +Node: Execution Stack853566 +Node: Debugger Info855204 +Node: Miscellaneous Debugger Commands859221 +Node: Readline Support864413 +Node: Limitations865305 +Node: Debugging Summary867402 +Node: Arbitrary Precision Arithmetic868570 +Node: Computer Arithmetic869986 +Ref: table-numeric-ranges873587 +Ref: Computer Arithmetic-Footnote-1874446 +Node: Math Definitions874503 +Ref: table-ieee-formats877790 +Ref: Math Definitions-Footnote-1878394 +Node: MPFR features878499 +Node: FP Math Caution880167 +Ref: FP Math Caution-Footnote-1881217 +Node: Inexactness of computations881586 +Node: Inexact representation882534 +Node: Comparing FP Values883889 +Node: Errors accumulate884962 +Node: Getting Accuracy886395 +Node: Try To Round889054 +Node: Setting precision889953 +Ref: table-predefined-precision-strings890635 +Node: Setting the rounding mode892429 +Ref: table-gawk-rounding-modes892793 +Ref: Setting the rounding mode-Footnote-1896247 +Node: Arbitrary Precision Integers896426 +Ref: Arbitrary Precision Integers-Footnote-1900209 +Node: POSIX Floating Point Problems900358 +Ref: POSIX Floating Point Problems-Footnote-1904234 +Node: Floating point summary904272 +Node: Dynamic Extensions906464 +Node: Extension Intro908016 +Node: Plugin License909282 +Node: Extension Mechanism Outline910079 +Ref: figure-load-extension910507 +Ref: figure-register-new-function911987 +Ref: figure-call-new-function912991 +Node: Extension API Description914977 +Node: Extension API Functions Introduction916427 +Node: General Data Types921293 +Ref: General Data Types-Footnote-1926986 +Node: Requesting Values927285 +Ref: table-value-types-returned928022 +Node: Memory Allocation Functions928980 +Ref: Memory Allocation Functions-Footnote-1931727 +Node: Constructor Functions931823 +Node: Registration Functions933581 +Node: Extension Functions934266 +Node: Exit Callback Functions936568 +Node: Extension Version String937816 +Node: Input Parsers938466 +Node: Output Wrappers948280 +Node: Two-way processors952796 +Node: Printing Messages955000 +Ref: Printing Messages-Footnote-1956077 +Node: Updating `ERRNO'956229 +Node: Accessing Parameters956968 +Node: Symbol Table Access958198 +Node: Symbol table by name958712 +Node: Symbol table by cookie960688 +Ref: Symbol table by cookie-Footnote-1964821 +Node: Cached values964884 +Ref: Cached values-Footnote-1968388 +Node: Array Manipulation968479 +Ref: Array Manipulation-Footnote-1969577 +Node: Array Data Types969616 +Ref: Array Data Types-Footnote-1972319 +Node: Array Functions972411 +Node: Flattening Arrays976285 +Node: Creating Arrays983137 +Node: Extension API Variables987868 +Node: Extension Versioning988504 +Node: Extension API Informational Variables990405 +Node: Extension API Boilerplate991491 +Node: Finding Extensions995295 +Node: Extension Example995855 +Node: Internal File Description996585 +Node: Internal File Ops1000676 +Ref: Internal File Ops-Footnote-11012108 +Node: Using Internal File Ops1012248 +Ref: Using Internal File Ops-Footnote-11014595 +Node: Extension Samples1014863 +Node: Extension Sample File Functions1016387 +Node: Extension Sample Fnmatch1023955 +Node: Extension Sample Fork1025437 +Node: Extension Sample Inplace1026650 +Node: Extension Sample Ord1028325 +Node: Extension Sample Readdir1029161 +Ref: table-readdir-file-types1030017 +Node: Extension Sample Revout1030816 +Node: Extension Sample Rev2way1031407 +Node: Extension Sample Read write array1032148 +Node: Extension Sample Readfile1034027 +Node: Extension Sample API Tests1035127 +Node: Extension Sample Time1035652 +Node: gawkextlib1036967 +Node: Extension summary1039780 +Node: Extension Exercises1043473 +Node: Language History1044195 +Node: V7/SVR3.11045838 +Node: SVR41048158 +Node: POSIX1049600 +Node: BTL1050986 +Node: POSIX/GNU1051720 +Node: Feature History1057496 +Node: Common Extensions1070587 +Node: Ranges and Locales1071899 +Ref: Ranges and Locales-Footnote-11076516 +Ref: Ranges and Locales-Footnote-21076543 +Ref: Ranges and Locales-Footnote-31076777 +Node: Contributors1076998 +Node: History summary1082423 +Node: Installation1083792 +Node: Gawk Distribution1084743 +Node: Getting1085227 +Node: Extracting1086051 +Node: Distribution contents1087693 +Node: Unix Installation1093463 +Node: Quick Installation1094080 +Node: Additional Configuration Options1096522 +Node: Configuration Philosophy1098260 +Node: Non-Unix Installation1100611 +Node: PC Installation1101069 +Node: PC Binary Installation1102380 +Node: PC Compiling1104228 +Ref: PC Compiling-Footnote-11107227 +Node: PC Testing1107332 +Node: PC Using1108508 +Node: Cygwin1112660 +Node: MSYS1113469 +Node: VMS Installation1113967 +Node: VMS Compilation1114763 +Ref: VMS Compilation-Footnote-11115985 +Node: VMS Dynamic Extensions1116043 +Node: VMS Installation Details1117416 +Node: VMS Running1119668 +Node: VMS GNV1122502 +Node: VMS Old Gawk1123225 +Node: Bugs1123695 +Node: Other Versions1127699 +Node: Installation summary1133923 +Node: Notes1134979 +Node: Compatibility Mode1135844 +Node: Additions1136626 +Node: Accessing The Source1137551 +Node: Adding Code1138987 +Node: New Ports1145165 +Node: Derived Files1149646 +Ref: Derived Files-Footnote-11155121 +Ref: Derived Files-Footnote-21155155 +Ref: Derived Files-Footnote-31155751 +Node: Future Extensions1155865 +Node: Implementation Limitations1156471 +Node: Extension Design1157719 +Node: Old Extension Problems1158873 +Ref: Old Extension Problems-Footnote-11160390 +Node: Extension New Mechanism Goals1160447 +Ref: Extension New Mechanism Goals-Footnote-11163807 +Node: Extension Other Design Decisions1163996 +Node: Extension Future Growth1166102 +Node: Old Extension Mechanism1166938 +Node: Notes summary1168700 +Node: Basic Concepts1169886 +Node: Basic High Level1170567 +Ref: figure-general-flow1170839 +Ref: figure-process-flow1171438 +Ref: Basic High Level-Footnote-11174667 +Node: Basic Data Typing1174852 +Node: Glossary1178180 +Node: Copying1203332 +Node: GNU Free Documentation License1240888 +Node: Index1266024 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 2e7efca5..00a5a436 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -27337,11 +27337,13 @@ using regular pipes. @ @ @ @ and no-one can talk to host that's close,@* @ @ @ @ unless the host that isn't close@* @ @ @ @ is busy, hung, or dead.} +@author Mike O'Brien (aka Mr.@: Protocol) @end quotation @end ifnotdocbook @docbook <blockquote> +<attribution>Mike O'Brien (aka Mr. Protocol)</attribution> <literallayout class="normal"><literal>EMISTERED</literal>: <emphasis>A host is a host from coast to coast,</emphasis> <emphasis>and no-one can talk to host that's close,</emphasis> @@ -27516,9 +27518,9 @@ in the morning to work.) @cindex @code{BEGIN} pattern, and profiling @cindex @code{END} pattern, and profiling @example - # gawk profile, created Thu Feb 27 05:16:21 2014 + # gawk profile, created Mon Sep 29 05:16:21 2014 - # BEGIN block(s) + # BEGIN rule(s) BEGIN @{ 1 print "First BEGIN rule" @@ -27545,7 +27547,7 @@ in the morning to work.) @} @} - # END block(s) + # END rule(s) END @{ 1 print "First END rule" @@ -27673,7 +27675,7 @@ come out as: @end example @noindent -which is correct, but possibly surprising. +which is correct, but possibly unexpected. @cindex profiling @command{awk} programs, dynamically @cindex @command{gawk} program, dynamic profiling @@ -27705,7 +27707,7 @@ $ @kbd{kill -USR1 13992} @noindent As usual, the profiled version of the program is written to -@file{awkprof.out}, or to a different file if one specified with +@file{awkprof.out}, or to a different file if one was specified with the @option{--profile} option. Along with the regular profile, as shown earlier, the profile file @@ -27765,6 +27767,7 @@ The @option{--non-decimal-data} option causes @command{gawk} to treat octal- and hexadecimal-looking input data as octal and hexadecimal. This option should be used with caution or not at all; use of @code{strtonum()} is preferable. +Note that this option may disappear in a future version of @command{gawk}. @item You can take over complete control of sorting in @samp{for (@var{indx} in @var{array})} @@ -27784,9 +27787,9 @@ or @code{printf}. Use @code{close()} to close off the coprocess completely, or optionally, close off one side of the two-way communications. @item -By using special ``@value{FN}s'' with the @samp{|&} operator, you can open a +By using special @value{FN}s with the @samp{|&} operator, you can open a TCP/IP (or UDP/IP) connection to remote hosts in the Internet. @command{gawk} -supports both IPv4 an IPv6. +supports both IPv4 and IPv6. @item You can generate statement count profiles of your program. This can help you @@ -28024,7 +28027,7 @@ In June 2001 Bruno Haible wrote: This information is accessed via the POSIX character classes in regular expressions, such as @code{/[[:alnum:]]/} -(@pxref{Regexp Operators}). +(@pxref{Bracket Expressions}). @cindex monetary information, localization @cindex currency symbols, localization @@ -28107,7 +28110,7 @@ default arguments. Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the -English singular variant of a message, and @var{string2} the English plural +English singular variant of a message, and @var{string2} is the English plural variant of the same message. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. @@ -28195,9 +28198,11 @@ This example would be better done with @code{dcngettext()}: @example if (groggy) - message = dcngettext("%d customer disturbing me\n", "%d customers disturbing me\n", "adminprog") + message = dcngettext("%d customer disturbing me\n", + "%d customers disturbing me\n", "adminprog") else - message = dcngettext("enjoying %d customer\n", "enjoying %d customers\n", "adminprog") + message = dcngettext("enjoying %d customer\n", + "enjoying %d customers\n", "adminprog") printf(message, ncustomers) @end example @@ -28269,7 +28274,7 @@ First, use the @option{--gen-pot} command-line option to create the initial @file{.pot} file: @example -$ @kbd{gawk --gen-pot -f guide.awk > guide.pot} +gawk --gen-pot -f guide.awk > guide.pot @end example @cindex @code{xgettext} utility @@ -28333,11 +28338,11 @@ example, @samp{string} is the first argument and @samp{length(string)} is the se @example $ @kbd{gawk 'BEGIN @{} -> @kbd{string = "Dont Panic"} +> @kbd{string = "Don\47t Panic"} > @kbd{printf "%2$d characters live in \"%1$s\"\n",} > @kbd{string, length(string)} > @kbd{@}'} -@print{} 10 characters live in "Dont Panic" +@print{} 11 characters live in "Don't Panic" @end example If present, positional specifiers come first in the format specification, @@ -28549,7 +28554,8 @@ msgstr "Like, the scoop is" @cindex GNU/Linux The next step is to make the directory to hold the binary message object file and then to create the @file{guide.mo} file. -We pretend that our file is to be used in the @code{en_US.UTF-8} locale. +We pretend that our file is to be used in the @code{en_US.UTF-8} locale, +since we have to use a locale name known to the C @command{gettext} routines. The directory layout shown here is standard for GNU @command{gettext} on GNU/Linux systems. Other versions of @command{gettext} may use a different layout: @@ -28570,8 +28576,8 @@ $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES} The @command{msgfmt} utility does the conversion from human-readable @file{.po} file to machine-readable @file{.mo} file. By default, @command{msgfmt} creates a file named @file{messages}. -This file must be renamed and placed in the proper directory so that -@command{gawk} can find it: +This file must be renamed and placed in the proper directory (using +the @option{-o} option) so that @command{gawk} can find it: @example $ @kbd{msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo} @@ -28614,8 +28620,8 @@ complete detail in @cite{GNU gettext tools}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.1.tar.gz, -@value{PVERSION} 0.19.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.2.tar.gz, +@value{PVERSION} 0.19.2}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -28703,7 +28709,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{awk} +ahead to the next section on the specific features of the @command{gawk} debugger.) Of course, a debugging program cannot remove bugs for you, since it has @@ -28743,7 +28749,7 @@ is going wrong (or, for that matter, to better comprehend a perfectly functional program that you or someone else wrote). @node Debugging Terms -@subsection Additional Debugging Concepts +@subsection Debugging Concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. @@ -28832,8 +28838,8 @@ as our example. @cindex starting the debugger @cindex debugger, how to start -Starting the debugger is almost exactly like running @command{gawk}, -except you have to pass an additional option @option{--debug} or the +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 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 @@ -28851,6 +28857,7 @@ this syntax is slightly different from what they 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.) +The @option{-1} is an option to @file{uniq.awk}. Instead of immediately running the program on @file{inputfile}, as @command{gawk} would ordinarily do, the debugger merely loads all @@ -29032,7 +29039,7 @@ gawk> @kbd{p n m alast aline} This is kind of disappointing, though. All we found out is that there are five elements in @code{alast}; @code{m} and @code{aline} don't have -values yet since we are at line 68 but haven't executed it yet. +values since we are at line 68 but haven't executed it yet. This information is useful enough (we now know that none of the words were accidentally left out), but what if we want to see inside the array? @@ -29225,7 +29232,8 @@ Delete breakpoint(s) set at entry to function @var{function}. @cindex breakpoint condition @item @code{condition} @var{n} @code{"@var{expression}"} Add a condition to existing breakpoint or watchpoint @var{n}. The -condition is an @command{awk} expression that the debugger evaluates +condition is an @command{awk} expression @emph{enclosed in double quotes} +that the debugger evaluates whenever the breakpoint or watchpoint is reached. If the condition is true, then the debugger stops execution and prompts for a command. Otherwise, the debugger continues executing the program. If the condition expression is @@ -29413,7 +29421,7 @@ see the output shown under @code{dump} in @ref{Miscellaneous Debugger Commands}. @item @code{until} [[@var{filename}@code{:}]@var{n} | @var{function}] @itemx @code{u} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, continue execution until a line past the current -line in current stack frame is reached. With an argument, +line in the current stack frame is reached. With an argument, continue execution until the specified location is reached, or the current stack frame returns. @end table @@ -29477,7 +29485,7 @@ gawk> @kbd{print $3} @noindent This prints the third field in the input record (if the specified field does not exist, it prints @samp{Null field}). A variable can be an array element, with -the subscripts being constant values. To print the contents of an array, +the subscripts being constant string values. To print the contents of an array, prefix the name of the array with the @samp{@@} symbol: @example @@ -29543,7 +29551,7 @@ watch list. @end table @node Execution Stack -@subsection Dealing with the Stack +@subsection Working with the Stack Whenever you run a program which contains any function calls, @command{gawk} maintains a stack of all of the function calls leading up @@ -29554,16 +29562,22 @@ functions which called the one you are in. The commands for doing this are: @table @asis @cindex debugger commands, @code{bt} (@code{backtrace}) @cindex debugger commands, @code{backtrace} +@cindex debugger commands, @code{where} (@code{backtrace}) @cindex @code{backtrace} debugger command @cindex @code{bt} debugger command (alias for @code{backtrace}) +@cindex @code{where} debugger command +@cindex @code{where} debugger command (alias for @code{backtrace}) @cindex call stack, display in debugger @cindex traceback, display in debugger @item @code{backtrace} [@var{count}] @itemx @code{bt} [@var{count}] +@itemx @code{where} [@var{count}] Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each function, the source @value{FN}, and the line number. +The alias @code{where} for @code{backtrace} is provided for long-time +GDB users who may be used to that command. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -29613,7 +29627,7 @@ The value for @var{what} should be one of the following: @table @code @item args @cindex show function arguments, in debugger -Arguments of the selected frame. +List arguments of the selected frame. @item break @cindex show breakpoints @@ -29625,7 +29639,7 @@ List all items in the automatic display list. @item frame @cindex describe call stack frame, in debugger -Description of the selected stack frame. +Give a description of the selected stack frame. @item functions @cindex list function definitions, in debugger @@ -29634,11 +29648,11 @@ line numbers. @item locals @cindex show local variables, in debugger -Local variables of the selected frame. +List local variables of the selected frame. @item source @cindex show name of current source file, in debugger -The name of the current source file. Each time the program stops, the +Print the name of the current source file. Each time the program stops, the current source file is the file containing the current instruction. When the debugger first starts, the current source file is the first file included via the @option{-f} option. The @@ -29755,6 +29769,7 @@ commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (@pxref{Signature Program}) demonstrates: +@c FIXME: This will need updating if num-handler branch is ever merged in. @smallexample gawk> @kbd{dump} @print{} # BEGIN @@ -29828,7 +29843,7 @@ are as follows: @c nested table @table @asis -@item @code{-} +@item @code{-} (Minus) Print lines before the lines last printed. @item @code{+} @@ -29916,7 +29931,7 @@ and @end table @node Limitations -@section Limitations and Future Plans +@section Limitations 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 @@ -29964,8 +29979,10 @@ executing, short programs. The @command{gawk} debugger only accepts source supplied with the @option{-f} option. @end itemize +@ignore Look forward to a future release when these and other missing features may be added, and of course feel free to try to add them yourself! +@end ignore @node Debugging Summary @section Summary @@ -30008,9 +30025,8 @@ and editing. @cindex floating-point, numbers@comma{} arbitrary precision This @value{CHAPTER} introduces some basic concepts relating to -how computers do arithmetic and briefly lists the features in -@command{gawk} for performing arbitrary precision floating point -computations. It then proceeds to describe floating-point arithmetic, +how computers do arithmetic and defines some important terms. +It then proceeds to describe floating-point arithmetic, which is what @command{awk} uses for all its computations, including a discussion of arbitrary precision floating point arithmetic, which is a feature available only in @command{gawk}. It continues on to present @@ -30105,8 +30121,10 @@ Computers work with integer and floating point values of different ranges. Integer values are usually either 32 or 64 bits in size. Single precision floating point values occupy 32 bits, whereas double precision floating point values occupy 64 bits. Floating point values are always -signed. The possible ranges of values are shown in the following table. +signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. +@float Table,table-numeric-ranges +@caption{Value Ranges for Different Numeric Representations} @multitable @columnfractions .34 .33 .33 @headitem Numeric representation @tab Miniumum value @tab Maximum value @item 32-bit signed integer @tab @minus{}2,147,483,648 @tab 2,147,483,647 @@ -30116,6 +30134,7 @@ signed. The possible ranges of values are shown in the following table. @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} @end multitable +@end float @node Math Definitions @section Other Stuff To Know @@ -30143,14 +30162,12 @@ 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, which I have paraphrased, and -for the examples}. -A special value that results from attempting a -calculation that has no answer as a real number. In such a case, -programs can either receive a floating-point exception, or get @code{NaN} -back as the result. The IEEE 754 standard recommends that systems return -@code{NaN}. Some examples: +``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, +or get @code{NaN} back as the result. The IEEE 754 standard recommends +that systems return @code{NaN}. Some examples: @table @code @item sqrt(-1) @@ -30224,9 +30241,9 @@ to allow greater precisions and larger exponent ranges. field values for the basic IEEE 754 binary formats: @float Table,table-ieee-formats -@caption{Basic IEEE Format Context Values} +@caption{Basic IEEE Format Values} @multitable @columnfractions .20 .20 .20 .20 .20 -@headitem Name @tab Total bits @tab Precision @tab emin @tab emax +@headitem Name @tab Total bits @tab Precision @tab Minimum exponent @tab Maximum exponent @item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127 @item Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023 @item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383 @@ -30241,16 +30258,16 @@ one extra bit of significand. @node MPFR features @section Arbitrary Precison Arithmetic Features In @command{gawk} -By default, @command{gawk} uses the double precision floating point values +By default, @command{gawk} uses the double precision floating-point values supplied by the hardware of the system it runs on. However, if it was -compiled to do, @command{gawk} uses the @uref{http://www.mpfr.org, GNU -MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary +compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org +GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary precision arithmetic on numbers. You can see if MPFR support is available like so: @example $ @kbd{gawk --version} -@print{} GNU Awk 4.1.1, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) +@print{} GNU Awk 4.1.2, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) @print{} Copyright (C) 1989, 1991-2014 Free Software Foundation. @dots{} @end example @@ -30274,7 +30291,8 @@ Two built-in variables, @code{PREC} and @code{ROUNDMODE}, provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. -@xref{Auto-set}, for more information. +@xref{Setting precision}, and @ref{Setting the rounding mode}, +for more information. @node FP Math Caution @section Floating Point Arithmetic: Caveat Emptor! @@ -30388,6 +30406,10 @@ else # not ok @end example +@noindent +(We assume that you have a simple absolute value function named +@code{abs()} defined elsewhere in your program.) + @node Errors accumulate @subsubsection Errors Accumulate @@ -30474,7 +30496,7 @@ It is easy to forget that the finite number of bits used to store the value is often just an approximation after proper rounding. The test for equality succeeds if and only if @emph{all} bits in the two operands are exactly the same. Since this is not necessarily true after floating-point -computations with a particular precision and effective rounding rule, +computations with a particular precision and effective rounding mode, a straight test for equality may not work. Instead, compare the two numbers to see if they are within the desirable delta of each other. @@ -30573,7 +30595,7 @@ Be wary of floating-point constants! When reading a floating-point constant from program source code, @command{gawk} uses the default precision (that of a C @code{double}), unless overridden by an assignment to the special variable @code{PREC} on the command line, to store it -internally as a MPFR number. Changing the precision using @code{PREC} +internally as an MPFR number. Changing the precision using @code{PREC} in the program text does @emph{not} change the precision of a constant. If you need to represent a floating-point constant at a higher precision @@ -30711,15 +30733,15 @@ the following computes 5<superscript>4<superscript>3<superscript>2</superscript></superscript></superscript>, @c @end docbook the result of which is beyond the -limits of ordinary hardware double-precision floating point values: +limits of ordinary hardware double precision floating point values: @example $ @kbd{gawk -M 'BEGIN @{} > @kbd{x = 5^4^3^2} -> @kbd{print "# of digits =", length(x)} +> @kbd{print "number of digits =", length(x)} > @kbd{print substr(x, 1, 20), "...", substr(x, length(x) - 19, 20)} > @kbd{@}'} -@print{} # of digits = 183231 +@print{} number of digits = 183231 @print{} 62060698786608744707 ... 92256259918212890625 @end example @@ -30942,7 +30964,7 @@ Thus @samp{+nan} and @samp{+NaN} are the same. @itemize @value{BULLET} @item Most computer arithmetic is done using either integers or floating-point -values. The default for @command{awk} is to use double-precision +values. Standard @command{awk} uses double precision floating-point values. @item @@ -31061,7 +31083,7 @@ Extensions are written in C or C++, using the @dfn{Application Programming 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 sample extension. In addition, it documents +them, and presents a small example extension. In addition, it documents the sample extensions included in the @command{gawk} distribution, and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @@ -31077,10 +31099,14 @@ goals and design. @node Plugin License @section Extension Licensing -Every dynamic extension should define the global symbol -@code{plugin_is_GPL_compatible} to assert that it has been licensed under -a GPL-compatible license. If this symbol does not exist, @command{gawk} -emits a fatal error and exits when it tries to load your extension. +Every dynamic extension must be distributed under a license that is +compatible with the GNU GPL (@pxref{Copying}). + +In order for the extension to tell @command{gawk} that it is +properly licensed, the extension must define the global symbol +@code{plugin_is_GPL_compatible}. If this symbol does not exist, +@command{gawk} emits a fatal error and exits when it tries to load +your extension. The declared type of the symbol should be @code{int}. It does not need to be in any allocated section, though. The code merely asserts that @@ -31095,7 +31121,7 @@ int plugin_is_GPL_compatible; Communication between @command{gawk} and an extension is two-way. First, when an extension -is loaded, it is passed a pointer to a @code{struct} whose fields are +is loaded, @command{gawk} passes it a pointer to a @code{struct} whose fields are function pointers. @ifnotdocbook This is shown in @ref{figure-load-extension}. @@ -31131,29 +31157,29 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}. The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a -function for ``registering'' new built-in functions. +function for ``registering'' new functions. @ifnotdocbook -This is shown in @ref{figure-load-new-function}. +This is shown in @ref{figure-register-new-function}. @end ifnotdocbook @ifdocbook -This is shown in @inlineraw{docbook, <xref linkend="figure-load-new-function"/>}. +This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function"/>}. @end ifdocbook @ifnotdocbook -@float Figure,figure-load-new-function -@caption{Loading The New Function} +@float Figure,figure-register-new-function +@caption{Registering A New Function} @ifinfo -@center @image{api-figure2, , , Loading The New Function, txt} +@center @image{api-figure2, , , Registering A New Function, txt} @end ifinfo @ifnotinfo -@center @image{api-figure2, , , Loading The New Function} +@center @image{api-figure2, , , Registering A New Function} @end ifnotinfo @end float @end ifnotdocbook @docbook -<figure id="figure-load-new-function" float="0"> -<title>Loading The New Function</title> +<figure id="figure-register-new-function" float="0"> +<title>Registering A New Function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject> </mediaobject> @@ -31203,8 +31229,8 @@ and understandable. Although all of this sounds somewhat complicated, the result is that extension code is quite straightforward to write and to read. You can -see this in the sample extensions @file{filefuncs.c} (@pxref{Extension -Example}) and also the @file{testext.c} code for testing the APIs. +see this in the sample extension @file{filefuncs.c} (@pxref{Extension +Example}) and also in the @file{testext.c} code for testing the APIs. Some other bits and pieces: @@ -31386,7 +31412,7 @@ and also how characters are likely to be input and output from files. @item When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type (number, string, -scalars, value cookie, array, or ``undefined''). When the request is +scalar, value cookie, array, or ``undefined''). When the request is ``undefined,'' the returned value will have the real underlying type. However, if the request and actual type don't match, the access function @@ -31545,7 +31571,7 @@ 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. Given a scalar cookie, @command{gawk} can directly retrieve or -modify the value, as required, without having to first find it. +modify the value, as required, without having to find it first. The @code{awk_value_cookie_t} type and @code{value_cookie} macro are similar. If you know that you wish to diff --git a/doc/gawktexi.in b/doc/gawktexi.in index d026a3b1..a0677a7c 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -26434,11 +26434,13 @@ using regular pipes. @ @ @ @ and no-one can talk to host that's close,@* @ @ @ @ unless the host that isn't close@* @ @ @ @ is busy, hung, or dead.} +@author Mike O'Brien (aka Mr.@: Protocol) @end quotation @end ifnotdocbook @docbook <blockquote> +<attribution>Mike O'Brien (aka Mr. Protocol)</attribution> <literallayout class="normal"><literal>EMISTERED</literal>: <emphasis>A host is a host from coast to coast,</emphasis> <emphasis>and no-one can talk to host that's close,</emphasis> @@ -26613,9 +26615,9 @@ in the morning to work.) @cindex @code{BEGIN} pattern, and profiling @cindex @code{END} pattern, and profiling @example - # gawk profile, created Thu Feb 27 05:16:21 2014 + # gawk profile, created Mon Sep 29 05:16:21 2014 - # BEGIN block(s) + # BEGIN rule(s) BEGIN @{ 1 print "First BEGIN rule" @@ -26642,7 +26644,7 @@ in the morning to work.) @} @} - # END block(s) + # END rule(s) END @{ 1 print "First END rule" @@ -26770,7 +26772,7 @@ come out as: @end example @noindent -which is correct, but possibly surprising. +which is correct, but possibly unexpected. @cindex profiling @command{awk} programs, dynamically @cindex @command{gawk} program, dynamic profiling @@ -26802,7 +26804,7 @@ $ @kbd{kill -USR1 13992} @noindent As usual, the profiled version of the program is written to -@file{awkprof.out}, or to a different file if one specified with +@file{awkprof.out}, or to a different file if one was specified with the @option{--profile} option. Along with the regular profile, as shown earlier, the profile file @@ -26862,6 +26864,7 @@ The @option{--non-decimal-data} option causes @command{gawk} to treat octal- and hexadecimal-looking input data as octal and hexadecimal. This option should be used with caution or not at all; use of @code{strtonum()} is preferable. +Note that this option may disappear in a future version of @command{gawk}. @item You can take over complete control of sorting in @samp{for (@var{indx} in @var{array})} @@ -26881,9 +26884,9 @@ or @code{printf}. Use @code{close()} to close off the coprocess completely, or optionally, close off one side of the two-way communications. @item -By using special ``@value{FN}s'' with the @samp{|&} operator, you can open a +By using special @value{FN}s with the @samp{|&} operator, you can open a TCP/IP (or UDP/IP) connection to remote hosts in the Internet. @command{gawk} -supports both IPv4 an IPv6. +supports both IPv4 and IPv6. @item You can generate statement count profiles of your program. This can help you @@ -27121,7 +27124,7 @@ In June 2001 Bruno Haible wrote: This information is accessed via the POSIX character classes in regular expressions, such as @code{/[[:alnum:]]/} -(@pxref{Regexp Operators}). +(@pxref{Bracket Expressions}). @cindex monetary information, localization @cindex currency symbols, localization @@ -27204,7 +27207,7 @@ default arguments. Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the -English singular variant of a message, and @var{string2} the English plural +English singular variant of a message, and @var{string2} is the English plural variant of the same message. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. @@ -27292,9 +27295,11 @@ This example would be better done with @code{dcngettext()}: @example if (groggy) - message = dcngettext("%d customer disturbing me\n", "%d customers disturbing me\n", "adminprog") + message = dcngettext("%d customer disturbing me\n", + "%d customers disturbing me\n", "adminprog") else - message = dcngettext("enjoying %d customer\n", "enjoying %d customers\n", "adminprog") + message = dcngettext("enjoying %d customer\n", + "enjoying %d customers\n", "adminprog") printf(message, ncustomers) @end example @@ -27366,7 +27371,7 @@ First, use the @option{--gen-pot} command-line option to create the initial @file{.pot} file: @example -$ @kbd{gawk --gen-pot -f guide.awk > guide.pot} +gawk --gen-pot -f guide.awk > guide.pot @end example @cindex @code{xgettext} utility @@ -27430,11 +27435,11 @@ example, @samp{string} is the first argument and @samp{length(string)} is the se @example $ @kbd{gawk 'BEGIN @{} -> @kbd{string = "Dont Panic"} +> @kbd{string = "Don\47t Panic"} > @kbd{printf "%2$d characters live in \"%1$s\"\n",} > @kbd{string, length(string)} > @kbd{@}'} -@print{} 10 characters live in "Dont Panic" +@print{} 11 characters live in "Don't Panic" @end example If present, positional specifiers come first in the format specification, @@ -27646,7 +27651,8 @@ msgstr "Like, the scoop is" @cindex GNU/Linux The next step is to make the directory to hold the binary message object file and then to create the @file{guide.mo} file. -We pretend that our file is to be used in the @code{en_US.UTF-8} locale. +We pretend that our file is to be used in the @code{en_US.UTF-8} locale, +since we have to use a locale name known to the C @command{gettext} routines. The directory layout shown here is standard for GNU @command{gettext} on GNU/Linux systems. Other versions of @command{gettext} may use a different layout: @@ -27667,8 +27673,8 @@ $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES} The @command{msgfmt} utility does the conversion from human-readable @file{.po} file to machine-readable @file{.mo} file. By default, @command{msgfmt} creates a file named @file{messages}. -This file must be renamed and placed in the proper directory so that -@command{gawk} can find it: +This file must be renamed and placed in the proper directory (using +the @option{-o} option) so that @command{gawk} can find it: @example $ @kbd{msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo} @@ -27711,8 +27717,8 @@ complete detail in @cite{GNU gettext tools}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.1.tar.gz, -@value{PVERSION} 0.19.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.2.tar.gz, +@value{PVERSION} 0.19.2}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -27800,7 +27806,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{awk} +ahead to the next section on the specific features of the @command{gawk} debugger.) Of course, a debugging program cannot remove bugs for you, since it has @@ -27840,7 +27846,7 @@ is going wrong (or, for that matter, to better comprehend a perfectly functional program that you or someone else wrote). @node Debugging Terms -@subsection Additional Debugging Concepts +@subsection Debugging Concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. @@ -27929,8 +27935,8 @@ as our example. @cindex starting the debugger @cindex debugger, how to start -Starting the debugger is almost exactly like running @command{gawk}, -except you have to pass an additional option @option{--debug} or the +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 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 @@ -27948,6 +27954,7 @@ this syntax is slightly different from what they 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.) +The @option{-1} is an option to @file{uniq.awk}. Instead of immediately running the program on @file{inputfile}, as @command{gawk} would ordinarily do, the debugger merely loads all @@ -28129,7 +28136,7 @@ gawk> @kbd{p n m alast aline} This is kind of disappointing, though. All we found out is that there are five elements in @code{alast}; @code{m} and @code{aline} don't have -values yet since we are at line 68 but haven't executed it yet. +values since we are at line 68 but haven't executed it yet. This information is useful enough (we now know that none of the words were accidentally left out), but what if we want to see inside the array? @@ -28322,7 +28329,8 @@ Delete breakpoint(s) set at entry to function @var{function}. @cindex breakpoint condition @item @code{condition} @var{n} @code{"@var{expression}"} Add a condition to existing breakpoint or watchpoint @var{n}. The -condition is an @command{awk} expression that the debugger evaluates +condition is an @command{awk} expression @emph{enclosed in double quotes} +that the debugger evaluates whenever the breakpoint or watchpoint is reached. If the condition is true, then the debugger stops execution and prompts for a command. Otherwise, the debugger continues executing the program. If the condition expression is @@ -28510,7 +28518,7 @@ see the output shown under @code{dump} in @ref{Miscellaneous Debugger Commands}. @item @code{until} [[@var{filename}@code{:}]@var{n} | @var{function}] @itemx @code{u} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, continue execution until a line past the current -line in current stack frame is reached. With an argument, +line in the current stack frame is reached. With an argument, continue execution until the specified location is reached, or the current stack frame returns. @end table @@ -28574,7 +28582,7 @@ gawk> @kbd{print $3} @noindent This prints the third field in the input record (if the specified field does not exist, it prints @samp{Null field}). A variable can be an array element, with -the subscripts being constant values. To print the contents of an array, +the subscripts being constant string values. To print the contents of an array, prefix the name of the array with the @samp{@@} symbol: @example @@ -28640,7 +28648,7 @@ watch list. @end table @node Execution Stack -@subsection Dealing with the Stack +@subsection Working with the Stack Whenever you run a program which contains any function calls, @command{gawk} maintains a stack of all of the function calls leading up @@ -28651,16 +28659,22 @@ functions which called the one you are in. The commands for doing this are: @table @asis @cindex debugger commands, @code{bt} (@code{backtrace}) @cindex debugger commands, @code{backtrace} +@cindex debugger commands, @code{where} (@code{backtrace}) @cindex @code{backtrace} debugger command @cindex @code{bt} debugger command (alias for @code{backtrace}) +@cindex @code{where} debugger command +@cindex @code{where} debugger command (alias for @code{backtrace}) @cindex call stack, display in debugger @cindex traceback, display in debugger @item @code{backtrace} [@var{count}] @itemx @code{bt} [@var{count}] +@itemx @code{where} [@var{count}] Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each function, the source @value{FN}, and the line number. +The alias @code{where} for @code{backtrace} is provided for long-time +GDB users who may be used to that command. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -28710,7 +28724,7 @@ The value for @var{what} should be one of the following: @table @code @item args @cindex show function arguments, in debugger -Arguments of the selected frame. +List arguments of the selected frame. @item break @cindex show breakpoints @@ -28722,7 +28736,7 @@ List all items in the automatic display list. @item frame @cindex describe call stack frame, in debugger -Description of the selected stack frame. +Give a description of the selected stack frame. @item functions @cindex list function definitions, in debugger @@ -28731,11 +28745,11 @@ line numbers. @item locals @cindex show local variables, in debugger -Local variables of the selected frame. +List local variables of the selected frame. @item source @cindex show name of current source file, in debugger -The name of the current source file. Each time the program stops, the +Print the name of the current source file. Each time the program stops, the current source file is the file containing the current instruction. When the debugger first starts, the current source file is the first file included via the @option{-f} option. The @@ -28852,6 +28866,7 @@ commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (@pxref{Signature Program}) demonstrates: +@c FIXME: This will need updating if num-handler branch is ever merged in. @smallexample gawk> @kbd{dump} @print{} # BEGIN @@ -28925,7 +28940,7 @@ are as follows: @c nested table @table @asis -@item @code{-} +@item @code{-} (Minus) Print lines before the lines last printed. @item @code{+} @@ -29013,7 +29028,7 @@ and @end table @node Limitations -@section Limitations and Future Plans +@section Limitations 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 @@ -29061,8 +29076,10 @@ executing, short programs. The @command{gawk} debugger only accepts source supplied with the @option{-f} option. @end itemize +@ignore Look forward to a future release when these and other missing features may be added, and of course feel free to try to add them yourself! +@end ignore @node Debugging Summary @section Summary @@ -29105,9 +29122,8 @@ and editing. @cindex floating-point, numbers@comma{} arbitrary precision This @value{CHAPTER} introduces some basic concepts relating to -how computers do arithmetic and briefly lists the features in -@command{gawk} for performing arbitrary precision floating point -computations. It then proceeds to describe floating-point arithmetic, +how computers do arithmetic and defines some important terms. +It then proceeds to describe floating-point arithmetic, which is what @command{awk} uses for all its computations, including a discussion of arbitrary precision floating point arithmetic, which is a feature available only in @command{gawk}. It continues on to present @@ -29202,8 +29218,10 @@ Computers work with integer and floating point values of different ranges. Integer values are usually either 32 or 64 bits in size. Single precision floating point values occupy 32 bits, whereas double precision floating point values occupy 64 bits. Floating point values are always -signed. The possible ranges of values are shown in the following table. +signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. +@float Table,table-numeric-ranges +@caption{Value Ranges for Different Numeric Representations} @multitable @columnfractions .34 .33 .33 @headitem Numeric representation @tab Miniumum value @tab Maximum value @item 32-bit signed integer @tab @minus{}2,147,483,648 @tab 2,147,483,647 @@ -29213,6 +29231,7 @@ signed. The possible ranges of values are shown in the following table. @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} @end multitable +@end float @node Math Definitions @section Other Stuff To Know @@ -29240,14 +29259,12 @@ 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, which I have paraphrased, and -for the examples}. -A special value that results from attempting a -calculation that has no answer as a real number. In such a case, -programs can either receive a floating-point exception, or get @code{NaN} -back as the result. The IEEE 754 standard recommends that systems return -@code{NaN}. Some examples: +``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, +or get @code{NaN} back as the result. The IEEE 754 standard recommends +that systems return @code{NaN}. Some examples: @table @code @item sqrt(-1) @@ -29321,9 +29338,9 @@ to allow greater precisions and larger exponent ranges. field values for the basic IEEE 754 binary formats: @float Table,table-ieee-formats -@caption{Basic IEEE Format Context Values} +@caption{Basic IEEE Format Values} @multitable @columnfractions .20 .20 .20 .20 .20 -@headitem Name @tab Total bits @tab Precision @tab emin @tab emax +@headitem Name @tab Total bits @tab Precision @tab Minimum exponent @tab Maximum exponent @item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127 @item Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023 @item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383 @@ -29338,16 +29355,16 @@ one extra bit of significand. @node MPFR features @section Arbitrary Precison Arithmetic Features In @command{gawk} -By default, @command{gawk} uses the double precision floating point values +By default, @command{gawk} uses the double precision floating-point values supplied by the hardware of the system it runs on. However, if it was -compiled to do, @command{gawk} uses the @uref{http://www.mpfr.org, GNU -MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary +compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org +GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary precision arithmetic on numbers. You can see if MPFR support is available like so: @example $ @kbd{gawk --version} -@print{} GNU Awk 4.1.1, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) +@print{} GNU Awk 4.1.2, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) @print{} Copyright (C) 1989, 1991-2014 Free Software Foundation. @dots{} @end example @@ -29371,7 +29388,8 @@ Two built-in variables, @code{PREC} and @code{ROUNDMODE}, provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. -@xref{Auto-set}, for more information. +@xref{Setting precision}, and @ref{Setting the rounding mode}, +for more information. @node FP Math Caution @section Floating Point Arithmetic: Caveat Emptor! @@ -29485,6 +29503,10 @@ else # not ok @end example +@noindent +(We assume that you have a simple absolute value function named +@code{abs()} defined elsewhere in your program.) + @node Errors accumulate @subsubsection Errors Accumulate @@ -29571,7 +29593,7 @@ It is easy to forget that the finite number of bits used to store the value is often just an approximation after proper rounding. The test for equality succeeds if and only if @emph{all} bits in the two operands are exactly the same. Since this is not necessarily true after floating-point -computations with a particular precision and effective rounding rule, +computations with a particular precision and effective rounding mode, a straight test for equality may not work. Instead, compare the two numbers to see if they are within the desirable delta of each other. @@ -29670,7 +29692,7 @@ Be wary of floating-point constants! When reading a floating-point constant from program source code, @command{gawk} uses the default precision (that of a C @code{double}), unless overridden by an assignment to the special variable @code{PREC} on the command line, to store it -internally as a MPFR number. Changing the precision using @code{PREC} +internally as an MPFR number. Changing the precision using @code{PREC} in the program text does @emph{not} change the precision of a constant. If you need to represent a floating-point constant at a higher precision @@ -29808,15 +29830,15 @@ the following computes 5<superscript>4<superscript>3<superscript>2</superscript></superscript></superscript>, @c @end docbook the result of which is beyond the -limits of ordinary hardware double-precision floating point values: +limits of ordinary hardware double precision floating point values: @example $ @kbd{gawk -M 'BEGIN @{} > @kbd{x = 5^4^3^2} -> @kbd{print "# of digits =", length(x)} +> @kbd{print "number of digits =", length(x)} > @kbd{print substr(x, 1, 20), "...", substr(x, length(x) - 19, 20)} > @kbd{@}'} -@print{} # of digits = 183231 +@print{} number of digits = 183231 @print{} 62060698786608744707 ... 92256259918212890625 @end example @@ -30039,7 +30061,7 @@ Thus @samp{+nan} and @samp{+NaN} are the same. @itemize @value{BULLET} @item Most computer arithmetic is done using either integers or floating-point -values. The default for @command{awk} is to use double-precision +values. Standard @command{awk} uses double precision floating-point values. @item @@ -30158,7 +30180,7 @@ Extensions are written in C or C++, using the @dfn{Application Programming 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 sample extension. In addition, it documents +them, and presents a small example extension. In addition, it documents the sample extensions included in the @command{gawk} distribution, and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @@ -30174,10 +30196,14 @@ goals and design. @node Plugin License @section Extension Licensing -Every dynamic extension should define the global symbol -@code{plugin_is_GPL_compatible} to assert that it has been licensed under -a GPL-compatible license. If this symbol does not exist, @command{gawk} -emits a fatal error and exits when it tries to load your extension. +Every dynamic extension must be distributed under a license that is +compatible with the GNU GPL (@pxref{Copying}). + +In order for the extension to tell @command{gawk} that it is +properly licensed, the extension must define the global symbol +@code{plugin_is_GPL_compatible}. If this symbol does not exist, +@command{gawk} emits a fatal error and exits when it tries to load +your extension. The declared type of the symbol should be @code{int}. It does not need to be in any allocated section, though. The code merely asserts that @@ -30192,7 +30218,7 @@ int plugin_is_GPL_compatible; Communication between @command{gawk} and an extension is two-way. First, when an extension -is loaded, it is passed a pointer to a @code{struct} whose fields are +is loaded, @command{gawk} passes it a pointer to a @code{struct} whose fields are function pointers. @ifnotdocbook This is shown in @ref{figure-load-extension}. @@ -30228,29 +30254,29 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}. The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a -function for ``registering'' new built-in functions. +function for ``registering'' new functions. @ifnotdocbook -This is shown in @ref{figure-load-new-function}. +This is shown in @ref{figure-register-new-function}. @end ifnotdocbook @ifdocbook -This is shown in @inlineraw{docbook, <xref linkend="figure-load-new-function"/>}. +This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function"/>}. @end ifdocbook @ifnotdocbook -@float Figure,figure-load-new-function -@caption{Loading The New Function} +@float Figure,figure-register-new-function +@caption{Registering A New Function} @ifinfo -@center @image{api-figure2, , , Loading The New Function, txt} +@center @image{api-figure2, , , Registering A New Function, txt} @end ifinfo @ifnotinfo -@center @image{api-figure2, , , Loading The New Function} +@center @image{api-figure2, , , Registering A New Function} @end ifnotinfo @end float @end ifnotdocbook @docbook -<figure id="figure-load-new-function" float="0"> -<title>Loading The New Function</title> +<figure id="figure-register-new-function" float="0"> +<title>Registering A New Function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject> </mediaobject> @@ -30300,8 +30326,8 @@ and understandable. Although all of this sounds somewhat complicated, the result is that extension code is quite straightforward to write and to read. You can -see this in the sample extensions @file{filefuncs.c} (@pxref{Extension -Example}) and also the @file{testext.c} code for testing the APIs. +see this in the sample extension @file{filefuncs.c} (@pxref{Extension +Example}) and also in the @file{testext.c} code for testing the APIs. Some other bits and pieces: @@ -30483,7 +30509,7 @@ and also how characters are likely to be input and output from files. @item When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type (number, string, -scalars, value cookie, array, or ``undefined''). When the request is +scalar, value cookie, array, or ``undefined''). When the request is ``undefined,'' the returned value will have the real underlying type. However, if the request and actual type don't match, the access function @@ -30642,7 +30668,7 @@ 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. Given a scalar cookie, @command{gawk} can directly retrieve or -modify the value, as required, without having to first find it. +modify the value, as required, without having to find it first. The @code{awk_value_cookie_t} type and @code{value_cookie} macro are similar. If you know that you wish to |