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 95aba006..e1c3c210 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 e6872457..058d1100 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 @@ -4072,8 +4072,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 @@ -4112,9 +4112,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. @@ -4133,7 +4133,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 @@ -4385,7 +4385,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 @@ -4651,7 +4651,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). @@ -4829,7 +4829,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: @@ -5543,7 +5543,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 @@ -5664,7 +5664,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 @@ -5714,7 +5714,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. @@ -5789,9 +5789,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' ------------------------------------------------------------------------- @@ -6179,7 +6179,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. @@ -6241,11 +6241,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 { @@ -7102,8 +7102,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 @@ -7484,10 +7484,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. @@ -7591,7 +7591,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::). @@ -8885,7 +8885,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 @@ -8899,7 +8899,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. @@ -10003,8 +10003,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 @@ -10014,7 +10014,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. @@ -10679,8 +10679,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 @@ -11223,7 +11224,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: @@ -12132,10 +12133,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: @@ -13366,7 +13367,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. @@ -14392,7 +14393,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 @@ -16548,7 +16549,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 # @@ -21756,11 +21757,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 @@ -22022,7 +22023,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. @@ -22578,13 +22579,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. @@ -22604,6 +22605,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, @@ -22628,8 +22631,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. @@ -22717,7 +22718,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 --------------------------------- @@ -22862,7 +22863,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 --------------------------------------------------------- @@ -23507,7 +23508,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' ----------------------- @@ -23528,7 +23529,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 ------------------------ @@ -23561,7 +23562,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 ---------------------------------------- @@ -23666,7 +23667,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 @@ -24436,8 +24437,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 @@ -24947,7 +24948,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 */ @@ -24972,14 +24981,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) @@ -25006,7 +25011,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); @@ -25088,14 +25093,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 @@ -25107,32 +25112,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 @@ -25160,9 +25166,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 @@ -25173,7 +25179,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")' @@ -25229,8 +25235,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 @@ -25271,10 +25277,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 @@ -25324,15 +25330,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 @@ -25527,7 +25534,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'. @@ -25598,6 +25605,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 @@ -25634,7 +25644,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 ------------------------------ @@ -25667,21 +25677,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 @@ -25710,6 +25708,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 @@ -25722,21 +25732,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 @@ -25812,6 +25818,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. @@ -25826,8 +25834,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. @@ -25851,7 +25857,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' @@ -25865,7 +25871,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. @@ -25898,11 +25904,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: @@ -25952,7 +25958,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::). @@ -25973,12 +25979,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::). @@ -26002,7 +26006,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::). @@ -26017,8 +26021,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 ~ @@ -26045,8 +26049,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. @@ -26108,7 +26112,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' @@ -26150,11 +26154,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: @@ -26163,7 +26162,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 @@ -26182,24 +26181,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: @@ -26251,7 +26250,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 @@ -26647,30 +26646,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 @@ -26711,14 +26706,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. @@ -26915,6 +26910,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. @@ -28899,7 +28897,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 @@ -29466,11 +29464,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::.) @@ -29487,7 +29485,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 @@ -31701,10 +31699,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. @@ -31766,7 +31760,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) @@ -32282,7 +32276,7 @@ Index (line 99) * exp: Numeric Functions. (line 18) * expand utility: Very Simple. (line 72) -* Expat XML parser library: gawkextlib. (line 35) +* Expat XML parser library: gawkextlib. (line 31) * exponent: Numeric Functions. (line 18) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) @@ -32559,7 +32553,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. @@ -32618,6 +32611,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 129) @@ -32697,7 +32691,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) @@ -32997,6 +32991,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) @@ -33327,6 +33322,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) @@ -33440,7 +33439,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. @@ -33545,7 +33544,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) @@ -33990,10 +33989,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) @@ -34006,6 +34002,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) @@ -34070,7 +34069,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) @@ -34108,557 +34107,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-1129504 -Node: Other Arguments129529 -Node: Naming Standard Input132490 -Node: Environment Variables133583 -Node: AWKPATH Variable134141 -Ref: AWKPATH Variable-Footnote-1136993 -Ref: AWKPATH Variable-Footnote-2137038 -Node: AWKLIBPATH Variable137298 -Node: Other Environment Variables138057 -Node: Exit Status141759 -Node: Include Files142434 -Node: Loading Shared Libraries146012 -Node: Obsolete147439 -Node: Undocumented148136 -Node: Invoking Summary148403 -Node: Regexp150069 -Node: Regexp Usage151528 -Node: Escape Sequences153561 -Node: Regexp Operators159578 -Ref: Regexp Operators-Footnote-1167013 -Ref: Regexp Operators-Footnote-2167160 -Node: Bracket Expressions167258 -Ref: table-char-classes169275 -Node: Leftmost Longest172215 -Node: Computed Regexps173517 -Node: GNU Regexp Operators176914 -Node: Case-sensitivity180620 -Ref: Case-sensitivity-Footnote-1183510 -Ref: Case-sensitivity-Footnote-2183745 -Node: Regexp Summary183853 -Node: Reading Files185322 -Node: Records187414 -Node: awk split records188142 -Node: gawk split records193054 -Ref: gawk split records-Footnote-1197593 -Node: Fields197630 -Ref: Fields-Footnote-1200426 -Node: Nonconstant Fields200512 -Ref: Nonconstant Fields-Footnote-1202742 -Node: Changing Fields202944 -Node: Field Separators208876 -Node: Default Field Splitting211578 -Node: Regexp Field Splitting212695 -Node: Single Character Fields216045 -Node: Command Line Field Separator217104 -Node: Full Line Fields220314 -Ref: Full Line Fields-Footnote-1220822 -Node: Field Splitting Summary220868 -Ref: Field Splitting Summary-Footnote-1223999 -Node: Constant Size224100 -Node: Splitting By Content228706 -Ref: Splitting By Content-Footnote-1232779 -Node: Multiple Line232819 -Ref: Multiple Line-Footnote-1238708 -Node: Getline238887 -Node: Plain Getline241098 -Node: Getline/Variable243738 -Node: Getline/File244885 -Node: Getline/Variable/File246269 -Ref: Getline/Variable/File-Footnote-1247868 -Node: Getline/Pipe247955 -Node: Getline/Variable/Pipe250638 -Node: Getline/Coprocess251767 -Node: Getline/Variable/Coprocess253019 -Node: Getline Notes253756 -Node: Getline Summary256548 -Ref: table-getline-variants256956 -Node: Read Timeout257785 -Ref: Read Timeout-Footnote-1261599 -Node: Command-line directories261657 -Node: Input Summary262561 -Node: Input Exercises265813 -Node: Printing266541 -Node: Print268318 -Node: Print Examples269775 -Node: Output Separators272554 -Node: OFMT274570 -Node: Printf275922 -Node: Basic Printf276707 -Node: Control Letters278278 -Node: Format Modifiers282262 -Node: Printf Examples288269 -Node: Redirection290751 -Node: Special FD297482 -Ref: Special FD-Footnote-1300639 -Node: Special Files300713 -Node: Other Inherited Files301329 -Node: Special Network302329 -Node: Special Caveats303190 -Node: Close Files And Pipes304141 -Ref: Close Files And Pipes-Footnote-1311318 -Ref: Close Files And Pipes-Footnote-2311466 -Node: Output Summary311616 -Node: Output Exercises312612 -Node: Expressions313292 -Node: Values314477 -Node: Constants315153 -Node: Scalar Constants315833 -Ref: Scalar Constants-Footnote-1316692 -Node: Nondecimal-numbers316942 -Node: Regexp Constants319942 -Node: Using Constant Regexps320467 -Node: Variables323605 -Node: Using Variables324260 -Node: Assignment Options326164 -Node: Conversion328039 -Node: Strings And Numbers328563 -Ref: Strings And Numbers-Footnote-1331625 -Node: Locale influences conversions331734 -Ref: table-locale-affects334449 -Node: All Operators335037 -Node: Arithmetic Ops335667 -Node: Concatenation338172 -Ref: Concatenation-Footnote-1340991 -Node: Assignment Ops341097 -Ref: table-assign-ops346080 -Node: Increment Ops347358 -Node: Truth Values and Conditions350796 -Node: Truth Values351879 -Node: Typing and Comparison352928 -Node: Variable Typing353721 -Node: Comparison Operators357373 -Ref: table-relational-ops357783 -Node: POSIX String Comparison361298 -Ref: POSIX String Comparison-Footnote-1362370 -Node: Boolean Ops362508 -Ref: Boolean Ops-Footnote-1366987 -Node: Conditional Exp367078 -Node: Function Calls368805 -Node: Precedence372685 -Node: Locales376353 -Node: Expressions Summary377984 -Node: Patterns and Actions380558 -Node: Pattern Overview381674 -Node: Regexp Patterns383353 -Node: Expression Patterns383896 -Node: Ranges387676 -Node: BEGIN/END390782 -Node: Using BEGIN/END391544 -Ref: Using BEGIN/END-Footnote-1394281 -Node: I/O And BEGIN/END394387 -Node: BEGINFILE/ENDFILE396701 -Node: Empty399602 -Node: Using Shell Variables399919 -Node: Action Overview402195 -Node: Statements404522 -Node: If Statement406370 -Node: While Statement407868 -Node: Do Statement409896 -Node: For Statement411038 -Node: Switch Statement414193 -Node: Break Statement416581 -Node: Continue Statement418622 -Node: Next Statement420447 -Node: Nextfile Statement422827 -Node: Exit Statement425457 -Node: Built-in Variables427860 -Node: User-modified428987 -Ref: User-modified-Footnote-1436667 -Node: Auto-set436729 -Ref: Auto-set-Footnote-1449586 -Ref: Auto-set-Footnote-2449791 -Node: ARGC and ARGV449847 -Node: Pattern Action Summary454051 -Node: Arrays456470 -Node: Array Basics457799 -Node: Array Intro458643 -Ref: figure-array-elements460616 -Ref: Array Intro-Footnote-1463140 -Node: Reference to Elements463268 -Node: Assigning Elements465718 -Node: Array Example466209 -Node: Scanning an Array467967 -Node: Controlling Scanning470983 -Ref: Controlling Scanning-Footnote-1476172 -Node: Numeric Array Subscripts476488 -Node: Uninitialized Subscripts478671 -Node: Delete480288 -Ref: Delete-Footnote-1483032 -Node: Multidimensional483089 -Node: Multiscanning486184 -Node: Arrays of Arrays487773 -Node: Arrays Summary492534 -Node: Functions494639 -Node: Built-in495512 -Node: Calling Built-in496590 -Node: Numeric Functions498578 -Ref: Numeric Functions-Footnote-1502600 -Ref: Numeric Functions-Footnote-2502957 -Ref: Numeric Functions-Footnote-3503005 -Node: String Functions503274 -Ref: String Functions-Footnote-1526734 -Ref: String Functions-Footnote-2526863 -Ref: String Functions-Footnote-3527111 -Node: Gory Details527198 -Ref: table-sub-escapes528979 -Ref: table-sub-proposed530499 -Ref: table-posix-sub531863 -Ref: table-gensub-escapes533403 -Ref: Gory Details-Footnote-1534235 -Node: I/O Functions534386 -Ref: I/O Functions-Footnote-1541487 -Node: Time Functions541634 -Ref: Time Functions-Footnote-1552103 -Ref: Time Functions-Footnote-2552171 -Ref: Time Functions-Footnote-3552329 -Ref: Time Functions-Footnote-4552440 -Ref: Time Functions-Footnote-5552552 -Ref: Time Functions-Footnote-6552779 -Node: Bitwise Functions553045 -Ref: table-bitwise-ops553607 -Ref: Bitwise Functions-Footnote-1557915 -Node: Type Functions558084 -Node: I18N Functions559233 -Node: User-defined560878 -Node: Definition Syntax561682 -Ref: Definition Syntax-Footnote-1567086 -Node: Function Example567155 -Ref: Function Example-Footnote-1570072 -Node: Function Caveats570094 -Node: Calling A Function570612 -Node: Variable Scope571567 -Node: Pass By Value/Reference574555 -Node: Return Statement578065 -Node: Dynamic Typing581049 -Node: Indirect Calls581978 -Ref: Indirect Calls-Footnote-1591699 -Node: Functions Summary591827 -Node: Library Functions594526 -Ref: Library Functions-Footnote-1598144 -Ref: Library Functions-Footnote-2598287 -Node: Library Names598458 -Ref: Library Names-Footnote-1601916 -Ref: Library Names-Footnote-2602136 -Node: General Functions602222 -Node: Strtonum Function603250 -Node: Assert Function606270 -Node: Round Function609594 -Node: Cliff Random Function611135 -Node: Ordinal Functions612151 -Ref: Ordinal Functions-Footnote-1615216 -Ref: Ordinal Functions-Footnote-2615468 -Node: Join Function615679 -Ref: Join Function-Footnote-1617450 -Node: Getlocaltime Function617650 -Node: Readfile Function621391 -Node: Data File Management623339 -Node: Filetrans Function623971 -Node: Rewind Function628030 -Node: File Checking629415 -Ref: File Checking-Footnote-1630743 -Node: Empty Files630944 -Node: Ignoring Assigns632923 -Node: Getopt Function634474 -Ref: Getopt Function-Footnote-1645934 -Node: Passwd Functions646137 -Ref: Passwd Functions-Footnote-1654988 -Node: Group Functions655076 -Ref: Group Functions-Footnote-1662979 -Node: Walking Arrays663192 -Node: Library Functions Summary664795 -Node: Library Exercises666196 -Node: Sample Programs667476 -Node: Running Examples668246 -Node: Clones668974 -Node: Cut Program670198 -Node: Egrep Program679928 -Ref: Egrep Program-Footnote-1687430 -Node: Id Program687540 -Node: Split Program691184 -Ref: Split Program-Footnote-1694630 -Node: Tee Program694758 -Node: Uniq Program697545 -Node: Wc Program704966 -Ref: Wc Program-Footnote-1709214 -Node: Miscellaneous Programs709306 -Node: Dupword Program710519 -Node: Alarm Program712550 -Node: Translate Program717354 -Ref: Translate Program-Footnote-1721927 -Ref: Translate Program-Footnote-2722197 -Node: Labels Program722336 -Ref: Labels Program-Footnote-1725685 -Node: Word Sorting725769 -Node: History Sorting729839 -Node: Extract Program731675 -Node: Simple Sed739207 -Node: Igawk Program742269 -Ref: Igawk Program-Footnote-1756595 -Ref: Igawk Program-Footnote-2756796 -Ref: Igawk Program-Footnote-3756918 -Node: Anagram Program757033 -Node: Signature Program760095 -Node: Programs Summary761342 -Node: Programs Exercises762535 -Ref: Programs Exercises-Footnote-1766666 -Node: Advanced Features766757 -Node: Nondecimal Data768705 -Node: Array Sorting770295 -Node: Controlling Array Traversal770992 -Ref: Controlling Array Traversal-Footnote-1779323 -Node: Array Sorting Functions779441 -Ref: Array Sorting Functions-Footnote-1783333 -Node: Two-way I/O783527 -Ref: Two-way I/O-Footnote-1788471 -Ref: Two-way I/O-Footnote-2788657 -Node: TCP/IP Networking788739 -Node: Profiling791616 -Node: Advanced Features Summary799160 -Node: Internationalization801093 -Node: I18N and L10N802573 -Node: Explaining gettext803259 -Ref: Explaining gettext-Footnote-1808288 -Ref: Explaining gettext-Footnote-2808472 -Node: Programmer i18n808637 -Ref: Programmer i18n-Footnote-1813503 -Node: Translator i18n813552 -Node: String Extraction814346 -Ref: String Extraction-Footnote-1815477 -Node: Printf Ordering815563 -Ref: Printf Ordering-Footnote-1818349 -Node: I18N Portability818413 -Ref: I18N Portability-Footnote-1820862 -Node: I18N Example820925 -Ref: I18N Example-Footnote-1823725 -Node: Gawk I18N823797 -Node: I18N Summary824435 -Node: Debugger825774 -Node: Debugging826796 -Node: Debugging Concepts827237 -Node: Debugging Terms829094 -Node: Awk Debugging831669 -Node: Sample Debugging Session832561 -Node: Debugger Invocation833081 -Node: Finding The Bug834465 -Node: List of Debugger Commands840940 -Node: Breakpoint Control842272 -Node: Debugger Execution Control845964 -Node: Viewing And Changing Data849328 -Node: Execution Stack852693 -Node: Debugger Info854331 -Node: Miscellaneous Debugger Commands858348 -Node: Readline Support863540 -Node: Limitations864432 -Node: Debugging Summary866529 -Node: Arbitrary Precision Arithmetic867697 -Node: Computer Arithmetic869113 -Ref: table-numeric-ranges872714 -Ref: Computer Arithmetic-Footnote-1873573 -Node: Math Definitions873630 -Ref: table-ieee-formats876917 -Ref: Math Definitions-Footnote-1877521 -Node: MPFR features877626 -Node: FP Math Caution879294 -Ref: FP Math Caution-Footnote-1880344 -Node: Inexactness of computations880713 -Node: Inexact representation881661 -Node: Comparing FP Values883016 -Node: Errors accumulate884089 -Node: Getting Accuracy885522 -Node: Try To Round888181 -Node: Setting precision889080 -Ref: table-predefined-precision-strings889762 -Node: Setting the rounding mode891556 -Ref: table-gawk-rounding-modes891920 -Ref: Setting the rounding mode-Footnote-1895374 -Node: Arbitrary Precision Integers895553 -Ref: Arbitrary Precision Integers-Footnote-1898544 -Node: POSIX Floating Point Problems898693 -Ref: POSIX Floating Point Problems-Footnote-1902569 -Node: Floating point summary902607 -Node: Dynamic Extensions904799 -Node: Extension Intro906351 -Node: Plugin License907617 -Node: Extension Mechanism Outline908414 -Ref: figure-load-extension908842 -Ref: figure-register-new-function910322 -Ref: figure-call-new-function911326 -Node: Extension API Description913312 -Node: Extension API Functions Introduction914762 -Node: General Data Types919598 -Ref: General Data Types-Footnote-1925275 -Node: Memory Allocation Functions925574 -Ref: Memory Allocation Functions-Footnote-1928403 -Node: Constructor Functions928499 -Node: Registration Functions930233 -Node: Extension Functions930918 -Node: Exit Callback Functions933214 -Node: Extension Version String934462 -Node: Input Parsers935112 -Node: Output Wrappers944927 -Node: Two-way processors949443 -Node: Printing Messages951647 -Ref: Printing Messages-Footnote-1952724 -Node: Updating `ERRNO'952876 -Node: Requesting Values953619 -Ref: table-value-types-returned954356 -Node: Accessing Parameters955314 -Node: Symbol Table Access956544 -Node: Symbol table by name957058 -Node: Symbol table by cookie959038 -Ref: Symbol table by cookie-Footnote-1963175 -Node: Cached values963238 -Ref: Cached values-Footnote-1966742 -Node: Array Manipulation966833 -Ref: Array Manipulation-Footnote-1967931 -Node: Array Data Types967970 -Ref: Array Data Types-Footnote-1970627 -Node: Array Functions970719 -Node: Flattening Arrays974573 -Node: Creating Arrays981460 -Node: Extension API Variables986227 -Node: Extension Versioning986863 -Node: Extension API Informational Variables988764 -Node: Extension API Boilerplate989850 -Node: Finding Extensions993666 -Node: Extension Example994226 -Node: Internal File Description994998 -Node: Internal File Ops999065 -Ref: Internal File Ops-Footnote-11010499 -Node: Using Internal File Ops1010639 -Ref: Using Internal File Ops-Footnote-11012986 -Node: Extension Samples1013254 -Node: Extension Sample File Functions1014778 -Node: Extension Sample Fnmatch1022346 -Node: Extension Sample Fork1023828 -Node: Extension Sample Inplace1025041 -Node: Extension Sample Ord1026716 -Node: Extension Sample Readdir1027552 -Ref: table-readdir-file-types1028408 -Node: Extension Sample Revout1029207 -Node: Extension Sample Rev2way1029798 -Node: Extension Sample Read write array1030539 -Node: Extension Sample Readfile1032418 -Node: Extension Sample API Tests1033518 -Node: Extension Sample Time1034043 -Node: gawkextlib1035358 -Node: Extension summary1038171 -Node: Extension Exercises1041864 -Node: Language History1042586 -Node: V7/SVR3.11044229 -Node: SVR41046549 -Node: POSIX1047991 -Node: BTL1049377 -Node: POSIX/GNU1050111 -Node: Feature History1055827 -Node: Common Extensions1068918 -Node: Ranges and Locales1070230 -Ref: Ranges and Locales-Footnote-11074847 -Ref: Ranges and Locales-Footnote-21074874 -Ref: Ranges and Locales-Footnote-31075108 -Node: Contributors1075329 -Node: History summary1080756 -Node: Installation1082125 -Node: Gawk Distribution1083076 -Node: Getting1083560 -Node: Extracting1084384 -Node: Distribution contents1086026 -Node: Unix Installation1091743 -Node: Quick Installation1092360 -Node: Additional Configuration Options1094802 -Node: Configuration Philosophy1096540 -Node: Non-Unix Installation1098891 -Node: PC Installation1099349 -Node: PC Binary Installation1100660 -Node: PC Compiling1102508 -Ref: PC Compiling-Footnote-11105507 -Node: PC Testing1105612 -Node: PC Using1106788 -Node: Cygwin1110940 -Node: MSYS1111749 -Node: VMS Installation1112247 -Node: VMS Compilation1113043 -Ref: VMS Compilation-Footnote-11114265 -Node: VMS Dynamic Extensions1114323 -Node: VMS Installation Details1115696 -Node: VMS Running1117948 -Node: VMS GNV1120782 -Node: VMS Old Gawk1121505 -Node: Bugs1121975 -Node: Other Versions1125979 -Node: Installation summary1132203 -Node: Notes1133259 -Node: Compatibility Mode1134124 -Node: Additions1134906 -Node: Accessing The Source1135831 -Node: Adding Code1137267 -Node: New Ports1143439 -Node: Derived Files1147920 -Ref: Derived Files-Footnote-11153395 -Ref: Derived Files-Footnote-21153429 -Ref: Derived Files-Footnote-31154025 -Node: Future Extensions1154139 -Node: Implementation Limitations1154745 -Node: Extension Design1155993 -Node: Old Extension Problems1157147 -Ref: Old Extension Problems-Footnote-11158664 -Node: Extension New Mechanism Goals1158721 -Ref: Extension New Mechanism Goals-Footnote-11162081 -Node: Extension Other Design Decisions1162270 -Node: Extension Future Growth1164376 -Node: Old Extension Mechanism1165212 -Node: Notes summary1166974 -Node: Basic Concepts1168160 -Node: Basic High Level1168841 -Ref: figure-general-flow1169113 -Ref: figure-process-flow1169712 -Ref: Basic High Level-Footnote-11172941 -Node: Basic Data Typing1173126 -Node: Glossary1176454 -Node: Copying1201606 -Node: GNU Free Documentation License1239162 -Node: Index1264298 +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-1129508 +Node: Other Arguments129533 +Node: Naming Standard Input132494 +Node: Environment Variables133587 +Node: AWKPATH Variable134145 +Ref: AWKPATH Variable-Footnote-1136997 +Ref: AWKPATH Variable-Footnote-2137042 +Node: AWKLIBPATH Variable137302 +Node: Other Environment Variables138061 +Node: Exit Status141763 +Node: Include Files142438 +Node: Loading Shared Libraries146016 +Node: Obsolete147443 +Node: Undocumented148140 +Node: Invoking Summary148407 +Node: Regexp150073 +Node: Regexp Usage151532 +Node: Escape Sequences153565 +Node: Regexp Operators159582 +Ref: Regexp Operators-Footnote-1167017 +Ref: Regexp Operators-Footnote-2167164 +Node: Bracket Expressions167262 +Ref: table-char-classes169279 +Node: Leftmost Longest172219 +Node: Computed Regexps173521 +Node: GNU Regexp Operators176918 +Node: Case-sensitivity180624 +Ref: Case-sensitivity-Footnote-1183514 +Ref: Case-sensitivity-Footnote-2183749 +Node: Regexp Summary183857 +Node: Reading Files185326 +Node: Records187420 +Node: awk split records188152 +Node: gawk split records193066 +Ref: gawk split records-Footnote-1197605 +Node: Fields197642 +Ref: Fields-Footnote-1200440 +Node: Nonconstant Fields200526 +Ref: Nonconstant Fields-Footnote-1202756 +Node: Changing Fields202958 +Node: Field Separators208890 +Node: Default Field Splitting211594 +Node: Regexp Field Splitting212711 +Node: Single Character Fields216061 +Node: Command Line Field Separator217120 +Node: Full Line Fields220332 +Ref: Full Line Fields-Footnote-1220840 +Node: Field Splitting Summary220886 +Ref: Field Splitting Summary-Footnote-1224017 +Node: Constant Size224118 +Node: Splitting By Content228724 +Ref: Splitting By Content-Footnote-1232797 +Node: Multiple Line232837 +Ref: Multiple Line-Footnote-1238726 +Node: Getline238905 +Node: Plain Getline241116 +Node: Getline/Variable243756 +Node: Getline/File244903 +Node: Getline/Variable/File246287 +Ref: Getline/Variable/File-Footnote-1247888 +Node: Getline/Pipe247975 +Node: Getline/Variable/Pipe250658 +Node: Getline/Coprocess251789 +Node: Getline/Variable/Coprocess253041 +Node: Getline Notes253780 +Node: Getline Summary256572 +Ref: table-getline-variants256984 +Node: Read Timeout257813 +Ref: Read Timeout-Footnote-1261627 +Node: Command-line directories261685 +Node: Input Summary262589 +Node: Input Exercises265841 +Node: Printing266569 +Node: Print268346 +Node: Print Examples269803 +Node: Output Separators272582 +Node: OFMT274600 +Node: Printf275954 +Node: Basic Printf276739 +Node: Control Letters278310 +Node: Format Modifiers282294 +Node: Printf Examples288301 +Node: Redirection290783 +Node: Special FD297514 +Ref: Special FD-Footnote-1300671 +Node: Special Files300745 +Node: Other Inherited Files301361 +Node: Special Network302361 +Node: Special Caveats303222 +Node: Close Files And Pipes304173 +Ref: Close Files And Pipes-Footnote-1311352 +Ref: Close Files And Pipes-Footnote-2311500 +Node: Output Summary311650 +Node: Output Exercises312646 +Node: Expressions313326 +Node: Values314511 +Node: Constants315187 +Node: Scalar Constants315867 +Ref: Scalar Constants-Footnote-1316726 +Node: Nondecimal-numbers316976 +Node: Regexp Constants319976 +Node: Using Constant Regexps320501 +Node: Variables323639 +Node: Using Variables324294 +Node: Assignment Options326204 +Node: Conversion328079 +Node: Strings And Numbers328603 +Ref: Strings And Numbers-Footnote-1331667 +Node: Locale influences conversions331776 +Ref: table-locale-affects334491 +Node: All Operators335079 +Node: Arithmetic Ops335709 +Node: Concatenation338214 +Ref: Concatenation-Footnote-1341033 +Node: Assignment Ops341139 +Ref: table-assign-ops346122 +Node: Increment Ops347400 +Node: Truth Values and Conditions350838 +Node: Truth Values351921 +Node: Typing and Comparison352970 +Node: Variable Typing353763 +Node: Comparison Operators357415 +Ref: table-relational-ops357825 +Node: POSIX String Comparison361340 +Ref: POSIX String Comparison-Footnote-1362412 +Node: Boolean Ops362550 +Ref: Boolean Ops-Footnote-1367029 +Node: Conditional Exp367120 +Node: Function Calls368847 +Node: Precedence372727 +Node: Locales376395 +Node: Expressions Summary378026 +Node: Patterns and Actions380600 +Node: Pattern Overview381720 +Node: Regexp Patterns383399 +Node: Expression Patterns383942 +Node: Ranges387722 +Node: BEGIN/END390828 +Node: Using BEGIN/END391590 +Ref: Using BEGIN/END-Footnote-1394327 +Node: I/O And BEGIN/END394433 +Node: BEGINFILE/ENDFILE396747 +Node: Empty399648 +Node: Using Shell Variables399965 +Node: Action Overview402241 +Node: Statements404568 +Node: If Statement406416 +Node: While Statement407914 +Node: Do Statement409942 +Node: For Statement411084 +Node: Switch Statement414239 +Node: Break Statement416627 +Node: Continue Statement418668 +Node: Next Statement420493 +Node: Nextfile Statement422873 +Node: Exit Statement425503 +Node: Built-in Variables427906 +Node: User-modified429039 +Ref: User-modified-Footnote-1436719 +Node: Auto-set436781 +Ref: Auto-set-Footnote-1449638 +Ref: Auto-set-Footnote-2449843 +Node: ARGC and ARGV449899 +Node: Pattern Action Summary454103 +Node: Arrays456530 +Node: Array Basics457859 +Node: Array Intro458703 +Ref: figure-array-elements460676 +Ref: Array Intro-Footnote-1463200 +Node: Reference to Elements463328 +Node: Assigning Elements465778 +Node: Array Example466269 +Node: Scanning an Array468027 +Node: Controlling Scanning471043 +Ref: Controlling Scanning-Footnote-1476232 +Node: Numeric Array Subscripts476548 +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-1502662 +Ref: Numeric Functions-Footnote-2503019 +Ref: Numeric Functions-Footnote-3503067 +Node: String Functions503336 +Ref: String Functions-Footnote-1526800 +Ref: String Functions-Footnote-2526929 +Ref: String Functions-Footnote-3527177 +Node: Gory Details527264 +Ref: table-sub-escapes529045 +Ref: table-sub-proposed530565 +Ref: table-posix-sub531929 +Ref: table-gensub-escapes533469 +Ref: Gory Details-Footnote-1534301 +Node: I/O Functions534452 +Ref: I/O Functions-Footnote-1541553 +Node: Time Functions541700 +Ref: Time Functions-Footnote-1552169 +Ref: Time Functions-Footnote-2552237 +Ref: Time Functions-Footnote-3552395 +Ref: Time Functions-Footnote-4552506 +Ref: Time Functions-Footnote-5552618 +Ref: Time Functions-Footnote-6552845 +Node: Bitwise Functions553111 +Ref: table-bitwise-ops553673 +Ref: Bitwise Functions-Footnote-1557981 +Node: Type Functions558150 +Node: I18N Functions559299 +Node: User-defined560944 +Node: Definition Syntax561748 +Ref: Definition Syntax-Footnote-1567154 +Node: Function Example567223 +Ref: Function Example-Footnote-1570140 +Node: Function Caveats570162 +Node: Calling A Function570680 +Node: Variable Scope571635 +Node: Pass By Value/Reference574623 +Node: Return Statement578133 +Node: Dynamic Typing581117 +Node: Indirect Calls582046 +Ref: Indirect Calls-Footnote-1591767 +Node: Functions Summary591895 +Node: Library Functions594594 +Ref: Library Functions-Footnote-1598212 +Ref: Library Functions-Footnote-2598355 +Node: Library Names598526 +Ref: Library Names-Footnote-1601986 +Ref: Library Names-Footnote-2602206 +Node: General Functions602292 +Node: Strtonum Function603320 +Node: Assert Function606340 +Node: Round Function609664 +Node: Cliff Random Function611205 +Node: Ordinal Functions612221 +Ref: Ordinal Functions-Footnote-1615286 +Ref: Ordinal Functions-Footnote-2615538 +Node: Join Function615749 +Ref: Join Function-Footnote-1617520 +Node: Getlocaltime Function617720 +Node: Readfile Function621461 +Node: Data File Management623409 +Node: Filetrans Function624041 +Node: Rewind Function628100 +Node: File Checking629485 +Ref: File Checking-Footnote-1630813 +Node: Empty Files631014 +Node: Ignoring Assigns632993 +Node: Getopt Function634544 +Ref: Getopt Function-Footnote-1646004 +Node: Passwd Functions646207 +Ref: Passwd Functions-Footnote-1655058 +Node: Group Functions655146 +Ref: Group Functions-Footnote-1663049 +Node: Walking Arrays663262 +Node: Library Functions Summary664865 +Node: Library Exercises666266 +Node: Sample Programs667546 +Node: Running Examples668316 +Node: Clones669044 +Node: Cut Program670268 +Node: Egrep Program679998 +Ref: Egrep Program-Footnote-1687502 +Node: Id Program687612 +Node: Split Program691256 +Ref: Split Program-Footnote-1694702 +Node: Tee Program694830 +Node: Uniq Program697617 +Node: Wc Program705038 +Ref: Wc Program-Footnote-1709286 +Node: Miscellaneous Programs709378 +Node: Dupword Program710591 +Node: Alarm Program712622 +Node: Translate Program717426 +Ref: Translate Program-Footnote-1721999 +Ref: Translate Program-Footnote-2722269 +Node: Labels Program722408 +Ref: Labels Program-Footnote-1725757 +Node: Word Sorting725841 +Node: History Sorting729911 +Node: Extract Program731747 +Node: Simple Sed739279 +Node: Igawk Program742341 +Ref: Igawk Program-Footnote-1756667 +Ref: Igawk Program-Footnote-2756868 +Ref: Igawk Program-Footnote-3756990 +Node: Anagram Program757105 +Node: Signature Program760167 +Node: Programs Summary761414 +Node: Programs Exercises762607 +Ref: Programs Exercises-Footnote-1766738 +Node: Advanced Features766829 +Node: Nondecimal Data768777 +Node: Array Sorting770367 +Node: Controlling Array Traversal771064 +Ref: Controlling Array Traversal-Footnote-1779395 +Node: Array Sorting Functions779513 +Ref: Array Sorting Functions-Footnote-1783405 +Node: Two-way I/O783599 +Ref: Two-way I/O-Footnote-1788543 +Ref: Two-way I/O-Footnote-2788729 +Node: TCP/IP Networking788811 +Node: Profiling791688 +Node: Advanced Features Summary799232 +Node: Internationalization801165 +Node: I18N and L10N802645 +Node: Explaining gettext803331 +Ref: Explaining gettext-Footnote-1808360 +Ref: Explaining gettext-Footnote-2808544 +Node: Programmer i18n808709 +Ref: Programmer i18n-Footnote-1813575 +Node: Translator i18n813624 +Node: String Extraction814418 +Ref: String Extraction-Footnote-1815549 +Node: Printf Ordering815635 +Ref: Printf Ordering-Footnote-1818421 +Node: I18N Portability818485 +Ref: I18N Portability-Footnote-1820934 +Node: I18N Example820997 +Ref: I18N Example-Footnote-1823797 +Node: Gawk I18N823869 +Node: I18N Summary824507 +Node: Debugger825846 +Node: Debugging826868 +Node: Debugging Concepts827309 +Node: Debugging Terms829166 +Node: Awk Debugging831741 +Node: Sample Debugging Session832633 +Node: Debugger Invocation833153 +Node: Finding The Bug834537 +Node: List of Debugger Commands841012 +Node: Breakpoint Control842344 +Node: Debugger Execution Control846036 +Node: Viewing And Changing Data849400 +Node: Execution Stack852765 +Node: Debugger Info854403 +Node: Miscellaneous Debugger Commands858420 +Node: Readline Support863612 +Node: Limitations864504 +Node: Debugging Summary866601 +Node: Arbitrary Precision Arithmetic867769 +Node: Computer Arithmetic869185 +Ref: table-numeric-ranges872786 +Ref: Computer Arithmetic-Footnote-1873645 +Node: Math Definitions873702 +Ref: table-ieee-formats876989 +Ref: Math Definitions-Footnote-1877593 +Node: MPFR features877698 +Node: FP Math Caution879367 +Ref: FP Math Caution-Footnote-1880417 +Node: Inexactness of computations880786 +Node: Inexact representation881734 +Node: Comparing FP Values883089 +Node: Errors accumulate884162 +Node: Getting Accuracy885595 +Node: Try To Round888254 +Node: Setting precision889153 +Ref: table-predefined-precision-strings889837 +Node: Setting the rounding mode891631 +Ref: table-gawk-rounding-modes891995 +Ref: Setting the rounding mode-Footnote-1895449 +Node: Arbitrary Precision Integers895628 +Ref: Arbitrary Precision Integers-Footnote-1898619 +Node: POSIX Floating Point Problems898768 +Ref: POSIX Floating Point Problems-Footnote-1902644 +Node: Floating point summary902682 +Node: Dynamic Extensions904874 +Node: Extension Intro906426 +Node: Plugin License907692 +Node: Extension Mechanism Outline908489 +Ref: figure-load-extension908917 +Ref: figure-register-new-function910397 +Ref: figure-call-new-function911401 +Node: Extension API Description913387 +Node: Extension API Functions Introduction914837 +Node: General Data Types919673 +Ref: General Data Types-Footnote-1925360 +Node: Memory Allocation Functions925659 +Ref: Memory Allocation Functions-Footnote-1928489 +Node: Constructor Functions928585 +Node: Registration Functions930319 +Node: Extension Functions931004 +Node: Exit Callback Functions933300 +Node: Extension Version String934548 +Node: Input Parsers935198 +Node: Output Wrappers945013 +Node: Two-way processors949529 +Node: Printing Messages951733 +Ref: Printing Messages-Footnote-1952810 +Node: Updating `ERRNO'952962 +Node: Requesting Values953702 +Ref: table-value-types-returned954430 +Node: Accessing Parameters955388 +Node: Symbol Table Access956619 +Node: Symbol table by name957133 +Node: Symbol table by cookie959113 +Ref: Symbol table by cookie-Footnote-1963252 +Node: Cached values963315 +Ref: Cached values-Footnote-1966819 +Node: Array Manipulation966910 +Ref: Array Manipulation-Footnote-1968008 +Node: Array Data Types968047 +Ref: Array Data Types-Footnote-1970704 +Node: Array Functions970796 +Node: Flattening Arrays974650 +Node: Creating Arrays981537 +Node: Extension API Variables986304 +Node: Extension Versioning986940 +Node: Extension API Informational Variables988841 +Node: Extension API Boilerplate989929 +Node: Finding Extensions993745 +Node: Extension Example994305 +Node: Internal File Description995077 +Node: Internal File Ops999144 +Ref: Internal File Ops-Footnote-11010802 +Node: Using Internal File Ops1010942 +Ref: Using Internal File Ops-Footnote-11013325 +Node: Extension Samples1013598 +Node: Extension Sample File Functions1015122 +Node: Extension Sample Fnmatch1022724 +Node: Extension Sample Fork1024206 +Node: Extension Sample Inplace1025419 +Node: Extension Sample Ord1027094 +Node: Extension Sample Readdir1027930 +Ref: table-readdir-file-types1028786 +Node: Extension Sample Revout1029597 +Node: Extension Sample Rev2way1030188 +Node: Extension Sample Read write array1030929 +Node: Extension Sample Readfile1032868 +Node: Extension Sample Time1033963 +Node: Extension Sample API Tests1035312 +Node: gawkextlib1035803 +Node: Extension summary1038453 +Node: Extension Exercises1042135 +Node: Language History1042857 +Node: V7/SVR3.11044514 +Node: SVR41046695 +Node: POSIX1048140 +Node: BTL1049529 +Node: POSIX/GNU1050263 +Node: Feature History1055832 +Node: Common Extensions1068923 +Node: Ranges and Locales1070247 +Ref: Ranges and Locales-Footnote-11074886 +Ref: Ranges and Locales-Footnote-21074913 +Ref: Ranges and Locales-Footnote-31075147 +Node: Contributors1075368 +Node: History summary1080908 +Node: Installation1082277 +Node: Gawk Distribution1083228 +Node: Getting1083712 +Node: Extracting1084536 +Node: Distribution contents1086178 +Node: Unix Installation1091895 +Node: Quick Installation1092512 +Node: Additional Configuration Options1094954 +Node: Configuration Philosophy1096692 +Node: Non-Unix Installation1099043 +Node: PC Installation1099501 +Node: PC Binary Installation1100812 +Node: PC Compiling1102660 +Ref: PC Compiling-Footnote-11105659 +Node: PC Testing1105764 +Node: PC Using1106940 +Node: Cygwin1111092 +Node: MSYS1111901 +Node: VMS Installation1112399 +Node: VMS Compilation1113195 +Ref: VMS Compilation-Footnote-11114417 +Node: VMS Dynamic Extensions1114475 +Node: VMS Installation Details1115848 +Node: VMS Running1118100 +Node: VMS GNV1120934 +Node: VMS Old Gawk1121657 +Node: Bugs1122127 +Node: Other Versions1126131 +Node: Installation summary1132355 +Node: Notes1133411 +Node: Compatibility Mode1134276 +Node: Additions1135058 +Node: Accessing The Source1135983 +Node: Adding Code1137419 +Node: New Ports1143591 +Node: Derived Files1148072 +Ref: Derived Files-Footnote-11153547 +Ref: Derived Files-Footnote-21153581 +Ref: Derived Files-Footnote-31154177 +Node: Future Extensions1154291 +Node: Implementation Limitations1154897 +Node: Extension Design1156145 +Node: Old Extension Problems1157299 +Ref: Old Extension Problems-Footnote-11158816 +Node: Extension New Mechanism Goals1158873 +Ref: Extension New Mechanism Goals-Footnote-11162233 +Node: Extension Other Design Decisions1162422 +Node: Extension Future Growth1164530 +Node: Old Extension Mechanism1165366 +Node: Notes summary1167128 +Node: Basic Concepts1168314 +Node: Basic High Level1168995 +Ref: figure-general-flow1169267 +Ref: figure-process-flow1169866 +Ref: Basic High Level-Footnote-11173095 +Node: Basic Data Typing1173280 +Node: Glossary1176608 +Node: Copying1201766 +Node: GNU Free Documentation License1239322 +Node: Index1264458 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 119d8ab3..513dea3a 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 @@ -6151,7 +6151,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}). @@ -6199,9 +6199,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. @@ -6219,7 +6219,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 @@ -6605,7 +6605,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}. @@ -6963,7 +6963,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). @@ -7208,7 +7208,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: @@ -8194,7 +8194,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.} @@ -8356,7 +8356,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 @@ -8418,7 +8418,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. @@ -8521,9 +8521,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} @@ -8983,7 +8983,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 @@ -9059,7 +9059,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"}. @@ -10236,7 +10236,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}, @@ -10292,7 +10292,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}, @@ -10785,10 +10785,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. @@ -10914,7 +10914,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 @@ -12945,7 +12945,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. @@ -12960,7 +12960,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 @@ -14369,11 +14369,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 @@ -14384,8 +14384,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. @@ -14400,7 +14400,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 @@ -14637,9 +14637,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. @@ -15306,7 +15306,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 @@ -16100,7 +16100,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 @@ -17267,8 +17267,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. @@ -19257,7 +19257,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. @@ -20505,7 +20505,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 @@ -23419,7 +23419,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 @@ -30271,7 +30271,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. @@ -30547,7 +30547,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. @@ -31209,13 +31209,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. @@ -31234,6 +31234,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 @@ -31266,9 +31269,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. @@ -32479,7 +32479,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 @@ -33344,7 +33344,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 @@ -33919,7 +33919,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 @@ -33950,16 +33959,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 */ @@ -33988,7 +33991,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); @@ -34051,7 +34054,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 @@ -34079,14 +34082,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 @@ -34100,25 +34103,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 @@ -34143,9 +34147,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 @@ -34155,7 +34159,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 @@ -34218,7 +34222,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 @@ -34263,10 +34267,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. @@ -34320,8 +34324,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 @@ -34329,7 +34333,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()} @@ -34537,7 +34542,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 @@ -34629,6 +34634,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 @@ -34704,17 +34712,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 @@ -34745,6 +34742,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} @@ -34760,8 +34768,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. @@ -34770,17 +34777,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 @@ -34871,6 +34875,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, @@ -34894,9 +34901,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. @@ -34928,7 +34932,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 @@ -34945,7 +34949,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 @@ -35027,7 +35031,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 @@ -35100,7 +35104,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}). @@ -35131,14 +35135,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 @@ -35177,7 +35178,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 @@ -35200,7 +35201,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 @@ -35235,8 +35236,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 @@ -35331,7 +35332,7 @@ in the current version of @command{gawk}. @itemize @value{BULLET} @item -Additional built-in variables: +Additional predefined variables: @itemize @value{MINUS} @item @@ -35415,14 +35416,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 @@ -35437,7 +35430,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 @@ -35465,6 +35458,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()}, @@ -35478,30 +35485,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: @@ -35624,7 +35616,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} @@ -36257,33 +36249,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 @@ -36320,6 +36308,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]}; @@ -36327,7 +36316,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. @@ -36633,6 +36622,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 @@ -39154,7 +39148,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 @@ -39895,11 +39889,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 @@ -39918,7 +39912,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 7102d39f..6e4c9567 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 @@ -5935,7 +5935,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}). @@ -5983,9 +5983,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. @@ -6003,7 +6003,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 @@ -6332,7 +6332,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}. @@ -6659,7 +6659,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). @@ -6904,7 +6904,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: @@ -7795,7 +7795,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.} @@ -7957,7 +7957,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 @@ -8019,7 +8019,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. @@ -8122,9 +8122,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} @@ -8584,7 +8584,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 @@ -8660,7 +8660,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"}. @@ -9794,7 +9794,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}, @@ -10257,10 +10257,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. @@ -10386,7 +10386,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 @@ -12278,7 +12278,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. @@ -12293,7 +12293,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 @@ -13702,11 +13702,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 @@ -13717,8 +13717,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. @@ -13733,7 +13733,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 @@ -13970,9 +13970,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. @@ -14593,7 +14593,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 @@ -15387,7 +15387,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 @@ -16554,8 +16554,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. @@ -18383,7 +18383,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. @@ -19631,7 +19631,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 @@ -22516,7 +22516,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 @@ -29368,7 +29368,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. @@ -29644,7 +29644,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. @@ -30306,13 +30306,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. @@ -30331,6 +30331,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 @@ -30363,9 +30366,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. @@ -31576,7 +31576,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 @@ -32441,7 +32441,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 @@ -33016,7 +33016,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 @@ -33047,16 +33056,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 */ @@ -33085,7 +33088,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); @@ -33148,7 +33151,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 @@ -33176,14 +33179,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 @@ -33197,25 +33200,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 @@ -33240,9 +33244,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 @@ -33252,7 +33256,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 @@ -33315,7 +33319,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 @@ -33360,10 +33364,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. @@ -33417,8 +33421,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 @@ -33426,7 +33430,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()} @@ -33634,7 +33639,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 @@ -33726,6 +33731,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 @@ -33801,17 +33809,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 @@ -33842,6 +33839,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} @@ -33857,8 +33865,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. @@ -33867,17 +33874,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 @@ -33968,6 +33972,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, @@ -33991,9 +33998,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. @@ -34025,7 +34029,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 @@ -34042,7 +34046,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 @@ -34124,7 +34128,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 @@ -34197,7 +34201,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}). @@ -34228,14 +34232,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 @@ -34274,7 +34275,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 @@ -34297,7 +34298,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 @@ -34332,8 +34333,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 @@ -34428,7 +34429,7 @@ in the current version of @command{gawk}. @itemize @value{BULLET} @item -Additional built-in variables: +Additional predefined variables: @itemize @value{MINUS} @item @@ -34512,14 +34513,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 @@ -34534,7 +34527,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 @@ -34562,6 +34555,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()}, @@ -34575,30 +34582,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: @@ -34721,7 +34713,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} @@ -35354,33 +35346,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 @@ -35417,6 +35405,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]}; @@ -35424,7 +35413,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. @@ -35730,6 +35719,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 @@ -38251,7 +38245,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 @@ -38992,11 +38986,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 @@ -39015,7 +39009,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 |