diff options
| -rw-r--r-- | ChangeLog | 9 | ||||
| -rw-r--r-- | doc/ChangeLog | 12 | ||||
| -rw-r--r-- | doc/gawk.info | 1559 | ||||
| -rw-r--r-- | doc/gawk.texi | 429 | ||||
| -rw-r--r-- | doc/gawktexi.in | 429 | ||||
| -rw-r--r-- | extension/ChangeLog | 4 | ||||
| -rw-r--r-- | extension/filefuncs.c | 2 | ||||
| -rw-r--r-- | gawkapi.h | 2 | ||||
| -rw-r--r-- | profile.c | 1 | ||||
| -rw-r--r-- | test/ChangeLog | 5 | ||||
| -rw-r--r-- | test/Makefile.am | 10 | ||||
| -rw-r--r-- | test/Makefile.in | 10 | ||||
| -rw-r--r-- | test/profile0.awk | 1 | ||||
| -rw-r--r-- | test/profile0.in | 2 | ||||
| -rw-r--r-- | test/profile0.ok | 6 |
15 files changed, 1313 insertions, 1168 deletions
@@ -1,3 +1,12 @@ +2015-02-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawkapi.h: Fix spelling error in comment. + +2015-02-10 Arnold D. Robbins <arnold@skeeve.com> + + * profile.c (pprint): Restore printing of count for rules. + Bug report by Hermann Peifer. + 2015-02-08 Arnold D. Robbins <arnold@skeeve.com> * io.c: Make it "NONFATAL" everywhere. diff --git a/doc/ChangeLog b/doc/ChangeLog index 3840f933..51005c7c 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,15 @@ +2015-02-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: O'Reilly fixes. + +2015-02-10 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor fixes, O'Reilly fixes. + +2015-02-09 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Restore a lost sentence. O'Reilly fixes. + 2015-02-08 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: O'Reilly fixes. diff --git a/doc/gawk.info b/doc/gawk.info index 118c814a..bb5c30bb 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1376,6 +1376,12 @@ also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities. + +Arnold Robbins +Nof Ayalon +Israel +February 2015 + File: gawk.info, Node: Getting Started, Next: Invoking Gawk, Prev: Preface, Up: Top @@ -9131,9 +9137,10 @@ accepts any record with a first field that contains `li': -| 555-5553 -| 555-6699 - pattern. The expression `/li/' has the value one if `li' appears in -the current input record. Thus, as a pattern, `/li/' matches any record -containing `li'. + A regexp constant as a pattern is also a special case of an +expression pattern. The expression `/li/' has the value one if `li' +appears in the current input record. Thus, as a pattern, `/li/' matches +any record containing `li'. Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions @@ -21872,7 +21879,7 @@ Decimal arithmetic sides) of the decimal point, and the results of a computation are always exact. - Some modern system can do decimal arithmetic in hardware, but + Some modern systems can do decimal arithmetic in hardware, but usually you need a special software library to provide access to these instructions. There are also libraries that do decimal arithmetic entirely in software. @@ -21926,12 +21933,6 @@ Numeric representation Minimum value Maximum value 32-bit unsigned integer 0 4,294,967,295 64-bit signed integer -9,223,372,036,854,775,8089,223,372,036,854,775,807 64-bit unsigned integer 0 18,446,744,073,709,551,615 -Single-precision `1.175494e-38' `3.402823e+38' -floating point -(approximate) -Double-precision `2.225074e-308' `1.797693e+308' -floating point -(approximate) Table 15.1: Value ranges for different numeric representations @@ -21947,7 +21948,7 @@ File: gawk.info, Node: Math Definitions, Next: MPFR features, Prev: Computer The rest of this major node uses a number of terms. Here are some informal definitions that should help you work your way through the -material here. +material here: "Accuracy" A floating-point calculation's accuracy is how close it comes to @@ -21967,7 +21968,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 @@ -21993,15 +21994,15 @@ material here. PREC = 3.322 * DPS - Here, PREC denotes the binary precision (measured in bits) and DPS - (short for decimal places) is the decimal digits. + Here, _prec_ denotes the binary precision (measured in bits) and + _dps_ (short for decimal places) is the decimal digits. "Rounding mode" How numbers are rounded up or down when necessary. More details are provided later. "Significand" - A floating-point value consists the significand multiplied by 10 + A floating-point value consists of the significand multiplied by 10 to the power of the exponent. For example, in `1.2345e67', the significand is `1.2345'. @@ -22023,7 +22024,7 @@ precision formats to allow greater precisions and larger exponent ranges. (`awk' uses only the 64-bit double-precision format.) *note table-ieee-formats:: lists the precision and exponent field -values for the basic IEEE 754 binary formats: +values for the basic IEEE 754 binary formats. Name Total bits Precision Minimum Maximum exponent exponent @@ -22088,7 +22089,7 @@ File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers, P Math class is tough! -- Teen Talk Barbie, July 1992 - This minor node provides a high level overview of the issues + This minor node provides a high-level overview of the issues involved when doing lots of floating-point arithmetic.(1) The discussion applies to both hardware and arbitrary-precision floating-point arithmetic. @@ -22109,8 +22110,8 @@ floating-point arithmetic. (1) There is a very nice paper on floating-point arithmetic (http://www.validlab.com/goldberg/paper.pdf) by David Goldberg, "What -Every Computer Scientist Should Know About Floating-point Arithmetic," -`ACM Computing Surveys' *23*, 1 (1991-03), 5-48. This is worth reading +Every Computer Scientist Should Know About Floating-Point Arithmetic," +`ACM Computing Surveys' *23*, 1 (1991-03): 5-48. This is worth reading if you are interested in the details, but it does require a background in computer science. @@ -22164,7 +22165,7 @@ number as you assigned to it: Often the error is so small you do not even notice it, and if you do, you can always specify how much precision you would like in your output. -Usually this is a format string like `"%.15g"', which when used in the +Usually this is a format string like `"%.15g"', which, when used in the previous example, produces an output identical to the input. @@ -22204,7 +22205,7 @@ File: gawk.info, Node: Errors accumulate, Prev: Comparing FP Values, Up: Inex The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating-point operations, +value that is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of pi using one of its many series representations: @@ -22255,7 +22256,7 @@ easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may be important for your computation. Rounding error, cumulative precision -loss and underflow are often troublesome. +loss, and underflow are often troublesome. When `gawk' tests the expressions `0.1 + 12.2' and `12.3' for equality using the machine double-precision arithmetic, it decides that @@ -22290,8 +22291,9 @@ illustrated by our earlier attempt to compute the value of pi. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. - Repeated addition is not necessarily equivalent to multiplication in -floating-point arithmetic. In the example in *note Errors accumulate::: + Additionally, you should understand that repeated addition is not +necessarily equivalent to multiplication in floating-point arithmetic. +In the example in *note Errors accumulate::: $ gawk 'BEGIN { > for (d = 1.1; d <= 1.5; d += 0.1) # loop five times (?) @@ -22346,7 +22348,7 @@ set the value to one of the predefined case-insensitive strings shown in *note table-predefined-precision-strings::, to emulate an IEEE 754 binary format. -`PREC' IEEE 754 Binary Format +`PREC' IEEE 754 binary format --------------------------------------------------- `"half"' 16-bit half-precision `"single"' Basic 32-bit single precision @@ -22379,14 +22381,14 @@ on arithmetic operations: example illustrates the differences among various ways to print a floating-point constant: - $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 0.1) }' - -| 0.1000000000000000055511151 - $ gawk -M -v PREC=113 'BEGIN { printf("%0.25f\n", 0.1) }' - -| 0.1000000000000000000000000 - $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", "0.1") }' - -| 0.1000000000000000000000000 - $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 1/10) }' - -| 0.1000000000000000000000000 + $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 0.1) }' + -| 0.1000000000000000055511151 + $ gawk -M -v PREC=113 'BEGIN { printf("%0.25f\n", 0.1) }' + -| 0.1000000000000000000000000 + $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", "0.1") }' + -| 0.1000000000000000000000000 + $ gawk -M 'BEGIN { PREC = 113; printf("%0.25f\n", 1/10) }' + -| 0.1000000000000000000000000 File: gawk.info, Node: Setting the rounding mode, Prev: Setting precision, Up: FP Math Caution @@ -22394,15 +22396,15 @@ File: gawk.info, Node: Setting the rounding mode, Prev: Setting precision, Up 15.4.5 Setting the Rounding Mode -------------------------------- -The `ROUNDMODE' variable provides program level control over the +The `ROUNDMODE' variable provides program-level control over the rounding mode. The correspondence between `ROUNDMODE' and the IEEE rounding modes is shown in *note table-gawk-rounding-modes::. -Rounding Mode IEEE Name `ROUNDMODE' +Rounding mode IEEE name `ROUNDMODE' --------------------------------------------------------------------------- Round to nearest, ties to even `roundTiesToEven' `"N"' or `"n"' -Round toward plus Infinity `roundTowardPositive' `"U"' or `"u"' -Round toward negative Infinity `roundTowardNegative' `"D"' or `"d"' +Round toward positive infinity `roundTowardPositive' `"U"' or `"u"' +Round toward negative infinity `roundTowardNegative' `"D"' or `"d"' Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero @@ -22453,8 +22455,8 @@ distributes upward and downward rounds of exact halves, which might cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. - The other rounding modes are rarely used. Round toward positive -infinity (`roundTowardPositive') and round toward negative infinity + The other rounding modes are rarely used. Rounding toward positive +infinity (`roundTowardPositive') and toward negative infinity (`roundTowardNegative') are often used to implement interval arithmetic, where you adjust the rounding mode to calculate upper and lower bounds for the range of output. The `roundTowardZero' mode can be @@ -22502,7 +22504,7 @@ floating-point values: If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for -correct output (using the formula `prec = 3.322 * dps'), would be 3.322 +correct output (using the formula `prec = 3.322 * dps') would be 3.322 x 183231, or 608693. The result from an arithmetic operation with an integer and a @@ -22533,7 +22535,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or -want, you can employ a subterfuge, and convert the integer to floating +want, you can employ a subterfuge and convert the integer to floating point first, like this: gawk -M 'BEGIN { n = 13; print (n + 0.0) % 2.0 }' @@ -22616,7 +22618,7 @@ File: gawk.info, Node: POSIX Floating Point Problems, Next: Floating point sum 15.6 Standards Versus Existing Practice ======================================= -Historically, `awk' has converted any non-numeric looking string to the +Historically, `awk' has converted any nonnumeric-looking string to the numeric value zero, when required. Furthermore, the original definition of the language and the original POSIX standards specified that `awk' only understands decimal numbers (base 10), and not octal @@ -22630,8 +22632,8 @@ These features are: hexadecimal notation (e.g., `0xDEADBEEF'). (Note: data values, _not_ source code constants.) - * Support for the special IEEE 754 floating-point values "Not A - Number" (NaN), positive Infinity ("inf"), and negative Infinity + * Support for the special IEEE 754 floating-point values "not a + number" (NaN), positive infinity ("inf"), and negative infinity ("-inf"). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @@ -22648,21 +22650,21 @@ historical practice: values is also a very severe departure from historical practice. The second problem is that the `gawk' maintainer feels that this -interpretation of the standard, which requires a certain amount of +interpretation of the standard, which required a certain amount of "language lawyering" to arrive at in the first place, was not even -intended by the standard developers. In other words, "we see how you +intended by the standard developers. In other words, "We see how you got where you are, but we don't think that that's where you want to be." Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that `awk' support -hexadecimal floating-point values and special values for "Not A Number" +hexadecimal floating-point values and special values for "not a number" and infinity. Although the `gawk' maintainer continues to feel that providing those features is inadvisable, nevertheless, on systems that support IEEE floating point, it seems reasonable to provide _some_ way to -support NaN and Infinity values. The solution implemented in `gawk' is +support NaN and infinity values. The solution implemented in `gawk' is as follows: * With the `--posix' command-line option, `gawk' becomes "hands @@ -22677,7 +22679,7 @@ as follows: $ echo 0xDeadBeef | gawk --posix '{ print $1 + 0 }' -| 3735928559 - * Without `--posix', `gawk' interprets the four strings `+inf', + * Without `--posix', `gawk' interprets the four string values `+inf', `-inf', `+nan', and `-nan' specially, producing the corresponding special numeric values. The leading sign acts a signal to `gawk' (and the user) that the value is really numeric. Hexadecimal @@ -22691,7 +22693,7 @@ as follows: $ echo 0xDeadBeef | gawk '{ print $1 + 0 }' -| 0 - `gawk' ignores case in the four special values. Thus `+nan' and + `gawk' ignores case in the four special values. Thus, `+nan' and `+NaN' are the same. ---------- Footnotes ---------- @@ -22708,9 +22710,9 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob floating-point values. Standard `awk' uses double-precision floating-point values. - * In the early 1990s, Barbie mistakenly said "Math class is tough!" + * In the early 1990s Barbie mistakenly said, "Math class is tough!" Although math isn't tough, floating-point arithmetic isn't the same - as pencil and paper math, and care must be taken: + as pencil-and-paper math, and care must be taken: - Not all numbers can be represented exactly. @@ -22731,7 +22733,7 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob rounding mode. * With `-M', `gawk' performs arbitrary-precision integer arithmetic - using the GMP library. This is faster and more space efficient + using the GMP library. This is faster and more space-efficient than using MPFR for the same calculations. * There are several "dark corners" with respect to floating-point @@ -22742,7 +22744,7 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and paper. In order to take advantage of - the power of computer floating point, you need to know its + the power of floating-point arithmetic, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the @@ -22801,7 +22803,7 @@ the rest of this Info file. `gawk''s functionality. For example, they can provide access to system calls (such as `chdir()' to change directory) and to other C library routines that could be of use. As with most software, "the sky is the -limit;" if you can imagine something that you might want to do and can +limit"; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the "application @@ -22809,7 +22811,7 @@ programming interface" (API) defined for this purpose by the `gawk' developers. The rest of this major node explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents the sample extensions included in -the `gawk' distribution, and describes the `gawkextlib' project. *Note +the `gawk' distribution and describes the `gawkextlib' project. *Note Extension Design::, for a discussion of the extension mechanism goals and design. @@ -22927,7 +22929,7 @@ Example::) and also in the `testext.c' code for testing the APIs. Some other bits and pieces: * The API provides access to `gawk''s `do_XXX' values, reflecting - command-line options, like `do_lint', `do_profiling' and so on + command-line options, like `do_lint', `do_profiling', and so on (*note Extension API Variables::). These are informational: an extension cannot affect their values inside `gawk'. In addition, attempting to assign to them produces a compile-time error. @@ -22973,8 +22975,8 @@ File: gawk.info, Node: Extension API Functions Introduction, Next: General Dat 16.4.1 Introduction ------------------- -Access to facilities within `gawk' are made available by calling -through function pointers passed into your extension. +Access to facilities within `gawk' is achieved by calling through +function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -22995,7 +22997,7 @@ operations: - Two-way processors - All of these are discussed in detail, later in this major node. + All of these are discussed in detail later in this major node. * Printing fatal, warning, and "lint" warning messages. @@ -23021,7 +23023,7 @@ operations: - Clearing an array - - Flattening an array for easy C style looping over all its + - Flattening an array for easy C-style looping over all its indices and elements Some points about using the API: @@ -23030,7 +23032,7 @@ operations: `gawkapi.h'. For correct use, you must therefore include the corresponding standard header file _before_ including `gawkapi.h': - C Entity Header File + C entity Header file ------------------------------------------- `EOF' `<stdio.h>' Values for `errno' `<errno.h>' @@ -23054,13 +23056,13 @@ operations: * Although the API only uses ISO C 90 features, there is an exception; the "constructor" functions use the `inline' keyword. If your compiler does not support this keyword, you should either - place `-Dinline=''' on your command line, or use the GNU Autotools + place `-Dinline=''' on your command line or use the GNU Autotools and include a `config.h' file in your extensions. * All pointers filled in by `gawk' point to memory managed by `gawk' and should be treated by the extension as read-only. Memory for _all_ strings passed into `gawk' from the extension _must_ come - from calling one of `gawk_malloc()', `gawk_calloc()' or + from calling one of `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()', and is managed by `gawk' from then on. * The API defines several simple `struct's that map values as seen @@ -23073,7 +23075,7 @@ operations: multibyte encoding (as defined by `LC_XXX' environment variables) and not using wide characters. This matches how `gawk' stores strings internally and also how characters are - likely to be input and output from files. + likely to be input into and output from files. * When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type @@ -23110,6 +23112,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent minor nodes, together with the functions that use them. + The general-purpose types and structures are as follows: + `typedef void *awk_ext_id_t;' A value of this type is received from `gawk' when an extension is loaded. That value must then be passed back to `gawk' as the @@ -23125,7 +23129,7 @@ use them. ` awk_false = 0,' ` awk_true' `} awk_bool_t;' - A simple boolean type. + A simple Boolean type. `typedef struct awk_string {' ` char *str; /* data */' @@ -23169,8 +23173,8 @@ use them. `#define array_cookie u.a' `#define scalar_cookie u.scl' `#define value_cookie u.vc' - These macros make accessing the fields of the `awk_value_t' more - readable. + Using these macros makes accessing the fields of the `awk_value_t' + more readable. `typedef void *awk_scalar_t;' Scalars can be represented as an opaque type. These values are @@ -23190,8 +23194,8 @@ indicates what is in the `union'. Representing numbers is easy--the API uses a C `double'. Strings require more work. Because `gawk' allows embedded NUL bytes in string -values, a string must be represented as a pair containing a -data-pointer and length. This is the `awk_string_t' type. +values, a string must be represented as a pair containing a data +pointer and length. This is the `awk_string_t' type. Identifiers (i.e., the names of global variables) can be associated with either scalar values or with arrays. In addition, `gawk' provides @@ -23203,12 +23207,12 @@ Manipulation::. of the `union' as if they were fields in a `struct'; this is a common coding practice in C. Such code is easier to write and to read, but it remains _your_ responsibility to make sure that the `val_type' member -correctly reflects the type of the value in the `awk_value_t'. +correctly reflects the type of the value in the `awk_value_t' struct. Conceptually, the first three members of the `union' (number, string, and array) are all that is needed for working with `awk' values. However, because the API provides routines for accessing and changing -the value of global scalar variables only by using the variable's name, +the value of a global scalar variable only by using the variable's name, there is a performance penalty: `gawk' must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -23217,17 +23221,19 @@ just a theoretical one. reading and/or changing the value of one or more scalar variables, you can obtain a "scalar cookie"(1) object for that variable, and then use the cookie for getting the variable's value or for changing the -variable's value. This is the `awk_scalar_t' type and `scalar_cookie' -macro. Given a scalar cookie, `gawk' can directly retrieve or modify -the value, as required, without having to find it first. +variable's value. The `awk_scalar_t' type holds a scalar cookie, and +the `scalar_cookie' macro provides access to the value of that type in +the `awk_value_t' struct. Given a scalar cookie, `gawk' can directly +retrieve or modify the value, as required, without having to find it +first. The `awk_value_cookie_t' type and `value_cookie' macro are similar. If you know that you wish to use the same numeric or string _value_ for one or more variables, you can create the value once, retaining a "value cookie" for it, and then pass in that value cookie whenever you -wish to set the value of a variable. This saves both storage space -within the running `gawk' process as well as the time needed to create -the value. +wish to set the value of a variable. This saves storage space within +the running `gawk' process and reduces the time needed to create the +value. ---------- Footnotes ---------- @@ -23262,7 +23268,7 @@ prototypes, in the way that extension code would use them: `void gawk_free(void *ptr);' Call the correct version of `free()' to release storage that was - allocated with `gawk_malloc()', `gawk_calloc()' or + allocated with `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()'. The API has to provide these functions because it is possible for an @@ -23274,7 +23280,7 @@ version of `malloc()', unexpected behavior would likely result. Two convenience macros may be used for allocating storage from `gawk_malloc()' and `gawk_realloc()'. If the allocation fails, they cause `gawk' to exit with a fatal error message. They should be used -as if they were procedure calls that do not return a value. +as if they were procedure calls that do not return a value: `#define emalloc(pointer, type, size, message) ...' The arguments to this macro are as follows: @@ -23304,13 +23310,13 @@ as if they were procedure calls that do not return a value. make_malloced_string(message, strlen(message), & result); `#define erealloc(pointer, type, size, message) ...' - This is like `emalloc()', but it calls `gawk_realloc()', instead - of `gawk_malloc()'. The arguments are the same as for the + This is like `emalloc()', but it calls `gawk_realloc()' instead of + `gawk_malloc()'. The arguments are the same as for the `emalloc()' macro. ---------- Footnotes ---------- - (1) This is more common on MS-Windows systems, but can happen on + (1) This is more common on MS-Windows systems, but it can happen on Unix-like systems as well. @@ -23336,7 +23342,7 @@ extension code would use them: This function creates a string value in the `awk_value_t' variable pointed to by `result'. It expects `string' to be a `char *' value pointing to data previously obtained from `gawk_malloc()', - `gawk_calloc()' or `gawk_realloc()'. The idea here is that the + `gawk_calloc()', or `gawk_realloc()'. The idea here is that the data is passed directly to `gawk', which assumes responsibility for it. It returns `result'. @@ -23386,7 +23392,7 @@ Extension functions are described by the following record: The fields are: `const char *name;' - The name of the new function. `awk' level code calls the function + The name of the new function. `awk'-level code calls the function by this name. This is a regular C string. Function names must obey the rules for `awk' identifiers. That is, @@ -23398,7 +23404,7 @@ Extension functions are described by the following record: This is a pointer to the C function that provides the extension's functionality. The function must fill in `*result' with either a number or a string. `gawk' takes ownership of any string memory. - As mentioned earlier, string memory *must* come from one of + As mentioned earlier, string memory _must_ come from one of `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()'. The `num_actual_args' argument tells the C function how many @@ -23445,10 +23451,10 @@ function with `gawk' using the following function: `gawk' intends to pass to the `exit()' system call. `arg0' - A pointer to private data which `gawk' saves in order to pass + A pointer to private data that `gawk' saves in order to pass to the function pointed to by `funcp'. - Exit callback functions are called in last-in-first-out (LIFO) + Exit callback functions are called in last-in, first-out (LIFO) order--that is, in the reverse order in which they are registered with `gawk'. @@ -23458,8 +23464,8 @@ File: gawk.info, Node: Extension Version String, Next: Input Parsers, Prev: E 16.4.5.3 Registering An Extension Version String ................................................ -You can register a version string which indicates the name and version -of your extension, with `gawk', as follows: +You can register a version string that indicates the name and version +of your extension with `gawk', as follows: `void register_ext_version(const char *version);' Register the string pointed to by `version' with `gawk'. Note @@ -23482,7 +23488,7 @@ Files::). Additionally, it sets the value of `RT' (*note Built-in Variables::). If you want, you can provide your own custom input parser. An input -parser's job is to return a record to the `gawk' record processing +parser's job is to return a record to the `gawk' record-processing code, along with indicators for the value and length of the data to be used for `RT', if any. @@ -23499,10 +23505,10 @@ used for `RT', if any. `awk_bool_t XXX_take_control_of(awk_input_buf_t *iobuf);' When `gawk' decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill - in certain fields in the `awk_input_buf_t' structure, and ensure + in certain fields in the `awk_input_buf_t' structure and ensure that certain conditions are true. It should then return true. If - an error of some kind occurs, it should not fill in any fields, - and should return false; then `gawk' will not use the input parser. + an error of some kind occurs, it should not fill in any fields and + should return false; then `gawk' will not use the input parser. The details are presented shortly. Your extension should package these functions inside an @@ -23579,10 +23585,10 @@ the `struct stat', or any combination of these factors. Once `XXX_can_take_file()' has returned true, and `gawk' has decided to use your input parser, it calls `XXX_take_control_of()'. That -function then fills one of either the `get_record' field or the -`read_func' field in the `awk_input_buf_t'. It must also ensure that -`fd' is _not_ set to `INVALID_HANDLE'. The following list describes -the fields that may be filled by `XXX_take_control_of()': +function then fills either the `get_record' field or the `read_func' +field in the `awk_input_buf_t'. It must also ensure that `fd' is _not_ +set to `INVALID_HANDLE'. The following list describes the fields that +may be filled by `XXX_take_control_of()': `void *opaque;' This is used to hold any state information needed by the input @@ -23599,22 +23605,22 @@ the fields that may be filled by `XXX_take_control_of()': Its behavior is described in the text following this list. `ssize_t (*read_func)();' - This function pointer should point to function that has the same + This function pointer should point to a function that has the same behavior as the standard POSIX `read()' system call. It is an alternative to the `get_record' pointer. Its behavior is also described in the text following this list. `void (*close_func)(struct awk_input *iobuf);' This function pointer should point to a function that does the - "tear down." It should release any resources allocated by + "teardown." It should release any resources allocated by `XXX_take_control_of()'. It may also close the file. If it does so, it should set the `fd' field to `INVALID_HANDLE'. If `fd' is still not `INVALID_HANDLE' after the call to this function, `gawk' calls the regular `close()' system call. - Having a "tear down" function is optional. If your input parser - does not need it, do not set this field. Then, `gawk' calls the + Having a "teardown" function is optional. If your input parser does + not need it, do not set this field. Then, `gawk' calls the regular `close()' system call on the file descriptor, so it should be valid. @@ -23622,7 +23628,7 @@ the fields that may be filled by `XXX_take_control_of()': records. The parameters are as follows: `char **out' - This is a pointer to a `char *' variable which is set to point to + This is a pointer to a `char *' variable that is set to point to the record. `gawk' makes its own copy of the data, so the extension must manage this storage. @@ -23671,16 +23677,16 @@ explicitly. NOTE: You must choose one method or the other: either a function that returns a record, or one that returns raw data. In particular, if you supply a function to get a record, `gawk' will - call it, and never call the raw read function. + call it, and will never call the raw read function. `gawk' ships with a sample extension that reads directories, -returning records for each entry in the directory (*note Extension -Sample Readdir::). You may wish to use that code as a guide for writing -your own input parser. +returning records for each entry in a directory (*note Extension Sample +Readdir::). You may wish to use that code as a guide for writing your +own input parser. When writing an input parser, you should think about (and document) how it is expected to interact with `awk' code. You may want it to -always be called, and take effect as appropriate (as the `readdir' +always be called, and to take effect as appropriate (as the `readdir' extension does). Or you may want it to take effect based upon the value of an `awk' variable, as the XML extension from the `gawkextlib' project does (*note gawkextlib::). In the latter case, code in a @@ -23780,17 +23786,17 @@ in the `awk_output_buf_t'. The data members are as follows: These pointers should be set to point to functions that perform the equivalent function as the `<stdio.h>' functions do, if appropriate. `gawk' uses these function pointers for all output. - `gawk' initializes the pointers to point to internal, "pass - through" functions that just call the regular `<stdio.h>' - functions, so an extension only needs to redefine those functions - that are appropriate for what it does. + `gawk' initializes the pointers to point to internal "pass-through" + functions that just call the regular `<stdio.h>' functions, so an + extension only needs to redefine those functions that are + appropriate for what it does. The `XXX_can_take_file()' function should make a decision based upon the `name' and `mode' fields, and any additional state (such as `awk' variable values) that is appropriate. When `gawk' calls `XXX_take_control_of()', that function should fill -in the other fields, as appropriate, except for `fp', which it should +in the other fields as appropriate, except for `fp', which it should just use normally. You register your output wrapper with the following function: @@ -23827,16 +23833,17 @@ structures as described earlier. The name of the two-way processor. `awk_bool_t (*can_take_two_way)(const char *name);' - This function returns true if it wants to take over two-way I/O - for this file name. It should not change any state (variable - values, etc.) within `gawk'. + The function pointed to by this field should return true if it + wants to take over two-way I/O for this file name. It should not + change any state (variable values, etc.) within `gawk'. `awk_bool_t (*take_control_of)(const char *name,' ` awk_input_buf_t *inbuf,' ` awk_output_buf_t *outbuf);' - This function should fill in the `awk_input_buf_t' and - `awk_outut_buf_t' structures pointed to by `inbuf' and `outbuf', - respectively. These structures were described earlier. + The function pointed to by this field should fill in the + `awk_input_buf_t' and `awk_outut_buf_t' structures pointed to by + `inbuf' and `outbuf', respectively. These structures were + described earlier. `awk_const struct two_way_processor *awk_const next;' This is for use by `gawk'; therefore it is marked `awk_const' so @@ -23860,7 +23867,7 @@ File: gawk.info, Node: Printing Messages, Next: Updating `ERRNO', Prev: Regis You can print different kinds of warning messages from your extension, as described here. Note that for these functions, you must pass in the -extension id received from `gawk' when the extension was loaded:(1) +extension ID received from `gawk' when the extension was loaded:(1) `void fatal(awk_ext_id_t id, const char *format, ...);' Print a message and then cause `gawk' to exit immediately. @@ -23916,7 +23923,7 @@ value you expect. If the actual value matches what you requested, the function returns true and fills in the `awk_value_t' result. Otherwise, the function returns false, and the `val_type' member indicates the type of the actual value. You may then print an error -message, or reissue the request for the actual value type, as +message or reissue the request for the actual value type, as appropriate. This behavior is summarized in *note table-value-types-returned::. @@ -23925,15 +23932,15 @@ table-value-types-returned::. String Number Array Undefined ------------------------------------------------------------------------------ - String String String false false - Number Number if can Number false false + String String String False False + Number Number if can Number False False be converted, else false -Type Array false false Array false -Requested Scalar Scalar Scalar false false +Type Array False False Array False +Requested Scalar Scalar Scalar False False Undefined String Number Array Undefined - Value false false false false - Cookie + Value False False False False + cookie Table 16.1: API value types returned @@ -23950,16 +23957,16 @@ your extension function. They are: ` awk_valtype_t wanted,' ` awk_value_t *result);' Fill in the `awk_value_t' structure pointed to by `result' with - the `count''th argument. Return true if the actual type matches - `wanted', false otherwise. In the latter case, `result->val_type' - indicates the actual type (*note Table 16.1: - table-value-types-returned.). Counts are zero based--the first + the `count'th argument. Return true if the actual type matches + `wanted', and false otherwise. In the latter case, + `result->val_type' indicates the actual type (*note Table 16.1: + table-value-types-returned.). Counts are zero-based--the first argument is numbered zero, the second one, and so on. `wanted' indicates the type of value expected. `awk_bool_t set_argument(size_t count, awk_array_t array);' Convert a parameter that was undefined into an array; this provides - call-by-reference for arrays. Return false if `count' is too big, + call by reference for arrays. Return false if `count' is too big, or if the argument's type is not undefined. *Note Array Manipulation::, for more information on creating arrays. @@ -23987,8 +23994,8 @@ File: gawk.info, Node: Symbol table by name, Next: Symbol table by cookie, Up The following routines provide the ability to access and update global `awk'-level variables by name. In compiler terminology, identifiers of different kinds are termed "symbols", thus the "sym" in the routines' -names. The data structure which stores information about symbols is -termed a "symbol table". +names. The data structure that stores information about symbols is +termed a "symbol table". The functions are as follows: `awk_bool_t sym_lookup(const char *name,' ` awk_valtype_t wanted,' @@ -23996,14 +24003,14 @@ termed a "symbol table". Fill in the `awk_value_t' structure pointed to by `result' with the value of the variable named by the string `name', which is a regular C string. `wanted' indicates the type of value expected. - Return true if the actual type matches `wanted', false otherwise. - In the latter case, `result->val_type' indicates the actual type - (*note Table 16.1: table-value-types-returned.). + Return true if the actual type matches `wanted', and false + otherwise. In the latter case, `result->val_type' indicates the + actual type (*note Table 16.1: table-value-types-returned.). `awk_bool_t sym_update(const char *name, awk_value_t *value);' Update the variable named by the string `name', which is a regular C string. The variable is added to `gawk''s symbol table if it is - not there. Return true if everything worked, false otherwise. + not there. Return true if everything worked, and false otherwise. Changing types (scalar to array or vice versa) of an existing variable is _not_ allowed, nor may this routine be used to update @@ -24028,7 +24035,7 @@ File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Sym A "scalar cookie" is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in `gawk''s symbol table every time access is needed. This -was discussed earlier in *note General Data Types::. +was discussed earlier, in *note General Data Types::. The following functions let you work with scalar cookies: @@ -24139,7 +24146,7 @@ File: gawk.info, Node: Cached values, Prev: Symbol table by cookie, Up: Symbo .......................................... The routines in this section allow you to create and release cached -values. As with scalar cookies, in theory, cached values are not +values. Like scalar cookies, in theory, cached values are not necessary. You can create numbers and strings using the functions in *note Constructor Functions::. You can then assign those values to variables using `sym_update()' or `sym_update_scalar()', as you like. @@ -24210,7 +24217,7 @@ Using value cookies in this way saves considerable storage, as all of `VAR1' through `VAR100' share the same value. You might be wondering, "Is this sharing problematic? What happens -if `awk' code assigns a new value to `VAR1', are all the others changed +if `awk' code assigns a new value to `VAR1'; are all the others changed too?" That's a great question. The answer is that no, it's not a problem. @@ -24329,7 +24336,7 @@ File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev: Array 16.4.11.2 Array Functions ......................... -The following functions relate to individual array elements. +The following functions relate to individual array elements: `awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);' For the array represented by `a_cookie', place in `*count' the @@ -24347,13 +24354,14 @@ The following functions relate to individual array elements. (*note Table 16.1: table-value-types-returned.). The value for `index' can be numeric, in which case `gawk' - converts it to a string. Using non-integral values is possible, but + converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to - strings (*note Conversion::); thus using integral values is safest. + strings (*note Conversion::); thus, using integral values is + safest. As with _all_ strings passed into `gawk' from an extension, the string value of `index' must come from `gawk_malloc()', - `gawk_calloc()' or `gawk_realloc()', and `gawk' releases the + `gawk_calloc()', or `gawk_realloc()', and `gawk' releases the storage. `awk_bool_t set_array_element(awk_array_t a_cookie,' @@ -24397,9 +24405,9 @@ The following functions relate to individual array elements. `awk_bool_t release_flattened_array(awk_array_t a_cookie,' ` awk_flat_array_t *data);' When done with a flattened array, release the storage using this - function. You must pass in both the original array cookie, and - the address of the created `awk_flat_array_t' structure. The - function returns true upon success, false otherwise. + function. You must pass in both the original array cookie and the + address of the created `awk_flat_array_t' structure. The function + returns true upon success, false otherwise. File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array Functions, Up: Array Manipulation @@ -24409,8 +24417,8 @@ File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array To "flatten" an array is to create a structure that represents the full array in a fashion that makes it easy for C code to traverse the entire -array. Test code in `extension/testext.c' does this, and also serves -as a nice example showing how to use the APIs. +array. Some of the code in `extension/testext.c' does this, and also +serves as a nice example showing how to use the APIs. We walk through that part of the code one step at a time. First, the `gawk' script that drives the test extension: @@ -24459,9 +24467,8 @@ number of arguments: } The function then proceeds in steps, as follows. First, retrieve the -name of the array, passed as the first argument. Then retrieve the -array itself. If either operation fails, print error messages and -return: +name of the array, passed as the first argument, followed by the array +itself. If either operation fails, print an error message and return: /* get argument named array as flat array and print it */ if (get_argument(0, AWK_STRING, & value)) { @@ -24491,9 +24498,9 @@ count of elements in the array and print it: printf("dump_array_and_delete: incoming size is %lu\n", (unsigned long) count); - The third step is to actually flatten the array, and then to double -check that the count in the `awk_flat_array_t' is the same as the count -just retrieved: + The third step is to actually flatten the array, and then to +double-check that the count in the `awk_flat_array_t' is the same as +the count just retrieved: if (! flatten_array(value2.array_cookie, & flat_array)) { printf("dump_array_and_delete: could not flatten array\n"); @@ -24510,7 +24517,7 @@ just retrieved: The fourth step is to retrieve the index of the element to be deleted, which was passed as the second argument. Remember that -argument counts passed to `get_argument()' are zero-based, thus the +argument counts passed to `get_argument()' are zero-based, and thus the second argument is numbered one: if (! get_argument(1, AWK_STRING, & value3)) { @@ -24523,7 +24530,7 @@ over every element in the array, printing the index and element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the `AWK_ELEMENT_DELETE' bit in the `flags' field of the element. When the array is released, `gawk' -traverses the flattened array, and deletes any elements which have this +traverses the flattened array, and deletes any elements that have this flag bit set: for (i = 0; i < flat_array->count; i++) { @@ -24741,10 +24748,10 @@ The API provides both a "major" and a "minor" version number. The API versions are available at compile time as constants: `GAWK_API_MAJOR_VERSION' - The major version of the API. + The major version of the API `GAWK_API_MINOR_VERSION' - The minor version of the API. + The minor version of the API The minor version increases when new functions are added to the API. Such new functions are always added to the end of the API `struct'. @@ -24759,13 +24766,13 @@ For this reason, the major and minor API versions of the running `gawk' are included in the API `struct' as read-only constant integers: `api->major_version' - The major version of the running `gawk'. + The major version of the running `gawk' `api->minor_version' - The minor version of the running `gawk'. + The minor version of the running `gawk' It is up to the extension to decide if there are API -incompatibilities. Typically a check like this is enough: +incompatibilities. Typically, a check like this is enough: if (api->major_version != GAWK_API_MAJOR_VERSION || api->minor_version < GAWK_API_MINOR_VERSION) { @@ -24777,7 +24784,7 @@ incompatibilities. Typically a check like this is enough: } Such code is included in the boilerplate `dl_load_func()' macro -provided in `gawkapi.h' (discussed later, in *note Extension API +provided in `gawkapi.h' (discussed in *note Extension API Boilerplate::). @@ -24828,7 +24835,7 @@ functions) toward the top of your source file, using predefined names as described here. The boilerplate needed is also provided in comments in the `gawkapi.h' header file: - /* Boiler plate code: */ + /* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -24878,7 +24885,7 @@ in the `gawkapi.h' header file: to point to a string giving the name and version of your extension. `static awk_ext_func_t func_table[] = { ... };' - This is an array of one or more `awk_ext_func_t' structures as + This is an array of one or more `awk_ext_func_t' structures, as described earlier (*note Extension Functions::). It can then be looped over for multiple calls to `add_ext_func()'. @@ -24991,7 +24998,7 @@ appropriate information: `stat()' fails. It fills in the following elements: `"name"' - The name of the file that was `stat()''ed. + The name of the file that was `stat()'ed. `"dev"' `"ino"' @@ -25039,7 +25046,7 @@ appropriate information: The file is a directory. `"fifo"' - The file is a named-pipe (also known as a FIFO). + The file is a named pipe (also known as a FIFO). `"file"' The file is just a regular file. @@ -25059,7 +25066,7 @@ appropriate information: systems, "a priori" knowledge is used to provide a value. Where no value can be determined, it defaults to 512. - Several additional elements may be present depending upon the + Several additional elements may be present, depending upon the operating system and the type of the file. You can test for them in your `awk' program by using the `in' operator (*note Reference to Elements::): @@ -25088,9 +25095,9 @@ File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops, Prev Here is the C code for these extensions.(1) The file includes a number of standard header files, and then -includes the `gawkapi.h' header file which provides the API definitions. -Those are followed by the necessary variable declarations to make use -of the API macros and boilerplate code (*note Extension API +includes the `gawkapi.h' header file, which provides the API +definitions. Those are followed by the necessary variable declarations +to make use of the API macros and boilerplate code (*note Extension API Boilerplate::): #ifdef HAVE_CONFIG_H @@ -25126,9 +25133,9 @@ Boilerplate::): By convention, for an `awk' function `foo()', the C function that implements it is called `do_foo()'. The function should have two -arguments: the first is an `int' usually called `nargs', that +arguments. The first is an `int', usually called `nargs', that represents the number of actual arguments for the function. The second -is a pointer to an `awk_value_t', usually named `result': +is a pointer to an `awk_value_t' structure, usually named `result': /* do_chdir --- provide dynamically loaded chdir() function for gawk */ @@ -25164,8 +25171,8 @@ is numbered zero. } The `stat()' extension is more involved. First comes a function -that turns a numeric mode into a printable representation (e.g., 644 -becomes `-rw-r--r--'). This is omitted here for brevity: +that turns a numeric mode into a printable representation (e.g., octal +`0644' becomes `-rw-r--r--'). This is omitted here for brevity: /* format_mode --- turn a stat mode field into something readable */ @@ -25215,8 +25222,8 @@ contain the result of the `stat()': The following function does most of the work to fill in the `awk_array_t' result array with values obtained from a valid `struct -stat'. It is done in a separate function to support the `stat()' -function for `gawk' and also to support the `fts()' extension which is +stat'. This work is done in a separate function to support the `stat()' +function for `gawk' and also to support the `fts()' extension, which is included in the same file but whose code is not shown here (*note Extension Sample File Functions::). @@ -25328,8 +25335,8 @@ argument is optional. If present, it causes `do_stat()' to use the `stat()' system call instead of the `lstat()' system call. This is done by using a function pointer: `statfunc'. `statfunc' is initialized to point to `lstat()' (instead of `stat()') to get the file -information, in case the file is a symbolic link. However, if there -were three arguments, `statfunc' is set point to `stat()', instead. +information, in case the file is a symbolic link. However, if the third +argument is included, `statfunc' is set to point to `stat()', instead. Here is the `do_stat()' function, which starts with variable declarations and argument checking: @@ -25378,7 +25385,7 @@ returns: /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) { update_ERRNO_int(errno); @@ -25397,7 +25404,8 @@ When done, the function returns the result from `fill_stat_array()': function(s) into `gawk'. The `filefuncs' extension also provides an `fts()' function, which -we omit here. For its sake there is an initialization function: +we omit here (*note Extension Sample File Functions::). For its sake, +there is an initialization function: /* init_filefuncs --- initialization routine */ @@ -25521,9 +25529,9 @@ File: gawk.info, Node: Extension Samples, Next: gawkextlib, Prev: Extension E 16.7 The Sample Extensions in the `gawk' Distribution ===================================================== -This minor node provides brief overviews of the sample extensions that +This minor node provides a brief overview of the sample extensions that come in the `gawk' distribution. Some of them are intended for -production use (e.g., the `filefuncs', `readdir' and `inplace' +production use (e.g., the `filefuncs', `readdir', and `inplace' extensions). Others mainly provide example code that shows how to use the extension API. @@ -25560,13 +25568,13 @@ follows. The usage is: `result = chdir("/some/directory")' The `chdir()' function is a direct hook to the `chdir()' system call to change the current directory. It returns zero upon - success or less than zero upon error. In the latter case, it - updates `ERRNO'. + success or a value less than zero upon error. In the latter case, + it updates `ERRNO'. `result = stat("/some/path", statdata' [`, follow']`)' The `stat()' function provides a hook into the `stat()' system - call. It returns zero upon success or less than zero upon error. - In the latter case, it updates `ERRNO'. + call. It returns zero upon success or a value less than zero upon + error. In the latter case, it updates `ERRNO'. By default, it uses the `lstat()' system call. However, if passed a third argument, it uses `stat()' instead. @@ -25593,23 +25601,23 @@ follows. The usage is: `"minor"' `st_minor' Device files `"blksize"'`st_blksize' All `"pmode"' A human-readable version of the All - mode value, such as printed by - `ls'. For example, - `"-rwxr-xr-x"' + mode value, like that printed by + `ls' (for example, + `"-rwxr-xr-x"') `"linkval"'The value of the symbolic link Symbolic links - `"type"' The type of the file as a string. All - One of `"file"', `"blockdev"', - `"chardev"', `"directory"', - `"socket"', `"fifo"', `"symlink"', - `"door"', or `"unknown"'. Not - all systems support all file - types. + `"type"' The type of the file as a All + string--one of `"file"', + `"blockdev"', `"chardev"', + `"directory"', `"socket"', + `"fifo"', `"symlink"', `"door"', + or `"unknown"' (not all systems + support all file types) `flags = or(FTS_PHYSICAL, ...)' `result = fts(pathlist, flags, filedata)' Walk the file trees provided in `pathlist' and fill in the - `filedata' array as described next. `flags' is the bitwise OR of + `filedata' array, as described next. `flags' is the bitwise OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return -1. @@ -25662,10 +25670,11 @@ requested hierarchies. filesystem. `filedata' - The `filedata' array is first cleared. Then, `fts()' creates an - element in `filedata' for every element in `pathlist'. The index - is the name of the directory or file given in `pathlist'. The - element for this index is itself an array. There are two cases: + The `filedata' array holds the results. `fts()' first clears it. + Then it creates an element in `filedata' for every element in + `pathlist'. The index is the name of the directory or file given + in `pathlist'. The element for this index is itself an array. + There are two cases: _The path is a file_ In this case, the array contains two or three elements: @@ -25701,7 +25710,7 @@ requested hierarchies. elements as for a file: `"path"', `"stat"', and `"error"'. The `fts()' function returns zero if there were no errors. -Otherwise it returns -1. +Otherwise, it returns -1. NOTE: The `fts()' extension does not exactly mimic the interface of the C library `fts()' routines, choosing instead to provide an @@ -25740,14 +25749,14 @@ adds one constant (`FNM_NOMATCH'), and an array of flag values named The arguments to `fnmatch()' are: `pattern' - The file name wildcard to match. + The file name wildcard to match `string' - The file name string. + The file name string `flag' Either zero, or the bitwise OR of one or more of the flags in the - `FNM' array. + `FNM' array The flags are as follows: @@ -25781,13 +25790,13 @@ The `fork' extension adds three functions, as follows: `pid = fork()' This function creates a new process. The return value is zero in - the child and the process-ID number of the child in the parent, or + the child and the process ID number of the child in the parent, or -1 upon error. In the latter case, `ERRNO' indicates the problem. In the child, `PROCINFO["pid"]' and `PROCINFO["ppid"]' are updated to reflect the correct values. `ret = waitpid(pid)' - This function takes a numeric argument, which is the process-ID to + This function takes a numeric argument, which is the process ID to wait for. The return value is that of the `waitpid()' system call. `ret = wait()' @@ -25811,8 +25820,8 @@ File: gawk.info, Node: Extension Sample Inplace, Next: Extension Sample Ord, 16.7.4 Enabling In-Place File Editing ------------------------------------- -The `inplace' extension emulates GNU `sed''s `-i' option which performs -"in place" editing of each input file. It uses the bundled +The `inplace' extension emulates GNU `sed''s `-i' option, which +performs "in-place" editing of each input file. It uses the bundled `inplace.awk' include file to invoke the extension properly: # inplace --- load and invoke the inplace extension. @@ -25895,11 +25904,11 @@ returned as a record. The record consists of three fields. The first two are the inode number and the file name, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +has a third field (also separated by a slash), which is a single letter indicating the type of the file. The letters and their corresponding file types are shown in *note table-readdir-file-types::. -Letter File Type +Letter File type -------------------------------------------------------------------------- `b' Block device `c' Character device @@ -25946,7 +25955,7 @@ unwary. Here is an example: print "don't panic" > "/dev/stdout" } - The output from this program is: `cinap t'nod'. + The output from this program is `cinap t'nod'. File: gawk.info, Node: Extension Sample Rev2way, Next: Extension Sample Read write array, Prev: Extension Sample Revout, Up: Extension Samples @@ -25994,7 +26003,7 @@ The `rwarray' extension adds two functions, named `writea()' and `reada()' is the inverse of `writea()'; it reads the file named as its first argument, filling in the array named as the second argument. It clears the array first. Here too, the return value - is one on success and zero upon failure. + is one on success, or zero upon failure. The array created by `reada()' is identical to that written by `writea()' in the sense that the contents are the same. However, due to @@ -26078,7 +26087,7 @@ The `time' extension adds two functions, named `gettimeofday()' and Attempt to sleep for SECONDS seconds. If SECONDS is negative, or the attempt to sleep fails, return -1 and set `ERRNO'. Otherwise, return zero after sleeping for the indicated amount of time. Note - that SECONDS may be a floating-point (non-integral) value. + that SECONDS may be a floating-point (nonintegral) value. Implementation details: depending on platform availability, this function tries to use `nanosleep()' or `select()' to implement the delay. @@ -26106,7 +26115,9 @@ provides a number of `gawk' extensions, including one for processing XML files. This is the evolution of the original `xgawk' (XML `gawk') project. - As of this writing, there are six extensions: + As of this writing, there are seven extensions: + + * `errno' extension * GD graphics library extension @@ -26115,7 +26126,7 @@ project. * PostgreSQL extension * MPFR library extension (this provides access to a number of MPFR - functions which `gawk''s native MPFR support does not) + functions that `gawk''s native MPFR support does not) * Redis extension @@ -26156,7 +26167,7 @@ follows. First, build and install `gawk': If you have installed `gawk' in the standard way, then you will likely not need the `--with-gawk' option when configuring `gawkextlib'. -You may also need to use the `sudo' utility to install both `gawk' and +You may need to use the `sudo' utility to install both `gawk' and `gawkextlib', depending upon how your system works. If you write an extension that you wish to share with other `gawk' @@ -26178,7 +26189,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga a variable named `plugin_is_GPL_compatible'. * Communication between `gawk' and an extension is two-way. `gawk' - passes a `struct' to the extension which contains various data + passes a `struct' to the extension that contains various data fields and function pointers. The extension can then call into `gawk' via the supplied function pointers to accomplish certain tasks. @@ -26189,7 +26200,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga convention, implementation functions are named `do_XXXX()' for some `awk'-level function `XXXX()'. - * The API is defined in a header file named `gawkpi.h'. You must + * The API is defined in a header file named `gawkapi.h'. You must include a number of standard header files _before_ including it in your source file. @@ -26219,16 +26230,16 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * Manipulating arrays (retrieving, adding, deleting, and modifying elements; getting the count of elements in an array; creating a new array; clearing an array; and flattening an - array for easy C style looping over all its indices and + array for easy C-style looping over all its indices and elements) * The API defines a number of standard data types for representing `awk' values, array elements, and arrays. - * The API provide convenience functions for constructing values. It - also provides memory management functions to ensure compatibility - between memory allocated by `gawk' and memory allocated by an - extension. + * The API provides convenience functions for constructing values. + It also provides memory management functions to ensure + compatibility between memory allocated by `gawk' and memory + allocated by an extension. * _All_ memory passed from `gawk' to an extension must be treated as read-only by the extension. @@ -26246,8 +26257,8 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga header file make this easier to do. * The `gawk' distribution includes a number of small but useful - sample extensions. The `gawkextlib' project includes several more, - larger, extensions. If you wish to write an extension and + sample extensions. The `gawkextlib' project includes several more + (larger) extensions. If you wish to write an extension and contribute it to the community of `gawk' users, the `gawkextlib' project is the place to do so. @@ -32192,7 +32203,7 @@ Index * BEGIN pattern, and profiling: Profiling. (line 62) * BEGIN pattern, assert() user-defined function and: Assert Function. (line 83) -* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 69) +* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 70) * BEGIN pattern, exit statement and: Exit Statement. (line 12) * BEGIN pattern, getline and: Getline Notes. (line 19) * BEGIN pattern, headings, adding: Print Examples. (line 43) @@ -32209,7 +32220,7 @@ Index * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. (line 60) * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. - (line 69) + (line 70) * beginfile() user-defined function: Filetrans Function. (line 62) * Bentley, Jon: Glossary. (line 207) * Benzinger, Michael: Contributors. (line 97) @@ -32235,7 +32246,7 @@ Index * body, in actions: Statements. (line 10) * body, in loops: While Statement. (line 14) * Boolean expressions: Boolean Ops. (line 6) -* Boolean expressions, as patterns: Expression Patterns. (line 38) +* Boolean expressions, as patterns: Expression Patterns. (line 39) * Boolean operators, See Boolean expressions: Boolean Ops. (line 6) * Bourne shell, quoting rules for: Quoting. (line 18) * braces ({}): Profiling. (line 142) @@ -32820,7 +32831,7 @@ Index * END pattern, and profiling: Profiling. (line 62) * END pattern, assert() user-defined function and: Assert Function. (line 75) -* END pattern, Boolean patterns and: Expression Patterns. (line 69) +* END pattern, Boolean patterns and: Expression Patterns. (line 70) * END pattern, exit statement and: Exit Statement. (line 12) * END pattern, next/nextfile statements and <1>: Next Statement. (line 44) @@ -32829,7 +32840,7 @@ Index * END pattern, operators and: Using BEGIN/END. (line 17) * END pattern, print statement and: I/O And BEGIN/END. (line 16) * ENDFILE pattern: BEGINFILE/ENDFILE. (line 6) -* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 69) +* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 70) * endfile() user-defined function: Filetrans Function. (line 62) * endgrent() function (C library): Group Functions. (line 212) * endgrent() user-defined function: Group Functions. (line 215) @@ -32888,7 +32899,7 @@ Index (line 99) * exp: Numeric Functions. (line 33) * expand utility: Very Simple. (line 73) -* Expat XML parser library: gawkextlib. (line 33) +* Expat XML parser library: gawkextlib. (line 35) * exponent: Numeric Functions. (line 33) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) @@ -33308,7 +33319,7 @@ Index * git utility <2>: Accessing The Source. (line 10) * git utility <3>: Other Versions. (line 29) -* git utility: gawkextlib. (line 27) +* git utility: gawkextlib. (line 29) * Git, use of for gawk source code: Derived Files. (line 6) * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 51) @@ -34737,544 +34748,544 @@ Ref: Manual History-Footnote-167139 Ref: Manual History-Footnote-267180 Node: How To Contribute67254 Node: Acknowledgments68383 -Node: Getting Started73200 -Node: Running gawk75639 -Node: One-shot76829 -Node: Read Terminal78093 -Node: Long80124 -Node: Executable Scripts81637 -Ref: Executable Scripts-Footnote-184426 -Node: Comments84529 -Node: Quoting87011 -Node: DOS Quoting92529 -Node: Sample Data Files93204 -Node: Very Simple95799 -Node: Two Rules100698 -Node: More Complex102584 -Node: Statements/Lines105446 -Ref: Statements/Lines-Footnote-1109901 -Node: Other Features110166 -Node: When111102 -Ref: When-Footnote-1112856 -Node: Intro Summary112921 -Node: Invoking Gawk113805 -Node: Command Line115319 -Node: Options116117 -Ref: Options-Footnote-1131912 -Ref: Options-Footnote-2132141 -Node: Other Arguments132166 -Node: Naming Standard Input135114 -Node: Environment Variables136207 -Node: AWKPATH Variable136765 -Ref: AWKPATH Variable-Footnote-1140172 -Ref: AWKPATH Variable-Footnote-2140217 -Node: AWKLIBPATH Variable140477 -Node: Other Environment Variables141733 -Node: Exit Status145251 -Node: Include Files145927 -Node: Loading Shared Libraries149516 -Node: Obsolete150943 -Node: Undocumented151635 -Node: Invoking Summary151902 -Node: Regexp153565 -Node: Regexp Usage155019 -Node: Escape Sequences157056 -Node: Regexp Operators163285 -Ref: Regexp Operators-Footnote-1170695 -Ref: Regexp Operators-Footnote-2170842 -Node: Bracket Expressions170940 -Ref: table-char-classes172955 -Node: Leftmost Longest175897 -Node: Computed Regexps177199 -Node: GNU Regexp Operators180628 -Node: Case-sensitivity184300 -Ref: Case-sensitivity-Footnote-1187185 -Ref: Case-sensitivity-Footnote-2187420 -Node: Regexp Summary187528 -Node: Reading Files188995 -Node: Records191088 -Node: awk split records191821 -Node: gawk split records196750 -Ref: gawk split records-Footnote-1201289 -Node: Fields201326 -Ref: Fields-Footnote-1204104 -Node: Nonconstant Fields204190 -Ref: Nonconstant Fields-Footnote-1206428 -Node: Changing Fields206631 -Node: Field Separators212562 -Node: Default Field Splitting215266 -Node: Regexp Field Splitting216383 -Node: Single Character Fields219733 -Node: Command Line Field Separator220792 -Node: Full Line Fields224009 -Ref: Full Line Fields-Footnote-1225530 -Ref: Full Line Fields-Footnote-2225576 -Node: Field Splitting Summary225677 -Node: Constant Size227751 -Node: Splitting By Content232334 -Ref: Splitting By Content-Footnote-1236299 -Node: Multiple Line236462 -Ref: Multiple Line-Footnote-1242343 -Node: Getline242522 -Node: Plain Getline244729 -Node: Getline/Variable247369 -Node: Getline/File248518 -Node: Getline/Variable/File249903 -Ref: Getline/Variable/File-Footnote-1251506 -Node: Getline/Pipe251593 -Node: Getline/Variable/Pipe254271 -Node: Getline/Coprocess255402 -Node: Getline/Variable/Coprocess256666 -Node: Getline Notes257405 -Node: Getline Summary260199 -Ref: table-getline-variants260611 -Node: Read Timeout261440 -Ref: Read Timeout-Footnote-1265277 -Node: Command-line directories265335 -Node: Input Summary266240 -Node: Input Exercises269625 -Node: Printing270353 -Node: Print272188 -Node: Print Examples273645 -Node: Output Separators276424 -Node: OFMT278442 -Node: Printf279797 -Node: Basic Printf280582 -Node: Control Letters282154 -Node: Format Modifiers286139 -Node: Printf Examples292149 -Node: Redirection294635 -Node: Special FD301473 -Ref: Special FD-Footnote-1304639 -Node: Special Files304713 -Node: Other Inherited Files305330 -Node: Special Network306330 -Node: Special Caveats307192 -Node: Close Files And Pipes308141 -Ref: Close Files And Pipes-Footnote-1315326 -Ref: Close Files And Pipes-Footnote-2315474 -Node: Nonfatal315624 -Node: Output Summary317547 -Node: Output Exercises318768 -Node: Expressions319448 -Node: Values320637 -Node: Constants321314 -Node: Scalar Constants322005 -Ref: Scalar Constants-Footnote-1322867 -Node: Nondecimal-numbers323117 -Node: Regexp Constants326127 -Node: Using Constant Regexps326653 -Node: Variables329816 -Node: Using Variables330473 -Node: Assignment Options332384 -Node: Conversion334259 -Node: Strings And Numbers334783 -Ref: Strings And Numbers-Footnote-1337848 -Node: Locale influences conversions337957 -Ref: table-locale-affects340703 -Node: All Operators341295 -Node: Arithmetic Ops341924 -Node: Concatenation344429 -Ref: Concatenation-Footnote-1347248 -Node: Assignment Ops347355 -Ref: table-assign-ops352334 -Node: Increment Ops353644 -Node: Truth Values and Conditions357075 -Node: Truth Values358158 -Node: Typing and Comparison359207 -Node: Variable Typing360023 -Node: Comparison Operators363690 -Ref: table-relational-ops364100 -Node: POSIX String Comparison367595 -Ref: POSIX String Comparison-Footnote-1368667 -Node: Boolean Ops368806 -Ref: Boolean Ops-Footnote-1373284 -Node: Conditional Exp373375 -Node: Function Calls375113 -Node: Precedence378993 -Node: Locales382653 -Node: Expressions Summary384285 -Node: Patterns and Actions386856 -Node: Pattern Overview387976 -Node: Regexp Patterns389655 -Node: Expression Patterns390198 -Node: Ranges393907 -Node: BEGIN/END397014 -Node: Using BEGIN/END397775 -Ref: Using BEGIN/END-Footnote-1400511 -Node: I/O And BEGIN/END400617 -Node: BEGINFILE/ENDFILE402932 -Node: Empty405829 -Node: Using Shell Variables406146 -Node: Action Overview408419 -Node: Statements410745 -Node: If Statement412593 -Node: While Statement414088 -Node: Do Statement416116 -Node: For Statement417264 -Node: Switch Statement420422 -Node: Break Statement422804 -Node: Continue Statement424845 -Node: Next Statement426672 -Node: Nextfile Statement429053 -Node: Exit Statement431681 -Node: Built-in Variables434092 -Node: User-modified435225 -Ref: User-modified-Footnote-1442928 -Node: Auto-set442990 -Ref: Auto-set-Footnote-1456699 -Ref: Auto-set-Footnote-2456904 -Node: ARGC and ARGV456960 -Node: Pattern Action Summary461178 -Node: Arrays463611 -Node: Array Basics464940 -Node: Array Intro465784 -Ref: figure-array-elements467718 -Ref: Array Intro-Footnote-1470338 -Node: Reference to Elements470466 -Node: Assigning Elements472928 -Node: Array Example473419 -Node: Scanning an Array475178 -Node: Controlling Scanning478198 -Ref: Controlling Scanning-Footnote-1483592 -Node: Numeric Array Subscripts483908 -Node: Uninitialized Subscripts486093 -Node: Delete487710 -Ref: Delete-Footnote-1490459 -Node: Multidimensional490516 -Node: Multiscanning493613 -Node: Arrays of Arrays495202 -Node: Arrays Summary499956 -Node: Functions502047 -Node: Built-in503086 -Node: Calling Built-in504164 -Node: Numeric Functions506159 -Ref: Numeric Functions-Footnote-1510977 -Ref: Numeric Functions-Footnote-2511334 -Ref: Numeric Functions-Footnote-3511382 -Node: String Functions511654 -Ref: String Functions-Footnote-1535155 -Ref: String Functions-Footnote-2535284 -Ref: String Functions-Footnote-3535532 -Node: Gory Details535619 -Ref: table-sub-escapes537400 -Ref: table-sub-proposed538915 -Ref: table-posix-sub540277 -Ref: table-gensub-escapes541814 -Ref: Gory Details-Footnote-1542647 -Node: I/O Functions542798 -Ref: I/O Functions-Footnote-1550034 -Node: Time Functions550181 -Ref: Time Functions-Footnote-1560690 -Ref: Time Functions-Footnote-2560758 -Ref: Time Functions-Footnote-3560916 -Ref: Time Functions-Footnote-4561027 -Ref: Time Functions-Footnote-5561139 -Ref: Time Functions-Footnote-6561366 -Node: Bitwise Functions561632 -Ref: table-bitwise-ops562194 -Ref: Bitwise Functions-Footnote-1566522 -Node: Type Functions566694 -Node: I18N Functions567846 -Node: User-defined569493 -Node: Definition Syntax570298 -Ref: Definition Syntax-Footnote-1575957 -Node: Function Example576028 -Ref: Function Example-Footnote-1578949 -Node: Function Caveats578971 -Node: Calling A Function579489 -Node: Variable Scope580447 -Node: Pass By Value/Reference583440 -Node: Return Statement586937 -Node: Dynamic Typing589916 -Node: Indirect Calls590845 -Ref: Indirect Calls-Footnote-1602151 -Node: Functions Summary602279 -Node: Library Functions604981 -Ref: Library Functions-Footnote-1608589 -Ref: Library Functions-Footnote-2608732 -Node: Library Names608903 -Ref: Library Names-Footnote-1612361 -Ref: Library Names-Footnote-2612584 -Node: General Functions612670 -Node: Strtonum Function613773 -Node: Assert Function616795 -Node: Round Function620119 -Node: Cliff Random Function621660 -Node: Ordinal Functions622676 -Ref: Ordinal Functions-Footnote-1625739 -Ref: Ordinal Functions-Footnote-2625991 -Node: Join Function626202 -Ref: Join Function-Footnote-1627972 -Node: Getlocaltime Function628172 -Node: Readfile Function631916 -Node: Shell Quoting633888 -Node: Data File Management635289 -Node: Filetrans Function635921 -Node: Rewind Function640017 -Node: File Checking641403 -Ref: File Checking-Footnote-1642736 -Node: Empty Files642937 -Node: Ignoring Assigns644916 -Node: Getopt Function646466 -Ref: Getopt Function-Footnote-1657930 -Node: Passwd Functions658130 -Ref: Passwd Functions-Footnote-1666970 -Node: Group Functions667058 -Ref: Group Functions-Footnote-1674955 -Node: Walking Arrays675160 -Node: Library Functions Summary676760 -Node: Library Exercises678164 -Node: Sample Programs679444 -Node: Running Examples680214 -Node: Clones680942 -Node: Cut Program682166 -Node: Egrep Program691886 -Ref: Egrep Program-Footnote-1699389 -Node: Id Program699499 -Node: Split Program703175 -Ref: Split Program-Footnote-1706629 -Node: Tee Program706757 -Node: Uniq Program709546 -Node: Wc Program716965 -Ref: Wc Program-Footnote-1721215 -Node: Miscellaneous Programs721309 -Node: Dupword Program722522 -Node: Alarm Program724553 -Node: Translate Program729358 -Ref: Translate Program-Footnote-1733921 -Node: Labels Program734191 -Ref: Labels Program-Footnote-1737542 -Node: Word Sorting737626 -Node: History Sorting741696 -Node: Extract Program743531 -Node: Simple Sed751055 -Node: Igawk Program754125 -Ref: Igawk Program-Footnote-1768451 -Ref: Igawk Program-Footnote-2768652 -Ref: Igawk Program-Footnote-3768774 -Node: Anagram Program768889 -Node: Signature Program771950 -Node: Programs Summary773197 -Node: Programs Exercises774418 -Ref: Programs Exercises-Footnote-1778549 -Node: Advanced Features778640 -Node: Nondecimal Data780622 -Node: Array Sorting782212 -Node: Controlling Array Traversal782912 -Ref: Controlling Array Traversal-Footnote-1791278 -Node: Array Sorting Functions791396 -Ref: Array Sorting Functions-Footnote-1795282 -Node: Two-way I/O795478 -Ref: Two-way I/O-Footnote-1800423 -Ref: Two-way I/O-Footnote-2800609 -Node: TCP/IP Networking800691 -Node: Profiling803563 -Node: Advanced Features Summary811834 -Node: Internationalization813767 -Node: I18N and L10N815247 -Node: Explaining gettext815933 -Ref: Explaining gettext-Footnote-1820958 -Ref: Explaining gettext-Footnote-2821142 -Node: Programmer i18n821307 -Ref: Programmer i18n-Footnote-1826183 -Node: Translator i18n826232 -Node: String Extraction827026 -Ref: String Extraction-Footnote-1828157 -Node: Printf Ordering828243 -Ref: Printf Ordering-Footnote-1831029 -Node: I18N Portability831093 -Ref: I18N Portability-Footnote-1833549 -Node: I18N Example833612 -Ref: I18N Example-Footnote-1836415 -Node: Gawk I18N836487 -Node: I18N Summary837131 -Node: Debugger838471 -Node: Debugging839493 -Node: Debugging Concepts839934 -Node: Debugging Terms841744 -Node: Awk Debugging844316 -Node: Sample Debugging Session845222 -Node: Debugger Invocation845756 -Node: Finding The Bug847141 -Node: List of Debugger Commands853620 -Node: Breakpoint Control854952 -Node: Debugger Execution Control858629 -Node: Viewing And Changing Data861988 -Node: Execution Stack865364 -Node: Debugger Info866999 -Node: Miscellaneous Debugger Commands871044 -Node: Readline Support876045 -Node: Limitations876939 -Node: Debugging Summary879054 -Node: Arbitrary Precision Arithmetic880228 -Node: Computer Arithmetic881644 -Ref: table-numeric-ranges885242 -Ref: Computer Arithmetic-Footnote-1886101 -Node: Math Definitions886158 -Ref: table-ieee-formats889446 -Ref: Math Definitions-Footnote-1890050 -Node: MPFR features890155 -Node: FP Math Caution891826 -Ref: FP Math Caution-Footnote-1892876 -Node: Inexactness of computations893245 -Node: Inexact representation894204 -Node: Comparing FP Values895561 -Node: Errors accumulate896643 -Node: Getting Accuracy898076 -Node: Try To Round900738 -Node: Setting precision901637 -Ref: table-predefined-precision-strings902321 -Node: Setting the rounding mode904110 -Ref: table-gawk-rounding-modes904474 -Ref: Setting the rounding mode-Footnote-1907929 -Node: Arbitrary Precision Integers908108 -Ref: Arbitrary Precision Integers-Footnote-1913008 -Node: POSIX Floating Point Problems913157 -Ref: POSIX Floating Point Problems-Footnote-1917030 -Node: Floating point summary917068 -Node: Dynamic Extensions919262 -Node: Extension Intro920814 -Node: Plugin License922080 -Node: Extension Mechanism Outline922877 -Ref: figure-load-extension923305 -Ref: figure-register-new-function924785 -Ref: figure-call-new-function925789 -Node: Extension API Description927775 -Node: Extension API Functions Introduction929225 -Node: General Data Types934049 -Ref: General Data Types-Footnote-1939788 -Node: Memory Allocation Functions940087 -Ref: Memory Allocation Functions-Footnote-1942926 -Node: Constructor Functions943022 -Node: Registration Functions944756 -Node: Extension Functions945441 -Node: Exit Callback Functions947738 -Node: Extension Version String948986 -Node: Input Parsers949651 -Node: Output Wrappers959530 -Node: Two-way processors964045 -Node: Printing Messages966249 -Ref: Printing Messages-Footnote-1967325 -Node: Updating `ERRNO'967477 -Node: Requesting Values968217 -Ref: table-value-types-returned968945 -Node: Accessing Parameters969902 -Node: Symbol Table Access971133 -Node: Symbol table by name971647 -Node: Symbol table by cookie973628 -Ref: Symbol table by cookie-Footnote-1977772 -Node: Cached values977835 -Ref: Cached values-Footnote-1981334 -Node: Array Manipulation981425 -Ref: Array Manipulation-Footnote-1982523 -Node: Array Data Types982560 -Ref: Array Data Types-Footnote-1985215 -Node: Array Functions985307 -Node: Flattening Arrays989161 -Node: Creating Arrays996053 -Node: Extension API Variables1000824 -Node: Extension Versioning1001460 -Node: Extension API Informational Variables1003361 -Node: Extension API Boilerplate1004426 -Node: Finding Extensions1008235 -Node: Extension Example1008795 -Node: Internal File Description1009567 -Node: Internal File Ops1013634 -Ref: Internal File Ops-Footnote-11025304 -Node: Using Internal File Ops1025444 -Ref: Using Internal File Ops-Footnote-11027827 -Node: Extension Samples1028100 -Node: Extension Sample File Functions1029626 -Node: Extension Sample Fnmatch1037264 -Node: Extension Sample Fork1038755 -Node: Extension Sample Inplace1039970 -Node: Extension Sample Ord1041645 -Node: Extension Sample Readdir1042481 -Ref: table-readdir-file-types1043357 -Node: Extension Sample Revout1044168 -Node: Extension Sample Rev2way1044758 -Node: Extension Sample Read write array1045498 -Node: Extension Sample Readfile1047438 -Node: Extension Sample Time1048533 -Node: Extension Sample API Tests1049882 -Node: gawkextlib1050373 -Node: Extension summary1053031 -Node: Extension Exercises1056720 -Node: Language History1057442 -Node: V7/SVR3.11059098 -Node: SVR41061279 -Node: POSIX1062724 -Node: BTL1064113 -Node: POSIX/GNU1064847 -Node: Feature History1070728 -Node: Common Extensions1084522 -Node: Ranges and Locales1085846 -Ref: Ranges and Locales-Footnote-11090464 -Ref: Ranges and Locales-Footnote-21090491 -Ref: Ranges and Locales-Footnote-31090725 -Node: Contributors1090946 -Node: History summary1096487 -Node: Installation1097857 -Node: Gawk Distribution1098803 -Node: Getting1099287 -Node: Extracting1100110 -Node: Distribution contents1101745 -Node: Unix Installation1107810 -Node: Quick Installation1108493 -Node: Shell Startup Files1110904 -Node: Additional Configuration Options1111983 -Node: Configuration Philosophy1113722 -Node: Non-Unix Installation1116091 -Node: PC Installation1116549 -Node: PC Binary Installation1117868 -Node: PC Compiling1119716 -Ref: PC Compiling-Footnote-11122737 -Node: PC Testing1122846 -Node: PC Using1124022 -Node: Cygwin1128137 -Node: MSYS1128960 -Node: VMS Installation1129460 -Node: VMS Compilation1130252 -Ref: VMS Compilation-Footnote-11131474 -Node: VMS Dynamic Extensions1131532 -Node: VMS Installation Details1133216 -Node: VMS Running1135468 -Node: VMS GNV1138304 -Node: VMS Old Gawk1139038 -Node: Bugs1139508 -Node: Other Versions1143391 -Node: Installation summary1149815 -Node: Notes1150871 -Node: Compatibility Mode1151736 -Node: Additions1152518 -Node: Accessing The Source1153443 -Node: Adding Code1154878 -Node: New Ports1161035 -Node: Derived Files1165517 -Ref: Derived Files-Footnote-11170992 -Ref: Derived Files-Footnote-21171026 -Ref: Derived Files-Footnote-31171622 -Node: Future Extensions1171736 -Node: Implementation Limitations1172342 -Node: Extension Design1173590 -Node: Old Extension Problems1174744 -Ref: Old Extension Problems-Footnote-11176261 -Node: Extension New Mechanism Goals1176318 -Ref: Extension New Mechanism Goals-Footnote-11179678 -Node: Extension Other Design Decisions1179867 -Node: Extension Future Growth1181975 -Node: Old Extension Mechanism1182811 -Node: Notes summary1184573 -Node: Basic Concepts1185759 -Node: Basic High Level1186440 -Ref: figure-general-flow1186712 -Ref: figure-process-flow1187311 -Ref: Basic High Level-Footnote-11190540 -Node: Basic Data Typing1190725 -Node: Glossary1194053 -Node: Copying1225982 -Node: GNU Free Documentation License1263538 -Node: Index1288674 +Node: Getting Started73249 +Node: Running gawk75688 +Node: One-shot76878 +Node: Read Terminal78142 +Node: Long80173 +Node: Executable Scripts81686 +Ref: Executable Scripts-Footnote-184475 +Node: Comments84578 +Node: Quoting87060 +Node: DOS Quoting92578 +Node: Sample Data Files93253 +Node: Very Simple95848 +Node: Two Rules100747 +Node: More Complex102633 +Node: Statements/Lines105495 +Ref: Statements/Lines-Footnote-1109950 +Node: Other Features110215 +Node: When111151 +Ref: When-Footnote-1112905 +Node: Intro Summary112970 +Node: Invoking Gawk113854 +Node: Command Line115368 +Node: Options116166 +Ref: Options-Footnote-1131961 +Ref: Options-Footnote-2132190 +Node: Other Arguments132215 +Node: Naming Standard Input135163 +Node: Environment Variables136256 +Node: AWKPATH Variable136814 +Ref: AWKPATH Variable-Footnote-1140221 +Ref: AWKPATH Variable-Footnote-2140266 +Node: AWKLIBPATH Variable140526 +Node: Other Environment Variables141782 +Node: Exit Status145300 +Node: Include Files145976 +Node: Loading Shared Libraries149565 +Node: Obsolete150992 +Node: Undocumented151684 +Node: Invoking Summary151951 +Node: Regexp153614 +Node: Regexp Usage155068 +Node: Escape Sequences157105 +Node: Regexp Operators163334 +Ref: Regexp Operators-Footnote-1170744 +Ref: Regexp Operators-Footnote-2170891 +Node: Bracket Expressions170989 +Ref: table-char-classes173004 +Node: Leftmost Longest175946 +Node: Computed Regexps177248 +Node: GNU Regexp Operators180677 +Node: Case-sensitivity184349 +Ref: Case-sensitivity-Footnote-1187234 +Ref: Case-sensitivity-Footnote-2187469 +Node: Regexp Summary187577 +Node: Reading Files189044 +Node: Records191137 +Node: awk split records191870 +Node: gawk split records196799 +Ref: gawk split records-Footnote-1201338 +Node: Fields201375 +Ref: Fields-Footnote-1204153 +Node: Nonconstant Fields204239 +Ref: Nonconstant Fields-Footnote-1206477 +Node: Changing Fields206680 +Node: Field Separators212611 +Node: Default Field Splitting215315 +Node: Regexp Field Splitting216432 +Node: Single Character Fields219782 +Node: Command Line Field Separator220841 +Node: Full Line Fields224058 +Ref: Full Line Fields-Footnote-1225579 +Ref: Full Line Fields-Footnote-2225625 +Node: Field Splitting Summary225726 +Node: Constant Size227800 +Node: Splitting By Content232383 +Ref: Splitting By Content-Footnote-1236348 +Node: Multiple Line236511 +Ref: Multiple Line-Footnote-1242392 +Node: Getline242571 +Node: Plain Getline244778 +Node: Getline/Variable247418 +Node: Getline/File248567 +Node: Getline/Variable/File249952 +Ref: Getline/Variable/File-Footnote-1251555 +Node: Getline/Pipe251642 +Node: Getline/Variable/Pipe254320 +Node: Getline/Coprocess255451 +Node: Getline/Variable/Coprocess256715 +Node: Getline Notes257454 +Node: Getline Summary260248 +Ref: table-getline-variants260660 +Node: Read Timeout261489 +Ref: Read Timeout-Footnote-1265326 +Node: Command-line directories265384 +Node: Input Summary266289 +Node: Input Exercises269674 +Node: Printing270402 +Node: Print272237 +Node: Print Examples273694 +Node: Output Separators276473 +Node: OFMT278491 +Node: Printf279846 +Node: Basic Printf280631 +Node: Control Letters282203 +Node: Format Modifiers286188 +Node: Printf Examples292198 +Node: Redirection294684 +Node: Special FD301522 +Ref: Special FD-Footnote-1304688 +Node: Special Files304762 +Node: Other Inherited Files305379 +Node: Special Network306379 +Node: Special Caveats307241 +Node: Close Files And Pipes308190 +Ref: Close Files And Pipes-Footnote-1315375 +Ref: Close Files And Pipes-Footnote-2315523 +Node: Nonfatal315673 +Node: Output Summary317596 +Node: Output Exercises318817 +Node: Expressions319497 +Node: Values320686 +Node: Constants321363 +Node: Scalar Constants322054 +Ref: Scalar Constants-Footnote-1322916 +Node: Nondecimal-numbers323166 +Node: Regexp Constants326176 +Node: Using Constant Regexps326702 +Node: Variables329865 +Node: Using Variables330522 +Node: Assignment Options332433 +Node: Conversion334308 +Node: Strings And Numbers334832 +Ref: Strings And Numbers-Footnote-1337897 +Node: Locale influences conversions338006 +Ref: table-locale-affects340752 +Node: All Operators341344 +Node: Arithmetic Ops341973 +Node: Concatenation344478 +Ref: Concatenation-Footnote-1347297 +Node: Assignment Ops347404 +Ref: table-assign-ops352383 +Node: Increment Ops353693 +Node: Truth Values and Conditions357124 +Node: Truth Values358207 +Node: Typing and Comparison359256 +Node: Variable Typing360072 +Node: Comparison Operators363739 +Ref: table-relational-ops364149 +Node: POSIX String Comparison367644 +Ref: POSIX String Comparison-Footnote-1368716 +Node: Boolean Ops368855 +Ref: Boolean Ops-Footnote-1373333 +Node: Conditional Exp373424 +Node: Function Calls375162 +Node: Precedence379042 +Node: Locales382702 +Node: Expressions Summary384334 +Node: Patterns and Actions386905 +Node: Pattern Overview388025 +Node: Regexp Patterns389704 +Node: Expression Patterns390247 +Node: Ranges394027 +Node: BEGIN/END397134 +Node: Using BEGIN/END397895 +Ref: Using BEGIN/END-Footnote-1400631 +Node: I/O And BEGIN/END400737 +Node: BEGINFILE/ENDFILE403052 +Node: Empty405949 +Node: Using Shell Variables406266 +Node: Action Overview408539 +Node: Statements410865 +Node: If Statement412713 +Node: While Statement414208 +Node: Do Statement416236 +Node: For Statement417384 +Node: Switch Statement420542 +Node: Break Statement422924 +Node: Continue Statement424965 +Node: Next Statement426792 +Node: Nextfile Statement429173 +Node: Exit Statement431801 +Node: Built-in Variables434212 +Node: User-modified435345 +Ref: User-modified-Footnote-1443048 +Node: Auto-set443110 +Ref: Auto-set-Footnote-1456819 +Ref: Auto-set-Footnote-2457024 +Node: ARGC and ARGV457080 +Node: Pattern Action Summary461298 +Node: Arrays463731 +Node: Array Basics465060 +Node: Array Intro465904 +Ref: figure-array-elements467838 +Ref: Array Intro-Footnote-1470458 +Node: Reference to Elements470586 +Node: Assigning Elements473048 +Node: Array Example473539 +Node: Scanning an Array475298 +Node: Controlling Scanning478318 +Ref: Controlling Scanning-Footnote-1483712 +Node: Numeric Array Subscripts484028 +Node: Uninitialized Subscripts486213 +Node: Delete487830 +Ref: Delete-Footnote-1490579 +Node: Multidimensional490636 +Node: Multiscanning493733 +Node: Arrays of Arrays495322 +Node: Arrays Summary500076 +Node: Functions502167 +Node: Built-in503206 +Node: Calling Built-in504284 +Node: Numeric Functions506279 +Ref: Numeric Functions-Footnote-1511097 +Ref: Numeric Functions-Footnote-2511454 +Ref: Numeric Functions-Footnote-3511502 +Node: String Functions511774 +Ref: String Functions-Footnote-1535275 +Ref: String Functions-Footnote-2535404 +Ref: String Functions-Footnote-3535652 +Node: Gory Details535739 +Ref: table-sub-escapes537520 +Ref: table-sub-proposed539035 +Ref: table-posix-sub540397 +Ref: table-gensub-escapes541934 +Ref: Gory Details-Footnote-1542767 +Node: I/O Functions542918 +Ref: I/O Functions-Footnote-1550154 +Node: Time Functions550301 +Ref: Time Functions-Footnote-1560810 +Ref: Time Functions-Footnote-2560878 +Ref: Time Functions-Footnote-3561036 +Ref: Time Functions-Footnote-4561147 +Ref: Time Functions-Footnote-5561259 +Ref: Time Functions-Footnote-6561486 +Node: Bitwise Functions561752 +Ref: table-bitwise-ops562314 +Ref: Bitwise Functions-Footnote-1566642 +Node: Type Functions566814 +Node: I18N Functions567966 +Node: User-defined569613 +Node: Definition Syntax570418 +Ref: Definition Syntax-Footnote-1576077 +Node: Function Example576148 +Ref: Function Example-Footnote-1579069 +Node: Function Caveats579091 +Node: Calling A Function579609 +Node: Variable Scope580567 +Node: Pass By Value/Reference583560 +Node: Return Statement587057 +Node: Dynamic Typing590036 +Node: Indirect Calls590965 +Ref: Indirect Calls-Footnote-1602271 +Node: Functions Summary602399 +Node: Library Functions605101 +Ref: Library Functions-Footnote-1608709 +Ref: Library Functions-Footnote-2608852 +Node: Library Names609023 +Ref: Library Names-Footnote-1612481 +Ref: Library Names-Footnote-2612704 +Node: General Functions612790 +Node: Strtonum Function613893 +Node: Assert Function616915 +Node: Round Function620239 +Node: Cliff Random Function621780 +Node: Ordinal Functions622796 +Ref: Ordinal Functions-Footnote-1625859 +Ref: Ordinal Functions-Footnote-2626111 +Node: Join Function626322 +Ref: Join Function-Footnote-1628092 +Node: Getlocaltime Function628292 +Node: Readfile Function632036 +Node: Shell Quoting634008 +Node: Data File Management635409 +Node: Filetrans Function636041 +Node: Rewind Function640137 +Node: File Checking641523 +Ref: File Checking-Footnote-1642856 +Node: Empty Files643057 +Node: Ignoring Assigns645036 +Node: Getopt Function646586 +Ref: Getopt Function-Footnote-1658050 +Node: Passwd Functions658250 +Ref: Passwd Functions-Footnote-1667090 +Node: Group Functions667178 +Ref: Group Functions-Footnote-1675075 +Node: Walking Arrays675280 +Node: Library Functions Summary676880 +Node: Library Exercises678284 +Node: Sample Programs679564 +Node: Running Examples680334 +Node: Clones681062 +Node: Cut Program682286 +Node: Egrep Program692006 +Ref: Egrep Program-Footnote-1699509 +Node: Id Program699619 +Node: Split Program703295 +Ref: Split Program-Footnote-1706749 +Node: Tee Program706877 +Node: Uniq Program709666 +Node: Wc Program717085 +Ref: Wc Program-Footnote-1721335 +Node: Miscellaneous Programs721429 +Node: Dupword Program722642 +Node: Alarm Program724673 +Node: Translate Program729478 +Ref: Translate Program-Footnote-1734041 +Node: Labels Program734311 +Ref: Labels Program-Footnote-1737662 +Node: Word Sorting737746 +Node: History Sorting741816 +Node: Extract Program743651 +Node: Simple Sed751175 +Node: Igawk Program754245 +Ref: Igawk Program-Footnote-1768571 +Ref: Igawk Program-Footnote-2768772 +Ref: Igawk Program-Footnote-3768894 +Node: Anagram Program769009 +Node: Signature Program772070 +Node: Programs Summary773317 +Node: Programs Exercises774538 +Ref: Programs Exercises-Footnote-1778669 +Node: Advanced Features778760 +Node: Nondecimal Data780742 +Node: Array Sorting782332 +Node: Controlling Array Traversal783032 +Ref: Controlling Array Traversal-Footnote-1791398 +Node: Array Sorting Functions791516 +Ref: Array Sorting Functions-Footnote-1795402 +Node: Two-way I/O795598 +Ref: Two-way I/O-Footnote-1800543 +Ref: Two-way I/O-Footnote-2800729 +Node: TCP/IP Networking800811 +Node: Profiling803683 +Node: Advanced Features Summary811954 +Node: Internationalization813887 +Node: I18N and L10N815367 +Node: Explaining gettext816053 +Ref: Explaining gettext-Footnote-1821078 +Ref: Explaining gettext-Footnote-2821262 +Node: Programmer i18n821427 +Ref: Programmer i18n-Footnote-1826303 +Node: Translator i18n826352 +Node: String Extraction827146 +Ref: String Extraction-Footnote-1828277 +Node: Printf Ordering828363 +Ref: Printf Ordering-Footnote-1831149 +Node: I18N Portability831213 +Ref: I18N Portability-Footnote-1833669 +Node: I18N Example833732 +Ref: I18N Example-Footnote-1836535 +Node: Gawk I18N836607 +Node: I18N Summary837251 +Node: Debugger838591 +Node: Debugging839613 +Node: Debugging Concepts840054 +Node: Debugging Terms841864 +Node: Awk Debugging844436 +Node: Sample Debugging Session845342 +Node: Debugger Invocation845876 +Node: Finding The Bug847261 +Node: List of Debugger Commands853740 +Node: Breakpoint Control855072 +Node: Debugger Execution Control858749 +Node: Viewing And Changing Data862108 +Node: Execution Stack865484 +Node: Debugger Info867119 +Node: Miscellaneous Debugger Commands871164 +Node: Readline Support876165 +Node: Limitations877059 +Node: Debugging Summary879174 +Node: Arbitrary Precision Arithmetic880348 +Node: Computer Arithmetic881764 +Ref: table-numeric-ranges885363 +Ref: Computer Arithmetic-Footnote-1885887 +Node: Math Definitions885944 +Ref: table-ieee-formats889239 +Ref: Math Definitions-Footnote-1889843 +Node: MPFR features889948 +Node: FP Math Caution891619 +Ref: FP Math Caution-Footnote-1892669 +Node: Inexactness of computations893038 +Node: Inexact representation893997 +Node: Comparing FP Values895355 +Node: Errors accumulate896437 +Node: Getting Accuracy897869 +Node: Try To Round900573 +Node: Setting precision901472 +Ref: table-predefined-precision-strings902156 +Node: Setting the rounding mode903985 +Ref: table-gawk-rounding-modes904349 +Ref: Setting the rounding mode-Footnote-1907801 +Node: Arbitrary Precision Integers907980 +Ref: Arbitrary Precision Integers-Footnote-1912878 +Node: POSIX Floating Point Problems913027 +Ref: POSIX Floating Point Problems-Footnote-1916906 +Node: Floating point summary916944 +Node: Dynamic Extensions919140 +Node: Extension Intro920692 +Node: Plugin License921957 +Node: Extension Mechanism Outline922754 +Ref: figure-load-extension923182 +Ref: figure-register-new-function924662 +Ref: figure-call-new-function925666 +Node: Extension API Description927653 +Node: Extension API Functions Introduction929103 +Node: General Data Types933924 +Ref: General Data Types-Footnote-1939824 +Node: Memory Allocation Functions940123 +Ref: Memory Allocation Functions-Footnote-1942962 +Node: Constructor Functions943061 +Node: Registration Functions944796 +Node: Extension Functions945481 +Node: Exit Callback Functions947778 +Node: Extension Version String949026 +Node: Input Parsers949689 +Node: Output Wrappers959564 +Node: Two-way processors964077 +Node: Printing Messages966340 +Ref: Printing Messages-Footnote-1967416 +Node: Updating `ERRNO'967568 +Node: Requesting Values968308 +Ref: table-value-types-returned969035 +Node: Accessing Parameters969992 +Node: Symbol Table Access971226 +Node: Symbol table by name971740 +Node: Symbol table by cookie973760 +Ref: Symbol table by cookie-Footnote-1977905 +Node: Cached values977968 +Ref: Cached values-Footnote-1981464 +Node: Array Manipulation981555 +Ref: Array Manipulation-Footnote-1982653 +Node: Array Data Types982690 +Ref: Array Data Types-Footnote-1985345 +Node: Array Functions985437 +Node: Flattening Arrays989296 +Node: Creating Arrays996198 +Node: Extension API Variables1000969 +Node: Extension Versioning1001605 +Node: Extension API Informational Variables1003496 +Node: Extension API Boilerplate1004561 +Node: Finding Extensions1008370 +Node: Extension Example1008930 +Node: Internal File Description1009702 +Node: Internal File Ops1013769 +Ref: Internal File Ops-Footnote-11025520 +Node: Using Internal File Ops1025660 +Ref: Using Internal File Ops-Footnote-11028043 +Node: Extension Samples1028316 +Node: Extension Sample File Functions1029844 +Node: Extension Sample Fnmatch1037525 +Node: Extension Sample Fork1039013 +Node: Extension Sample Inplace1040228 +Node: Extension Sample Ord1041904 +Node: Extension Sample Readdir1042740 +Ref: table-readdir-file-types1043617 +Node: Extension Sample Revout1044428 +Node: Extension Sample Rev2way1045017 +Node: Extension Sample Read write array1045757 +Node: Extension Sample Readfile1047697 +Node: Extension Sample Time1048792 +Node: Extension Sample API Tests1050140 +Node: gawkextlib1050631 +Node: Extension summary1053309 +Node: Extension Exercises1056998 +Node: Language History1057720 +Node: V7/SVR3.11059376 +Node: SVR41061557 +Node: POSIX1063002 +Node: BTL1064391 +Node: POSIX/GNU1065125 +Node: Feature History1071006 +Node: Common Extensions1084800 +Node: Ranges and Locales1086124 +Ref: Ranges and Locales-Footnote-11090742 +Ref: Ranges and Locales-Footnote-21090769 +Ref: Ranges and Locales-Footnote-31091003 +Node: Contributors1091224 +Node: History summary1096765 +Node: Installation1098135 +Node: Gawk Distribution1099081 +Node: Getting1099565 +Node: Extracting1100388 +Node: Distribution contents1102023 +Node: Unix Installation1108088 +Node: Quick Installation1108771 +Node: Shell Startup Files1111182 +Node: Additional Configuration Options1112261 +Node: Configuration Philosophy1114000 +Node: Non-Unix Installation1116369 +Node: PC Installation1116827 +Node: PC Binary Installation1118146 +Node: PC Compiling1119994 +Ref: PC Compiling-Footnote-11123015 +Node: PC Testing1123124 +Node: PC Using1124300 +Node: Cygwin1128415 +Node: MSYS1129238 +Node: VMS Installation1129738 +Node: VMS Compilation1130530 +Ref: VMS Compilation-Footnote-11131752 +Node: VMS Dynamic Extensions1131810 +Node: VMS Installation Details1133494 +Node: VMS Running1135746 +Node: VMS GNV1138582 +Node: VMS Old Gawk1139316 +Node: Bugs1139786 +Node: Other Versions1143669 +Node: Installation summary1150093 +Node: Notes1151149 +Node: Compatibility Mode1152014 +Node: Additions1152796 +Node: Accessing The Source1153721 +Node: Adding Code1155156 +Node: New Ports1161313 +Node: Derived Files1165795 +Ref: Derived Files-Footnote-11171270 +Ref: Derived Files-Footnote-21171304 +Ref: Derived Files-Footnote-31171900 +Node: Future Extensions1172014 +Node: Implementation Limitations1172620 +Node: Extension Design1173868 +Node: Old Extension Problems1175022 +Ref: Old Extension Problems-Footnote-11176539 +Node: Extension New Mechanism Goals1176596 +Ref: Extension New Mechanism Goals-Footnote-11179956 +Node: Extension Other Design Decisions1180145 +Node: Extension Future Growth1182253 +Node: Old Extension Mechanism1183089 +Node: Notes summary1184851 +Node: Basic Concepts1186037 +Node: Basic High Level1186718 +Ref: figure-general-flow1186990 +Ref: figure-process-flow1187589 +Ref: Basic High Level-Footnote-11190818 +Node: Basic Data Typing1191003 +Node: Glossary1194331 +Node: Copying1226260 +Node: GNU Free Documentation License1263816 +Node: Index1288952 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 1a239124..0fd9ac04 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -1302,7 +1302,7 @@ October 2014 <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> <affiliation><jobtitle>Israel</jobtitle></affiliation> </author> - <date>December 2014</date> + <date>February 2015</date> </prefaceinfo> @end docbook @@ -2286,14 +2286,14 @@ which they raised and educated me. Finally, I also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities. -@iftex +@ifnotdocbook @sp 2 @noindent Arnold Robbins @* Nof Ayalon @* Israel @* -December 2014 -@end iftex +February 2015 +@end ifnotdocbook @ifnotinfo @part @value{PART1}The @command{awk} Language @@ -13232,6 +13232,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as +A regexp constant as a pattern is also a special case of an expression pattern. The expression @code{/li/} has the value one if @samp{li} appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @@ -30246,7 +30247,7 @@ paper and pencil (and/or a calculator). In theory, numbers can have an arbitrary number of digits on either side (or both sides) of the decimal point, and the results of a computation are always exact. -Some modern system can do decimal arithmetic in hardware, but usually you +Some modern systems can do decimal arithmetic in hardware, but usually you need a special software library to provide access to these instructions. There are also libraries that do decimal arithmetic entirely in software. @@ -30302,8 +30303,34 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615 -@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} -@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} +@iftex +@item Single-precision floating point (approximate) @tab @math{1.175494^{-38}} @tab @math{3.402823^{38}} +@item Double-precision floating point (approximate) @tab @math{2.225074^{-308}} @tab @math{1.797693^{308}} +@end iftex +@ifnottex +@ifnotdocbook +@item Single-precision floating point (approximate) @tab 1.175494e-38 @tab 3.402823e38 +@item Double-precision floating point (approximate) @tab 2.225074e-308 @tab 1.797693e308 +@end ifnotdocbook +@end ifnottex +@ifdocbook +@item Single-precision floating point (approximate) @tab +@docbook +1.175494<superscript>-38</superscript> +@end docbook +@tab +@docbook +3.402823<superscript>38</superscript> +@end docbook +@item Double-precision floating point (approximate) @tab +@docbook +2.225074<superscript>-308</superscript> +@end docbook +@tab +@docbook +1.797693<superscript>308</superscript> +@end docbook +@end ifdocbook @end multitable @end float @@ -30312,7 +30339,7 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. The rest of this @value{CHAPTER} uses a number of terms. Here are some informal definitions that should help you work your way through the material -here. +here: @table @dfn @item Accuracy @@ -30333,7 +30360,7 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.''@footnote{Thanks to Michael Brennan for this description, +``Not a number.''@footnote{Thanks to Michael Brennan for this description, which we have paraphrased, and for the examples.} A special value that results from attempting a calculation that has no answer as a real number. In such a case, programs can either receive a floating-point exception, @@ -30376,8 +30403,8 @@ formula: @end display @noindent -Here, @var{prec} denotes the binary precision -(measured in bits) and @var{dps} (short for decimal places) +Here, @emph{prec} denotes the binary precision +(measured in bits) and @emph{dps} (short for decimal places) is the decimal digits. @item Rounding mode @@ -30385,7 +30412,7 @@ How numbers are rounded up or down when necessary. More details are provided later. @item Significand -A floating-point value consists the significand multiplied by 10 +A floating-point value consists of the significand multiplied by 10 to the power of the exponent. For example, in @code{1.2345e67}, the significand is @code{1.2345}. @@ -30409,7 +30436,7 @@ to allow greater precisions and larger exponent ranges. (@command{awk} uses only the 64-bit double-precision format.) @ref{table-ieee-formats} lists the precision and exponent -field values for the basic IEEE 754 binary formats: +field values for the basic IEEE 754 binary formats. @float Table,table-ieee-formats @caption{Basic IEEE format values} @@ -30473,12 +30500,12 @@ for more information. @author Teen Talk Barbie, July 1992 @end quotation -This @value{SECTION} provides a high level overview of the issues +This @value{SECTION} provides a high-level overview of the issues involved when doing lots of floating-point arithmetic.@footnote{There is a very nice @uref{http://www.validlab.com/goldberg/paper.pdf, paper on floating-point arithmetic} by David Goldberg, ``What Every -Computer Scientist Should Know About Floating-point Arithmetic,'' -@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), 5-48. This is +Computer Scientist Should Know About Floating-Point Arithmetic,'' +@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03): 5-48. This is worth reading if you are interested in the details, but it does require a background in computer science.} The discussion applies to both hardware and arbitrary-precision @@ -30547,7 +30574,7 @@ $ @kbd{gawk 'BEGIN @{ x = 0.875; y = 0.425} Often the error is so small you do not even notice it, and if you do, you can always specify how much precision you would like in your output. -Usually this is a format string like @code{"%.15g"}, which when +Usually this is a format string like @code{"%.15g"}, which, when used in the previous example, produces an output identical to the input. @node Comparing FP Values @@ -30586,7 +30613,7 @@ else The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating-point operations, +value that is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of @value{PI} using one of its many series representations: @@ -30639,7 +30666,7 @@ no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may be important -for your computation. Rounding error, cumulative precision loss +for your computation. Rounding error, cumulative precision loss, and underflow are often troublesome. When @command{gawk} tests the expressions @samp{0.1 + 12.2} and @@ -30679,7 +30706,8 @@ by our earlier attempt to compute the value of @value{PI}. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. -Repeated addition is not necessarily equivalent to multiplication +Additionally, you should understand that +repeated addition is not necessarily equivalent to multiplication in floating-point arithmetic. In the example in @ref{Errors accumulate}: @@ -30742,7 +30770,7 @@ to emulate an IEEE 754 binary format. @float Table,table-predefined-precision-strings @caption{Predefined precision strings for @code{PREC}} @multitable {@code{"double"}} {12345678901234567890123456789012345} -@headitem @code{PREC} @tab IEEE 754 Binary Format +@headitem @code{PREC} @tab IEEE 754 binary format @item @code{"half"} @tab 16-bit half-precision @item @code{"single"} @tab Basic 32-bit single precision @item @code{"double"} @tab Basic 64-bit double precision @@ -30774,7 +30802,6 @@ than the default and cannot use a command-line assignment to @code{PREC}, you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a floating-point constant: -@end quotation @example $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'} @@ -30786,22 +30813,23 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'} $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'} @print{} 0.1000000000000000000000000 @end example +@end quotation @node Setting the rounding mode @subsection Setting the Rounding Mode The @code{ROUNDMODE} variable provides -program level control over the rounding mode. +program-level control over the rounding mode. The correspondence between @code{ROUNDMODE} and the IEEE rounding modes is shown in @ref{table-gawk-rounding-modes}. @float Table,table-gawk-rounding-modes @caption{@command{gawk} rounding modes} @multitable @columnfractions .45 .30 .25 -@headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE} +@headitem Rounding mode @tab IEEE name @tab @code{ROUNDMODE} @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"} -@item Round toward plus Infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} -@item Round toward negative Infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} +@item Round toward positive infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} +@item Round toward negative infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} @item Round toward zero @tab @code{roundTowardZero} @tab @code{"Z"} or @code{"z"} @item Round to nearest, ties away from zero @tab @code{roundTiesToAway} @tab @code{"A"} or @code{"a"} @end multitable @@ -30862,8 +30890,8 @@ distributes upward and downward rounds of exact halves, which might cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. -The other rounding modes are rarely used. Round toward positive infinity -(@code{roundTowardPositive}) and round toward negative infinity +The other rounding modes are rarely used. Rounding toward positive infinity +(@code{roundTowardPositive}) and toward negative infinity (@code{roundTowardNegative}) are often used to implement interval arithmetic, where you adjust the rounding mode to calculate upper and lower bounds for the range of output. The @code{roundTowardZero} mode can @@ -30920,17 +30948,17 @@ If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for correct output (using the formula @iftex -@math{prec = 3.322 @cdot dps}), +@math{prec = 3.322 @cdot dps}) would be @math{3.322 @cdot 183231}, @end iftex @ifnottex @ifnotdocbook -@samp{prec = 3.322 * dps}), +@samp{prec = 3.322 * dps}) would be 3.322 x 183231, @end ifnotdocbook @end ifnottex @docbook -<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>), +<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>) would be <emphasis>prec</emphasis> = 3.322 ⋅ 183231, @c @end docbook @@ -30968,7 +30996,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or -want, you can employ a subterfuge, and convert the integer to floating +want, you can employ a subterfuge and convert the integer to floating point first, like this: @example @@ -31105,7 +31133,7 @@ word sizes. See @node POSIX Floating Point Problems @section Standards Versus Existing Practice -Historically, @command{awk} has converted any non-numeric looking string +Historically, @command{awk} has converted any nonnumeric-looking string to the numeric value zero, when required. Furthermore, the original definition of the language and the original POSIX standards specified that @command{awk} only understands decimal numbers (base 10), and not octal @@ -31122,8 +31150,8 @@ notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not} source code constants.) @item -Support for the special IEEE 754 floating-point values ``Not A Number'' -(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf''). +Support for the special IEEE 754 floating-point values ``not a number'' +(NaN), positive infinity (``inf''), and negative infinity (``@minus{}inf''). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}. @@ -31144,21 +31172,21 @@ values is also a very severe departure from historical practice. @end itemize The second problem is that the @command{gawk} maintainer feels that this -interpretation of the standard, which requires a certain amount of +interpretation of the standard, which required a certain amount of ``language lawyering'' to arrive at in the first place, was not even -intended by the standard developers. In other words, ``we see how you +intended by the standard developers. In other words, ``We see how you got where you are, but we don't think that that's where you want to be.'' Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that @command{awk} support hexadecimal floating-point values and -special values for ``Not A Number'' and infinity. +special values for ``not a number'' and infinity. Although the @command{gawk} maintainer continues to feel that providing those features is inadvisable, nevertheless, on systems that support IEEE floating point, it seems -reasonable to provide @emph{some} way to support NaN and Infinity values. +reasonable to provide @emph{some} way to support NaN and infinity values. The solution implemented in @command{gawk} is as follows: @itemize @value{BULLET} @@ -31178,7 +31206,7 @@ $ @kbd{echo 0xDeadBeef | gawk --posix '@{ print $1 + 0 @}'} @end example @item -Without @option{--posix}, @command{gawk} interprets the four strings +Without @option{--posix}, @command{gawk} interprets the four string values @samp{+inf}, @samp{-inf}, @samp{+nan}, @@ -31200,7 +31228,7 @@ $ @kbd{echo 0xDeadBeef | gawk '@{ print $1 + 0 @}'} @end example @command{gawk} ignores case in the four special values. -Thus @samp{+nan} and @samp{+NaN} are the same. +Thus, @samp{+nan} and @samp{+NaN} are the same. @end itemize @node Floating point summary @@ -31213,9 +31241,9 @@ values. Standard @command{awk} uses double-precision floating-point values. @item -In the early 1990s, Barbie mistakenly said ``Math class is tough!'' +In the early 1990s Barbie mistakenly said, ``Math class is tough!'' Although math isn't tough, floating-point arithmetic isn't the same -as pencil and paper math, and care must be taken: +as pencil-and-paper math, and care must be taken: @c nested list @itemize @value{MINUS} @@ -31248,7 +31276,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and @item With @option{-M}, @command{gawk} performs arbitrary-precision integer arithmetic using the GMP library. -This is faster and more space efficient than using MPFR for +This is faster and more space-efficient than using MPFR for the same calculations. @item @@ -31260,7 +31288,7 @@ It pays to be aware of them. Overall, there is no need to be unduly suspicious about the results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and -paper. In order to take advantage of the power of computer floating point, +paper. In order to take advantage of the power of floating-point arithmetic, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the correct number @@ -31321,7 +31349,7 @@ Extensions are useful because they allow you (of course) to extend @command{gawk}'s functionality. For example, they can provide access to system calls (such as @code{chdir()} to change directory) and to other C library routines that could be of use. As with most software, -``the sky is the limit;'' if you can imagine something that you might +``the sky is the limit''; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the @dfn{application programming @@ -31329,7 +31357,7 @@ interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents -the sample extensions included in the @command{gawk} distribution, +the sample extensions included in the @command{gawk} distribution and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @xref{Extension Design}, for a discussion of the extension mechanism @@ -31482,7 +31510,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command-line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling}, and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -31526,7 +31554,7 @@ This (rather large) @value{SECTION} describes the API in detail. @node Extension API Functions Introduction @subsection Introduction -Access to facilities within @command{gawk} are made available +Access to facilities within @command{gawk} is achieved by calling through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -31554,7 +31582,7 @@ Output wrappers Two-way processors @end itemize -All of these are discussed in detail, later in this @value{CHAPTER}. +All of these are discussed in detail later in this @value{CHAPTER}. @item Printing fatal, warning, and ``lint'' warning messages. @@ -31592,7 +31620,7 @@ Creating a new array Clearing an array @item -Flattening an array for easy C style looping over all its indices and elements +Flattening an array for easy C-style looping over all its indices and elements @end itemize @end itemize @@ -31604,8 +31632,9 @@ The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: +@c FIXME: Make this is a float at some point. @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}} -@headitem C Entity @tab Header File +@headitem C entity @tab Header file @item @code{EOF} @tab @code{<stdio.h>} @item Values for @code{errno} @tab @code{<errno.h>} @item @code{FILE} @tab @code{<stdio.h>} @@ -31631,7 +31660,7 @@ Doing so, however, is poor coding practice. Although the API only uses ISO C 90 features, there is an exception; the ``constructor'' functions use the @code{inline} keyword. If your compiler does not support this keyword, you should either place -@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a +@samp{-Dinline=''} on your command line or use the GNU Autotools and include a @file{config.h} file in your extensions. @item @@ -31639,7 +31668,7 @@ All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} from the extension @emph{must} come from calling one of -@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -31653,7 +31682,7 @@ characters are allowed. By intent, strings are maintained using the current multibyte encoding (as defined by @env{LC_@var{xxx}} environment variables) and not using wide characters. This matches how @command{gawk} stores strings internally -and also how characters are likely to be input and output from files. +and also how characters are likely to be input into and output from files. @end quotation @item @@ -31698,6 +31727,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent @value{SECTION}s, together with the functions that use them. +The general-purpose types and structures are as follows: + @table @code @item typedef void *awk_ext_id_t; A value of this type is received from @command{gawk} when an extension is loaded. @@ -31714,7 +31745,7 @@ while allowing @command{gawk} to use them as it needs to. @itemx @ @ @ @ awk_false = 0, @itemx @ @ @ @ awk_true @itemx @} awk_bool_t; -A simple boolean type. +A simple Boolean type. @item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @@ -31760,7 +31791,7 @@ The @code{val_type} member indicates what kind of value the @itemx #define array_cookie@ @ @ u.a @itemx #define scalar_cookie@ @ u.scl @itemx #define value_cookie@ @ @ u.vc -These macros make accessing the fields of the @code{awk_value_t} more +Using these macros makes accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; @@ -31783,7 +31814,7 @@ indicates what is in the @code{union}. Representing numbers is easy---the API uses a C @code{double}. Strings require more work. Because @command{gawk} allows embedded @sc{nul} bytes in string values, a string must be represented as a pair containing a -data-pointer and length. This is the @code{awk_string_t} type. +data pointer and length. This is the @code{awk_string_t} type. Identifiers (i.e., the names of global variables) can be associated with either scalar values or with arrays. In addition, @command{gawk} @@ -31796,12 +31827,12 @@ of the @code{union} as if they were fields in a @code{struct}; this is a common coding practice in C. Such code is easier to write and to read, but it remains @emph{your} responsibility to make sure that the @code{val_type} member correctly reflects the type of the value in -the @code{awk_value_t}. +the @code{awk_value_t} struct. Conceptually, the first three members of the @code{union} (number, string, and array) are all that is needed for working with @command{awk} values. However, because the API provides routines for accessing and changing -the value of global scalar variables only by using the variable's name, +the value of a global scalar variable only by using the variable's name, there is a performance penalty: @command{gawk} must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -31819,7 +31850,9 @@ See also the entry for ``Cookie'' in the @ref{Glossary}. object for that variable, and then use the cookie for getting the variable's value or for changing the variable's value. -This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro. +The @code{awk_scalar_t} type holds a scalar cookie, and the +@code{scalar_cookie} macro provides access to the value of that type +in the @code{awk_value_t} struct. Given a scalar cookie, @command{gawk} can directly retrieve or modify the value, as required, without having to find it first. @@ -31828,8 +31861,8 @@ If you know that you wish to use the same numeric or string @emph{value} for one or more variables, you can create the value once, retaining a @dfn{value cookie} for it, and then pass in that value cookie whenever you wish to set the value of a -variable. This saves both storage space within the running @command{gawk} -process as well as the time needed to create the value. +variable. This saves storage space within the running @command{gawk} +process and reduces the time needed to create the value. @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @@ -31857,13 +31890,13 @@ be passed to @command{gawk}. @item void gawk_free(void *ptr); Call the correct version of @code{free()} to release storage that was -allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. +allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. @end table The API has to provide these functions because it is possible for an extension to be compiled and linked against a different version of the C library than was used for the @command{gawk} -executable.@footnote{This is more common on MS-Windows systems, but +executable.@footnote{This is more common on MS-Windows systems, but it can happen on Unix-like systems as well.} If @command{gawk} were to use its version of @code{free()} when the memory came from an unrelated version of @code{malloc()}, unexpected behavior would @@ -31873,7 +31906,7 @@ Two convenience macros may be used for allocating storage from @code{gawk_malloc()} and @code{gawk_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were -procedure calls that do not return a value. +procedure calls that do not return a value: @table @code @item #define emalloc(pointer, type, size, message) @dots{} @@ -31910,7 +31943,7 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +This is like @code{emalloc()}, but it calls @code{gawk_realloc()} instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -31935,7 +31968,7 @@ for storage in @code{result}. It returns @code{result}. @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) This function creates a string value in the @code{awk_value_t} variable pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -31986,7 +32019,7 @@ The fields are: @table @code @item const char *name; The name of the new function. -@command{awk} level code calls the function by this name. +@command{awk}-level code calls the function by this name. This is a regular C string. Function names must obey the rules for @command{awk} @@ -32000,7 +32033,7 @@ This is a pointer to the C function that provides the extension's functionality. The function must fill in @code{*result} with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from one of +As mentioned earlier, string memory @emph{must} come from one of @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many @@ -32052,20 +32085,20 @@ The @code{exit_status} parameter is the exit status value that @command{gawk} intends to pass to the @code{exit()} system call. @item arg0 -A pointer to private data which @command{gawk} saves in order to pass to +A pointer to private data that @command{gawk} saves in order to pass to the function pointed to by @code{funcp}. @end table @end table -Exit callback functions are called in last-in-first-out (LIFO) +Exit callback functions are called in last-in, first-out (LIFO) order---that is, in the reverse order in which they are registered with @command{gawk}. @node Extension Version String @subsubsection Registering An Extension Version String -You can register a version string which indicates the name and -version of your extension, with @command{gawk}, as follows: +You can register a version string that indicates the name and +version of your extension with @command{gawk}, as follows: @table @code @item void register_ext_version(const char *version); @@ -32087,7 +32120,7 @@ of @code{RS} to find the end of the record, and then uses @code{FS} Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}). If you want, you can provide your own custom input parser. An input -parser's job is to return a record to the @command{gawk} record processing +parser's job is to return a record to the @command{gawk} record-processing code, along with indicators for the value and length of the data to be used for @code{RT}, if any. @@ -32105,9 +32138,9 @@ It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf); When @command{gawk} decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill -in certain fields in the @code{awk_input_buf_t} structure, and ensure +in certain fields in the @code{awk_input_buf_t} structure and ensure that certain conditions are true. It should then return true. If an -error of some kind occurs, it should not fill in any fields, and should +error of some kind occurs, it should not fill in any fields and should return false; then @command{gawk} will not use the input parser. The details are presented shortly. @end table @@ -32200,7 +32233,7 @@ in the @code{struct stat}, or any combination of these factors. Once @code{@var{XXX}_can_take_file()} has returned true, and @command{gawk} has decided to use your input parser, it calls -@code{@var{XXX}_take_control_of()}. That function then fills one of +@code{@var{XXX}_take_control_of()}. That function then fills either the @code{get_record} field or the @code{read_func} field in the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not} set to @code{INVALID_HANDLE}. The following list describes the fields that @@ -32222,21 +32255,21 @@ records. Said function is the core of the input parser. Its behavior is described in the text following this list. @item ssize_t (*read_func)(); -This function pointer should point to function that has the +This function pointer should point to a function that has the same behavior as the standard POSIX @code{read()} system call. It is an alternative to the @code{get_record} pointer. Its behavior is also described in the text following this list. @item void (*close_func)(struct awk_input *iobuf); This function pointer should point to a function that does -the ``tear down.'' It should release any resources allocated by +the ``teardown.'' It should release any resources allocated by @code{@var{XXX}_take_control_of()}. It may also close the file. If it does so, it should set the @code{fd} field to @code{INVALID_HANDLE}. If @code{fd} is still not @code{INVALID_HANDLE} after the call to this function, @command{gawk} calls the regular @code{close()} system call. -Having a ``tear down'' function is optional. If your input parser does +Having a ``teardown'' function is optional. If your input parser does not need it, do not set this field. Then, @command{gawk} calls the regular @code{close()} system call on the file descriptor, so it should be valid. @@ -32247,7 +32280,7 @@ input records. The parameters are as follows: @table @code @item char **out -This is a pointer to a @code{char *} variable which is set to point +This is a pointer to a @code{char *} variable that is set to point to the record. @command{gawk} makes its own copy of the data, so the extension must manage this storage. @@ -32300,17 +32333,17 @@ set this field explicitly. You must choose one method or the other: either a function that returns a record, or one that returns raw data. In particular, if you supply a function to get a record, @command{gawk} will -call it, and never call the raw read function. +call it, and will never call the raw read function. @end quotation @command{gawk} ships with a sample extension that reads directories, -returning records for each entry in the directory (@pxref{Extension +returning records for each entry in a directory (@pxref{Extension Sample Readdir}). You may wish to use that code as a guide for writing your own input parser. When writing an input parser, you should think about (and document) how it is expected to interact with @command{awk} code. You may want -it to always be called, and take effect as appropriate (as the +it to always be called, and to take effect as appropriate (as the @code{readdir} extension does). Or you may want it to take effect based upon the value of an @command{awk} variable, as the XML extension from the @code{gawkextlib} project does (@pxref{gawkextlib}). @@ -32420,7 +32453,7 @@ a pointer to any private data associated with the file. These pointers should be set to point to functions that perform the equivalent function as the @code{<stdio.h>} functions do, if appropriate. @command{gawk} uses these function pointers for all output. -@command{gawk} initializes the pointers to point to internal, ``pass through'' +@command{gawk} initializes the pointers to point to internal ``pass-through'' functions that just call the regular @code{<stdio.h>} functions, so an extension only needs to redefine those functions that are appropriate for what it does. @@ -32431,7 +32464,7 @@ upon the @code{name} and @code{mode} fields, and any additional state (such as @command{awk} variable values) that is appropriate. When @command{gawk} calls @code{@var{XXX}_take_control_of()}, that function should fill -in the other fields, as appropriate, except for @code{fp}, which it should just +in the other fields as appropriate, except for @code{fp}, which it should just use normally. You register your output wrapper with the following function: @@ -32471,14 +32504,14 @@ The fields are as follows: The name of the two-way processor. @item awk_bool_t (*can_take_two_way)(const char *name); -This function returns true if it wants to take over two-way I/O for this @value{FN}. +The function pointed to by this field should return true if it wants to take over two-way I/O for this @value{FN}. It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t (*take_control_of)(const char *name, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_input_buf_t *inbuf, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_output_buf_t *outbuf); -This function should fill in the @code{awk_input_buf_t} and +The function pointed to by this field should fill in the @code{awk_input_buf_t} and @code{awk_outut_buf_t} structures pointed to by @code{inbuf} and @code{outbuf}, respectively. These structures were described earlier. @@ -32507,7 +32540,7 @@ Register the two-way processor pointed to by @code{two_way_processor} with You can print different kinds of warning messages from your extension, as described here. Note that for these functions, -you must pass in the extension id received from @command{gawk} +you must pass in the extension ID received from @command{gawk} when the extension was loaded:@footnote{Because the API uses only ISO C 90 features, it cannot make use of the ISO C 99 variadic macro feature to hide that parameter. More's the pity.} @@ -32560,7 +32593,7 @@ matches what you requested, the function returns true and fills in the @code{awk_value_t} result. Otherwise, the function returns false, and the @code{val_type} member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual +print an error message or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. @@ -32593,32 +32626,32 @@ value type, as appropriate. This behavior is summarized in <entry><para><emphasis role="bold">String</emphasis></para></entry> <entry><para>String</para></entry> <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> <entry><para><emphasis role="bold">Number</emphasis></para></entry> <entry><para>Number if can be converted, else false</para></entry> <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Type</emphasis></para></entry> <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> <entry><para>Array</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Requested</emphasis></para></entry> <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> <entry><para>Scalar</para></entry> <entry><para>Scalar</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> @@ -32630,11 +32663,11 @@ value type, as appropriate. This behavior is summarized in </row> <row> <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> + <entry><para><emphasis role="bold">Value cookie</emphasis></para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para> + </entry><entry><para>False</para></entry> </row> </tbody> </tgroup> @@ -32652,12 +32685,12 @@ value type, as appropriate. This behavior is summarized in @end tex @multitable @columnfractions .166 .166 .198 .15 .15 .166 @headitem @tab @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{String} @tab String @tab String @tab false @tab false -@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false -@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @tab @b{String} @tab String @tab String @tab False @tab False +@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab False @tab False +@item @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab False +@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab False @tab False @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false +@item @tab @b{Value cookie} @tab False @tab False @tab False @tab False @end multitable @end ifnotdocbook @end ifnotplaintext @@ -32668,21 +32701,21 @@ value type, as appropriate. This behavior is summarized in +------------+------------+-----------+-----------+ | String | Number | Array | Undefined | +-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | +| | String | String | String | False | False | | |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | +| | Number | Number if | Number | False | False | | | | can be | | | | | | | converted, | | | | | | | else false | | | | | |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | +| Type | Array | False | False | Array | False | | Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | +| | Scalar | Scalar | Scalar | False | False | | |-----------+------------+------------+-----------+-----------+ | | Undefined | String | Number | Array | Undefined | | |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | +| | Value | False | False | False | False | +| | cookie | | | | | +-----------+-----------+------------+------------+-----------+-----------+ @end example @end ifplaintext @@ -32699,16 +32732,16 @@ passed to your extension function. They are: @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Fill in the @code{awk_value_t} structure pointed to by @code{result} -with the @code{count}'th argument. Return true if the actual -type matches @code{wanted}, false otherwise. In the latter +with the @code{count}th argument. Return true if the actual +type matches @code{wanted}, and false otherwise. In the latter case, @code{result@w{->}val_type} indicates the actual type -(@pxref{table-value-types-returned}). Counts are zero based---the first +(@pxref{table-value-types-returned}). Counts are zero-based---the first argument is numbered zero, the second one, and so on. @code{wanted} indicates the type of value expected. @item awk_bool_t set_argument(size_t count, awk_array_t array); Convert a parameter that was undefined into an array; this provides -call-by-reference for arrays. Return false if @code{count} is too big, +call by reference for arrays. Return false if @code{count} is too big, or if the argument's type is not undefined. @DBXREF{Array Manipulation} for more information on creating arrays. @end table @@ -32732,8 +32765,9 @@ allows you to create and release cached values. The following routines provide the ability to access and update global @command{awk}-level variables by name. In compiler terminology, identifiers of different kinds are termed @dfn{symbols}, thus the ``sym'' -in the routines' names. The data structure which stores information +in the routines' names. The data structure that stores information about symbols is termed a @dfn{symbol table}. +The functions are as follows: @table @code @item awk_bool_t sym_lookup(const char *name, @@ -32742,14 +32776,14 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise. +Return true if the actual type matches @code{wanted}, and false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @item awk_bool_t sym_update(const char *name, awk_value_t *value); Update the variable named by the string @code{name}, which is a regular C string. The variable is added to @command{gawk}'s symbol table -if it is not there. Return true if everything worked, false otherwise. +if it is not there. Return true if everything worked, and false otherwise. Changing types (scalar to array or vice versa) of an existing variable is @emph{not} allowed, nor may this routine be used to update an array. @@ -32774,7 +32808,7 @@ populate it. A @dfn{scalar cookie} is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in @command{gawk}'s symbol table every time -access is needed. This was discussed earlier in @ref{General Data Types}. +access is needed. This was discussed earlier, in @ref{General Data Types}. The following functions let you work with scalar cookies: @@ -32890,7 +32924,7 @@ and carefully check the return values from the API functions. @subsubsection Creating and Using Cached Values The routines in this section allow you to create and release -cached values. As with scalar cookies, in theory, cached values +cached values. Like scalar cookies, in theory, cached values are not necessary. You can create numbers and strings using the functions in @ref{Constructor Functions}. You can then assign those values to variables using @code{sym_update()} @@ -32968,7 +33002,7 @@ Using value cookies in this way saves considerable storage, as all of @code{VAR1} through @code{VAR100} share the same value. You might be wondering, ``Is this sharing problematic? -What happens if @command{awk} code assigns a new value to @code{VAR1}, +What happens if @command{awk} code assigns a new value to @code{VAR1}; are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. @@ -33072,7 +33106,7 @@ modify them. @node Array Functions @subsubsection Array Functions -The following functions relate to individual array elements. +The following functions relate to individual array elements: @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); @@ -33091,13 +33125,13 @@ Return false if @code{wanted} does not match the actual type or if @code{index} is not in the array (@pxref{table-value-types-returned}). The value for @code{index} can be numeric, in which case @command{gawk} -converts it to a string. Using non-integral values is possible, but +converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to strings -(@pxref{Conversion}); thus using integral values is safest. +(@pxref{Conversion}); thus, using integral values is safest. As with @emph{all} strings passed into @command{gawk} from an extension, the string value of @code{index} must come from @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}, and +@code{gawk_calloc()}, or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -33153,7 +33187,7 @@ flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data); When done with a flattened array, release the storage using this function. -You must pass in both the original array cookie, and the address of +You must pass in both the original array cookie and the address of the created @code{awk_flat_array_t} structure. The function returns true upon success, false otherwise. @end table @@ -33163,7 +33197,7 @@ The function returns true upon success, false otherwise. To @dfn{flatten} an array is to create a structure that represents the full array in a fashion that makes it easy -for C code to traverse the entire array. Test code +for C code to traverse the entire array. Some of the code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. @@ -33220,9 +33254,9 @@ dump_array_and_delete(int nargs, awk_value_t *result) @end example The function then proceeds in steps, as follows. First, retrieve -the name of the array, passed as the first argument. Then -retrieve the array itself. If either operation fails, print -error messages and return: +the name of the array, passed as the first argument, followed by +the array itself. If either operation fails, print an +error message and return: @example /* get argument named array as flat array and print it */ @@ -33258,7 +33292,7 @@ and print it: @end example The third step is to actually flatten the array, and then -to double check that the count in the @code{awk_flat_array_t} +to double-check that the count in the @code{awk_flat_array_t} is the same as the count just retrieved: @example @@ -33279,7 +33313,7 @@ is the same as the count just retrieved: The fourth step is to retrieve the index of the element to be deleted, which was passed as the second argument. Remember that argument counts passed to @code{get_argument()} -are zero-based, thus the second argument is numbered one: +are zero-based, and thus the second argument is numbered one: @example if (! get_argument(1, AWK_STRING, & value3)) @{ @@ -33294,7 +33328,7 @@ element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the @code{AWK_ELEMENT_DELETE} bit in the @code{flags} field of the element. When the array is released, @command{gawk} -traverses the flattened array, and deletes any elements which +traverses the flattened array, and deletes any elements that have this flag bit set: @example @@ -33582,10 +33616,10 @@ The API versions are available at compile time as constants: @table @code @item GAWK_API_MAJOR_VERSION -The major version of the API. +The major version of the API @item GAWK_API_MINOR_VERSION -The minor version of the API. +The minor version of the API @end table The minor version increases when new functions are added to the API. Such @@ -33603,14 +33637,14 @@ constant integers: @table @code @item api->major_version -The major version of the running @command{gawk}. +The major version of the running @command{gawk} @item api->minor_version -The minor version of the running @command{gawk}. +The minor version of the running @command{gawk} @end table It is up to the extension to decide if there are API incompatibilities. -Typically a check like this is enough: +Typically, a check like this is enough: @example if (api->major_version != GAWK_API_MAJOR_VERSION @@ -33624,7 +33658,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION @end example Such code is included in the boilerplate @code{dl_load_func()} macro -provided in @file{gawkapi.h} (discussed later, in +provided in @file{gawkapi.h} (discussed in @ref{Extension API Boilerplate}). @node Extension API Informational Variables @@ -33671,7 +33705,7 @@ as described here. The boilerplate needed is also provided in comments in the @file{gawkapi.h} header file: @example -/* Boiler plate code: */ +/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -33730,7 +33764,7 @@ to @code{NULL}, or to point to a string giving the name and version of your extension. @item static awk_ext_func_t func_table[] = @{ @dots{} @}; -This is an array of one or more @code{awk_ext_func_t} structures +This is an array of one or more @code{awk_ext_func_t} structures, as described earlier (@pxref{Extension Functions}). It can then be looped over for multiple calls to @code{add_ext_func()}. @@ -33861,7 +33895,7 @@ the @code{stat()} fails. It fills in the following elements: @table @code @item "name" -The name of the file that was @code{stat()}'ed. +The name of the file that was @code{stat()}ed. @item "dev" @itemx "ino" @@ -33917,7 +33951,7 @@ interprocess communications). The file is a directory. @item "fifo" -The file is a named-pipe (also known as a FIFO). +The file is a named pipe (also known as a FIFO). @item "file" The file is just a regular file. @@ -33940,7 +33974,7 @@ For some other systems, @dfn{a priori} knowledge is used to provide a value. Where no value can be determined, it defaults to 512. @end table -Several additional elements may be present depending upon the operating +Several additional elements may be present, depending upon the operating system and the type of the file. You can test for them in your @command{awk} program by using the @code{in} operator (@pxref{Reference to Elements}): @@ -33970,7 +34004,7 @@ edited slightly for presentation. See @file{extension/filefuncs.c} in the @command{gawk} distribution for the complete version.} The file includes a number of standard header files, and then includes -the @file{gawkapi.h} header file which provides the API definitions. +the @file{gawkapi.h} header file, which provides the API definitions. Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code (@pxref{Extension API Boilerplate}): @@ -34011,9 +34045,9 @@ int plugin_is_GPL_compatible; @cindex programming conventions, @command{gawk} extensions By convention, for an @command{awk} function @code{foo()}, the C function that implements it is called @code{do_foo()}. The function should have -two arguments: the first is an @code{int} usually called @code{nargs}, +two arguments. The first is an @code{int}, usually called @code{nargs}, that represents the number of actual arguments for the function. -The second is a pointer to an @code{awk_value_t}, usually named +The second is a pointer to an @code{awk_value_t} structure, usually named @code{result}: @example @@ -34059,7 +34093,7 @@ Finally, the function returns the return value to the @command{awk} level: The @code{stat()} extension is more involved. First comes a function that turns a numeric mode into a printable representation -(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity: +(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for brevity: @example /* format_mode --- turn a stat mode field into something readable */ @@ -34115,9 +34149,9 @@ array_set_numeric(awk_array_t array, const char *sub, double num) The following function does most of the work to fill in the @code{awk_array_t} result array with values obtained -from a valid @code{struct stat}. It is done in a separate function +from a valid @code{struct stat}. This work is done in a separate function to support the @code{stat()} function for @command{gawk} and also -to support the @code{fts()} extension which is included in +to support the @code{fts()} extension, which is included in the same file but whose code is not shown here (@pxref{Extension Sample File Functions}). @@ -34238,8 +34272,8 @@ the @code{stat()} system call instead of the @code{lstat()} system call. This is done by using a function pointer: @code{statfunc}. @code{statfunc} is initialized to point to @code{lstat()} (instead of @code{stat()}) to get the file information, in case the file is a -symbolic link. However, if there were three arguments, @code{statfunc} -is set point to @code{stat()}, instead. +symbolic link. However, if the third argument is included, @code{statfunc} +is set to point to @code{stat()}, instead. Here is the @code{do_stat()} function, which starts with variable declarations and argument checking: @@ -34295,7 +34329,7 @@ Next, it gets the information for the file. If the called function /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) @{ update_ERRNO_int(errno); @@ -34317,7 +34351,9 @@ Finally, it's necessary to provide the ``glue'' that loads the new function(s) into @command{gawk}. The @code{filefuncs} extension also provides an @code{fts()} -function, which we omit here. For its sake there is an initialization +function, which we omit here +(@pxref{Extension Sample File Functions}). +For its sake, there is an initialization function: @example @@ -34442,9 +34478,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @section The Sample Extensions in the @command{gawk} Distribution @cindex extensions distributed with @command{gawk} -This @value{SECTION} provides brief overviews of the sample extensions +This @value{SECTION} provides a brief overview of the sample extensions that come in the @command{gawk} distribution. Some of them are intended -for production use (e.g., the @code{filefuncs}, @code{readdir} and +for production use (e.g., the @code{filefuncs}, @code{readdir}, and @code{inplace} extensions). Others mainly provide example code that shows how to use the extension API. @@ -34480,14 +34516,14 @@ This is how you load the extension. @item @code{result = chdir("/some/directory")} The @code{chdir()} function is a direct hook to the @code{chdir()} system call to change the current directory. It returns zero -upon success or less than zero upon error. In the latter case, it updates -@code{ERRNO}. +upon success or a value less than zero upon error. +In the latter case, it updates @code{ERRNO}. @cindex @code{stat()} extension function @item @code{result = stat("/some/path", statdata} [@code{, follow}]@code{)} The @code{stat()} function provides a hook into the @code{stat()} system call. -It returns zero upon success or less than zero upon error. +It returns zero upon success or a value less than zero upon error. In the latter case, it updates @code{ERRNO}. By default, it uses the @code{lstat()} system call. However, if passed @@ -34514,10 +34550,10 @@ array with information retrieved from the filesystem, as follows: @item @code{"major"} @tab @code{st_major} @tab Device files @item @code{"minor"} @tab @code{st_minor} @tab Device files @item @code{"blksize"} @tab @code{st_blksize} @tab All -@item @code{"pmode"} @tab A human-readable version of the mode value, such as printed by -@command{ls}. For example, @code{"-rwxr-xr-x"} @tab All +@item @code{"pmode"} @tab A human-readable version of the mode value, like that printed by +@command{ls} (for example, @code{"-rwxr-xr-x"}) @tab All @item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links -@item @code{"type"} @tab The type of the file as a string. One of +@item @code{"type"} @tab The type of the file as a string---one of @code{"file"}, @code{"blockdev"}, @code{"chardev"}, @@ -34527,15 +34563,15 @@ array with information retrieved from the filesystem, as follows: @code{"symlink"}, @code{"door"}, or -@code{"unknown"}. -Not all systems support all file types. @tab All +@code{"unknown"} +(not all systems support all file types) @tab All @end multitable @cindex @code{fts()} extension function @item @code{flags = or(FTS_PHYSICAL, ...)} @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the -@code{filedata} array as described next. @code{flags} is the bitwise +@code{filedata} array, as described next. @code{flags} is the bitwise OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -34591,7 +34627,8 @@ During a traversal, do not cross onto a different mounted filesystem. @end table @item filedata -The @code{filedata} array is first cleared. Then, @code{fts()} creates +The @code{filedata} array holds the results. +@code{fts()} first clears it. Then it creates an element in @code{filedata} for every element in @code{pathlist}. The index is the name of the directory or file given in @code{pathlist}. The element for this index is itself an array. There are two cases: @@ -34633,7 +34670,7 @@ for a file: @code{"path"}, @code{"stat"}, and @code{"error"}. @end table The @code{fts()} function returns zero if there were no errors. -Otherwise it returns @minus{}1. +Otherwise, it returns @minus{}1. @quotation NOTE The @code{fts()} extension does not exactly mimic the @@ -34675,14 +34712,14 @@ The arguments to @code{fnmatch()} are: @table @code @item pattern -The @value{FN} wildcard to match. +The @value{FN} wildcard to match @item string -The @value{FN} string. +The @value{FN} string @item flag Either zero, or the bitwise OR of one or more of the -flags in the @code{FNM} array. +flags in the @code{FNM} array @end table The flags are as follows: @@ -34719,14 +34756,14 @@ This is how you load the extension. @cindex @code{fork()} extension function @item pid = fork() This function creates a new process. The return value is zero in the -child and the process-ID number of the child in the parent, or @minus{}1 +child and the process ID number of the child in the parent, or @minus{}1 upon error. In the latter case, @code{ERRNO} indicates the problem. In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are updated to reflect the correct values. @cindex @code{waitpid()} extension function @item ret = waitpid(pid) -This function takes a numeric argument, which is the process-ID to +This function takes a numeric argument, which is the process ID to wait for. The return value is that of the @code{waitpid()} system call. @@ -34754,8 +34791,8 @@ else @subsection Enabling In-Place File Editing @cindex @code{inplace} extension -The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option -which performs ``in place'' editing of each input file. +The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option, +which performs ``in-place'' editing of each input file. It uses the bundled @file{inplace.awk} include file to invoke the extension properly: @@ -34851,14 +34888,14 @@ they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode number and the @value{FN}, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +has a third field (also separated by a slash), which is a single letter indicating the type of the file. The letters and their corresponding file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types @caption{File types returned by the @code{readdir} extension} @multitable @columnfractions .1 .9 -@headitem Letter @tab File Type +@headitem Letter @tab File type @item @code{b} @tab Block device @item @code{c} @tab Character device @item @code{d} @tab Directory @@ -34886,7 +34923,7 @@ Here is an example: @@load "readdir" @dots{} BEGIN @{ FS = "/" @} -@{ print "file name is", $2 @} +@{ print "@value{FN} is", $2 @} @end example @node Extension Sample Revout @@ -34907,8 +34944,7 @@ BEGIN @{ @} @end example -The output from this program is: -@samp{cinap t'nod}. +The output from this program is @samp{cinap t'nod}. @node Extension Sample Rev2way @subsection Two-Way I/O Example @@ -34963,7 +34999,7 @@ success, or zero upon failure. @code{reada()} is the inverse of @code{writea()}; it reads the file named as its first argument, filling in the array named as the second argument. It clears the array first. -Here too, the return value is one on success and zero upon failure. +Here too, the return value is one on success, or zero upon failure. @end table The array created by @code{reada()} is identical to that written by @@ -35051,7 +35087,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}. Attempt to sleep for @var{seconds} seconds. If @var{seconds} is negative, or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}. Otherwise, return zero after sleeping for the indicated amount of time. -Note that @var{seconds} may be a floating-point (non-integral) value. +Note that @var{seconds} may be a floating-point (nonintegral) value. Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table @@ -35078,10 +35114,13 @@ project provides a number of @command{gawk} extensions, including one for processing XML files. This is the evolution of the original @command{xgawk} (XML @command{gawk}) project. -As of this writing, there are six extensions: +As of this writing, there are seven extensions: @itemize @value{BULLET} @item +@code{errno} extension + +@item GD graphics library extension @item @@ -35092,7 +35131,7 @@ PostgreSQL extension @item MPFR library extension -(this provides access to a number of MPFR functions which @command{gawk}'s +(this provides access to a number of MPFR functions that @command{gawk}'s native MPFR support does not) @item @@ -35146,7 +35185,7 @@ make install @ii{Install the extensions} If you have installed @command{gawk} in the standard way, then you will likely not need the @option{--with-gawk} option when configuring -@code{gawkextlib}. You may also need to use the @command{sudo} utility +@code{gawkextlib}. You may need to use the @command{sudo} utility to install both @command{gawk} and @code{gawkextlib}, depending upon how your system works. @@ -35171,7 +35210,7 @@ named @code{plugin_is_GPL_compatible}. @item Communication between @command{gawk} and an extension is two-way. -@command{gawk} passes a @code{struct} to the extension which contains +@command{gawk} passes a @code{struct} to the extension that contains various data fields and function pointers. The extension can then call into @command{gawk} via the supplied function pointers to accomplish certain tasks. @@ -35184,7 +35223,7 @@ By convention, implementation functions are named @code{do_@var{XXXX}()} for some @command{awk}-level function @code{@var{XXXX}()}. @item -The API is defined in a header file named @file{gawkpi.h}. You must include +The API is defined in a header file named @file{gawkapi.h}. You must include a number of standard header files @emph{before} including it in your source file. @item @@ -35229,7 +35268,7 @@ getting the count of elements in an array; creating a new array; clearing an array; and -flattening an array for easy C style looping over all its indices and elements) +flattening an array for easy C-style looping over all its indices and elements) @end itemize @item @@ -35237,7 +35276,7 @@ The API defines a number of standard data types for representing @command{awk} values, array elements, and arrays. @item -The API provide convenience functions for constructing values. +The API provides convenience functions for constructing values. It also provides memory management functions to ensure compatibility between memory allocated by @command{gawk} and memory allocated by an extension. @@ -35263,8 +35302,8 @@ file make this easier to do. @item The @command{gawk} distribution includes a number of small but useful -sample extensions. The @code{gawkextlib} project includes several more, -larger, extensions. If you wish to write an extension and contribute it +sample extensions. The @code{gawkextlib} project includes several more +(larger) extensions. If you wish to write an extension and contribute it to the community of @command{gawk} users, the @code{gawkextlib} project is the place to do so. diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 1e833fe2..c466abff 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -1297,7 +1297,7 @@ October 2014 <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> <affiliation><jobtitle>Israel</jobtitle></affiliation> </author> - <date>December 2014</date> + <date>February 2015</date> </prefaceinfo> @end docbook @@ -2253,14 +2253,14 @@ which they raised and educated me. Finally, I also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities. -@iftex +@ifnotdocbook @sp 2 @noindent Arnold Robbins @* Nof Ayalon @* Israel @* -December 2014 -@end iftex +February 2015 +@end ifnotdocbook @ifnotinfo @part @value{PART1}The @command{awk} Language @@ -12560,6 +12560,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as +A regexp constant as a pattern is also a special case of an expression pattern. The expression @code{/li/} has the value one if @samp{li} appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @@ -29337,7 +29338,7 @@ paper and pencil (and/or a calculator). In theory, numbers can have an arbitrary number of digits on either side (or both sides) of the decimal point, and the results of a computation are always exact. -Some modern system can do decimal arithmetic in hardware, but usually you +Some modern systems can do decimal arithmetic in hardware, but usually you need a special software library to provide access to these instructions. There are also libraries that do decimal arithmetic entirely in software. @@ -29393,8 +29394,34 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615 -@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} -@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} +@iftex +@item Single-precision floating point (approximate) @tab @math{1.175494^{-38}} @tab @math{3.402823^{38}} +@item Double-precision floating point (approximate) @tab @math{2.225074^{-308}} @tab @math{1.797693^{308}} +@end iftex +@ifnottex +@ifnotdocbook +@item Single-precision floating point (approximate) @tab 1.175494e-38 @tab 3.402823e38 +@item Double-precision floating point (approximate) @tab 2.225074e-308 @tab 1.797693e308 +@end ifnotdocbook +@end ifnottex +@ifdocbook +@item Single-precision floating point (approximate) @tab +@docbook +1.175494<superscript>-38</superscript> +@end docbook +@tab +@docbook +3.402823<superscript>38</superscript> +@end docbook +@item Double-precision floating point (approximate) @tab +@docbook +2.225074<superscript>-308</superscript> +@end docbook +@tab +@docbook +1.797693<superscript>308</superscript> +@end docbook +@end ifdocbook @end multitable @end float @@ -29403,7 +29430,7 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. The rest of this @value{CHAPTER} uses a number of terms. Here are some informal definitions that should help you work your way through the material -here. +here: @table @dfn @item Accuracy @@ -29424,7 +29451,7 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.''@footnote{Thanks to Michael Brennan for this description, +``Not a number.''@footnote{Thanks to Michael Brennan for this description, which we have paraphrased, and for the examples.} A special value that results from attempting a calculation that has no answer as a real number. In such a case, programs can either receive a floating-point exception, @@ -29467,8 +29494,8 @@ formula: @end display @noindent -Here, @var{prec} denotes the binary precision -(measured in bits) and @var{dps} (short for decimal places) +Here, @emph{prec} denotes the binary precision +(measured in bits) and @emph{dps} (short for decimal places) is the decimal digits. @item Rounding mode @@ -29476,7 +29503,7 @@ How numbers are rounded up or down when necessary. More details are provided later. @item Significand -A floating-point value consists the significand multiplied by 10 +A floating-point value consists of the significand multiplied by 10 to the power of the exponent. For example, in @code{1.2345e67}, the significand is @code{1.2345}. @@ -29500,7 +29527,7 @@ to allow greater precisions and larger exponent ranges. (@command{awk} uses only the 64-bit double-precision format.) @ref{table-ieee-formats} lists the precision and exponent -field values for the basic IEEE 754 binary formats: +field values for the basic IEEE 754 binary formats. @float Table,table-ieee-formats @caption{Basic IEEE format values} @@ -29564,12 +29591,12 @@ for more information. @author Teen Talk Barbie, July 1992 @end quotation -This @value{SECTION} provides a high level overview of the issues +This @value{SECTION} provides a high-level overview of the issues involved when doing lots of floating-point arithmetic.@footnote{There is a very nice @uref{http://www.validlab.com/goldberg/paper.pdf, paper on floating-point arithmetic} by David Goldberg, ``What Every -Computer Scientist Should Know About Floating-point Arithmetic,'' -@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), 5-48. This is +Computer Scientist Should Know About Floating-Point Arithmetic,'' +@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03): 5-48. This is worth reading if you are interested in the details, but it does require a background in computer science.} The discussion applies to both hardware and arbitrary-precision @@ -29638,7 +29665,7 @@ $ @kbd{gawk 'BEGIN @{ x = 0.875; y = 0.425} Often the error is so small you do not even notice it, and if you do, you can always specify how much precision you would like in your output. -Usually this is a format string like @code{"%.15g"}, which when +Usually this is a format string like @code{"%.15g"}, which, when used in the previous example, produces an output identical to the input. @node Comparing FP Values @@ -29677,7 +29704,7 @@ else The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating-point operations, +value that is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of @value{PI} using one of its many series representations: @@ -29730,7 +29757,7 @@ no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may be important -for your computation. Rounding error, cumulative precision loss +for your computation. Rounding error, cumulative precision loss, and underflow are often troublesome. When @command{gawk} tests the expressions @samp{0.1 + 12.2} and @@ -29770,7 +29797,8 @@ by our earlier attempt to compute the value of @value{PI}. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. -Repeated addition is not necessarily equivalent to multiplication +Additionally, you should understand that +repeated addition is not necessarily equivalent to multiplication in floating-point arithmetic. In the example in @ref{Errors accumulate}: @@ -29833,7 +29861,7 @@ to emulate an IEEE 754 binary format. @float Table,table-predefined-precision-strings @caption{Predefined precision strings for @code{PREC}} @multitable {@code{"double"}} {12345678901234567890123456789012345} -@headitem @code{PREC} @tab IEEE 754 Binary Format +@headitem @code{PREC} @tab IEEE 754 binary format @item @code{"half"} @tab 16-bit half-precision @item @code{"single"} @tab Basic 32-bit single precision @item @code{"double"} @tab Basic 64-bit double precision @@ -29865,7 +29893,6 @@ than the default and cannot use a command-line assignment to @code{PREC}, you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a floating-point constant: -@end quotation @example $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'} @@ -29877,22 +29904,23 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'} $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'} @print{} 0.1000000000000000000000000 @end example +@end quotation @node Setting the rounding mode @subsection Setting the Rounding Mode The @code{ROUNDMODE} variable provides -program level control over the rounding mode. +program-level control over the rounding mode. The correspondence between @code{ROUNDMODE} and the IEEE rounding modes is shown in @ref{table-gawk-rounding-modes}. @float Table,table-gawk-rounding-modes @caption{@command{gawk} rounding modes} @multitable @columnfractions .45 .30 .25 -@headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE} +@headitem Rounding mode @tab IEEE name @tab @code{ROUNDMODE} @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"} -@item Round toward plus Infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} -@item Round toward negative Infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} +@item Round toward positive infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"} +@item Round toward negative infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"} @item Round toward zero @tab @code{roundTowardZero} @tab @code{"Z"} or @code{"z"} @item Round to nearest, ties away from zero @tab @code{roundTiesToAway} @tab @code{"A"} or @code{"a"} @end multitable @@ -29953,8 +29981,8 @@ distributes upward and downward rounds of exact halves, which might cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. -The other rounding modes are rarely used. Round toward positive infinity -(@code{roundTowardPositive}) and round toward negative infinity +The other rounding modes are rarely used. Rounding toward positive infinity +(@code{roundTowardPositive}) and toward negative infinity (@code{roundTowardNegative}) are often used to implement interval arithmetic, where you adjust the rounding mode to calculate upper and lower bounds for the range of output. The @code{roundTowardZero} mode can @@ -30011,17 +30039,17 @@ If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for correct output (using the formula @iftex -@math{prec = 3.322 @cdot dps}), +@math{prec = 3.322 @cdot dps}) would be @math{3.322 @cdot 183231}, @end iftex @ifnottex @ifnotdocbook -@samp{prec = 3.322 * dps}), +@samp{prec = 3.322 * dps}) would be 3.322 x 183231, @end ifnotdocbook @end ifnottex @docbook -<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>), +<emphasis>prec</emphasis> = 3.322 ⋅ <emphasis>dps</emphasis>) would be <emphasis>prec</emphasis> = 3.322 ⋅ 183231, @c @end docbook @@ -30059,7 +30087,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or -want, you can employ a subterfuge, and convert the integer to floating +want, you can employ a subterfuge and convert the integer to floating point first, like this: @example @@ -30196,7 +30224,7 @@ word sizes. See @node POSIX Floating Point Problems @section Standards Versus Existing Practice -Historically, @command{awk} has converted any non-numeric looking string +Historically, @command{awk} has converted any nonnumeric-looking string to the numeric value zero, when required. Furthermore, the original definition of the language and the original POSIX standards specified that @command{awk} only understands decimal numbers (base 10), and not octal @@ -30213,8 +30241,8 @@ notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not} source code constants.) @item -Support for the special IEEE 754 floating-point values ``Not A Number'' -(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf''). +Support for the special IEEE 754 floating-point values ``not a number'' +(NaN), positive infinity (``inf''), and negative infinity (``@minus{}inf''). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}. @@ -30235,21 +30263,21 @@ values is also a very severe departure from historical practice. @end itemize The second problem is that the @command{gawk} maintainer feels that this -interpretation of the standard, which requires a certain amount of +interpretation of the standard, which required a certain amount of ``language lawyering'' to arrive at in the first place, was not even -intended by the standard developers. In other words, ``we see how you +intended by the standard developers. In other words, ``We see how you got where you are, but we don't think that that's where you want to be.'' Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that @command{awk} support hexadecimal floating-point values and -special values for ``Not A Number'' and infinity. +special values for ``not a number'' and infinity. Although the @command{gawk} maintainer continues to feel that providing those features is inadvisable, nevertheless, on systems that support IEEE floating point, it seems -reasonable to provide @emph{some} way to support NaN and Infinity values. +reasonable to provide @emph{some} way to support NaN and infinity values. The solution implemented in @command{gawk} is as follows: @itemize @value{BULLET} @@ -30269,7 +30297,7 @@ $ @kbd{echo 0xDeadBeef | gawk --posix '@{ print $1 + 0 @}'} @end example @item -Without @option{--posix}, @command{gawk} interprets the four strings +Without @option{--posix}, @command{gawk} interprets the four string values @samp{+inf}, @samp{-inf}, @samp{+nan}, @@ -30291,7 +30319,7 @@ $ @kbd{echo 0xDeadBeef | gawk '@{ print $1 + 0 @}'} @end example @command{gawk} ignores case in the four special values. -Thus @samp{+nan} and @samp{+NaN} are the same. +Thus, @samp{+nan} and @samp{+NaN} are the same. @end itemize @node Floating point summary @@ -30304,9 +30332,9 @@ values. Standard @command{awk} uses double-precision floating-point values. @item -In the early 1990s, Barbie mistakenly said ``Math class is tough!'' +In the early 1990s Barbie mistakenly said, ``Math class is tough!'' Although math isn't tough, floating-point arithmetic isn't the same -as pencil and paper math, and care must be taken: +as pencil-and-paper math, and care must be taken: @c nested list @itemize @value{MINUS} @@ -30339,7 +30367,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and @item With @option{-M}, @command{gawk} performs arbitrary-precision integer arithmetic using the GMP library. -This is faster and more space efficient than using MPFR for +This is faster and more space-efficient than using MPFR for the same calculations. @item @@ -30351,7 +30379,7 @@ It pays to be aware of them. Overall, there is no need to be unduly suspicious about the results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and -paper. In order to take advantage of the power of computer floating point, +paper. In order to take advantage of the power of floating-point arithmetic, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the correct number @@ -30412,7 +30440,7 @@ Extensions are useful because they allow you (of course) to extend @command{gawk}'s functionality. For example, they can provide access to system calls (such as @code{chdir()} to change directory) and to other C library routines that could be of use. As with most software, -``the sky is the limit;'' if you can imagine something that you might +``the sky is the limit''; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the @dfn{application programming @@ -30420,7 +30448,7 @@ interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents -the sample extensions included in the @command{gawk} distribution, +the sample extensions included in the @command{gawk} distribution and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @xref{Extension Design}, for a discussion of the extension mechanism @@ -30573,7 +30601,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command-line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling}, and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -30617,7 +30645,7 @@ This (rather large) @value{SECTION} describes the API in detail. @node Extension API Functions Introduction @subsection Introduction -Access to facilities within @command{gawk} are made available +Access to facilities within @command{gawk} is achieved by calling through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -30645,7 +30673,7 @@ Output wrappers Two-way processors @end itemize -All of these are discussed in detail, later in this @value{CHAPTER}. +All of these are discussed in detail later in this @value{CHAPTER}. @item Printing fatal, warning, and ``lint'' warning messages. @@ -30683,7 +30711,7 @@ Creating a new array Clearing an array @item -Flattening an array for easy C style looping over all its indices and elements +Flattening an array for easy C-style looping over all its indices and elements @end itemize @end itemize @@ -30695,8 +30723,9 @@ The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: +@c FIXME: Make this is a float at some point. @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}} -@headitem C Entity @tab Header File +@headitem C entity @tab Header file @item @code{EOF} @tab @code{<stdio.h>} @item Values for @code{errno} @tab @code{<errno.h>} @item @code{FILE} @tab @code{<stdio.h>} @@ -30722,7 +30751,7 @@ Doing so, however, is poor coding practice. Although the API only uses ISO C 90 features, there is an exception; the ``constructor'' functions use the @code{inline} keyword. If your compiler does not support this keyword, you should either place -@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a +@samp{-Dinline=''} on your command line or use the GNU Autotools and include a @file{config.h} file in your extensions. @item @@ -30730,7 +30759,7 @@ All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} from the extension @emph{must} come from calling one of -@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -30744,7 +30773,7 @@ characters are allowed. By intent, strings are maintained using the current multibyte encoding (as defined by @env{LC_@var{xxx}} environment variables) and not using wide characters. This matches how @command{gawk} stores strings internally -and also how characters are likely to be input and output from files. +and also how characters are likely to be input into and output from files. @end quotation @item @@ -30789,6 +30818,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent @value{SECTION}s, together with the functions that use them. +The general-purpose types and structures are as follows: + @table @code @item typedef void *awk_ext_id_t; A value of this type is received from @command{gawk} when an extension is loaded. @@ -30805,7 +30836,7 @@ while allowing @command{gawk} to use them as it needs to. @itemx @ @ @ @ awk_false = 0, @itemx @ @ @ @ awk_true @itemx @} awk_bool_t; -A simple boolean type. +A simple Boolean type. @item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @@ -30851,7 +30882,7 @@ The @code{val_type} member indicates what kind of value the @itemx #define array_cookie@ @ @ u.a @itemx #define scalar_cookie@ @ u.scl @itemx #define value_cookie@ @ @ u.vc -These macros make accessing the fields of the @code{awk_value_t} more +Using these macros makes accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; @@ -30874,7 +30905,7 @@ indicates what is in the @code{union}. Representing numbers is easy---the API uses a C @code{double}. Strings require more work. Because @command{gawk} allows embedded @sc{nul} bytes in string values, a string must be represented as a pair containing a -data-pointer and length. This is the @code{awk_string_t} type. +data pointer and length. This is the @code{awk_string_t} type. Identifiers (i.e., the names of global variables) can be associated with either scalar values or with arrays. In addition, @command{gawk} @@ -30887,12 +30918,12 @@ of the @code{union} as if they were fields in a @code{struct}; this is a common coding practice in C. Such code is easier to write and to read, but it remains @emph{your} responsibility to make sure that the @code{val_type} member correctly reflects the type of the value in -the @code{awk_value_t}. +the @code{awk_value_t} struct. Conceptually, the first three members of the @code{union} (number, string, and array) are all that is needed for working with @command{awk} values. However, because the API provides routines for accessing and changing -the value of global scalar variables only by using the variable's name, +the value of a global scalar variable only by using the variable's name, there is a performance penalty: @command{gawk} must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -30910,7 +30941,9 @@ See also the entry for ``Cookie'' in the @ref{Glossary}. object for that variable, and then use the cookie for getting the variable's value or for changing the variable's value. -This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro. +The @code{awk_scalar_t} type holds a scalar cookie, and the +@code{scalar_cookie} macro provides access to the value of that type +in the @code{awk_value_t} struct. Given a scalar cookie, @command{gawk} can directly retrieve or modify the value, as required, without having to find it first. @@ -30919,8 +30952,8 @@ If you know that you wish to use the same numeric or string @emph{value} for one or more variables, you can create the value once, retaining a @dfn{value cookie} for it, and then pass in that value cookie whenever you wish to set the value of a -variable. This saves both storage space within the running @command{gawk} -process as well as the time needed to create the value. +variable. This saves storage space within the running @command{gawk} +process and reduces the time needed to create the value. @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @@ -30948,13 +30981,13 @@ be passed to @command{gawk}. @item void gawk_free(void *ptr); Call the correct version of @code{free()} to release storage that was -allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. +allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. @end table The API has to provide these functions because it is possible for an extension to be compiled and linked against a different version of the C library than was used for the @command{gawk} -executable.@footnote{This is more common on MS-Windows systems, but +executable.@footnote{This is more common on MS-Windows systems, but it can happen on Unix-like systems as well.} If @command{gawk} were to use its version of @code{free()} when the memory came from an unrelated version of @code{malloc()}, unexpected behavior would @@ -30964,7 +30997,7 @@ Two convenience macros may be used for allocating storage from @code{gawk_malloc()} and @code{gawk_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were -procedure calls that do not return a value. +procedure calls that do not return a value: @table @code @item #define emalloc(pointer, type, size, message) @dots{} @@ -31001,7 +31034,7 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +This is like @code{emalloc()}, but it calls @code{gawk_realloc()} instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -31026,7 +31059,7 @@ for storage in @code{result}. It returns @code{result}. @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) This function creates a string value in the @code{awk_value_t} variable pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -31077,7 +31110,7 @@ The fields are: @table @code @item const char *name; The name of the new function. -@command{awk} level code calls the function by this name. +@command{awk}-level code calls the function by this name. This is a regular C string. Function names must obey the rules for @command{awk} @@ -31091,7 +31124,7 @@ This is a pointer to the C function that provides the extension's functionality. The function must fill in @code{*result} with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from one of +As mentioned earlier, string memory @emph{must} come from one of @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many @@ -31143,20 +31176,20 @@ The @code{exit_status} parameter is the exit status value that @command{gawk} intends to pass to the @code{exit()} system call. @item arg0 -A pointer to private data which @command{gawk} saves in order to pass to +A pointer to private data that @command{gawk} saves in order to pass to the function pointed to by @code{funcp}. @end table @end table -Exit callback functions are called in last-in-first-out (LIFO) +Exit callback functions are called in last-in, first-out (LIFO) order---that is, in the reverse order in which they are registered with @command{gawk}. @node Extension Version String @subsubsection Registering An Extension Version String -You can register a version string which indicates the name and -version of your extension, with @command{gawk}, as follows: +You can register a version string that indicates the name and +version of your extension with @command{gawk}, as follows: @table @code @item void register_ext_version(const char *version); @@ -31178,7 +31211,7 @@ of @code{RS} to find the end of the record, and then uses @code{FS} Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}). If you want, you can provide your own custom input parser. An input -parser's job is to return a record to the @command{gawk} record processing +parser's job is to return a record to the @command{gawk} record-processing code, along with indicators for the value and length of the data to be used for @code{RT}, if any. @@ -31196,9 +31229,9 @@ It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf); When @command{gawk} decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill -in certain fields in the @code{awk_input_buf_t} structure, and ensure +in certain fields in the @code{awk_input_buf_t} structure and ensure that certain conditions are true. It should then return true. If an -error of some kind occurs, it should not fill in any fields, and should +error of some kind occurs, it should not fill in any fields and should return false; then @command{gawk} will not use the input parser. The details are presented shortly. @end table @@ -31291,7 +31324,7 @@ in the @code{struct stat}, or any combination of these factors. Once @code{@var{XXX}_can_take_file()} has returned true, and @command{gawk} has decided to use your input parser, it calls -@code{@var{XXX}_take_control_of()}. That function then fills one of +@code{@var{XXX}_take_control_of()}. That function then fills either the @code{get_record} field or the @code{read_func} field in the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not} set to @code{INVALID_HANDLE}. The following list describes the fields that @@ -31313,21 +31346,21 @@ records. Said function is the core of the input parser. Its behavior is described in the text following this list. @item ssize_t (*read_func)(); -This function pointer should point to function that has the +This function pointer should point to a function that has the same behavior as the standard POSIX @code{read()} system call. It is an alternative to the @code{get_record} pointer. Its behavior is also described in the text following this list. @item void (*close_func)(struct awk_input *iobuf); This function pointer should point to a function that does -the ``tear down.'' It should release any resources allocated by +the ``teardown.'' It should release any resources allocated by @code{@var{XXX}_take_control_of()}. It may also close the file. If it does so, it should set the @code{fd} field to @code{INVALID_HANDLE}. If @code{fd} is still not @code{INVALID_HANDLE} after the call to this function, @command{gawk} calls the regular @code{close()} system call. -Having a ``tear down'' function is optional. If your input parser does +Having a ``teardown'' function is optional. If your input parser does not need it, do not set this field. Then, @command{gawk} calls the regular @code{close()} system call on the file descriptor, so it should be valid. @@ -31338,7 +31371,7 @@ input records. The parameters are as follows: @table @code @item char **out -This is a pointer to a @code{char *} variable which is set to point +This is a pointer to a @code{char *} variable that is set to point to the record. @command{gawk} makes its own copy of the data, so the extension must manage this storage. @@ -31391,17 +31424,17 @@ set this field explicitly. You must choose one method or the other: either a function that returns a record, or one that returns raw data. In particular, if you supply a function to get a record, @command{gawk} will -call it, and never call the raw read function. +call it, and will never call the raw read function. @end quotation @command{gawk} ships with a sample extension that reads directories, -returning records for each entry in the directory (@pxref{Extension +returning records for each entry in a directory (@pxref{Extension Sample Readdir}). You may wish to use that code as a guide for writing your own input parser. When writing an input parser, you should think about (and document) how it is expected to interact with @command{awk} code. You may want -it to always be called, and take effect as appropriate (as the +it to always be called, and to take effect as appropriate (as the @code{readdir} extension does). Or you may want it to take effect based upon the value of an @command{awk} variable, as the XML extension from the @code{gawkextlib} project does (@pxref{gawkextlib}). @@ -31511,7 +31544,7 @@ a pointer to any private data associated with the file. These pointers should be set to point to functions that perform the equivalent function as the @code{<stdio.h>} functions do, if appropriate. @command{gawk} uses these function pointers for all output. -@command{gawk} initializes the pointers to point to internal, ``pass through'' +@command{gawk} initializes the pointers to point to internal ``pass-through'' functions that just call the regular @code{<stdio.h>} functions, so an extension only needs to redefine those functions that are appropriate for what it does. @@ -31522,7 +31555,7 @@ upon the @code{name} and @code{mode} fields, and any additional state (such as @command{awk} variable values) that is appropriate. When @command{gawk} calls @code{@var{XXX}_take_control_of()}, that function should fill -in the other fields, as appropriate, except for @code{fp}, which it should just +in the other fields as appropriate, except for @code{fp}, which it should just use normally. You register your output wrapper with the following function: @@ -31562,14 +31595,14 @@ The fields are as follows: The name of the two-way processor. @item awk_bool_t (*can_take_two_way)(const char *name); -This function returns true if it wants to take over two-way I/O for this @value{FN}. +The function pointed to by this field should return true if it wants to take over two-way I/O for this @value{FN}. It should not change any state (variable values, etc.) within @command{gawk}. @item awk_bool_t (*take_control_of)(const char *name, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_input_buf_t *inbuf, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_output_buf_t *outbuf); -This function should fill in the @code{awk_input_buf_t} and +The function pointed to by this field should fill in the @code{awk_input_buf_t} and @code{awk_outut_buf_t} structures pointed to by @code{inbuf} and @code{outbuf}, respectively. These structures were described earlier. @@ -31598,7 +31631,7 @@ Register the two-way processor pointed to by @code{two_way_processor} with You can print different kinds of warning messages from your extension, as described here. Note that for these functions, -you must pass in the extension id received from @command{gawk} +you must pass in the extension ID received from @command{gawk} when the extension was loaded:@footnote{Because the API uses only ISO C 90 features, it cannot make use of the ISO C 99 variadic macro feature to hide that parameter. More's the pity.} @@ -31651,7 +31684,7 @@ matches what you requested, the function returns true and fills in the @code{awk_value_t} result. Otherwise, the function returns false, and the @code{val_type} member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual +print an error message or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. @@ -31684,32 +31717,32 @@ value type, as appropriate. This behavior is summarized in <entry><para><emphasis role="bold">String</emphasis></para></entry> <entry><para>String</para></entry> <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> <entry><para><emphasis role="bold">Number</emphasis></para></entry> <entry><para>Number if can be converted, else false</para></entry> <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Type</emphasis></para></entry> <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> <entry><para>Array</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> </row> <row> <entry><para><emphasis role="bold">Requested</emphasis></para></entry> <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> <entry><para>Scalar</para></entry> <entry><para>Scalar</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> </row> <row> <entry></entry> @@ -31721,11 +31754,11 @@ value type, as appropriate. This behavior is summarized in </row> <row> <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> + <entry><para><emphasis role="bold">Value cookie</emphasis></para></entry> + <entry><para>False</para></entry> + <entry><para>False</para></entry> + <entry><para>False</para> + </entry><entry><para>False</para></entry> </row> </tbody> </tgroup> @@ -31743,12 +31776,12 @@ value type, as appropriate. This behavior is summarized in @end tex @multitable @columnfractions .166 .166 .198 .15 .15 .166 @headitem @tab @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{String} @tab String @tab String @tab false @tab false -@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false -@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @tab @b{String} @tab String @tab String @tab False @tab False +@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab False @tab False +@item @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab False +@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab False @tab False @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false +@item @tab @b{Value cookie} @tab False @tab False @tab False @tab False @end multitable @end ifnotdocbook @end ifnotplaintext @@ -31759,21 +31792,21 @@ value type, as appropriate. This behavior is summarized in +------------+------------+-----------+-----------+ | String | Number | Array | Undefined | +-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | +| | String | String | String | False | False | | |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | +| | Number | Number if | Number | False | False | | | | can be | | | | | | | converted, | | | | | | | else false | | | | | |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | +| Type | Array | False | False | Array | False | | Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | +| | Scalar | Scalar | Scalar | False | False | | |-----------+------------+------------+-----------+-----------+ | | Undefined | String | Number | Array | Undefined | | |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | +| | Value | False | False | False | False | +| | cookie | | | | | +-----------+-----------+------------+------------+-----------+-----------+ @end example @end ifplaintext @@ -31790,16 +31823,16 @@ passed to your extension function. They are: @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Fill in the @code{awk_value_t} structure pointed to by @code{result} -with the @code{count}'th argument. Return true if the actual -type matches @code{wanted}, false otherwise. In the latter +with the @code{count}th argument. Return true if the actual +type matches @code{wanted}, and false otherwise. In the latter case, @code{result@w{->}val_type} indicates the actual type -(@pxref{table-value-types-returned}). Counts are zero based---the first +(@pxref{table-value-types-returned}). Counts are zero-based---the first argument is numbered zero, the second one, and so on. @code{wanted} indicates the type of value expected. @item awk_bool_t set_argument(size_t count, awk_array_t array); Convert a parameter that was undefined into an array; this provides -call-by-reference for arrays. Return false if @code{count} is too big, +call by reference for arrays. Return false if @code{count} is too big, or if the argument's type is not undefined. @DBXREF{Array Manipulation} for more information on creating arrays. @end table @@ -31823,8 +31856,9 @@ allows you to create and release cached values. The following routines provide the ability to access and update global @command{awk}-level variables by name. In compiler terminology, identifiers of different kinds are termed @dfn{symbols}, thus the ``sym'' -in the routines' names. The data structure which stores information +in the routines' names. The data structure that stores information about symbols is termed a @dfn{symbol table}. +The functions are as follows: @table @code @item awk_bool_t sym_lookup(const char *name, @@ -31833,14 +31867,14 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise. +Return true if the actual type matches @code{wanted}, and false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @item awk_bool_t sym_update(const char *name, awk_value_t *value); Update the variable named by the string @code{name}, which is a regular C string. The variable is added to @command{gawk}'s symbol table -if it is not there. Return true if everything worked, false otherwise. +if it is not there. Return true if everything worked, and false otherwise. Changing types (scalar to array or vice versa) of an existing variable is @emph{not} allowed, nor may this routine be used to update an array. @@ -31865,7 +31899,7 @@ populate it. A @dfn{scalar cookie} is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in @command{gawk}'s symbol table every time -access is needed. This was discussed earlier in @ref{General Data Types}. +access is needed. This was discussed earlier, in @ref{General Data Types}. The following functions let you work with scalar cookies: @@ -31981,7 +32015,7 @@ and carefully check the return values from the API functions. @subsubsection Creating and Using Cached Values The routines in this section allow you to create and release -cached values. As with scalar cookies, in theory, cached values +cached values. Like scalar cookies, in theory, cached values are not necessary. You can create numbers and strings using the functions in @ref{Constructor Functions}. You can then assign those values to variables using @code{sym_update()} @@ -32059,7 +32093,7 @@ Using value cookies in this way saves considerable storage, as all of @code{VAR1} through @code{VAR100} share the same value. You might be wondering, ``Is this sharing problematic? -What happens if @command{awk} code assigns a new value to @code{VAR1}, +What happens if @command{awk} code assigns a new value to @code{VAR1}; are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. @@ -32163,7 +32197,7 @@ modify them. @node Array Functions @subsubsection Array Functions -The following functions relate to individual array elements. +The following functions relate to individual array elements: @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); @@ -32182,13 +32216,13 @@ Return false if @code{wanted} does not match the actual type or if @code{index} is not in the array (@pxref{table-value-types-returned}). The value for @code{index} can be numeric, in which case @command{gawk} -converts it to a string. Using non-integral values is possible, but +converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to strings -(@pxref{Conversion}); thus using integral values is safest. +(@pxref{Conversion}); thus, using integral values is safest. As with @emph{all} strings passed into @command{gawk} from an extension, the string value of @code{index} must come from @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}, and +@code{gawk_calloc()}, or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -32244,7 +32278,7 @@ flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data); When done with a flattened array, release the storage using this function. -You must pass in both the original array cookie, and the address of +You must pass in both the original array cookie and the address of the created @code{awk_flat_array_t} structure. The function returns true upon success, false otherwise. @end table @@ -32254,7 +32288,7 @@ The function returns true upon success, false otherwise. To @dfn{flatten} an array is to create a structure that represents the full array in a fashion that makes it easy -for C code to traverse the entire array. Test code +for C code to traverse the entire array. Some of the code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. @@ -32311,9 +32345,9 @@ dump_array_and_delete(int nargs, awk_value_t *result) @end example The function then proceeds in steps, as follows. First, retrieve -the name of the array, passed as the first argument. Then -retrieve the array itself. If either operation fails, print -error messages and return: +the name of the array, passed as the first argument, followed by +the array itself. If either operation fails, print an +error message and return: @example /* get argument named array as flat array and print it */ @@ -32349,7 +32383,7 @@ and print it: @end example The third step is to actually flatten the array, and then -to double check that the count in the @code{awk_flat_array_t} +to double-check that the count in the @code{awk_flat_array_t} is the same as the count just retrieved: @example @@ -32370,7 +32404,7 @@ is the same as the count just retrieved: The fourth step is to retrieve the index of the element to be deleted, which was passed as the second argument. Remember that argument counts passed to @code{get_argument()} -are zero-based, thus the second argument is numbered one: +are zero-based, and thus the second argument is numbered one: @example if (! get_argument(1, AWK_STRING, & value3)) @{ @@ -32385,7 +32419,7 @@ element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the @code{AWK_ELEMENT_DELETE} bit in the @code{flags} field of the element. When the array is released, @command{gawk} -traverses the flattened array, and deletes any elements which +traverses the flattened array, and deletes any elements that have this flag bit set: @example @@ -32673,10 +32707,10 @@ The API versions are available at compile time as constants: @table @code @item GAWK_API_MAJOR_VERSION -The major version of the API. +The major version of the API @item GAWK_API_MINOR_VERSION -The minor version of the API. +The minor version of the API @end table The minor version increases when new functions are added to the API. Such @@ -32694,14 +32728,14 @@ constant integers: @table @code @item api->major_version -The major version of the running @command{gawk}. +The major version of the running @command{gawk} @item api->minor_version -The minor version of the running @command{gawk}. +The minor version of the running @command{gawk} @end table It is up to the extension to decide if there are API incompatibilities. -Typically a check like this is enough: +Typically, a check like this is enough: @example if (api->major_version != GAWK_API_MAJOR_VERSION @@ -32715,7 +32749,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION @end example Such code is included in the boilerplate @code{dl_load_func()} macro -provided in @file{gawkapi.h} (discussed later, in +provided in @file{gawkapi.h} (discussed in @ref{Extension API Boilerplate}). @node Extension API Informational Variables @@ -32762,7 +32796,7 @@ as described here. The boilerplate needed is also provided in comments in the @file{gawkapi.h} header file: @example -/* Boiler plate code: */ +/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -32821,7 +32855,7 @@ to @code{NULL}, or to point to a string giving the name and version of your extension. @item static awk_ext_func_t func_table[] = @{ @dots{} @}; -This is an array of one or more @code{awk_ext_func_t} structures +This is an array of one or more @code{awk_ext_func_t} structures, as described earlier (@pxref{Extension Functions}). It can then be looped over for multiple calls to @code{add_ext_func()}. @@ -32952,7 +32986,7 @@ the @code{stat()} fails. It fills in the following elements: @table @code @item "name" -The name of the file that was @code{stat()}'ed. +The name of the file that was @code{stat()}ed. @item "dev" @itemx "ino" @@ -33008,7 +33042,7 @@ interprocess communications). The file is a directory. @item "fifo" -The file is a named-pipe (also known as a FIFO). +The file is a named pipe (also known as a FIFO). @item "file" The file is just a regular file. @@ -33031,7 +33065,7 @@ For some other systems, @dfn{a priori} knowledge is used to provide a value. Where no value can be determined, it defaults to 512. @end table -Several additional elements may be present depending upon the operating +Several additional elements may be present, depending upon the operating system and the type of the file. You can test for them in your @command{awk} program by using the @code{in} operator (@pxref{Reference to Elements}): @@ -33061,7 +33095,7 @@ edited slightly for presentation. See @file{extension/filefuncs.c} in the @command{gawk} distribution for the complete version.} The file includes a number of standard header files, and then includes -the @file{gawkapi.h} header file which provides the API definitions. +the @file{gawkapi.h} header file, which provides the API definitions. Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code (@pxref{Extension API Boilerplate}): @@ -33102,9 +33136,9 @@ int plugin_is_GPL_compatible; @cindex programming conventions, @command{gawk} extensions By convention, for an @command{awk} function @code{foo()}, the C function that implements it is called @code{do_foo()}. The function should have -two arguments: the first is an @code{int} usually called @code{nargs}, +two arguments. The first is an @code{int}, usually called @code{nargs}, that represents the number of actual arguments for the function. -The second is a pointer to an @code{awk_value_t}, usually named +The second is a pointer to an @code{awk_value_t} structure, usually named @code{result}: @example @@ -33150,7 +33184,7 @@ Finally, the function returns the return value to the @command{awk} level: The @code{stat()} extension is more involved. First comes a function that turns a numeric mode into a printable representation -(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity: +(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for brevity: @example /* format_mode --- turn a stat mode field into something readable */ @@ -33206,9 +33240,9 @@ array_set_numeric(awk_array_t array, const char *sub, double num) The following function does most of the work to fill in the @code{awk_array_t} result array with values obtained -from a valid @code{struct stat}. It is done in a separate function +from a valid @code{struct stat}. This work is done in a separate function to support the @code{stat()} function for @command{gawk} and also -to support the @code{fts()} extension which is included in +to support the @code{fts()} extension, which is included in the same file but whose code is not shown here (@pxref{Extension Sample File Functions}). @@ -33329,8 +33363,8 @@ the @code{stat()} system call instead of the @code{lstat()} system call. This is done by using a function pointer: @code{statfunc}. @code{statfunc} is initialized to point to @code{lstat()} (instead of @code{stat()}) to get the file information, in case the file is a -symbolic link. However, if there were three arguments, @code{statfunc} -is set point to @code{stat()}, instead. +symbolic link. However, if the third argument is included, @code{statfunc} +is set to point to @code{stat()}, instead. Here is the @code{do_stat()} function, which starts with variable declarations and argument checking: @@ -33386,7 +33420,7 @@ Next, it gets the information for the file. If the called function /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) @{ update_ERRNO_int(errno); @@ -33408,7 +33442,9 @@ Finally, it's necessary to provide the ``glue'' that loads the new function(s) into @command{gawk}. The @code{filefuncs} extension also provides an @code{fts()} -function, which we omit here. For its sake there is an initialization +function, which we omit here +(@pxref{Extension Sample File Functions}). +For its sake, there is an initialization function: @example @@ -33533,9 +33569,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @section The Sample Extensions in the @command{gawk} Distribution @cindex extensions distributed with @command{gawk} -This @value{SECTION} provides brief overviews of the sample extensions +This @value{SECTION} provides a brief overview of the sample extensions that come in the @command{gawk} distribution. Some of them are intended -for production use (e.g., the @code{filefuncs}, @code{readdir} and +for production use (e.g., the @code{filefuncs}, @code{readdir}, and @code{inplace} extensions). Others mainly provide example code that shows how to use the extension API. @@ -33571,14 +33607,14 @@ This is how you load the extension. @item @code{result = chdir("/some/directory")} The @code{chdir()} function is a direct hook to the @code{chdir()} system call to change the current directory. It returns zero -upon success or less than zero upon error. In the latter case, it updates -@code{ERRNO}. +upon success or a value less than zero upon error. +In the latter case, it updates @code{ERRNO}. @cindex @code{stat()} extension function @item @code{result = stat("/some/path", statdata} [@code{, follow}]@code{)} The @code{stat()} function provides a hook into the @code{stat()} system call. -It returns zero upon success or less than zero upon error. +It returns zero upon success or a value less than zero upon error. In the latter case, it updates @code{ERRNO}. By default, it uses the @code{lstat()} system call. However, if passed @@ -33605,10 +33641,10 @@ array with information retrieved from the filesystem, as follows: @item @code{"major"} @tab @code{st_major} @tab Device files @item @code{"minor"} @tab @code{st_minor} @tab Device files @item @code{"blksize"} @tab @code{st_blksize} @tab All -@item @code{"pmode"} @tab A human-readable version of the mode value, such as printed by -@command{ls}. For example, @code{"-rwxr-xr-x"} @tab All +@item @code{"pmode"} @tab A human-readable version of the mode value, like that printed by +@command{ls} (for example, @code{"-rwxr-xr-x"}) @tab All @item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links -@item @code{"type"} @tab The type of the file as a string. One of +@item @code{"type"} @tab The type of the file as a string---one of @code{"file"}, @code{"blockdev"}, @code{"chardev"}, @@ -33618,15 +33654,15 @@ array with information retrieved from the filesystem, as follows: @code{"symlink"}, @code{"door"}, or -@code{"unknown"}. -Not all systems support all file types. @tab All +@code{"unknown"} +(not all systems support all file types) @tab All @end multitable @cindex @code{fts()} extension function @item @code{flags = or(FTS_PHYSICAL, ...)} @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the -@code{filedata} array as described next. @code{flags} is the bitwise +@code{filedata} array, as described next. @code{flags} is the bitwise OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -33682,7 +33718,8 @@ During a traversal, do not cross onto a different mounted filesystem. @end table @item filedata -The @code{filedata} array is first cleared. Then, @code{fts()} creates +The @code{filedata} array holds the results. +@code{fts()} first clears it. Then it creates an element in @code{filedata} for every element in @code{pathlist}. The index is the name of the directory or file given in @code{pathlist}. The element for this index is itself an array. There are two cases: @@ -33724,7 +33761,7 @@ for a file: @code{"path"}, @code{"stat"}, and @code{"error"}. @end table The @code{fts()} function returns zero if there were no errors. -Otherwise it returns @minus{}1. +Otherwise, it returns @minus{}1. @quotation NOTE The @code{fts()} extension does not exactly mimic the @@ -33766,14 +33803,14 @@ The arguments to @code{fnmatch()} are: @table @code @item pattern -The @value{FN} wildcard to match. +The @value{FN} wildcard to match @item string -The @value{FN} string. +The @value{FN} string @item flag Either zero, or the bitwise OR of one or more of the -flags in the @code{FNM} array. +flags in the @code{FNM} array @end table The flags are as follows: @@ -33810,14 +33847,14 @@ This is how you load the extension. @cindex @code{fork()} extension function @item pid = fork() This function creates a new process. The return value is zero in the -child and the process-ID number of the child in the parent, or @minus{}1 +child and the process ID number of the child in the parent, or @minus{}1 upon error. In the latter case, @code{ERRNO} indicates the problem. In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are updated to reflect the correct values. @cindex @code{waitpid()} extension function @item ret = waitpid(pid) -This function takes a numeric argument, which is the process-ID to +This function takes a numeric argument, which is the process ID to wait for. The return value is that of the @code{waitpid()} system call. @@ -33845,8 +33882,8 @@ else @subsection Enabling In-Place File Editing @cindex @code{inplace} extension -The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option -which performs ``in place'' editing of each input file. +The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option, +which performs ``in-place'' editing of each input file. It uses the bundled @file{inplace.awk} include file to invoke the extension properly: @@ -33942,14 +33979,14 @@ they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode number and the @value{FN}, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +has a third field (also separated by a slash), which is a single letter indicating the type of the file. The letters and their corresponding file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types @caption{File types returned by the @code{readdir} extension} @multitable @columnfractions .1 .9 -@headitem Letter @tab File Type +@headitem Letter @tab File type @item @code{b} @tab Block device @item @code{c} @tab Character device @item @code{d} @tab Directory @@ -33977,7 +34014,7 @@ Here is an example: @@load "readdir" @dots{} BEGIN @{ FS = "/" @} -@{ print "file name is", $2 @} +@{ print "@value{FN} is", $2 @} @end example @node Extension Sample Revout @@ -33998,8 +34035,7 @@ BEGIN @{ @} @end example -The output from this program is: -@samp{cinap t'nod}. +The output from this program is @samp{cinap t'nod}. @node Extension Sample Rev2way @subsection Two-Way I/O Example @@ -34054,7 +34090,7 @@ success, or zero upon failure. @code{reada()} is the inverse of @code{writea()}; it reads the file named as its first argument, filling in the array named as the second argument. It clears the array first. -Here too, the return value is one on success and zero upon failure. +Here too, the return value is one on success, or zero upon failure. @end table The array created by @code{reada()} is identical to that written by @@ -34142,7 +34178,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}. Attempt to sleep for @var{seconds} seconds. If @var{seconds} is negative, or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}. Otherwise, return zero after sleeping for the indicated amount of time. -Note that @var{seconds} may be a floating-point (non-integral) value. +Note that @var{seconds} may be a floating-point (nonintegral) value. Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table @@ -34169,10 +34205,13 @@ project provides a number of @command{gawk} extensions, including one for processing XML files. This is the evolution of the original @command{xgawk} (XML @command{gawk}) project. -As of this writing, there are six extensions: +As of this writing, there are seven extensions: @itemize @value{BULLET} @item +@code{errno} extension + +@item GD graphics library extension @item @@ -34183,7 +34222,7 @@ PostgreSQL extension @item MPFR library extension -(this provides access to a number of MPFR functions which @command{gawk}'s +(this provides access to a number of MPFR functions that @command{gawk}'s native MPFR support does not) @item @@ -34237,7 +34276,7 @@ make install @ii{Install the extensions} If you have installed @command{gawk} in the standard way, then you will likely not need the @option{--with-gawk} option when configuring -@code{gawkextlib}. You may also need to use the @command{sudo} utility +@code{gawkextlib}. You may need to use the @command{sudo} utility to install both @command{gawk} and @code{gawkextlib}, depending upon how your system works. @@ -34262,7 +34301,7 @@ named @code{plugin_is_GPL_compatible}. @item Communication between @command{gawk} and an extension is two-way. -@command{gawk} passes a @code{struct} to the extension which contains +@command{gawk} passes a @code{struct} to the extension that contains various data fields and function pointers. The extension can then call into @command{gawk} via the supplied function pointers to accomplish certain tasks. @@ -34275,7 +34314,7 @@ By convention, implementation functions are named @code{do_@var{XXXX}()} for some @command{awk}-level function @code{@var{XXXX}()}. @item -The API is defined in a header file named @file{gawkpi.h}. You must include +The API is defined in a header file named @file{gawkapi.h}. You must include a number of standard header files @emph{before} including it in your source file. @item @@ -34320,7 +34359,7 @@ getting the count of elements in an array; creating a new array; clearing an array; and -flattening an array for easy C style looping over all its indices and elements) +flattening an array for easy C-style looping over all its indices and elements) @end itemize @item @@ -34328,7 +34367,7 @@ The API defines a number of standard data types for representing @command{awk} values, array elements, and arrays. @item -The API provide convenience functions for constructing values. +The API provides convenience functions for constructing values. It also provides memory management functions to ensure compatibility between memory allocated by @command{gawk} and memory allocated by an extension. @@ -34354,8 +34393,8 @@ file make this easier to do. @item The @command{gawk} distribution includes a number of small but useful -sample extensions. The @code{gawkextlib} project includes several more, -larger, extensions. If you wish to write an extension and contribute it +sample extensions. The @code{gawkextlib} project includes several more +(larger) extensions. If you wish to write an extension and contribute it to the community of @command{gawk} users, the @code{gawkextlib} project is the place to do so. diff --git a/extension/ChangeLog b/extension/ChangeLog index e30ad593..22eee5e4 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,7 @@ +2015-02-11 Arnold D. Robbins <arnold@skeeve.com> + + * filefuncs.c: Punctuation fix. + 2015-01-24 Arnold D. Robbins <arnold@skeeve.com> Infrastructure updates. diff --git a/extension/filefuncs.c b/extension/filefuncs.c index a20e9ff7..ddb1ecda 100644 --- a/extension/filefuncs.c +++ b/extension/filefuncs.c @@ -490,7 +490,7 @@ do_stat(int nargs, awk_value_t *result) /* always empty out the array */ clear_array(array); - /* stat the file, if error, set ERRNO and return */ + /* stat the file; if error, set ERRNO and return */ ret = statfunc(name, & sbuf); if (ret < 0) { update_ERRNO_int(errno); @@ -846,7 +846,7 @@ make_number(double num, awk_value_t *result) extern int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id); #if 0 -/* Boiler plate code: */ +/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api; @@ -226,6 +226,7 @@ pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header) if (do_profile && ! rule_count[rule]++) fprintf(prof_fp, _("\t# Rule(s)\n\n")); ip1 = pc->nexti; + indent(ip1->exec_count); if (ip1 != (pc + 1)->firsti) { /* non-empty pattern */ pprint(ip1->nexti, (pc + 1)->firsti, false); /* Allow for case where the "pattern" is just a comment */ diff --git a/test/ChangeLog b/test/ChangeLog index e888c669..d047ae0a 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,8 @@ +2015-02-10 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (profile0): New test. + * profile0.awk, profile0.in, profile0.ok: New files. + 2015-02-08 Arnold D. Robbins <arnold@skeeve.com> * nonfatal1.awk, nonfatal2.awk: String is now "NONFATAL". diff --git a/test/Makefile.am b/test/Makefile.am index 053f89fd..38b0d00b 100644 --- a/test/Makefile.am +++ b/test/Makefile.am @@ -714,6 +714,8 @@ EXTRA_DIST = \ prmreuse.ok \ procinfs.awk \ procinfs.ok \ + profile0.awk \ + profile0.ok \ profile2.ok \ profile3.awk \ profile3.ok \ @@ -1048,7 +1050,7 @@ GAWK_EXT_TESTS = \ nastyparm next nondec nondec2 \ nonfatal1 nonfatal2 \ patsplit posix printfbad1 printfbad2 printfbad3 printfbad4 printhuge procinfs \ - profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ + profile0 profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ profile8 pty1 \ rebuf regnul1 regnul2 regx8bit reginttrad reint reint2 rsgetline rsglstdin rsstart1 \ rsstart2 rsstart3 rstest6 shadow sortfor sortu split_after_fpat \ @@ -1699,6 +1701,12 @@ dumpvars:: @grep -v ENVIRON < awkvars.out | grep -v PROCINFO > _$@; rm awkvars.out @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +profile0: + @echo $@ + @$(AWK) --profile=ap-$@.out -f "$(srcdir)"/$@.awk "$(srcdir)"/$@.in > /dev/null + @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + profile1: @echo $@ @$(AWK) -f "$(srcdir)"/xref.awk "$(srcdir)"/dtdgport.awk > _$@.out1 diff --git a/test/Makefile.in b/test/Makefile.in index 25ea167b..9b235e46 100644 --- a/test/Makefile.in +++ b/test/Makefile.in @@ -971,6 +971,8 @@ EXTRA_DIST = \ prmreuse.ok \ procinfs.awk \ procinfs.ok \ + profile0.awk \ + profile0.ok \ profile2.ok \ profile3.awk \ profile3.ok \ @@ -1304,7 +1306,7 @@ GAWK_EXT_TESTS = \ nastyparm next nondec nondec2 \ nonfatal1 nonfatal2 \ patsplit posix printfbad1 printfbad2 printfbad3 printfbad4 printhuge procinfs \ - profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ + profile0 profile1 profile2 profile3 profile4 profile5 profile6 profile7 \ profile8 pty1 \ rebuf regnul1 regnul2 regx8bit reginttrad reint reint2 rsgetline rsglstdin rsstart1 \ rsstart2 rsstart3 rstest6 shadow sortfor sortu split_after_fpat \ @@ -2137,6 +2139,12 @@ dumpvars:: @grep -v ENVIRON < awkvars.out | grep -v PROCINFO > _$@; rm awkvars.out @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +profile0: + @echo $@ + @$(AWK) --profile=ap-$@.out -f "$(srcdir)"/$@.awk "$(srcdir)"/$@.in > /dev/null + @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + profile1: @echo $@ @$(AWK) -f "$(srcdir)"/xref.awk "$(srcdir)"/dtdgport.awk > _$@.out1 diff --git a/test/profile0.awk b/test/profile0.awk new file mode 100644 index 00000000..a42e94df --- /dev/null +++ b/test/profile0.awk @@ -0,0 +1 @@ +NR == 1 diff --git a/test/profile0.in b/test/profile0.in new file mode 100644 index 00000000..7bba8c8e --- /dev/null +++ b/test/profile0.in @@ -0,0 +1,2 @@ +line 1 +line 2 diff --git a/test/profile0.ok b/test/profile0.ok new file mode 100644 index 00000000..2e3c5728 --- /dev/null +++ b/test/profile0.ok @@ -0,0 +1,6 @@ + # Rule(s) + + 2 NR == 1 { # 1 + 1 print $0 + } + |