diff options
| -rw-r--r-- | doc/ChangeLog | 1 | ||||
| -rw-r--r-- | doc/gawk.info | 1511 | ||||
| -rw-r--r-- | doc/gawk.texi | 340 | ||||
| -rw-r--r-- | doc/gawktexi.in | 338 |
4 files changed, 1089 insertions, 1101 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 5004b645..dc2c6484 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,6 +1,7 @@ 2014-09-29 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: More fixes after reading through the MS. + And still more fixes. 2014-09-28 Arnold D. Robbins <arnold@skeeve.com> diff --git a/doc/gawk.info b/doc/gawk.info index eeca9a77..326c80cf 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -332,7 +332,7 @@ entitled "GNU Free Documentation License". record. * Nextfile Statement:: Stop processing the current file. * Exit Statement:: Stop execution of `awk'. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * User-modified:: Built-in variables that you change to control `awk'. * Auto-set:: Built-in variables where `awk' @@ -530,7 +530,6 @@ entitled "GNU Free Documentation License". * Extension API Description:: A full description of the API. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @@ -543,6 +542,7 @@ entitled "GNU Free Documentation License". * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. * Updating `ERRNO':: Functions for updating `ERRNO'. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -581,9 +581,9 @@ entitled "GNU Free Documentation License". processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to `gettimeofday()' and `sleep()'. +* Extension Sample API Tests:: Tests for the API. * gawkextlib:: The `gawkextlib' project. * Extension summary:: Extension summary. * Extension Exercises:: Exercises. @@ -998,7 +998,7 @@ building blocks for getting most things done in a program. *note Patterns and Actions::, describes how to write patterns for matching records, actions for doing something when a record is matched, -and the built-in variables `awk' and `gawk' use. +and the predefined variables `awk' and `gawk' use. *note Arrays::, covers `awk''s one-and-only data structure: associative arrays. Deleting array elements and whole arrays is also @@ -4065,8 +4065,8 @@ standard input (by default, this is the keyboard, but often it is a pipe from another command) or from files whose names you specify on the `awk' command line. If you specify input files, `awk' reads them in order, processing all the data from one before going on to the next. -The name of the current input file can be found in the built-in variable -`FILENAME' (*note Built-in Variables::). +The name of the current input file can be found in the predefined +variable `FILENAME' (*note Built-in Variables::). The input is read in units called "records", and is processed by the rules of your program one record at a time. By default, each record is @@ -4105,9 +4105,9 @@ File: gawk.info, Node: Records, Next: Fields, Up: Reading Files `awk' divides the input for your program into records and fields. It keeps track of the number of records that have been read so far from -the current input file. This value is stored in a built-in variable +the current input file. This value is stored in a predefined variable called `FNR' which is reset to zero every time a new file is started. -Another built-in variable, `NR', records the total number of input +Another predefined variable, `NR', records the total number of input records read so far from all data files. It starts at zero, but is never automatically reset to zero. @@ -4126,7 +4126,7 @@ Records are separated by a character called the "record separator". By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by assigning the character to the -built-in variable `RS'. +predefined variable `RS'. Like any other variable, the value of `RS' can be changed in the `awk' program with the assignment operator, `=' (*note Assignment @@ -4378,7 +4378,7 @@ Here the first field, or `$1', is `This', the second field, or `$2', is Because there is no space between the `e' and the `.', the period is considered part of the seventh field. - `NF' is a built-in variable whose value is the number of fields in + `NF' is a predefined variable whose value is the number of fields in the current record. `awk' automatically updates the value of `NF' each time it reads a record. No matter how many fields there are, the last field in a record can be represented by `$NF'. So, `$NF' is the same @@ -4644,7 +4644,7 @@ the following line: is split into three fields: `m', `*g', and `*gai*pan'. Note the leading spaces in the values of the second and third fields. - The field separator is represented by the built-in variable `FS'. + The field separator is represented by the predefined variable `FS'. Shell programmers take note: `awk' does _not_ use the name `IFS' that is used by the POSIX-compliant shells (such as the Unix Bourne shell, `sh', or Bash). @@ -4822,7 +4822,7 @@ uppercase `F' instead of a lowercase `f'. The latter option (`-f') specifies a file containing an `awk' program. The value used for the argument to `-F' is processed in exactly the -same way as assignments to the built-in variable `FS'. Any special +same way as assignments to the predefined variable `FS'. Any special characters in the field separator must be escaped appropriately. For example, to use a `\' as the field separator on the command line, you would have to type: @@ -5536,7 +5536,7 @@ Use `getline VAR < FILE' to read input from the file FILE, and put it in the variable VAR. As above, FILE is a string-valued expression that specifies the file from which to read. - In this version of `getline', none of the built-in variables are + In this version of `getline', none of the predefined variables are changed and the record is not split into fields. The only variable changed is VAR.(1) For example, the following program copies all the input files to the output, except for records that say @@ -5657,7 +5657,7 @@ following program reads the current date and time into the variable print "Report printed on " current_time } - In this version of `getline', none of the built-in variables are + In this version of `getline', none of the predefined variables are changed and the record is not split into fields. However, `RT' is set. According to POSIX, `EXPRESSION | getline VAR' is ambiguous if @@ -5707,7 +5707,7 @@ When you use `COMMAND |& getline VAR', the output from the coprocess COMMAND is sent through a two-way pipe to `getline' and into the variable VAR. - In this version of `getline', none of the built-in variables are + In this version of `getline', none of the predefined variables are changed and the record is not split into fields. The only variable changed is VAR. However, `RT' is set. @@ -5782,9 +5782,9 @@ File: gawk.info, Node: Getline Summary, Prev: Getline Notes, Up: Getline ------------------------------------ *note table-getline-variants:: summarizes the eight variants of -`getline', listing which built-in variables are set by each one, and +`getline', listing which predefined variables are set by each one, and whether the variant is standard or a `gawk' extension. Note: for each -variant, `gawk' sets the `RT' built-in variable. +variant, `gawk' sets the `RT' predefined variable. Variant Effect `awk' / `gawk' ------------------------------------------------------------------------- @@ -6172,7 +6172,7 @@ As mentioned previously, a `print' statement contains a list of items separated by commas. In the output, the items are normally separated by single spaces. However, this doesn't need to be the case; a single space is simply the default. Any string of characters may be used as -the "output field separator" by setting the built-in variable `OFS'. +the "output field separator" by setting the predefined variable `OFS'. The initial value of this variable is the string `" "'--that is, a single space. @@ -6234,11 +6234,11 @@ to format numbers (or strings), and that there are a number of different ways in which numbers can be formatted. The different format specifications are discussed more fully in *note Control Letters::. - The built-in variable `OFMT' contains the format specification that -`print' uses with `sprintf()' when it wants to convert a number to a -string for printing. The default value of `OFMT' is `"%.6g"'. The way -`print' prints numbers can be changed by supplying a different format -specification for the value of `OFMT', as shown in the following + The predefined variable `OFMT' contains the format specification +that `print' uses with `sprintf()' when it wants to convert a number to +a string for printing. The default value of `OFMT' is `"%.6g"'. The +way `print' prints numbers can be changed by supplying a different +format specification for the value of `OFMT', as shown in the following example: $ awk 'BEGIN { @@ -7095,8 +7095,8 @@ value from `close()': (d.c.) `gawk' treats `close()' as a function. The return value is -1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. In these -cases, `gawk' sets the built-in variable `ERRNO' to a string describing -the problem. +cases, `gawk' sets the predefined variable `ERRNO' to a string +describing the problem. In `gawk', when closing a pipe or coprocess (input or output), the return value is the exit status of the command.(2) Otherwise, it is the @@ -7477,10 +7477,10 @@ array parameters. *Note String Functions::. A few variables have special built-in meanings, such as `FS' (the field separator), and `NF' (the number of fields in the current input -record). *Note Built-in Variables::, for a list of the built-in -variables. These built-in variables can be used and assigned just like -all other variables, but their values are also used or changed -automatically by `awk'. All built-in variables' names are entirely +record). *Note Built-in Variables::, for a list of the predefined +variables. These predefined variables can be used and assigned just +like all other variables, but their values are also used or changed +automatically by `awk'. All predefined variables' names are entirely uppercase. Variables in `awk' can be assigned either numeric or string values. @@ -7584,7 +7584,7 @@ the string as numerals: `"2.5"' converts to 2.5, `"1e3"' converts to interpreted as valid numbers convert to zero. The exact manner in which numbers are converted into strings is -controlled by the `awk' built-in variable `CONVFMT' (*note Built-in +controlled by the `awk' predefined variable `CONVFMT' (*note Built-in Variables::). Numbers are converted using the `sprintf()' function with `CONVFMT' as the format specifier (*note String Functions::). @@ -8878,7 +8878,7 @@ File: gawk.info, Node: Patterns and Actions, Next: Arrays, Prev: Expressions, As you have already seen, each `awk' statement consists of a pattern with an associated action. This major node describes how you build patterns and actions, what kinds of things you can do within actions, -and `awk''s built-in variables. +and `awk''s predefined variables. The pattern-action rules and the statements available for use within actions form the core of `awk' programming. In a sense, everything @@ -8892,7 +8892,7 @@ top of. Now it's time to start building something useful. * Action Overview:: What goes into an action. * Statements:: Describes the various control statements in detail. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * Pattern Action Summary:: Patterns and Actions summary. @@ -9996,8 +9996,8 @@ statement with a nonzero argument, as shown in the following example: File: gawk.info, Node: Built-in Variables, Next: Pattern Action Summary, Prev: Statements, Up: Patterns and Actions -7.5 Built-in Variables -====================== +7.5 Predefined Variables +======================== Most `awk' variables are available to use for your own purposes; they never change unless your program assigns values to them, and they never @@ -10007,7 +10007,7 @@ of these automatically, so that they enable you to tell `awk' how to do certain things. Others are set automatically by `awk', so that they carry information from the internal workings of `awk' to your program. - This minor node documents all of `gawk''s built-in variables, most + This minor node documents all of `gawk''s predefined variables, most of which are also documented in the major nodes describing their areas of activity. @@ -10680,8 +10680,9 @@ File: gawk.info, Node: Pattern Action Summary, Prev: Built-in Variables, Up: You may pass an optional numeric value to be used as `awk''s exit status. - * Some built-in variables provide control over `awk', mainly for I/O. - Other variables convey information from `awk' to your program. + * Some predefined variables provide control over `awk', mainly for + I/O. Other variables convey information from `awk' to your + program. * `ARGC' and `ARGV' make the command-line arguments available to your program. Manipulating them from a `BEGIN' rule lets you @@ -11224,7 +11225,7 @@ File: gawk.info, Node: Numeric Array Subscripts, Next: Uninitialized Subscript An important aspect to remember about arrays is that _array subscripts are always strings_. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting -(*note Conversion::). This means that the value of the built-in +(*note Conversion::). This means that the value of the predefined variable `CONVFMT' can affect how your program accesses elements of an array. For example: @@ -12148,10 +12149,10 @@ Options::): `match()', the order is the same as for the `~' operator: `STRING ~ REGEXP'. - The `match()' function sets the built-in variable `RSTART' to the - index. It also sets the built-in variable `RLENGTH' to the length - in characters of the matched substring. If no match is found, - `RSTART' is set to zero, and `RLENGTH' to -1. + The `match()' function sets the predefined variable `RSTART' to + the index. It also sets the predefined variable `RLENGTH' to the + length in characters of the matched substring. If no match is + found, `RSTART' is set to zero, and `RLENGTH' to -1. For example: @@ -13382,7 +13383,7 @@ call. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. In addition, according to the POSIX standard, function parameters cannot -have the same name as one of the special built-in variables (*note +have the same name as one of the special predefined variables (*note Built-in Variables::). Not all versions of `awk' enforce this restriction. @@ -14408,7 +14409,7 @@ to start that variable's name with a capital letter--for example, `getopt()''s `Opterr' and `Optind' variables (*note Getopt Function::). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the -variable is not one of `awk''s built-in variables, such as `FS'. +variable is not one of `awk''s predefined variables, such as `FS'. It is also important that _all_ variables in library functions that do not need to save state are, in fact, declared local.(2) If this is @@ -16564,7 +16565,7 @@ Function::). The program begins with a descriptive comment and then a `BEGIN' rule that processes the command-line arguments with `getopt()'. The `-i' (ignore case) option is particularly easy with `gawk'; we just use the -`IGNORECASE' built-in variable (*note Built-in Variables::): +`IGNORECASE' predefined variable (*note Built-in Variables::): # egrep.awk --- simulate egrep in awk # @@ -21772,11 +21773,11 @@ platform-independent results. With the `-M' command-line option, all floating-point arithmetic operators and numeric functions can yield results to any desired precision level supported by MPFR. - Two built-in variables, `PREC' and `ROUNDMODE', provide control over -the working precision and the rounding mode. The precision and the -rounding mode are set globally for every operation to follow. *Note -Setting precision::, and *note Setting the rounding mode::, for more -information. + Two predefined variables, `PREC' and `ROUNDMODE', provide control +over the working precision and the rounding mode. The precision and +the rounding mode are set globally for every operation to follow. +*Note Setting precision::, and *note Setting the rounding mode::, for +more information. File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers, Prev: MPFR features, Up: Arbitrary Precision Arithmetic @@ -22038,7 +22039,7 @@ File: gawk.info, Node: Setting precision, Next: Setting the rounding mode, Pr precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the current working precision. The default working precision is 53 bits, -which you can modify using the built-in variable `PREC'. You can also +which you can modify using the predefined variable `PREC'. You can also 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. @@ -22617,13 +22618,13 @@ describes the API in detail. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with `gawk'. * Printing Messages:: Functions for printing messages. * Updating `ERRNO':: Functions for updating `ERRNO'. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -22643,6 +22644,8 @@ through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: + * Allocating, reallocating, and releasing memory. + * Registration functions. You may register: - extension functions, @@ -22667,8 +22670,6 @@ operations: * Symbol table access: retrieving a global variable, creating one, or changing one. - * Allocating, reallocating, and releasing memory. - * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -22756,7 +22757,7 @@ macros that you should use in your code. This minor node presents the macros as if they were functions. -File: gawk.info, Node: General Data Types, Next: Requesting Values, Prev: Extension API Functions Introduction, Up: Extension API Description +File: gawk.info, Node: General Data Types, Next: Memory Allocation Functions, Prev: Extension API Functions Introduction, Up: Extension API Description 16.4.2 General Purpose Data Types --------------------------------- @@ -22901,7 +22902,7 @@ the value. See also the entry for "Cookie" in the *note Glossary::. -File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: Requesting Values, Up: Extension API Description +File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: General Data Types, Up: Extension API Description 16.4.3 Memory Allocation Functions and Convenience Macros --------------------------------------------------------- @@ -23546,7 +23547,7 @@ of the ISO C 99 variadic macro feature to hide that parameter. More's the pity. -File: gawk.info, Node: Updating `ERRNO', Next: Accessing Parameters, Prev: Printing Messages, Up: Extension API Description +File: gawk.info, Node: Updating `ERRNO', Next: Requesting Values, Prev: Printing Messages, Up: Extension API Description 16.4.7 Updating `ERRNO' ----------------------- @@ -23567,7 +23568,7 @@ The following functions allow you to update the `ERRNO' variable: Unset `ERRNO'. -File: gawk.info, Node: Requesting Values, Next: Memory Allocation Functions, Prev: General Data Types, Up: Extension API Description +File: gawk.info, Node: Requesting Values, Next: Accessing Parameters, Prev: Updating `ERRNO', Up: Extension API Description 16.4.8 Requesting Values ------------------------ @@ -23600,7 +23601,7 @@ Requested: Scalar Scalar Scalar false false Table 16.1: API Value Types Returned -File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Updating `ERRNO', Up: Extension API Description +File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Requesting Values, Up: Extension API Description 16.4.9 Accessing and Updating Parameters ---------------------------------------- @@ -23705,7 +23706,7 @@ was discussed earlier, in *note General Data Types::. `awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value);' Update the value associated with a scalar cookie. Return false if the new value is not of type `AWK_STRING' or `AWK_NUMBER'. Here - too, the built-in variables may not be updated. + too, the predefined variables may not be updated. It is not obvious at first glance how to work with scalar cookies or what their raison d'e^tre really is. In theory, the `sym_lookup()' and @@ -24475,8 +24476,8 @@ invoked. The variables are: option. The value of `do_lint' can change if `awk' code modifies the `LINT' -built-in variable (*note Built-in Variables::). The others should not -change during execution. +predefined variable (*note Built-in Variables::). The others should +not change during execution. File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variables, Up: Extension API Description @@ -24986,7 +24987,15 @@ and/or the type of the file. It then returns zero, for success: return 0; } - Finally, here is the `do_stat()' function. It starts with variable + The third argument to `stat()' was not discussed previously. This +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. + + Here is the `do_stat()' function. It starts with variable declarations and argument checking: /* do_stat --- provide a stat() function for gawk */ @@ -25011,14 +25020,10 @@ declarations and argument checking: return make_number(-1, result); } - The third argument to `stat()' was not discussed previously. This -argument is optional. If present, it causes `stat()' to use the `stat()' -system call instead of the `lstat()' system call. - Then comes the actual work. First, the function gets the arguments. -Next, it gets the information for the file. The code use `lstat()' -(instead of `stat()') to get the file information, in case the file is -a symbolic link. If there's an error, it sets `ERRNO' and returns: +Next, it gets the information for the file. If the called function +(`lstat()' or `stat()') returns an error, the code sets `ERRNO' and +returns: /* file is first arg, array to hold results is second */ if ( ! get_argument(0, AWK_STRING, & file_param) @@ -25045,7 +25050,7 @@ a symbolic link. If there's an error, it sets `ERRNO' and returns: } The tedious work is done by `fill_stat_array()', shown earlier. -When done, return the result from `fill_stat_array()': +When done, the function returns the result from `fill_stat_array()': ret = fill_stat_array(name, array, & sbuf); @@ -25127,14 +25132,14 @@ create a GNU/Linux shared library: for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) + strftime("%m %d %Y %H:%M:%S", data["mtime"]) print "\nInfo for JUNK" ret = stat("JUNK", data) print "ret =", ret for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + print "JUNK modified:", strftime("%m %d %Y %H:%M:%S", data["mtime"]) } The `AWKLIBPATH' environment variable tells `gawk' where to find @@ -25146,32 +25151,33 @@ directory and run the program: -| Info for testff.awk -| ret = 0 -| data["blksize"] = 4096 - -| data["mtime"] = 1350838628 + -| data["devbsize"] = 512 + -| data["mtime"] = 1412004710 -| data["mode"] = 33204 -| data["type"] = file -| data["dev"] = 2053 -| data["gid"] = 1000 - -| data["ino"] = 1719496 - -| data["ctime"] = 1350838628 + -| data["ino"] = 10358899 + -| data["ctime"] = 1412004710 -| data["blocks"] = 8 -| data["nlink"] = 1 -| data["name"] = testff.awk - -| data["atime"] = 1350838632 + -| data["atime"] = 1412004716 -| data["pmode"] = -rw-rw-r-- - -| data["size"] = 662 + -| data["size"] = 666 -| data["uid"] = 1000 - -| testff.awk modified: 10 21 12 18:57:08 + -| testff.awk modified: 09 29 2014 18:31:50 -| -| Info for JUNK -| ret = -1 - -| JUNK modified: 01 01 70 02:00:00 + -| JUNK modified: 01 01 1970 02:00:00 ---------- Footnotes ---------- (1) In practice, you would probably want to use the GNU Autotools--Automake, Autoconf, Libtool, and `gettext'--to configure and build your libraries. Instructions for doing so are beyond the scope of -this Info file. *Note gawkextlib::, for WWW links to the tools. +this Info file. *Note gawkextlib::, for Internet links to the tools. File: gawk.info, Node: Extension Samples, Next: gawkextlib, Prev: Extension Example, Up: Dynamic Extensions @@ -25199,9 +25205,9 @@ the extension API. * Extension Sample Rev2way:: Reversing data sample two-way processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to `gettimeofday()' and `sleep()'. +* Extension Sample API Tests:: Tests for the API. File: gawk.info, Node: Extension Sample File Functions, Next: Extension Sample Fnmatch, Up: Extension Samples @@ -25212,7 +25218,7 @@ File: gawk.info, Node: Extension Sample File Functions, Next: Extension Sample The `filefuncs' extension provides three different functions, as follows: The usage is: -@load "filefuncs" +`@load "filefuncs"' This is how you load the extension. `result = chdir("/some/directory")' @@ -25268,8 +25274,8 @@ follows: The usage is: `result = fts(pathlist, flags, filedata)' Walk the file trees provided in `pathlist' and fill in the `filedata' array as described below. `flags' is the bitwise OR of - several predefined constant values, also described below. Return - zero if there were no errors, otherwise return -1. + several predefined values, also described below. Return zero if + there were no errors, otherwise return -1. The `fts()' function provides a hook to the C library `fts()' routines for traversing file hierarchies. Instead of returning data @@ -25310,10 +25316,10 @@ requested hierarchies. whether or not `FTS_LOGICAL' is set. `FTS_SEEDOT' - By default, the `fts()' routines do not return entries for - `.' (dot) and `..' (dot-dot). This option causes entries for - dot-dot to also be included. (The extension always includes - an entry for dot, see below.) + By default, the C library `fts()' routines do not return + entries for `.' (dot) and `..' (dot-dot). This option causes + entries for dot-dot to also be included. (The extension + always includes an entry for dot, see below.) `FTS_XDEV' During a traversal, do not cross onto a different mounted @@ -25363,15 +25369,16 @@ 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 - interface that is based on associative arrays, which should be - more comfortable to use from an `awk' program. This includes the - lack of a comparison function, since `gawk' already provides - powerful array sorting facilities. While an `fts_read()'-like - interface could have been provided, this felt less natural than - simply creating a multidimensional array to represent the file - hierarchy and its information. + interface that is based on associative arrays, which is more + comfortable to use from an `awk' program. This includes the lack + of a comparison function, since `gawk' already provides powerful + array sorting facilities. While an `fts_read()'-like interface + could have been provided, this felt less natural than simply + creating a multidimensional array to represent the file hierarchy + and its information. - See `test/fts.awk' in the `gawk' distribution for an example. + See `test/fts.awk' in the `gawk' distribution for an example use of +the `fts()' extension function. File: gawk.info, Node: Extension Sample Fnmatch, Next: Extension Sample Fork, Prev: Extension Sample File Functions, Up: Extension Samples @@ -25566,7 +25573,7 @@ Letter File Type `s' Socket `u' Anything else (unknown) -Table 16.2: File Types Returned By `readdir()' +Table 16.2: File Types Returned By The `readdir' Extension On systems without the file type information, the third field is always `u'. @@ -25637,6 +25644,9 @@ File: gawk.info, Node: Extension Sample Read write array, Next: Extension Samp The `rwarray' extension adds two functions, named `writea()' and `reada()', as follows: +`@load "rwarray"' + This is how you load the extension. + `ret = writea(file, array)' This function takes a string argument, which is the name of the file to which to dump the array, and the array itself as the @@ -25673,7 +25683,7 @@ restored on systems with a different one, but this has not been tried. ret = reada("arraydump.bin", array) -File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample API Tests, Prev: Extension Sample Read write array, Up: Extension Samples +File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample Time, Prev: Extension Sample Read write array, Up: Extension Samples 16.7.10 Reading An Entire File ------------------------------ @@ -25706,21 +25716,9 @@ an input parser: } -File: gawk.info, Node: Extension Sample API Tests, Next: Extension Sample Time, Prev: Extension Sample Readfile, Up: Extension Samples - -16.7.11 API Tests ------------------ - -The `testext' extension exercises parts of the extension API that are -not tested by the other samples. The `extension/testext.c' file -contains both the C code for the extension and `awk' test code inside C -comments that run the tests. The testing framework extracts the `awk' -code and runs the tests. See the source file for more information. +File: gawk.info, Node: Extension Sample Time, Next: Extension Sample API Tests, Prev: Extension Sample Readfile, Up: Extension Samples - -File: gawk.info, Node: Extension Sample Time, Prev: Extension Sample API Tests, Up: Extension Samples - -16.7.12 Extension Time Functions +16.7.11 Extension Time Functions -------------------------------- The `time' extension adds two functions, named `gettimeofday()' and @@ -25749,6 +25747,18 @@ The `time' extension adds two functions, named `gettimeofday()' and delay. +File: gawk.info, Node: Extension Sample API Tests, Prev: Extension Sample Time, Up: Extension Samples + +16.7.12 API Tests +----------------- + +The `testext' extension exercises parts of the extension API that are +not tested by the other samples. The `extension/testext.c' file +contains both the C code for the extension and `awk' test code inside C +comments that run the tests. The testing framework extracts the `awk' +code and runs the tests. See the source file for more information. + + File: gawk.info, Node: gawkextlib, Next: Extension summary, Prev: Extension Samples, Up: Dynamic Extensions 16.8 The `gawkextlib' Project @@ -25761,21 +25771,17 @@ project. As of this writing, there are five extensions: - * XML parser extension, using the Expat - (http://expat.sourceforge.net) XML parsing library. + * GD graphics library extension. * PDF extension. * PostgreSQL extension. - * GD graphics library extension. - * MPFR library extension. This provides access to a number of MPFR functions which `gawk''s native MPFR support does not. - The `time' extension described earlier (*note Extension Sample -Time::) was originally from this project but has been moved in to the -main `gawk' distribution. + * XML parser extension, using the Expat + (http://expat.sourceforge.net) XML parsing library. You can check out the code for the `gawkextlib' project using the Git (http://git-scm.com) distributed source code control system. The @@ -25851,6 +25857,8 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * API function pointers are provided for the following kinds of operations: + * Allocating, reallocating, and releasing memory. + * Registration functions. You may register extension functions, exit callbacks, a version string, input parsers, output wrappers, and two-way processors. @@ -25865,8 +25873,6 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * Symbol table access: retrieving a global variable, creating one, or changing one. - * Allocating, reallocating, and releasing memory. - * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -25890,7 +25896,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * _All_ memory passed from an extension to `gawk' must come from the API's memory allocation functions. `gawk' takes responsibility for - the memory and will release it when appropriate. + the memory and releases it when appropriate. * The API provides information about the running version of `gawk' so that an extension can make sure it is compatible with the `gawk' @@ -25904,7 +25910,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga 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 should be the place to do so. + project is the place to do so. @@ -25937,11 +25943,11 @@ This Info file describes the GNU implementation of `awk', which follows the POSIX specification. Many long-time `awk' users learned `awk' programming with the original `awk' implementation in Version 7 Unix. (This implementation was the basis for `awk' in Berkeley Unix, through -4.3-Reno. Subsequent versions of Berkeley Unix, and some systems -derived from 4.4BSD-Lite, used various versions of `gawk' for their -`awk'.) This major node briefly describes the evolution of the `awk' -language, with cross-references to other parts of the Info file where -you can find more information. +4.3-Reno. Subsequent versions of Berkeley Unix, and, for a while, some +systems derived from 4.4BSD-Lite, used various versions of `gawk' for +their `awk'.) This major node briefly describes the evolution of the +`awk' language, with cross-references to other parts of the Info file +where you can find more information. * Menu: @@ -25991,7 +25997,7 @@ the changes, with cross-references to further details: Functions::). * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP' - built-in variables (*note Built-in Variables::). + predefined variables (*note Built-in Variables::). * Assignable `$0' (*note Changing Fields::). @@ -26012,12 +26018,10 @@ the changes, with cross-references to further details: Functions::), rather than using only the first character of `FS'. * Dynamic regexps as operands of the `~' and `!~' operators (*note - Regexp Usage::). + Computed Regexps::). * The escape sequences `\b', `\f', and `\r' (*note Escape - Sequences::). (Some vendors have updated their old versions of - `awk' to recognize `\b', `\f', and `\r', but this is not something - you can rely on.) + Sequences::). * Redirection of input for the `getline' function (*note Getline::). @@ -26041,7 +26045,7 @@ The System V Release 4 (1989) version of Unix `awk' added these features * The `-v' option for assigning variables before program execution begins (*note Options::). - * The `--' option for terminating command-line options. + * The `--' signal for terminating command-line options. * The `\a', `\v', and `\x' escape sequences (*note Escape Sequences::). @@ -26056,8 +26060,8 @@ The System V Release 4 (1989) version of Unix `awk' added these features `printf' function (*note Control Letters::). * The ability to dynamically pass the field width and precision - (`"%*.*d"') in the argument list of the `printf' function (*note - Control Letters::). + (`"%*.*d"') in the argument list of `printf' and `sprintf()' + (*note Control Letters::). * The use of regexp constants, such as `/foo/', as expressions, where they are equivalent to using the matching operator, as in `$0 ~ @@ -26084,8 +26088,8 @@ introduced the following changes into the language: * The concept of a numeric string and tighter comparison rules to go with it (*note Typing and Comparison::). - * The use of built-in variables as function parameter names is - forbidden (*note Definition Syntax::. + * The use of predefined variables as function parameter names is + forbidden (*note Definition Syntax::). * More complete documentation of many of the previously undocumented features of the language. @@ -26147,7 +26151,7 @@ can all be disabled with either the `--traditional' or `--posix' options node summarizes the additional features over POSIX `awk' that are in the current version of `gawk'. - * Additional built-in variables: + * Additional predefined variables: - The `ARGIND' `BINMODE', `ERRNO', `FIELDWIDTHS', `FPAT', `IGNORECASE', `LINT', `PROCINFO', `RT', and `TEXTDOMAIN' @@ -26189,11 +26193,6 @@ the current version of `gawk'. - The `BEGINFILE' and `ENDFILE' special patterns. (*note BEGINFILE/ENDFILE::). - - The ability to delete all of an array at once with `delete - ARRAY' (*note Delete::). - - - The `nextfile' statement (*note Nextfile Statement::). - - The `switch' statement (*note Switch Statement::). * Changes to standard `awk' functions: @@ -26202,7 +26201,7 @@ the current version of `gawk'. one end of a two-way pipe to a coprocess (*note Two-way I/O::). - - POSIX compliance for `gsub()' and `sub()'. + - POSIX compliance for `gsub()' and `sub()' with `--posix'. - The `length()' function accepts an array argument and returns the number of elements in the array (*note String @@ -26221,24 +26220,24 @@ the current version of `gawk'. * Additional functions only in `gawk': - - The `and()', `compl()', `lshift()', `or()', `rshift()', and - `xor()' functions for bit manipulation (*note Bitwise - Functions::). + - The `gensub()', `patsplit()', and `strtonum()' functions for + more powerful text manipulation (*note String Functions::). - The `asort()' and `asorti()' functions for sorting arrays (*note Array Sorting::). - - The `bindtextdomain()', `dcgettext()' and `dcngettext()' - functions for internationalization (*note Programmer i18n::). + - The `mktime()', `systime()', and `strftime()' functions for + working with timestamps (*note Time Functions::). - - The `fflush()' function from BWK `awk' (*note I/O + - The `and()', `compl()', `lshift()', `or()', `rshift()', and + `xor()' functions for bit manipulation (*note Bitwise Functions::). - - The `gensub()', `patsplit()', and `strtonum()' functions for - more powerful text manipulation (*note String Functions::). + - The `isarray()' function to check if a variable is an array + or not (*note Type Functions::). - - The `mktime()', `systime()', and `strftime()' functions for - working with timestamps (*note Time Functions::). + - The `bindtextdomain()', `dcgettext()' and `dcngettext()' + functions for internationalization (*note Programmer i18n::). * Changes and/or additions in the command-line options: @@ -26290,7 +26289,7 @@ the current version of `gawk'. * Support for the following obsolete systems was removed from the - code and the documentation for `gawk' version 4.1: + code for `gawk' version 4.1: - Ultrix @@ -26688,30 +26687,26 @@ File: gawk.info, Node: Common Extensions, Next: Ranges and Locales, Prev: Fea A.7 Common Extensions Summary ============================= -This minor node summarizes the common extensions supported by `gawk', -Brian Kernighan's `awk', and `mawk', the three most widely-used freely -available versions of `awk' (*note Other Versions::). - -Feature BWK Awk Mawk GNU Awk --------------------------------------------------------- -`\x' Escape sequence X X X -`FS' as null string X X X -`/dev/stdin' special file X X X -`/dev/stdout' special file X X X -`/dev/stderr' special file X X X -`delete' without subscript X X X -`fflush()' function X X X -`length()' of an array X X X -`nextfile' statement X X X -`**' and `**=' operators X X -`func' keyword X X -`BINMODE' variable X X -`RS' as regexp X X -Time related functions X X - - (Technically speaking, as of late 2012, `fflush()', `delete ARRAY', -and `nextfile' are no longer extensions, since they have been added to -POSIX.) +The following table summarizes the common extensions supported by +`gawk', Brian Kernighan's `awk', and `mawk', the three most widely-used +freely available versions of `awk' (*note Other Versions::). + +Feature BWK Awk Mawk GNU Awk Now standard +----------------------------------------------------------------------- +`\x' Escape sequence X X X +`FS' as null string X X X +`/dev/stdin' special file X X X +`/dev/stdout' special file X X X +`/dev/stderr' special file X X X +`delete' without subscript X X X X +`fflush()' function X X X X +`length()' of an array X X X +`nextfile' statement X X X X +`**' and `**=' operators X X +`func' keyword X X +`BINMODE' variable X X +`RS' as regexp X X +Time related functions X X File: gawk.info, Node: Ranges and Locales, Next: Contributors, Prev: Common Extensions, Up: Language History @@ -26752,14 +26747,14 @@ like `[a-dx-z]' is still equivalent to `[abcdxyz]', as in ASCII. But outside those locales, the ordering was defined to be based on "collation order". - In many locales, `A' and `a' are both less than `B'. In other -words, these locales sort characters in dictionary order, and -`[a-dx-z]' is typically not equivalent to `[abcdxyz]'; instead it might -be equivalent to `[ABCXYabcdxyz]', for example. + What does that mean? In many locales, `A' and `a' are both less +than `B'. In other words, these locales sort characters in dictionary +order, and `[a-dx-z]' is typically not equivalent to `[abcdxyz]'; +instead it might be equivalent to `[ABCXYabcdxyz]', for example. This point needs to be emphasized: Much literature teaches that you should use `[a-z]' to match a lowercase character. But on systems with -non-ASCII locales, this also matched all of the uppercase characters +non-ASCII locales, this also matches all of the uppercase characters except `A' or `Z'! This was a continuous cause of confusion, even well into the twenty-first century. @@ -26956,6 +26951,9 @@ Info file, in approximate chronological order: 4.1 was driven primarily by Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. + * John Malmberg contributed significant improvements to the OpenVMS + port and the related documentation. + * Antonio Giovanni Colombo rewrote a number of examples in the early chapters that were severely dated, for which I am incredibly grateful. @@ -28941,7 +28939,7 @@ C.5.3 Other Design Decisions ---------------------------- As an arbitrary design decision, extensions can read the values of -built-in variables and arrays (such as `ARGV' and `FS'), but cannot +predefined variables and arrays (such as `ARGV' and `FS'), but cannot change them, with the exception of `PROCINFO'. The reason for this is to prevent an extension function from @@ -29508,11 +29506,11 @@ FDL Field When `awk' reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can - change by setting the built-in variable `FS'). Such pieces are + change by setting the predefined variable `FS'). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable `FIELDWIDTHS' to describe their lengths. If you wish to specify the contents of fields instead of the field - separator, you can use the built-in variable `FPAT' to do so. + separator, you can use the predefined variable `FPAT' to do so. (*Note Field Separators::, *note Constant Size::, and *note Splitting By Content::.) @@ -29529,7 +29527,7 @@ Format Format strings control the appearance of output in the `strftime()' and `sprintf()' functions, and in the `printf' statement as well. Also, data conversions from numbers to strings - are controlled by the format strings contained in the built-in + are controlled by the format strings contained in the predefined variables `CONVFMT' and `OFMT'. (*Note Control Letters::.) Free Documentation License @@ -31743,10 +31741,6 @@ Index * bug-gawk@gnu.org bug reporting address: Bugs. (line 30) * built-in functions: Functions. (line 6) * built-in functions, evaluation order: Calling Built-in. (line 30) -* built-in variables: Built-in Variables. (line 6) -* built-in variables, -v option, setting with: Options. (line 40) -* built-in variables, conveying information: Auto-set. (line 6) -* built-in variables, user-modifiable: User-modified. (line 6) * Busybox Awk: Other Versions. (line 88) * c.e., See common extensions: Conventions. (line 51) * call by reference: Pass By Value/Reference. @@ -31808,7 +31802,7 @@ Index * Collado, Manuel: Acknowledgments. (line 60) * collating elements: Bracket Expressions. (line 79) * collating symbols: Bracket Expressions. (line 86) -* Colombo, Antonio <1>: Contributors. (line 137) +* Colombo, Antonio <1>: Contributors. (line 140) * Colombo, Antonio: Acknowledgments. (line 60) * columns, aligning: Print Examples. (line 70) * columns, cutting: Cut Program. (line 6) @@ -32325,7 +32319,7 @@ Index (line 99) * exp: Numeric Functions. (line 33) * expand utility: Very Simple. (line 72) -* Expat XML parser library: gawkextlib. (line 35) +* Expat XML parser library: gawkextlib. (line 31) * exponent: Numeric Functions. (line 33) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) @@ -32602,7 +32596,6 @@ Index * gawk, awk and: Preface. (line 21) * gawk, bitwise operations in: Bitwise Functions. (line 40) * gawk, break statement in: Break Statement. (line 51) -* gawk, built-in variables and: Built-in Variables. (line 14) * gawk, character classes and: Bracket Expressions. (line 100) * gawk, coding style in: Adding Code. (line 39) * gawk, command-line options, and regular expressions: GNU Regexp Operators. @@ -32661,6 +32654,7 @@ Index * gawk, newlines in: Statements/Lines. (line 12) * gawk, octal numbers and: Nondecimal-numbers. (line 42) * gawk, OS/2 version of: PC Using. (line 16) +* gawk, predefined variables and: Built-in Variables. (line 14) * gawk, PROCINFO array in <1>: Two-way I/O. (line 99) * gawk, PROCINFO array in <2>: Time Functions. (line 47) * gawk, PROCINFO array in: Auto-set. (line 137) @@ -32740,7 +32734,7 @@ Index * git utility <2>: Accessing The Source. (line 10) * git utility <3>: Other Versions. (line 29) -* git utility: gawkextlib. (line 29) +* git utility: gawkextlib. (line 25) * Git, use of for gawk source code: Derived Files. (line 6) * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 51) @@ -33040,6 +33034,7 @@ Index * mailing list, GNITS: Acknowledgments. (line 52) * Malmberg, John <1>: Bugs. (line 71) * Malmberg, John: Acknowledgments. (line 60) +* Malmberg, John E.: Contributors. (line 137) * mark parity: Ordinal Functions. (line 45) * marked string extraction (internationalization): String Extraction. (line 6) @@ -33370,6 +33365,10 @@ Index * precedence <1>: Precedence. (line 6) * precedence: Increment Ops. (line 60) * precedence, regexp operators: Regexp Operators. (line 156) +* predefined variables: Built-in Variables. (line 6) +* predefined variables, -v option, setting with: Options. (line 40) +* predefined variables, conveying information: Auto-set. (line 6) +* predefined variables, user-modifiable: User-modified. (line 6) * print debugger command: Viewing And Changing Data. (line 36) * print statement: Printing. (line 16) @@ -33483,7 +33482,7 @@ Index * Rankin, Pat <3>: Assignment Ops. (line 100) * Rankin, Pat: Acknowledgments. (line 60) * reada() extension function: Extension Sample Read write array. - (line 15) + (line 18) * readable data files, checking: File Checking. (line 6) * readable.awk program: File Checking. (line 11) * readdir extension: Extension Sample Readdir. @@ -33588,7 +33587,7 @@ Index * RLENGTH variable, match() function and: String Functions. (line 227) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) -* Robbins, Arnold <3>: Contributors. (line 141) +* Robbins, Arnold <3>: Contributors. (line 144) * Robbins, Arnold <4>: General Data Types. (line 6) * Robbins, Arnold <5>: Alarm Program. (line 6) * Robbins, Arnold <6>: Passwd Functions. (line 90) @@ -34033,10 +34032,7 @@ Index * variables <1>: Basic Data Typing. (line 6) * variables: Other Features. (line 6) * variables, assigning on command line: Assignment Options. (line 6) -* variables, built-in <1>: Built-in Variables. (line 6) * variables, built-in: Using Variables. (line 23) -* variables, built-in, -v option, setting with: Options. (line 40) -* variables, built-in, conveying information: Auto-set. (line 6) * variables, flag: Boolean Ops. (line 69) * variables, getline command into, using <1>: Getline/Variable/Coprocess. (line 6) @@ -34049,6 +34045,9 @@ Index * variables, global, printing list of: Options. (line 93) * variables, initializing: Using Variables. (line 23) * variables, local to a function: Variable Scope. (line 6) +* variables, predefined: Built-in Variables. (line 6) +* variables, predefined -v option, setting with: Options. (line 40) +* variables, predefined conveying information: Auto-set. (line 6) * variables, private: Library Names. (line 11) * variables, setting: Options. (line 32) * variables, shadowing: Definition Syntax. (line 71) @@ -34113,7 +34112,7 @@ Index * words, duplicate, searching for: Dupword Program. (line 6) * words, usage counts, generating: Word Sorting. (line 6) * writea() extension function: Extension Sample Read write array. - (line 9) + (line 12) * xgettext utility: String Extraction. (line 13) * xor: Bitwise Functions. (line 56) * XOR bitwise operation: Bitwise Functions. (line 6) @@ -34151,557 +34150,557 @@ Index Tag Table: Node: Top1204 -Node: Foreword41978 -Node: Preface46325 -Ref: Preface-Footnote-149220 -Ref: Preface-Footnote-249327 -Ref: Preface-Footnote-349560 -Node: History49702 -Node: Names52076 -Ref: Names-Footnote-153170 -Node: This Manual53316 -Ref: This Manual-Footnote-159151 -Node: Conventions59251 -Node: Manual History61596 -Ref: Manual History-Footnote-164672 -Ref: Manual History-Footnote-264713 -Node: How To Contribute64787 -Node: Acknowledgments66026 -Node: Getting Started70774 -Node: Running gawk73208 -Node: One-shot74398 -Node: Read Terminal75623 -Node: Long77650 -Node: Executable Scripts79166 -Ref: Executable Scripts-Footnote-181955 -Node: Comments82057 -Node: Quoting84530 -Node: DOS Quoting90040 -Node: Sample Data Files90715 -Node: Very Simple93308 -Node: Two Rules98199 -Node: More Complex100085 -Node: Statements/Lines102947 -Ref: Statements/Lines-Footnote-1107403 -Node: Other Features107668 -Node: When108599 -Ref: When-Footnote-1110355 -Node: Intro Summary110420 -Node: Invoking Gawk111303 -Node: Command Line112818 -Node: Options113609 -Ref: Options-Footnote-1129375 -Node: Other Arguments129400 -Node: Naming Standard Input132361 -Node: Environment Variables133454 -Node: AWKPATH Variable134012 -Ref: AWKPATH Variable-Footnote-1136864 -Ref: AWKPATH Variable-Footnote-2136909 -Node: AWKLIBPATH Variable137169 -Node: Other Environment Variables137928 -Node: Exit Status141401 -Node: Include Files142076 -Node: Loading Shared Libraries145654 -Node: Obsolete147081 -Node: Undocumented147778 -Node: Invoking Summary148045 -Node: Regexp149711 -Node: Regexp Usage151170 -Node: Escape Sequences153203 -Node: Regexp Operators159303 -Ref: Regexp Operators-Footnote-1166738 -Ref: Regexp Operators-Footnote-2166885 -Node: Bracket Expressions166983 -Ref: table-char-classes169000 -Node: Leftmost Longest171940 -Node: Computed Regexps173242 -Node: GNU Regexp Operators176639 -Node: Case-sensitivity180345 -Ref: Case-sensitivity-Footnote-1183235 -Ref: Case-sensitivity-Footnote-2183470 -Node: Regexp Summary183578 -Node: Reading Files185047 -Node: Records187139 -Node: awk split records187867 -Node: gawk split records192779 -Ref: gawk split records-Footnote-1197318 -Node: Fields197355 -Ref: Fields-Footnote-1200151 -Node: Nonconstant Fields200237 -Ref: Nonconstant Fields-Footnote-1202467 -Node: Changing Fields202669 -Node: Field Separators208601 -Node: Default Field Splitting211303 -Node: Regexp Field Splitting212420 -Node: Single Character Fields215770 -Node: Command Line Field Separator216829 -Node: Full Line Fields220039 -Ref: Full Line Fields-Footnote-1220547 -Node: Field Splitting Summary220593 -Ref: Field Splitting Summary-Footnote-1223724 -Node: Constant Size223825 -Node: Splitting By Content228431 -Ref: Splitting By Content-Footnote-1232504 -Node: Multiple Line232544 -Ref: Multiple Line-Footnote-1238433 -Node: Getline238612 -Node: Plain Getline240823 -Node: Getline/Variable243463 -Node: Getline/File244610 -Node: Getline/Variable/File245994 -Ref: Getline/Variable/File-Footnote-1247593 -Node: Getline/Pipe247680 -Node: Getline/Variable/Pipe250363 -Node: Getline/Coprocess251492 -Node: Getline/Variable/Coprocess252744 -Node: Getline Notes253481 -Node: Getline Summary256273 -Ref: table-getline-variants256681 -Node: Read Timeout257510 -Ref: Read Timeout-Footnote-1261324 -Node: Command-line directories261382 -Node: Input Summary262286 -Node: Input Exercises265538 -Node: Printing266266 -Node: Print268043 -Node: Print Examples269500 -Node: Output Separators272279 -Node: OFMT274295 -Node: Printf275647 -Node: Basic Printf276432 -Node: Control Letters278003 -Node: Format Modifiers281987 -Node: Printf Examples287994 -Node: Redirection290476 -Node: Special FD297207 -Ref: Special FD-Footnote-1300364 -Node: Special Files300438 -Node: Other Inherited Files301054 -Node: Special Network302054 -Node: Special Caveats302915 -Node: Close Files And Pipes303866 -Ref: Close Files And Pipes-Footnote-1311043 -Ref: Close Files And Pipes-Footnote-2311191 -Node: Output Summary311341 -Node: Output Exercises312337 -Node: Expressions313017 -Node: Values314202 -Node: Constants314878 -Node: Scalar Constants315558 -Ref: Scalar Constants-Footnote-1316417 -Node: Nondecimal-numbers316667 -Node: Regexp Constants319667 -Node: Using Constant Regexps320192 -Node: Variables323330 -Node: Using Variables323985 -Node: Assignment Options325889 -Node: Conversion327764 -Node: Strings And Numbers328288 -Ref: Strings And Numbers-Footnote-1331350 -Node: Locale influences conversions331459 -Ref: table-locale-affects334174 -Node: All Operators334762 -Node: Arithmetic Ops335392 -Node: Concatenation337897 -Ref: Concatenation-Footnote-1340716 -Node: Assignment Ops340822 -Ref: table-assign-ops345805 -Node: Increment Ops347083 -Node: Truth Values and Conditions350521 -Node: Truth Values351604 -Node: Typing and Comparison352653 -Node: Variable Typing353446 -Node: Comparison Operators357098 -Ref: table-relational-ops357508 -Node: POSIX String Comparison361023 -Ref: POSIX String Comparison-Footnote-1362095 -Node: Boolean Ops362233 -Ref: Boolean Ops-Footnote-1366712 -Node: Conditional Exp366803 -Node: Function Calls368530 -Node: Precedence372410 -Node: Locales376078 -Node: Expressions Summary377709 -Node: Patterns and Actions380283 -Node: Pattern Overview381399 -Node: Regexp Patterns383078 -Node: Expression Patterns383621 -Node: Ranges387401 -Node: BEGIN/END390507 -Node: Using BEGIN/END391269 -Ref: Using BEGIN/END-Footnote-1394006 -Node: I/O And BEGIN/END394112 -Node: BEGINFILE/ENDFILE396426 -Node: Empty399327 -Node: Using Shell Variables399644 -Node: Action Overview401920 -Node: Statements404247 -Node: If Statement406095 -Node: While Statement407593 -Node: Do Statement409621 -Node: For Statement410763 -Node: Switch Statement413918 -Node: Break Statement416306 -Node: Continue Statement418347 -Node: Next Statement420172 -Node: Nextfile Statement422552 -Node: Exit Statement425182 -Node: Built-in Variables427585 -Node: User-modified428712 -Ref: User-modified-Footnote-1436392 -Node: Auto-set436454 -Ref: Auto-set-Footnote-1449648 -Ref: Auto-set-Footnote-2449853 -Node: ARGC and ARGV449909 -Node: Pattern Action Summary454113 -Node: Arrays456532 -Node: Array Basics457861 -Node: Array Intro458705 -Ref: figure-array-elements460678 -Ref: Array Intro-Footnote-1463202 -Node: Reference to Elements463330 -Node: Assigning Elements465780 -Node: Array Example466271 -Node: Scanning an Array468029 -Node: Controlling Scanning471045 -Ref: Controlling Scanning-Footnote-1476234 -Node: Numeric Array Subscripts476550 -Node: Uninitialized Subscripts478733 -Node: Delete480350 -Ref: Delete-Footnote-1483094 -Node: Multidimensional483151 -Node: Multiscanning486246 -Node: Arrays of Arrays487835 -Node: Arrays Summary492596 -Node: Functions494701 -Node: Built-in495574 -Node: Calling Built-in496652 -Node: Numeric Functions498640 -Ref: Numeric Functions-Footnote-1503464 -Ref: Numeric Functions-Footnote-2503821 -Ref: Numeric Functions-Footnote-3503869 -Node: String Functions504138 -Ref: String Functions-Footnote-1527598 -Ref: String Functions-Footnote-2527727 -Ref: String Functions-Footnote-3527975 -Node: Gory Details528062 -Ref: table-sub-escapes529843 -Ref: table-sub-proposed531363 -Ref: table-posix-sub532727 -Ref: table-gensub-escapes534267 -Ref: Gory Details-Footnote-1535099 -Node: I/O Functions535250 -Ref: I/O Functions-Footnote-1542351 -Node: Time Functions542498 -Ref: Time Functions-Footnote-1552967 -Ref: Time Functions-Footnote-2553035 -Ref: Time Functions-Footnote-3553193 -Ref: Time Functions-Footnote-4553304 -Ref: Time Functions-Footnote-5553416 -Ref: Time Functions-Footnote-6553643 -Node: Bitwise Functions553909 -Ref: table-bitwise-ops554471 -Ref: Bitwise Functions-Footnote-1558779 -Node: Type Functions558948 -Node: I18N Functions560097 -Node: User-defined561742 -Node: Definition Syntax562546 -Ref: Definition Syntax-Footnote-1567950 -Node: Function Example568019 -Ref: Function Example-Footnote-1570936 -Node: Function Caveats570958 -Node: Calling A Function571476 -Node: Variable Scope572431 -Node: Pass By Value/Reference575419 -Node: Return Statement578929 -Node: Dynamic Typing581913 -Node: Indirect Calls582842 -Ref: Indirect Calls-Footnote-1592563 -Node: Functions Summary592691 -Node: Library Functions595390 -Ref: Library Functions-Footnote-1599008 -Ref: Library Functions-Footnote-2599151 -Node: Library Names599322 -Ref: Library Names-Footnote-1602780 -Ref: Library Names-Footnote-2603000 -Node: General Functions603086 -Node: Strtonum Function604114 -Node: Assert Function607134 -Node: Round Function610458 -Node: Cliff Random Function611999 -Node: Ordinal Functions613015 -Ref: Ordinal Functions-Footnote-1616080 -Ref: Ordinal Functions-Footnote-2616332 -Node: Join Function616543 -Ref: Join Function-Footnote-1618314 -Node: Getlocaltime Function618514 -Node: Readfile Function622255 -Node: Data File Management624203 -Node: Filetrans Function624835 -Node: Rewind Function628894 -Node: File Checking630279 -Ref: File Checking-Footnote-1631607 -Node: Empty Files631808 -Node: Ignoring Assigns633787 -Node: Getopt Function635338 -Ref: Getopt Function-Footnote-1646798 -Node: Passwd Functions647001 -Ref: Passwd Functions-Footnote-1655852 -Node: Group Functions655940 -Ref: Group Functions-Footnote-1663843 -Node: Walking Arrays664056 -Node: Library Functions Summary665659 -Node: Library Exercises667060 -Node: Sample Programs668340 -Node: Running Examples669110 -Node: Clones669838 -Node: Cut Program671062 -Node: Egrep Program680792 -Ref: Egrep Program-Footnote-1688294 -Node: Id Program688404 -Node: Split Program692048 -Ref: Split Program-Footnote-1695494 -Node: Tee Program695622 -Node: Uniq Program698409 -Node: Wc Program705830 -Ref: Wc Program-Footnote-1710078 -Node: Miscellaneous Programs710170 -Node: Dupword Program711383 -Node: Alarm Program713414 -Node: Translate Program718218 -Ref: Translate Program-Footnote-1722791 -Ref: Translate Program-Footnote-2723061 -Node: Labels Program723200 -Ref: Labels Program-Footnote-1726549 -Node: Word Sorting726633 -Node: History Sorting730703 -Node: Extract Program732539 -Node: Simple Sed740071 -Node: Igawk Program743133 -Ref: Igawk Program-Footnote-1757459 -Ref: Igawk Program-Footnote-2757660 -Ref: Igawk Program-Footnote-3757782 -Node: Anagram Program757897 -Node: Signature Program760959 -Node: Programs Summary762206 -Node: Programs Exercises763399 -Ref: Programs Exercises-Footnote-1767530 -Node: Advanced Features767621 -Node: Nondecimal Data769569 -Node: Array Sorting771159 -Node: Controlling Array Traversal771856 -Ref: Controlling Array Traversal-Footnote-1780187 -Node: Array Sorting Functions780305 -Ref: Array Sorting Functions-Footnote-1784197 -Node: Two-way I/O784391 -Ref: Two-way I/O-Footnote-1789335 -Ref: Two-way I/O-Footnote-2789521 -Node: TCP/IP Networking789603 -Node: Profiling792480 -Node: Advanced Features Summary800033 -Node: Internationalization801966 -Node: I18N and L10N803446 -Node: Explaining gettext804132 -Ref: Explaining gettext-Footnote-1809161 -Ref: Explaining gettext-Footnote-2809345 -Node: Programmer i18n809510 -Ref: Programmer i18n-Footnote-1814376 -Node: Translator i18n814425 -Node: String Extraction815219 -Ref: String Extraction-Footnote-1816350 -Node: Printf Ordering816436 -Ref: Printf Ordering-Footnote-1819222 -Node: I18N Portability819286 -Ref: I18N Portability-Footnote-1821735 -Node: I18N Example821798 -Ref: I18N Example-Footnote-1824598 -Node: Gawk I18N824670 -Node: I18N Summary825308 -Node: Debugger826647 -Node: Debugging827669 -Node: Debugging Concepts828110 -Node: Debugging Terms829967 -Node: Awk Debugging832542 -Node: Sample Debugging Session833434 -Node: Debugger Invocation833954 -Node: Finding The Bug835338 -Node: List of Debugger Commands841813 -Node: Breakpoint Control843145 -Node: Debugger Execution Control846837 -Node: Viewing And Changing Data850201 -Node: Execution Stack853566 -Node: Debugger Info855204 -Node: Miscellaneous Debugger Commands859221 -Node: Readline Support864413 -Node: Limitations865305 -Node: Debugging Summary867402 -Node: Arbitrary Precision Arithmetic868570 -Node: Computer Arithmetic869986 -Ref: table-numeric-ranges873587 -Ref: Computer Arithmetic-Footnote-1874446 -Node: Math Definitions874503 -Ref: table-ieee-formats877790 -Ref: Math Definitions-Footnote-1878394 -Node: MPFR features878499 -Node: FP Math Caution880167 -Ref: FP Math Caution-Footnote-1881217 -Node: Inexactness of computations881586 -Node: Inexact representation882534 -Node: Comparing FP Values883889 -Node: Errors accumulate884962 -Node: Getting Accuracy886395 -Node: Try To Round889054 -Node: Setting precision889953 -Ref: table-predefined-precision-strings890635 -Node: Setting the rounding mode892429 -Ref: table-gawk-rounding-modes892793 -Ref: Setting the rounding mode-Footnote-1896247 -Node: Arbitrary Precision Integers896426 -Ref: Arbitrary Precision Integers-Footnote-1900209 -Node: POSIX Floating Point Problems900358 -Ref: POSIX Floating Point Problems-Footnote-1904234 -Node: Floating point summary904272 -Node: Dynamic Extensions906464 -Node: Extension Intro908016 -Node: Plugin License909282 -Node: Extension Mechanism Outline910079 -Ref: figure-load-extension910507 -Ref: figure-register-new-function911987 -Ref: figure-call-new-function912991 -Node: Extension API Description914977 -Node: Extension API Functions Introduction916427 -Node: General Data Types921263 -Ref: General Data Types-Footnote-1926940 -Node: Memory Allocation Functions927239 -Ref: Memory Allocation Functions-Footnote-1930068 -Node: Constructor Functions930164 -Node: Registration Functions931898 -Node: Extension Functions932583 -Node: Exit Callback Functions934879 -Node: Extension Version String936127 -Node: Input Parsers936777 -Node: Output Wrappers946592 -Node: Two-way processors951108 -Node: Printing Messages953312 -Ref: Printing Messages-Footnote-1954389 -Node: Updating `ERRNO'954541 -Node: Requesting Values955284 -Ref: table-value-types-returned956021 -Node: Accessing Parameters956979 -Node: Symbol Table Access958209 -Node: Symbol table by name958723 -Node: Symbol table by cookie960703 -Ref: Symbol table by cookie-Footnote-1964840 -Node: Cached values964903 -Ref: Cached values-Footnote-1968407 -Node: Array Manipulation968498 -Ref: Array Manipulation-Footnote-1969596 -Node: Array Data Types969635 -Ref: Array Data Types-Footnote-1972292 -Node: Array Functions972384 -Node: Flattening Arrays976238 -Node: Creating Arrays983125 -Node: Extension API Variables987892 -Node: Extension Versioning988528 -Node: Extension API Informational Variables990429 -Node: Extension API Boilerplate991515 -Node: Finding Extensions995331 -Node: Extension Example995891 -Node: Internal File Description996663 -Node: Internal File Ops1000730 -Ref: Internal File Ops-Footnote-11012164 -Node: Using Internal File Ops1012304 -Ref: Using Internal File Ops-Footnote-11014651 -Node: Extension Samples1014919 -Node: Extension Sample File Functions1016443 -Node: Extension Sample Fnmatch1024011 -Node: Extension Sample Fork1025493 -Node: Extension Sample Inplace1026706 -Node: Extension Sample Ord1028381 -Node: Extension Sample Readdir1029217 -Ref: table-readdir-file-types1030073 -Node: Extension Sample Revout1030872 -Node: Extension Sample Rev2way1031463 -Node: Extension Sample Read write array1032204 -Node: Extension Sample Readfile1034083 -Node: Extension Sample API Tests1035183 -Node: Extension Sample Time1035708 -Node: gawkextlib1037023 -Node: Extension summary1039836 -Node: Extension Exercises1043529 -Node: Language History1044251 -Node: V7/SVR3.11045894 -Node: SVR41048214 -Node: POSIX1049656 -Node: BTL1051042 -Node: POSIX/GNU1051776 -Node: Feature History1057552 -Node: Common Extensions1070643 -Node: Ranges and Locales1071955 -Ref: Ranges and Locales-Footnote-11076572 -Ref: Ranges and Locales-Footnote-21076599 -Ref: Ranges and Locales-Footnote-31076833 -Node: Contributors1077054 -Node: History summary1082481 -Node: Installation1083850 -Node: Gawk Distribution1084801 -Node: Getting1085285 -Node: Extracting1086109 -Node: Distribution contents1087751 -Node: Unix Installation1093521 -Node: Quick Installation1094138 -Node: Additional Configuration Options1096580 -Node: Configuration Philosophy1098318 -Node: Non-Unix Installation1100669 -Node: PC Installation1101127 -Node: PC Binary Installation1102438 -Node: PC Compiling1104286 -Ref: PC Compiling-Footnote-11107285 -Node: PC Testing1107390 -Node: PC Using1108566 -Node: Cygwin1112718 -Node: MSYS1113527 -Node: VMS Installation1114025 -Node: VMS Compilation1114821 -Ref: VMS Compilation-Footnote-11116043 -Node: VMS Dynamic Extensions1116101 -Node: VMS Installation Details1117474 -Node: VMS Running1119726 -Node: VMS GNV1122560 -Node: VMS Old Gawk1123283 -Node: Bugs1123753 -Node: Other Versions1127757 -Node: Installation summary1133981 -Node: Notes1135037 -Node: Compatibility Mode1135902 -Node: Additions1136684 -Node: Accessing The Source1137609 -Node: Adding Code1139045 -Node: New Ports1145217 -Node: Derived Files1149698 -Ref: Derived Files-Footnote-11155173 -Ref: Derived Files-Footnote-21155207 -Ref: Derived Files-Footnote-31155803 -Node: Future Extensions1155917 -Node: Implementation Limitations1156523 -Node: Extension Design1157771 -Node: Old Extension Problems1158925 -Ref: Old Extension Problems-Footnote-11160442 -Node: Extension New Mechanism Goals1160499 -Ref: Extension New Mechanism Goals-Footnote-11163859 -Node: Extension Other Design Decisions1164048 -Node: Extension Future Growth1166154 -Node: Old Extension Mechanism1166990 -Node: Notes summary1168752 -Node: Basic Concepts1169938 -Node: Basic High Level1170619 -Ref: figure-general-flow1170891 -Ref: figure-process-flow1171490 -Ref: Basic High Level-Footnote-11174719 -Node: Basic Data Typing1174904 -Node: Glossary1178232 -Node: Copying1203384 -Node: GNU Free Documentation License1240940 -Node: Index1266076 +Node: Foreword41980 +Node: Preface46327 +Ref: Preface-Footnote-149222 +Ref: Preface-Footnote-249329 +Ref: Preface-Footnote-349562 +Node: History49704 +Node: Names52078 +Ref: Names-Footnote-153172 +Node: This Manual53318 +Ref: This Manual-Footnote-159155 +Node: Conventions59255 +Node: Manual History61600 +Ref: Manual History-Footnote-164676 +Ref: Manual History-Footnote-264717 +Node: How To Contribute64791 +Node: Acknowledgments66030 +Node: Getting Started70778 +Node: Running gawk73212 +Node: One-shot74402 +Node: Read Terminal75627 +Node: Long77654 +Node: Executable Scripts79170 +Ref: Executable Scripts-Footnote-181959 +Node: Comments82061 +Node: Quoting84534 +Node: DOS Quoting90044 +Node: Sample Data Files90719 +Node: Very Simple93312 +Node: Two Rules98203 +Node: More Complex100089 +Node: Statements/Lines102951 +Ref: Statements/Lines-Footnote-1107407 +Node: Other Features107672 +Node: When108603 +Ref: When-Footnote-1110359 +Node: Intro Summary110424 +Node: Invoking Gawk111307 +Node: Command Line112822 +Node: Options113613 +Ref: Options-Footnote-1129379 +Node: Other Arguments129404 +Node: Naming Standard Input132365 +Node: Environment Variables133458 +Node: AWKPATH Variable134016 +Ref: AWKPATH Variable-Footnote-1136868 +Ref: AWKPATH Variable-Footnote-2136913 +Node: AWKLIBPATH Variable137173 +Node: Other Environment Variables137932 +Node: Exit Status141405 +Node: Include Files142080 +Node: Loading Shared Libraries145658 +Node: Obsolete147085 +Node: Undocumented147782 +Node: Invoking Summary148049 +Node: Regexp149715 +Node: Regexp Usage151174 +Node: Escape Sequences153207 +Node: Regexp Operators159307 +Ref: Regexp Operators-Footnote-1166742 +Ref: Regexp Operators-Footnote-2166889 +Node: Bracket Expressions166987 +Ref: table-char-classes169004 +Node: Leftmost Longest171944 +Node: Computed Regexps173246 +Node: GNU Regexp Operators176643 +Node: Case-sensitivity180349 +Ref: Case-sensitivity-Footnote-1183239 +Ref: Case-sensitivity-Footnote-2183474 +Node: Regexp Summary183582 +Node: Reading Files185051 +Node: Records187145 +Node: awk split records187877 +Node: gawk split records192791 +Ref: gawk split records-Footnote-1197330 +Node: Fields197367 +Ref: Fields-Footnote-1200165 +Node: Nonconstant Fields200251 +Ref: Nonconstant Fields-Footnote-1202481 +Node: Changing Fields202683 +Node: Field Separators208615 +Node: Default Field Splitting211319 +Node: Regexp Field Splitting212436 +Node: Single Character Fields215786 +Node: Command Line Field Separator216845 +Node: Full Line Fields220057 +Ref: Full Line Fields-Footnote-1220565 +Node: Field Splitting Summary220611 +Ref: Field Splitting Summary-Footnote-1223742 +Node: Constant Size223843 +Node: Splitting By Content228449 +Ref: Splitting By Content-Footnote-1232522 +Node: Multiple Line232562 +Ref: Multiple Line-Footnote-1238451 +Node: Getline238630 +Node: Plain Getline240841 +Node: Getline/Variable243481 +Node: Getline/File244628 +Node: Getline/Variable/File246012 +Ref: Getline/Variable/File-Footnote-1247613 +Node: Getline/Pipe247700 +Node: Getline/Variable/Pipe250383 +Node: Getline/Coprocess251514 +Node: Getline/Variable/Coprocess252766 +Node: Getline Notes253505 +Node: Getline Summary256297 +Ref: table-getline-variants256709 +Node: Read Timeout257538 +Ref: Read Timeout-Footnote-1261352 +Node: Command-line directories261410 +Node: Input Summary262314 +Node: Input Exercises265566 +Node: Printing266294 +Node: Print268071 +Node: Print Examples269528 +Node: Output Separators272307 +Node: OFMT274325 +Node: Printf275679 +Node: Basic Printf276464 +Node: Control Letters278035 +Node: Format Modifiers282019 +Node: Printf Examples288026 +Node: Redirection290508 +Node: Special FD297239 +Ref: Special FD-Footnote-1300396 +Node: Special Files300470 +Node: Other Inherited Files301086 +Node: Special Network302086 +Node: Special Caveats302947 +Node: Close Files And Pipes303898 +Ref: Close Files And Pipes-Footnote-1311077 +Ref: Close Files And Pipes-Footnote-2311225 +Node: Output Summary311375 +Node: Output Exercises312371 +Node: Expressions313051 +Node: Values314236 +Node: Constants314912 +Node: Scalar Constants315592 +Ref: Scalar Constants-Footnote-1316451 +Node: Nondecimal-numbers316701 +Node: Regexp Constants319701 +Node: Using Constant Regexps320226 +Node: Variables323364 +Node: Using Variables324019 +Node: Assignment Options325929 +Node: Conversion327804 +Node: Strings And Numbers328328 +Ref: Strings And Numbers-Footnote-1331392 +Node: Locale influences conversions331501 +Ref: table-locale-affects334216 +Node: All Operators334804 +Node: Arithmetic Ops335434 +Node: Concatenation337939 +Ref: Concatenation-Footnote-1340758 +Node: Assignment Ops340864 +Ref: table-assign-ops345847 +Node: Increment Ops347125 +Node: Truth Values and Conditions350563 +Node: Truth Values351646 +Node: Typing and Comparison352695 +Node: Variable Typing353488 +Node: Comparison Operators357140 +Ref: table-relational-ops357550 +Node: POSIX String Comparison361065 +Ref: POSIX String Comparison-Footnote-1362137 +Node: Boolean Ops362275 +Ref: Boolean Ops-Footnote-1366754 +Node: Conditional Exp366845 +Node: Function Calls368572 +Node: Precedence372452 +Node: Locales376120 +Node: Expressions Summary377751 +Node: Patterns and Actions380325 +Node: Pattern Overview381445 +Node: Regexp Patterns383124 +Node: Expression Patterns383667 +Node: Ranges387447 +Node: BEGIN/END390553 +Node: Using BEGIN/END391315 +Ref: Using BEGIN/END-Footnote-1394052 +Node: I/O And BEGIN/END394158 +Node: BEGINFILE/ENDFILE396472 +Node: Empty399373 +Node: Using Shell Variables399690 +Node: Action Overview401966 +Node: Statements404293 +Node: If Statement406141 +Node: While Statement407639 +Node: Do Statement409667 +Node: For Statement410809 +Node: Switch Statement413964 +Node: Break Statement416352 +Node: Continue Statement418393 +Node: Next Statement420218 +Node: Nextfile Statement422598 +Node: Exit Statement425228 +Node: Built-in Variables427631 +Node: User-modified428764 +Ref: User-modified-Footnote-1436444 +Node: Auto-set436506 +Ref: Auto-set-Footnote-1449700 +Ref: Auto-set-Footnote-2449905 +Node: ARGC and ARGV449961 +Node: Pattern Action Summary454165 +Node: Arrays456592 +Node: Array Basics457921 +Node: Array Intro458765 +Ref: figure-array-elements460738 +Ref: Array Intro-Footnote-1463262 +Node: Reference to Elements463390 +Node: Assigning Elements465840 +Node: Array Example466331 +Node: Scanning an Array468089 +Node: Controlling Scanning471105 +Ref: Controlling Scanning-Footnote-1476294 +Node: Numeric Array Subscripts476610 +Node: Uninitialized Subscripts478795 +Node: Delete480412 +Ref: Delete-Footnote-1483156 +Node: Multidimensional483213 +Node: Multiscanning486308 +Node: Arrays of Arrays487897 +Node: Arrays Summary492658 +Node: Functions494763 +Node: Built-in495636 +Node: Calling Built-in496714 +Node: Numeric Functions498702 +Ref: Numeric Functions-Footnote-1503526 +Ref: Numeric Functions-Footnote-2503883 +Ref: Numeric Functions-Footnote-3503931 +Node: String Functions504200 +Ref: String Functions-Footnote-1527664 +Ref: String Functions-Footnote-2527793 +Ref: String Functions-Footnote-3528041 +Node: Gory Details528128 +Ref: table-sub-escapes529909 +Ref: table-sub-proposed531429 +Ref: table-posix-sub532793 +Ref: table-gensub-escapes534333 +Ref: Gory Details-Footnote-1535165 +Node: I/O Functions535316 +Ref: I/O Functions-Footnote-1542417 +Node: Time Functions542564 +Ref: Time Functions-Footnote-1553033 +Ref: Time Functions-Footnote-2553101 +Ref: Time Functions-Footnote-3553259 +Ref: Time Functions-Footnote-4553370 +Ref: Time Functions-Footnote-5553482 +Ref: Time Functions-Footnote-6553709 +Node: Bitwise Functions553975 +Ref: table-bitwise-ops554537 +Ref: Bitwise Functions-Footnote-1558845 +Node: Type Functions559014 +Node: I18N Functions560163 +Node: User-defined561808 +Node: Definition Syntax562612 +Ref: Definition Syntax-Footnote-1568018 +Node: Function Example568087 +Ref: Function Example-Footnote-1571004 +Node: Function Caveats571026 +Node: Calling A Function571544 +Node: Variable Scope572499 +Node: Pass By Value/Reference575487 +Node: Return Statement578997 +Node: Dynamic Typing581981 +Node: Indirect Calls582910 +Ref: Indirect Calls-Footnote-1592631 +Node: Functions Summary592759 +Node: Library Functions595458 +Ref: Library Functions-Footnote-1599076 +Ref: Library Functions-Footnote-2599219 +Node: Library Names599390 +Ref: Library Names-Footnote-1602850 +Ref: Library Names-Footnote-2603070 +Node: General Functions603156 +Node: Strtonum Function604184 +Node: Assert Function607204 +Node: Round Function610528 +Node: Cliff Random Function612069 +Node: Ordinal Functions613085 +Ref: Ordinal Functions-Footnote-1616150 +Ref: Ordinal Functions-Footnote-2616402 +Node: Join Function616613 +Ref: Join Function-Footnote-1618384 +Node: Getlocaltime Function618584 +Node: Readfile Function622325 +Node: Data File Management624273 +Node: Filetrans Function624905 +Node: Rewind Function628964 +Node: File Checking630349 +Ref: File Checking-Footnote-1631677 +Node: Empty Files631878 +Node: Ignoring Assigns633857 +Node: Getopt Function635408 +Ref: Getopt Function-Footnote-1646868 +Node: Passwd Functions647071 +Ref: Passwd Functions-Footnote-1655922 +Node: Group Functions656010 +Ref: Group Functions-Footnote-1663913 +Node: Walking Arrays664126 +Node: Library Functions Summary665729 +Node: Library Exercises667130 +Node: Sample Programs668410 +Node: Running Examples669180 +Node: Clones669908 +Node: Cut Program671132 +Node: Egrep Program680862 +Ref: Egrep Program-Footnote-1688366 +Node: Id Program688476 +Node: Split Program692120 +Ref: Split Program-Footnote-1695566 +Node: Tee Program695694 +Node: Uniq Program698481 +Node: Wc Program705902 +Ref: Wc Program-Footnote-1710150 +Node: Miscellaneous Programs710242 +Node: Dupword Program711455 +Node: Alarm Program713486 +Node: Translate Program718290 +Ref: Translate Program-Footnote-1722863 +Ref: Translate Program-Footnote-2723133 +Node: Labels Program723272 +Ref: Labels Program-Footnote-1726621 +Node: Word Sorting726705 +Node: History Sorting730775 +Node: Extract Program732611 +Node: Simple Sed740143 +Node: Igawk Program743205 +Ref: Igawk Program-Footnote-1757531 +Ref: Igawk Program-Footnote-2757732 +Ref: Igawk Program-Footnote-3757854 +Node: Anagram Program757969 +Node: Signature Program761031 +Node: Programs Summary762278 +Node: Programs Exercises763471 +Ref: Programs Exercises-Footnote-1767602 +Node: Advanced Features767693 +Node: Nondecimal Data769641 +Node: Array Sorting771231 +Node: Controlling Array Traversal771928 +Ref: Controlling Array Traversal-Footnote-1780259 +Node: Array Sorting Functions780377 +Ref: Array Sorting Functions-Footnote-1784269 +Node: Two-way I/O784463 +Ref: Two-way I/O-Footnote-1789407 +Ref: Two-way I/O-Footnote-2789593 +Node: TCP/IP Networking789675 +Node: Profiling792552 +Node: Advanced Features Summary800105 +Node: Internationalization802038 +Node: I18N and L10N803518 +Node: Explaining gettext804204 +Ref: Explaining gettext-Footnote-1809233 +Ref: Explaining gettext-Footnote-2809417 +Node: Programmer i18n809582 +Ref: Programmer i18n-Footnote-1814448 +Node: Translator i18n814497 +Node: String Extraction815291 +Ref: String Extraction-Footnote-1816422 +Node: Printf Ordering816508 +Ref: Printf Ordering-Footnote-1819294 +Node: I18N Portability819358 +Ref: I18N Portability-Footnote-1821807 +Node: I18N Example821870 +Ref: I18N Example-Footnote-1824670 +Node: Gawk I18N824742 +Node: I18N Summary825380 +Node: Debugger826719 +Node: Debugging827741 +Node: Debugging Concepts828182 +Node: Debugging Terms830039 +Node: Awk Debugging832614 +Node: Sample Debugging Session833506 +Node: Debugger Invocation834026 +Node: Finding The Bug835410 +Node: List of Debugger Commands841885 +Node: Breakpoint Control843217 +Node: Debugger Execution Control846909 +Node: Viewing And Changing Data850273 +Node: Execution Stack853638 +Node: Debugger Info855276 +Node: Miscellaneous Debugger Commands859293 +Node: Readline Support864485 +Node: Limitations865377 +Node: Debugging Summary867474 +Node: Arbitrary Precision Arithmetic868642 +Node: Computer Arithmetic870058 +Ref: table-numeric-ranges873659 +Ref: Computer Arithmetic-Footnote-1874518 +Node: Math Definitions874575 +Ref: table-ieee-formats877862 +Ref: Math Definitions-Footnote-1878466 +Node: MPFR features878571 +Node: FP Math Caution880240 +Ref: FP Math Caution-Footnote-1881290 +Node: Inexactness of computations881659 +Node: Inexact representation882607 +Node: Comparing FP Values883962 +Node: Errors accumulate885035 +Node: Getting Accuracy886468 +Node: Try To Round889127 +Node: Setting precision890026 +Ref: table-predefined-precision-strings890710 +Node: Setting the rounding mode892504 +Ref: table-gawk-rounding-modes892868 +Ref: Setting the rounding mode-Footnote-1896322 +Node: Arbitrary Precision Integers896501 +Ref: Arbitrary Precision Integers-Footnote-1900284 +Node: POSIX Floating Point Problems900433 +Ref: POSIX Floating Point Problems-Footnote-1904309 +Node: Floating point summary904347 +Node: Dynamic Extensions906539 +Node: Extension Intro908091 +Node: Plugin License909357 +Node: Extension Mechanism Outline910154 +Ref: figure-load-extension910582 +Ref: figure-register-new-function912062 +Ref: figure-call-new-function913066 +Node: Extension API Description915052 +Node: Extension API Functions Introduction916502 +Node: General Data Types921338 +Ref: General Data Types-Footnote-1927025 +Node: Memory Allocation Functions927324 +Ref: Memory Allocation Functions-Footnote-1930154 +Node: Constructor Functions930250 +Node: Registration Functions931984 +Node: Extension Functions932669 +Node: Exit Callback Functions934965 +Node: Extension Version String936213 +Node: Input Parsers936863 +Node: Output Wrappers946678 +Node: Two-way processors951194 +Node: Printing Messages953398 +Ref: Printing Messages-Footnote-1954475 +Node: Updating `ERRNO'954627 +Node: Requesting Values955367 +Ref: table-value-types-returned956095 +Node: Accessing Parameters957053 +Node: Symbol Table Access958284 +Node: Symbol table by name958798 +Node: Symbol table by cookie960778 +Ref: Symbol table by cookie-Footnote-1964917 +Node: Cached values964980 +Ref: Cached values-Footnote-1968484 +Node: Array Manipulation968575 +Ref: Array Manipulation-Footnote-1969673 +Node: Array Data Types969712 +Ref: Array Data Types-Footnote-1972369 +Node: Array Functions972461 +Node: Flattening Arrays976315 +Node: Creating Arrays983202 +Node: Extension API Variables987969 +Node: Extension Versioning988605 +Node: Extension API Informational Variables990506 +Node: Extension API Boilerplate991594 +Node: Finding Extensions995410 +Node: Extension Example995970 +Node: Internal File Description996742 +Node: Internal File Ops1000809 +Ref: Internal File Ops-Footnote-11012467 +Node: Using Internal File Ops1012607 +Ref: Using Internal File Ops-Footnote-11014990 +Node: Extension Samples1015263 +Node: Extension Sample File Functions1016787 +Node: Extension Sample Fnmatch1024389 +Node: Extension Sample Fork1025871 +Node: Extension Sample Inplace1027084 +Node: Extension Sample Ord1028759 +Node: Extension Sample Readdir1029595 +Ref: table-readdir-file-types1030451 +Node: Extension Sample Revout1031262 +Node: Extension Sample Rev2way1031853 +Node: Extension Sample Read write array1032594 +Node: Extension Sample Readfile1034533 +Node: Extension Sample Time1035628 +Node: Extension Sample API Tests1036977 +Node: gawkextlib1037468 +Node: Extension summary1040118 +Node: Extension Exercises1043800 +Node: Language History1044522 +Node: V7/SVR3.11046179 +Node: SVR41048360 +Node: POSIX1049805 +Node: BTL1051194 +Node: POSIX/GNU1051928 +Node: Feature History1057557 +Node: Common Extensions1070648 +Node: Ranges and Locales1071972 +Ref: Ranges and Locales-Footnote-11076611 +Ref: Ranges and Locales-Footnote-21076638 +Ref: Ranges and Locales-Footnote-31076872 +Node: Contributors1077093 +Node: History summary1082633 +Node: Installation1084002 +Node: Gawk Distribution1084953 +Node: Getting1085437 +Node: Extracting1086261 +Node: Distribution contents1087903 +Node: Unix Installation1093673 +Node: Quick Installation1094290 +Node: Additional Configuration Options1096732 +Node: Configuration Philosophy1098470 +Node: Non-Unix Installation1100821 +Node: PC Installation1101279 +Node: PC Binary Installation1102590 +Node: PC Compiling1104438 +Ref: PC Compiling-Footnote-11107437 +Node: PC Testing1107542 +Node: PC Using1108718 +Node: Cygwin1112870 +Node: MSYS1113679 +Node: VMS Installation1114177 +Node: VMS Compilation1114973 +Ref: VMS Compilation-Footnote-11116195 +Node: VMS Dynamic Extensions1116253 +Node: VMS Installation Details1117626 +Node: VMS Running1119878 +Node: VMS GNV1122712 +Node: VMS Old Gawk1123435 +Node: Bugs1123905 +Node: Other Versions1127909 +Node: Installation summary1134133 +Node: Notes1135189 +Node: Compatibility Mode1136054 +Node: Additions1136836 +Node: Accessing The Source1137761 +Node: Adding Code1139197 +Node: New Ports1145369 +Node: Derived Files1149850 +Ref: Derived Files-Footnote-11155325 +Ref: Derived Files-Footnote-21155359 +Ref: Derived Files-Footnote-31155955 +Node: Future Extensions1156069 +Node: Implementation Limitations1156675 +Node: Extension Design1157923 +Node: Old Extension Problems1159077 +Ref: Old Extension Problems-Footnote-11160594 +Node: Extension New Mechanism Goals1160651 +Ref: Extension New Mechanism Goals-Footnote-11164011 +Node: Extension Other Design Decisions1164200 +Node: Extension Future Growth1166308 +Node: Old Extension Mechanism1167144 +Node: Notes summary1168906 +Node: Basic Concepts1170092 +Node: Basic High Level1170773 +Ref: figure-general-flow1171045 +Ref: figure-process-flow1171644 +Ref: Basic High Level-Footnote-11174873 +Node: Basic Data Typing1175058 +Node: Glossary1178386 +Node: Copying1203544 +Node: GNU Free Documentation License1241100 +Node: Index1266236 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index f7b04d7d..fd411745 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -708,7 +708,7 @@ particular records in a file and perform operations upon them. record. * Nextfile Statement:: Stop processing the current file. * Exit Statement:: Stop execution of @command{awk}. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * User-modified:: Built-in variables that you change to control @command{awk}. * Auto-set:: Built-in variables where @command{awk} @@ -906,7 +906,6 @@ particular records in a file and perform operations upon them. * Extension API Description:: A full description of the API. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @@ -919,6 +918,7 @@ particular records in a file and perform operations upon them. * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -957,9 +957,9 @@ particular records in a file and perform operations upon them. processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. * gawkextlib:: The @code{gawkextlib} project. * Extension summary:: Extension summary. * Extension Exercises:: Exercises. @@ -1570,7 +1570,7 @@ for getting most things done in a program. @ref{Patterns and Actions}, describes how to write patterns for matching records, actions for -doing something when a record is matched, and the built-in variables +doing something when a record is matched, and the predefined variables @command{awk} and @command{gawk} use. @ref{Arrays}, @@ -3656,8 +3656,8 @@ The @option{-v} option can only set one variable, but it can be used more than once, setting another variable each time, like this: @samp{awk @w{-v foo=1} @w{-v bar=2} @dots{}}. -@cindex built-in variables, @code{-v} option@comma{} setting with -@cindex variables, built-in, @code{-v} option@comma{} setting with +@cindex predefined variables, @code{-v} option@comma{} setting with +@cindex variables, predefined @code{-v} option@comma{} setting with @quotation CAUTION Using @option{-v} to set the values of the built-in variables may lead to surprising results. @command{awk} will reset the @@ -6142,7 +6142,7 @@ standard input (by default, this is the keyboard, but often it is a pipe from an command) or from files whose names you specify on the @command{awk} command line. If you specify input files, @command{awk} reads them in order, processing all the data from one before going on to the next. -The name of the current input file can be found in the built-in variable +The name of the current input file can be found in the predefined variable @code{FILENAME} (@pxref{Built-in Variables}). @@ -6190,9 +6190,9 @@ used with it do not have to be named on the @command{awk} command line @cindex @code{FNR} variable @command{awk} divides the input for your program into records and fields. It keeps track of the number of records that have been read so far from -the current input file. This value is stored in a built-in variable +the current input file. This value is stored in a predefined variable called @code{FNR} which is reset to zero every time a new file is started. -Another built-in variable, @code{NR}, records the total number of input +Another predefined variable, @code{NR}, records the total number of input records read so far from all @value{DF}s. It starts at zero, but is never automatically reset to zero. @@ -6210,7 +6210,7 @@ Records are separated by a character called the @dfn{record separator}. By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by -assigning the character to the built-in variable @code{RS}. +assigning the character to the predefined variable @code{RS}. @cindex newlines, as record separators @cindex @code{RS} variable @@ -6596,7 +6596,7 @@ field. @cindex @code{NF} variable @cindex fields, number of -@code{NF} is a built-in variable whose value is the number of fields +@code{NF} is a predefined variable whose value is the number of fields in the current record. @command{awk} automatically updates the value of @code{NF} each time it reads a record. No matter how many fields there are, the last field in a record can be represented by @code{$NF}. @@ -6954,7 +6954,7 @@ is split into three fields: @samp{m}, @samp{@bullet{}g}, and Note the leading spaces in the values of the second and third fields. @cindex troubleshooting, @command{awk} uses @code{FS} not @code{IFS} -The field separator is represented by the built-in variable @code{FS}. +The field separator is represented by the predefined variable @code{FS}. Shell programmers take note: @command{awk} does @emph{not} use the name @code{IFS} that is used by the POSIX-compliant shells (such as the Unix Bourne shell, @command{sh}, or Bash). @@ -7199,7 +7199,7 @@ an uppercase @samp{F} instead of a lowercase @samp{f}. The latter option (@option{-f}) specifies a file containing an @command{awk} program. The value used for the argument to @option{-F} is processed in exactly the -same way as assignments to the built-in variable @code{FS}. +same way as assignments to the predefined variable @code{FS}. Any special characters in the field separator must be escaped appropriately. For example, to use a @samp{\} as the field separator on the command line, you would have to type: @@ -8185,7 +8185,7 @@ from the file @var{file}, and put it in the variable @var{var}. As above, @var{file} is a string-valued expression that specifies the file from which to read. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}.@footnote{This is not quite true. @code{RT} could be changed if @code{RS} is a regular expression.} @@ -8347,7 +8347,7 @@ BEGIN @{ @} @end example -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. However, @code{RT} is set. @ifinfo @@ -8409,7 +8409,7 @@ When you use @samp{@var{command} |& getline @var{var}}, the output from the coprocess @var{command} is sent through a two-way pipe to @code{getline} and into the variable @var{var}. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}. However, @code{RT} is set. @@ -8512,9 +8512,9 @@ know that there is a string value to be assigned. @ref{table-getline-variants} summarizes the eight variants of @code{getline}, -listing which built-in variables are set by each one, +listing which predefined variables are set by each one, and whether the variant is standard or a @command{gawk} extension. -Note: for each variant, @command{gawk} sets the @code{RT} built-in variable. +Note: for each variant, @command{gawk} sets the @code{RT} predefined variable. @float Table,table-getline-variants @caption{@code{getline} Variants and What They Set} @@ -8974,7 +8974,7 @@ of items separated by commas. In the output, the items are normally separated by single spaces. However, this doesn't need to be the case; a single space is simply the default. Any string of characters may be used as the @dfn{output field separator} by setting the -built-in variable @code{OFS}. The initial value of this variable +predefined variable @code{OFS}. The initial value of this variable is the string @w{@code{" "}}---that is, a single space. The output from an entire @code{print} statement is called an @@ -9050,7 +9050,7 @@ more fully in @cindexawkfunc{sprintf} @cindex @code{OFMT} variable @cindex output, format specifier@comma{} @code{OFMT} -The built-in variable @code{OFMT} contains the format specification +The predefined variable @code{OFMT} contains the format specification that @code{print} uses with @code{sprintf()} when it wants to convert a number to a string for printing. The default value of @code{OFMT} is @code{"%.6g"}. @@ -10227,7 +10227,7 @@ retval = close(command) # syntax error in many Unix awks The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. -In these cases, @command{gawk} sets the built-in variable +In these cases, @command{gawk} sets the predefined variable @code{ERRNO} to a string describing the problem. In @command{gawk}, @@ -10283,7 +10283,7 @@ retval = close(command) # syntax error in many Unix awks The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. -In these cases, @command{gawk} sets the built-in variable +In these cases, @command{gawk} sets the predefined variable @code{ERRNO} to a string describing the problem. In @command{gawk}, @@ -10776,10 +10776,10 @@ array parameters. @xref{String Functions}. @cindex variables, initializing A few variables have special built-in meanings, such as @code{FS} (the field separator), and @code{NF} (the number of fields in the current input -record). @xref{Built-in Variables}, for a list of the built-in variables. -These built-in variables can be used and assigned just like all other +record). @xref{Built-in Variables}, for a list of the predefined variables. +These predefined variables can be used and assigned just like all other variables, but their values are also used or changed automatically by -@command{awk}. All built-in variables' names are entirely uppercase. +@command{awk}. All predefined variables' names are entirely uppercase. Variables in @command{awk} can be assigned either numeric or string values. The kind of value a variable holds can change over the life of a program. @@ -10905,7 +10905,7 @@ Strings that can't be interpreted as valid numbers convert to zero. @cindex @code{CONVFMT} variable The exact manner in which numbers are converted into strings is controlled -by the @command{awk} built-in variable @code{CONVFMT} (@pxref{Built-in Variables}). +by the @command{awk} predefined variable @code{CONVFMT} (@pxref{Built-in Variables}). Numbers are converted using the @code{sprintf()} function with @code{CONVFMT} as the format specifier @@ -12936,7 +12936,7 @@ program, and occasionally the format for data read as input. As you have already seen, each @command{awk} statement consists of a pattern with an associated action. This @value{CHAPTER} describes how you build patterns and actions, what kinds of things you can do within -actions, and @command{awk}'s built-in variables. +actions, and @command{awk}'s predefined variables. The pattern-action rules and the statements available for use within actions form the core of @command{awk} programming. @@ -12951,7 +12951,7 @@ building something useful. * Action Overview:: What goes into an action. * Statements:: Describes the various control statements in detail. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * Pattern Action Summary:: Patterns and Actions summary. @end menu @@ -14360,11 +14360,11 @@ results across different operating systems. @c ENDOFRANGE accs @node Built-in Variables -@section Built-in Variables +@section Predefined Variables @c STARTOFRANGE bvar -@cindex built-in variables +@cindex predefined variables @c STARTOFRANGE varb -@cindex variables, built-in +@cindex variables, predefined Most @command{awk} variables are available to use for your own purposes; they never change unless your program assigns values to @@ -14375,8 +14375,8 @@ to tell @command{awk} how to do certain things. Others are set automatically by @command{awk}, so that they carry information from the internal workings of @command{awk} to your program. -@cindex @command{gawk}, built-in variables and -This @value{SECTION} documents all of @command{gawk}'s built-in variables, +@cindex @command{gawk}, predefined variables and +This @value{SECTION} documents all of @command{gawk}'s predefined variables, most of which are also documented in the @value{CHAPTER}s describing their areas of activity. @@ -14391,7 +14391,7 @@ their areas of activity. @node User-modified @subsection Built-in Variables That Control @command{awk} @c STARTOFRANGE bvaru -@cindex built-in variables, user-modifiable +@cindex predefined variables, user-modifiable @c STARTOFRANGE nmbv @cindex user-modifiable variables @@ -14628,9 +14628,9 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}. @subsection Built-in Variables That Convey Information @c STARTOFRANGE bvconi -@cindex built-in variables, conveying information +@cindex predefined variables, conveying information @c STARTOFRANGE vbconi -@cindex variables, built-in, conveying information +@cindex variables, predefined conveying information The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide information to your program. @@ -15305,7 +15305,7 @@ immediately. You may pass an optional numeric value to be used as @command{awk}'s exit status. @item -Some built-in variables provide control over @command{awk}, mainly for I/O. +Some predefined variables provide control over @command{awk}, mainly for I/O. Other variables convey information from @command{awk} to your program. @item @@ -16099,7 +16099,7 @@ An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting (@pxref{Conversion}). -This means that the value of the built-in variable @code{CONVFMT} can +This means that the value of the predefined variable @code{CONVFMT} can affect how your program accesses elements of an array. For example: @example @@ -17283,8 +17283,8 @@ for @code{match()}, the order is the same as for the @samp{~} operator: @cindex @code{RSTART} variable, @code{match()} function and @cindex @code{RLENGTH} variable, @code{match()} function and @cindex @code{match()} function, @code{RSTART}/@code{RLENGTH} variables -The @code{match()} function sets the built-in variable @code{RSTART} to -the index. It also sets the built-in variable @code{RLENGTH} to the +The @code{match()} function sets the predefined variable @code{RSTART} to +the index. It also sets the predefined variable @code{RLENGTH} to the length in characters of the matched substring. If no match is found, @code{RSTART} is set to zero, and @code{RLENGTH} to @minus{}1. @@ -19273,7 +19273,7 @@ the call. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. In addition, according to the POSIX standard, function parameters -cannot have the same name as one of the special built-in variables +cannot have the same name as one of the special predefined variables (@pxref{Built-in Variables}). Not all versions of @command{awk} enforce this restriction. @@ -20521,7 +20521,7 @@ example, @code{getopt()}'s @code{Opterr} and @code{Optind} variables (@pxref{Getopt Function}). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is -not one of @command{awk}'s built-in variables, such as @code{FS}. +not one of @command{awk}'s predefined variables, such as @code{FS}. @cindex @option{--dump-variables} option, using for library functions It is also important that @emph{all} variables in library @@ -23435,7 +23435,7 @@ and the file transition library program The program begins with a descriptive comment and then a @code{BEGIN} rule that processes the command-line arguments with @code{getopt()}. The @option{-i} (ignore case) option is particularly easy with @command{gawk}; we just use the -@code{IGNORECASE} built-in variable +@code{IGNORECASE} predefined variable (@pxref{Built-in Variables}): @cindex @code{egrep.awk} program @@ -30287,7 +30287,7 @@ results. With the @option{-M} command-line option, all floating-point arithmetic operators and numeric functions can yield results to any desired precision level supported by MPFR. -Two built-in variables, @code{PREC} and @code{ROUNDMODE}, +Two predefined variables, @code{PREC} and @code{ROUNDMODE}, provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. @@ -30563,7 +30563,7 @@ $ @kbd{gawk -f pi2.awk} the precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the current working precision. The default working precision is 53 bits, which you can -modify using the built-in variable @code{PREC}. You can also set the +modify using the predefined variable @code{PREC}. You can also set the value to one of the predefined case-insensitive strings shown in @ref{table-predefined-precision-strings}, to emulate an IEEE 754 binary format. @@ -31264,13 +31264,13 @@ This (rather large) @value{SECTION} describes the API in detail. @menu * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -31289,6 +31289,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register: @itemize @value{MINUS} @item @@ -31321,9 +31324,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -32534,7 +32534,7 @@ Return false if the value cannot be retrieved. @item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value); Update the value associated with a scalar cookie. Return false if the new value is not of type @code{AWK_STRING} or @code{AWK_NUMBER}. -Here too, the built-in variables may not be updated. +Here too, the predefined variables may not be updated. @end table It is not obvious at first glance how to work with scalar cookies or @@ -33399,7 +33399,7 @@ This variable is true if @command{gawk} was invoked with @option{--traditional} @end table The value of @code{do_lint} can change if @command{awk} code -modifies the @code{LINT} built-in variable (@pxref{Built-in Variables}). +modifies the @code{LINT} predefined variable (@pxref{Built-in Variables}). The others should not change during execution. @node Extension API Boilerplate @@ -33974,7 +33974,16 @@ for success: @} @end example -Finally, here is the @code{do_stat()} function. It starts with +The third argument to @code{stat()} was not discussed previously. This +argument is optional. If present, it causes @code{do_stat()} to use +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. + +Here is the @code{do_stat()} function. It starts with variable declarations and argument checking: @ignore @@ -34005,16 +34014,10 @@ do_stat(int nargs, awk_value_t *result) @} @end example -The third argument to @code{stat()} was not discussed previously. This argument -is optional. If present, it causes @code{stat()} to use the @code{stat()} -system call instead of the @code{lstat()} system call. - Then comes the actual work. First, the function gets the arguments. -Next, it gets the information for the file. -The code use @code{lstat()} (instead of @code{stat()}) -to get the file information, -in case the file is a symbolic link. -If there's an error, it sets @code{ERRNO} and returns: +Next, it gets the information for the file. If the called function +(@code{lstat()} or @code{stat()}) returns an error, the code sets +@code{ERRNO} and returns: @example /* file is first arg, array to hold results is second */ @@ -34043,7 +34046,7 @@ If there's an error, it sets @code{ERRNO} and returns: @end example The tedious work is done by @code{fill_stat_array()}, shown -earlier. When done, return the result from @code{fill_stat_array()}: +earlier. When done, the function returns the result from @code{fill_stat_array()}: @example ret = fill_stat_array(name, array, & sbuf); @@ -34106,7 +34109,7 @@ of the @file{gawkapi.h} header file, the following steps@footnote{In practice, you would probably want to use the GNU Autotools---Automake, Autoconf, Libtool, and @command{gettext}---to configure and build your libraries. Instructions for doing so are beyond -the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for WWW links to +the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to the tools.} create a GNU/Linux shared library: @example @@ -34134,14 +34137,14 @@ BEGIN @{ for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) + strftime("%m %d %Y %H:%M:%S", data["mtime"]) print "\nInfo for JUNK" ret = stat("JUNK", data) print "ret =", ret for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + print "JUNK modified:", strftime("%m %d %Y %H:%M:%S", data["mtime"]) @} @end example @@ -34155,25 +34158,26 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @print{} Info for testff.awk @print{} ret = 0 @print{} data["blksize"] = 4096 -@print{} data["mtime"] = 1350838628 +@print{} data["devbsize"] = 512 +@print{} data["mtime"] = 1412004710 @print{} data["mode"] = 33204 @print{} data["type"] = file @print{} data["dev"] = 2053 @print{} data["gid"] = 1000 -@print{} data["ino"] = 1719496 -@print{} data["ctime"] = 1350838628 +@print{} data["ino"] = 10358899 +@print{} data["ctime"] = 1412004710 @print{} data["blocks"] = 8 @print{} data["nlink"] = 1 @print{} data["name"] = testff.awk -@print{} data["atime"] = 1350838632 +@print{} data["atime"] = 1412004716 @print{} data["pmode"] = -rw-rw-r-- -@print{} data["size"] = 662 +@print{} data["size"] = 666 @print{} data["uid"] = 1000 -@print{} testff.awk modified: 10 21 12 18:57:08 -@print{} +@print{} testff.awk modified: 09 29 2014 18:31:50 +@print{} @print{} Info for JUNK @print{} ret = -1 -@print{} JUNK modified: 01 01 70 02:00:00 +@print{} JUNK modified: 01 01 1970 02:00:00 @end example @node Extension Samples @@ -34198,9 +34202,9 @@ Others mainly provide example code that shows how to use the extension API. * Extension Sample Rev2way:: Reversing data sample two-way processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. @end menu @node Extension Sample File Functions @@ -34210,7 +34214,7 @@ The @code{filefuncs} extension provides three different functions, as follows: The usage is: @table @asis -@item @@load "filefuncs" +@item @code{@@load "filefuncs"} This is how you load the extension. @cindex @code{chdir()} extension function @@ -34273,7 +34277,7 @@ Not all systems support all file types. @tab All @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the @code{filedata} array as described below. @code{flags} is the bitwise -OR of several predefined constant values, also described below. +OR of several predefined values, also described below. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -34318,10 +34322,10 @@ Immediately follow a symbolic link named in @code{pathlist}, whether or not @code{FTS_LOGICAL} is set. @item FTS_SEEDOT -By default, the @code{fts()} routines do not return entries for @file{.} (dot) -and @file{..} (dot-dot). This option causes entries for dot-dot to also -be included. (The extension always includes an entry for dot, -see below.) +By default, the C library @code{fts()} routines do not return entries for +@file{.} (dot) and @file{..} (dot-dot). This option causes entries for +dot-dot to also be included. (The extension always includes an entry +for dot, see below.) @item FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. @@ -34375,8 +34379,8 @@ Otherwise it returns @minus{}1. @quotation NOTE The @code{fts()} extension does not exactly mimic the interface of the C library @code{fts()} routines, choosing instead to -provide an interface that is based on associative arrays, which should -be more comfortable to use from an @command{awk} program. This includes the +provide an interface that is based on associative arrays, which is +more comfortable to use from an @command{awk} program. This includes the lack of a comparison function, since @command{gawk} already provides powerful array sorting facilities. While an @code{fts_read()}-like interface could have been provided, this felt less natural than simply @@ -34384,7 +34388,8 @@ creating a multidimensional array to represent the file hierarchy and its information. @end quotation -See @file{test/fts.awk} in the @command{gawk} distribution for an example. +See @file{test/fts.awk} in the @command{gawk} distribution for an example +use of the @code{fts()} extension function. @node Extension Sample Fnmatch @subsection Interface To @code{fnmatch()} @@ -34592,7 +34597,7 @@ indicating the type of the file. The letters are file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types -@caption{File Types Returned By @code{readdir()}} +@caption{File Types Returned By The @code{readdir} Extension} @multitable @columnfractions .1 .9 @headitem Letter @tab File Type @item @code{b} @tab Block device @@ -34684,6 +34689,9 @@ The @code{rwarray} extension adds two functions, named @code{writea()} and @code{reada()}, as follows: @table @code +@item @@load "rwarray" +This is how you load the extension. + @cindex @code{writea()} extension function @item ret = writea(file, array) This function takes a string argument, which is the name of the file @@ -34759,17 +34767,6 @@ if (contents == "" && ERRNO != "") @{ @} @end example -@node Extension Sample API Tests -@subsection API Tests -@cindex @code{testext} extension - -The @code{testext} extension exercises parts of the extension API that -are not tested by the other samples. The @file{extension/testext.c} -file contains both the C code for the extension and @command{awk} -test code inside C comments that run the tests. The testing framework -extracts the @command{awk} code and runs the tests. See the source file -for more information. - @node Extension Sample Time @subsection Extension Time Functions @@ -34800,6 +34797,17 @@ Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table +@node Extension Sample API Tests +@subsection API Tests +@cindex @code{testext} extension + +The @code{testext} extension exercises parts of the extension API that +are not tested by the other samples. The @file{extension/testext.c} +file contains both the C code for the extension and @command{awk} +test code inside C comments that run the tests. The testing framework +extracts the @command{awk} code and runs the tests. See the source file +for more information. + @node gawkextlib @section The @code{gawkextlib} Project @cindex @code{gawkextlib} @@ -34815,8 +34823,7 @@ As of this writing, there are five extensions: @itemize @value{BULLET} @item -XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} -XML parsing library. +GD graphics library extension. @item PDF extension. @@ -34825,17 +34832,14 @@ PDF extension. PostgreSQL extension. @item -GD graphics library extension. - -@item MPFR library extension. This provides access to a number of MPFR functions which @command{gawk}'s native MPFR support does not. -@end itemize -The @code{time} extension described earlier (@pxref{Extension Sample -Time}) was originally from this project but has been moved in to the -main @command{gawk} distribution. +@item +XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} +XML parsing library. +@end itemize @cindex @command{git} utility You can check out the code for the @code{gawkextlib} project @@ -34926,6 +34930,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register extension functions, exit callbacks, @@ -34949,9 +34956,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -34983,7 +34987,7 @@ treated as read-only by the extension. @item @emph{All} memory passed from an extension to @command{gawk} must come from the API's memory allocation functions. @command{gawk} takes responsibility for -the memory and will release it when appropriate. +the memory and releases it when appropriate. @item The API provides information about the running version of @command{gawk} so @@ -35000,7 +35004,7 @@ 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 to the community of @command{gawk} users, the @code{gawkextlib} project -should be the place to do so. +is the place to do so. @end itemize @@ -35082,7 +35086,7 @@ which follows the POSIX specification. Many long-time @command{awk} users learned @command{awk} programming with the original @command{awk} implementation in Version 7 Unix. (This implementation was the basis for @command{awk} in Berkeley Unix, through 4.3-Reno. Subsequent versions -of Berkeley Unix, and some systems derived from 4.4BSD-Lite, used various +of Berkeley Unix, and, for a while, some systems derived from 4.4BSD-Lite, used various versions of @command{gawk} for their @command{awk}.) This @value{CHAPTER} briefly describes the evolution of the @command{awk} language, with cross-references to other parts of the @value{DOCUMENT} where you can @@ -35155,7 +35159,7 @@ The built-in functions @code{close()} and @code{system()} @item The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART}, -and @code{SUBSEP} built-in variables (@pxref{Built-in Variables}). +and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}). @item Assignable @code{$0} (@pxref{Changing Fields}). @@ -35186,14 +35190,11 @@ of @code{FS}. @item Dynamic regexps as operands of the @samp{~} and @samp{!~} operators -(@pxref{Regexp Usage}). +(@pxref{Computed Regexps}). @item The escape sequences @samp{\b}, @samp{\f}, and @samp{\r} (@pxref{Escape Sequences}). -(Some vendors have updated their old versions of @command{awk} to -recognize @samp{\b}, @samp{\f}, and @samp{\r}, but this is not -something you can rely on.) @item Redirection of input for the @code{getline} function @@ -35232,7 +35233,7 @@ The @option{-v} option for assigning variables before program execution begins @c GNU, Bell Laboratories & MKS together @item -The @option{--} option for terminating command-line options. +The @option{--} signal for terminating command-line options. @item The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences @@ -35255,7 +35256,7 @@ A cleaner specification for the @code{%c} format-control letter in the @item The ability to dynamically pass the field width and precision (@code{"%*.*d"}) -in the argument list of the @code{printf} function +in the argument list of @code{printf} and @code{sprintf()} (@pxref{Control Letters}). @item @@ -35290,8 +35291,8 @@ The concept of a numeric string and tighter comparison rules to go with it (@pxref{Typing and Comparison}). @item -The use of built-in variables as function parameter names is forbidden -(@pxref{Definition Syntax}. +The use of predefined variables as function parameter names is forbidden +(@pxref{Definition Syntax}). @item More complete documentation of many of the previously undocumented @@ -35386,7 +35387,7 @@ in the current version of @command{gawk}. @itemize @value{BULLET} @item -Additional built-in variables: +Additional predefined variables: @itemize @value{MINUS} @item @@ -35470,14 +35471,6 @@ The @code{BEGINFILE} and @code{ENDFILE} special patterns. (@pxref{BEGINFILE/ENDFILE}). @item -The ability to delete all of an array at once with @samp{delete @var{array}} -(@pxref{Delete}). - -@item -The @code{nextfile} statement -(@pxref{Nextfile Statement}). - -@item The @code{switch} statement (@pxref{Switch Statement}). @end itemize @@ -35492,7 +35485,7 @@ of a two-way pipe to a coprocess (@pxref{Two-way I/O}). @item -POSIX compliance for @code{gsub()} and @code{sub()}. +POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix}. @item The @code{length()} function accepts an array argument @@ -35520,6 +35513,20 @@ Additional functions only in @command{gawk}: @itemize @value{MINUS} @item +The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions +for more powerful text manipulation +(@pxref{String Functions}). + +@item +The @code{asort()} and @code{asorti()} functions for sorting arrays +(@pxref{Array Sorting}). + +@item +The @code{mktime()}, @code{systime()}, and @code{strftime()} +functions for working with timestamps +(@pxref{Time Functions}). + +@item The @code{and()}, @code{compl()}, @@ -35533,30 +35540,15 @@ functions for bit manipulation @c In 4.1, and(), or() and xor() grew the ability to take > 2 arguments @item -The @code{asort()} and @code{asorti()} functions for sorting arrays -(@pxref{Array Sorting}). +The @code{isarray()} function to check if a variable is an array or not +(@pxref{Type Functions}). @item The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()} functions for internationalization (@pxref{Programmer i18n}). - -@item -The @code{fflush()} function from BWK @command{awk} -(@pxref{I/O Functions}). - -@item -The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions -for more powerful text manipulation -(@pxref{String Functions}). - -@item -The @code{mktime()}, @code{systime()}, and @code{strftime()} -functions for working with timestamps -(@pxref{Time Functions}). @end itemize - @item Changes and/or additions in the command-line options: @@ -35679,7 +35671,7 @@ GCC for VAX and Alpha has not been tested for a while. @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} @value{PVERSION} 4.1: +for @command{gawk} @value{PVERSION} 4.1: @c nested table @itemize @value{MINUS} @@ -36316,33 +36308,29 @@ The dynamic extension interface was completely redone @cindex extensions, Brian Kernighan's @command{awk} @cindex extensions, @command{mawk} -This @value{SECTION} summarizes the common extensions supported +The following table summarizes the common extensions supported by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk}, the three most widely-used freely available versions of @command{awk} (@pxref{Other Versions}). -@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} -@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk -@item @samp{\x} Escape sequence @tab X @tab X @tab X -@item @code{FS} as null string @tab X @tab X @tab X -@item @file{/dev/stdin} special file @tab X @tab X @tab X -@item @file{/dev/stdout} special file @tab X @tab X @tab X -@item @file{/dev/stderr} special file @tab X @tab X @tab X -@item @code{delete} without subscript @tab X @tab X @tab X -@item @code{fflush()} function @tab X @tab X @tab X -@item @code{length()} of an array @tab X @tab X @tab X -@item @code{nextfile} statement @tab X @tab X @tab X -@item @code{**} and @code{**=} operators @tab X @tab @tab X -@item @code{func} keyword @tab X @tab @tab X -@item @code{BINMODE} variable @tab @tab X @tab X -@item @code{RS} as regexp @tab @tab X @tab X -@item Time related functions @tab @tab X @tab X +@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} +@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @tab Now standard +@item @samp{\x} Escape sequence @tab X @tab X @tab X @tab +@item @code{FS} as null string @tab X @tab X @tab X @tab +@item @file{/dev/stdin} special file @tab X @tab X @tab X @tab +@item @file{/dev/stdout} special file @tab X @tab X @tab X @tab +@item @file{/dev/stderr} special file @tab X @tab X @tab X @tab +@item @code{delete} without subscript @tab X @tab X @tab X @tab X +@item @code{fflush()} function @tab X @tab X @tab X @tab X +@item @code{length()} of an array @tab X @tab X @tab X @tab +@item @code{nextfile} statement @tab X @tab X @tab X @tab X +@item @code{**} and @code{**=} operators @tab X @tab @tab X @tab +@item @code{func} keyword @tab X @tab @tab X @tab +@item @code{BINMODE} variable @tab @tab X @tab X @tab +@item @code{RS} as regexp @tab @tab X @tab X @tab +@item Time related functions @tab @tab X @tab X @tab @end multitable -(Technically speaking, as of late 2012, @code{fflush()}, @samp{delete @var{array}}, -and @code{nextfile} are no longer extensions, since they have been added -to POSIX.) - @node Ranges and Locales @appendixsec Regexp Ranges and Locales: A Long Sad Story @@ -36379,6 +36367,7 @@ In the @code{"C"} and @code{"POSIX"} locales, a range expression like But outside those locales, the ordering was defined to be based on @dfn{collation order}. +What does that mean? In many locales, @samp{A} and @samp{a} are both less than @samp{B}. In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; @@ -36386,7 +36375,7 @@ instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. This point needs to be emphasized: Much literature teaches that you should use @samp{[a-z]} to match a lowercase character. But on systems with -non-ASCII locales, this also matched all of the uppercase characters +non-ASCII locales, this also matches all of the uppercase characters except @samp{A} or @samp{Z}! This was a continuous cause of confusion, even well into the twenty-first century. @@ -36692,6 +36681,11 @@ The development of the extension API first released with Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. +@cindex Malmberg, John E. +@item +John Malmberg contributed significant improvements to the +OpenVMS port and the related documentation. + @item @cindex Colombo, Antonio Antonio Giovanni Colombo rewrote a number of examples in the early @@ -39215,7 +39209,7 @@ Pat Rankin suggested the solution that was adopted. @appendixsubsec Other Design Decisions As an arbitrary design decision, extensions can read the values of -built-in variables and arrays (such as @code{ARGV} and @code{FS}), but cannot +predefined variables and arrays (such as @code{ARGV} and @code{FS}), but cannot change them, with the exception of @code{PROCINFO}. The reason for this is to prevent an extension function from affecting @@ -39956,11 +39950,11 @@ See ``Free Documentation License.'' @item Field When @command{awk} reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can -change by setting the built-in variable @code{FS}). Such pieces are +change by setting the predefined variable @code{FS}). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable @code{FIELDWIDTHS} to describe their lengths. If you wish to specify the contents of fields instead of the field -separator, you can use the built-in variable @code{FPAT} to do so. +separator, you can use the predefined variable @code{FPAT} to do so. (@xref{Field Separators}, @ref{Constant Size}, and @@ -39979,7 +39973,7 @@ See also ``Double Precision'' and ``Single Precision.'' Format strings control the appearance of output in the @code{strftime()} and @code{sprintf()} functions, and in the @code{printf} statement as well. Also, data conversions from numbers to strings -are controlled by the format strings contained in the built-in variables +are controlled by the format strings contained in the predefined variables @code{CONVFMT} and @code{OFMT}. (@xref{Control Letters}.) @item Free Documentation License diff --git a/doc/gawktexi.in b/doc/gawktexi.in index b42d7f7b..eb9bb0d4 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -703,7 +703,7 @@ particular records in a file and perform operations upon them. record. * Nextfile Statement:: Stop processing the current file. * Exit Statement:: Stop execution of @command{awk}. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * User-modified:: Built-in variables that you change to control @command{awk}. * Auto-set:: Built-in variables where @command{awk} @@ -901,7 +901,6 @@ particular records in a file and perform operations upon them. * Extension API Description:: A full description of the API. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @@ -914,6 +913,7 @@ particular records in a file and perform operations upon them. * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -952,9 +952,9 @@ particular records in a file and perform operations upon them. processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. * gawkextlib:: The @code{gawkextlib} project. * Extension summary:: Extension summary. * Extension Exercises:: Exercises. @@ -1537,7 +1537,7 @@ for getting most things done in a program. @ref{Patterns and Actions}, describes how to write patterns for matching records, actions for -doing something when a record is matched, and the built-in variables +doing something when a record is matched, and the predefined variables @command{awk} and @command{gawk} use. @ref{Arrays}, @@ -3567,8 +3567,8 @@ The @option{-v} option can only set one variable, but it can be used more than once, setting another variable each time, like this: @samp{awk @w{-v foo=1} @w{-v bar=2} @dots{}}. -@cindex built-in variables, @code{-v} option@comma{} setting with -@cindex variables, built-in, @code{-v} option@comma{} setting with +@cindex predefined variables, @code{-v} option@comma{} setting with +@cindex variables, predefined @code{-v} option@comma{} setting with @quotation CAUTION Using @option{-v} to set the values of the built-in variables may lead to surprising results. @command{awk} will reset the @@ -5926,7 +5926,7 @@ standard input (by default, this is the keyboard, but often it is a pipe from an command) or from files whose names you specify on the @command{awk} command line. If you specify input files, @command{awk} reads them in order, processing all the data from one before going on to the next. -The name of the current input file can be found in the built-in variable +The name of the current input file can be found in the predefined variable @code{FILENAME} (@pxref{Built-in Variables}). @@ -5974,9 +5974,9 @@ used with it do not have to be named on the @command{awk} command line @cindex @code{FNR} variable @command{awk} divides the input for your program into records and fields. It keeps track of the number of records that have been read so far from -the current input file. This value is stored in a built-in variable +the current input file. This value is stored in a predefined variable called @code{FNR} which is reset to zero every time a new file is started. -Another built-in variable, @code{NR}, records the total number of input +Another predefined variable, @code{NR}, records the total number of input records read so far from all @value{DF}s. It starts at zero, but is never automatically reset to zero. @@ -5994,7 +5994,7 @@ Records are separated by a character called the @dfn{record separator}. By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by -assigning the character to the built-in variable @code{RS}. +assigning the character to the predefined variable @code{RS}. @cindex newlines, as record separators @cindex @code{RS} variable @@ -6323,7 +6323,7 @@ field. @cindex @code{NF} variable @cindex fields, number of -@code{NF} is a built-in variable whose value is the number of fields +@code{NF} is a predefined variable whose value is the number of fields in the current record. @command{awk} automatically updates the value of @code{NF} each time it reads a record. No matter how many fields there are, the last field in a record can be represented by @code{$NF}. @@ -6650,7 +6650,7 @@ is split into three fields: @samp{m}, @samp{@bullet{}g}, and Note the leading spaces in the values of the second and third fields. @cindex troubleshooting, @command{awk} uses @code{FS} not @code{IFS} -The field separator is represented by the built-in variable @code{FS}. +The field separator is represented by the predefined variable @code{FS}. Shell programmers take note: @command{awk} does @emph{not} use the name @code{IFS} that is used by the POSIX-compliant shells (such as the Unix Bourne shell, @command{sh}, or Bash). @@ -6895,7 +6895,7 @@ an uppercase @samp{F} instead of a lowercase @samp{f}. The latter option (@option{-f}) specifies a file containing an @command{awk} program. The value used for the argument to @option{-F} is processed in exactly the -same way as assignments to the built-in variable @code{FS}. +same way as assignments to the predefined variable @code{FS}. Any special characters in the field separator must be escaped appropriately. For example, to use a @samp{\} as the field separator on the command line, you would have to type: @@ -7786,7 +7786,7 @@ from the file @var{file}, and put it in the variable @var{var}. As above, @var{file} is a string-valued expression that specifies the file from which to read. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}.@footnote{This is not quite true. @code{RT} could be changed if @code{RS} is a regular expression.} @@ -7948,7 +7948,7 @@ BEGIN @{ @} @end example -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. However, @code{RT} is set. @ifinfo @@ -8010,7 +8010,7 @@ When you use @samp{@var{command} |& getline @var{var}}, the output from the coprocess @var{command} is sent through a two-way pipe to @code{getline} and into the variable @var{var}. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}. However, @code{RT} is set. @@ -8113,9 +8113,9 @@ know that there is a string value to be assigned. @ref{table-getline-variants} summarizes the eight variants of @code{getline}, -listing which built-in variables are set by each one, +listing which predefined variables are set by each one, and whether the variant is standard or a @command{gawk} extension. -Note: for each variant, @command{gawk} sets the @code{RT} built-in variable. +Note: for each variant, @command{gawk} sets the @code{RT} predefined variable. @float Table,table-getline-variants @caption{@code{getline} Variants and What They Set} @@ -8575,7 +8575,7 @@ of items separated by commas. In the output, the items are normally separated by single spaces. However, this doesn't need to be the case; a single space is simply the default. Any string of characters may be used as the @dfn{output field separator} by setting the -built-in variable @code{OFS}. The initial value of this variable +predefined variable @code{OFS}. The initial value of this variable is the string @w{@code{" "}}---that is, a single space. The output from an entire @code{print} statement is called an @@ -8651,7 +8651,7 @@ more fully in @cindexawkfunc{sprintf} @cindex @code{OFMT} variable @cindex output, format specifier@comma{} @code{OFMT} -The built-in variable @code{OFMT} contains the format specification +The predefined variable @code{OFMT} contains the format specification that @code{print} uses with @code{sprintf()} when it wants to convert a number to a string for printing. The default value of @code{OFMT} is @code{"%.6g"}. @@ -9785,7 +9785,7 @@ retval = close(command) # syntax error in many Unix awks The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. -In these cases, @command{gawk} sets the built-in variable +In these cases, @command{gawk} sets the predefined variable @code{ERRNO} to a string describing the problem. In @command{gawk}, @@ -10248,10 +10248,10 @@ array parameters. @xref{String Functions}. @cindex variables, initializing A few variables have special built-in meanings, such as @code{FS} (the field separator), and @code{NF} (the number of fields in the current input -record). @xref{Built-in Variables}, for a list of the built-in variables. -These built-in variables can be used and assigned just like all other +record). @xref{Built-in Variables}, for a list of the predefined variables. +These predefined variables can be used and assigned just like all other variables, but their values are also used or changed automatically by -@command{awk}. All built-in variables' names are entirely uppercase. +@command{awk}. All predefined variables' names are entirely uppercase. Variables in @command{awk} can be assigned either numeric or string values. The kind of value a variable holds can change over the life of a program. @@ -10377,7 +10377,7 @@ Strings that can't be interpreted as valid numbers convert to zero. @cindex @code{CONVFMT} variable The exact manner in which numbers are converted into strings is controlled -by the @command{awk} built-in variable @code{CONVFMT} (@pxref{Built-in Variables}). +by the @command{awk} predefined variable @code{CONVFMT} (@pxref{Built-in Variables}). Numbers are converted using the @code{sprintf()} function with @code{CONVFMT} as the format specifier @@ -12269,7 +12269,7 @@ program, and occasionally the format for data read as input. As you have already seen, each @command{awk} statement consists of a pattern with an associated action. This @value{CHAPTER} describes how you build patterns and actions, what kinds of things you can do within -actions, and @command{awk}'s built-in variables. +actions, and @command{awk}'s predefined variables. The pattern-action rules and the statements available for use within actions form the core of @command{awk} programming. @@ -12284,7 +12284,7 @@ building something useful. * Action Overview:: What goes into an action. * Statements:: Describes the various control statements in detail. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * Pattern Action Summary:: Patterns and Actions summary. @end menu @@ -13693,11 +13693,11 @@ results across different operating systems. @c ENDOFRANGE accs @node Built-in Variables -@section Built-in Variables +@section Predefined Variables @c STARTOFRANGE bvar -@cindex built-in variables +@cindex predefined variables @c STARTOFRANGE varb -@cindex variables, built-in +@cindex variables, predefined Most @command{awk} variables are available to use for your own purposes; they never change unless your program assigns values to @@ -13708,8 +13708,8 @@ to tell @command{awk} how to do certain things. Others are set automatically by @command{awk}, so that they carry information from the internal workings of @command{awk} to your program. -@cindex @command{gawk}, built-in variables and -This @value{SECTION} documents all of @command{gawk}'s built-in variables, +@cindex @command{gawk}, predefined variables and +This @value{SECTION} documents all of @command{gawk}'s predefined variables, most of which are also documented in the @value{CHAPTER}s describing their areas of activity. @@ -13724,7 +13724,7 @@ their areas of activity. @node User-modified @subsection Built-in Variables That Control @command{awk} @c STARTOFRANGE bvaru -@cindex built-in variables, user-modifiable +@cindex predefined variables, user-modifiable @c STARTOFRANGE nmbv @cindex user-modifiable variables @@ -13961,9 +13961,9 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}. @subsection Built-in Variables That Convey Information @c STARTOFRANGE bvconi -@cindex built-in variables, conveying information +@cindex predefined variables, conveying information @c STARTOFRANGE vbconi -@cindex variables, built-in, conveying information +@cindex variables, predefined conveying information The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide information to your program. @@ -14592,7 +14592,7 @@ immediately. You may pass an optional numeric value to be used as @command{awk}'s exit status. @item -Some built-in variables provide control over @command{awk}, mainly for I/O. +Some predefined variables provide control over @command{awk}, mainly for I/O. Other variables convey information from @command{awk} to your program. @item @@ -15386,7 +15386,7 @@ An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting (@pxref{Conversion}). -This means that the value of the built-in variable @code{CONVFMT} can +This means that the value of the predefined variable @code{CONVFMT} can affect how your program accesses elements of an array. For example: @example @@ -16570,8 +16570,8 @@ for @code{match()}, the order is the same as for the @samp{~} operator: @cindex @code{RSTART} variable, @code{match()} function and @cindex @code{RLENGTH} variable, @code{match()} function and @cindex @code{match()} function, @code{RSTART}/@code{RLENGTH} variables -The @code{match()} function sets the built-in variable @code{RSTART} to -the index. It also sets the built-in variable @code{RLENGTH} to the +The @code{match()} function sets the predefined variable @code{RSTART} to +the index. It also sets the predefined variable @code{RLENGTH} to the length in characters of the matched substring. If no match is found, @code{RSTART} is set to zero, and @code{RLENGTH} to @minus{}1. @@ -18399,7 +18399,7 @@ the call. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. In addition, according to the POSIX standard, function parameters -cannot have the same name as one of the special built-in variables +cannot have the same name as one of the special predefined variables (@pxref{Built-in Variables}). Not all versions of @command{awk} enforce this restriction. @@ -19647,7 +19647,7 @@ example, @code{getopt()}'s @code{Opterr} and @code{Optind} variables (@pxref{Getopt Function}). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is -not one of @command{awk}'s built-in variables, such as @code{FS}. +not one of @command{awk}'s predefined variables, such as @code{FS}. @cindex @option{--dump-variables} option, using for library functions It is also important that @emph{all} variables in library @@ -22532,7 +22532,7 @@ and the file transition library program The program begins with a descriptive comment and then a @code{BEGIN} rule that processes the command-line arguments with @code{getopt()}. The @option{-i} (ignore case) option is particularly easy with @command{gawk}; we just use the -@code{IGNORECASE} built-in variable +@code{IGNORECASE} predefined variable (@pxref{Built-in Variables}): @cindex @code{egrep.awk} program @@ -29384,7 +29384,7 @@ results. With the @option{-M} command-line option, all floating-point arithmetic operators and numeric functions can yield results to any desired precision level supported by MPFR. -Two built-in variables, @code{PREC} and @code{ROUNDMODE}, +Two predefined variables, @code{PREC} and @code{ROUNDMODE}, provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. @@ -29660,7 +29660,7 @@ $ @kbd{gawk -f pi2.awk} the precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the current working precision. The default working precision is 53 bits, which you can -modify using the built-in variable @code{PREC}. You can also set the +modify using the predefined variable @code{PREC}. You can also set the value to one of the predefined case-insensitive strings shown in @ref{table-predefined-precision-strings}, to emulate an IEEE 754 binary format. @@ -30361,13 +30361,13 @@ This (rather large) @value{SECTION} describes the API in detail. @menu * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -30386,6 +30386,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register: @itemize @value{MINUS} @item @@ -30418,9 +30421,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -31631,7 +31631,7 @@ Return false if the value cannot be retrieved. @item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value); Update the value associated with a scalar cookie. Return false if the new value is not of type @code{AWK_STRING} or @code{AWK_NUMBER}. -Here too, the built-in variables may not be updated. +Here too, the predefined variables may not be updated. @end table It is not obvious at first glance how to work with scalar cookies or @@ -32496,7 +32496,7 @@ This variable is true if @command{gawk} was invoked with @option{--traditional} @end table The value of @code{do_lint} can change if @command{awk} code -modifies the @code{LINT} built-in variable (@pxref{Built-in Variables}). +modifies the @code{LINT} predefined variable (@pxref{Built-in Variables}). The others should not change during execution. @node Extension API Boilerplate @@ -33071,7 +33071,16 @@ for success: @} @end example -Finally, here is the @code{do_stat()} function. It starts with +The third argument to @code{stat()} was not discussed previously. This +argument is optional. If present, it causes @code{do_stat()} to use +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. + +Here is the @code{do_stat()} function. It starts with variable declarations and argument checking: @ignore @@ -33102,16 +33111,10 @@ do_stat(int nargs, awk_value_t *result) @} @end example -The third argument to @code{stat()} was not discussed previously. This argument -is optional. If present, it causes @code{stat()} to use the @code{stat()} -system call instead of the @code{lstat()} system call. - Then comes the actual work. First, the function gets the arguments. -Next, it gets the information for the file. -The code use @code{lstat()} (instead of @code{stat()}) -to get the file information, -in case the file is a symbolic link. -If there's an error, it sets @code{ERRNO} and returns: +Next, it gets the information for the file. If the called function +(@code{lstat()} or @code{stat()}) returns an error, the code sets +@code{ERRNO} and returns: @example /* file is first arg, array to hold results is second */ @@ -33140,7 +33143,7 @@ If there's an error, it sets @code{ERRNO} and returns: @end example The tedious work is done by @code{fill_stat_array()}, shown -earlier. When done, return the result from @code{fill_stat_array()}: +earlier. When done, the function returns the result from @code{fill_stat_array()}: @example ret = fill_stat_array(name, array, & sbuf); @@ -33203,7 +33206,7 @@ of the @file{gawkapi.h} header file, the following steps@footnote{In practice, you would probably want to use the GNU Autotools---Automake, Autoconf, Libtool, and @command{gettext}---to configure and build your libraries. Instructions for doing so are beyond -the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for WWW links to +the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to the tools.} create a GNU/Linux shared library: @example @@ -33231,14 +33234,14 @@ BEGIN @{ for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) + strftime("%m %d %Y %H:%M:%S", data["mtime"]) print "\nInfo for JUNK" ret = stat("JUNK", data) print "ret =", ret for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + print "JUNK modified:", strftime("%m %d %Y %H:%M:%S", data["mtime"]) @} @end example @@ -33252,25 +33255,26 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @print{} Info for testff.awk @print{} ret = 0 @print{} data["blksize"] = 4096 -@print{} data["mtime"] = 1350838628 +@print{} data["devbsize"] = 512 +@print{} data["mtime"] = 1412004710 @print{} data["mode"] = 33204 @print{} data["type"] = file @print{} data["dev"] = 2053 @print{} data["gid"] = 1000 -@print{} data["ino"] = 1719496 -@print{} data["ctime"] = 1350838628 +@print{} data["ino"] = 10358899 +@print{} data["ctime"] = 1412004710 @print{} data["blocks"] = 8 @print{} data["nlink"] = 1 @print{} data["name"] = testff.awk -@print{} data["atime"] = 1350838632 +@print{} data["atime"] = 1412004716 @print{} data["pmode"] = -rw-rw-r-- -@print{} data["size"] = 662 +@print{} data["size"] = 666 @print{} data["uid"] = 1000 -@print{} testff.awk modified: 10 21 12 18:57:08 -@print{} +@print{} testff.awk modified: 09 29 2014 18:31:50 +@print{} @print{} Info for JUNK @print{} ret = -1 -@print{} JUNK modified: 01 01 70 02:00:00 +@print{} JUNK modified: 01 01 1970 02:00:00 @end example @node Extension Samples @@ -33295,9 +33299,9 @@ Others mainly provide example code that shows how to use the extension API. * Extension Sample Rev2way:: Reversing data sample two-way processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. @end menu @node Extension Sample File Functions @@ -33307,7 +33311,7 @@ The @code{filefuncs} extension provides three different functions, as follows: The usage is: @table @asis -@item @@load "filefuncs" +@item @code{@@load "filefuncs"} This is how you load the extension. @cindex @code{chdir()} extension function @@ -33370,7 +33374,7 @@ Not all systems support all file types. @tab All @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the @code{filedata} array as described below. @code{flags} is the bitwise -OR of several predefined constant values, also described below. +OR of several predefined values, also described below. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -33415,10 +33419,10 @@ Immediately follow a symbolic link named in @code{pathlist}, whether or not @code{FTS_LOGICAL} is set. @item FTS_SEEDOT -By default, the @code{fts()} routines do not return entries for @file{.} (dot) -and @file{..} (dot-dot). This option causes entries for dot-dot to also -be included. (The extension always includes an entry for dot, -see below.) +By default, the C library @code{fts()} routines do not return entries for +@file{.} (dot) and @file{..} (dot-dot). This option causes entries for +dot-dot to also be included. (The extension always includes an entry +for dot, see below.) @item FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. @@ -33472,8 +33476,8 @@ Otherwise it returns @minus{}1. @quotation NOTE The @code{fts()} extension does not exactly mimic the interface of the C library @code{fts()} routines, choosing instead to -provide an interface that is based on associative arrays, which should -be more comfortable to use from an @command{awk} program. This includes the +provide an interface that is based on associative arrays, which is +more comfortable to use from an @command{awk} program. This includes the lack of a comparison function, since @command{gawk} already provides powerful array sorting facilities. While an @code{fts_read()}-like interface could have been provided, this felt less natural than simply @@ -33481,7 +33485,8 @@ creating a multidimensional array to represent the file hierarchy and its information. @end quotation -See @file{test/fts.awk} in the @command{gawk} distribution for an example. +See @file{test/fts.awk} in the @command{gawk} distribution for an example +use of the @code{fts()} extension function. @node Extension Sample Fnmatch @subsection Interface To @code{fnmatch()} @@ -33689,7 +33694,7 @@ indicating the type of the file. The letters are file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types -@caption{File Types Returned By @code{readdir()}} +@caption{File Types Returned By The @code{readdir} Extension} @multitable @columnfractions .1 .9 @headitem Letter @tab File Type @item @code{b} @tab Block device @@ -33781,6 +33786,9 @@ The @code{rwarray} extension adds two functions, named @code{writea()} and @code{reada()}, as follows: @table @code +@item @@load "rwarray" +This is how you load the extension. + @cindex @code{writea()} extension function @item ret = writea(file, array) This function takes a string argument, which is the name of the file @@ -33856,17 +33864,6 @@ if (contents == "" && ERRNO != "") @{ @} @end example -@node Extension Sample API Tests -@subsection API Tests -@cindex @code{testext} extension - -The @code{testext} extension exercises parts of the extension API that -are not tested by the other samples. The @file{extension/testext.c} -file contains both the C code for the extension and @command{awk} -test code inside C comments that run the tests. The testing framework -extracts the @command{awk} code and runs the tests. See the source file -for more information. - @node Extension Sample Time @subsection Extension Time Functions @@ -33897,6 +33894,17 @@ Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table +@node Extension Sample API Tests +@subsection API Tests +@cindex @code{testext} extension + +The @code{testext} extension exercises parts of the extension API that +are not tested by the other samples. The @file{extension/testext.c} +file contains both the C code for the extension and @command{awk} +test code inside C comments that run the tests. The testing framework +extracts the @command{awk} code and runs the tests. See the source file +for more information. + @node gawkextlib @section The @code{gawkextlib} Project @cindex @code{gawkextlib} @@ -33912,8 +33920,7 @@ As of this writing, there are five extensions: @itemize @value{BULLET} @item -XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} -XML parsing library. +GD graphics library extension. @item PDF extension. @@ -33922,17 +33929,14 @@ PDF extension. PostgreSQL extension. @item -GD graphics library extension. - -@item MPFR library extension. This provides access to a number of MPFR functions which @command{gawk}'s native MPFR support does not. -@end itemize -The @code{time} extension described earlier (@pxref{Extension Sample -Time}) was originally from this project but has been moved in to the -main @command{gawk} distribution. +@item +XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} +XML parsing library. +@end itemize @cindex @command{git} utility You can check out the code for the @code{gawkextlib} project @@ -34023,6 +34027,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register extension functions, exit callbacks, @@ -34046,9 +34053,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -34080,7 +34084,7 @@ treated as read-only by the extension. @item @emph{All} memory passed from an extension to @command{gawk} must come from the API's memory allocation functions. @command{gawk} takes responsibility for -the memory and will release it when appropriate. +the memory and releases it when appropriate. @item The API provides information about the running version of @command{gawk} so @@ -34097,7 +34101,7 @@ 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 to the community of @command{gawk} users, the @code{gawkextlib} project -should be the place to do so. +is the place to do so. @end itemize @@ -34179,7 +34183,7 @@ which follows the POSIX specification. Many long-time @command{awk} users learned @command{awk} programming with the original @command{awk} implementation in Version 7 Unix. (This implementation was the basis for @command{awk} in Berkeley Unix, through 4.3-Reno. Subsequent versions -of Berkeley Unix, and some systems derived from 4.4BSD-Lite, used various +of Berkeley Unix, and, for a while, some systems derived from 4.4BSD-Lite, used various versions of @command{gawk} for their @command{awk}.) This @value{CHAPTER} briefly describes the evolution of the @command{awk} language, with cross-references to other parts of the @value{DOCUMENT} where you can @@ -34252,7 +34256,7 @@ The built-in functions @code{close()} and @code{system()} @item The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART}, -and @code{SUBSEP} built-in variables (@pxref{Built-in Variables}). +and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}). @item Assignable @code{$0} (@pxref{Changing Fields}). @@ -34283,14 +34287,11 @@ of @code{FS}. @item Dynamic regexps as operands of the @samp{~} and @samp{!~} operators -(@pxref{Regexp Usage}). +(@pxref{Computed Regexps}). @item The escape sequences @samp{\b}, @samp{\f}, and @samp{\r} (@pxref{Escape Sequences}). -(Some vendors have updated their old versions of @command{awk} to -recognize @samp{\b}, @samp{\f}, and @samp{\r}, but this is not -something you can rely on.) @item Redirection of input for the @code{getline} function @@ -34329,7 +34330,7 @@ The @option{-v} option for assigning variables before program execution begins @c GNU, Bell Laboratories & MKS together @item -The @option{--} option for terminating command-line options. +The @option{--} signal for terminating command-line options. @item The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences @@ -34352,7 +34353,7 @@ A cleaner specification for the @code{%c} format-control letter in the @item The ability to dynamically pass the field width and precision (@code{"%*.*d"}) -in the argument list of the @code{printf} function +in the argument list of @code{printf} and @code{sprintf()} (@pxref{Control Letters}). @item @@ -34387,8 +34388,8 @@ The concept of a numeric string and tighter comparison rules to go with it (@pxref{Typing and Comparison}). @item -The use of built-in variables as function parameter names is forbidden -(@pxref{Definition Syntax}. +The use of predefined variables as function parameter names is forbidden +(@pxref{Definition Syntax}). @item More complete documentation of many of the previously undocumented @@ -34483,7 +34484,7 @@ in the current version of @command{gawk}. @itemize @value{BULLET} @item -Additional built-in variables: +Additional predefined variables: @itemize @value{MINUS} @item @@ -34567,14 +34568,6 @@ The @code{BEGINFILE} and @code{ENDFILE} special patterns. (@pxref{BEGINFILE/ENDFILE}). @item -The ability to delete all of an array at once with @samp{delete @var{array}} -(@pxref{Delete}). - -@item -The @code{nextfile} statement -(@pxref{Nextfile Statement}). - -@item The @code{switch} statement (@pxref{Switch Statement}). @end itemize @@ -34589,7 +34582,7 @@ of a two-way pipe to a coprocess (@pxref{Two-way I/O}). @item -POSIX compliance for @code{gsub()} and @code{sub()}. +POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix}. @item The @code{length()} function accepts an array argument @@ -34617,6 +34610,20 @@ Additional functions only in @command{gawk}: @itemize @value{MINUS} @item +The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions +for more powerful text manipulation +(@pxref{String Functions}). + +@item +The @code{asort()} and @code{asorti()} functions for sorting arrays +(@pxref{Array Sorting}). + +@item +The @code{mktime()}, @code{systime()}, and @code{strftime()} +functions for working with timestamps +(@pxref{Time Functions}). + +@item The @code{and()}, @code{compl()}, @@ -34630,30 +34637,15 @@ functions for bit manipulation @c In 4.1, and(), or() and xor() grew the ability to take > 2 arguments @item -The @code{asort()} and @code{asorti()} functions for sorting arrays -(@pxref{Array Sorting}). +The @code{isarray()} function to check if a variable is an array or not +(@pxref{Type Functions}). @item The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()} functions for internationalization (@pxref{Programmer i18n}). - -@item -The @code{fflush()} function from BWK @command{awk} -(@pxref{I/O Functions}). - -@item -The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions -for more powerful text manipulation -(@pxref{String Functions}). - -@item -The @code{mktime()}, @code{systime()}, and @code{strftime()} -functions for working with timestamps -(@pxref{Time Functions}). @end itemize - @item Changes and/or additions in the command-line options: @@ -34776,7 +34768,7 @@ GCC for VAX and Alpha has not been tested for a while. @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} @value{PVERSION} 4.1: +for @command{gawk} @value{PVERSION} 4.1: @c nested table @itemize @value{MINUS} @@ -35413,33 +35405,29 @@ The dynamic extension interface was completely redone @cindex extensions, Brian Kernighan's @command{awk} @cindex extensions, @command{mawk} -This @value{SECTION} summarizes the common extensions supported +The following table summarizes the common extensions supported by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk}, the three most widely-used freely available versions of @command{awk} (@pxref{Other Versions}). -@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} -@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk -@item @samp{\x} Escape sequence @tab X @tab X @tab X -@item @code{FS} as null string @tab X @tab X @tab X -@item @file{/dev/stdin} special file @tab X @tab X @tab X -@item @file{/dev/stdout} special file @tab X @tab X @tab X -@item @file{/dev/stderr} special file @tab X @tab X @tab X -@item @code{delete} without subscript @tab X @tab X @tab X -@item @code{fflush()} function @tab X @tab X @tab X -@item @code{length()} of an array @tab X @tab X @tab X -@item @code{nextfile} statement @tab X @tab X @tab X -@item @code{**} and @code{**=} operators @tab X @tab @tab X -@item @code{func} keyword @tab X @tab @tab X -@item @code{BINMODE} variable @tab @tab X @tab X -@item @code{RS} as regexp @tab @tab X @tab X -@item Time related functions @tab @tab X @tab X +@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} +@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @tab Now standard +@item @samp{\x} Escape sequence @tab X @tab X @tab X @tab +@item @code{FS} as null string @tab X @tab X @tab X @tab +@item @file{/dev/stdin} special file @tab X @tab X @tab X @tab +@item @file{/dev/stdout} special file @tab X @tab X @tab X @tab +@item @file{/dev/stderr} special file @tab X @tab X @tab X @tab +@item @code{delete} without subscript @tab X @tab X @tab X @tab X +@item @code{fflush()} function @tab X @tab X @tab X @tab X +@item @code{length()} of an array @tab X @tab X @tab X @tab +@item @code{nextfile} statement @tab X @tab X @tab X @tab X +@item @code{**} and @code{**=} operators @tab X @tab @tab X @tab +@item @code{func} keyword @tab X @tab @tab X @tab +@item @code{BINMODE} variable @tab @tab X @tab X @tab +@item @code{RS} as regexp @tab @tab X @tab X @tab +@item Time related functions @tab @tab X @tab X @tab @end multitable -(Technically speaking, as of late 2012, @code{fflush()}, @samp{delete @var{array}}, -and @code{nextfile} are no longer extensions, since they have been added -to POSIX.) - @node Ranges and Locales @appendixsec Regexp Ranges and Locales: A Long Sad Story @@ -35476,6 +35464,7 @@ In the @code{"C"} and @code{"POSIX"} locales, a range expression like But outside those locales, the ordering was defined to be based on @dfn{collation order}. +What does that mean? In many locales, @samp{A} and @samp{a} are both less than @samp{B}. In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; @@ -35483,7 +35472,7 @@ instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. This point needs to be emphasized: Much literature teaches that you should use @samp{[a-z]} to match a lowercase character. But on systems with -non-ASCII locales, this also matched all of the uppercase characters +non-ASCII locales, this also matches all of the uppercase characters except @samp{A} or @samp{Z}! This was a continuous cause of confusion, even well into the twenty-first century. @@ -35789,6 +35778,11 @@ The development of the extension API first released with Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. +@cindex Malmberg, John E. +@item +John Malmberg contributed significant improvements to the +OpenVMS port and the related documentation. + @item @cindex Colombo, Antonio Antonio Giovanni Colombo rewrote a number of examples in the early @@ -38312,7 +38306,7 @@ Pat Rankin suggested the solution that was adopted. @appendixsubsec Other Design Decisions As an arbitrary design decision, extensions can read the values of -built-in variables and arrays (such as @code{ARGV} and @code{FS}), but cannot +predefined variables and arrays (such as @code{ARGV} and @code{FS}), but cannot change them, with the exception of @code{PROCINFO}. The reason for this is to prevent an extension function from affecting @@ -39053,11 +39047,11 @@ See ``Free Documentation License.'' @item Field When @command{awk} reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can -change by setting the built-in variable @code{FS}). Such pieces are +change by setting the predefined variable @code{FS}). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable @code{FIELDWIDTHS} to describe their lengths. If you wish to specify the contents of fields instead of the field -separator, you can use the built-in variable @code{FPAT} to do so. +separator, you can use the predefined variable @code{FPAT} to do so. (@xref{Field Separators}, @ref{Constant Size}, and @@ -39076,7 +39070,7 @@ See also ``Double Precision'' and ``Single Precision.'' Format strings control the appearance of output in the @code{strftime()} and @code{sprintf()} functions, and in the @code{printf} statement as well. Also, data conversions from numbers to strings -are controlled by the format strings contained in the built-in variables +are controlled by the format strings contained in the predefined variables @code{CONVFMT} and @code{OFMT}. (@xref{Control Letters}.) @item Free Documentation License |