diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 80 | ||||
| -rw-r--r-- | doc/Makefile.in | 60 | ||||
| -rw-r--r-- | doc/gawk.1 | 10 | ||||
| -rw-r--r-- | doc/gawk.info | 1890 | ||||
| -rw-r--r-- | doc/gawk.texi | 959 | ||||
| -rw-r--r-- | doc/gawktexi.in | 941 | ||||
| -rw-r--r-- | doc/texinfo.tex | 31 |
7 files changed, 2247 insertions, 1724 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index fc2a1354..10f0165c 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,83 @@ +2013-12-21 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Additional Configuration Options): Document + the --disable-extensions option. + +2013-12-12 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Fix the presentation of asort() and asorti(). + Thanks to Andy Schorr for pointing out the problems. + +2013-11-28 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Update quotations to use @author, fix a few + placements of footnotes. + +2013-11-08 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Update the list of files included in the gawk + distribution and fix a few typos. + +2013-11-03 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Fix the section and subsection headings in + the Preface. Also change the short title page to just + "GNU Awk". + +2013-10-31 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Add @shorttitlepage command. + +2013-10-25 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Contributors): Update with more info. + (Distributtion contents): Ditto. + General: Remove all hyphens when used with "multi" prefix. + +2013-10-22 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Other Environment Variables): Document GAWK_MSG_SRC + variable and fix documentation of *_CHAIN_MAX variables. + +2013-10-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Conversion, Printf Ordering): Better wording for + descriptions of CONVFMT. Thanks to Hermann Peifer. + +2013-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Other Versions): Updated info on MKS awk and + some other links. + +2013-09-24 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Readfile function): New node. + +2013-09-22 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (FN, FFN, DF,DDF, PVERSION, CTL): Remove macros. + They have no alternate versions and are just in the way. + +2013-08-15 Arnold D. Robbins <arnold@skeeve.com> + + * gawk.1: Document that ENVIRON updates affect the environment. + * gawktexi.in: Ditto. + +2013-06-27 Arnold D. Robbins <arnold@skeeve.com> + + * texinfo.tex: Update from Karl, fixes a formating problem. + * gawktexi.in (Conversions): Undo @w{} around @option{--posix}. + +2013-06-22 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Type Functions): Add more explanation to isarray(), + including that it makes no sense to call it at the global level. + +2013-06-03 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Make it crystal clear not to use delete with FUNCTAB, + or attempt to assign to it. + 2013-05-29 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in (Internal File Description): Add "devbsize" element diff --git a/doc/Makefile.in b/doc/Makefile.in index 41f65b0d..52e5f873 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,7 +1,7 @@ -# Makefile.in generated by automake 1.13.1 from Makefile.am. +# Makefile.in generated by automake 1.13.4 from Makefile.am. # @configure_input@ -# Copyright (C) 1994-2012 Free Software Foundation, Inc. +# Copyright (C) 1994-2013 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, @@ -38,23 +38,51 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA # VPATH = @srcdir@ -am__make_dryrun = \ - { \ - am__dry=no; \ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ case $$MAKEFLAGS in \ *\\[\ \ ]*) \ - echo 'am--echo: ; @echo "AM" OK' | $(MAKE) -f - 2>/dev/null \ - | grep '^AM OK$$' >/dev/null || am__dry=yes;; \ - *) \ - for am__flg in $$MAKEFLAGS; do \ - case $$am__flg in \ - *=*|--*) ;; \ - *n*) am__dry=yes; break;; \ - esac; \ - done;; \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ esac; \ - test $$am__dry = yes; \ - } + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) pkgdatadir = $(datadir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ @@ -13,7 +13,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "May 09 2013" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Aug 15 2013" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -917,11 +917,17 @@ An array containing the values of the current environment. The array is indexed by the environment variables, each element being the value of that variable (e.g., \fBENVIRON["HOME"]\fP might be \fB"/home/arnold"\fR). -Changing this array does not affect the environment seen by programs which +.sp +In POSIX mode, +changing this array does not affect the environment seen by programs which .I gawk spawns via redirection or the .B system() function. +Otherwise, +.I gawk +updates its real environment so that programs it spawns see +the changes. .TP .B ERRNO If a system error occurs either doing a redirection for diff --git a/doc/gawk.info b/doc/gawk.info index bc407397..845d3be3 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -196,7 +196,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Field Splitting Summary:: Some final points and a summary table. * Constant Size:: Reading constant width data. * Splitting By Content:: Defining Fields By Content -* Multiple Line:: Reading multi-line records. +* Multiple Line:: Reading multiline records. * Getline:: Reading files under explicit program control using the `getline' function. @@ -347,9 +347,9 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) `awk'. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. -* Multi-dimensional:: Emulating multidimensional arrays in +* Multidimensional:: Emulating multidimensional arrays in `awk'. -* Multi-scanning:: Scanning multidimensional arrays. +* Multiscanning:: Scanning multidimensional arrays. * Arrays of Arrays:: True multidimensional arrays. * Built-in:: Summarizes the built-in functions. * Calling Built-in:: How to call built-in functions. @@ -401,6 +401,8 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. +* Readfile Function:: A function to read an entire file at + once. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -1079,11 +1081,11 @@ by first pressing and holding the `CONTROL' key, next pressing the `d' key and finally releasing both keys. Dark Corners -............ +------------ Dark corners are basically fractal -- no matter how much you - illuminate, there's always a smaller but darker one. - Brian Kernighan + illuminate, there's always a smaller but darker one. -- Brian + Kernighan Until the POSIX standard (and `GAWK: Effective AWK Programming'), many features of `awk' were either poorly documented or not documented @@ -1819,7 +1821,7 @@ information). Using this information, create your own `BBS-list' and If you are using the stand-alone version of Info, see *note Extract Program::, for an `awk' program that extracts these data files from -`gawk.texi', the Texinfo source file for this Info file. +`gawk.texi', the (generated) Texinfo source file for this Info file. File: gawk.info, Node: Very Simple, Next: Two Rules, Prev: Sample Data Files, Up: Getting Started @@ -2849,10 +2851,6 @@ used by regular users. the `gawk' developers for testing and tuning. They are subject to change. The variables are: -`AVG_CHAIN_MAX' - The average number of items `gawk' will maintain on a hash chain - for managing arrays. - `AWK_HASH' If this variable exists with a value of `gst', `gawk' will switch to using the hash function from GNU Smalltalk for managing arrays. @@ -2864,6 +2862,13 @@ change. The variables are: debugging problems on filesystems on non-POSIX operating systems where I/O is performed in records, not in blocks. +`GAWK_MSG_SRC' + If this variable exists, `gawk' includes the source file name and + line number from which warning and/or fatal messages are + generated. Its purpose is to help isolate the source of a + message, since there can be multiple places which produce the same + warning or error message. + `GAWK_NO_DFA' If this variable exists, `gawk' does not use the DFA regexp matcher for "does it match" kinds of tests. This can cause `gawk' to be @@ -2876,6 +2881,14 @@ change. The variables are: This specifies the amount by which `gawk' should grow its internal evaluation stack, when needed. +`INT_CHAIN_MAX' + The average number of items `gawk' will maintain on a hash chain + for managing arrays indexed by integers. + +`STR_CHAIN_MAX' + The average number of items `gawk' will maintain on a hash chain + for managing arrays indexed by strings. + `TIDYMEM' If this variable exists, `gawk' uses the `mtrace()' library calls from GNU LIBC to help track down possible memory leaks. @@ -3052,8 +3065,7 @@ File: gawk.info, Node: Undocumented, Prev: Obsolete, Up: Invoking Gawk 2.10 Undocumented Options and Features ====================================== - Use the Source, Luke! - Obi-Wan + Use the Source, Luke! -- Obi-Wan This minor node intentionally left blank. @@ -3876,7 +3888,7 @@ have to be named on the `awk' command line (*note Getline::). * Field Separators:: The field separator and how to change it. * Constant Size:: Reading constant width data. * Splitting By Content:: Defining Fields By Content -* Multiple Line:: Reading multi-line records. +* Multiple Line:: Reading multiline records. * Getline:: Reading files under explicit program control using the `getline' function. * Read Timeout:: Reading input with a timeout. @@ -5291,8 +5303,7 @@ File: gawk.info, Node: Getline/Pipe, Next: Getline/Variable/Pipe, Prev: Getli --------------------------------- Omniscience has much to recommend it. Failing that, attention to - details would be useful. - Brian Kernighan + details would be useful. -- Brian Kernighan The output of a command can also be piped into `getline', using `COMMAND | getline'. In this case, the string COMMAND is run as a @@ -7095,7 +7106,7 @@ controlled by the `awk' built-in variable `CONVFMT' (*note Built-in Variables::). Numbers are converted using the `sprintf()' function with `CONVFMT' as the format specifier (*note String Functions::). - `CONVFMT''s default value is `"%.6g"', which prints a value with at + `CONVFMT''s default value is `"%.6g"', which creates a value with at most six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, 17 digits is usually enough to capture a floating-point number's value @@ -7302,8 +7313,7 @@ File: gawk.info, Node: Concatenation, Next: Assignment Ops, Prev: Arithmetic 6.2.2 String Concatenation -------------------------- - It seemed like a good idea at the time. - Brian Kernighan + It seemed like a good idea at the time. -- Brian Kernighan There is only one string operation: concatenation. It does not have a specific operator to represent it. Instead, concatenation is @@ -7609,8 +7619,7 @@ is a summary of increment and decrement expressions: Operator Evaluation Order Doctor, doctor! It hurts when I do this! - So don't do that! - Groucho Marx + So don't do that! -- Groucho Marx What happens for something like the following? @@ -7691,8 +7700,8 @@ File: gawk.info, Node: Typing and Comparison, Next: Boolean Ops, Prev: Truth 6.3.2 Variable Typing and Comparison Expressions ------------------------------------------------ - The Guide is definitive. Reality is frequently inaccurate. - The Hitchhiker's Guide to the Galaxy + The Guide is definitive. Reality is frequently inaccurate. -- The + Hitchhiker's Guide to the Galaxy Unlike other programming languages, `awk' variables do not have a fixed type. Instead, they can be either a number or a string, depending @@ -9495,7 +9504,7 @@ specific to `gawk' are marked with a pound sign (`#'). `FS' This is the input field separator (*note Field Separators::). The - value is a single-character string or a multi-character regular + value is a single-character string or a multicharacter regular expression that matches the separations between fields in an input record. If the value is the null string (`""'), then each character in the record becomes a separate field. (This behavior @@ -9597,7 +9606,7 @@ specific to `gawk' are marked with a pound sign (`#'). This is the subscript separator. It has the default value of `"\034"' and is used to separate the parts of the indices of a multidimensional array. Thus, the expression `foo["A", "B"]' - really accesses `foo["A\034B"]' (*note Multi-dimensional::). + really accesses `foo["A\034B"]' (*note Multidimensional::). `TEXTDOMAIN #' This variable is used for internationalization of programs at the @@ -9679,9 +9688,18 @@ with a pound sign (`#'). An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of the particular environment variables. For - example, `ENVIRON["HOME"]' might be `/home/arnold'. Changing this - array does not affect the environment passed on to any programs - that `awk' may spawn via redirection or the `system()' function. + example, `ENVIRON["HOME"]' might be `/home/arnold'. + + For POSIX `awk', changing this array does not affect the + environment passed on to any programs that `awk' may spawn via + redirection or the `system()' function. + + However, beginning with version 4.2, if not in POSIX compatibility + mode, `gawk' does update its own environment when `ENVIRON' is + changed, thus changing the environment seen by programs that it + creates. You should therefore be especially careful if you modify + `ENVIRON["PATH"]"', which is the search path for finding + executable programs. Some operating systems may not have environment variables. On such systems, the `ENVIRON' array is empty (except for @@ -9737,8 +9755,11 @@ with a pound sign (`#'). `FUNCTAB #' An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. - *NOTE*: You may not use the `delete' statement with the `FUNCTAB' - array. + + NOTE: Attempting to use the `delete' statement with the + `FUNCTAB' array will cause a fatal error. Any attempt to + assign to an element of the `FUNCTAB' array will also cause a + fatal error. `NR' The number of input records `awk' has processed since the @@ -10085,7 +10106,7 @@ cannot have a variable and an array with the same name in the same * Numeric Array Subscripts:: How to use numbers as subscripts in `awk'. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. -* Multi-dimensional:: Emulating multidimensional arrays in +* Multidimensional:: Emulating multidimensional arrays in `awk'. * Arrays of Arrays:: True multidimensional arrays. @@ -10117,8 +10138,7 @@ File: gawk.info, Node: Array Intro, Next: Reference to Elements, Up: Array Ba ---------------------------- Doing linear scans over an associative array is like trying to - club someone to death with a loaded Uzi. - Larry Wall + club someone to death with a loaded Uzi. -- Larry Wall The `awk' language provides one-dimensional arrays for storing groups of related strings or numbers. Every `awk' array must have a @@ -10428,42 +10448,45 @@ available: default `awk' behavior. `"@ind_str_asc"' - Order by indices compared as strings; this is the most basic sort. - (Internally, array indices are always strings, so with `a[2*5] = 1' - the index is `"10"' rather than numeric 10.) + Order by indices in ascending order compared as strings; this is + the most basic sort. (Internally, array indices are always + strings, so with `a[2*5] = 1' the index is `"10"' rather than + numeric 10.) `"@ind_num_asc"' - Order by indices but force them to be treated as numbers in the - process. Any index with a non-numeric value will end up - positioned as if it were zero. + Order by indices in ascending order but force them to be treated + as numbers in the process. Any index with a non-numeric value + will end up positioned as if it were zero. `"@val_type_asc"' - Order by element values rather than indices. Ordering is by the - type assigned to the element (*note Typing and Comparison::). All - numeric values come before all string values, which in turn come - before all subarrays. (Subarrays have not been described yet; - *note Arrays of Arrays::). + Order by element values in ascending order (rather than by + indices). Ordering is by the type assigned to the element (*note + Typing and Comparison::). All numeric values come before all + string values, which in turn come before all subarrays. + (Subarrays have not been described yet; *note Arrays of Arrays::.) `"@val_str_asc"' - Order by element values rather than by indices. Scalar values are - compared as strings. Subarrays, if present, come out last. + Order by element values in ascending order (rather than by + indices). Scalar values are compared as strings. Subarrays, if + present, come out last. `"@val_num_asc"' - Order by element values rather than by indices. Scalar values are - compared as numbers. Subarrays, if present, come out last. When - numeric values are equal, the string values are used to provide an - ordering: this guarantees consistent results across different - versions of the C `qsort()' function,(1) which `gawk' uses - internally to perform the sorting. + Order by element values in ascending order (rather than by + indices). Scalar values are compared as numbers. Subarrays, if + present, come out last. When numeric values are equal, the string + values are used to provide an ordering: this guarantees consistent + results across different versions of the C `qsort()' function,(1) + which `gawk' uses internally to perform the sorting. `"@ind_str_desc"' - Reverse order from the most basic sort. + String indices ordered from high to low. `"@ind_num_desc"' Numeric indices ordered from high to low. `"@val_type_desc"' - Element values, based on type, in descending order. + Element values, based on type, ordered from high to low. + Subarrays, if present, come out first. `"@val_str_desc"' Element values, treated as strings, ordered from high to low. @@ -10666,7 +10689,7 @@ knowledge of the actual rules since they can sometimes have a subtle effect on your programs. -File: gawk.info, Node: Uninitialized Subscripts, Next: Multi-dimensional, Prev: Numeric Array Subscripts, Up: Arrays +File: gawk.info, Node: Uninitialized Subscripts, Next: Multidimensional, Prev: Numeric Array Subscripts, Up: Arrays 8.4 Using Uninitialized Variables as Subscripts =============================================== @@ -10714,14 +10737,14 @@ string as a subscript if `--lint' is provided on the command line (*note Options::). -File: gawk.info, Node: Multi-dimensional, Next: Arrays of Arrays, Prev: Uninitialized Subscripts, Up: Arrays +File: gawk.info, Node: Multidimensional, Next: Arrays of Arrays, Prev: Uninitialized Subscripts, Up: Arrays 8.5 Multidimensional Arrays =========================== * Menu: -* Multi-scanning:: Scanning multidimensional arrays. +* Multiscanning:: Scanning multidimensional arrays. A multidimensional array is an array in which an element is identified by a sequence of indices instead of a single index. For @@ -10800,7 +10823,7 @@ the program produces the following output: 3 2 1 6 -File: gawk.info, Node: Multi-scanning, Up: Multi-dimensional +File: gawk.info, Node: Multiscanning, Up: Multidimensional 8.5.1 Scanning Multidimensional Arrays -------------------------------------- @@ -10840,7 +10863,7 @@ The result is to set `separate[1]' to `"1"' and `separate[2]' to recovered. -File: gawk.info, Node: Arrays of Arrays, Prev: Multi-dimensional, Up: Arrays +File: gawk.info, Node: Arrays of Arrays, Prev: Multidimensional, Up: Arrays 8.6 Arrays of Arrays ==================== @@ -11176,13 +11199,15 @@ File: gawk.info, Node: String Functions, Next: I/O Functions, Prev: Numeric F ----------------------------------- The functions in this minor node look at or change the text of one or -more strings. `gawk' understands locales (*note Locales::), and does -all string processing in terms of _characters_, not _bytes_. This -distinction is particularly important to understand for locales where -one character may be represented by multiple bytes. Thus, for example, -`length()' returns the number of characters in a string, and not the -number of bytes used to represent those characters, Similarly, -`index()' works with character indices, and not byte indices. +more strings. + + `gawk' understands locales (*note Locales::), and does all string +processing in terms of _characters_, not _bytes_. This distinction is +particularly important to understand for locales where one character +may be represented by multiple bytes. Thus, for example, `length()' +returns the number of characters in a string, and not the number of +bytes used to represent those characters. Similarly, `index()' works +with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets ([ ]). Several functions perform string substitution; the @@ -11198,26 +11223,26 @@ pound sign (`#'): `gensub()'. `asort(SOURCE [, DEST [, HOW ] ]) #' - Return the number of elements in the array SOURCE. `gawk' sorts - the contents of SOURCE and replaces the indices of the sorted - values of SOURCE with sequential integers starting with one. If - the optional array DEST is specified, then SOURCE is duplicated - into DEST. DEST is then sorted, leaving the indices of SOURCE - unchanged. The optional third argument HOW is a string which - controls the rule for comparing values, and the sort direction. A - single space is required between the comparison mode, `string' or - `number', and the direction specification, `ascending' or - `descending'. You can omit direction and/or mode in which case it - will default to `ascending' and `string', respectively. An empty - string "" is the same as the default `"ascending string"' for the - value of HOW. If the `source' array contains subarrays as values, - they will come out last(first) in the `dest' array for - `ascending'(`descending') order specification. The value of - `IGNORECASE' affects the sorting. The third argument can also be - a user-defined function name in which case the value returned by - the function is used to order the array elements before - constructing the result array. *Note Array Sorting Functions::, - for more information. +`asorti(SOURCE [, DEST [, HOW ] ]) #' + These two functions are similar in behavior, so they are described + together. + + NOTE: The following description ignores the third argument, + HOW, since it requires understanding features that we have + not discussed yet. Thus, the discussion here is a deliberate + simplification. (We do provide all the details later on: + *Note Array Sorting Functions::, for the full story.) + + Both functions return the number of elements in the array SOURCE. + For `asort()', `gawk' sorts the values of SOURCE and replaces the + indices of the sorted values of SOURCE with sequential integers + starting with one. If the optional array DEST is specified, then + SOURCE is duplicated into DEST. DEST is then sorted, leaving the + indices of SOURCE unchanged. + + When comparing strings, `IGNORECASE' affects the sorting. If the + SOURCE array contains subarrays as values (*note Arrays of + Arrays::), they will come last, after all scalar values. For example, if the contents of `a' are as follows: @@ -11235,23 +11260,16 @@ pound sign (`#'): a[2] = "de" a[3] = "sac" - In order to reverse the direction of the sorted results in the - above example, `asort()' can be called with three arguments as - follows: - - asort(a, a, "descending") + The `asorti()' function works similarly to `asort()', however, the + _indices_ are sorted, instead of the values. Thus, in the previous + example, starting with the same initial set of indices and values + in `a', calling `asorti(a)' would yield: - The `asort()' function is described in more detail in *note Array - Sorting Functions::. `asort()' is a `gawk' extension; it is not - available in compatibility mode (*note Options::). - -`asorti(SOURCE [, DEST [, HOW ] ]) #' - Return the number of elements in the array SOURCE. It works - similarly to `asort()', however, the _indices_ are sorted, instead - of the values. (Here too, `IGNORECASE' affects the sorting.) + a[1] = "first" + a[2] = "last" + a[3] = "middle" - The `asorti()' function is described in more detail in *note Array - Sorting Functions::. `asorti()' is a `gawk' extension; it is not + `asort()' and `asorti()' are `gawk' extensions; they are not available in compatibility mode (*note Options::). `gensub(REGEXP, REPLACEMENT, HOW [, TARGET]) #' @@ -12414,7 +12432,7 @@ File: gawk.info, Node: Bitwise Functions, Next: Type Functions, Prev: Time Fu 9.1.6 Bit-Manipulation Functions -------------------------------- - I can explain it for you, but I can't understand it for you. + I can explain it for you, but I can't understand it for you. -- Anonymous Many languages provide the ability to perform "bitwise" operations @@ -12554,6 +12572,19 @@ of Arrays::). `isarray(X)' Return a true value if X is an array. Otherwise return false. + `isarray()' is meant for use in two circumstances. The first is when +traversing a multidimensional array: you can test if an element is +itself an array or not. The second is inside the body of a +user-defined function (not discussed yet; *note User-defined::), to +test if a paramater is an array or not. + + Note, however, that using `isarray()' at the global level to test +variables makes no sense. Since you are the one writing the program, you +are supposed to know if your variables are arrays or not. And in fact, +due to the way `gawk' works, if you pass the name of a variable that +has not been previously used to `isarray()', `gawk' will end up turning +it into a scalar. + File: gawk.info, Node: I18N Functions, Prev: Type Functions, Up: Built-in @@ -13471,7 +13502,7 @@ algorithms and program tasks in a single place. It simplifies programming, making program development more manageable, and making programs more readable. - In their seminal 1976 book, `Software Tools'(1), Brian Kernighan and + In their seminal 1976 book, `Software Tools',(1) Brian Kernighan and P.J. Plauger wrote: Good Programming is not learned from generalities, but by seeing @@ -13647,6 +13678,7 @@ programming use. vice versa. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. +* Readfile Function:: A function to read an entire file at once. File: gawk.info, Node: Strtonum Function, Next: Assert Function, Up: General Functions @@ -14039,7 +14071,7 @@ concatenation. The lack of an explicit operator for concatenation makes string operations more difficult than they really need to be. -File: gawk.info, Node: Getlocaltime Function, Prev: Join Function, Up: General Functions +File: gawk.info, Node: Getlocaltime Function, Next: Readfile Function, Prev: Join Function, Up: General Functions 10.2.7 Managing the Time of Day ------------------------------- @@ -14121,6 +14153,66 @@ the `getlocaltime()' function would have allowed the user to supply an optional timestamp value to use instead of the current time. +File: gawk.info, Node: Readfile Function, Prev: Getlocaltime Function, Up: General Functions + +10.2.8 Reading A Whole File At Once +----------------------------------- + +Often, it is convenient to have the entire contents of a file available +in memory as a single string. A straightforward but naive way to do +that might be as follows: + + function readfile(file, tmp, contents) + { + if ((getline tmp < file) < 0) + return + + contents = tmp + while (getline tmp < file) > 0) + contents = contents RT tmp + + close(file) + return contents + } + + This function reads from `file' one record at a time, building up +the full contents of the file in the local variable `contents'. It +works, but is not necessarily efficient. + + The following function, based on a suggestion by Denis Shirokov, +reads the entire contents of the named file in one shot: + + # readfile.awk --- read an entire file at once + + function readfile(file, tmp, save_rs) + { + save_rs = RS + RS = "^$" + getline tmp < file + close(file) + RS = save_rs + + return tmp + } + + It works by setting `RS' to `^$', a regular expression that will +never match if the file has contents. `gawk' reads data from the file +into `tmp' attempting to match `RS'. The match fails after each read, +but fails quickly, such that `gawk' fills `tmp' with the entire +contents of the file. (*Note Records::, for information on `RT' and +`RS'.) + + In the case that `file' is empty, the return value is the null +string. Thus calling code may use something like: + + contents = readfile("/some/path") + if (length(contents) == 0) + # file was empty ... + + This tests the result to see if it is empty or not. An equivalent +test would be `contents == ""'. + + File: gawk.info, Node: Data File Management, Next: Getopt Function, Prev: General Functions, Up: Library Functions 10.3 Data File Management @@ -14527,7 +14619,7 @@ characters (*note String Functions::).(1) # <c> a character representing the current option # Private Data: - # _opti -- index in multi-flag option, e.g., -abc + # _opti -- index in multiflag option, e.g., -abc The function starts out with comments presenting a list of the global variables it uses, what the return values are, what they mean, @@ -16550,8 +16642,8 @@ File: gawk.info, Node: Alarm Program, Next: Translate Program, Prev: Dupword 11.3.2 An Alarm Clock Program ----------------------------- - Nothing cures insomnia like a ringing alarm clock. - Arnold Robbins + Nothing cures insomnia like a ringing alarm clock. -- Arnold + Robbins The following program is a simple "alarm clock" program. You give it a time of day and an optional message. At the specified time, it @@ -16795,10 +16887,10 @@ program. ---------- Footnotes ---------- - (1) On some older systems, `tr' may require that the lists be -written as range expressions enclosed in square brackets (`[a-z]') and -quoted, to prevent the shell from attempting a file name expansion. -This is not a feature. + (1) On some older systems, including Solaris, `tr' may require that +the lists be written as range expressions enclosed in square brackets +(`[a-z]') and quoted, to prevent the shell from attempting a file name +expansion. This is not a feature. (2) This program was written before `gawk' acquired the ability to split each character in a string into separate array elements. @@ -17108,11 +17200,11 @@ are simply removed. `extract.awk' uses the `join()' library function (*note Join Function::). The example programs in the online Texinfo source for `GAWK: -Effective AWK Programming' (`gawk.texi') have all been bracketed inside -`file' and `endfile' lines. The `gawk' distribution uses a copy of -`extract.awk' to extract the sample programs and install many of them -in a standard directory where `gawk' can find them. The Texinfo file -looks something like this: +Effective AWK Programming' (`gawktexi.in') have all been bracketed +inside `file' and `endfile' lines. The `gawk' distribution uses a copy +of `extract.awk' to extract the sample programs and install many of +them in a standard directory where `gawk' can find them. The Texinfo +file looks something like this: ... This program has a @code{BEGIN} rule, @@ -17864,8 +17956,8 @@ File: gawk.info, Node: Advanced Features, Next: Internationalization, Prev: S ****************************** Write documentation as if whoever reads it is a violent psychopath - who knows where you live. - Steve English, as quoted by Peter Langston + who knows where you live. -- Steve English, as quoted by Peter + Langston This major node discusses advanced features in `gawk'. It's a bit of a "grab bag" of items that are otherwise unrelated to each other. @@ -18141,7 +18233,7 @@ seemingly ordered data: function cmp_randomize(i1, v1, i2, v2) { - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) } @@ -18155,7 +18247,7 @@ elements with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, so consider it only if necessary. The following comparison functions force a deterministic order, and are based on the -fact that the indices of two elements are never equal: +fact that the (string) indices of two elements are never equal: function cmp_numeric(i1, v1, i2, v2) { @@ -18214,9 +18306,9 @@ functions (*note String Functions::) for sorting arrays. For example: After the call to `asort()', the array `data' is indexed from 1 to some number N, the total number of elements in `data'. (This count is `asort()''s return value.) `data[1]' <= `data[2]' <= `data[3]', and so -on. The comparison is based on the type of the elements (*note Typing -and Comparison::). All numeric values come before all string values, -which in turn come before all subarrays. +on. The default comparison is based on the type of the elements (*note +Typing and Comparison::). All numeric values come before all string +values, which in turn come before all subarrays. An important side effect of calling `asort()' is that _the array's original indices are irrevocably lost_. As this isn't always @@ -18231,21 +18323,11 @@ desirable, `asort()' accepts a second argument: and then sorts `dest', destroying its indices. However, the `source' array is not affected. - `asort()' accepts a third string argument to control comparison of -array elements. As with `PROCINFO["sorted_in"]', this argument may be -one of the predefined names that `gawk' provides (*note Controlling -Scanning::), or the name of a user-defined function (*note Controlling -Array Traversal::). - - NOTE: In all cases, the sorted element values consist of the - original array's element values. The ability to control - comparison merely affects the way in which they are sorted. - Often, what's needed is to sort on the values of the _indices_ instead of the values of the elements. To do that, use the `asorti()' -function. The interface is identical to that of `asort()', except that -the index values are used for sorting, and become the values of the -result array: +function. The interface and behavior are identical to that of +`asort()', except that the index values are used for sorting, and +become the values of the result array: { source[$0] = some_func($0) } @@ -18260,32 +18342,41 @@ result array: } } - Similar to `asort()', in all cases, the sorted element values -consist of the original array's indices. The ability to control -comparison merely affects the way in which they are sorted. - - Sorting the array by replacing the indices provides maximal -flexibility. To traverse the elements in decreasing order, use a loop -that goes from N down to 1, either over the elements or over the -indices.(1) - - Copying array indices and elements isn't expensive in terms of -memory. Internally, `gawk' maintains "reference counts" to data. For -example, when `asort()' copies the first array to the second one, there -is only one copy of the original array elements' data, even though both -arrays use the values. + So far, so good. Now it starts to get interesting. Both `asort()' +and `asorti()' accept a third string argument to control comparison of +array elements. In *note String Functions::, we ignored this third +argument; however, the time has now come to describe how this argument +affects these two functions. + + Basically, the third argument specifies how the array is to be +sorted. There are two possibilities. As with `PROCINFO["sorted_in"]', +this argument may be one of the predefined names that `gawk' provides +(*note Controlling Scanning::), or it may be the name of a user-defined +function (*note Controlling Array Traversal::). + + In the latter case, _the function can compare elements in any way it +chooses_, taking into account just the indices, just the values, or +both. This is extremely powerful. + + Once the array is sorted, `asort()' takes the _values_ in their +final order, and uses them to fill in the result array, whereas +`asorti()' takes the _indices_ in their final order, and uses them to +fill in the result array. + + NOTE: Copying array indices and elements isn't expensive in terms + of memory. Internally, `gawk' maintains "reference counts" to + data. For example, when `asort()' copies the first array to the + second one, there is only one copy of the original array elements' + data, even though both arrays use the values. Because `IGNORECASE' affects string comparisons, the value of `IGNORECASE' also affects sorting for both `asort()' and `asorti()'. Note also that the locale's sorting order does _not_ come into play; -comparisons are based on character values only.(2) Caveat Emptor. +comparisons are based on character values only.(1) Caveat Emptor. ---------- Footnotes ---------- - (1) You may also use one of the predefined sorting names that sorts -in decreasing order. - - (2) This is true because locale-based comparison occurs only when in + (1) This is true because locale-based comparison occurs only when in POSIX compatibility mode, and since `asort()' and `asorti()' are `gawk' extensions, they are not available in that case. @@ -20362,8 +20453,7 @@ File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic Extension authority; they tend to believe that all digits of a printed answer are significant. Disillusioned computer users have just the opposite approach; they are constantly afraid that their answers - are almost meaningless. - Donald Knuth(1) + are almost meaningless.(1) -- Donald Knuth This major node discusses issues that you may encounter when performing arithmetic. It begins by discussing some of the general @@ -20492,7 +20582,7 @@ automatic conversion (via `CONVFMT') and from printing (via `OFMT'). what the default string representations show. `CONVFMT''s default value is `"%.6g"', which yields a value with at -least six significant digits. For some applications, you might want to +most six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, most of the time, 17 digits is enough to capture a floating-point number's value exactly.(1) @@ -21244,9 +21334,7 @@ File: gawk.info, Node: Changing Precision, Next: Exact Arithmetic, Prev: Floa them to full membership of the high-precision club, or do we treat them and all their associates as second-class citizens? Sometimes the first course is proper, sometimes the second, and it takes - careful analysis to tell which. - - Dirk Laurie(1) + careful analysis to tell which.(1) -- Dirk Laurie `gawk' does not implicitly modify the precision of any previously computed results when the working precision is changed with an @@ -21754,12 +21842,9 @@ File: gawk.info, Node: General Data Types, Next: Requesting Values, Prev: Ext 16.4.2 General Purpose Data Types --------------------------------- - I have a true love/hate relationship with unions. - Arnold Robbins - - That's the thing about unions: the compiler will arrange things so - they can accommodate both love and hate. - Chet Ramey + I have a true love/hate relationship with unions. -- Arnold + Robbins That's the thing about unions: the compiler will arrange + things so they can accommodate both love and hate. -- Chet Ramey The extension API defines a number of simple types and structures for general purpose use. Additional, more specialized, data structures @@ -23542,8 +23627,7 @@ File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev: Find 16.6 Example: Some File Functions ================================= - No matter where you go, there you are. - Buckaroo Bonzai + No matter where you go, there you are. -- Buckaroo Bonzai Two useful functions that are not in `awk' are `chdir()' (so that an `awk' program can change its directory) and `stat()' (so that an `awk' @@ -24233,7 +24317,7 @@ follows: The usage is: The `fts()' function provides a hook to the C library `fts()' routines for traversing file hierarchies. Instead of returning data -about one file at a time in a stream, it fills in a multi-dimensional +about one file at a time in a stream, it fills in a multidimensional array with data about each file and directory encountered in the requested hierarchies. @@ -24328,7 +24412,7 @@ Otherwise it returns -1. 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 multi-dimensional array to represent the file + simply creating a multidimensional array to represent the file hierarchy and its information. See `test/fts.awk' in the `gawk' distribution for an example. @@ -24866,7 +24950,7 @@ the changes, with cross-references to further details: * Multiple `BEGIN' and `END' rules (*note BEGIN/END::). - * Multidimensional arrays (*note Multi-dimensional::). + * Multidimensional arrays (*note Multidimensional::). File: gawk.info, Node: SVR4, Next: POSIX, Prev: V7/SVR3.1, Up: Language History @@ -25274,8 +25358,7 @@ File: gawk.info, Node: Contributors, Prev: Ranges and Locales, Up: Language H A.8 Major Contributors to `gawk' ================================ - Always give credit where credit is due. - Anonymous + Always give credit where credit is due. -- Anonymous This minor node names the major contributors to `gawk' and/or this Info file, in approximate chronological order: @@ -25377,6 +25460,9 @@ Info file, in approximate chronological order: - The modifications to convert `gawk' into a byte-code interpreter, including the debugger. + - The addition of true multidimensional arrays. *note Arrays + of Arrays::. + - The additional modifications for support of arbitrary precision arithmetic. @@ -25387,6 +25473,9 @@ Info file, in approximate chronological order: - Improved array internals for arrays indexed by integers. + - The improved array sorting features were driven by John + together with Pat Rankin. + * Efraim Yawitz contributed the original text for *note Debugger::. * The development of the extension API first released with `gawk' @@ -25509,6 +25598,13 @@ to different non-Unix operating systems: Various `.c', `.y', and `.h' files The actual `gawk' source code. +`ABOUT-NLS' + Information about GNU `gettext' and translations. + +`AUTHORS' + A file with some information about the authorship of `gawk'. It + exists only to satisfy the pedants at the Free Software Foundation. + `README' `README_d/README.*' Descriptive files: `README' for `gawk' under Unix and the rest for @@ -25534,16 +25630,6 @@ Various `.c', `.y', and `.h' files `COPYING' The GNU General Public License. -`FUTURES' - A brief list of features and changes being contemplated for future - releases, with some indication of the time frame for the feature, - based on its difficulty. - -`LIMITATIONS' - A list of those factors that limit `gawk''s performance. Most of - these depend on the hardware or operating system software and are - not limits in `gawk' itself. - `POSIX.STD' A description of behaviors in the POSIX standard for `awk' which are left undefined, or where `gawk' may not comply fully, as well @@ -25575,11 +25661,18 @@ Various `.c', `.y', and `.h' files The `troff' source for a manual page describing `gawk'. This is distributed for the convenience of Unix users. -`doc/gawk.texi' +`doc/gawktexi.in' +`doc/sidebar.awk' The Texinfo source file for this Info file. It should be - processed with TeX (via `texi2dvi' or `texi2pdf') to produce a - printed document, and with `makeinfo' to produce an Info or HTML - file. + processed by `doc/sidebar.awk' before processing with `texi2dvi' + or `texi2pdf' to produce a printed document, and with `makeinfo' + to produce an Info or HTML file. The `Makefile' takes care of + this processing and produces printable output via `texi2dvi' or + `texi2pdf'. + +`doc/gawk.texi' + The file produced after processing `gawktexi.in' with + `sidebar.awk'. `doc/gawk.info' The generated Info file for this Info file. @@ -25609,15 +25702,21 @@ Various `.c', `.y', and `.h' files `Makefile.in' `aclocal.m4' +`bisonfix.awk' +`config.guess' `configh.in' `configure.ac' `configure' `custom.h' +`depcomp' +`install-sh' `missing_d/*' +`mkinstalldirs' `m4/*' - These files and subdirectories are used when configuring `gawk' - for various Unix systems. They are explained in *note Unix - Installation::. + These files and subdirectories are used when configuring and + compiling `gawk' for various Unix systems. Most of them are + explained in *note Unix Installation::. The rest are there to + support the main infrastructure. `po/*' The `po' library contains message translations. @@ -25737,6 +25836,12 @@ B.2.2 Additional Configuration Options There are several additional options you may use on the `configure' command line when compiling `gawk' from scratch, including: +`--disable-extensions' + Disable configuring and building the sample extensions in the + `extension' directory. This is useful for cross-compiling. The + default action is to dynamically check if the extensions can be + configured and compiled. + `--disable-lint' Disable all lint checking within `gawk'. The `--lint' and `--lint-old' options (*note Options::) are accepted, but silently @@ -26270,8 +26375,8 @@ File: gawk.info, Node: Bugs, Next: Other Versions, Prev: Non-Unix Installatio B.4 Reporting Problems and Bugs =============================== - There is nothing more dangerous than a bored archeologist. - The Hitchhiker's Guide to the Galaxy + There is nothing more dangerous than a bored archeologist. -- The + Hitchhiker's Guide to the Galaxy If you have problems with `gawk' or think that you have found a bug, please report it to the developers; we cannot promise to do anything @@ -26350,8 +26455,8 @@ B.5 Other Freely Available `awk' Implementations ================================================ It's kind of fun to put comments like this in your awk code. - `// Do C++ comments work? answer: yes! of course' - Michael Brennan + `// Do C++ comments work? answer: yes! of course' -- Michael + Brennan There are a number of other freely available `awk' implementations. This minor node briefly describes where to get them: @@ -26442,12 +26547,18 @@ Busybox Awk The OpenSolaris POSIX `awk' The version of `awk' in `/usr/xpg4/bin' on Solaris is more-or-less POSIX-compliant. It is based on the `awk' from Mortice Kern - Systems for PCs. The source code can be downloaded from the - OpenSolaris web site (http://www.opensolaris.org). This author - was able to make it compile and work under GNU/Linux with 1-2 - hours of work. Making it more generally portable (using GNU - Autoconf and/or Automake) would take more work, and this has not - been done, at least to our knowledge. + Systems for PCs. This author was able to make it compile and work + under GNU/Linux with 1-2 hours of work. Making it more generally + portable (using GNU Autoconf and/or Automake) would take more + work, and this has not been done, at least to our knowledge. + + The source code used to be available from the OpenSolaris web site. + However, that project was ended and the web site shut down. + Fortunately, the Illumos project + (http://wiki.illumos.org/display/illumos/illumos+Home) makes this + implementation available. You can view the files one at a time + from + `https://github.com/joyent/illumos-joyent/blob/master/usr/src/cmd/awk_xpg4'. `jawk' This is an interpreter for `awk' written in Java. It claims to be @@ -26477,6 +26588,11 @@ QSE Awk `http://www.quiktrim.org/QTawk.html' for more information, including the manual and a download link. +Other Versions + See also the Wikipedia article + (http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations), + for information on additional versions. + File: gawk.info, Node: Notes, Next: Basic Concepts, Prev: Installation, Up: Top @@ -26943,10 +27059,7 @@ C.3 Probable Future Extensions ============================== AWK is a language similar to PERL, only considerably more elegant. - Arnold Robbins - - Hey! - Larry Wall + -- Arnold Robbins Hey! -- Larry Wall The `TODO' file in the `gawk' Git repository lists possible future enhancements. Some of these relate to the source code, and others to @@ -27080,7 +27193,7 @@ Some goals for the new API were: fashion for C code. - The ability to create arrays (including `gawk''s true - multi-dimensional arrays). + multidimensional arrays). Some additional important goals were: @@ -29354,10 +29467,12 @@ Index * --characters-as-bytes option: Options. (line 82) * --copyright option: Options. (line 102) * --debug option: Options. (line 122) -* --disable-lint configuration option: Additional Configuration Options. +* --disable-extensions configuration option: Additional Configuration Options. (line 9) +* --disable-lint configuration option: Additional Configuration Options. + (line 15) * --disable-nls configuration option: Additional Configuration Options. - (line 24) + (line 30) * --dump-variables option <1>: Library Names. (line 45) * --dump-variables option: Options. (line 107) * --exec option: Options. (line 139) @@ -29395,7 +29510,7 @@ Index * --use-lc-numeric option: Options. (line 215) * --version option: Options. (line 293) * --with-whiny-user-strftime configuration option: Additional Configuration Options. - (line 29) + (line 35) * -b option: Options. (line 82) * -C option: Options. (line 102) * -D option: Options. (line 122) @@ -29564,7 +29679,7 @@ Index (line 23) * advanced features, specifying field content: Splitting By Content. (line 9) -* Aho, Alfred <1>: Contributors. (line 12) +* Aho, Alfred <1>: Contributors. (line 11) * Aho, Alfred: History. (line 17) * alarm clock example program: Alarm Program. (line 9) * alarm.awk program: Alarm Program. (line 29) @@ -29603,7 +29718,7 @@ Index * arrays: Arrays. (line 6) * arrays, as parameters to functions: Pass By Value/Reference. (line 47) -* arrays, associative: Array Intro. (line 50) +* arrays, associative: Array Intro. (line 49) * arrays, associative, library functions and: Library Names. (line 57) * arrays, deleting entire contents: Delete. (line 39) * arrays, elements, assigning: Assigning Elements. (line 6) @@ -29611,34 +29726,38 @@ Index * arrays, elements, order of: Scanning an Array. (line 48) * arrays, elements, referencing: Reference to Elements. (line 6) -* arrays, elements, retrieving number of: String Functions. (line 29) +* arrays, elements, retrieving number of: String Functions. (line 32) * arrays, for statement and: Scanning an Array. (line 20) -* arrays, IGNORECASE variable and: Array Intro. (line 92) -* arrays, indexing: Array Intro. (line 50) +* arrays, IGNORECASE variable and: Array Intro. (line 91) +* arrays, indexing: Array Intro. (line 49) * arrays, merging into strings: Join Function. (line 6) -* arrays, multidimensional: Multi-dimensional. (line 10) -* arrays, multidimensional, scanning: Multi-scanning. (line 11) +* arrays, multidimensional: Multidimensional. (line 10) +* arrays, multidimensional, scanning: Multiscanning. (line 11) * arrays, names of: Arrays. (line 18) * arrays, scanning: Scanning an Array. (line 6) * arrays, sorting: Array Sorting Functions. (line 6) * arrays, sorting, IGNORECASE variable and: Array Sorting Functions. - (line 81) -* arrays, sparse: Array Intro. (line 71) + (line 83) +* arrays, sparse: Array Intro. (line 70) * arrays, subscripts: Numeric Array Subscripts. (line 6) * arrays, subscripts, uninitialized variables as: Uninitialized Subscripts. (line 6) * artificial intelligence, gawk and: Distribution contents. - (line 55) + (line 52) * ASCII <1>: Glossary. (line 141) * ASCII: Ordinal Functions. (line 45) * asort() function (gawk) <1>: Array Sorting Functions. (line 6) -* asort() function (gawk): String Functions. (line 29) +* asort() function (gawk): String Functions. (line 32) * asort() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) -* asorti() function (gawk): String Functions. (line 77) +* asorti() function (gawk) <1>: Array Sorting Functions. + (line 6) +* asorti() function (gawk): String Functions. (line 32) +* asorti() function (gawk), arrays, sorting: Array Sorting Functions. + (line 6) * assert() function (C library): Assert Function. (line 6) * assert() user-defined function: Assert Function. (line 28) * assertions: Assert Function. (line 6) @@ -29646,7 +29765,7 @@ Index * assignment operators, evaluation order: Assignment Ops. (line 111) * assignment operators, lvalues/rvalues: Assignment Ops. (line 32) * assignments as filenames: Ignoring Assigns. (line 6) -* associative arrays: Array Intro. (line 50) +* associative arrays: Array Intro. (line 49) * asterisk (*), * operator, as multiplication operator: Precedence. (line 55) * asterisk (*), * operator, as regexp operator: Regexp Operators. @@ -29800,7 +29919,7 @@ Index * BEGINFILE pattern, Boolean patterns and: Expression Patterns. (line 73) * beginfile() user-defined function: Filetrans Function. (line 62) -* Benzinger, Michael: Contributors. (line 98) +* Benzinger, Michael: Contributors. (line 97) * Berry, Karl: Acknowledgments. (line 33) * binary input/output: User-modified. (line 10) * bindtextdomain() function (C library): Explaining gettext. (line 49) @@ -29845,12 +29964,12 @@ Index * Brennan, Michael: Delete. (line 56) * Brian Kernighan's awk: Other Versions. (line 13) * Brian Kernighan's awk, extensions: BTL. (line 6) -* Broder, Alan J.: Contributors. (line 89) -* Brown, Martin: Contributors. (line 83) +* Broder, Alan J.: Contributors. (line 88) +* Brown, Martin: Contributors. (line 82) * BSD-based operating systems: Glossary. (line 624) * bt debugger command (alias for backtrace): Execution Stack. (line 13) * Buening, Andreas <1>: Bugs. (line 71) -* Buening, Andreas <2>: Contributors. (line 93) +* Buening, Andreas <2>: Contributors. (line 92) * Buening, Andreas: Acknowledgments. (line 60) * buffering, input/output <1>: Two-way I/O. (line 70) * buffering, input/output: I/O Functions. (line 137) @@ -29879,8 +29998,8 @@ Index * caret (^), in bracket expressions: Bracket Expressions. (line 17) * caret (^), regexp operator: Regexp Operators. (line 22) * case keyword: Switch Statement. (line 6) -* case sensitivity, array indices and: Array Intro. (line 92) -* case sensitivity, converting case: String Functions. (line 524) +* case sensitivity, array indices and: Array Intro. (line 91) +* case sensitivity, converting case: String Functions. (line 519) * case sensitivity, example programs: Library Functions. (line 53) * case sensitivity, gawk: Case-sensitivity. (line 26) * case sensitivity, regexps and <1>: User-modified. (line 82) @@ -29911,13 +30030,13 @@ Index * close() function <1>: I/O Functions. (line 10) * close() function <2>: Close Files And Pipes. (line 18) -* close() function <3>: Getline/Pipe. (line 28) +* close() function <3>: Getline/Pipe. (line 27) * close() function: Getline/Variable/File. (line 30) * close() function, return value: Close Files And Pipes. (line 130) * close() function, two-way pipes and: Two-way I/O. (line 77) -* Close, Diane <1>: Contributors. (line 21) +* Close, Diane <1>: Contributors. (line 20) * Close, Diane: Manual History. (line 41) * Collado, Manuel: Acknowledgments. (line 60) * collating elements: Bracket Expressions. (line 69) @@ -29957,7 +30076,7 @@ Index * common extensions, delete to delete entire arrays: Delete. (line 39) * common extensions, func keyword: Definition Syntax. (line 83) * common extensions, length() applied to an array: String Functions. - (line 198) + (line 193) * common extensions, RS as a regexp: Records. (line 120) * common extensions, single character fields: Single Character Fields. (line 6) @@ -29983,15 +30102,17 @@ Index * compl() function (gawk): Bitwise Functions. (line 43) * complement, bitwise: Bitwise Functions. (line 25) * compound statements, control statements and: Statements. (line 10) -* concatenating: Concatenation. (line 9) +* concatenating: Concatenation. (line 8) * condition debugger command: Breakpoint Control. (line 54) * conditional expressions: Conditional Exp. (line 6) -* configuration option, --disable-lint: Additional Configuration Options. +* configuration option, --disable-extensions: Additional Configuration Options. (line 9) +* configuration option, --disable-lint: Additional Configuration Options. + (line 15) * configuration option, --disable-nls: Additional Configuration Options. - (line 24) + (line 30) * configuration option, --with-whiny-user-strftime: Additional Configuration Options. - (line 29) + (line 35) * configuration options, gawk: Additional Configuration Options. (line 6) * constants, floating-point: Floating-point Constants. @@ -30002,7 +30123,7 @@ Index (line 6) * continue statement: Continue Statement. (line 6) * control statements: Statements. (line 6) -* converting, case: String Functions. (line 524) +* converting, case: String Functions. (line 519) * converting, dates to timestamps: Time Functions. (line 75) * converting, during subscripting: Numeric Array Subscripts. (line 31) @@ -30054,15 +30175,15 @@ Index * dark corner, exit statement: Exit Statement. (line 30) * dark corner, field separators: Field Splitting Summary. (line 46) -* dark corner, FILENAME variable <1>: Auto-set. (line 93) +* dark corner, FILENAME variable <1>: Auto-set. (line 102) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 311) +* dark corner, FNR/NR variables: Auto-set. (line 323) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) * dark corner, input files: Records. (line 103) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 184) +* dark corner, length() function: String Functions. (line 179) * dark corner, locale's decimal point character: Conversion. (line 77) * dark corner, multiline records: Multiple Line. (line 35) * dark corner, NF variable, decrementing: Changing Fields. (line 107) @@ -30073,7 +30194,7 @@ Index (line 147) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 363) +* dark corner, split() function: String Functions. (line 358) * dark corner, strings, storing: Records. (line 195) * dark corner, value of ARGV[0]: Auto-set. (line 35) * data, fixed-width: Constant Size. (line 9) @@ -30085,7 +30206,7 @@ Index * dates, converting to timestamps: Time Functions. (line 75) * dates, information related to, localization: Explaining gettext. (line 115) -* Davies, Stephen <1>: Contributors. (line 75) +* Davies, Stephen <1>: Contributors. (line 74) * Davies, Stephen: Acknowledgments. (line 60) * dcgettext() function (gawk) <1>: Programmer i18n. (line 19) * dcgettext() function (gawk): I18N Functions. (line 22) @@ -30198,14 +30319,14 @@ Index * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) * Deifik, Scott <1>: Bugs. (line 70) -* Deifik, Scott <2>: Contributors. (line 54) +* Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) * delete debugger command: Breakpoint Control. (line 64) * delete statement: Delete. (line 6) * deleting elements in arrays: Delete. (line 6) * deleting entire arrays: Delete. (line 39) * Demaille, Akim: Acknowledgments. (line 60) -* differences between gawk and awk: String Functions. (line 198) +* differences between gawk and awk: String Functions. (line 193) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 88) * differences in awk and gawk, ARGIND variable: Auto-set. (line 40) @@ -30225,12 +30346,12 @@ Index (line 23) * differences in awk and gawk, close() function: Close Files And Pipes. (line 81) -* differences in awk and gawk, ERRNO variable: Auto-set. (line 73) +* differences in awk and gawk, ERRNO variable: Auto-set. (line 82) * differences in awk and gawk, error messages: Special FD. (line 16) * differences in awk and gawk, FIELDWIDTHS variable: User-modified. (line 35) * differences in awk and gawk, FPAT variable: User-modified. (line 45) -* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 119) +* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 128) * differences in awk and gawk, function arguments (gawk): Calling Built-in. (line 16) * differences in awk and gawk, getline command: Getline. (line 19) @@ -30250,26 +30371,26 @@ Index (line 34) * differences in awk and gawk, LINT variable: User-modified. (line 98) * differences in awk and gawk, match() function: String Functions. - (line 261) + (line 256) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) -* differences in awk and gawk, PROCINFO array: Auto-set. (line 130) +* differences in awk and gawk, PROCINFO array: Auto-set. (line 142) * differences in awk and gawk, record separators: Records. (line 117) * differences in awk and gawk, regexp constants: Using Constant Regexps. (line 43) * differences in awk and gawk, regular expressions: Case-sensitivity. (line 26) * differences in awk and gawk, RS/RT variables: Records. (line 172) -* differences in awk and gawk, RT variable: Auto-set. (line 263) +* differences in awk and gawk, RT variable: Auto-set. (line 275) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. - (line 351) + (line 346) * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: Records. (line 191) * differences in awk and gawk, strtonum() function (gawk): String Functions. - (line 406) -* differences in awk and gawk, SYMTAB variable: Auto-set. (line 271) + (line 401) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 283) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 162) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. @@ -30350,13 +30471,13 @@ Index (line 11) * EREs (Extended Regular Expressions): Bracket Expressions. (line 24) * ERRNO variable <1>: TCP/IP Networking. (line 54) -* ERRNO variable <2>: Auto-set. (line 73) +* ERRNO variable <2>: Auto-set. (line 82) * ERRNO variable <3>: BEGINFILE/ENDFILE. (line 26) * ERRNO variable <4>: Close Files And Pipes. (line 138) * ERRNO variable: Getline. (line 19) * error handling: Special FD. (line 16) -* error handling, ERRNO variable and: Auto-set. (line 73) +* error handling, ERRNO variable and: Auto-set. (line 82) * error output: Special FD. (line 6) * escape processing, gsub()/gensub()/sub() functions: Gory Details. (line 6) @@ -30364,7 +30485,7 @@ Index * eval debugger command: Viewing And Changing Data. (line 23) * evaluation order: Increment Ops. (line 60) -* evaluation order, concatenation: Concatenation. (line 42) +* evaluation order, concatenation: Concatenation. (line 41) * evaluation order, functions: Calling Built-in. (line 30) * examining fields: Fields. (line 6) * exclamation point (!), ! operator <1>: Egrep Program. (line 170) @@ -30410,7 +30531,7 @@ Index * extensions, common, delete to delete entire arrays: Delete. (line 39) * extensions, common, func keyword: Definition Syntax. (line 83) * extensions, common, length() applied to an array: String Functions. - (line 198) + (line 193) * extensions, common, RS as a regexp: Records. (line 120) * extensions, common, single character fields: Single Character Fields. (line 6) @@ -30427,7 +30548,7 @@ Index * features, advanced, See advanced features: Obsolete. (line 6) * features, deprecated: Obsolete. (line 6) * features, undocumented: Undocumented. (line 6) -* Fenlason, Jay <1>: Contributors. (line 19) +* Fenlason, Jay <1>: Contributors. (line 18) * Fenlason, Jay: History. (line 30) * fflush() function: I/O Functions. (line 25) * field numbers: Nonconstant Fields. (line 6) @@ -30468,7 +30589,7 @@ Index * file names, distinguishing: Auto-set. (line 52) * file names, in compatibility mode: Special Caveats. (line 9) * file names, standard streams in gawk: Special FD. (line 46) -* FILENAME variable <1>: Auto-set. (line 93) +* FILENAME variable <1>: Auto-set. (line 102) * FILENAME variable: Reading Files. (line 6) * FILENAME variable, getline, setting with: Getline Notes. (line 19) * filenames, assignments as: Ignoring Assigns. (line 6) @@ -30525,7 +30646,7 @@ Index * files, Texinfo, extracting programs from: Extract Program. (line 6) * finish debugger command: Debugger Execution Control. (line 39) -* Fish, Fred: Contributors. (line 51) +* Fish, Fred: Contributors. (line 50) * fixed-width data: Constant Size. (line 9) * flag variables <1>: Tee Program. (line 20) * flag variables: Boolean Ops. (line 67) @@ -30535,9 +30656,9 @@ Index * floating-point, numbers: General Arithmetic. (line 6) * fnmatch extension function: Extension Sample Fnmatch. (line 6) -* FNR variable <1>: Auto-set. (line 103) +* FNR variable <1>: Auto-set. (line 112) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 311) +* FNR variable, changing: Auto-set. (line 323) * for statement: For Statement. (line 6) * for statement, looping over arrays: Scanning an Array. (line 20) * fork extension function: Extension Sample Fork. @@ -30584,7 +30705,7 @@ Index * FSF (Free Software Foundation): Manual History. (line 6) * fts extension function: Extension Sample File Functions. (line 77) -* FUNCTAB array: Auto-set. (line 119) +* FUNCTAB array: Auto-set. (line 128) * function calls: Function Calls. (line 6) * function calls, indirect: Indirect Calls. (line 6) * function pointers: Indirect Calls. (line 6) @@ -30631,7 +30752,7 @@ Index * functions, user-defined, next/nextfile statements and: Next Statement. (line 45) * G-d: Acknowledgments. (line 78) -* Garfinkle, Scott: Contributors. (line 35) +* Garfinkle, Scott: Contributors. (line 34) * gawk program, dynamic profiling: Profiling. (line 172) * gawk, ARGIND variable in: Other Arguments. (line 12) * gawk, awk and <1>: This Manual. (line 14) @@ -30653,7 +30774,7 @@ Index * gawk, distribution: Distribution contents. (line 6) * gawk, ERRNO variable in <1>: TCP/IP Networking. (line 54) -* gawk, ERRNO variable in <2>: Auto-set. (line 73) +* gawk, ERRNO variable in <2>: Auto-set. (line 82) * gawk, ERRNO variable in <3>: BEGINFILE/ENDFILE. (line 26) * gawk, ERRNO variable in <4>: Close Files And Pipes. (line 138) @@ -30670,13 +30791,13 @@ Index * gawk, FPAT variable in <1>: User-modified. (line 45) * gawk, FPAT variable in: Splitting By Content. (line 26) -* gawk, FUNCTAB array in: Auto-set. (line 119) +* gawk, FUNCTAB array in: Auto-set. (line 128) * gawk, function arguments and: Calling Built-in. (line 16) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: Array Sorting Functions. - (line 81) -* gawk, IGNORECASE variable in <2>: String Functions. (line 29) -* gawk, IGNORECASE variable in <3>: Array Intro. (line 92) + (line 83) +* gawk, IGNORECASE variable in <2>: String Functions. (line 32) +* gawk, IGNORECASE variable in <3>: Array Intro. (line 91) * gawk, IGNORECASE variable in <4>: User-modified. (line 82) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) * gawk, implementation issues: Notes. (line 6) @@ -30701,7 +30822,7 @@ Index * gawk, OS/2 version of: PC Using. (line 11) * gawk, PROCINFO array in <1>: Two-way I/O. (line 116) * gawk, PROCINFO array in <2>: Time Functions. (line 47) -* gawk, PROCINFO array in: Auto-set. (line 130) +* gawk, PROCINFO array in: Auto-set. (line 142) * gawk, regexp constants and: Using Constant Regexps. (line 28) * gawk, regular expressions, case sensitivity: Case-sensitivity. @@ -30709,7 +30830,7 @@ Index * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 161) -* gawk, RT variable in <1>: Auto-set. (line 263) +* gawk, RT variable in <1>: Auto-set. (line 275) * gawk, RT variable in <2>: Getline/Variable/File. (line 10) * gawk, RT variable in <3>: Multiple Line. (line 129) @@ -30718,7 +30839,7 @@ Index * gawk, source code, obtaining: Getting. (line 6) * gawk, splitting fields and: Constant Size. (line 87) * gawk, string-translation functions: I18N Functions. (line 6) -* gawk, SYMTAB array in: Auto-set. (line 271) +* gawk, SYMTAB array in: Auto-set. (line 283) * gawk, TEXTDOMAIN variable in: User-modified. (line 162) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 36) @@ -30729,7 +30850,7 @@ Index * gawkextlib project: gawkextlib. (line 6) * General Public License (GPL): Glossary. (line 314) * General Public License, See GPL: Manual History. (line 11) -* gensub() function (gawk) <1>: String Functions. (line 86) +* gensub() function (gawk) <1>: String Functions. (line 81) * gensub() function (gawk): Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) @@ -30792,23 +30913,23 @@ Index * GPL (General Public License): Manual History. (line 11) * GPL (General Public License), printing: Options. (line 102) * grcat program: Group Functions. (line 16) -* Grigera, Juan: Contributors. (line 58) +* Grigera, Juan: Contributors. (line 57) * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) * groups, information about: Group Functions. (line 6) -* gsub() function <1>: String Functions. (line 139) +* gsub() function <1>: String Functions. (line 134) * gsub() function: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 464) +* gsub() function, arguments of: String Functions. (line 459) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Debugger Commands. (line 66) -* Hankerson, Darrel <1>: Contributors. (line 61) +* Hankerson, Darrel <1>: Contributors. (line 60) * Hankerson, Darrel: Acknowledgments. (line 60) -* Haque, John: Contributors. (line 104) +* Haque, John: Contributors. (line 103) * Hartholz, Elaine: Acknowledgments. (line 38) * Hartholz, Marshall: Acknowledgments. (line 38) -* Hasegawa, Isamu: Contributors. (line 95) +* Hasegawa, Isamu: Contributors. (line 94) * help debugger command: Miscellaneous Debugger Commands. (line 66) * hexadecimal numbers: Nondecimal-numbers. (line 6) @@ -30834,16 +30955,18 @@ Index * igawk.sh program: Igawk Program. (line 124) * ignore debugger command: Breakpoint Control. (line 87) * IGNORECASE variable <1>: Array Sorting Functions. - (line 81) -* IGNORECASE variable <2>: String Functions. (line 29) -* IGNORECASE variable <3>: Array Intro. (line 92) + (line 83) +* IGNORECASE variable <2>: String Functions. (line 32) +* IGNORECASE variable <3>: Array Intro. (line 91) * IGNORECASE variable <4>: User-modified. (line 82) * IGNORECASE variable: Case-sensitivity. (line 26) * IGNORECASE variable, array sorting and: Array Sorting Functions. - (line 81) -* IGNORECASE variable, array subscripts and: Array Intro. (line 92) + (line 83) +* IGNORECASE variable, array subscripts and: Array Intro. (line 91) * IGNORECASE variable, in example programs: Library Functions. (line 53) +* Illumos: Other Versions. (line 104) +* Illumos, POSIX-compliant awk: Other Versions. (line 104) * implementation issues, gawk: Notes. (line 6) * implementation issues, gawk, debugging: Compatibility Mode. (line 6) * implementation issues, gawk, limits <1>: Redirection. (line 135) @@ -30857,8 +30980,8 @@ Index * in operator: Comparison Operators. (line 11) * increment operators: Increment Ops. (line 6) -* index() function: String Functions. (line 155) -* indexing arrays: Array Intro. (line 50) +* index() function: String Functions. (line 150) +* indexing arrays: Array Intro. (line 49) * indirect function calls: Indirect Calls. (line 6) * infinite precision: Arbitrary Precision Arithmetic. (line 6) @@ -30874,7 +30997,7 @@ Index * input files, reading: Reading Files. (line 6) * input files, running awk without: Read Terminal. (line 6) * input files, variable assignments and: Other Arguments. (line 19) -* input pipeline: Getline/Pipe. (line 10) +* input pipeline: Getline/Pipe. (line 9) * input redirection: Getline/File. (line 6) * input, data, nondecimal: Nondecimal Data. (line 6) * input, explicit: Getline. (line 6) @@ -30921,20 +31044,20 @@ Index * ISO 8859-1: Glossary. (line 141) * ISO Latin-1: Glossary. (line 141) * Jacobs, Andrew: Passwd Functions. (line 90) -* Jaegermann, Michal <1>: Contributors. (line 46) +* Jaegermann, Michal <1>: Contributors. (line 45) * Jaegermann, Michal: Acknowledgments. (line 60) -* Java implementation of awk: Other Versions. (line 106) +* Java implementation of awk: Other Versions. (line 112) * Java programming language: Glossary. (line 388) -* jawk: Other Versions. (line 106) +* jawk: Other Versions. (line 112) * Jedi knights: Undocumented. (line 6) * join() user-defined function: Join Function. (line 18) -* Kahrs, Ju"rgen <1>: Contributors. (line 71) +* Kahrs, Ju"rgen <1>: Contributors. (line 70) * Kahrs, Ju"rgen: Acknowledgments. (line 60) * Kasal, Stepan: Acknowledgments. (line 60) * Kenobi, Obi-Wan: Undocumented. (line 6) * Kernighan, Brian <1>: Basic Data Typing. (line 55) * Kernighan, Brian <2>: Other Versions. (line 13) -* Kernighan, Brian <3>: Contributors. (line 12) +* Kernighan, Brian <3>: Contributors. (line 11) * Kernighan, Brian <4>: BTL. (line 6) * Kernighan, Brian <5>: Concatenation. (line 6) * Kernighan, Brian <6>: Acknowledgments. (line 72) @@ -30944,7 +31067,7 @@ Index * Knights, jedi: Undocumented. (line 6) * Knuth, Donald: Arbitrary Precision Arithmetic. (line 6) -* Kwok, Conrad: Contributors. (line 35) +* Kwok, Conrad: Contributors. (line 34) * l debugger command (alias for list): Miscellaneous Debugger Commands. (line 72) * labels.awk program: Labels Program. (line 51) @@ -30969,10 +31092,10 @@ Index (line 11) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length() function: String Functions. (line 168) +* length() function: String Functions. (line 163) * Lesser General Public License (LGPL): Glossary. (line 405) * LGPL (Lesser General Public License): Glossary. (line 405) -* libmawk: Other Versions. (line 114) +* libmawk: Other Versions. (line 120) * libraries of awk functions: Library Functions. (line 6) * libraries of awk functions, assertions: Assert Function. (line 6) * libraries of awk functions, associative arrays and: Library Names. @@ -31051,15 +31174,15 @@ Index (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 60) -* match() function: String Functions. (line 208) +* match() function: String Functions. (line 203) * match() function, RSTART/RLENGTH variables: String Functions. - (line 225) + (line 220) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) * matching, null strings: Gory Details. (line 164) * mawk program: Other Versions. (line 44) -* McPhee, Patrick: Contributors. (line 101) +* McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 41) * message object files, converting from portable object files: I18N Example. (line 62) @@ -31119,16 +31242,16 @@ Index (line 47) * nexti debugger command: Debugger Execution Control. (line 49) -* NF variable <1>: Auto-set. (line 108) +* NF variable <1>: Auto-set. (line 117) * NF variable: Fields. (line 33) * NF variable, decrementing: Changing Fields. (line 107) * ni debugger command (alias for nexti): Debugger Execution Control. (line 49) * noassign.awk program: Ignoring Assigns. (line 15) * not Boolean-logic operator: Boolean Ops. (line 6) -* NR variable <1>: Auto-set. (line 125) +* NR variable <1>: Auto-set. (line 137) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 311) +* NR variable, changing: Auto-set. (line 323) * null strings <1>: Basic Data Typing. (line 26) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -31191,7 +31314,7 @@ Index * operators, input/output <1>: Precedence. (line 65) * operators, input/output <2>: Redirection. (line 22) * operators, input/output <3>: Getline/Coprocess. (line 6) -* operators, input/output <4>: Getline/Pipe. (line 10) +* operators, input/output <4>: Getline/Pipe. (line 9) * operators, input/output: Getline/File. (line 6) * operators, logical, See Boolean expressions: Boolean Ops. (line 6) * operators, precedence <1>: Precedence. (line 6) @@ -31199,7 +31322,7 @@ Index * operators, relational, See operators, comparison: Typing and Comparison. (line 9) * operators, short-circuit: Boolean Ops. (line 57) -* operators, string: Concatenation. (line 9) +* operators, string: Concatenation. (line 8) * operators, string-matching: Regexp Usage. (line 19) * operators, string-matching, for buffers: GNU Regexp Operators. (line 48) @@ -31223,7 +31346,7 @@ Index * ord extension function: Extension Sample Ord. (line 12) * ord() user-defined function: Ordinal Functions. (line 16) -* order of evaluation, concatenation: Concatenation. (line 42) +* order of evaluation, concatenation: Concatenation. (line 41) * ORS variable <1>: User-modified. (line 129) * ORS variable: Output Separators. (line 20) * output field separator, See OFS variable: Changing Fields. (line 64) @@ -31246,7 +31369,7 @@ Index * parentheses () <1>: Profiling. (line 138) * parentheses (): Regexp Operators. (line 79) * password file: Passwd Functions. (line 16) -* patsplit() function (gawk): String Functions. (line 295) +* patsplit() function (gawk): String Functions. (line 290) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) @@ -31259,7 +31382,7 @@ Index * patterns, types of: Pattern Overview. (line 15) * pawk (profiling version of Brian Kernighan's awk): Other Versions. (line 78) -* pawk, awk-like facilities for Python: Other Versions. (line 118) +* pawk, awk-like facilities for Python: Other Versions. (line 124) * PC operating systems, gawk on: PC Using. (line 6) * PC operating systems, gawk on, installing: PC Installation. (line 6) * percent sign (%), % operator: Precedence. (line 55) @@ -31267,11 +31390,11 @@ Index * percent sign (%), %= operator: Assignment Ops. (line 129) * period (.): Regexp Operators. (line 43) * Perl: Future Extensions. (line 6) -* Peters, Arno: Contributors. (line 86) -* Peterson, Hal: Contributors. (line 40) +* Peters, Arno: Contributors. (line 85) +* Peterson, Hal: Contributors. (line 39) * pipes, closing: Close Files And Pipes. (line 6) -* pipes, input: Getline/Pipe. (line 10) +* pipes, input: Getline/Pipe. (line 9) * pipes, output: Redirection. (line 57) * Pitts, Dave <1>: Bugs. (line 73) * Pitts, Dave: Acknowledgments. (line 60) @@ -31299,7 +31422,7 @@ Index * portability, gawk: New Ports. (line 6) * portability, gettext library and: Explaining gettext. (line 10) * portability, internationalization and: I18N Portability. (line 6) -* portability, length() function: String Functions. (line 177) +* portability, length() function: String Functions. (line 172) * portability, new awk vs. old awk: Conversion. (line 55) * portability, next statement in user-defined functions: Pass By Value/Reference. (line 91) @@ -31307,7 +31430,7 @@ Index * portability, operators: Increment Ops. (line 60) * portability, operators, not in POSIX awk: Precedence. (line 98) * portability, POSIXLY_CORRECT environment variable: Options. (line 353) -* portability, substr() function: String Functions. (line 514) +* portability, substr() function: String Functions. (line 509) * portable object files <1>: Translator i18n. (line 6) * portable object files: Explaining gettext. (line 36) * portable object files, converting to message object files: I18N Example. @@ -31344,7 +31467,7 @@ Index * POSIX awk, FS variable and: User-modified. (line 66) * POSIX awk, function keyword in: Definition Syntax. (line 83) * POSIX awk, functions and, gsub()/sub(): Gory Details. (line 54) -* POSIX awk, functions and, length(): String Functions. (line 177) +* POSIX awk, functions and, length(): String Functions. (line 172) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 135) * POSIX awk, next/nextfile statements and: Next Statement. (line 45) @@ -31355,7 +31478,7 @@ Index * POSIX awk, printf format strings and: Format Modifiers. (line 159) * POSIX awk, regular expressions and: Regexp Operators. (line 161) * POSIX awk, timestamps and: Time Functions. (line 6) -* POSIX awk, | I/O operator and: Getline/Pipe. (line 56) +* POSIX awk, | I/O operator and: Getline/Pipe. (line 55) * POSIX mode: Options. (line 247) * POSIX, awk and: Preface. (line 23) * POSIX, gawk extensions not included in: POSIX/GNU. (line 6) @@ -31408,7 +31531,7 @@ Index * PROCINFO array <3>: Group Functions. (line 6) * PROCINFO array <4>: Passwd Functions. (line 6) * PROCINFO array <5>: Time Functions. (line 47) -* PROCINFO array <6>: Auto-set. (line 130) +* PROCINFO array <6>: Auto-set. (line 142) * PROCINFO array: Obsolete. (line 11) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 172) @@ -31438,12 +31561,12 @@ Index * pwcat program: Passwd Functions. (line 23) * q debugger command (alias for quit): Miscellaneous Debugger Commands. (line 99) -* QSE Awk: Other Versions. (line 124) +* QSE Awk: Other Versions. (line 130) * question mark (?) regexp operator <1>: GNU Regexp Operators. (line 59) * question mark (?) regexp operator: Regexp Operators. (line 111) * question mark (?), ?: operator: Precedence. (line 92) -* QuikTrim Awk: Other Versions. (line 128) +* QuikTrim Awk: Other Versions. (line 134) * quit debugger command: Miscellaneous Debugger Commands. (line 99) * QUIT signal (MS-Windows): Profiling. (line 207) @@ -31465,7 +31588,7 @@ Index * range expressions (regexps): Bracket Expressions. (line 6) * range patterns: Ranges. (line 6) * Rankin, Pat <1>: Bugs. (line 72) -* Rankin, Pat <2>: Contributors. (line 38) +* Rankin, Pat <2>: Contributors. (line 37) * Rankin, Pat <3>: Assignment Ops. (line 100) * Rankin, Pat: Acknowledgments. (line 60) * reada extension function: Extension Sample Read write array. @@ -31476,6 +31599,7 @@ Index (line 9) * readfile extension function: Extension Sample Readfile. (line 11) +* readfile() user-defined function: Readfile Function. (line 30) * recipe for a programming language: History. (line 6) * record separators <1>: User-modified. (line 143) * record separators: Records. (line 14) @@ -31493,7 +31617,7 @@ Index * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) * reference counting, sorting arrays: Array Sorting Functions. - (line 75) + (line 77) * regexp constants <1>: Comparison Operators. (line 103) * regexp constants <2>: Regexp Constants. (line 6) @@ -31561,23 +31685,23 @@ Index * right angle bracket (>), >> operator (I/O): Redirection. (line 50) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 55) -* RLENGTH variable: Auto-set. (line 250) -* RLENGTH variable, match() function and: String Functions. (line 225) +* RLENGTH variable: Auto-set. (line 262) +* RLENGTH variable, match() function and: String Functions. (line 220) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) -* Robbins, Arnold <3>: Contributors. (line 125) +* Robbins, Arnold <3>: Contributors. (line 130) * Robbins, Arnold <4>: Alarm Program. (line 6) * Robbins, Arnold <5>: Passwd Functions. (line 90) -* Robbins, Arnold <6>: Getline/Pipe. (line 40) +* Robbins, Arnold <6>: Getline/Pipe. (line 39) * Robbins, Arnold: Command Line Field Separator. (line 80) -* Robbins, Bill: Getline/Pipe. (line 40) +* Robbins, Bill: Getline/Pipe. (line 39) * Robbins, Harry: Acknowledgments. (line 78) * Robbins, Jean: Acknowledgments. (line 78) * Robbins, Miriam <1>: Passwd Functions. (line 90) -* Robbins, Miriam <2>: Getline/Pipe. (line 40) +* Robbins, Miriam <2>: Getline/Pipe. (line 39) * Robbins, Miriam: Acknowledgments. (line 78) -* Rommel, Kai Uwe: Contributors. (line 43) +* Rommel, Kai Uwe: Contributors. (line 42) * round() user-defined function: Round Function. (line 16) * rounding mode, floating-point: Rounding Mode. (line 6) * rounding numbers: Round Function. (line 6) @@ -31588,14 +31712,14 @@ Index * RS variable: Records. (line 20) * RS variable, multiline records and: Multiple Line. (line 17) * rshift() function (gawk): Bitwise Functions. (line 52) -* RSTART variable: Auto-set. (line 256) -* RSTART variable, match() function and: String Functions. (line 225) -* RT variable <1>: Auto-set. (line 263) +* RSTART variable: Auto-set. (line 268) +* RSTART variable, match() function and: String Functions. (line 220) +* RT variable <1>: Auto-set. (line 275) * RT variable <2>: Getline/Variable/File. (line 10) * RT variable <3>: Multiple Line. (line 129) * RT variable: Records. (line 117) -* Rubin, Paul <1>: Contributors. (line 16) +* Rubin, Paul <1>: Contributors. (line 15) * Rubin, Paul: History. (line 30) * rule, definition of: Getting Started. (line 21) * run debugger command: Debugger Execution Control. @@ -31605,7 +31729,7 @@ Index (line 68) * sandbox mode: Options. (line 279) * scalar values: Basic Data Typing. (line 13) -* Schorr, Andrew <1>: Contributors. (line 121) +* Schorr, Andrew <1>: Contributors. (line 126) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) @@ -31619,7 +31743,7 @@ Index * search paths, for source files <2>: PC Using. (line 11) * search paths, for source files <3>: Igawk Program. (line 368) * search paths, for source files: AWKPATH Variable. (line 6) -* searching: String Functions. (line 155) +* searching: String Functions. (line 150) * searching, files for regular expressions: Egrep Program. (line 6) * searching, for words: Dupword Program. (line 6) * sed utility <1>: Glossary. (line 12) @@ -31655,7 +31779,7 @@ Index * si debugger command (alias for stepi): Debugger Execution Control. (line 76) * side effects <1>: Increment Ops. (line 11) -* side effects: Concatenation. (line 42) +* side effects: Concatenation. (line 41) * side effects, array indexing: Reference to Elements. (line 42) * side effects, asort() function: Array Sorting Functions. @@ -31673,7 +31797,7 @@ Index (line 110) * sidebar, Changing FS Does Not Affect the Fields: Field Splitting Summary. (line 38) -* sidebar, Changing NR and FNR: Auto-set. (line 309) +* sidebar, Changing NR and FNR: Auto-set. (line 321) * sidebar, Controlling Output Buffering with system(): I/O Functions. (line 135) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. @@ -31731,22 +31855,23 @@ Index * source code, Brian Kernighan's awk: Other Versions. (line 13) * source code, Busybox Awk: Other Versions. (line 88) * source code, gawk: Gawk Distribution. (line 6) -* source code, jawk: Other Versions. (line 106) -* source code, libmawk: Other Versions. (line 114) +* source code, Illumos awk: Other Versions. (line 104) +* source code, jawk: Other Versions. (line 112) +* source code, libmawk: Other Versions. (line 120) * source code, mawk: Other Versions. (line 44) * source code, mixing: Options. (line 131) * source code, pawk: Other Versions. (line 78) -* source code, QSE Awk: Other Versions. (line 124) -* source code, QuikTrim Awk: Other Versions. (line 128) +* source code, QSE Awk: Other Versions. (line 130) +* source code, QuikTrim Awk: Other Versions. (line 134) * source code, Solaris awk: Other Versions. (line 96) * source files, search path for: Igawk Program. (line 368) -* sparse arrays: Array Intro. (line 71) +* sparse arrays: Array Intro. (line 70) * Spencer, Henry: Glossary. (line 12) * split utility: Split Program. (line 6) -* split() function: String Functions. (line 317) +* split() function: String Functions. (line 312) * split() function, array elements, deleting: Delete. (line 61) * split.awk program: Split Program. (line 30) -* sprintf() function <1>: String Functions. (line 382) +* sprintf() function <1>: String Functions. (line 377) * sprintf() function: OFMT. (line 15) * sprintf() function, OFMT variable and: User-modified. (line 124) * sprintf() function, print/printf statements and: Round Function. @@ -31755,7 +31880,7 @@ Index * square brackets ([]): Regexp Operators. (line 55) * srand() function: Numeric Functions. (line 82) * Stallman, Richard <1>: Glossary. (line 305) -* Stallman, Richard <2>: Contributors. (line 24) +* Stallman, Richard <2>: Contributors. (line 23) * Stallman, Richard <3>: Acknowledgments. (line 18) * Stallman, Richard: Manual History. (line 6) * standard error: Special FD. (line 6) @@ -31779,7 +31904,7 @@ Index * string constants, vs. regexp constants: Computed Regexps. (line 38) * string extraction (internationalization): String Extraction. (line 6) -* string operators: Concatenation. (line 9) +* string operators: Concatenation. (line 8) * string-matching operators: Regexp Usage. (line 19) * strings, converting <1>: Bitwise Functions. (line 109) * strings, converting: Conversion. (line 6) @@ -31792,30 +31917,29 @@ Index * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strings, splitting: String Functions. (line 337) -* strtonum() function (gawk): String Functions. (line 389) +* strings, splitting: String Functions. (line 332) +* strtonum() function (gawk): String Functions. (line 384) * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data. (line 36) -* sub() function <1>: String Functions. (line 410) +* sub() function <1>: String Functions. (line 405) * sub() function: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 464) +* sub() function, arguments of: String Functions. (line 459) * sub() function, escape processing: Gory Details. (line 6) * subscript separators: User-modified. (line 156) -* subscripts in arrays, multidimensional: Multi-dimensional. (line 10) -* subscripts in arrays, multidimensional, scanning: Multi-scanning. +* subscripts in arrays, multidimensional: Multidimensional. (line 10) +* subscripts in arrays, multidimensional, scanning: Multiscanning. (line 11) * subscripts in arrays, numbers as: Numeric Array Subscripts. (line 6) * subscripts in arrays, uninitialized variables as: Uninitialized Subscripts. (line 6) * SUBSEP variable: User-modified. (line 156) -* SUBSEP variable, multidimensional arrays: Multi-dimensional. - (line 16) -* substr() function: String Functions. (line 483) +* SUBSEP variable, multidimensional arrays: Multidimensional. (line 16) +* substr() function: String Functions. (line 478) * Sumner, Andrew: Other Versions. (line 64) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 271) +* SYMTAB array: Auto-set. (line 283) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 147) * system() function: I/O Functions. (line 72) @@ -31833,7 +31957,7 @@ Index (line 6) * Texinfo <1>: Adding Code. (line 99) * Texinfo <2>: Distribution contents. - (line 80) + (line 77) * Texinfo <3>: Extract Program. (line 12) * Texinfo <4>: Dupword Program. (line 17) * Texinfo <5>: Library Functions. (line 33) @@ -31867,8 +31991,8 @@ Index * timestamps, converting dates to: Time Functions. (line 75) * timestamps, formatted: Getlocaltime Function. (line 6) -* tolower() function: String Functions. (line 525) -* toupper() function: String Functions. (line 531) +* tolower() function: String Functions. (line 520) +* toupper() function: String Functions. (line 526) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. (line 108) @@ -31891,9 +32015,9 @@ Index * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in. (line 16) * troubleshooting, getline function: File Checking. (line 25) -* troubleshooting, gsub()/sub() functions: String Functions. (line 474) -* troubleshooting, match() function: String Functions. (line 290) -* troubleshooting, patsplit() function: String Functions. (line 313) +* troubleshooting, gsub()/sub() functions: String Functions. (line 469) +* troubleshooting, match() function: String Functions. (line 285) +* troubleshooting, patsplit() function: String Functions. (line 308) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) * troubleshooting, printing: Redirection. (line 118) @@ -31901,13 +32025,13 @@ Index * troubleshooting, readable data files: File Checking. (line 6) * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 38) -* troubleshooting, string concatenation: Concatenation. (line 27) -* troubleshooting, substr() function: String Functions. (line 501) +* troubleshooting, string concatenation: Concatenation. (line 26) +* troubleshooting, substr() function: String Functions. (line 496) * troubleshooting, system() function: I/O Functions. (line 94) * troubleshooting, typographical errors, global variables: Options. (line 112) * true, logical: Truth Values. (line 6) -* Trueman, David <1>: Contributors. (line 31) +* Trueman, David <1>: Contributors. (line 30) * Trueman, David <2>: Acknowledgments. (line 47) * Trueman, David: History. (line 30) * trunc-mod operation: Arithmetic Ops. (line 66) @@ -31987,7 +32111,7 @@ Index * variables, user-defined: Variables. (line 6) * vertical bar (|): Regexp Operators. (line 69) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) -* vertical bar (|), | operator (I/O): Getline/Pipe. (line 10) +* vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) * vertical bar (|), |& operator (I/O) <1>: Two-way I/O. (line 44) * vertical bar (|), |& operator (I/O) <2>: Precedence. (line 65) * vertical bar (|), |& operator (I/O): Getline/Coprocess. (line 6) @@ -32010,7 +32134,7 @@ Index (line 67) * wc utility: Wc Program. (line 6) * wc.awk program: Wc Program. (line 46) -* Weinberger, Peter <1>: Contributors. (line 12) +* Weinberger, Peter <1>: Contributors. (line 11) * Weinberger, Peter: History. (line 17) * while statement <1>: While Statement. (line 6) * while statement: Regexp Usage. (line 19) @@ -32018,9 +32142,9 @@ Index (line 6) * whitespace, functions, calling: Calling Built-in. (line 10) * whitespace, newlines as: Options. (line 253) -* Williams, Kent: Contributors. (line 35) -* Woehlke, Matthew: Contributors. (line 80) -* Woods, John: Contributors. (line 28) +* Williams, Kent: Contributors. (line 34) +* Woehlke, Matthew: Contributors. (line 79) +* Woods, John: Contributors. (line 27) * word boundaries, matching: GNU Regexp Operators. (line 38) * word, regexp definition of: GNU Regexp Operators. @@ -32036,20 +32160,20 @@ Index * xgettext utility: String Extraction. (line 13) * XOR bitwise operation: Bitwise Functions. (line 6) * xor() function (gawk): Bitwise Functions. (line 55) -* Yawitz, Efraim: Contributors. (line 119) +* Yawitz, Efraim: Contributors. (line 124) * Zaretskii, Eli <1>: Bugs. (line 70) -* Zaretskii, Eli <2>: Contributors. (line 56) +* Zaretskii, Eli <2>: Contributors. (line 55) * Zaretskii, Eli: Acknowledgments. (line 60) * zero, negative vs. positive: Unexpected Results. (line 34) * zerofile.awk program: Empty Files. (line 21) -* Zoulas, Christos: Contributors. (line 67) +* Zoulas, Christos: Contributors. (line 66) * {} (braces): Profiling. (line 134) * {} (braces), actions and: Action Overview. (line 19) * {} (braces), statements, grouping: Statements. (line 10) * | (vertical bar): Regexp Operators. (line 69) * | (vertical bar), | operator (I/O) <1>: Precedence. (line 65) * | (vertical bar), | operator (I/O) <2>: Redirection. (line 57) -* | (vertical bar), | operator (I/O): Getline/Pipe. (line 10) +* | (vertical bar), | operator (I/O): Getline/Pipe. (line 9) * | (vertical bar), |& operator (I/O) <1>: Two-way I/O. (line 44) * | (vertical bar), |& operator (I/O) <2>: Precedence. (line 65) * | (vertical bar), |& operator (I/O) <3>: Redirection. (line 102) @@ -32071,520 +32195,520 @@ Index Tag Table: Node: Top1360 -Node: Foreword40338 -Node: Preface44683 -Ref: Preface-Footnote-147736 -Ref: Preface-Footnote-247832 -Node: History48064 -Node: Names50438 -Ref: Names-Footnote-151915 -Node: This Manual51987 -Ref: This Manual-Footnote-157761 -Node: Conventions57861 -Node: Manual History60013 -Ref: Manual History-Footnote-163461 -Ref: Manual History-Footnote-263502 -Node: How To Contribute63576 -Node: Acknowledgments64720 -Node: Getting Started68929 -Node: Running gawk71308 -Node: One-shot72494 -Node: Read Terminal73719 -Ref: Read Terminal-Footnote-175369 -Ref: Read Terminal-Footnote-275645 -Node: Long75816 -Node: Executable Scripts77192 -Ref: Executable Scripts-Footnote-179025 -Ref: Executable Scripts-Footnote-279127 -Node: Comments79674 -Node: Quoting82141 -Node: DOS Quoting86764 -Node: Sample Data Files87439 -Node: Very Simple90471 -Node: Two Rules95070 -Node: More Complex97217 -Ref: More Complex-Footnote-1100147 -Node: Statements/Lines100232 -Ref: Statements/Lines-Footnote-1104694 -Node: Other Features104959 -Node: When105887 -Node: Invoking Gawk108034 -Node: Command Line109495 -Node: Options110278 -Ref: Options-Footnote-1125670 -Node: Other Arguments125695 -Node: Naming Standard Input128353 -Node: Environment Variables129447 -Node: AWKPATH Variable130005 -Ref: AWKPATH Variable-Footnote-1132763 -Node: AWKLIBPATH Variable133023 -Node: Other Environment Variables133741 -Node: Exit Status136236 -Node: Include Files136911 -Node: Loading Shared Libraries140480 -Node: Obsolete141844 -Node: Undocumented142541 -Node: Regexp142784 -Node: Regexp Usage144173 -Node: Escape Sequences146199 -Node: Regexp Operators151868 -Ref: Regexp Operators-Footnote-1159248 -Ref: Regexp Operators-Footnote-2159395 -Node: Bracket Expressions159493 -Ref: table-char-classes161383 -Node: GNU Regexp Operators163906 -Node: Case-sensitivity167629 -Ref: Case-sensitivity-Footnote-1170597 -Ref: Case-sensitivity-Footnote-2170832 -Node: Leftmost Longest170940 -Node: Computed Regexps172141 -Node: Reading Files175478 -Node: Records177481 -Ref: Records-Footnote-1186370 -Node: Fields186407 -Ref: Fields-Footnote-1189440 -Node: Nonconstant Fields189526 -Node: Changing Fields191728 -Node: Field Separators197687 -Node: Default Field Splitting200316 -Node: Regexp Field Splitting201433 -Node: Single Character Fields204775 -Node: Command Line Field Separator205834 -Node: Field Splitting Summary209275 -Ref: Field Splitting Summary-Footnote-1212386 -Node: Constant Size212487 -Node: Splitting By Content217071 -Ref: Splitting By Content-Footnote-1220797 -Node: Multiple Line220837 -Ref: Multiple Line-Footnote-1226684 -Node: Getline226863 -Node: Plain Getline229079 -Node: Getline/Variable231174 -Node: Getline/File232321 -Node: Getline/Variable/File233662 -Ref: Getline/Variable/File-Footnote-1235261 -Node: Getline/Pipe235348 -Node: Getline/Variable/Pipe238048 -Node: Getline/Coprocess239155 -Node: Getline/Variable/Coprocess240407 -Node: Getline Notes241144 -Node: Getline Summary243931 -Ref: table-getline-variants244339 -Node: Read Timeout245251 -Ref: Read Timeout-Footnote-1248992 -Node: Command line directories249049 -Node: Printing249679 -Node: Print251310 -Node: Print Examples252647 -Node: Output Separators255431 -Node: OFMT257191 -Node: Printf258549 -Node: Basic Printf259455 -Node: Control Letters260994 -Node: Format Modifiers264806 -Node: Printf Examples270815 -Node: Redirection273530 -Node: Special Files280495 -Node: Special FD281028 -Ref: Special FD-Footnote-1284653 -Node: Special Network284727 -Node: Special Caveats285577 -Node: Close Files And Pipes286373 -Ref: Close Files And Pipes-Footnote-1293356 -Ref: Close Files And Pipes-Footnote-2293504 -Node: Expressions293654 -Node: Values294786 -Node: Constants295462 -Node: Scalar Constants296142 -Ref: Scalar Constants-Footnote-1297001 -Node: Nondecimal-numbers297183 -Node: Regexp Constants300183 -Node: Using Constant Regexps300658 -Node: Variables303713 -Node: Using Variables304368 -Node: Assignment Options306092 -Node: Conversion307964 -Ref: table-locale-affects313464 -Ref: Conversion-Footnote-1314088 -Node: All Operators314197 -Node: Arithmetic Ops314827 -Node: Concatenation317332 -Ref: Concatenation-Footnote-1320125 -Node: Assignment Ops320245 -Ref: table-assign-ops325233 -Node: Increment Ops326564 -Node: Truth Values and Conditions329999 -Node: Truth Values331082 -Node: Typing and Comparison332131 -Node: Variable Typing332920 -Ref: Variable Typing-Footnote-1336817 -Node: Comparison Operators336939 -Ref: table-relational-ops337349 -Node: POSIX String Comparison340898 -Ref: POSIX String Comparison-Footnote-1341854 -Node: Boolean Ops341992 -Ref: Boolean Ops-Footnote-1346070 -Node: Conditional Exp346161 -Node: Function Calls347893 -Node: Precedence351487 -Node: Locales355156 -Node: Patterns and Actions356245 -Node: Pattern Overview357299 -Node: Regexp Patterns358968 -Node: Expression Patterns359511 -Node: Ranges363196 -Node: BEGIN/END366162 -Node: Using BEGIN/END366924 -Ref: Using BEGIN/END-Footnote-1369655 -Node: I/O And BEGIN/END369761 -Node: BEGINFILE/ENDFILE372043 -Node: Empty374957 -Node: Using Shell Variables375273 -Node: Action Overview377558 -Node: Statements379915 -Node: If Statement381769 -Node: While Statement383268 -Node: Do Statement385312 -Node: For Statement386468 -Node: Switch Statement389620 -Node: Break Statement391717 -Node: Continue Statement393707 -Node: Next Statement395500 -Node: Nextfile Statement397890 -Node: Exit Statement400533 -Node: Built-in Variables402949 -Node: User-modified404044 -Ref: User-modified-Footnote-1412404 -Node: Auto-set412466 -Ref: Auto-set-Footnote-1425397 -Ref: Auto-set-Footnote-2425602 -Node: ARGC and ARGV425658 -Node: Arrays429509 -Node: Array Basics431014 -Node: Array Intro431840 -Node: Reference to Elements436158 -Node: Assigning Elements438428 -Node: Array Example438919 -Node: Scanning an Array440651 -Node: Controlling Scanning442965 -Ref: Controlling Scanning-Footnote-1447888 -Node: Delete448204 -Ref: Delete-Footnote-1450969 -Node: Numeric Array Subscripts451026 -Node: Uninitialized Subscripts453209 -Node: Multi-dimensional454837 -Node: Multi-scanning457931 -Node: Arrays of Arrays459522 -Node: Functions464163 -Node: Built-in464982 -Node: Calling Built-in466060 -Node: Numeric Functions468048 -Ref: Numeric Functions-Footnote-1471880 -Ref: Numeric Functions-Footnote-2472237 -Ref: Numeric Functions-Footnote-3472285 -Node: String Functions472554 -Ref: String Functions-Footnote-1496112 -Ref: String Functions-Footnote-2496241 -Ref: String Functions-Footnote-3496489 -Node: Gory Details496576 -Ref: table-sub-escapes498255 -Ref: table-sub-posix-92499609 -Ref: table-sub-proposed500960 -Ref: table-posix-sub502314 -Ref: table-gensub-escapes503859 -Ref: Gory Details-Footnote-1505035 -Ref: Gory Details-Footnote-2505086 -Node: I/O Functions505237 -Ref: I/O Functions-Footnote-1512222 -Node: Time Functions512369 -Ref: Time Functions-Footnote-1523302 -Ref: Time Functions-Footnote-2523370 -Ref: Time Functions-Footnote-3523528 -Ref: Time Functions-Footnote-4523639 -Ref: Time Functions-Footnote-5523751 -Ref: Time Functions-Footnote-6523978 -Node: Bitwise Functions524244 -Ref: table-bitwise-ops524802 -Ref: Bitwise Functions-Footnote-1529023 -Node: Type Functions529207 -Node: I18N Functions529677 -Node: User-defined531304 -Node: Definition Syntax532108 -Ref: Definition Syntax-Footnote-1537018 -Node: Function Example537087 -Node: Function Caveats539681 -Node: Calling A Function540102 -Node: Variable Scope541217 -Node: Pass By Value/Reference544180 -Node: Return Statement547688 -Node: Dynamic Typing550669 -Node: Indirect Calls551600 -Node: Library Functions561285 -Ref: Library Functions-Footnote-1564798 -Ref: Library Functions-Footnote-2564941 -Node: Library Names565112 -Ref: Library Names-Footnote-1568583 -Ref: Library Names-Footnote-2568803 -Node: General Functions568889 -Node: Strtonum Function569842 -Node: Assert Function572772 -Node: Round Function576098 -Node: Cliff Random Function577641 -Node: Ordinal Functions578657 -Ref: Ordinal Functions-Footnote-1581727 -Ref: Ordinal Functions-Footnote-2581979 -Node: Join Function582188 -Ref: Join Function-Footnote-1583959 -Node: Getlocaltime Function584159 -Node: Data File Management587874 -Node: Filetrans Function588506 -Node: Rewind Function592575 -Node: File Checking593962 -Node: Empty Files595056 -Node: Ignoring Assigns597286 -Node: Getopt Function598839 -Ref: Getopt Function-Footnote-1610143 -Node: Passwd Functions610346 -Ref: Passwd Functions-Footnote-1619321 -Node: Group Functions619409 -Node: Walking Arrays627493 -Node: Sample Programs629630 -Node: Running Examples630304 -Node: Clones631032 -Node: Cut Program632256 -Node: Egrep Program642101 -Ref: Egrep Program-Footnote-1649874 -Node: Id Program649984 -Node: Split Program653600 -Ref: Split Program-Footnote-1657119 -Node: Tee Program657247 -Node: Uniq Program660050 -Node: Wc Program667479 -Ref: Wc Program-Footnote-1671745 -Ref: Wc Program-Footnote-2671945 -Node: Miscellaneous Programs672037 -Node: Dupword Program673225 -Node: Alarm Program675256 -Node: Translate Program680005 -Ref: Translate Program-Footnote-1684392 -Ref: Translate Program-Footnote-2684620 -Node: Labels Program684754 -Ref: Labels Program-Footnote-1688125 -Node: Word Sorting688209 -Node: History Sorting692093 -Node: Extract Program693932 -Ref: Extract Program-Footnote-1701433 -Node: Simple Sed701561 -Node: Igawk Program704623 -Ref: Igawk Program-Footnote-1719780 -Ref: Igawk Program-Footnote-2719981 -Node: Anagram Program720119 -Node: Signature Program723187 -Node: Advanced Features724287 -Node: Nondecimal Data726169 -Node: Array Sorting727752 -Node: Controlling Array Traversal728449 -Node: Array Sorting Functions736687 -Ref: Array Sorting Functions-Footnote-1740361 -Ref: Array Sorting Functions-Footnote-2740454 -Node: Two-way I/O740648 -Ref: Two-way I/O-Footnote-1746080 -Node: TCP/IP Networking746150 -Node: Profiling748994 -Node: Internationalization756491 -Node: I18N and L10N757916 -Node: Explaining gettext758602 -Ref: Explaining gettext-Footnote-1763670 -Ref: Explaining gettext-Footnote-2763854 -Node: Programmer i18n764019 -Node: Translator i18n768221 -Node: String Extraction769014 -Ref: String Extraction-Footnote-1769975 -Node: Printf Ordering770061 -Ref: Printf Ordering-Footnote-1772845 -Node: I18N Portability772909 -Ref: I18N Portability-Footnote-1775358 -Node: I18N Example775421 -Ref: I18N Example-Footnote-1778059 -Node: Gawk I18N778131 -Node: Debugger778752 -Node: Debugging779723 -Node: Debugging Concepts780156 -Node: Debugging Terms782012 -Node: Awk Debugging784609 -Node: Sample Debugging Session785501 -Node: Debugger Invocation786021 -Node: Finding The Bug787353 -Node: List of Debugger Commands793841 -Node: Breakpoint Control795175 -Node: Debugger Execution Control798839 -Node: Viewing And Changing Data802199 -Node: Execution Stack805555 -Node: Debugger Info807022 -Node: Miscellaneous Debugger Commands811004 -Node: Readline Support816180 -Node: Limitations817011 -Node: Arbitrary Precision Arithmetic819263 -Ref: Arbitrary Precision Arithmetic-Footnote-1820914 -Node: General Arithmetic821062 -Node: Floating Point Issues822782 -Node: String Conversion Precision823663 -Ref: String Conversion Precision-Footnote-1825369 -Node: Unexpected Results825478 -Node: POSIX Floating Point Problems827631 -Ref: POSIX Floating Point Problems-Footnote-1831456 -Node: Integer Programming831494 -Node: Floating-point Programming833233 -Ref: Floating-point Programming-Footnote-1839564 -Ref: Floating-point Programming-Footnote-2839834 -Node: Floating-point Representation840098 -Node: Floating-point Context841263 -Ref: table-ieee-formats842102 -Node: Rounding Mode843486 -Ref: table-rounding-modes843965 -Ref: Rounding Mode-Footnote-1846980 -Node: Gawk and MPFR847159 -Node: Arbitrary Precision Floats848414 -Ref: Arbitrary Precision Floats-Footnote-1850857 -Node: Setting Precision851173 -Ref: table-predefined-precision-strings851859 -Node: Setting Rounding Mode854004 -Ref: table-gawk-rounding-modes854408 -Node: Floating-point Constants855595 -Node: Changing Precision857024 -Ref: Changing Precision-Footnote-1858424 -Node: Exact Arithmetic858598 -Node: Arbitrary Precision Integers861736 -Ref: Arbitrary Precision Integers-Footnote-1864754 -Node: Dynamic Extensions864901 -Node: Extension Intro866359 -Node: Plugin License867624 -Node: Extension Mechanism Outline868309 -Ref: load-extension868726 -Ref: load-new-function870204 -Ref: call-new-function871199 -Node: Extension API Description873214 -Node: Extension API Functions Introduction874427 -Node: General Data Types879293 -Ref: General Data Types-Footnote-1884895 -Node: Requesting Values885194 -Ref: table-value-types-returned885925 -Node: Constructor Functions886879 -Node: Registration Functions889899 -Node: Extension Functions890584 -Node: Exit Callback Functions892809 -Node: Extension Version String894058 -Node: Input Parsers894708 -Node: Output Wrappers904465 -Node: Two-way processors908975 -Node: Printing Messages911183 -Ref: Printing Messages-Footnote-1912260 -Node: Updating `ERRNO'912412 -Node: Accessing Parameters913151 -Node: Symbol Table Access914381 -Node: Symbol table by name914893 -Node: Symbol table by cookie916640 -Ref: Symbol table by cookie-Footnote-1920770 -Node: Cached values920833 -Ref: Cached values-Footnote-1924282 -Node: Array Manipulation924373 -Ref: Array Manipulation-Footnote-1925471 -Node: Array Data Types925510 -Ref: Array Data Types-Footnote-1928213 -Node: Array Functions928305 -Node: Flattening Arrays932071 -Node: Creating Arrays938923 -Node: Extension API Variables943648 -Node: Extension Versioning944284 -Node: Extension API Informational Variables946185 -Node: Extension API Boilerplate947271 -Node: Finding Extensions951075 -Node: Extension Example951635 -Node: Internal File Description952366 -Node: Internal File Ops956457 -Ref: Internal File Ops-Footnote-1967965 -Node: Using Internal File Ops968105 -Ref: Using Internal File Ops-Footnote-1970458 -Node: Extension Samples970724 -Node: Extension Sample File Functions972248 -Node: Extension Sample Fnmatch980735 -Node: Extension Sample Fork982461 -Node: Extension Sample Inplace983679 -Node: Extension Sample Ord985457 -Node: Extension Sample Readdir986293 -Node: Extension Sample Revout987825 -Node: Extension Sample Rev2way988418 -Node: Extension Sample Read write array989108 -Node: Extension Sample Readfile990991 -Node: Extension Sample API Tests991809 -Node: Extension Sample Time992334 -Node: gawkextlib993698 -Node: Language History996458 -Node: V7/SVR3.1997980 -Node: SVR41000301 -Node: POSIX1001743 -Node: BTL1003129 -Node: POSIX/GNU1003863 -Node: Common Extensions1009398 -Node: Ranges and Locales1010704 -Ref: Ranges and Locales-Footnote-11015322 -Ref: Ranges and Locales-Footnote-21015349 -Ref: Ranges and Locales-Footnote-31015609 -Node: Contributors1015830 -Node: Installation1020709 -Node: Gawk Distribution1021603 -Node: Getting1022087 -Node: Extracting1022913 -Node: Distribution contents1024605 -Node: Unix Installation1029866 -Node: Quick Installation1030483 -Node: Additional Configuration Options1032927 -Node: Configuration Philosophy1034404 -Node: Non-Unix Installation1036758 -Node: PC Installation1037216 -Node: PC Binary Installation1038515 -Node: PC Compiling1040363 -Node: PC Testing1043307 -Node: PC Using1044483 -Node: Cygwin1048668 -Node: MSYS1049668 -Node: VMS Installation1050182 -Node: VMS Compilation1050785 -Ref: VMS Compilation-Footnote-11051792 -Node: VMS Installation Details1051850 -Node: VMS Running1053485 -Node: VMS Old Gawk1055092 -Node: Bugs1055566 -Node: Other Versions1059418 -Node: Notes1065019 -Node: Compatibility Mode1065819 -Node: Additions1066602 -Node: Accessing The Source1067529 -Node: Adding Code1068969 -Node: New Ports1075014 -Node: Derived Files1079149 -Ref: Derived Files-Footnote-11084470 -Ref: Derived Files-Footnote-21084504 -Ref: Derived Files-Footnote-31085104 -Node: Future Extensions1085202 -Node: Implementation Limitations1085783 -Node: Extension Design1087035 -Node: Old Extension Problems1088189 -Ref: Old Extension Problems-Footnote-11089697 -Node: Extension New Mechanism Goals1089754 -Ref: Extension New Mechanism Goals-Footnote-11093120 -Node: Extension Other Design Decisions1093306 -Node: Extension Future Growth1095412 -Node: Old Extension Mechanism1096248 -Node: Basic Concepts1097988 -Node: Basic High Level1098669 -Ref: figure-general-flow1098940 -Ref: figure-process-flow1099539 -Ref: Basic High Level-Footnote-11102768 -Node: Basic Data Typing1102953 -Node: Glossary1106308 -Node: Copying1131770 -Node: GNU Free Documentation License1169327 -Node: Index1194464 +Node: Foreword40460 +Node: Preface44805 +Ref: Preface-Footnote-147858 +Ref: Preface-Footnote-247954 +Node: History48186 +Node: Names50560 +Ref: Names-Footnote-152037 +Node: This Manual52109 +Ref: This Manual-Footnote-157883 +Node: Conventions57983 +Node: Manual History60139 +Ref: Manual History-Footnote-163587 +Ref: Manual History-Footnote-263628 +Node: How To Contribute63702 +Node: Acknowledgments64846 +Node: Getting Started69055 +Node: Running gawk71434 +Node: One-shot72620 +Node: Read Terminal73845 +Ref: Read Terminal-Footnote-175495 +Ref: Read Terminal-Footnote-275771 +Node: Long75942 +Node: Executable Scripts77318 +Ref: Executable Scripts-Footnote-179151 +Ref: Executable Scripts-Footnote-279253 +Node: Comments79800 +Node: Quoting82267 +Node: DOS Quoting86890 +Node: Sample Data Files87565 +Node: Very Simple90609 +Node: Two Rules95208 +Node: More Complex97355 +Ref: More Complex-Footnote-1100285 +Node: Statements/Lines100370 +Ref: Statements/Lines-Footnote-1104832 +Node: Other Features105097 +Node: When106025 +Node: Invoking Gawk108172 +Node: Command Line109633 +Node: Options110416 +Ref: Options-Footnote-1125808 +Node: Other Arguments125833 +Node: Naming Standard Input128491 +Node: Environment Variables129585 +Node: AWKPATH Variable130143 +Ref: AWKPATH Variable-Footnote-1132901 +Node: AWKLIBPATH Variable133161 +Node: Other Environment Variables133879 +Node: Exit Status136842 +Node: Include Files137517 +Node: Loading Shared Libraries141086 +Node: Obsolete142450 +Node: Undocumented143147 +Node: Regexp143389 +Node: Regexp Usage144778 +Node: Escape Sequences146804 +Node: Regexp Operators152473 +Ref: Regexp Operators-Footnote-1159853 +Ref: Regexp Operators-Footnote-2160000 +Node: Bracket Expressions160098 +Ref: table-char-classes161988 +Node: GNU Regexp Operators164511 +Node: Case-sensitivity168234 +Ref: Case-sensitivity-Footnote-1171202 +Ref: Case-sensitivity-Footnote-2171437 +Node: Leftmost Longest171545 +Node: Computed Regexps172746 +Node: Reading Files176083 +Node: Records178085 +Ref: Records-Footnote-1186974 +Node: Fields187011 +Ref: Fields-Footnote-1190044 +Node: Nonconstant Fields190130 +Node: Changing Fields192332 +Node: Field Separators198291 +Node: Default Field Splitting200920 +Node: Regexp Field Splitting202037 +Node: Single Character Fields205379 +Node: Command Line Field Separator206438 +Node: Field Splitting Summary209879 +Ref: Field Splitting Summary-Footnote-1212990 +Node: Constant Size213091 +Node: Splitting By Content217675 +Ref: Splitting By Content-Footnote-1221401 +Node: Multiple Line221441 +Ref: Multiple Line-Footnote-1227288 +Node: Getline227467 +Node: Plain Getline229683 +Node: Getline/Variable231778 +Node: Getline/File232925 +Node: Getline/Variable/File234266 +Ref: Getline/Variable/File-Footnote-1235865 +Node: Getline/Pipe235952 +Node: Getline/Variable/Pipe238651 +Node: Getline/Coprocess239758 +Node: Getline/Variable/Coprocess241010 +Node: Getline Notes241747 +Node: Getline Summary244534 +Ref: table-getline-variants244942 +Node: Read Timeout245854 +Ref: Read Timeout-Footnote-1249595 +Node: Command line directories249652 +Node: Printing250282 +Node: Print251913 +Node: Print Examples253250 +Node: Output Separators256034 +Node: OFMT257794 +Node: Printf259152 +Node: Basic Printf260058 +Node: Control Letters261597 +Node: Format Modifiers265409 +Node: Printf Examples271418 +Node: Redirection274133 +Node: Special Files281098 +Node: Special FD281631 +Ref: Special FD-Footnote-1285256 +Node: Special Network285330 +Node: Special Caveats286180 +Node: Close Files And Pipes286976 +Ref: Close Files And Pipes-Footnote-1293959 +Ref: Close Files And Pipes-Footnote-2294107 +Node: Expressions294257 +Node: Values295389 +Node: Constants296065 +Node: Scalar Constants296745 +Ref: Scalar Constants-Footnote-1297604 +Node: Nondecimal-numbers297786 +Node: Regexp Constants300786 +Node: Using Constant Regexps301261 +Node: Variables304316 +Node: Using Variables304971 +Node: Assignment Options306695 +Node: Conversion308567 +Ref: table-locale-affects314068 +Ref: Conversion-Footnote-1314692 +Node: All Operators314801 +Node: Arithmetic Ops315431 +Node: Concatenation317936 +Ref: Concatenation-Footnote-1320728 +Node: Assignment Ops320848 +Ref: table-assign-ops325836 +Node: Increment Ops327167 +Node: Truth Values and Conditions330601 +Node: Truth Values331684 +Node: Typing and Comparison332733 +Node: Variable Typing333526 +Ref: Variable Typing-Footnote-1337423 +Node: Comparison Operators337545 +Ref: table-relational-ops337955 +Node: POSIX String Comparison341504 +Ref: POSIX String Comparison-Footnote-1342460 +Node: Boolean Ops342598 +Ref: Boolean Ops-Footnote-1346676 +Node: Conditional Exp346767 +Node: Function Calls348499 +Node: Precedence352093 +Node: Locales355762 +Node: Patterns and Actions356851 +Node: Pattern Overview357905 +Node: Regexp Patterns359574 +Node: Expression Patterns360117 +Node: Ranges363802 +Node: BEGIN/END366768 +Node: Using BEGIN/END367530 +Ref: Using BEGIN/END-Footnote-1370261 +Node: I/O And BEGIN/END370367 +Node: BEGINFILE/ENDFILE372649 +Node: Empty375563 +Node: Using Shell Variables375879 +Node: Action Overview378164 +Node: Statements380521 +Node: If Statement382375 +Node: While Statement383874 +Node: Do Statement385918 +Node: For Statement387074 +Node: Switch Statement390226 +Node: Break Statement392323 +Node: Continue Statement394313 +Node: Next Statement396106 +Node: Nextfile Statement398496 +Node: Exit Statement401139 +Node: Built-in Variables403555 +Node: User-modified404650 +Ref: User-modified-Footnote-1413008 +Node: Auto-set413070 +Ref: Auto-set-Footnote-1426540 +Ref: Auto-set-Footnote-2426745 +Node: ARGC and ARGV426801 +Node: Arrays430652 +Node: Array Basics432157 +Node: Array Intro432983 +Node: Reference to Elements437300 +Node: Assigning Elements439570 +Node: Array Example440061 +Node: Scanning an Array441793 +Node: Controlling Scanning444107 +Ref: Controlling Scanning-Footnote-1449194 +Node: Delete449510 +Ref: Delete-Footnote-1452275 +Node: Numeric Array Subscripts452332 +Node: Uninitialized Subscripts454515 +Node: Multidimensional456142 +Node: Multiscanning459234 +Node: Arrays of Arrays460823 +Node: Functions465463 +Node: Built-in466282 +Node: Calling Built-in467360 +Node: Numeric Functions469348 +Ref: Numeric Functions-Footnote-1473180 +Ref: Numeric Functions-Footnote-2473537 +Ref: Numeric Functions-Footnote-3473585 +Node: String Functions473854 +Ref: String Functions-Footnote-1496774 +Ref: String Functions-Footnote-2496903 +Ref: String Functions-Footnote-3497151 +Node: Gory Details497238 +Ref: table-sub-escapes498917 +Ref: table-sub-posix-92500271 +Ref: table-sub-proposed501622 +Ref: table-posix-sub502976 +Ref: table-gensub-escapes504521 +Ref: Gory Details-Footnote-1505697 +Ref: Gory Details-Footnote-2505748 +Node: I/O Functions505899 +Ref: I/O Functions-Footnote-1512884 +Node: Time Functions513031 +Ref: Time Functions-Footnote-1523964 +Ref: Time Functions-Footnote-2524032 +Ref: Time Functions-Footnote-3524190 +Ref: Time Functions-Footnote-4524301 +Ref: Time Functions-Footnote-5524413 +Ref: Time Functions-Footnote-6524640 +Node: Bitwise Functions524906 +Ref: table-bitwise-ops525468 +Ref: Bitwise Functions-Footnote-1529689 +Node: Type Functions529873 +Node: I18N Functions531024 +Node: User-defined532651 +Node: Definition Syntax533455 +Ref: Definition Syntax-Footnote-1538365 +Node: Function Example538434 +Node: Function Caveats541028 +Node: Calling A Function541449 +Node: Variable Scope542564 +Node: Pass By Value/Reference545527 +Node: Return Statement549035 +Node: Dynamic Typing552016 +Node: Indirect Calls552947 +Node: Library Functions562632 +Ref: Library Functions-Footnote-1566145 +Ref: Library Functions-Footnote-2566288 +Node: Library Names566459 +Ref: Library Names-Footnote-1569930 +Ref: Library Names-Footnote-2570150 +Node: General Functions570236 +Node: Strtonum Function571264 +Node: Assert Function574194 +Node: Round Function577520 +Node: Cliff Random Function579063 +Node: Ordinal Functions580079 +Ref: Ordinal Functions-Footnote-1583149 +Ref: Ordinal Functions-Footnote-2583401 +Node: Join Function583610 +Ref: Join Function-Footnote-1585381 +Node: Getlocaltime Function585581 +Node: Readfile Function589322 +Node: Data File Management591161 +Node: Filetrans Function591793 +Node: Rewind Function595862 +Node: File Checking597249 +Node: Empty Files598343 +Node: Ignoring Assigns600573 +Node: Getopt Function602126 +Ref: Getopt Function-Footnote-1613429 +Node: Passwd Functions613632 +Ref: Passwd Functions-Footnote-1622607 +Node: Group Functions622695 +Node: Walking Arrays630779 +Node: Sample Programs632916 +Node: Running Examples633590 +Node: Clones634318 +Node: Cut Program635542 +Node: Egrep Program645387 +Ref: Egrep Program-Footnote-1653160 +Node: Id Program653270 +Node: Split Program656886 +Ref: Split Program-Footnote-1660405 +Node: Tee Program660533 +Node: Uniq Program663336 +Node: Wc Program670765 +Ref: Wc Program-Footnote-1675031 +Ref: Wc Program-Footnote-2675231 +Node: Miscellaneous Programs675323 +Node: Dupword Program676511 +Node: Alarm Program678542 +Node: Translate Program683295 +Ref: Translate Program-Footnote-1687682 +Ref: Translate Program-Footnote-2687930 +Node: Labels Program688064 +Ref: Labels Program-Footnote-1691435 +Node: Word Sorting691519 +Node: History Sorting695403 +Node: Extract Program697242 +Ref: Extract Program-Footnote-1704745 +Node: Simple Sed704873 +Node: Igawk Program707935 +Ref: Igawk Program-Footnote-1723092 +Ref: Igawk Program-Footnote-2723293 +Node: Anagram Program723431 +Node: Signature Program726499 +Node: Advanced Features727599 +Node: Nondecimal Data729485 +Node: Array Sorting731068 +Node: Controlling Array Traversal731765 +Node: Array Sorting Functions740049 +Ref: Array Sorting Functions-Footnote-1743918 +Node: Two-way I/O744112 +Ref: Two-way I/O-Footnote-1749544 +Node: TCP/IP Networking749614 +Node: Profiling752458 +Node: Internationalization759955 +Node: I18N and L10N761380 +Node: Explaining gettext762066 +Ref: Explaining gettext-Footnote-1767134 +Ref: Explaining gettext-Footnote-2767318 +Node: Programmer i18n767483 +Node: Translator i18n771685 +Node: String Extraction772478 +Ref: String Extraction-Footnote-1773439 +Node: Printf Ordering773525 +Ref: Printf Ordering-Footnote-1776309 +Node: I18N Portability776373 +Ref: I18N Portability-Footnote-1778822 +Node: I18N Example778885 +Ref: I18N Example-Footnote-1781523 +Node: Gawk I18N781595 +Node: Debugger782216 +Node: Debugging783187 +Node: Debugging Concepts783620 +Node: Debugging Terms785476 +Node: Awk Debugging788073 +Node: Sample Debugging Session788965 +Node: Debugger Invocation789485 +Node: Finding The Bug790817 +Node: List of Debugger Commands797305 +Node: Breakpoint Control798639 +Node: Debugger Execution Control802303 +Node: Viewing And Changing Data805663 +Node: Execution Stack809019 +Node: Debugger Info810486 +Node: Miscellaneous Debugger Commands814468 +Node: Readline Support819644 +Node: Limitations820475 +Node: Arbitrary Precision Arithmetic822727 +Ref: Arbitrary Precision Arithmetic-Footnote-1824376 +Node: General Arithmetic824524 +Node: Floating Point Issues826244 +Node: String Conversion Precision827125 +Ref: String Conversion Precision-Footnote-1828830 +Node: Unexpected Results828939 +Node: POSIX Floating Point Problems831092 +Ref: POSIX Floating Point Problems-Footnote-1834917 +Node: Integer Programming834955 +Node: Floating-point Programming836694 +Ref: Floating-point Programming-Footnote-1843025 +Ref: Floating-point Programming-Footnote-2843295 +Node: Floating-point Representation843559 +Node: Floating-point Context844724 +Ref: table-ieee-formats845563 +Node: Rounding Mode846947 +Ref: table-rounding-modes847426 +Ref: Rounding Mode-Footnote-1850441 +Node: Gawk and MPFR850620 +Node: Arbitrary Precision Floats851875 +Ref: Arbitrary Precision Floats-Footnote-1854318 +Node: Setting Precision854634 +Ref: table-predefined-precision-strings855320 +Node: Setting Rounding Mode857465 +Ref: table-gawk-rounding-modes857869 +Node: Floating-point Constants859056 +Node: Changing Precision860485 +Ref: Changing Precision-Footnote-1861882 +Node: Exact Arithmetic862056 +Node: Arbitrary Precision Integers865194 +Ref: Arbitrary Precision Integers-Footnote-1868212 +Node: Dynamic Extensions868359 +Node: Extension Intro869817 +Node: Plugin License871082 +Node: Extension Mechanism Outline871767 +Ref: load-extension872184 +Ref: load-new-function873662 +Ref: call-new-function874657 +Node: Extension API Description876672 +Node: Extension API Functions Introduction877885 +Node: General Data Types882751 +Ref: General Data Types-Footnote-1888350 +Node: Requesting Values888649 +Ref: table-value-types-returned889380 +Node: Constructor Functions890334 +Node: Registration Functions893354 +Node: Extension Functions894039 +Node: Exit Callback Functions896264 +Node: Extension Version String897513 +Node: Input Parsers898163 +Node: Output Wrappers907920 +Node: Two-way processors912430 +Node: Printing Messages914638 +Ref: Printing Messages-Footnote-1915715 +Node: Updating `ERRNO'915867 +Node: Accessing Parameters916606 +Node: Symbol Table Access917836 +Node: Symbol table by name918348 +Node: Symbol table by cookie920095 +Ref: Symbol table by cookie-Footnote-1924225 +Node: Cached values924288 +Ref: Cached values-Footnote-1927737 +Node: Array Manipulation927828 +Ref: Array Manipulation-Footnote-1928926 +Node: Array Data Types928965 +Ref: Array Data Types-Footnote-1931668 +Node: Array Functions931760 +Node: Flattening Arrays935526 +Node: Creating Arrays942378 +Node: Extension API Variables947103 +Node: Extension Versioning947739 +Node: Extension API Informational Variables949640 +Node: Extension API Boilerplate950726 +Node: Finding Extensions954530 +Node: Extension Example955090 +Node: Internal File Description955820 +Node: Internal File Ops959911 +Ref: Internal File Ops-Footnote-1971419 +Node: Using Internal File Ops971559 +Ref: Using Internal File Ops-Footnote-1973912 +Node: Extension Samples974178 +Node: Extension Sample File Functions975702 +Node: Extension Sample Fnmatch984187 +Node: Extension Sample Fork985913 +Node: Extension Sample Inplace987131 +Node: Extension Sample Ord988909 +Node: Extension Sample Readdir989745 +Node: Extension Sample Revout991277 +Node: Extension Sample Rev2way991870 +Node: Extension Sample Read write array992560 +Node: Extension Sample Readfile994443 +Node: Extension Sample API Tests995261 +Node: Extension Sample Time995786 +Node: gawkextlib997150 +Node: Language History999910 +Node: V7/SVR3.11001432 +Node: SVR41003752 +Node: POSIX1005194 +Node: BTL1006580 +Node: POSIX/GNU1007314 +Node: Common Extensions1012849 +Node: Ranges and Locales1014155 +Ref: Ranges and Locales-Footnote-11018773 +Ref: Ranges and Locales-Footnote-21018800 +Ref: Ranges and Locales-Footnote-31019060 +Node: Contributors1019281 +Node: Installation1024356 +Node: Gawk Distribution1025250 +Node: Getting1025734 +Node: Extracting1026560 +Node: Distribution contents1028252 +Node: Unix Installation1033772 +Node: Quick Installation1034389 +Node: Additional Configuration Options1036833 +Node: Configuration Philosophy1038569 +Node: Non-Unix Installation1040923 +Node: PC Installation1041381 +Node: PC Binary Installation1042680 +Node: PC Compiling1044528 +Node: PC Testing1047472 +Node: PC Using1048648 +Node: Cygwin1052833 +Node: MSYS1053833 +Node: VMS Installation1054347 +Node: VMS Compilation1054950 +Ref: VMS Compilation-Footnote-11055957 +Node: VMS Installation Details1056015 +Node: VMS Running1057650 +Node: VMS Old Gawk1059257 +Node: Bugs1059731 +Node: Other Versions1063587 +Node: Notes1069671 +Node: Compatibility Mode1070471 +Node: Additions1071254 +Node: Accessing The Source1072181 +Node: Adding Code1073621 +Node: New Ports1079666 +Node: Derived Files1083801 +Ref: Derived Files-Footnote-11089122 +Ref: Derived Files-Footnote-21089156 +Ref: Derived Files-Footnote-31089756 +Node: Future Extensions1089854 +Node: Implementation Limitations1090431 +Node: Extension Design1091683 +Node: Old Extension Problems1092837 +Ref: Old Extension Problems-Footnote-11094345 +Node: Extension New Mechanism Goals1094402 +Ref: Extension New Mechanism Goals-Footnote-11097767 +Node: Extension Other Design Decisions1097953 +Node: Extension Future Growth1100059 +Node: Old Extension Mechanism1100895 +Node: Basic Concepts1102635 +Node: Basic High Level1103316 +Ref: figure-general-flow1103587 +Ref: figure-process-flow1104186 +Ref: Basic High Level-Footnote-11107415 +Node: Basic Data Typing1107600 +Node: Glossary1110955 +Node: Copying1136417 +Node: GNU Free Documentation License1173974 +Node: Index1199111 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 240669cf..6e5fb555 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -120,13 +120,6 @@ @end macro @end ifnothtml -@set FN file name -@set FFN File Name -@set DF data file -@set DDF Data File -@set PVERSION version -@set CTL Ctrl - @ignore Some comments on the layout for TeX. 1. Use at least texinfo.tex 2000-09-06.09 @@ -201,6 +194,7 @@ supports it in developing GNU and promoting software freedom.'' @c during editing and review. @setchapternewpage odd +@shorttitlepage GNU Awk @titlepage @title @value{TITLE} @subtitle @value{SUBTITLE} @@ -410,7 +404,7 @@ particular records in a file and perform operations upon them. * Field Splitting Summary:: Some final points and a summary table. * Constant Size:: Reading constant width data. * Splitting By Content:: Defining Fields By Content -* Multiple Line:: Reading multi-line records. +* Multiple Line:: Reading multiline records. * Getline:: Reading files under explicit program control using the @code{getline} function. @@ -561,9 +555,9 @@ particular records in a file and perform operations upon them. @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. -* Multi-dimensional:: Emulating multidimensional arrays in +* Multidimensional:: Emulating multidimensional arrays in @command{awk}. -* Multi-scanning:: Scanning multidimensional arrays. +* Multiscanning:: Scanning multidimensional arrays. * Arrays of Arrays:: True multidimensional arrays. * Built-in:: Summarizes the built-in functions. * Calling Built-in:: How to call built-in functions. @@ -615,6 +609,8 @@ particular records in a file and perform operations upon them. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. +* Readfile Function:: A function to read an entire file at + once. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -1188,17 +1184,17 @@ wrote the bulk of @cite{TCP/IP Internetworking with @command{gawk}} (a separate document, available as part of the @command{gawk} distribution). His code finally became part of the main @command{gawk} distribution -with @command{gawk} @value{PVERSION} 3.1. +with @command{gawk} version 3.1. John Haque rewrote the @command{gawk} internals, in the process providing an @command{awk}-level debugger. This version became available as -@command{gawk} @value{PVERSION} 4.0, in 2011. +@command{gawk} version 4.0, in 2011. @xref{Contributors}, for a complete list of those who made important contributions to @command{gawk}. @node Names -@section A Rose by Any Other Name +@unnumberedsec A Rose by Any Other Name @cindex @command{awk}, new vs.@: old The @command{awk} language has evolved over the years. Full details are @@ -1234,7 +1230,7 @@ we simply use the term @command{awk}. When referring to a feature that is specific to the GNU implementation, we use the term @command{gawk}. @node This Manual -@section Using This Book +@unnumberedsec Using This Book @cindex @command{awk}, terms describing The term @command{awk} refers to a particular program as well as to the language you @@ -1407,7 +1403,7 @@ present the licenses that cover the @command{gawk} source code and this @value{DOCUMENT}, respectively. @node Conventions -@section Typographical Conventions +@unnumberedsec Typographical Conventions @cindex Texinfo This @value{DOCUMENT} is written in @uref{http://www.gnu.org/software/texinfo/, Texinfo}, @@ -1446,23 +1442,23 @@ emphasized @emph{like this}, and if a point needs to be made strongly, it is done @strong{like this}. The first occurrence of a new term is usually its @dfn{definition} and appears in the same font as the previous occurrence of ``definition'' in this sentence. -Finally, @value{FN}s are indicated like this: @file{/path/to/ourfile}. +Finally, file names are indicated like this: @file{/path/to/ourfile}. @end ifnotinfo Characters that you type at the keyboard look @kbd{like this}. In particular, there are special characters called ``control characters.'' These are characters that you type by holding down both the @kbd{CONTROL} key and -another key, at the same time. For example, a @kbd{@value{CTL}-d} is typed +another key, at the same time. For example, a @kbd{Ctrl-d} is typed by first pressing and holding the @kbd{CONTROL} key, next pressing the @kbd{d} key and finally releasing both keys. @c fakenode --- for prepinfo -@subsubheading Dark Corners +@unnumberedsubsec Dark Corners @cindex Kernighan, Brian @quotation @i{Dark corners are basically fractal --- no matter how much -you illuminate, there's always a smaller but darker one.}@* -Brian Kernighan +you illuminate, there's always a smaller but darker one.} +@author Brian Kernighan @end quotation @cindex d.c., See dark corner @@ -1597,7 +1593,7 @@ of @cite{GAWK: The GNU Awk User's Guide}. Edition @value{EDITION} maintains the basic structure of Edition 1.0, but with significant additional material, reflecting the host of new features -in @command{gawk} @value{PVERSION} @value{VERSION}. +in @command{gawk} version @value{VERSION}. Of particular note is @ref{Array Sorting}, @ref{Bitwise Functions}, @@ -2033,9 +2029,9 @@ awk '@var{program}' @noindent @command{awk} applies the @var{program} to the @dfn{standard input}, which usually means whatever you type on the terminal. This continues -until you indicate end-of-file by typing @kbd{@value{CTL}-d}. +until you indicate end-of-file by typing @kbd{Ctrl-d}. (On other operating systems, the end-of-file character may be different. -For example, on OS/2, it is @kbd{@value{CTL}-z}.) +For example, on OS/2, it is @kbd{Ctrl-z}.) @cindex files, input, See input files @cindex input files, running @command{awk} without @@ -2081,7 +2077,7 @@ $ @kbd{awk '@{ print @}'} @print{} Four score and seven years ago, ... @kbd{What, me worry?} @print{} What, me worry? -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @node Long @@ -2102,7 +2098,7 @@ awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{} @cindex command line, options @cindex options, command-line The @option{-f} instructs the @command{awk} utility to get the @command{awk} program -from the file @var{source-file}. Any @value{FN} can be used for +from the file @var{source-file}. Any file name can be used for @var{source-file}. For example, you could put the program: @example @@ -2127,8 +2123,8 @@ awk "BEGIN @{ print \"Don't Panic!\" @}" @noindent This was explained earlier (@pxref{Read Terminal}). -Note that you don't usually need single quotes around the @value{FN} that you -specify with @option{-f}, because most @value{FN}s don't contain any of the shell's +Note that you don't usually need single quotes around the file name that you +specify with @option{-f}, because most file names don't contain any of the shell's special characters. Notice that in @file{advice}, the @command{awk} program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. @@ -2138,7 +2134,7 @@ for programs that are provided on the @command{awk} command line. @c STARTOFRANGE qs2x @cindex @code{'} (single quote) If you want to clearly identify your @command{awk} program files as such, -you can add the extension @file{.awk} to the @value{FN}. This doesn't +you can add the extension @file{.awk} to the file name. This doesn't affect the execution of the @command{awk} program but it does make ``housekeeping'' easier. @@ -2165,13 +2161,13 @@ BEGIN @{ print "Don't Panic!" @} After making this file executable (with the @command{chmod} utility), simply type @samp{advice} at the shell and the system arranges to run @command{awk}@footnote{The -line beginning with @samp{#!} lists the full @value{FN} of an interpreter +line beginning with @samp{#!} lists the full file name of an interpreter to run and an optional initial command-line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument -in the list is the full @value{FN} of the @command{awk} program. +in the list is the full file name of the @command{awk} program. The rest of the -argument list contains either options to @command{awk}, or @value{DF}s, +argument list contains either options to @command{awk}, or data files, or both. Note that on many systems @command{awk} may be found in @file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had typed @samp{awk -f advice}: @@ -2421,7 +2417,7 @@ awk -F"" '@var{program}' @var{files} # wrong! @noindent In the second case, @command{awk} will attempt to use the text of the program -as the value of @code{FS}, and the first @value{FN} as the text of the program! +as the value of @code{FS}, and the first file name as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize @@ -2536,19 +2532,19 @@ gawk "@{ print \"\042\" $0 \"\042\" @}" @var{file} @node Sample Data Files -@section @value{DDF}s for the Examples +@section Data Files for the Examples @c For gawk >= 4.0, update these data files. No-one has such slow modems! @cindex input files, examples @cindex @code{BBS-list} file Many of the examples in this @value{DOCUMENT} take their input from two sample -@value{DF}s. The first, @file{BBS-list}, represents a list of +data files. The first, @file{BBS-list}, represents a list of computer bulletin board systems together with information about those systems. -The second @value{DF}, called @file{inventory-shipped}, contains +The second data file, called @file{inventory-shipped}, contains information about monthly shipments. In both files, each line is considered to be one @dfn{record}. -In the @value{DF} @file{BBS-list}, each record contains the name of a computer +In the data file @file{BBS-list}, each record contains the name of a computer bulletin board, its phone number, the board's baud rate(s), and a code for the number of hours it is operational. An @samp{A} in the last column means the board operates 24 hours a day. A @samp{B} in the last @@ -2578,7 +2574,7 @@ sabafoo 555-2127 1200/300 C @end example @cindex @code{inventory-shipped} file -The @value{DF} @file{inventory-shipped} represents +The data file @file{inventory-shipped} represents information about shipments during the year. Each record contains the month, the number of green crates shipped, the number of red boxes shipped, the number of @@ -2622,8 +2618,8 @@ learn in this @value{DOCUMENT}. @cindex Texinfo If you are using the stand-alone version of Info, see @ref{Extract Program}, -for an @command{awk} program that extracts these @value{DF}s from -@file{gawk.texi}, the Texinfo source file for this Info file. +for an @command{awk} program that extracts these data files from +@file{gawk.texi}, the (generated) Texinfo source file for this Info file. @end ifinfo @node Very Simple @@ -2685,9 +2681,9 @@ collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description of the program will give you a good idea of what is going on, but please read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) -Most of the examples use a @value{DF} named @file{data}. This is just a +Most of the examples use a data file named @file{data}. This is just a placeholder; if you use these programs yourself, substitute -your own @value{FN}s for @file{data}. +your own file names for @file{data}. For future reference, note that there is often more than one way to do things in @command{awk}. At some point, you may want to look back at these examples and see if @@ -2777,7 +2773,7 @@ awk 'END @{ print NR @}' data @end example @item -Print the even-numbered lines in the @value{DF}: +Print the even-numbered lines in the data file: @example awk 'NR % 2 == 0' data @@ -2819,7 +2815,7 @@ This program prints every line that contains the string @samp{12} @emph{or} the string @samp{21}. If a line contains both strings, it is printed twice, once by each rule. -This is what happens if we run this program on our two sample @value{DF}s, +This is what happens if we run this program on our two sample data files, @file{BBS-list} and @file{inventory-shipped}: @example @@ -2885,7 +2881,7 @@ the file. The fourth field identifies the group of the file. The fifth field contains the size of the file in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the @value{FN}.@footnote{The @samp{LC_ALL=C} is +contains the file name.@footnote{The @samp{LC_ALL=C} is needed to produce this traditional-style output from @command{ls}.} @c @cindex automatic initialization @@ -3294,8 +3290,8 @@ conventions. @cindex @code{-} (hyphen), filenames beginning with @cindex hyphen (@code{-}), filenames beginning with -This is useful if you have @value{FN}s that start with @samp{-}, -or in shell scripts, if you have @value{FN}s that will be specified +This is useful if you have file names that start with @samp{-}, +or in shell scripts, if you have file names that will be specified by the user that could start with @samp{-}. It is also useful for passing options on to the @command{awk} program; see @ref{Getopt Function}. @@ -3513,7 +3509,7 @@ when parsing numeric input data (@pxref{Locales}). Enable pretty-printing of @command{awk} programs. By default, output program is created in a file named @file{awkprof.out}. The optional @var{file} argument allows you to specify a different -@value{FN} for the output. +file name for the output. No space is allowed between the @option{-o} and @var{file}, if @var{file} is supplied. @@ -3534,7 +3530,7 @@ Enable profiling of @command{awk} programs (@pxref{Profiling}). By default, profiles are created in a file named @file{awkprof.out}. The optional @var{file} argument allows you to specify a different -@value{FN} for the profile file. +file name for the profile file. No space is allowed between the @option{-p} and @var{file}, if @var{file} is supplied. @@ -3662,7 +3658,7 @@ function names must be unique.) With standard @command{awk}, library functions can still be used, even if the program is entered at the terminal, by specifying @samp{-f /dev/tty}. After typing your program, -type @kbd{@value{CTL}-d} (the end-of-file character) to terminate it. +type @kbd{Ctrl-d} (the end-of-file character) to terminate it. (You may also use @samp{-f -} to read program source from the standard input but then you will not be able to also use the standard input as a source of data.) @@ -3744,9 +3740,9 @@ sets the variable @code{ARGIND} to the index in @code{ARGV} of the current element. @cindex input files, variable assignments and -The distinction between @value{FN} arguments and variable-assignment +The distinction between file name arguments and variable-assignment arguments is made when @command{awk} is about to open the next input file. -At that point in execution, it checks the @value{FN} to see whether +At that point in execution, it checks the file name to see whether it is really a variable assignment; if so, @command{awk} sets the variable instead of reading a file. @@ -3763,7 +3759,7 @@ sequences (@pxref{Escape Sequences}). @value{DARKCORNER} In some earlier implementations of @command{awk}, when a variable assignment -occurred before any @value{FN}s, the assignment would happen @emph{before} +occurred before any file names, the assignment would happen @emph{before} the @code{BEGIN} rule was executed. @command{awk}'s behavior was thus inconsistent; some command-line assignments were available inside the @code{BEGIN} rule, while others were not. Unfortunately, @@ -3774,8 +3770,8 @@ upon the old behavior. The variable assignment feature is most useful for assigning to variables such as @code{RS}, @code{OFS}, and @code{ORS}, which control input and -output formats before scanning the @value{DF}s. It is also useful for -controlling state if multiple passes are needed over a @value{DF}. For +output formats before scanning the data files. It is also useful for +controlling state if multiple passes are needed over a data file. For example: @cindex files, multiple passes over @@ -3811,13 +3807,13 @@ You may also use @code{"-"} to name standard input when reading files with @code{getline} (@pxref{Getline/File}). In addition, @command{gawk} allows you to specify the special -@value{FN} @file{/dev/stdin}, both on the command line and +file name @file{/dev/stdin}, both on the command line and with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file in the file system, however, @command{gawk} always processes -this @value{FN} itself.) +this file name itself.) @node Environment Variables @section The Environment Variables @command{gawk} Uses @@ -3847,7 +3843,7 @@ on the command-line with the @option{-f} option. In most @command{awk} implementations, you must supply a precise path name for each program file, unless the file is in the current directory. -But in @command{gawk}, if the @value{FN} supplied to the @option{-f} +But in @command{gawk}, if the file name supplied to the @option{-f} or @option{-i} options does not contain a @samp{/}, then @command{gawk} searches a list of directories (called the @dfn{search path}), one by one, looking for a @@ -3867,7 +3863,7 @@ though.} The search path feature is particularly useful for building libraries of useful @command{awk} functions. The library files can be placed in a standard directory in the default path and then specified on -the command line with a short @value{FN}. Otherwise, the full @value{FN} +the command line with a short file name. Otherwise, the full file name would have to be typed for each file. By using the @option{-i} option, or the @option{--source} and @option{-f} options, your command-line @@ -3961,10 +3957,6 @@ for use by the @command{gawk} developers for testing and tuning. They are subject to change. The variables are: @table @env -@item AVG_CHAIN_MAX -The average number of items @command{gawk} will maintain on a -hash chain for managing arrays. - @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} will switch to using the hash function from GNU Smalltalk for @@ -3977,6 +3969,13 @@ files one line at a time, instead of reading in blocks. This exists for debugging problems on filesystems on non-POSIX operating systems where I/O is performed in records, not in blocks. +@item GAWK_MSG_SRC +If this variable exists, @command{gawk} includes the source file +name and line number from which warning and/or fatal messages +are generated. Its purpose is to help isolate the source of a +message, since there can be multiple places which produce the +same warning or error message. + @item GAWK_NO_DFA If this variable exists, @command{gawk} does not use the DFA regexp matcher for ``does it match'' kinds of tests. This can cause @command{gawk} @@ -3989,6 +3988,14 @@ coordinate with each other.) This specifies the amount by which @command{gawk} should grow its internal evaluation stack, when needed. +@item INT_CHAIN_MAX +The average number of items @command{gawk} will maintain on a +hash chain for managing arrays indexed by integers. + +@item STR_CHAIN_MAX +The average number of items @command{gawk} will maintain on a +hash chain for managing arrays indexed by strings. + @item TIDYMEM If this variable exists, @command{gawk} uses the @code{mtrace()} library calls from GNU LIBC to help track down possible memory leaks. @@ -4067,7 +4074,7 @@ use @samp{@@include} followed by the name of the file to be included, enclosed in double quotes. @quotation NOTE -Keep in mind that this is a language construct and the @value{FN} cannot +Keep in mind that this is a language construct and the file name cannot be a string variable, but rather just a literal string in double quotes. @end quotation @@ -4092,7 +4099,7 @@ $ @kbd{gawk -f test3} @print{} This is file test3. @end example -The @value{FN} can, of course, be a pathname. For example: +The file name can, of course, be a pathname. For example: @example @@include "../io_funcs" @@ -4190,7 +4197,7 @@ they will @emph{not} be in the next release). @cindex @code{PROCINFO} array The process-related special files @file{/dev/pid}, @file{/dev/ppid}, @file{/dev/pgrpid}, and @file{/dev/user} were deprecated in @command{gawk} -3.1, but still worked. As of @value{PVERSION} 4.0, they are no longer +3.1, but still worked. As of version 4.0, they are no longer interpreted specially by @command{gawk}. (Use @code{PROCINFO} instead; see @ref{Auto-set}.) @@ -4209,8 +4216,8 @@ in case some option becomes obsolete in a future version of @command{gawk}. @cindex Jedi knights @cindex Knights, jedi @quotation -@i{Use the Source, Luke!}@* -Obi-Wan +@i{Use the Source, Luke!} +@author Obi-Wan @end quotation This @value{SECTION} intentionally left @@ -4446,39 +4453,39 @@ A literal backslash, @samp{\}. @cindex @code{\} (backslash), @code{\a} escape sequence @cindex backslash (@code{\}), @code{\a} escape sequence @item \a -The ``alert'' character, @kbd{@value{CTL}-g}, ASCII code 7 (BEL). +The ``alert'' character, @kbd{Ctrl-g}, ASCII code 7 (BEL). (This usually makes some sort of audible noise.) @cindex @code{\} (backslash), @code{\b} escape sequence @cindex backslash (@code{\}), @code{\b} escape sequence @item \b -Backspace, @kbd{@value{CTL}-h}, ASCII code 8 (BS). +Backspace, @kbd{Ctrl-h}, ASCII code 8 (BS). @cindex @code{\} (backslash), @code{\f} escape sequence @cindex backslash (@code{\}), @code{\f} escape sequence @item \f -Formfeed, @kbd{@value{CTL}-l}, ASCII code 12 (FF). +Formfeed, @kbd{Ctrl-l}, ASCII code 12 (FF). @cindex @code{\} (backslash), @code{\n} escape sequence @cindex backslash (@code{\}), @code{\n} escape sequence @item \n -Newline, @kbd{@value{CTL}-j}, ASCII code 10 (LF). +Newline, @kbd{Ctrl-j}, ASCII code 10 (LF). @cindex @code{\} (backslash), @code{\r} escape sequence @cindex backslash (@code{\}), @code{\r} escape sequence @item \r -Carriage return, @kbd{@value{CTL}-m}, ASCII code 13 (CR). +Carriage return, @kbd{Ctrl-m}, ASCII code 13 (CR). @cindex @code{\} (backslash), @code{\t} escape sequence @cindex backslash (@code{\}), @code{\t} escape sequence @item \t -Horizontal TAB, @kbd{@value{CTL}-i}, ASCII code 9 (HT). +Horizontal TAB, @kbd{Ctrl-i}, ASCII code 9 (HT). @c @cindex @command{awk} language, V.4 version @cindex @code{\} (backslash), @code{\v} escape sequence @cindex backslash (@code{\}), @code{\v} escape sequence @item \v -Vertical tab, @kbd{@value{CTL}-k}, ASCII code 11 (VT). +Vertical tab, @kbd{Ctrl-k}, ASCII code 11 (VT). @cindex @code{\} (backslash), @code{\}@var{nnn} escape sequence @cindex backslash (@code{\}), @code{\}@var{nnn} escape sequence @@ -4891,7 +4898,7 @@ constants, @command{gawk} did @emph{not} match interval expressions in regexps. -However, beginning with @value{PVERSION} 4.0, +However, beginning with version 4.0, @command{gawk} does match interval expressions by default. This is because compatibility with POSIX has become more important to most @command{gawk} users than compatibility with @@ -5487,7 +5494,7 @@ But a newline in a regexp constant works with no problem: $ @kbd{awk '$0 ~ /[ \t\n]/'} @kbd{here is a sample line} @print{} here is a sample line -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @command{gawk} does not have this problem, and it isn't likely to @@ -5525,7 +5532,7 @@ But a newline in a regexp constant works with no problem: $ @kbd{awk '$0 ~ /[ \t\n]/'} @kbd{here is a sample line} @print{} here is a sample line -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @command{gawk} does not have this problem, and it isn't likely to @@ -5576,7 +5583,7 @@ used with it do not have to be named on the @command{awk} command line * Field Separators:: The field separator and how to change it. * Constant Size:: Reading constant width data. * Splitting By Content:: Defining Fields By Content -* Multiple Line:: Reading multi-line records. +* Multiple Line:: Reading multiline records. * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. @@ -5601,7 +5608,7 @@ so far from the current input file. This value is stored in a built-in variable called @code{FNR}. It is reset to zero when a new file is started. Another built-in variable, @code{NR}, records the total -number of input records read so far from all @value{DF}s. It starts at zero, +number of input records read so far from all data files. It starts at zero, but is never automatically reset to zero. @cindex separators, for records @@ -5675,7 +5682,7 @@ $ @kbd{awk 'BEGIN @{ RS = "/" @}} @noindent Note that the entry for the @samp{camelot} BBS is not split. -In the original @value{DF} +In the original data file (@pxref{Sample Data Files}), the line looks like this: @@ -5688,7 +5695,7 @@ It has one baud rate only, so there are no slashes in the record, unlike the others which have two or more baud rates. In fact, this record is treated as part of the record for the @samp{core} BBS; the newline separating them in the output -is the original newline in the @value{DF}, not the one added by +is the original newline in the data file, not the one added by @command{awk} when it printed the record! @cindex record separators, changing @@ -5829,8 +5836,8 @@ In compatibility mode, only the first character of the value of <sidebar><title>@code{RS = "\0"} Is Not Portable</title> @end docbook -@cindex portability, @value{DF}s as single record -There are times when you might want to treat an entire @value{DF} as a +@cindex portability, data files as single record +There are times when you might want to treat an entire data file as a single record. The only way to make this happen is to give @code{RS} a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary @@ -5874,8 +5881,8 @@ record onto the end of the previous ones. @center @b{@code{RS = "\0"} Is Not Portable} -@cindex portability, @value{DF}s as single record -There are times when you might want to treat an entire @value{DF} as a +@cindex portability, data files as single record +There are times when you might want to treat an entire data file as a single record. The only way to make this happen is to give @code{RS} a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary @@ -7184,7 +7191,7 @@ appear in a row, they are considered one record separator. @cindex dark corner, multiline records There is an important difference between @samp{RS = ""} and @samp{RS = "\n\n+"}. In the first case, leading newlines in the input -@value{DF} are ignored, and if a file ends without extra blank lines +data file are ignored, and if a file ends without extra blank lines after the last record, the final newline is removed from the record. In the second case, this special processing is not done. @value{DARKCORNER} @@ -7219,7 +7226,7 @@ Another way to separate fields is to put each field on a separate line: to do this, just set the variable @code{FS} to the string @code{"\n"}. (This single character separator matches a single newline.) -A practical example of a @value{DF} organized this way might be a mailing +A practical example of a data file organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named @file{addresses}, which looks like this: @@ -7284,7 +7291,7 @@ value of @table @code @item RS == "\n" Records are separated by the newline character (@samp{\n}). In effect, -every line in the @value{DF} is a separate record, including blank lines. +every line in the data file is a separate record, including blank lines. This is the default. @item RS == @var{any single character} @@ -7490,7 +7497,7 @@ the value of @code{NF} do not change. @cindex operators, input/output Use @samp{getline < @var{file}} to read the next record from @var{file}. Here @var{file} is a string-valued expression that -specifies the @value{FN}. @samp{< @var{file}} is called a @dfn{redirection} +specifies the file name. @samp{< @var{file}} is called a @dfn{redirection} because it directs input to come from a different place. For example, the following program reads its input record from the file @file{secondary.input} when it @@ -7576,8 +7583,8 @@ that does handle nested @samp{@@include} statements. @c From private email, dated October 2, 1988. Used by permission, March 2013. @quotation @i{Omniscience has much to recommend it. -Failing that, attention to details would be useful.}@* -Brian Kernighan +Failing that, attention to details would be useful.} +@author Brian Kernighan @end quotation @cindex @code{|} (vertical bar), @code{|} operator (I/O) @@ -7797,10 +7804,10 @@ system permits. @item An interesting side effect occurs if you use @code{getline} without a redirection inside a @code{BEGIN} rule. Because an unredirected @code{getline} -reads from the command-line @value{DF}s, the first @code{getline} command +reads from the command-line data files, the first @code{getline} command causes @command{awk} to set the value of @code{FILENAME}. Normally, @code{FILENAME} does not have a value inside @code{BEGIN} rules, because you -have not yet started to process the command-line @value{DF}s. +have not yet started to process the command-line data files. @value{DARKCORNER} (@xref{BEGIN/END}, also @pxref{Auto-set}.) @@ -8022,7 +8029,7 @@ For printing with specifications, you need the @code{printf} statement @cindex @code{printf} statement Besides basic and formatted printing, this @value{CHAPTER} also covers I/O redirections to files and pipes, introduces -the special @value{FN}s that @command{gawk} processes internally, +the special file names that @command{gawk} processes internally, and discusses the @code{close()} built-in function. @menu @@ -8823,9 +8830,9 @@ but they work identically for @code{printf}: @cindex operators, input/output @item print @var{items} > @var{output-file} This redirection prints the items into the output file named -@var{output-file}. The @value{FN} @var{output-file} can be any +@var{output-file}. The file name @var{output-file} can be any expression. Its value is changed to a string and then used as a -@value{FN} (@pxref{Expressions}). +file name (@pxref{Expressions}). When this type of redirection is used, the @var{output-file} is erased before the first output is written to it. Subsequent writes to the same @@ -8996,7 +9003,7 @@ open as many pipelines as the underlying operating system permits. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, @command{sh}. For example, suppose you -have a list of files brought over from a system where all the @value{FN}s +have a list of files brought over from a system where all the file names are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient: @@ -9028,7 +9035,7 @@ It then sends the list to the shell for execution. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, @command{sh}. For example, suppose you -have a list of files brought over from a system where all the @value{FN}s +have a list of files brought over from a system where all the file names are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient: @@ -9051,12 +9058,12 @@ It then sends the list to the shell for execution. @c ENDOFRANGE reout @node Special Files -@section Special @value{FFN}s in @command{gawk} +@section Special File Names in @command{gawk} @c STARTOFRANGE gfn -@cindex @command{gawk}, @value{FN}s in +@cindex @command{gawk}, file names in -@command{gawk} provides a number of special @value{FN}s that it interprets -internally. These @value{FN}s provide access to standard file descriptors +@command{gawk} provides a number of special file names that it interprets +internally. These file names provide access to standard file descriptors and TCP/IP networking. @menu @@ -9120,12 +9127,12 @@ that happens, writing to the screen is not correct. In fact, if terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk} provides special @value{FN}s for accessing the three standard +@command{gawk} provides special file names for accessing the three standard streams. @value{COMMONEXT}. It also provides syntax for accessing -any other inherited open files. If the @value{FN} matches +any other inherited open files. If the file name matches one of these special names when @command{gawk} redirects input or output, -then it directly uses the stream that the @value{FN} stands for. -These special @value{FN}s work for all operating systems that @command{gawk} +then it directly uses the stream that the file name stands for. +These special file names work for all operating systems that @command{gawk} has been ported to, not just those that are POSIX-compliant: @cindex common extensions, @code{/dev/stdin} special file @@ -9134,7 +9141,7 @@ has been ported to, not just those that are POSIX-compliant: @cindex extensions, common@comma{} @code{/dev/stdin} special file @cindex extensions, common@comma{} @code{/dev/stdout} special file @cindex extensions, common@comma{} @code{/dev/stderr} special file -@cindex @value{FN}s, standard streams in @command{gawk} +@cindex file names, standard streams in @command{gawk} @cindex @code{/dev/@dots{}} special files (@command{gawk}) @cindex files, @code{/dev/@dots{}} special files @cindex @code{/dev/fd/@var{N}} special files @@ -9155,7 +9162,7 @@ the shell). Unless special pains are taken in the shell from which @command{gawk} is invoked, only descriptors 0, 1, and 2 are available. @end table -The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} +The file names @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2}, respectively. However, they are more self-explanatory. The proper way to write an error message in a @command{gawk} program @@ -9165,14 +9172,14 @@ is to use @file{/dev/stderr}, like this: print "Serious error detected!" > "/dev/stderr" @end example -@cindex troubleshooting, quotes with @value{FN}s -Note the use of quotes around the @value{FN}. +@cindex troubleshooting, quotes with file names +Note the use of quotes around the file name. Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. @c Exercise: What does it do? :-) -Finally, using the @code{close()} function on a @value{FN} of the +Finally, using the @code{close()} function on a file name of the form @code{"/dev/fd/@var{N}"}, for file descriptor numbers above two, does actually close the given file descriptor. @@ -9188,7 +9195,7 @@ versions of @command{awk}. @command{gawk} programs can open a two-way TCP/IP connection, acting as either a client or a server. -This is done using a special @value{FN} of the form: +This is done using a special file name of the form: @example @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}} @@ -9198,7 +9205,7 @@ The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}. The @var{protocol} is one of @samp{tcp} or @samp{udp}, and the other fields represent the other essential pieces of information for making a networking connection. -These @value{FN}s are used with the @samp{|&} operator for communicating +These file names are used with the @samp{|&} operator for communicating with a coprocess (@pxref{Two-way I/O}). This is an advanced feature, mentioned here only for completeness. @@ -9206,21 +9213,21 @@ Full discussion is delayed until @ref{TCP/IP Networking}. @node Special Caveats -@subsection Special @value{FFN} Caveats +@subsection Special File Name Caveats Here is a list of things to bear in mind when using the -special @value{FN}s that @command{gawk} provides: +special file names that @command{gawk} provides: @itemize @bullet -@cindex compatibility mode (@command{gawk}), @value{FN}s -@cindex @value{FN}s, in compatibility mode +@cindex compatibility mode (@command{gawk}), file names +@cindex file names, in compatibility mode @item -Recognition of these special @value{FN}s is disabled if @command{gawk} is in +Recognition of these special file names is disabled if @command{gawk} is in compatibility mode (@pxref{Options}). @item @command{gawk} @emph{always} -interprets these special @value{FN}s. +interprets these special file names. For example, using @samp{/dev/fd/4} for output actually writes on file descriptor 4, and not on a new file descriptor that is @code{dup()}'ed from file descriptor 4. Most of @@ -9243,7 +9250,7 @@ Doing so results in unpredictable behavior. @cindex coprocesses, closing @cindex @code{getline} command, coprocesses@comma{} using from -If the same @value{FN} or the same shell command is used with @code{getline} +If the same file name or the same shell command is used with @code{getline} more than once during the execution of an @command{awk} program (@pxref{Getline}), the file is opened (or the command is executed) the first time only. @@ -9252,7 +9259,7 @@ The next time the same file or command is used with @code{getline}, another record is read from it, and so on. Similarly, when a file or pipe is opened for output, @command{awk} remembers -the @value{FN} or command associated with it, and subsequent +the file name or command associated with it, and subsequent writes to the same file or command are appended to the previous writes. The file or pipe stays open until @command{awk} exits. @@ -9294,7 +9301,7 @@ file or command, or the next @code{print} or @code{printf} to that file or command, reopens the file or reruns the command. Because the expression that you use to close a file or pipeline must exactly match the expression used to open the file or run the command, -it is good practice to use a variable to store the @value{FN} or command. +it is good practice to use a variable to store the file name or command. The previous example becomes the following: @example @@ -9343,7 +9350,7 @@ a separate message. @cindex portability, @code{close()} function and If you use more files than the system allows you to have open, @command{gawk} attempts to multiplex the available open files among -your @value{DF}s. @command{gawk}'s ability to do this depends upon the +your data files. @command{gawk}'s ability to do this depends upon the facilities of your operating system, so it may not always work. It is therefore both good practice and good portability advice to always use @code{close()} on your files when you are done with them. @@ -9948,7 +9955,7 @@ as in the following: @noindent the variable is set at the very beginning, even before the @code{BEGIN} rules execute. The @option{-v} option and its assignment -must precede all the @value{FN} arguments, as well as the program text. +must precede all the file name arguments, as well as the program text. (@xref{Options}, for more information about the @option{-v} option.) Otherwise, the variable assignment is performed at a time determined by @@ -10030,7 +10037,7 @@ with @code{CONVFMT} as the format specifier (@pxref{String Functions}). -@code{CONVFMT}'s default value is @code{"%.6g"}, which prints a value with +@code{CONVFMT}'s default value is @code{"%.6g"}, which creates a value with at most six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, @@ -10121,7 +10128,7 @@ point, so the default behavior was restored to use a period as the decimal point character. You can use the @option{--use-lc-numeric} option (@pxref{Options}) to force @command{gawk} to use the locale's decimal point character. (@command{gawk} also uses the locale's decimal -point character when in POSIX mode, either via @w{@option{--posix}}, or the +point character when in POSIX mode, either via @option{--posix}, or the @env{POSIXLY_CORRECT} environment variable, as shown previously.) @ref{table-locale-affects} describes the cases in which the locale's decimal @@ -10279,8 +10286,8 @@ For maximum portability, do not use the @samp{**} operator. @subsection String Concatenation @cindex Kernighan, Brian @quotation -@i{It seemed like a good idea at the time.}@* -Brian Kernighan +@i{It seemed like a good idea at the time.} +@author Brian Kernighan @end quotation @cindex string operators @@ -10810,8 +10817,8 @@ like @samp{@var{lvalue}++}, but instead of adding, it subtracts.) @cindex Marx, Groucho @quotation @i{Doctor, doctor! It hurts when I do this!@* -So don't do that!}@* -Groucho Marx +So don't do that!} +@author Groucho Marx @end quotation @noindent @@ -10862,8 +10869,8 @@ You should avoid such things in your own programs. @cindex Marx, Groucho @quotation @i{Doctor, doctor! It hurts when I do this!@* -So don't do that!}@* -Groucho Marx +So don't do that!} +@author Groucho Marx @end quotation @noindent @@ -10961,8 +10968,8 @@ the string constant @code{"0"} is actually true, because it is non-null. @node Typing and Comparison @subsection Variable Typing and Comparison Expressions @quotation -@i{The Guide is definitive. Reality is frequently inaccurate.}@* -The Hitchhiker's Guide to the Galaxy +@i{The Guide is definitive. Reality is frequently inaccurate.} +@author The Hitchhiker's Guide to the Galaxy @end quotation @c STARTOFRANGE comex @@ -11620,7 +11627,7 @@ $ @kbd{awk '@{ print "The square root of", $1, "is", sqrt($1) @}'} @print{} The square root of 3 is 1.73205 @kbd{5} @print{} The square root of 5 is 2.23607 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example A function can also have side effects, such as assigning @@ -13142,11 +13149,11 @@ The @code{nextfile} statement is similar to the @code{next} statement. However, instead of abandoning processing of the current record, the @code{nextfile} statement instructs @command{awk} to stop processing the -current @value{DF}. +current data file. Upon execution of the @code{nextfile} statement, @code{FILENAME} is -updated to the name of the next @value{DF} listed on the command line, +updated to the name of the next data file listed on the command line, @code{FNR} is reset to one, and processing starts over with the first rule in the program. @@ -13155,10 +13162,10 @@ then the code in any @code{END} rules is executed. An exception to this is when @code{nextfile} is invoked during execution of any statement in an @code{END} rule; In this case, it causes the program to stop immediately. @xref{BEGIN/END}. -The @code{nextfile} statement is useful when there are many @value{DF}s +The @code{nextfile} statement is useful when there are many data files to process but it isn't necessary to process every record in every file. Without @code{nextfile}, -in order to move on to the next @value{DF}, a program +in order to move on to the next data file, a program would have to continue scanning the unwanted records. The @code{nextfile} statement accomplishes this much more efficiently. @@ -13396,7 +13403,7 @@ exclusively on the value of @code{FS}. @item FS This is the input field separator (@pxref{Field Separators}). -The value is a single-character string or a multi-character regular +The value is a single-character string or a multicharacter regular expression that matches the separations between fields in an input record. If the value is the null string (@code{""}), then each character in the record becomes a separate field. @@ -13542,7 +13549,7 @@ This is the subscript separator. It has the default value of @code{"\034"} and is used to separate the parts of the indices of a multidimensional array. Thus, the expression @code{@w{foo["A", "B"]}} really accesses @code{foo["A\034B"]} -(@pxref{Multi-dimensional}). +(@pxref{Multidimensional}). @cindex @command{gawk}, @code{TEXTDOMAIN} variable in @cindex @code{TEXTDOMAIN} variable @@ -13625,17 +13632,17 @@ about how @command{awk} uses these variables. @cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable @item ARGIND # The index in @code{ARGV} of the current file being processed. -Every time @command{gawk} opens a new @value{DF} for processing, it sets -@code{ARGIND} to the index in @code{ARGV} of the @value{FN}. +Every time @command{gawk} opens a new data file for processing, it sets +@code{ARGIND} to the index in @code{ARGV} of the file name. When @command{gawk} is processing the input files, @samp{FILENAME == ARGV[ARGIND]} is always true. @cindex files, processing@comma{} @code{ARGIND} variable and This variable is useful in file processing; it allows you to tell how far -along you are in the list of @value{DF}s as well as to distinguish between -successive instances of the same @value{FN} on the command line. +along you are in the list of data files as well as to distinguish between +successive instances of the same file name on the command line. -@cindex @value{FN}s, distinguishing +@cindex file names, distinguishing While you can change the value of @code{ARGIND} within your @command{awk} program, @command{gawk} automatically sets it to a new value when the next file is opened. @@ -13652,10 +13659,18 @@ it is not special. An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of the particular environment variables. For example, -@code{ENVIRON["HOME"]} might be @file{/home/arnold}. Changing this array -does not affect the environment passed on to any programs that -@command{awk} may spawn via redirection or the @code{system()} function. -@c (In a future version of @command{gawk}, it may do so.) +@code{ENVIRON["HOME"]} might be @file{/home/arnold}. + +For POSIX @command{awk}, changing this array does not affect the +environment passed on to any programs that @command{awk} may spawn via +redirection or the @code{system()} function. + +However, beginning with version 4.2, if not in POSIX +compatibility mode, @command{gawk} does update its own environment when +@code{ENVIRON} is changed, thus changing the environment seen by programs +that it creates. You should therefore be especially careful if you +modify @code{ENVIRON["PATH"]"}, which is the search path for finding +executable programs. Some operating systems may not have environment variables. On such systems, the @code{ENVIRON} array is empty (except for @@ -13697,14 +13712,14 @@ it is not special. @cindex dark corner, @code{FILENAME} variable @item FILENAME The name of the file that @command{awk} is currently reading. -When no @value{DF}s are listed on the command line, @command{awk} reads +When no data files are listed on the command line, @command{awk} reads from the standard input and @code{FILENAME} is set to @code{"-"}. @code{FILENAME} is changed each time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} rule, the value of @code{FILENAME} is @code{""}, since there are no input files being processed yet.@footnote{Some early implementations of Unix @command{awk} initialized -@code{FILENAME} to @code{"-"}, even if there were @value{DF}s to be +@code{FILENAME} to @code{"-"}, even if there were data files to be processed. This behavior was incorrect and should not be relied upon in your programs.} @value{DARKCORNER} @@ -13744,8 +13759,12 @@ current record. @xref{Changing Fields}. @item FUNCTAB # An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. -@strong{NOTE}: You may not use the @code{delete} statement with the -@code{FUNCTAB} array. + +@quotation NOTE +Attempting to use the @code{delete} statement with the @code{FUNCTAB} +array will cause a fatal error. Any attempt to assign to an element of +the @code{FUNCTAB} array will also cause a fatal error. +@end quotation @cindex @code{NR} variable @item NR @@ -14123,11 +14142,11 @@ additional files to be read. If the value of @code{ARGC} is decreased, that eliminates input files from the end of the list. By recording the old value of @code{ARGC} elsewhere, a program can treat the eliminated arguments as -something other than @value{FN}s. +something other than file names. To eliminate a file from the middle of the list, store the null string (@code{""}) into @code{ARGV} in place of the file's name. As a -special feature, @command{awk} ignores @value{FN}s that have been +special feature, @command{awk} ignores file names that have been replaced with the null string. Another option is to use the @code{delete} statement to remove elements from @@ -14222,7 +14241,7 @@ same @command{awk} program. * Numeric Array Subscripts:: How to use numbers as subscripts in @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. -* Multi-dimensional:: Emulating multidimensional arrays in +* Multidimensional:: Emulating multidimensional arrays in @command{awk}. * Arrays of Arrays:: True multidimensional arrays. @end menu @@ -14252,8 +14271,8 @@ an array. @cindex Wall, Larry @quotation @i{Doing linear scans over an associative array is like trying to club someone -to death with a loaded Uzi.}@* -Larry Wall +to death with a loaded Uzi.} +@author Larry Wall @end quotation The @command{awk} language provides one-dimensional arrays @@ -14664,29 +14683,29 @@ Array elements are processed in arbitrary order, which is the default @command{awk} behavior. @item "@@ind_str_asc" -Order by indices compared as strings; this is the most basic sort. +Order by indices in ascending order compared as strings; this is the most basic sort. (Internally, array indices are always strings, so with @samp{a[2*5] = 1} the index is @code{"10"} rather than numeric 10.) @item "@@ind_num_asc" -Order by indices but force them to be treated as numbers in the process. +Order by indices in ascending order but force them to be treated as numbers in the process. Any index with a non-numeric value will end up positioned as if it were zero. @item "@@val_type_asc" -Order by element values rather than indices. +Order by element values in ascending order (rather than by indices). Ordering is by the type assigned to the element (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. (Subarrays have not been described yet; -@pxref{Arrays of Arrays}). +@pxref{Arrays of Arrays}.) @item "@@val_str_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as strings. Subarrays, if present, come out last. @item "@@val_num_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as numbers. Subarrays, if present, come out last. When numeric values are equal, the string values are used to provide an ordering: this guarantees consistent results across different @@ -14699,13 +14718,14 @@ across different environments.} which @command{gawk} uses internally to perform the sorting. @item "@@ind_str_desc" -Reverse order from the most basic sort. +String indices ordered from high to low. @item "@@ind_num_desc" Numeric indices ordered from high to low. @item "@@val_type_desc" -Element values, based on type, in descending order. +Element values, based on type, ordered from high to low. +Subarrays, if present, come out first. @item "@@val_str_desc" Element values, treated as strings, ordered from high to low. @@ -15015,11 +15035,11 @@ Even though it is somewhat unusual, the null string if @option{--lint} is provided on the command line (@pxref{Options}). -@node Multi-dimensional +@node Multidimensional @section Multidimensional Arrays @menu -* Multi-scanning:: Scanning multidimensional arrays. +* Multiscanning:: Scanning multidimensional arrays. @end menu @cindex subscripts in arrays, multidimensional @@ -15117,7 +15137,7 @@ the program produces the following output: 3 2 1 6 @end example -@node Multi-scanning +@node Multiscanning @subsection Scanning Multidimensional Arrays There is no special @code{for} statement for scanning a @@ -15562,15 +15582,16 @@ sequences of random numbers. @node String Functions @subsection String-Manipulation Functions -The functions in this @value{SECTION} look at or change the text of one or more -strings. -@code{gawk} understands locales (@pxref{Locales}), and does all string processing in terms of -@emph{characters}, not @emph{bytes}. This distinction is particularly important -to understand for locales where one character -may be represented by multiple bytes. Thus, for example, @code{length()} -returns the number of characters in a string, and not the number of bytes -used to represent those characters, Similarly, @code{index()} works with -character indices, and not byte indices. +The functions in this @value{SECTION} look at or change the text of one +or more strings. + +@code{gawk} understands locales (@pxref{Locales}), and does all +string processing in terms of @emph{characters}, not @emph{bytes}. +This distinction is particularly important to understand for locales +where one character may be represented by multiple bytes. Thus, for +example, @code{length()} returns the number of characters in a string, +and not the number of bytes used to represent those characters. Similarly, +@code{index()} works with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).} Several functions perform string substitution; the full discussion is @@ -15587,30 +15608,32 @@ pound sign@w{ (@samp{#}):} @table @code @item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@itemx asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@cindex @code{asorti()} function (@command{gawk}) @cindex arrays, elements, retrieving number of @cindex @code{asort()} function (@command{gawk}) @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable -Return the number of elements in the array @var{source}. -@command{gawk} sorts the contents of @var{source} -and replaces the indices -of the sorted values of @var{source} with sequential -integers starting with one. If the optional array @var{dest} is specified, -then @var{source} is duplicated into @var{dest}. @var{dest} is then -sorted, leaving the indices of @var{source} unchanged. The optional third -argument @var{how} is a string which controls the rule for comparing values, -and the sort direction. A single space is required between the -comparison mode, @samp{string} or @samp{number}, and the direction specification, -@samp{ascending} or @samp{descending}. You can omit direction and/or mode -in which case it will default to @samp{ascending} and @samp{string}, respectively. -An empty string "" is the same as the default @code{"ascending string"} -for the value of @var{how}. If the @samp{source} array contains subarrays as values, -they will come out last(first) in the @samp{dest} array for @samp{ascending}(@samp{descending}) -order specification. The value of @code{IGNORECASE} affects the sorting. -The third argument can also be a user-defined function name in which case -the value returned by the function is used to order the array elements -before constructing the result array. -@xref{Array Sorting Functions}, for more information. +These two functions are similar in behavior, so they are described +together. + +@quotation NOTE +The following description ignores the third argument, @var{how}, since it +requires understanding features that we have not discussed yet. Thus, +the discussion here is a deliberate simplification. (We do provide all +the details later on: @xref{Array Sorting Functions}, for the full story.) +@end quotation + +Both functions return the number of elements in the array @var{source}. +For @command{asort()}, @command{gawk} sorts the values of @var{source} +and replaces the indices of the sorted values of @var{source} with +sequential integers starting with one. If the optional array @var{dest} +is specified, then @var{source} is duplicated into @var{dest}. @var{dest} +is then sorted, leaving the indices of @var{source} unchanged. + +When comparing strings, @code{IGNORECASE} affects the sorting. If the +@var{source} array contains subarrays as values (@pxref{Arrays of +Arrays}), they will come last, after all scalar values. For example, if the contents of @code{a} are as follows: @@ -15636,29 +15659,19 @@ a[2] = "de" a[3] = "sac" @end example -In order to reverse the direction of the sorted results in the above example, -@code{asort()} can be called with three arguments as follows: +The @code{asorti()} function works similarly to @code{asort()}, however, +the @emph{indices} are sorted, instead of the values. Thus, in the +previous example, starting with the same initial set of indices and +values in @code{a}, calling @samp{asorti(a)} would yield: @example -asort(a, a, "descending") +a[1] = "first" +a[2] = "last" +a[3] = "middle" @end example -The @code{asort()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asort()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). - -@item asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # -@cindex @code{asorti()} function (@command{gawk}) -Return the number of elements in the array @var{source}. -It works similarly to @code{asort()}, however, the @emph{indices} -are sorted, instead of the values. (Here too, -@code{IGNORECASE} affects the sorting.) - -The @code{asorti()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asorti()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). +@code{asort()} and @code{asorti()} are @command{gawk} extensions; they +are not available in compatibility mode (@pxref{Options}). @item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) # @cindex @code{gensub()} function (@command{gawk}) @@ -16557,17 +16570,17 @@ _bigskip} The only case where the difference is noticeable is the last one: @samp{\\\\} is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. -Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules +Starting with version 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, it continued to follow the 1996 proposed rules, since that had been its behavior for many years. -When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer +When version 4.0.0 was released, the @command{gawk} maintainer made the POSIX rules the default, breaking well over a decade's worth of backwards compatibility.@footnote{This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules.} Needless to say, this was a bad idea, -and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical +and as of version 4.0.1, @command{gawk} resumed its historical behavior, and only follows the POSIX rules when @option{--posix} is given. The rules for @code{gensub()} are considerably simpler. At the runtime @@ -16839,7 +16852,7 @@ $ @kbd{awk '@{ print $1 + $2 @}'} @print{} 2 @kbd{2 3} @print{} 5 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @noindent @@ -16850,13 +16863,13 @@ with this example: $ @kbd{awk '@{ print $1 + $2 @}' | cat} @kbd{1 1} @kbd{2 3} -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @print{} 2 @print{} 5 @end example @noindent -Here, no output is printed until after the @kbd{@value{CTL}-d} is typed, because +Here, no output is printed until after the @kbd{Ctrl-d} is typed, because it is all buffered and sent down the pipe to @command{cat} in one shot. @docbook @@ -16890,7 +16903,7 @@ $ @kbd{awk '@{ print $1 + $2 @}'} @print{} 2 @kbd{2 3} @print{} 5 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @noindent @@ -16901,13 +16914,13 @@ with this example: $ @kbd{awk '@{ print $1 + $2 @}' | cat} @kbd{1 1} @kbd{2 3} -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @print{} 2 @print{} 5 @end example @noindent -Here, no output is printed until after the @kbd{@value{CTL}-d} is typed, because +Here, no output is printed until after the @kbd{Ctrl-d} is typed, because it is all buffered and sent down the pipe to @command{cat} in one shot. @end cartouche @end ifnotdocbook @@ -17436,8 +17449,8 @@ gawk 'BEGIN @{ @c STARTOFRANGE opbit @cindex operations, bitwise @quotation -@i{I can explain it for you, but I can't understand it for you.}@* -Anonymous +@i{I can explain it for you, but I can't understand it for you.} +@author Anonymous @end quotation Many languages provide the ability to perform @dfn{bitwise} operations @@ -17739,6 +17752,19 @@ that traverses every element of a true multidimensional array Return a true value if @var{x} is an array. Otherwise return false. @end table +@code{isarray()} is meant for use in two circumstances. The first is when +traversing a multidimensional array: you can test if an element is itself +an array or not. The second is inside the body of a user-defined function +(not discussed yet; @pxref{User-defined}), to test if a paramater is an +array or not. + +Note, however, that using @code{isarray()} at the global level to test +variables makes no sense. Since you are the one writing the program, you +are supposed to know if your variables are arrays or not. And in fact, +due to the way @command{gawk} works, if you pass the name of a variable +that has not been previously used to @code{isarray()}, @command{gawk} +will end up turning it into a scalar. + @node I18N Functions @subsection String-Translation Functions @cindex @command{gawk}, string-translation functions @@ -18863,9 +18889,9 @@ it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more manageable, and making programs more readable. -In their seminal 1976 book, @cite{Software Tools}@footnote{Sadly, over 35 +In their seminal 1976 book, @cite{Software Tools},@footnote{Sadly, over 35 years later, many of the lessons taught by this book have yet to be -learned by a vast number of practicing programmers.}, Brian Kernighan +learned by a vast number of practicing programmers.} Brian Kernighan and P.J.@: Plauger wrote: @quotation @@ -19064,6 +19090,7 @@ programming use. vice versa. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. +* Readfile Function:: A function to read an entire file at once. @end menu @node Strtonum Function @@ -19279,7 +19306,7 @@ An @code{END} rule is automatically added to the program calling @code{assert()}. Normally, if a program consists of just a @code{BEGIN} rule, the input files and/or standard input are not read. However, now that the program has an @code{END} rule, @command{awk} -attempts to read the input @value{DF}s or standard input +attempts to read the input data files or standard input (@pxref{Using BEGIN/END}), most likely causing the program to hang as it waits for input. @@ -19688,17 +19715,92 @@ A more general design for the @code{getlocaltime()} function would have allowed the user to supply an optional timestamp value to use instead of the current time. +@node Readfile Function +@subsection Reading A Whole File At Once + +Often, it is convenient to have the entire contents of a file available +in memory as a single string. A straightforward but naive way to +do that might be as follows: + +@example +function readfile(file, tmp, contents) +@{ + if ((getline tmp < file) < 0) + return + + contents = tmp + while (getline tmp < file) > 0) + contents = contents RT tmp + + close(file) + return contents +@} +@end example + +This function reads from @code{file} one record at a time, building +up the full contents of the file in the local variable @code{contents}. +It works, but is not necessarily efficient. + +The following function, based on a suggestion by Denis Shirokov, +reads the entire contents of the named file in one shot: + +@cindex @code{readfile()} user-defined function +@example +@c file eg/lib/readfile.awk +# readfile.awk --- read an entire file at once +@c endfile +@ignore +@c file eg/lib/readfile.awk +# +# Original idea by Denis Shirokov, cosmogen@@gmail.com, April 2013 +# +@c endfile +@end ignore +@c file eg/lib/readfile.awk + +function readfile(file, tmp, save_rs) +@{ + save_rs = RS + RS = "^$" + getline tmp < file + close(file) + RS = save_rs + + return tmp +@} +@c endfile +@end example + +It works by setting @code{RS} to @samp{^$}, a regular expression that +will never match if the file has contents. @command{gawk} reads data from +the file into @code{tmp} attempting to match @code{RS}. The match fails +after each read, but fails quickly, such that @command{gawk} fills +@code{tmp} with the entire contents of the file. +(@xref{Records}, for information on @code{RT} and @code{RS}.) + +In the case that @code{file} is empty, the return value is the null +string. Thus calling code may use something like: + +@example +contents = readfile("/some/path") +if (length(contents) == 0) + # file was empty @dots{} +@end example + +This tests the result to see if it is empty or not. An equivalent +test would be @samp{contents == ""}. + @node Data File Management -@section @value{DDF} Management +@section Data File Management @c STARTOFRANGE dataf @cindex files, managing @c STARTOFRANGE libfdataf -@cindex libraries of @command{awk} functions, managing, @value{DF}s +@cindex libraries of @command{awk} functions, managing, data files @c STARTOFRANGE flibdataf -@cindex functions, library, managing @value{DF}s +@cindex functions, library, managing data files This @value{SECTION} presents functions that are useful for managing -command-line @value{DF}s. +command-line data files. @menu * Filetrans Function:: A function for handling data file transitions. @@ -19709,16 +19811,16 @@ command-line @value{DF}s. @end menu @node Filetrans Function -@subsection Noting @value{DDF} Boundaries +@subsection Noting Data File Boundaries -@cindex files, managing, @value{DF} boundaries +@cindex files, managing, data file boundaries @cindex files, initialization and cleanup The @code{BEGIN} and @code{END} rules are each executed exactly once at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the -@code{BEGIN} rule is executed at the beginning of each @value{DF} and the -@code{END} rule is executed at the end of each @value{DF}. +@code{BEGIN} rule is executed at the beginning of each data file and the +@code{END} rule is executed at the end of each data file. When informed that this was not the case, the user requested that we add new special @@ -19729,7 +19831,7 @@ Adding these special patterns to @command{gawk} wasn't necessary; the job can be done cleanly in @command{awk} itself, as illustrated by the following library program. It arranges to call two user-supplied functions, @code{beginfile()} and -@code{endfile()}, at the beginning and end of each @value{DF}. +@code{endfile()}, at the beginning and end of each data file. Besides solving the problem in only nine(!) lines of code, it does so @emph{portably}; this works with any implementation of @command{awk}: @@ -19760,17 +19862,17 @@ This file must be loaded before the user's ``main'' program, so that the rule it supplies is executed first. This rule relies on @command{awk}'s @code{FILENAME} variable that -automatically changes for each new @value{DF}. The current @value{FN} is +automatically changes for each new data file. The current file name is saved in a private variable, @code{_oldfilename}. If @code{FILENAME} does -not equal @code{_oldfilename}, then a new @value{DF} is being processed and +not equal @code{_oldfilename}, then a new data file is being processed and it is necessary to call @code{endfile()} for the old file. Because @code{endfile()} should only be called if a file has been processed, the program first checks to make sure that @code{_oldfilename} is not the null -string. The program then assigns the current @value{FN} to +string. The program then assigns the current file name to @code{_oldfilename} and calls @code{beginfile()} for the file. Because, like all @command{awk} variables, @code{_oldfilename} is initialized to the null string, this rule executes correctly even for the -first @value{DF}. +first data file. The program also supplies an @code{END} rule to do the final processing for the last file. Because this @code{END} rule comes before any @code{END} rules @@ -19779,7 +19881,7 @@ again the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function -If the same @value{DF} occurs twice in a row on the command line, then +If the same data file occurs twice in a row on the command line, then @code{endfile()} and @code{beginfile()} are not executed at the end of the first pass and at the beginning of the second pass. The following version solves the problem: @@ -19923,12 +20025,12 @@ The @code{rewind()} function also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). @node File Checking -@subsection Checking for Readable @value{DDF}s +@subsection Checking for Readable Data Files -@cindex troubleshooting, readable @value{DF}s -@cindex readable @value{DF}s@comma{} checking +@cindex troubleshooting, readable data files +@cindex readable data files@comma{} checking @cindex files, skipping -Normally, if you give @command{awk} a @value{DF} that isn't readable, +Normally, if you give @command{awk} a data file that isn't readable, it stops with a fatal error. There are times when you might want to just ignore such files and keep going. You can do this by prepending the following program to your @command{awk} @@ -19977,15 +20079,15 @@ This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an end of file indication, closes the file, and proceeds on to the next -command-line @value{DF}, @emph{without} executing any user-level +command-line data file, @emph{without} executing any user-level @command{awk} program code. Using @command{gawk}'s @code{ARGIND} variable (@pxref{Built-in Variables}), it is possible to detect when an empty -@value{DF} has been skipped. Similar to the library file presented +data file has been skipped. Similar to the library file presented in @ref{Filetrans Function}, the following library file calls a function named @code{zerofile()} that the user must provide. The arguments passed are -the @value{FN} and the position in @code{ARGV} where it was found: +the file name and the position in @code{ARGV} where it was found: @cindex @code{zerofile.awk} program @example @@ -20073,15 +20175,15 @@ END @{ @end ignore @node Ignoring Assigns -@subsection Treating Assignments as @value{FFN}s +@subsection Treating Assignments as File Names @cindex assignments as filenames @cindex filenames, assignments as Occasionally, you might not want @command{awk} to process command-line variable assignments (@pxref{Assignment Options}). -In particular, if you have a @value{FN} that contain an @samp{=} character, -@command{awk} treats the @value{FN} as an assignment, and does not process it. +In particular, if you have a file name that contain an @samp{=} character, +@command{awk} treats the file name as an assignment, and does not process it. Some users have suggested an additional command-line option for @command{gawk} to disable command-line assignments. However, some simple programming with @@ -20125,7 +20227,7 @@ awk -v No_command_assign=1 -f noassign.awk -f yourprog.awk * The function works by looping through the arguments. It prepends @samp{./} to any argument that matches the form -of a variable assignment, turning that argument into a @value{FN}. +of a variable assignment, turning that argument into a file name. The use of @code{No_command_assign} allows you to disable command-line assignments at invocation time, by giving the variable a true value. @@ -20292,7 +20394,7 @@ The discussion that follows walks through the code a bit at a time: # <c> a character representing the current option # Private Data: -# _opti -- index in multi-flag option, e.g., -abc +# _opti -- index in multiflag option, e.g., -abc @c endfile @end example @@ -20484,7 +20586,7 @@ After @code{getopt()} is through, it is the responsibility of the user level code to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options -as @value{FN}s. +as file names. @end quotation Several of the sample programs presented in @@ -21358,7 +21460,7 @@ awk -f @var{program} -- @var{options} @var{files} @noindent Here, @var{program} is the name of the @command{awk} program (such as @file{cut.awk}), @var{options} are any command-line options for the -program that start with a @samp{-}, and @var{files} are the actual @value{DF}s. +program that start with a @samp{-}, and @var{files} are the actual data files. If your system supports the @samp{#!} executable interpreter mechanism (@pxref{Executable Scripts}), @@ -21563,7 +21665,7 @@ spaces. Also remember that after @code{getopt()} is through we have to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options -as @value{FN}s. +as file names. After dealing with the command-line options, the program verifies that the options make sense. Only one or the other of @option{-c} and @option{-f} @@ -21759,8 +21861,8 @@ egrep @r{[} @var{options} @r{]} '@var{pattern}' @var{files} @dots{} The @var{pattern} is a regular expression. In typical usage, the regular expression is quoted to prevent the shell from expanding any of the -special characters as @value{FN} wildcards. Normally, @command{egrep} -prints the lines that matched. If multiple @value{FN}s are provided on +special characters as file name wildcards. Normally, @command{egrep} +prints the lines that matched. If multiple file names are provided on the command line, each output line is preceded by the name of the file and a colon. @@ -21851,7 +21953,7 @@ pattern is supplied with @option{-e}, the first nonoption on the command line is used. The @command{awk} command-line arguments up to @code{ARGV[Optind]} are cleared, so that @command{awk} won't try to process them as files. If no files are specified, the standard input is used, and if multiple files are -specified, we make sure to note this so that the @value{FN}s can precede the +specified, we make sure to note this so that the file names can precede the matched lines in the output: @example @@ -21949,9 +22051,9 @@ A number of additional tests are made, but they are only done if we are not counting lines. First, if the user only wants exit status (@code{no_print} is true), then it is enough to know that @emph{one} line in this file matched, and we can skip on to the next file with -@code{nextfile}. Similarly, if we are only printing @value{FN}s, we can -print the @value{FN}, and then skip to the next file with @code{nextfile}. -Finally, each line is printed, with a leading @value{FN} and colon +@code{nextfile}. Similarly, if we are only printing file names, we can +print the file name, and then skip to the next file with @code{nextfile}. +Finally, each line is printed, with a leading file name and colon if necessary: @cindex @code{!} (exclamation point), @code{!} operator @@ -22199,7 +22301,7 @@ number of lines in each file, supply a number on the command line preceded with a minus; e.g., @samp{-500} for files with 500 lines in them instead of 1000. To change the name of the output files to something like @file{myfileaa}, @file{myfileab}, and so on, supply an additional -argument that specifies the @value{FN} prefix. +argument that specifies the file name prefix. Here is a version of @command{split} in @command{awk}. It uses the @code{ord()} and @code{chr()} functions presented in @@ -22209,8 +22311,8 @@ The program first sets its defaults, and then tests to make sure there are not too many arguments. It then looks at each argument in turn. The first argument could be a minus sign followed by a number. If it is, this happens to look like a negative number, so it is made positive, and that is the -count of lines. The data @value{FN} is skipped over and the final argument -is used as the prefix for the output @value{FN}s: +count of lines. The data file name is skipped over and the final argument +is used as the prefix for the output file names: @cindex @code{split.awk} program @example @@ -22259,7 +22361,7 @@ BEGIN @{ The next rule does most of the work. @code{tcount} (temporary count) tracks how many lines have been printed to the output file so far. If it is greater than @code{count}, it is time to close the current file and start a new one. -@code{s1} and @code{s2} track the current suffixes for the @value{FN}. If +@code{s1} and @code{s2} track the current suffixes for the file name. If they are both @samp{z}, the file is just too big. Otherwise, @code{s1} moves to the next letter in the alphabet and @code{s2} starts over again at @samp{a}: @@ -22347,13 +22449,13 @@ The @code{BEGIN} rule first makes a copy of all the command-line arguments into an array named @code{copy}. @code{ARGV[0]} is not copied, since it is not needed. @code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to -process each @value{FN} in @code{ARGV} as input data. +process each file name in @code{ARGV} as input data. @cindex flag variables If the first argument is @option{-a}, then the flag variable @code{append} is set to true, and both @code{ARGV[1]} and @code{copy[1]} are deleted. If @code{ARGC} is less than two, then no -@value{FN}s were supplied and @code{tee} prints a usage message and exits. +file names were supplied and @code{tee} prints a usage message and exits. Finally, @command{awk} is forced to read the standard input by setting @code{ARGV[1]} to @code{"-"} and @code{ARGC} to two: @@ -22815,7 +22917,7 @@ BEGIN @{ @end example The @code{beginfile()} function is simple; it just resets the counts of lines, -words, and characters to zero, and saves the current @value{FN} in +words, and characters to zero, and saves the current file name in @code{fname}: @example @@ -22837,7 +22939,7 @@ you will see that @code{FNR} has already been reset by the time @code{endfile()} is called.} It then prints out those numbers for the file that was just read. It relies on @code{beginfile()} to reset the -numbers for the following @value{DF}: +numbers for the following data file: @c FIXME: ONE DAY: make the above footnote an exercise, @c instead of giving away the answer. @@ -23005,8 +23107,8 @@ word, comparing it to the previous one: @cindex insomnia, cure for @cindex Robbins, Arnold @quotation -@i{Nothing cures insomnia like a ringing alarm clock.}@* -Arnold Robbins +@i{Nothing cures insomnia like a ringing alarm clock.} +@author Arnold Robbins @end quotation @c STARTOFRANGE tialarm @@ -23182,12 +23284,10 @@ often used to map uppercase letters into lowercase for further processing: @command{tr} requires two lists of characters.@footnote{On some older systems, -@ifset ORA including Solaris, -@end ifset @command{tr} may require that the lists be written as range expressions enclosed in square brackets (@samp{[a-z]}) and quoted, -to prevent the shell from attempting a @value{FN} expansion. This is +to prevent the shell from attempting a file name expansion. This is not a feature.} When processing the input, the first character in the first list is replaced with the first character in the second list, the second character in the first list is replaced with the second @@ -23585,7 +23685,7 @@ The @command{uniq} program (@pxref{Uniq Program}), removes duplicate lines from @emph{sorted} data. -Suppose, however, you need to remove duplicate lines from a @value{DF} but +Suppose, however, you need to remove duplicate lines from a data file but that you want to preserve the order the lines are in. A good example of this might be a shell history file. The history file keeps a copy of all the commands you have entered, and it is not unusual to repeat a command @@ -23721,7 +23821,7 @@ Lines containing @samp{@@group} and @samp{@@end group} are simply removed. (@pxref{Join Function}). The example programs in the online Texinfo source for @cite{@value{TITLE}} -(@file{gawk.texi}) have all been bracketed inside @samp{file} and +(@file{gawktexi.in}) have all been bracketed inside @samp{file} and @samp{endfile} lines. The @command{gawk} distribution uses a copy of @file{extract.awk} to extract the sample programs and install many of them in a standard directory where @command{gawk} can find them. @@ -23804,7 +23904,7 @@ screen. @end ifnottex The second rule handles moving data into files. It verifies that a -@value{FN} is given in the directive. If the file named is not the +file name is given in the directive. If the file named is not the current file, then the current file is closed. Keeping the current file open until a new file is encountered allows the use of the @samp{>} redirection for printing the contents, keeping open file management @@ -23886,7 +23986,7 @@ subsequent output is appended to the file (@pxref{Redirection}). This makes it easy to mix program text and explanatory prose for the same sample source file (as has been done here!) without any hassle. The file is -only closed when a new data @value{FN} is encountered or at the end of the +only closed when a new data file name is encountered or at the end of the input file. Finally, the function @code{@w{unexpected_eof()}} prints an appropriate @@ -23938,7 +24038,7 @@ Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp The following program, @file{awksed.awk}, accepts at least two command-line arguments: the pattern to look for and the text to replace it with. Any -additional arguments are treated as data @value{FN}s to process. If none +additional arguments are treated as data file names to process. If none are provided, the standard input is used: @cindex Brennan, Michael @@ -24011,7 +24111,7 @@ The @code{BEGIN} rule handles the setup, checking for the right number of arguments and calling @code{usage()} if there is a problem. Then it sets @code{RS} and @code{ORS} from the command-line arguments and sets @code{ARGV[1]} and @code{ARGV[2]} to the null string, so that they are -not treated as @value{FN}s +not treated as file names (@pxref{ARGC and ARGV}). The @code{usage()} function prints an error message and exits. @@ -24109,7 +24209,7 @@ Literal text, provided with @option{--source} or @option{--source=}. This text is just appended directly. @item -Source @value{FN}s, provided with @option{-f}. We use a neat trick and append +Source file names, provided with @option{-f}. We use a neat trick and append @samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion program works the way @command{gawk} does, this gets the text of the file included into the program at the correct point. @@ -24122,7 +24222,7 @@ shell variable. @item Run the expanded program with @command{gawk} and any other original command-line -arguments that the user supplied (such as the data @value{FN}s). +arguments that the user supplied (such as the data file names). @end enumerate This program uses shell variables extensively: for storing command-line arguments, @@ -24153,7 +24253,7 @@ programming trick. Don't worry about it if you are not familiar with These are saved and passed on to @command{gawk}. @item -f@r{,} --file@r{,} --file=@r{,} -Wfile= -The @value{FN} is appended to the shell variable @code{program} with an +The file name is appended to the shell variable @code{program} with an @samp{@@include} statement. The @command{expr} utility is used to remove the leading option part of the argument (e.g., @samp{--file=}). @@ -24277,10 +24377,10 @@ is stored in the shell variable @code{expand_prog}. Doing this keeps the shell script readable. The @command{awk} program reads through the user's program, one line at a time, using @code{getline} (@pxref{Getline}). The input -@value{FN}s and @samp{@@include} statements are managed using a stack. -As each @samp{@@include} is encountered, the current @value{FN} is +file names and @samp{@@include} statements are managed using a stack. +As each @samp{@@include} is encountered, the current file name is ``pushed'' onto the stack and the file named in the @samp{@@include} -directive becomes the current @value{FN}. As each file is finished, +directive becomes the current file name. As each file is finished, the stack is ``popped,'' and the previous input file becomes the current input file again. The process is started by making the original file the first one on the stack. @@ -24289,16 +24389,16 @@ The @code{pathto()} function does the work of finding the full path to a file. It simulates @command{gawk}'s behavior when searching the @env{AWKPATH} environment variable (@pxref{AWKPATH Variable}). -If a @value{FN} has a @samp{/} in it, no path search is done. -Similarly, if the @value{FN} is @code{"-"}, then that string is +If a file name has a @samp{/} in it, no path search is done. +Similarly, if the file name is @code{"-"}, then that string is used as-is. Otherwise, -the @value{FN} is concatenated with the name of each directory in -the path, and an attempt is made to open the generated @value{FN}. +the file name is concatenated with the name of each directory in +the path, and an attempt is made to open the generated file name. The only way to test if a file can be read in @command{awk} is to go ahead and try to read it with @code{getline}; this is what @code{pathto()} does.@footnote{On some very old versions of @command{awk}, the test @samp{getline junk < t} can loop forever if the file exists but is empty. -Caveat emptor.} If the file can be read, it is closed and the @value{FN} +Caveat emptor.} If the file can be read, it is closed and the file name is returned: @ignore @@ -24356,14 +24456,14 @@ BEGIN @{ The stack is initialized with @code{ARGV[1]}, which will be @file{/dev/stdin}. The main loop comes next. Input lines are read in succession. Lines that do not start with @samp{@@include} are printed verbatim. -If the line does start with @samp{@@include}, the @value{FN} is in @code{$2}. +If the line does start with @samp{@@include}, the file name is in @code{$2}. @code{pathto()} is called to generate the full path. If it cannot, then the program prints an error message and continues. The next thing to check is if the file is included already. The -@code{processed} array is indexed by the full @value{FN} of each included +@code{processed} array is indexed by the full file name of each included file and it tracks this information for us. If the file is -seen again, a warning message is printed. Otherwise, the new @value{FN} is +seen again, a warning message is printed. Otherwise, the new file name is pushed onto the stack and processing continues. Finally, when @code{getline} encounters the end of the input file, the file @@ -24441,10 +24541,10 @@ options and command-line arguments that the user supplied. @c this causes more problems than it solves, so leave it out. @ignore -The special file @file{/dev/null} is passed as a @value{DF} to @command{gawk} +The special file @file{/dev/null} is passed as a data file to @command{gawk} to handle an interesting case. Suppose that the user's program only has -a @code{BEGIN} rule and there are no @value{DF}s to read. -The program should exit without reading any @value{DF}s. +a @code{BEGIN} rule and there are no data files to read. +The program should exit without reading any data files. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the @@ -24825,8 +24925,8 @@ who knows where you live." @end ignore @quotation @i{Write documentation as if whoever reads it is -a violent psychopath who knows where you live.}@* -Steve English, as quoted by Peter Langston +a violent psychopath who knows where you live.} +@author Steve English, as quoted by Peter Langston @end quotation This @value{CHAPTER} discusses advanced features in @command{gawk}. @@ -25145,7 +25245,7 @@ ordered data: @example function cmp_randomize(i1, v1, i2, v2) @{ - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) @} @end example @@ -25160,7 +25260,7 @@ with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, so consider it only if necessary. The following comparison functions force a deterministic order, and are based on the fact that the -indices of two elements are never equal: +(string) indices of two elements are never equal: @example function cmp_numeric(i1, v1, i2, v2) @@ -25219,15 +25319,14 @@ sorted array traversal is not the default. @cindex arrays, sorting @cindex @code{asort()} function (@command{gawk}) @cindex @code{asort()} function (@command{gawk}), arrays@comma{} sorting +@cindex @code{asorti()} function (@command{gawk}) +@cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting -In most @command{awk} implementations, sorting an array requires -writing a @code{sort()} function. -While this can be educational for exploring different sorting algorithms, -usually that's not the point of the program. -@command{gawk} provides the built-in @code{asort()} -and @code{asorti()} functions -(@pxref{String Functions}) -for sorting arrays. For example: +In most @command{awk} implementations, sorting an array requires writing +a @code{sort()} function. While this can be educational for exploring +different sorting algorithms, usually that's not the point of the program. +@command{gawk} provides the built-in @code{asort()} and @code{asorti()} +functions (@pxref{String Functions}) for sorting arrays. For example: @example @var{populate the array} data @@ -25240,7 +25339,7 @@ After the call to @code{asort()}, the array @code{data} is indexed from 1 to some number @var{n}, the total number of elements in @code{data}. (This count is @code{asort()}'s return value.) @code{data[1]} @value{LEQ} @code{data[2]} @value{LEQ} @code{data[3]}, and so on. -The comparison is based on the type of the elements +The default comparison is based on the type of the elements (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. @@ -25262,24 +25361,11 @@ In this case, @command{gawk} copies the @code{source} array into the @code{dest} array and then sorts @code{dest}, destroying its indices. However, the @code{source} array is not affected. -@code{asort()} accepts a third string argument to control comparison of -array elements. As with @code{PROCINFO["sorted_in"]}, this argument -may be one of the predefined names that @command{gawk} provides -(@pxref{Controlling Scanning}), or the name of a user-defined function -(@pxref{Controlling Array Traversal}). - -@quotation NOTE -In all cases, the sorted element values consist of the original -array's element values. The ability to control comparison merely -affects the way in which they are sorted. -@end quotation - Often, what's needed is to sort on the values of the @emph{indices} -instead of the values of the elements. -To do that, use the -@code{asorti()} function. The interface is identical to that of -@code{asort()}, except that the index values are used for sorting, and -become the values of the result array: +instead of the values of the elements. To do that, use the +@code{asorti()} function. The interface and behavior are identical to +that of @code{asort()}, except that the index values are used for sorting, +and become the values of the result array: @example @{ source[$0] = some_func($0) @} @@ -25296,23 +25382,35 @@ END @{ @} @end example -Similar to @code{asort()}, -in all cases, the sorted element values consist of the original -array's indices. The ability to control comparison merely -affects the way in which they are sorted. +So far, so good. Now it starts to get interesting. Both @code{asort()} +and @code{asorti()} accept a third string argument to control comparison +of array elements. In @ref{String Functions}, we ignored this third +argument; however, the time has now come to describe how this argument +affects these two functions. + +Basically, the third argument specifies how the array is to be sorted. +There are two possibilities. As with @code{PROCINFO["sorted_in"]}, +this argument may be one of the predefined names that @command{gawk} +provides (@pxref{Controlling Scanning}), or it may be the name of a +user-defined function (@pxref{Controlling Array Traversal}). + +In the latter case, @emph{the function can compare elements in any way +it chooses}, taking into account just the indices, just the values, +or both. This is extremely powerful. -Sorting the array by replacing the indices provides maximal flexibility. -To traverse the elements in decreasing order, use a loop that goes from -@var{n} down to 1, either over the elements or over the indices.@footnote{You -may also use one of the predefined sorting names that sorts in -decreasing order.} +Once the array is sorted, @code{asort()} takes the @emph{values} in +their final order, and uses them to fill in the result array, whereas +@code{asorti()} takes the @emph{indices} in their final order, and uses +them to fill in the result array. @cindex reference counting, sorting arrays +@quotation NOTE Copying array indices and elements isn't expensive in terms of memory. Internally, @command{gawk} maintains @dfn{reference counts} to data. For example, when @code{asort()} copies the first array to the second one, there is only one copy of the original array elements' data, even though both arrays use the values. +@end quotation @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in @@ -25538,10 +25636,10 @@ another process on another system across an IP network connection. You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is -by recognizing special @value{FN}s that begin with one of @samp{/inet/}, +by recognizing special file names that begin with one of @samp{/inet/}, @samp{/inet4/} or @samp{/inet6}. -The full syntax of the special @value{FN} is +The full syntax of the special file name is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. The components are: @@ -25910,8 +26008,8 @@ the case of the @code{INT} signal, @command{gawk} exits. This is because these systems don't support the @command{kill} command, so the only signals you can deliver to a program are those generated by the keyboard. The @code{INT} signal is generated by the -@kbd{@value{CTL}-@key{C}} or @kbd{@value{CTL}-@key{BREAK}} key, while the -@code{QUIT} signal is generated by the @kbd{@value{CTL}-@key{\}} key. +@kbd{Ctrl-@key{C}} or @kbd{Ctrl-@key{BREAK}} key, while the +@code{QUIT} signal is generated by the @kbd{Ctrl-@key{\}} key. Finally, @command{gawk} also accepts another option, @option{--pretty-print}. When called this way, @command{gawk} ``pretty prints'' the program into @@ -26703,7 +26801,7 @@ complete detail in @cite{GNU gettext tools}.) @end ifnotinfo As of this writing, the latest version of GNU @code{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz, @value{PVERSION} 0.18.2.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz, version 0.18.2.1}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -27583,7 +27681,7 @@ functions which called the one you are in. The commands for doing this are: Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each -function, the source @value{FN}, and the line number. +function, the source file name, and the line number. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -27716,7 +27814,7 @@ Turn instruction tracing on or off. The default is @code{off}. @end table @item @code{save} @var{filename} -Save the commands from the current session to the given @value{FN}, +Save the commands from the current session to the given file name, so that they can be replayed using the @command{source} command. @item @code{source} @var{filename} @@ -27884,8 +27982,8 @@ features. The following types of completion are available: @item Command completion Command names. -@item Source @value{FN} completion -Source @value{FN}s. Relevant commands are +@item Source file name completion +Source file names. Relevant commands are @code{break}, @code{clear}, @code{list}, @@ -27973,11 +28071,11 @@ to believe. Novice computer users solve this problem by implicitly trusting in the computer as an infallible authority; they tend to believe that all digits of a printed answer are significant. Disillusioned computer users have just the opposite approach; they are constantly afraid that their answers -are almost meaningless.}@* -Donald Knuth@footnote{Donald E.@: Knuth. +are almost meaningless.}@footnote{Donald E.@: Knuth. @cite{The Art of Computer Programming}. Volume 2, @cite{Seminumerical Algorithms}, third edition, 1998, ISBN 0-201-89683-4, p.@: 229.} +@author Donald Knuth @end quotation This @value{CHAPTER} discusses issues that you may encounter @@ -28115,7 +28213,7 @@ This makes it clear that the full numeric value is different from what the default string representations show. @code{CONVFMT}'s default value is @code{"%.6g"}, which yields a value with -at least six significant digits. For some applications, you might want to +at most six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, most of the time, 17 digits is enough to capture a floating-point number's @@ -28144,7 +28242,7 @@ $ @kbd{awk '@{ printf("%010d\n", $1 * 100) @}'} @print{} 0000051580 515.82 @print{} 0000051582 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @noindent @@ -28984,11 +29082,10 @@ floating-point format to a precision lower than working precision. Do we promote them to full membership of the high-precision club, or do we treat them and all their associates as second-class citizens? Sometimes the first course is proper, sometimes the second, and it takes -careful analysis to tell which.} - -Dirk Laurie@footnote{Dirk Laurie. +careful analysis to tell which.}@footnote{Dirk Laurie. @cite{Variable-precision Arithmetic Considered Perilous --- A Detective Story}. Electronic Transactions on Numerical Analysis. Volume 28, pp. 168-173, 2008.} +@author Dirk Laurie @end quotation @command{gawk} does not implicitly modify the precision of any previously @@ -29526,12 +29623,12 @@ the macros as if they were functions. @subsection General Purpose Data Types @quotation -@i{I have a true love/hate relationship with unions.}@* -Arnold Robbins +@i{I have a true love/hate relationship with unions.} +@author Arnold Robbins @i{That's the thing about unions: the compiler will arrange things so they -can accommodate both love and hate.}@* -Chet Ramey +can accommodate both love and hate.} +@author Chet Ramey @end quotation The extension API defines a number of simple types and structures for general @@ -31464,8 +31561,8 @@ path with a list of directories to search for compiled extensions. @section Example: Some File Functions @quotation -@i{No matter where you go, there you are.} @* -Buckaroo Bonzai +@i{No matter where you go, there you are.} +@author Buckaroo Bonzai @end quotation @c It's enough to show chdir and stat, no need for fts @@ -32248,7 +32345,7 @@ Return zero if there were no errors, otherwise return @minus{}1. The @code{fts()} function provides a hook to the C library @code{fts()} routines for traversing file hierarchies. Instead of returning data -about one file at a time in a stream, it fills in a multi-dimensional +about one file at a time in a stream, it fills in a multidimensional array with data about each file and directory encountered in the requested hierarchies. @@ -32349,7 +32446,7 @@ be 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 -creating a multi-dimensional array to represent the file hierarchy and +creating a multidimensional array to represent the file hierarchy and its information. @end quotation @@ -33007,7 +33104,7 @@ Multiple @code{BEGIN} and @code{END} rules @item Multidimensional arrays -(@pxref{Multi-dimensional}). +(@pxref{Multidimensional}). @end itemize @c ENDOFRANGE gawkv1 @@ -33214,7 +33311,7 @@ Special files in I/O redirections: @itemize @minus{} @item The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and -@file{/dev/fd/@var{N}} special @value{FN}s +@file{/dev/fd/@var{N}} special file names (@pxref{Special Files}). @item @@ -33438,7 +33535,7 @@ long options @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} @value{PVERSION} 4.0: +and the documentation for @command{gawk} version 4.0: @c nested table @itemize @minus @@ -33621,8 +33718,8 @@ cases: the default regexp matching; with @option{--traditional}, and with @appendixsec Major Contributors to @command{gawk} @cindex @command{gawk}, list of contributors to @quotation -@i{Always give credit where credit is due.}@* -Anonymous +@i{Always give credit where credit is due.} +@author Anonymous @end quotation This @value{SECTION} names the major contributors to @command{gawk} @@ -33819,6 +33916,10 @@ The modifications to convert @command{gawk} into a byte-code interpreter, including the debugger. @item +The addition of true multidimensional arrays. +@ref{Arrays of Arrays}. + +@item The additional modifications for support of arbitrary precision arithmetic. @item @@ -33831,6 +33932,10 @@ into one, for the 4.1 release. @item Improved array internals for arrays indexed by integers. + +@item +The improved array sorting features were driven by John together +with Pat Rankin. @end itemize @item @@ -33952,7 +34057,7 @@ Extracting the archive creates a directory named @file{gawk-@value{VERSION}.@value{PATCHLEVEL}} in the current directory. -The distribution @value{FN} is of the form +The distribution file name is of the form @file{gawk-@var{V}.@var{R}.@var{P}.tar.gz}. The @var{V} represents the major version of @command{gawk}, the @var{R} represents the current release of version @var{V}, and @@ -33984,6 +34089,13 @@ The actual @command{gawk} source code. @end table @table @file +@item ABOUT-NLS +Information about GNU @command{gettext} and translations. + +@item AUTHORS +A file with some information about the authorship of @command{gawk}. +It exists only to satisfy the pedants at the Free Software Foundation. + @item README @itemx README_d/README.* Descriptive files: @file{README} for @command{gawk} under Unix and the @@ -34007,16 +34119,6 @@ An older list of changes to @command{gawk}. @item COPYING The GNU General Public License. -@item FUTURES -A brief list of features and changes being contemplated for future -releases, with some indication of the time frame for the feature, based -on its difficulty. - -@item LIMITATIONS -A list of those factors that limit @command{gawk}'s performance. -Most of these depend on the hardware or operating system software and -are not limits in @command{gawk} itself. - @item POSIX.STD A description of behaviors in the POSIX standard for @command{awk} which are left undefined, or where @command{gawk} may not comply fully, as well @@ -34049,12 +34151,19 @@ The @command{troff} source for a manual page describing @command{gawk}. This is distributed for the convenience of Unix users. @cindex Texinfo -@item doc/gawk.texi +@item doc/gawktexi.in +@itemx doc/sidebar.awk The Texinfo source file for this @value{DOCUMENT}. -It should be processed with @TeX{} -(via @command{texi2dvi} or @command{texi2pdf}) +It should be processed by @file{doc/sidebar.awk} +before processing with @command{texi2dvi} or @command{texi2pdf} to produce a printed document, and with @command{makeinfo} to produce an Info or HTML file. +The @file{Makefile} takes care of this processing and produces +printable output via @command{texi2dvi} or @command{texi2pdf}. + +@item doc/gawk.texi +The file produced after processing @file{gawktexi.in} +with @file{sidebar.awk}. @item doc/gawk.info The generated Info file for this @value{DOCUMENT}. @@ -34093,15 +34202,21 @@ the @file{Makefile.in} files used by @command{autoconf} and @item Makefile.in @itemx aclocal.m4 +@itemx bisonfix.awk +@itemx config.guess @itemx configh.in @itemx configure.ac @itemx configure @itemx custom.h +@itemx depcomp +@itemx install-sh @itemx missing_d/* +@itemx mkinstalldirs @itemx m4/* -These files and subdirectories are used when configuring @command{gawk} -for various Unix systems. They are explained in -@ref{Unix Installation}. +These files and subdirectories are used when configuring and compiling +@command{gawk} for various Unix systems. Most of them are explained +in @ref{Unix Installation}. The rest are there to support the main +infrastructure. @item po/* The @file{po} library contains message translations. @@ -34245,6 +34360,14 @@ command line when compiling @command{gawk} from scratch, including: @table @code +@cindex @code{--disable-extensions} configuration option +@cindex configuration option, @code{--disable-extensions} +@item --disable-extensions +Disable configuring and building the sample extensions in the +@file{extension} directory. This is useful for cross-compiling. +The default action is to dynamically check if the extensions +can be configured and compiled. + @cindex @code{--disable-lint} configuration option @cindex configuration option, @code{--disable-lint} @item --disable-lint @@ -34804,7 +34927,7 @@ provides information about both the @command{gawk} implementation and the The logical name @samp{AWK_LIBRARY} can designate a default location for @command{awk} program files. For the @option{-f} option, if the specified -@value{FN} has no device or directory path information in it, @command{gawk} +file name has no device or directory path information in it, @command{gawk} looks in the current directory first, then in the directory specified by the translation of @samp{AWK_LIBRARY} if the file is not found. If, after searching in both directories, the file still is not found, @@ -34837,7 +34960,7 @@ One side effect of dual command-line parsing is that if there is only a single parameter (as in the quoted string program above), the command becomes ambiguous. To work around this, the normally optional @option{--} flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any -other dash-type options (or multiple parameters such as @value{DF}s to +other dash-type options (or multiple parameters such as data files to process) are present, there is no ambiguity and @option{--} can be omitted. @c @cindex directory search @@ -34898,7 +35021,7 @@ define a symbol, as follows: $ @kbd{gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe} @end example -This is apparently @value{PVERSION} 2.15.6, which is extremely old. We +This is apparently version 2.15.6, which is extremely old. We recommend compiling and using the current version. @c ENDOFRANGE opgawx @@ -34908,8 +35031,8 @@ recommend compiling and using the current version. @appendixsec Reporting Problems and Bugs @cindex archeologists @quotation -@i{There is nothing more dangerous than a bored archeologist.}@* -The Hitchhiker's Guide to the Galaxy +@i{There is nothing more dangerous than a bored archeologist.} +@author The Hitchhiker's Guide to the Galaxy @end quotation @c the radio show, not the book. :-) @@ -34927,8 +35050,8 @@ what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it -to the smallest possible @command{awk} program and input @value{DF} that -reproduces the problem. Then send us the program and @value{DF}, +to the smallest possible @command{awk} program and input data file that +reproduces the problem. Then send us the program and data file, some idea of what kind of Unix system you're using, the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps @@ -35025,8 +35148,8 @@ Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) @cindex Brennan, Michael @quotation @i{It's kind of fun to put comments like this in your awk code.}@* -@ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course}@* -Michael Brennan +@ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course} +@author Michael Brennan @end quotation There are a number of other freely available @command{awk} implementations. @@ -35068,10 +35191,8 @@ repository in a directory named @file{bwkawk}. If you leave that argument off the @command{git} command line, the repository copy is created in a directory named @file{awk}. -This version requires an ISO C (1990 standard) compiler; -the C compiler from -GCC (the GNU Compiler Collection) -works quite nicely. +This version requires an ISO C (1990 standard) compiler; the C compiler +from GCC (the GNU Compiler Collection) works quite nicely. @xref{Common Extensions}, for a list of extensions in this @command{awk} that are not in POSIX @command{awk}. @@ -35152,15 +35273,22 @@ information, see the @uref{http://busybox.net, project's home page}. @cindex source code, Solaris @command{awk} @item The OpenSolaris POSIX @command{awk} The version of @command{awk} in @file{/usr/xpg4/bin} on Solaris is -more-or-less -POSIX-compliant. It is based on the @command{awk} from Mortice Kern -Systems for PCs. The source code can be downloaded from -the @uref{http://www.opensolaris.org, OpenSolaris web site}. +more-or-less POSIX-compliant. It is based on the @command{awk} from +Mortice Kern Systems for PCs. This author was able to make it compile and work under GNU/Linux with 1--2 hours of work. Making it more generally portable (using GNU Autoconf and/or Automake) would take more work, and this has not been done, at least to our knowledge. +@cindex Illumos +@cindex Illumos, POSIX-compliant @command{awk} +@cindex source code, Illumos @command{awk} +The source code used to be available from the OpenSolaris web site. +However, that project was ended and the web site shut down. Fortunately, the +@uref{http://wiki.illumos.org/display/illumos/illumos+Home, Illumos project} +makes this implementation available. You can view the files one at a time from +@uref{https://github.com/joyent/illumos-joyent/blob/master/usr/src/cmd/awk_xpg4}. + @cindex @command{jawk} @cindex Java implementation of @command{awk} @cindex source code, @command{jawk} @@ -35201,6 +35329,10 @@ under the GPL. It has a large number of extensions over standard See @uref{http://www.quiktrim.org/QTawk.html} for more information, including the manual and a download link. +@item Other Versions +See also the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, +Wikipedia article}, for information on additional versions. + @end table @c ENDOFRANGE gligawk @c ENDOFRANGE ingawk @@ -35811,11 +35943,11 @@ Larry @cindex Wall, Larry @cindex Robbins, Arnold @quotation -@i{AWK is a language similar to PERL, only considerably more elegant.}@* -Arnold Robbins +@i{AWK is a language similar to PERL, only considerably more elegant.} +@author Arnold Robbins -@i{Hey!}@* -Larry Wall +@i{Hey!} +@author Larry Wall @end quotation The @file{TODO} file in the @command{gawk} Git repository lists possible @@ -35947,7 +36079,7 @@ in order to loop over all the element in an easy fashion for C code. @item The ability to create arrays (including @command{gawk}'s true -multi-dimensional arrays). +multidimensional arrays). @end itemize @end itemize @@ -36080,11 +36212,11 @@ to any of the above. @ref{Dynamic Extensions}, describes the supported API and mechanisms for writing extensions for @command{gawk}. This API was introduced -in @value{PVERSION} 4.1. However, for many years @command{gawk} +in version 4.1. However, for many years @command{gawk} provided an extension mechanism that required knowledge of @command{gawk} internals and that was not as well designed. -In order to provide a transition period, @command{gawk} @value{PVERSION} +In order to provide a transition period, @command{gawk} version 4.1 continues to support the original extension mechanism. This will be true for the life of exactly one major release. This support will be withdrawn, and removed from the source code, at the next major @@ -37052,7 +37184,7 @@ numeric values. It is the C type @code{float}. The character generated by hitting the space bar on the keyboard. @item Special File -A @value{FN} interpreted internally by @command{gawk}, instead of being handed +A file name interpreted internally by @command{gawk}, instead of being handed directly to the underlying operating system---for example, @file{/dev/stderr}. (@xref{Special Files}.) @@ -38433,6 +38565,7 @@ Consistency issues: Use MS-Windows not MS Windows Use MS-DOS not MS-DOS Use an empty set of parentheses after built-in and awk function names. + Use "multiFOO" without a hyphen. Date: Wed, 13 Apr 94 15:20:52 -0400 From: rms@gnu.org (Richard Stallman) diff --git a/doc/gawktexi.in b/doc/gawktexi.in index d0356991..aac8c2af 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -115,13 +115,6 @@ @end macro @end ifnothtml -@set FN file name -@set FFN File Name -@set DF data file -@set DDF Data File -@set PVERSION version -@set CTL Ctrl - @ignore Some comments on the layout for TeX. 1. Use at least texinfo.tex 2000-09-06.09 @@ -196,6 +189,7 @@ supports it in developing GNU and promoting software freedom.'' @c during editing and review. @setchapternewpage odd +@shorttitlepage GNU Awk @titlepage @title @value{TITLE} @subtitle @value{SUBTITLE} @@ -405,7 +399,7 @@ particular records in a file and perform operations upon them. * Field Splitting Summary:: Some final points and a summary table. * Constant Size:: Reading constant width data. * Splitting By Content:: Defining Fields By Content -* Multiple Line:: Reading multi-line records. +* Multiple Line:: Reading multiline records. * Getline:: Reading files under explicit program control using the @code{getline} function. @@ -556,9 +550,9 @@ particular records in a file and perform operations upon them. @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. -* Multi-dimensional:: Emulating multidimensional arrays in +* Multidimensional:: Emulating multidimensional arrays in @command{awk}. -* Multi-scanning:: Scanning multidimensional arrays. +* Multiscanning:: Scanning multidimensional arrays. * Arrays of Arrays:: True multidimensional arrays. * Built-in:: Summarizes the built-in functions. * Calling Built-in:: How to call built-in functions. @@ -610,6 +604,8 @@ particular records in a file and perform operations upon them. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. +* Readfile Function:: A function to read an entire file at + once. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -1155,17 +1151,17 @@ wrote the bulk of @cite{TCP/IP Internetworking with @command{gawk}} (a separate document, available as part of the @command{gawk} distribution). His code finally became part of the main @command{gawk} distribution -with @command{gawk} @value{PVERSION} 3.1. +with @command{gawk} version 3.1. John Haque rewrote the @command{gawk} internals, in the process providing an @command{awk}-level debugger. This version became available as -@command{gawk} @value{PVERSION} 4.0, in 2011. +@command{gawk} version 4.0, in 2011. @xref{Contributors}, for a complete list of those who made important contributions to @command{gawk}. @node Names -@section A Rose by Any Other Name +@unnumberedsec A Rose by Any Other Name @cindex @command{awk}, new vs.@: old The @command{awk} language has evolved over the years. Full details are @@ -1201,7 +1197,7 @@ we simply use the term @command{awk}. When referring to a feature that is specific to the GNU implementation, we use the term @command{gawk}. @node This Manual -@section Using This Book +@unnumberedsec Using This Book @cindex @command{awk}, terms describing The term @command{awk} refers to a particular program as well as to the language you @@ -1374,7 +1370,7 @@ present the licenses that cover the @command{gawk} source code and this @value{DOCUMENT}, respectively. @node Conventions -@section Typographical Conventions +@unnumberedsec Typographical Conventions @cindex Texinfo This @value{DOCUMENT} is written in @uref{http://www.gnu.org/software/texinfo/, Texinfo}, @@ -1413,23 +1409,23 @@ emphasized @emph{like this}, and if a point needs to be made strongly, it is done @strong{like this}. The first occurrence of a new term is usually its @dfn{definition} and appears in the same font as the previous occurrence of ``definition'' in this sentence. -Finally, @value{FN}s are indicated like this: @file{/path/to/ourfile}. +Finally, file names are indicated like this: @file{/path/to/ourfile}. @end ifnotinfo Characters that you type at the keyboard look @kbd{like this}. In particular, there are special characters called ``control characters.'' These are characters that you type by holding down both the @kbd{CONTROL} key and -another key, at the same time. For example, a @kbd{@value{CTL}-d} is typed +another key, at the same time. For example, a @kbd{Ctrl-d} is typed by first pressing and holding the @kbd{CONTROL} key, next pressing the @kbd{d} key and finally releasing both keys. @c fakenode --- for prepinfo -@subsubheading Dark Corners +@unnumberedsubsec Dark Corners @cindex Kernighan, Brian @quotation @i{Dark corners are basically fractal --- no matter how much -you illuminate, there's always a smaller but darker one.}@* -Brian Kernighan +you illuminate, there's always a smaller but darker one.} +@author Brian Kernighan @end quotation @cindex d.c., See dark corner @@ -1564,7 +1560,7 @@ of @cite{GAWK: The GNU Awk User's Guide}. Edition @value{EDITION} maintains the basic structure of Edition 1.0, but with significant additional material, reflecting the host of new features -in @command{gawk} @value{PVERSION} @value{VERSION}. +in @command{gawk} version @value{VERSION}. Of particular note is @ref{Array Sorting}, @ref{Bitwise Functions}, @@ -2000,9 +1996,9 @@ awk '@var{program}' @noindent @command{awk} applies the @var{program} to the @dfn{standard input}, which usually means whatever you type on the terminal. This continues -until you indicate end-of-file by typing @kbd{@value{CTL}-d}. +until you indicate end-of-file by typing @kbd{Ctrl-d}. (On other operating systems, the end-of-file character may be different. -For example, on OS/2, it is @kbd{@value{CTL}-z}.) +For example, on OS/2, it is @kbd{Ctrl-z}.) @cindex files, input, See input files @cindex input files, running @command{awk} without @@ -2048,7 +2044,7 @@ $ @kbd{awk '@{ print @}'} @print{} Four score and seven years ago, ... @kbd{What, me worry?} @print{} What, me worry? -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @node Long @@ -2069,7 +2065,7 @@ awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{} @cindex command line, options @cindex options, command-line The @option{-f} instructs the @command{awk} utility to get the @command{awk} program -from the file @var{source-file}. Any @value{FN} can be used for +from the file @var{source-file}. Any file name can be used for @var{source-file}. For example, you could put the program: @example @@ -2094,8 +2090,8 @@ awk "BEGIN @{ print \"Don't Panic!\" @}" @noindent This was explained earlier (@pxref{Read Terminal}). -Note that you don't usually need single quotes around the @value{FN} that you -specify with @option{-f}, because most @value{FN}s don't contain any of the shell's +Note that you don't usually need single quotes around the file name that you +specify with @option{-f}, because most file names don't contain any of the shell's special characters. Notice that in @file{advice}, the @command{awk} program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. @@ -2105,7 +2101,7 @@ for programs that are provided on the @command{awk} command line. @c STARTOFRANGE qs2x @cindex @code{'} (single quote) If you want to clearly identify your @command{awk} program files as such, -you can add the extension @file{.awk} to the @value{FN}. This doesn't +you can add the extension @file{.awk} to the file name. This doesn't affect the execution of the @command{awk} program but it does make ``housekeeping'' easier. @@ -2132,13 +2128,13 @@ BEGIN @{ print "Don't Panic!" @} After making this file executable (with the @command{chmod} utility), simply type @samp{advice} at the shell and the system arranges to run @command{awk}@footnote{The -line beginning with @samp{#!} lists the full @value{FN} of an interpreter +line beginning with @samp{#!} lists the full file name of an interpreter to run and an optional initial command-line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument -in the list is the full @value{FN} of the @command{awk} program. +in the list is the full file name of the @command{awk} program. The rest of the -argument list contains either options to @command{awk}, or @value{DF}s, +argument list contains either options to @command{awk}, or data files, or both. Note that on many systems @command{awk} may be found in @file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had typed @samp{awk -f advice}: @@ -2349,7 +2345,7 @@ awk -F"" '@var{program}' @var{files} # wrong! @noindent In the second case, @command{awk} will attempt to use the text of the program -as the value of @code{FS}, and the first @value{FN} as the text of the program! +as the value of @code{FS}, and the first file name as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize @@ -2464,19 +2460,19 @@ gawk "@{ print \"\042\" $0 \"\042\" @}" @var{file} @node Sample Data Files -@section @value{DDF}s for the Examples +@section Data Files for the Examples @c For gawk >= 4.0, update these data files. No-one has such slow modems! @cindex input files, examples @cindex @code{BBS-list} file Many of the examples in this @value{DOCUMENT} take their input from two sample -@value{DF}s. The first, @file{BBS-list}, represents a list of +data files. The first, @file{BBS-list}, represents a list of computer bulletin board systems together with information about those systems. -The second @value{DF}, called @file{inventory-shipped}, contains +The second data file, called @file{inventory-shipped}, contains information about monthly shipments. In both files, each line is considered to be one @dfn{record}. -In the @value{DF} @file{BBS-list}, each record contains the name of a computer +In the data file @file{BBS-list}, each record contains the name of a computer bulletin board, its phone number, the board's baud rate(s), and a code for the number of hours it is operational. An @samp{A} in the last column means the board operates 24 hours a day. A @samp{B} in the last @@ -2506,7 +2502,7 @@ sabafoo 555-2127 1200/300 C @end example @cindex @code{inventory-shipped} file -The @value{DF} @file{inventory-shipped} represents +The data file @file{inventory-shipped} represents information about shipments during the year. Each record contains the month, the number of green crates shipped, the number of red boxes shipped, the number of @@ -2550,8 +2546,8 @@ learn in this @value{DOCUMENT}. @cindex Texinfo If you are using the stand-alone version of Info, see @ref{Extract Program}, -for an @command{awk} program that extracts these @value{DF}s from -@file{gawk.texi}, the Texinfo source file for this Info file. +for an @command{awk} program that extracts these data files from +@file{gawk.texi}, the (generated) Texinfo source file for this Info file. @end ifinfo @node Very Simple @@ -2613,9 +2609,9 @@ collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description of the program will give you a good idea of what is going on, but please read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) -Most of the examples use a @value{DF} named @file{data}. This is just a +Most of the examples use a data file named @file{data}. This is just a placeholder; if you use these programs yourself, substitute -your own @value{FN}s for @file{data}. +your own file names for @file{data}. For future reference, note that there is often more than one way to do things in @command{awk}. At some point, you may want to look back at these examples and see if @@ -2705,7 +2701,7 @@ awk 'END @{ print NR @}' data @end example @item -Print the even-numbered lines in the @value{DF}: +Print the even-numbered lines in the data file: @example awk 'NR % 2 == 0' data @@ -2747,7 +2743,7 @@ This program prints every line that contains the string @samp{12} @emph{or} the string @samp{21}. If a line contains both strings, it is printed twice, once by each rule. -This is what happens if we run this program on our two sample @value{DF}s, +This is what happens if we run this program on our two sample data files, @file{BBS-list} and @file{inventory-shipped}: @example @@ -2813,7 +2809,7 @@ the file. The fourth field identifies the group of the file. The fifth field contains the size of the file in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the @value{FN}.@footnote{The @samp{LC_ALL=C} is +contains the file name.@footnote{The @samp{LC_ALL=C} is needed to produce this traditional-style output from @command{ls}.} @c @cindex automatic initialization @@ -3222,8 +3218,8 @@ conventions. @cindex @code{-} (hyphen), filenames beginning with @cindex hyphen (@code{-}), filenames beginning with -This is useful if you have @value{FN}s that start with @samp{-}, -or in shell scripts, if you have @value{FN}s that will be specified +This is useful if you have file names that start with @samp{-}, +or in shell scripts, if you have file names that will be specified by the user that could start with @samp{-}. It is also useful for passing options on to the @command{awk} program; see @ref{Getopt Function}. @@ -3441,7 +3437,7 @@ when parsing numeric input data (@pxref{Locales}). Enable pretty-printing of @command{awk} programs. By default, output program is created in a file named @file{awkprof.out}. The optional @var{file} argument allows you to specify a different -@value{FN} for the output. +file name for the output. No space is allowed between the @option{-o} and @var{file}, if @var{file} is supplied. @@ -3462,7 +3458,7 @@ Enable profiling of @command{awk} programs (@pxref{Profiling}). By default, profiles are created in a file named @file{awkprof.out}. The optional @var{file} argument allows you to specify a different -@value{FN} for the profile file. +file name for the profile file. No space is allowed between the @option{-p} and @var{file}, if @var{file} is supplied. @@ -3590,7 +3586,7 @@ function names must be unique.) With standard @command{awk}, library functions can still be used, even if the program is entered at the terminal, by specifying @samp{-f /dev/tty}. After typing your program, -type @kbd{@value{CTL}-d} (the end-of-file character) to terminate it. +type @kbd{Ctrl-d} (the end-of-file character) to terminate it. (You may also use @samp{-f -} to read program source from the standard input but then you will not be able to also use the standard input as a source of data.) @@ -3672,9 +3668,9 @@ sets the variable @code{ARGIND} to the index in @code{ARGV} of the current element. @cindex input files, variable assignments and -The distinction between @value{FN} arguments and variable-assignment +The distinction between file name arguments and variable-assignment arguments is made when @command{awk} is about to open the next input file. -At that point in execution, it checks the @value{FN} to see whether +At that point in execution, it checks the file name to see whether it is really a variable assignment; if so, @command{awk} sets the variable instead of reading a file. @@ -3691,7 +3687,7 @@ sequences (@pxref{Escape Sequences}). @value{DARKCORNER} In some earlier implementations of @command{awk}, when a variable assignment -occurred before any @value{FN}s, the assignment would happen @emph{before} +occurred before any file names, the assignment would happen @emph{before} the @code{BEGIN} rule was executed. @command{awk}'s behavior was thus inconsistent; some command-line assignments were available inside the @code{BEGIN} rule, while others were not. Unfortunately, @@ -3702,8 +3698,8 @@ upon the old behavior. The variable assignment feature is most useful for assigning to variables such as @code{RS}, @code{OFS}, and @code{ORS}, which control input and -output formats before scanning the @value{DF}s. It is also useful for -controlling state if multiple passes are needed over a @value{DF}. For +output formats before scanning the data files. It is also useful for +controlling state if multiple passes are needed over a data file. For example: @cindex files, multiple passes over @@ -3739,13 +3735,13 @@ You may also use @code{"-"} to name standard input when reading files with @code{getline} (@pxref{Getline/File}). In addition, @command{gawk} allows you to specify the special -@value{FN} @file{/dev/stdin}, both on the command line and +file name @file{/dev/stdin}, both on the command line and with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file in the file system, however, @command{gawk} always processes -this @value{FN} itself.) +this file name itself.) @node Environment Variables @section The Environment Variables @command{gawk} Uses @@ -3775,7 +3771,7 @@ on the command-line with the @option{-f} option. In most @command{awk} implementations, you must supply a precise path name for each program file, unless the file is in the current directory. -But in @command{gawk}, if the @value{FN} supplied to the @option{-f} +But in @command{gawk}, if the file name supplied to the @option{-f} or @option{-i} options does not contain a @samp{/}, then @command{gawk} searches a list of directories (called the @dfn{search path}), one by one, looking for a @@ -3795,7 +3791,7 @@ though.} The search path feature is particularly useful for building libraries of useful @command{awk} functions. The library files can be placed in a standard directory in the default path and then specified on -the command line with a short @value{FN}. Otherwise, the full @value{FN} +the command line with a short file name. Otherwise, the full file name would have to be typed for each file. By using the @option{-i} option, or the @option{--source} and @option{-f} options, your command-line @@ -3889,10 +3885,6 @@ for use by the @command{gawk} developers for testing and tuning. They are subject to change. The variables are: @table @env -@item AVG_CHAIN_MAX -The average number of items @command{gawk} will maintain on a -hash chain for managing arrays. - @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} will switch to using the hash function from GNU Smalltalk for @@ -3905,6 +3897,13 @@ files one line at a time, instead of reading in blocks. This exists for debugging problems on filesystems on non-POSIX operating systems where I/O is performed in records, not in blocks. +@item GAWK_MSG_SRC +If this variable exists, @command{gawk} includes the source file +name and line number from which warning and/or fatal messages +are generated. Its purpose is to help isolate the source of a +message, since there can be multiple places which produce the +same warning or error message. + @item GAWK_NO_DFA If this variable exists, @command{gawk} does not use the DFA regexp matcher for ``does it match'' kinds of tests. This can cause @command{gawk} @@ -3917,6 +3916,14 @@ coordinate with each other.) This specifies the amount by which @command{gawk} should grow its internal evaluation stack, when needed. +@item INT_CHAIN_MAX +The average number of items @command{gawk} will maintain on a +hash chain for managing arrays indexed by integers. + +@item STR_CHAIN_MAX +The average number of items @command{gawk} will maintain on a +hash chain for managing arrays indexed by strings. + @item TIDYMEM If this variable exists, @command{gawk} uses the @code{mtrace()} library calls from GNU LIBC to help track down possible memory leaks. @@ -3995,7 +4002,7 @@ use @samp{@@include} followed by the name of the file to be included, enclosed in double quotes. @quotation NOTE -Keep in mind that this is a language construct and the @value{FN} cannot +Keep in mind that this is a language construct and the file name cannot be a string variable, but rather just a literal string in double quotes. @end quotation @@ -4020,7 +4027,7 @@ $ @kbd{gawk -f test3} @print{} This is file test3. @end example -The @value{FN} can, of course, be a pathname. For example: +The file name can, of course, be a pathname. For example: @example @@include "../io_funcs" @@ -4118,7 +4125,7 @@ they will @emph{not} be in the next release). @cindex @code{PROCINFO} array The process-related special files @file{/dev/pid}, @file{/dev/ppid}, @file{/dev/pgrpid}, and @file{/dev/user} were deprecated in @command{gawk} -3.1, but still worked. As of @value{PVERSION} 4.0, they are no longer +3.1, but still worked. As of version 4.0, they are no longer interpreted specially by @command{gawk}. (Use @code{PROCINFO} instead; see @ref{Auto-set}.) @@ -4137,8 +4144,8 @@ in case some option becomes obsolete in a future version of @command{gawk}. @cindex Jedi knights @cindex Knights, jedi @quotation -@i{Use the Source, Luke!}@* -Obi-Wan +@i{Use the Source, Luke!} +@author Obi-Wan @end quotation This @value{SECTION} intentionally left @@ -4374,39 +4381,39 @@ A literal backslash, @samp{\}. @cindex @code{\} (backslash), @code{\a} escape sequence @cindex backslash (@code{\}), @code{\a} escape sequence @item \a -The ``alert'' character, @kbd{@value{CTL}-g}, ASCII code 7 (BEL). +The ``alert'' character, @kbd{Ctrl-g}, ASCII code 7 (BEL). (This usually makes some sort of audible noise.) @cindex @code{\} (backslash), @code{\b} escape sequence @cindex backslash (@code{\}), @code{\b} escape sequence @item \b -Backspace, @kbd{@value{CTL}-h}, ASCII code 8 (BS). +Backspace, @kbd{Ctrl-h}, ASCII code 8 (BS). @cindex @code{\} (backslash), @code{\f} escape sequence @cindex backslash (@code{\}), @code{\f} escape sequence @item \f -Formfeed, @kbd{@value{CTL}-l}, ASCII code 12 (FF). +Formfeed, @kbd{Ctrl-l}, ASCII code 12 (FF). @cindex @code{\} (backslash), @code{\n} escape sequence @cindex backslash (@code{\}), @code{\n} escape sequence @item \n -Newline, @kbd{@value{CTL}-j}, ASCII code 10 (LF). +Newline, @kbd{Ctrl-j}, ASCII code 10 (LF). @cindex @code{\} (backslash), @code{\r} escape sequence @cindex backslash (@code{\}), @code{\r} escape sequence @item \r -Carriage return, @kbd{@value{CTL}-m}, ASCII code 13 (CR). +Carriage return, @kbd{Ctrl-m}, ASCII code 13 (CR). @cindex @code{\} (backslash), @code{\t} escape sequence @cindex backslash (@code{\}), @code{\t} escape sequence @item \t -Horizontal TAB, @kbd{@value{CTL}-i}, ASCII code 9 (HT). +Horizontal TAB, @kbd{Ctrl-i}, ASCII code 9 (HT). @c @cindex @command{awk} language, V.4 version @cindex @code{\} (backslash), @code{\v} escape sequence @cindex backslash (@code{\}), @code{\v} escape sequence @item \v -Vertical tab, @kbd{@value{CTL}-k}, ASCII code 11 (VT). +Vertical tab, @kbd{Ctrl-k}, ASCII code 11 (VT). @cindex @code{\} (backslash), @code{\}@var{nnn} escape sequence @cindex backslash (@code{\}), @code{\}@var{nnn} escape sequence @@ -4738,7 +4745,7 @@ constants, @command{gawk} did @emph{not} match interval expressions in regexps. -However, beginning with @value{PVERSION} 4.0, +However, beginning with version 4.0, @command{gawk} does match interval expressions by default. This is because compatibility with POSIX has become more important to most @command{gawk} users than compatibility with @@ -5329,7 +5336,7 @@ But a newline in a regexp constant works with no problem: $ @kbd{awk '$0 ~ /[ \t\n]/'} @kbd{here is a sample line} @print{} here is a sample line -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @command{gawk} does not have this problem, and it isn't likely to @@ -5379,7 +5386,7 @@ used with it do not have to be named on the @command{awk} command line * Field Separators:: The field separator and how to change it. * Constant Size:: Reading constant width data. * Splitting By Content:: Defining Fields By Content -* Multiple Line:: Reading multi-line records. +* Multiple Line:: Reading multiline records. * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. @@ -5404,7 +5411,7 @@ so far from the current input file. This value is stored in a built-in variable called @code{FNR}. It is reset to zero when a new file is started. Another built-in variable, @code{NR}, records the total -number of input records read so far from all @value{DF}s. It starts at zero, +number of input records read so far from all data files. It starts at zero, but is never automatically reset to zero. @cindex separators, for records @@ -5478,7 +5485,7 @@ $ @kbd{awk 'BEGIN @{ RS = "/" @}} @noindent Note that the entry for the @samp{camelot} BBS is not split. -In the original @value{DF} +In the original data file (@pxref{Sample Data Files}), the line looks like this: @@ -5491,7 +5498,7 @@ It has one baud rate only, so there are no slashes in the record, unlike the others which have two or more baud rates. In fact, this record is treated as part of the record for the @samp{core} BBS; the newline separating them in the output -is the original newline in the @value{DF}, not the one added by +is the original newline in the data file, not the one added by @command{awk} when it printed the record! @cindex record separators, changing @@ -5627,8 +5634,8 @@ In compatibility mode, only the first character of the value of @code{RS} is used to determine the end of the record. @sidebar @code{RS = "\0"} Is Not Portable -@cindex portability, @value{DF}s as single record -There are times when you might want to treat an entire @value{DF} as a +@cindex portability, data files as single record +There are times when you might want to treat an entire data file as a single record. The only way to make this happen is to give @code{RS} a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary @@ -6810,7 +6817,7 @@ appear in a row, they are considered one record separator. @cindex dark corner, multiline records There is an important difference between @samp{RS = ""} and @samp{RS = "\n\n+"}. In the first case, leading newlines in the input -@value{DF} are ignored, and if a file ends without extra blank lines +data file are ignored, and if a file ends without extra blank lines after the last record, the final newline is removed from the record. In the second case, this special processing is not done. @value{DARKCORNER} @@ -6845,7 +6852,7 @@ Another way to separate fields is to put each field on a separate line: to do this, just set the variable @code{FS} to the string @code{"\n"}. (This single character separator matches a single newline.) -A practical example of a @value{DF} organized this way might be a mailing +A practical example of a data file organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named @file{addresses}, which looks like this: @@ -6910,7 +6917,7 @@ value of @table @code @item RS == "\n" Records are separated by the newline character (@samp{\n}). In effect, -every line in the @value{DF} is a separate record, including blank lines. +every line in the data file is a separate record, including blank lines. This is the default. @item RS == @var{any single character} @@ -7116,7 +7123,7 @@ the value of @code{NF} do not change. @cindex operators, input/output Use @samp{getline < @var{file}} to read the next record from @var{file}. Here @var{file} is a string-valued expression that -specifies the @value{FN}. @samp{< @var{file}} is called a @dfn{redirection} +specifies the file name. @samp{< @var{file}} is called a @dfn{redirection} because it directs input to come from a different place. For example, the following program reads its input record from the file @file{secondary.input} when it @@ -7202,8 +7209,8 @@ that does handle nested @samp{@@include} statements. @c From private email, dated October 2, 1988. Used by permission, March 2013. @quotation @i{Omniscience has much to recommend it. -Failing that, attention to details would be useful.}@* -Brian Kernighan +Failing that, attention to details would be useful.} +@author Brian Kernighan @end quotation @cindex @code{|} (vertical bar), @code{|} operator (I/O) @@ -7423,10 +7430,10 @@ system permits. @item An interesting side effect occurs if you use @code{getline} without a redirection inside a @code{BEGIN} rule. Because an unredirected @code{getline} -reads from the command-line @value{DF}s, the first @code{getline} command +reads from the command-line data files, the first @code{getline} command causes @command{awk} to set the value of @code{FILENAME}. Normally, @code{FILENAME} does not have a value inside @code{BEGIN} rules, because you -have not yet started to process the command-line @value{DF}s. +have not yet started to process the command-line data files. @value{DARKCORNER} (@xref{BEGIN/END}, also @pxref{Auto-set}.) @@ -7648,7 +7655,7 @@ For printing with specifications, you need the @code{printf} statement @cindex @code{printf} statement Besides basic and formatted printing, this @value{CHAPTER} also covers I/O redirections to files and pipes, introduces -the special @value{FN}s that @command{gawk} processes internally, +the special file names that @command{gawk} processes internally, and discusses the @code{close()} built-in function. @menu @@ -8449,9 +8456,9 @@ but they work identically for @code{printf}: @cindex operators, input/output @item print @var{items} > @var{output-file} This redirection prints the items into the output file named -@var{output-file}. The @value{FN} @var{output-file} can be any +@var{output-file}. The file name @var{output-file} can be any expression. Its value is changed to a string and then used as a -@value{FN} (@pxref{Expressions}). +file name (@pxref{Expressions}). When this type of redirection is used, the @var{output-file} is erased before the first output is written to it. Subsequent writes to the same @@ -8617,7 +8624,7 @@ open as many pipelines as the underlying operating system permits. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, @command{sh}. For example, suppose you -have a list of files brought over from a system where all the @value{FN}s +have a list of files brought over from a system where all the file names are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient: @@ -8639,12 +8646,12 @@ It then sends the list to the shell for execution. @c ENDOFRANGE reout @node Special Files -@section Special @value{FFN}s in @command{gawk} +@section Special File Names in @command{gawk} @c STARTOFRANGE gfn -@cindex @command{gawk}, @value{FN}s in +@cindex @command{gawk}, file names in -@command{gawk} provides a number of special @value{FN}s that it interprets -internally. These @value{FN}s provide access to standard file descriptors +@command{gawk} provides a number of special file names that it interprets +internally. These file names provide access to standard file descriptors and TCP/IP networking. @menu @@ -8708,12 +8715,12 @@ that happens, writing to the screen is not correct. In fact, if terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk} provides special @value{FN}s for accessing the three standard +@command{gawk} provides special file names for accessing the three standard streams. @value{COMMONEXT}. It also provides syntax for accessing -any other inherited open files. If the @value{FN} matches +any other inherited open files. If the file name matches one of these special names when @command{gawk} redirects input or output, -then it directly uses the stream that the @value{FN} stands for. -These special @value{FN}s work for all operating systems that @command{gawk} +then it directly uses the stream that the file name stands for. +These special file names work for all operating systems that @command{gawk} has been ported to, not just those that are POSIX-compliant: @cindex common extensions, @code{/dev/stdin} special file @@ -8722,7 +8729,7 @@ has been ported to, not just those that are POSIX-compliant: @cindex extensions, common@comma{} @code{/dev/stdin} special file @cindex extensions, common@comma{} @code{/dev/stdout} special file @cindex extensions, common@comma{} @code{/dev/stderr} special file -@cindex @value{FN}s, standard streams in @command{gawk} +@cindex file names, standard streams in @command{gawk} @cindex @code{/dev/@dots{}} special files (@command{gawk}) @cindex files, @code{/dev/@dots{}} special files @cindex @code{/dev/fd/@var{N}} special files @@ -8743,7 +8750,7 @@ the shell). Unless special pains are taken in the shell from which @command{gawk} is invoked, only descriptors 0, 1, and 2 are available. @end table -The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} +The file names @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2}, respectively. However, they are more self-explanatory. The proper way to write an error message in a @command{gawk} program @@ -8753,14 +8760,14 @@ is to use @file{/dev/stderr}, like this: print "Serious error detected!" > "/dev/stderr" @end example -@cindex troubleshooting, quotes with @value{FN}s -Note the use of quotes around the @value{FN}. +@cindex troubleshooting, quotes with file names +Note the use of quotes around the file name. Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. @c Exercise: What does it do? :-) -Finally, using the @code{close()} function on a @value{FN} of the +Finally, using the @code{close()} function on a file name of the form @code{"/dev/fd/@var{N}"}, for file descriptor numbers above two, does actually close the given file descriptor. @@ -8776,7 +8783,7 @@ versions of @command{awk}. @command{gawk} programs can open a two-way TCP/IP connection, acting as either a client or a server. -This is done using a special @value{FN} of the form: +This is done using a special file name of the form: @example @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}} @@ -8786,7 +8793,7 @@ The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}. The @var{protocol} is one of @samp{tcp} or @samp{udp}, and the other fields represent the other essential pieces of information for making a networking connection. -These @value{FN}s are used with the @samp{|&} operator for communicating +These file names are used with the @samp{|&} operator for communicating with a coprocess (@pxref{Two-way I/O}). This is an advanced feature, mentioned here only for completeness. @@ -8794,21 +8801,21 @@ Full discussion is delayed until @ref{TCP/IP Networking}. @node Special Caveats -@subsection Special @value{FFN} Caveats +@subsection Special File Name Caveats Here is a list of things to bear in mind when using the -special @value{FN}s that @command{gawk} provides: +special file names that @command{gawk} provides: @itemize @bullet -@cindex compatibility mode (@command{gawk}), @value{FN}s -@cindex @value{FN}s, in compatibility mode +@cindex compatibility mode (@command{gawk}), file names +@cindex file names, in compatibility mode @item -Recognition of these special @value{FN}s is disabled if @command{gawk} is in +Recognition of these special file names is disabled if @command{gawk} is in compatibility mode (@pxref{Options}). @item @command{gawk} @emph{always} -interprets these special @value{FN}s. +interprets these special file names. For example, using @samp{/dev/fd/4} for output actually writes on file descriptor 4, and not on a new file descriptor that is @code{dup()}'ed from file descriptor 4. Most of @@ -8831,7 +8838,7 @@ Doing so results in unpredictable behavior. @cindex coprocesses, closing @cindex @code{getline} command, coprocesses@comma{} using from -If the same @value{FN} or the same shell command is used with @code{getline} +If the same file name or the same shell command is used with @code{getline} more than once during the execution of an @command{awk} program (@pxref{Getline}), the file is opened (or the command is executed) the first time only. @@ -8840,7 +8847,7 @@ The next time the same file or command is used with @code{getline}, another record is read from it, and so on. Similarly, when a file or pipe is opened for output, @command{awk} remembers -the @value{FN} or command associated with it, and subsequent +the file name or command associated with it, and subsequent writes to the same file or command are appended to the previous writes. The file or pipe stays open until @command{awk} exits. @@ -8882,7 +8889,7 @@ file or command, or the next @code{print} or @code{printf} to that file or command, reopens the file or reruns the command. Because the expression that you use to close a file or pipeline must exactly match the expression used to open the file or run the command, -it is good practice to use a variable to store the @value{FN} or command. +it is good practice to use a variable to store the file name or command. The previous example becomes the following: @example @@ -8931,7 +8938,7 @@ a separate message. @cindex portability, @code{close()} function and If you use more files than the system allows you to have open, @command{gawk} attempts to multiplex the available open files among -your @value{DF}s. @command{gawk}'s ability to do this depends upon the +your data files. @command{gawk}'s ability to do this depends upon the facilities of your operating system, so it may not always work. It is therefore both good practice and good portability advice to always use @code{close()} on your files when you are done with them. @@ -9445,7 +9452,7 @@ as in the following: @noindent the variable is set at the very beginning, even before the @code{BEGIN} rules execute. The @option{-v} option and its assignment -must precede all the @value{FN} arguments, as well as the program text. +must precede all the file name arguments, as well as the program text. (@xref{Options}, for more information about the @option{-v} option.) Otherwise, the variable assignment is performed at a time determined by @@ -9527,7 +9534,7 @@ with @code{CONVFMT} as the format specifier (@pxref{String Functions}). -@code{CONVFMT}'s default value is @code{"%.6g"}, which prints a value with +@code{CONVFMT}'s default value is @code{"%.6g"}, which creates a value with at most six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, @@ -9618,7 +9625,7 @@ point, so the default behavior was restored to use a period as the decimal point character. You can use the @option{--use-lc-numeric} option (@pxref{Options}) to force @command{gawk} to use the locale's decimal point character. (@command{gawk} also uses the locale's decimal -point character when in POSIX mode, either via @w{@option{--posix}}, or the +point character when in POSIX mode, either via @option{--posix}, or the @env{POSIXLY_CORRECT} environment variable, as shown previously.) @ref{table-locale-affects} describes the cases in which the locale's decimal @@ -9776,8 +9783,8 @@ For maximum portability, do not use the @samp{**} operator. @subsection String Concatenation @cindex Kernighan, Brian @quotation -@i{It seemed like a good idea at the time.}@* -Brian Kernighan +@i{It seemed like a good idea at the time.} +@author Brian Kernighan @end quotation @cindex string operators @@ -10248,8 +10255,8 @@ like @samp{@var{lvalue}++}, but instead of adding, it subtracts.) @cindex Marx, Groucho @quotation @i{Doctor, doctor! It hurts when I do this!@* -So don't do that!}@* -Groucho Marx +So don't do that!} +@author Groucho Marx @end quotation @noindent @@ -10346,8 +10353,8 @@ the string constant @code{"0"} is actually true, because it is non-null. @node Typing and Comparison @subsection Variable Typing and Comparison Expressions @quotation -@i{The Guide is definitive. Reality is frequently inaccurate.}@* -The Hitchhiker's Guide to the Galaxy +@i{The Guide is definitive. Reality is frequently inaccurate.} +@author The Hitchhiker's Guide to the Galaxy @end quotation @c STARTOFRANGE comex @@ -11005,7 +11012,7 @@ $ @kbd{awk '@{ print "The square root of", $1, "is", sqrt($1) @}'} @print{} The square root of 3 is 1.73205 @kbd{5} @print{} The square root of 5 is 2.23607 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example A function can also have side effects, such as assigning @@ -12527,11 +12534,11 @@ The @code{nextfile} statement is similar to the @code{next} statement. However, instead of abandoning processing of the current record, the @code{nextfile} statement instructs @command{awk} to stop processing the -current @value{DF}. +current data file. Upon execution of the @code{nextfile} statement, @code{FILENAME} is -updated to the name of the next @value{DF} listed on the command line, +updated to the name of the next data file listed on the command line, @code{FNR} is reset to one, and processing starts over with the first rule in the program. @@ -12540,10 +12547,10 @@ then the code in any @code{END} rules is executed. An exception to this is when @code{nextfile} is invoked during execution of any statement in an @code{END} rule; In this case, it causes the program to stop immediately. @xref{BEGIN/END}. -The @code{nextfile} statement is useful when there are many @value{DF}s +The @code{nextfile} statement is useful when there are many data files to process but it isn't necessary to process every record in every file. Without @code{nextfile}, -in order to move on to the next @value{DF}, a program +in order to move on to the next data file, a program would have to continue scanning the unwanted records. The @code{nextfile} statement accomplishes this much more efficiently. @@ -12781,7 +12788,7 @@ exclusively on the value of @code{FS}. @item FS This is the input field separator (@pxref{Field Separators}). -The value is a single-character string or a multi-character regular +The value is a single-character string or a multicharacter regular expression that matches the separations between fields in an input record. If the value is the null string (@code{""}), then each character in the record becomes a separate field. @@ -12927,7 +12934,7 @@ This is the subscript separator. It has the default value of @code{"\034"} and is used to separate the parts of the indices of a multidimensional array. Thus, the expression @code{@w{foo["A", "B"]}} really accesses @code{foo["A\034B"]} -(@pxref{Multi-dimensional}). +(@pxref{Multidimensional}). @cindex @command{gawk}, @code{TEXTDOMAIN} variable in @cindex @code{TEXTDOMAIN} variable @@ -13010,17 +13017,17 @@ about how @command{awk} uses these variables. @cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable @item ARGIND # The index in @code{ARGV} of the current file being processed. -Every time @command{gawk} opens a new @value{DF} for processing, it sets -@code{ARGIND} to the index in @code{ARGV} of the @value{FN}. +Every time @command{gawk} opens a new data file for processing, it sets +@code{ARGIND} to the index in @code{ARGV} of the file name. When @command{gawk} is processing the input files, @samp{FILENAME == ARGV[ARGIND]} is always true. @cindex files, processing@comma{} @code{ARGIND} variable and This variable is useful in file processing; it allows you to tell how far -along you are in the list of @value{DF}s as well as to distinguish between -successive instances of the same @value{FN} on the command line. +along you are in the list of data files as well as to distinguish between +successive instances of the same file name on the command line. -@cindex @value{FN}s, distinguishing +@cindex file names, distinguishing While you can change the value of @code{ARGIND} within your @command{awk} program, @command{gawk} automatically sets it to a new value when the next file is opened. @@ -13037,10 +13044,18 @@ it is not special. An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of the particular environment variables. For example, -@code{ENVIRON["HOME"]} might be @file{/home/arnold}. Changing this array -does not affect the environment passed on to any programs that -@command{awk} may spawn via redirection or the @code{system()} function. -@c (In a future version of @command{gawk}, it may do so.) +@code{ENVIRON["HOME"]} might be @file{/home/arnold}. + +For POSIX @command{awk}, changing this array does not affect the +environment passed on to any programs that @command{awk} may spawn via +redirection or the @code{system()} function. + +However, beginning with version 4.2, if not in POSIX +compatibility mode, @command{gawk} does update its own environment when +@code{ENVIRON} is changed, thus changing the environment seen by programs +that it creates. You should therefore be especially careful if you +modify @code{ENVIRON["PATH"]"}, which is the search path for finding +executable programs. Some operating systems may not have environment variables. On such systems, the @code{ENVIRON} array is empty (except for @@ -13082,14 +13097,14 @@ it is not special. @cindex dark corner, @code{FILENAME} variable @item FILENAME The name of the file that @command{awk} is currently reading. -When no @value{DF}s are listed on the command line, @command{awk} reads +When no data files are listed on the command line, @command{awk} reads from the standard input and @code{FILENAME} is set to @code{"-"}. @code{FILENAME} is changed each time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} rule, the value of @code{FILENAME} is @code{""}, since there are no input files being processed yet.@footnote{Some early implementations of Unix @command{awk} initialized -@code{FILENAME} to @code{"-"}, even if there were @value{DF}s to be +@code{FILENAME} to @code{"-"}, even if there were data files to be processed. This behavior was incorrect and should not be relied upon in your programs.} @value{DARKCORNER} @@ -13129,8 +13144,12 @@ current record. @xref{Changing Fields}. @item FUNCTAB # An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. -@strong{NOTE}: You may not use the @code{delete} statement with the -@code{FUNCTAB} array. + +@quotation NOTE +Attempting to use the @code{delete} statement with the @code{FUNCTAB} +array will cause a fatal error. Any attempt to assign to an element of +the @code{FUNCTAB} array will also cause a fatal error. +@end quotation @cindex @code{NR} variable @item NR @@ -13462,11 +13481,11 @@ additional files to be read. If the value of @code{ARGC} is decreased, that eliminates input files from the end of the list. By recording the old value of @code{ARGC} elsewhere, a program can treat the eliminated arguments as -something other than @value{FN}s. +something other than file names. To eliminate a file from the middle of the list, store the null string (@code{""}) into @code{ARGV} in place of the file's name. As a -special feature, @command{awk} ignores @value{FN}s that have been +special feature, @command{awk} ignores file names that have been replaced with the null string. Another option is to use the @code{delete} statement to remove elements from @@ -13561,7 +13580,7 @@ same @command{awk} program. * Numeric Array Subscripts:: How to use numbers as subscripts in @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. -* Multi-dimensional:: Emulating multidimensional arrays in +* Multidimensional:: Emulating multidimensional arrays in @command{awk}. * Arrays of Arrays:: True multidimensional arrays. @end menu @@ -13591,8 +13610,8 @@ an array. @cindex Wall, Larry @quotation @i{Doing linear scans over an associative array is like trying to club someone -to death with a loaded Uzi.}@* -Larry Wall +to death with a loaded Uzi.} +@author Larry Wall @end quotation The @command{awk} language provides one-dimensional arrays @@ -14003,29 +14022,29 @@ Array elements are processed in arbitrary order, which is the default @command{awk} behavior. @item "@@ind_str_asc" -Order by indices compared as strings; this is the most basic sort. +Order by indices in ascending order compared as strings; this is the most basic sort. (Internally, array indices are always strings, so with @samp{a[2*5] = 1} the index is @code{"10"} rather than numeric 10.) @item "@@ind_num_asc" -Order by indices but force them to be treated as numbers in the process. +Order by indices in ascending order but force them to be treated as numbers in the process. Any index with a non-numeric value will end up positioned as if it were zero. @item "@@val_type_asc" -Order by element values rather than indices. +Order by element values in ascending order (rather than by indices). Ordering is by the type assigned to the element (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. (Subarrays have not been described yet; -@pxref{Arrays of Arrays}). +@pxref{Arrays of Arrays}.) @item "@@val_str_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as strings. Subarrays, if present, come out last. @item "@@val_num_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as numbers. Subarrays, if present, come out last. When numeric values are equal, the string values are used to provide an ordering: this guarantees consistent results across different @@ -14038,13 +14057,14 @@ across different environments.} which @command{gawk} uses internally to perform the sorting. @item "@@ind_str_desc" -Reverse order from the most basic sort. +String indices ordered from high to low. @item "@@ind_num_desc" Numeric indices ordered from high to low. @item "@@val_type_desc" -Element values, based on type, in descending order. +Element values, based on type, ordered from high to low. +Subarrays, if present, come out first. @item "@@val_str_desc" Element values, treated as strings, ordered from high to low. @@ -14354,11 +14374,11 @@ Even though it is somewhat unusual, the null string if @option{--lint} is provided on the command line (@pxref{Options}). -@node Multi-dimensional +@node Multidimensional @section Multidimensional Arrays @menu -* Multi-scanning:: Scanning multidimensional arrays. +* Multiscanning:: Scanning multidimensional arrays. @end menu @cindex subscripts in arrays, multidimensional @@ -14456,7 +14476,7 @@ the program produces the following output: 3 2 1 6 @end example -@node Multi-scanning +@node Multiscanning @subsection Scanning Multidimensional Arrays There is no special @code{for} statement for scanning a @@ -14901,15 +14921,16 @@ sequences of random numbers. @node String Functions @subsection String-Manipulation Functions -The functions in this @value{SECTION} look at or change the text of one or more -strings. -@code{gawk} understands locales (@pxref{Locales}), and does all string processing in terms of -@emph{characters}, not @emph{bytes}. This distinction is particularly important -to understand for locales where one character -may be represented by multiple bytes. Thus, for example, @code{length()} -returns the number of characters in a string, and not the number of bytes -used to represent those characters, Similarly, @code{index()} works with -character indices, and not byte indices. +The functions in this @value{SECTION} look at or change the text of one +or more strings. + +@code{gawk} understands locales (@pxref{Locales}), and does all +string processing in terms of @emph{characters}, not @emph{bytes}. +This distinction is particularly important to understand for locales +where one character may be represented by multiple bytes. Thus, for +example, @code{length()} returns the number of characters in a string, +and not the number of bytes used to represent those characters. Similarly, +@code{index()} works with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).} Several functions perform string substitution; the full discussion is @@ -14926,30 +14947,32 @@ pound sign@w{ (@samp{#}):} @table @code @item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@itemx asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@cindex @code{asorti()} function (@command{gawk}) @cindex arrays, elements, retrieving number of @cindex @code{asort()} function (@command{gawk}) @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable -Return the number of elements in the array @var{source}. -@command{gawk} sorts the contents of @var{source} -and replaces the indices -of the sorted values of @var{source} with sequential -integers starting with one. If the optional array @var{dest} is specified, -then @var{source} is duplicated into @var{dest}. @var{dest} is then -sorted, leaving the indices of @var{source} unchanged. The optional third -argument @var{how} is a string which controls the rule for comparing values, -and the sort direction. A single space is required between the -comparison mode, @samp{string} or @samp{number}, and the direction specification, -@samp{ascending} or @samp{descending}. You can omit direction and/or mode -in which case it will default to @samp{ascending} and @samp{string}, respectively. -An empty string "" is the same as the default @code{"ascending string"} -for the value of @var{how}. If the @samp{source} array contains subarrays as values, -they will come out last(first) in the @samp{dest} array for @samp{ascending}(@samp{descending}) -order specification. The value of @code{IGNORECASE} affects the sorting. -The third argument can also be a user-defined function name in which case -the value returned by the function is used to order the array elements -before constructing the result array. -@xref{Array Sorting Functions}, for more information. +These two functions are similar in behavior, so they are described +together. + +@quotation NOTE +The following description ignores the third argument, @var{how}, since it +requires understanding features that we have not discussed yet. Thus, +the discussion here is a deliberate simplification. (We do provide all +the details later on: @xref{Array Sorting Functions}, for the full story.) +@end quotation + +Both functions return the number of elements in the array @var{source}. +For @command{asort()}, @command{gawk} sorts the values of @var{source} +and replaces the indices of the sorted values of @var{source} with +sequential integers starting with one. If the optional array @var{dest} +is specified, then @var{source} is duplicated into @var{dest}. @var{dest} +is then sorted, leaving the indices of @var{source} unchanged. + +When comparing strings, @code{IGNORECASE} affects the sorting. If the +@var{source} array contains subarrays as values (@pxref{Arrays of +Arrays}), they will come last, after all scalar values. For example, if the contents of @code{a} are as follows: @@ -14975,29 +14998,19 @@ a[2] = "de" a[3] = "sac" @end example -In order to reverse the direction of the sorted results in the above example, -@code{asort()} can be called with three arguments as follows: +The @code{asorti()} function works similarly to @code{asort()}, however, +the @emph{indices} are sorted, instead of the values. Thus, in the +previous example, starting with the same initial set of indices and +values in @code{a}, calling @samp{asorti(a)} would yield: @example -asort(a, a, "descending") +a[1] = "first" +a[2] = "last" +a[3] = "middle" @end example -The @code{asort()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asort()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). - -@item asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # -@cindex @code{asorti()} function (@command{gawk}) -Return the number of elements in the array @var{source}. -It works similarly to @code{asort()}, however, the @emph{indices} -are sorted, instead of the values. (Here too, -@code{IGNORECASE} affects the sorting.) - -The @code{asorti()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asorti()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). +@code{asort()} and @code{asorti()} are @command{gawk} extensions; they +are not available in compatibility mode (@pxref{Options}). @item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) # @cindex @code{gensub()} function (@command{gawk}) @@ -15896,17 +15909,17 @@ _bigskip} The only case where the difference is noticeable is the last one: @samp{\\\\} is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. -Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules +Starting with version 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, it continued to follow the 1996 proposed rules, since that had been its behavior for many years. -When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer +When version 4.0.0 was released, the @command{gawk} maintainer made the POSIX rules the default, breaking well over a decade's worth of backwards compatibility.@footnote{This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules.} Needless to say, this was a bad idea, -and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical +and as of version 4.0.1, @command{gawk} resumed its historical behavior, and only follows the POSIX rules when @option{--posix} is given. The rules for @code{gensub()} are considerably simpler. At the runtime @@ -16140,7 +16153,7 @@ $ @kbd{awk '@{ print $1 + $2 @}'} @print{} 2 @kbd{2 3} @print{} 5 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @noindent @@ -16151,13 +16164,13 @@ with this example: $ @kbd{awk '@{ print $1 + $2 @}' | cat} @kbd{1 1} @kbd{2 3} -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @print{} 2 @print{} 5 @end example @noindent -Here, no output is printed until after the @kbd{@value{CTL}-d} is typed, because +Here, no output is printed until after the @kbd{Ctrl-d} is typed, because it is all buffered and sent down the pipe to @command{cat} in one shot. @end sidebar @@ -16614,8 +16627,8 @@ gawk 'BEGIN @{ @c STARTOFRANGE opbit @cindex operations, bitwise @quotation -@i{I can explain it for you, but I can't understand it for you.}@* -Anonymous +@i{I can explain it for you, but I can't understand it for you.} +@author Anonymous @end quotation Many languages provide the ability to perform @dfn{bitwise} operations @@ -16917,6 +16930,19 @@ that traverses every element of a true multidimensional array Return a true value if @var{x} is an array. Otherwise return false. @end table +@code{isarray()} is meant for use in two circumstances. The first is when +traversing a multidimensional array: you can test if an element is itself +an array or not. The second is inside the body of a user-defined function +(not discussed yet; @pxref{User-defined}), to test if a paramater is an +array or not. + +Note, however, that using @code{isarray()} at the global level to test +variables makes no sense. Since you are the one writing the program, you +are supposed to know if your variables are arrays or not. And in fact, +due to the way @command{gawk} works, if you pass the name of a variable +that has not been previously used to @code{isarray()}, @command{gawk} +will end up turning it into a scalar. + @node I18N Functions @subsection String-Translation Functions @cindex @command{gawk}, string-translation functions @@ -18041,9 +18067,9 @@ it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more manageable, and making programs more readable. -In their seminal 1976 book, @cite{Software Tools}@footnote{Sadly, over 35 +In their seminal 1976 book, @cite{Software Tools},@footnote{Sadly, over 35 years later, many of the lessons taught by this book have yet to be -learned by a vast number of practicing programmers.}, Brian Kernighan +learned by a vast number of practicing programmers.} Brian Kernighan and P.J.@: Plauger wrote: @quotation @@ -18242,6 +18268,7 @@ programming use. vice versa. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. +* Readfile Function:: A function to read an entire file at once. @end menu @node Strtonum Function @@ -18457,7 +18484,7 @@ An @code{END} rule is automatically added to the program calling @code{assert()}. Normally, if a program consists of just a @code{BEGIN} rule, the input files and/or standard input are not read. However, now that the program has an @code{END} rule, @command{awk} -attempts to read the input @value{DF}s or standard input +attempts to read the input data files or standard input (@pxref{Using BEGIN/END}), most likely causing the program to hang as it waits for input. @@ -18866,17 +18893,92 @@ A more general design for the @code{getlocaltime()} function would have allowed the user to supply an optional timestamp value to use instead of the current time. +@node Readfile Function +@subsection Reading A Whole File At Once + +Often, it is convenient to have the entire contents of a file available +in memory as a single string. A straightforward but naive way to +do that might be as follows: + +@example +function readfile(file, tmp, contents) +@{ + if ((getline tmp < file) < 0) + return + + contents = tmp + while (getline tmp < file) > 0) + contents = contents RT tmp + + close(file) + return contents +@} +@end example + +This function reads from @code{file} one record at a time, building +up the full contents of the file in the local variable @code{contents}. +It works, but is not necessarily efficient. + +The following function, based on a suggestion by Denis Shirokov, +reads the entire contents of the named file in one shot: + +@cindex @code{readfile()} user-defined function +@example +@c file eg/lib/readfile.awk +# readfile.awk --- read an entire file at once +@c endfile +@ignore +@c file eg/lib/readfile.awk +# +# Original idea by Denis Shirokov, cosmogen@@gmail.com, April 2013 +# +@c endfile +@end ignore +@c file eg/lib/readfile.awk + +function readfile(file, tmp, save_rs) +@{ + save_rs = RS + RS = "^$" + getline tmp < file + close(file) + RS = save_rs + + return tmp +@} +@c endfile +@end example + +It works by setting @code{RS} to @samp{^$}, a regular expression that +will never match if the file has contents. @command{gawk} reads data from +the file into @code{tmp} attempting to match @code{RS}. The match fails +after each read, but fails quickly, such that @command{gawk} fills +@code{tmp} with the entire contents of the file. +(@xref{Records}, for information on @code{RT} and @code{RS}.) + +In the case that @code{file} is empty, the return value is the null +string. Thus calling code may use something like: + +@example +contents = readfile("/some/path") +if (length(contents) == 0) + # file was empty @dots{} +@end example + +This tests the result to see if it is empty or not. An equivalent +test would be @samp{contents == ""}. + @node Data File Management -@section @value{DDF} Management +@section Data File Management @c STARTOFRANGE dataf @cindex files, managing @c STARTOFRANGE libfdataf -@cindex libraries of @command{awk} functions, managing, @value{DF}s +@cindex libraries of @command{awk} functions, managing, data files @c STARTOFRANGE flibdataf -@cindex functions, library, managing @value{DF}s +@cindex functions, library, managing data files This @value{SECTION} presents functions that are useful for managing -command-line @value{DF}s. +command-line data files. @menu * Filetrans Function:: A function for handling data file transitions. @@ -18887,16 +18989,16 @@ command-line @value{DF}s. @end menu @node Filetrans Function -@subsection Noting @value{DDF} Boundaries +@subsection Noting Data File Boundaries -@cindex files, managing, @value{DF} boundaries +@cindex files, managing, data file boundaries @cindex files, initialization and cleanup The @code{BEGIN} and @code{END} rules are each executed exactly once at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the -@code{BEGIN} rule is executed at the beginning of each @value{DF} and the -@code{END} rule is executed at the end of each @value{DF}. +@code{BEGIN} rule is executed at the beginning of each data file and the +@code{END} rule is executed at the end of each data file. When informed that this was not the case, the user requested that we add new special @@ -18907,7 +19009,7 @@ Adding these special patterns to @command{gawk} wasn't necessary; the job can be done cleanly in @command{awk} itself, as illustrated by the following library program. It arranges to call two user-supplied functions, @code{beginfile()} and -@code{endfile()}, at the beginning and end of each @value{DF}. +@code{endfile()}, at the beginning and end of each data file. Besides solving the problem in only nine(!) lines of code, it does so @emph{portably}; this works with any implementation of @command{awk}: @@ -18938,17 +19040,17 @@ This file must be loaded before the user's ``main'' program, so that the rule it supplies is executed first. This rule relies on @command{awk}'s @code{FILENAME} variable that -automatically changes for each new @value{DF}. The current @value{FN} is +automatically changes for each new data file. The current file name is saved in a private variable, @code{_oldfilename}. If @code{FILENAME} does -not equal @code{_oldfilename}, then a new @value{DF} is being processed and +not equal @code{_oldfilename}, then a new data file is being processed and it is necessary to call @code{endfile()} for the old file. Because @code{endfile()} should only be called if a file has been processed, the program first checks to make sure that @code{_oldfilename} is not the null -string. The program then assigns the current @value{FN} to +string. The program then assigns the current file name to @code{_oldfilename} and calls @code{beginfile()} for the file. Because, like all @command{awk} variables, @code{_oldfilename} is initialized to the null string, this rule executes correctly even for the -first @value{DF}. +first data file. The program also supplies an @code{END} rule to do the final processing for the last file. Because this @code{END} rule comes before any @code{END} rules @@ -18957,7 +19059,7 @@ again the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function -If the same @value{DF} occurs twice in a row on the command line, then +If the same data file occurs twice in a row on the command line, then @code{endfile()} and @code{beginfile()} are not executed at the end of the first pass and at the beginning of the second pass. The following version solves the problem: @@ -19072,12 +19174,12 @@ The @code{rewind()} function also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). @node File Checking -@subsection Checking for Readable @value{DDF}s +@subsection Checking for Readable Data Files -@cindex troubleshooting, readable @value{DF}s -@cindex readable @value{DF}s@comma{} checking +@cindex troubleshooting, readable data files +@cindex readable data files@comma{} checking @cindex files, skipping -Normally, if you give @command{awk} a @value{DF} that isn't readable, +Normally, if you give @command{awk} a data file that isn't readable, it stops with a fatal error. There are times when you might want to just ignore such files and keep going. You can do this by prepending the following program to your @command{awk} @@ -19126,15 +19228,15 @@ This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an end of file indication, closes the file, and proceeds on to the next -command-line @value{DF}, @emph{without} executing any user-level +command-line data file, @emph{without} executing any user-level @command{awk} program code. Using @command{gawk}'s @code{ARGIND} variable (@pxref{Built-in Variables}), it is possible to detect when an empty -@value{DF} has been skipped. Similar to the library file presented +data file has been skipped. Similar to the library file presented in @ref{Filetrans Function}, the following library file calls a function named @code{zerofile()} that the user must provide. The arguments passed are -the @value{FN} and the position in @code{ARGV} where it was found: +the file name and the position in @code{ARGV} where it was found: @cindex @code{zerofile.awk} program @example @@ -19222,15 +19324,15 @@ END @{ @end ignore @node Ignoring Assigns -@subsection Treating Assignments as @value{FFN}s +@subsection Treating Assignments as File Names @cindex assignments as filenames @cindex filenames, assignments as Occasionally, you might not want @command{awk} to process command-line variable assignments (@pxref{Assignment Options}). -In particular, if you have a @value{FN} that contain an @samp{=} character, -@command{awk} treats the @value{FN} as an assignment, and does not process it. +In particular, if you have a file name that contain an @samp{=} character, +@command{awk} treats the file name as an assignment, and does not process it. Some users have suggested an additional command-line option for @command{gawk} to disable command-line assignments. However, some simple programming with @@ -19274,7 +19376,7 @@ awk -v No_command_assign=1 -f noassign.awk -f yourprog.awk * The function works by looping through the arguments. It prepends @samp{./} to any argument that matches the form -of a variable assignment, turning that argument into a @value{FN}. +of a variable assignment, turning that argument into a file name. The use of @code{No_command_assign} allows you to disable command-line assignments at invocation time, by giving the variable a true value. @@ -19441,7 +19543,7 @@ The discussion that follows walks through the code a bit at a time: # <c> a character representing the current option # Private Data: -# _opti -- index in multi-flag option, e.g., -abc +# _opti -- index in multiflag option, e.g., -abc @c endfile @end example @@ -19633,7 +19735,7 @@ After @code{getopt()} is through, it is the responsibility of the user level code to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options -as @value{FN}s. +as file names. @end quotation Several of the sample programs presented in @@ -20507,7 +20609,7 @@ awk -f @var{program} -- @var{options} @var{files} @noindent Here, @var{program} is the name of the @command{awk} program (such as @file{cut.awk}), @var{options} are any command-line options for the -program that start with a @samp{-}, and @var{files} are the actual @value{DF}s. +program that start with a @samp{-}, and @var{files} are the actual data files. If your system supports the @samp{#!} executable interpreter mechanism (@pxref{Executable Scripts}), @@ -20712,7 +20814,7 @@ spaces. Also remember that after @code{getopt()} is through we have to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options -as @value{FN}s. +as file names. After dealing with the command-line options, the program verifies that the options make sense. Only one or the other of @option{-c} and @option{-f} @@ -20908,8 +21010,8 @@ egrep @r{[} @var{options} @r{]} '@var{pattern}' @var{files} @dots{} The @var{pattern} is a regular expression. In typical usage, the regular expression is quoted to prevent the shell from expanding any of the -special characters as @value{FN} wildcards. Normally, @command{egrep} -prints the lines that matched. If multiple @value{FN}s are provided on +special characters as file name wildcards. Normally, @command{egrep} +prints the lines that matched. If multiple file names are provided on the command line, each output line is preceded by the name of the file and a colon. @@ -21000,7 +21102,7 @@ pattern is supplied with @option{-e}, the first nonoption on the command line is used. The @command{awk} command-line arguments up to @code{ARGV[Optind]} are cleared, so that @command{awk} won't try to process them as files. If no files are specified, the standard input is used, and if multiple files are -specified, we make sure to note this so that the @value{FN}s can precede the +specified, we make sure to note this so that the file names can precede the matched lines in the output: @example @@ -21098,9 +21200,9 @@ A number of additional tests are made, but they are only done if we are not counting lines. First, if the user only wants exit status (@code{no_print} is true), then it is enough to know that @emph{one} line in this file matched, and we can skip on to the next file with -@code{nextfile}. Similarly, if we are only printing @value{FN}s, we can -print the @value{FN}, and then skip to the next file with @code{nextfile}. -Finally, each line is printed, with a leading @value{FN} and colon +@code{nextfile}. Similarly, if we are only printing file names, we can +print the file name, and then skip to the next file with @code{nextfile}. +Finally, each line is printed, with a leading file name and colon if necessary: @cindex @code{!} (exclamation point), @code{!} operator @@ -21348,7 +21450,7 @@ number of lines in each file, supply a number on the command line preceded with a minus; e.g., @samp{-500} for files with 500 lines in them instead of 1000. To change the name of the output files to something like @file{myfileaa}, @file{myfileab}, and so on, supply an additional -argument that specifies the @value{FN} prefix. +argument that specifies the file name prefix. Here is a version of @command{split} in @command{awk}. It uses the @code{ord()} and @code{chr()} functions presented in @@ -21358,8 +21460,8 @@ The program first sets its defaults, and then tests to make sure there are not too many arguments. It then looks at each argument in turn. The first argument could be a minus sign followed by a number. If it is, this happens to look like a negative number, so it is made positive, and that is the -count of lines. The data @value{FN} is skipped over and the final argument -is used as the prefix for the output @value{FN}s: +count of lines. The data file name is skipped over and the final argument +is used as the prefix for the output file names: @cindex @code{split.awk} program @example @@ -21408,7 +21510,7 @@ BEGIN @{ The next rule does most of the work. @code{tcount} (temporary count) tracks how many lines have been printed to the output file so far. If it is greater than @code{count}, it is time to close the current file and start a new one. -@code{s1} and @code{s2} track the current suffixes for the @value{FN}. If +@code{s1} and @code{s2} track the current suffixes for the file name. If they are both @samp{z}, the file is just too big. Otherwise, @code{s1} moves to the next letter in the alphabet and @code{s2} starts over again at @samp{a}: @@ -21496,13 +21598,13 @@ The @code{BEGIN} rule first makes a copy of all the command-line arguments into an array named @code{copy}. @code{ARGV[0]} is not copied, since it is not needed. @code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to -process each @value{FN} in @code{ARGV} as input data. +process each file name in @code{ARGV} as input data. @cindex flag variables If the first argument is @option{-a}, then the flag variable @code{append} is set to true, and both @code{ARGV[1]} and @code{copy[1]} are deleted. If @code{ARGC} is less than two, then no -@value{FN}s were supplied and @code{tee} prints a usage message and exits. +file names were supplied and @code{tee} prints a usage message and exits. Finally, @command{awk} is forced to read the standard input by setting @code{ARGV[1]} to @code{"-"} and @code{ARGC} to two: @@ -21964,7 +22066,7 @@ BEGIN @{ @end example The @code{beginfile()} function is simple; it just resets the counts of lines, -words, and characters to zero, and saves the current @value{FN} in +words, and characters to zero, and saves the current file name in @code{fname}: @example @@ -21986,7 +22088,7 @@ you will see that @code{FNR} has already been reset by the time @code{endfile()} is called.} It then prints out those numbers for the file that was just read. It relies on @code{beginfile()} to reset the -numbers for the following @value{DF}: +numbers for the following data file: @c FIXME: ONE DAY: make the above footnote an exercise, @c instead of giving away the answer. @@ -22154,8 +22256,8 @@ word, comparing it to the previous one: @cindex insomnia, cure for @cindex Robbins, Arnold @quotation -@i{Nothing cures insomnia like a ringing alarm clock.}@* -Arnold Robbins +@i{Nothing cures insomnia like a ringing alarm clock.} +@author Arnold Robbins @end quotation @c STARTOFRANGE tialarm @@ -22331,12 +22433,10 @@ often used to map uppercase letters into lowercase for further processing: @command{tr} requires two lists of characters.@footnote{On some older systems, -@ifset ORA including Solaris, -@end ifset @command{tr} may require that the lists be written as range expressions enclosed in square brackets (@samp{[a-z]}) and quoted, -to prevent the shell from attempting a @value{FN} expansion. This is +to prevent the shell from attempting a file name expansion. This is not a feature.} When processing the input, the first character in the first list is replaced with the first character in the second list, the second character in the first list is replaced with the second @@ -22734,7 +22834,7 @@ The @command{uniq} program (@pxref{Uniq Program}), removes duplicate lines from @emph{sorted} data. -Suppose, however, you need to remove duplicate lines from a @value{DF} but +Suppose, however, you need to remove duplicate lines from a data file but that you want to preserve the order the lines are in. A good example of this might be a shell history file. The history file keeps a copy of all the commands you have entered, and it is not unusual to repeat a command @@ -22870,7 +22970,7 @@ Lines containing @samp{@@group} and @samp{@@end group} are simply removed. (@pxref{Join Function}). The example programs in the online Texinfo source for @cite{@value{TITLE}} -(@file{gawk.texi}) have all been bracketed inside @samp{file} and +(@file{gawktexi.in}) have all been bracketed inside @samp{file} and @samp{endfile} lines. The @command{gawk} distribution uses a copy of @file{extract.awk} to extract the sample programs and install many of them in a standard directory where @command{gawk} can find them. @@ -22953,7 +23053,7 @@ screen. @end ifnottex The second rule handles moving data into files. It verifies that a -@value{FN} is given in the directive. If the file named is not the +file name is given in the directive. If the file named is not the current file, then the current file is closed. Keeping the current file open until a new file is encountered allows the use of the @samp{>} redirection for printing the contents, keeping open file management @@ -23035,7 +23135,7 @@ subsequent output is appended to the file (@pxref{Redirection}). This makes it easy to mix program text and explanatory prose for the same sample source file (as has been done here!) without any hassle. The file is -only closed when a new data @value{FN} is encountered or at the end of the +only closed when a new data file name is encountered or at the end of the input file. Finally, the function @code{@w{unexpected_eof()}} prints an appropriate @@ -23087,7 +23187,7 @@ Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp The following program, @file{awksed.awk}, accepts at least two command-line arguments: the pattern to look for and the text to replace it with. Any -additional arguments are treated as data @value{FN}s to process. If none +additional arguments are treated as data file names to process. If none are provided, the standard input is used: @cindex Brennan, Michael @@ -23160,7 +23260,7 @@ The @code{BEGIN} rule handles the setup, checking for the right number of arguments and calling @code{usage()} if there is a problem. Then it sets @code{RS} and @code{ORS} from the command-line arguments and sets @code{ARGV[1]} and @code{ARGV[2]} to the null string, so that they are -not treated as @value{FN}s +not treated as file names (@pxref{ARGC and ARGV}). The @code{usage()} function prints an error message and exits. @@ -23258,7 +23358,7 @@ Literal text, provided with @option{--source} or @option{--source=}. This text is just appended directly. @item -Source @value{FN}s, provided with @option{-f}. We use a neat trick and append +Source file names, provided with @option{-f}. We use a neat trick and append @samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion program works the way @command{gawk} does, this gets the text of the file included into the program at the correct point. @@ -23271,7 +23371,7 @@ shell variable. @item Run the expanded program with @command{gawk} and any other original command-line -arguments that the user supplied (such as the data @value{FN}s). +arguments that the user supplied (such as the data file names). @end enumerate This program uses shell variables extensively: for storing command-line arguments, @@ -23302,7 +23402,7 @@ programming trick. Don't worry about it if you are not familiar with These are saved and passed on to @command{gawk}. @item -f@r{,} --file@r{,} --file=@r{,} -Wfile= -The @value{FN} is appended to the shell variable @code{program} with an +The file name is appended to the shell variable @code{program} with an @samp{@@include} statement. The @command{expr} utility is used to remove the leading option part of the argument (e.g., @samp{--file=}). @@ -23426,10 +23526,10 @@ is stored in the shell variable @code{expand_prog}. Doing this keeps the shell script readable. The @command{awk} program reads through the user's program, one line at a time, using @code{getline} (@pxref{Getline}). The input -@value{FN}s and @samp{@@include} statements are managed using a stack. -As each @samp{@@include} is encountered, the current @value{FN} is +file names and @samp{@@include} statements are managed using a stack. +As each @samp{@@include} is encountered, the current file name is ``pushed'' onto the stack and the file named in the @samp{@@include} -directive becomes the current @value{FN}. As each file is finished, +directive becomes the current file name. As each file is finished, the stack is ``popped,'' and the previous input file becomes the current input file again. The process is started by making the original file the first one on the stack. @@ -23438,16 +23538,16 @@ The @code{pathto()} function does the work of finding the full path to a file. It simulates @command{gawk}'s behavior when searching the @env{AWKPATH} environment variable (@pxref{AWKPATH Variable}). -If a @value{FN} has a @samp{/} in it, no path search is done. -Similarly, if the @value{FN} is @code{"-"}, then that string is +If a file name has a @samp{/} in it, no path search is done. +Similarly, if the file name is @code{"-"}, then that string is used as-is. Otherwise, -the @value{FN} is concatenated with the name of each directory in -the path, and an attempt is made to open the generated @value{FN}. +the file name is concatenated with the name of each directory in +the path, and an attempt is made to open the generated file name. The only way to test if a file can be read in @command{awk} is to go ahead and try to read it with @code{getline}; this is what @code{pathto()} does.@footnote{On some very old versions of @command{awk}, the test @samp{getline junk < t} can loop forever if the file exists but is empty. -Caveat emptor.} If the file can be read, it is closed and the @value{FN} +Caveat emptor.} If the file can be read, it is closed and the file name is returned: @ignore @@ -23505,14 +23605,14 @@ BEGIN @{ The stack is initialized with @code{ARGV[1]}, which will be @file{/dev/stdin}. The main loop comes next. Input lines are read in succession. Lines that do not start with @samp{@@include} are printed verbatim. -If the line does start with @samp{@@include}, the @value{FN} is in @code{$2}. +If the line does start with @samp{@@include}, the file name is in @code{$2}. @code{pathto()} is called to generate the full path. If it cannot, then the program prints an error message and continues. The next thing to check is if the file is included already. The -@code{processed} array is indexed by the full @value{FN} of each included +@code{processed} array is indexed by the full file name of each included file and it tracks this information for us. If the file is -seen again, a warning message is printed. Otherwise, the new @value{FN} is +seen again, a warning message is printed. Otherwise, the new file name is pushed onto the stack and processing continues. Finally, when @code{getline} encounters the end of the input file, the file @@ -23590,10 +23690,10 @@ options and command-line arguments that the user supplied. @c this causes more problems than it solves, so leave it out. @ignore -The special file @file{/dev/null} is passed as a @value{DF} to @command{gawk} +The special file @file{/dev/null} is passed as a data file to @command{gawk} to handle an interesting case. Suppose that the user's program only has -a @code{BEGIN} rule and there are no @value{DF}s to read. -The program should exit without reading any @value{DF}s. +a @code{BEGIN} rule and there are no data files to read. +The program should exit without reading any data files. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the @@ -23974,8 +24074,8 @@ who knows where you live." @end ignore @quotation @i{Write documentation as if whoever reads it is -a violent psychopath who knows where you live.}@* -Steve English, as quoted by Peter Langston +a violent psychopath who knows where you live.} +@author Steve English, as quoted by Peter Langston @end quotation This @value{CHAPTER} discusses advanced features in @command{gawk}. @@ -24294,7 +24394,7 @@ ordered data: @example function cmp_randomize(i1, v1, i2, v2) @{ - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) @} @end example @@ -24309,7 +24409,7 @@ with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, so consider it only if necessary. The following comparison functions force a deterministic order, and are based on the fact that the -indices of two elements are never equal: +(string) indices of two elements are never equal: @example function cmp_numeric(i1, v1, i2, v2) @@ -24368,15 +24468,14 @@ sorted array traversal is not the default. @cindex arrays, sorting @cindex @code{asort()} function (@command{gawk}) @cindex @code{asort()} function (@command{gawk}), arrays@comma{} sorting +@cindex @code{asorti()} function (@command{gawk}) +@cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting -In most @command{awk} implementations, sorting an array requires -writing a @code{sort()} function. -While this can be educational for exploring different sorting algorithms, -usually that's not the point of the program. -@command{gawk} provides the built-in @code{asort()} -and @code{asorti()} functions -(@pxref{String Functions}) -for sorting arrays. For example: +In most @command{awk} implementations, sorting an array requires writing +a @code{sort()} function. While this can be educational for exploring +different sorting algorithms, usually that's not the point of the program. +@command{gawk} provides the built-in @code{asort()} and @code{asorti()} +functions (@pxref{String Functions}) for sorting arrays. For example: @example @var{populate the array} data @@ -24389,7 +24488,7 @@ After the call to @code{asort()}, the array @code{data} is indexed from 1 to some number @var{n}, the total number of elements in @code{data}. (This count is @code{asort()}'s return value.) @code{data[1]} @value{LEQ} @code{data[2]} @value{LEQ} @code{data[3]}, and so on. -The comparison is based on the type of the elements +The default comparison is based on the type of the elements (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. @@ -24411,24 +24510,11 @@ In this case, @command{gawk} copies the @code{source} array into the @code{dest} array and then sorts @code{dest}, destroying its indices. However, the @code{source} array is not affected. -@code{asort()} accepts a third string argument to control comparison of -array elements. As with @code{PROCINFO["sorted_in"]}, this argument -may be one of the predefined names that @command{gawk} provides -(@pxref{Controlling Scanning}), or the name of a user-defined function -(@pxref{Controlling Array Traversal}). - -@quotation NOTE -In all cases, the sorted element values consist of the original -array's element values. The ability to control comparison merely -affects the way in which they are sorted. -@end quotation - Often, what's needed is to sort on the values of the @emph{indices} -instead of the values of the elements. -To do that, use the -@code{asorti()} function. The interface is identical to that of -@code{asort()}, except that the index values are used for sorting, and -become the values of the result array: +instead of the values of the elements. To do that, use the +@code{asorti()} function. The interface and behavior are identical to +that of @code{asort()}, except that the index values are used for sorting, +and become the values of the result array: @example @{ source[$0] = some_func($0) @} @@ -24445,23 +24531,35 @@ END @{ @} @end example -Similar to @code{asort()}, -in all cases, the sorted element values consist of the original -array's indices. The ability to control comparison merely -affects the way in which they are sorted. +So far, so good. Now it starts to get interesting. Both @code{asort()} +and @code{asorti()} accept a third string argument to control comparison +of array elements. In @ref{String Functions}, we ignored this third +argument; however, the time has now come to describe how this argument +affects these two functions. + +Basically, the third argument specifies how the array is to be sorted. +There are two possibilities. As with @code{PROCINFO["sorted_in"]}, +this argument may be one of the predefined names that @command{gawk} +provides (@pxref{Controlling Scanning}), or it may be the name of a +user-defined function (@pxref{Controlling Array Traversal}). + +In the latter case, @emph{the function can compare elements in any way +it chooses}, taking into account just the indices, just the values, +or both. This is extremely powerful. -Sorting the array by replacing the indices provides maximal flexibility. -To traverse the elements in decreasing order, use a loop that goes from -@var{n} down to 1, either over the elements or over the indices.@footnote{You -may also use one of the predefined sorting names that sorts in -decreasing order.} +Once the array is sorted, @code{asort()} takes the @emph{values} in +their final order, and uses them to fill in the result array, whereas +@code{asorti()} takes the @emph{indices} in their final order, and uses +them to fill in the result array. @cindex reference counting, sorting arrays +@quotation NOTE Copying array indices and elements isn't expensive in terms of memory. Internally, @command{gawk} maintains @dfn{reference counts} to data. For example, when @code{asort()} copies the first array to the second one, there is only one copy of the original array elements' data, even though both arrays use the values. +@end quotation @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in @@ -24687,10 +24785,10 @@ another process on another system across an IP network connection. You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is -by recognizing special @value{FN}s that begin with one of @samp{/inet/}, +by recognizing special file names that begin with one of @samp{/inet/}, @samp{/inet4/} or @samp{/inet6}. -The full syntax of the special @value{FN} is +The full syntax of the special file name is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. The components are: @@ -25059,8 +25157,8 @@ the case of the @code{INT} signal, @command{gawk} exits. This is because these systems don't support the @command{kill} command, so the only signals you can deliver to a program are those generated by the keyboard. The @code{INT} signal is generated by the -@kbd{@value{CTL}-@key{C}} or @kbd{@value{CTL}-@key{BREAK}} key, while the -@code{QUIT} signal is generated by the @kbd{@value{CTL}-@key{\}} key. +@kbd{Ctrl-@key{C}} or @kbd{Ctrl-@key{BREAK}} key, while the +@code{QUIT} signal is generated by the @kbd{Ctrl-@key{\}} key. Finally, @command{gawk} also accepts another option, @option{--pretty-print}. When called this way, @command{gawk} ``pretty prints'' the program into @@ -25852,7 +25950,7 @@ complete detail in @cite{GNU gettext tools}.) @end ifnotinfo As of this writing, the latest version of GNU @code{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz, @value{PVERSION} 0.18.2.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz, version 0.18.2.1}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -26732,7 +26830,7 @@ functions which called the one you are in. The commands for doing this are: Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each -function, the source @value{FN}, and the line number. +function, the source file name, and the line number. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -26865,7 +26963,7 @@ Turn instruction tracing on or off. The default is @code{off}. @end table @item @code{save} @var{filename} -Save the commands from the current session to the given @value{FN}, +Save the commands from the current session to the given file name, so that they can be replayed using the @command{source} command. @item @code{source} @var{filename} @@ -27033,8 +27131,8 @@ features. The following types of completion are available: @item Command completion Command names. -@item Source @value{FN} completion -Source @value{FN}s. Relevant commands are +@item Source file name completion +Source file names. Relevant commands are @code{break}, @code{clear}, @code{list}, @@ -27122,11 +27220,11 @@ to believe. Novice computer users solve this problem by implicitly trusting in the computer as an infallible authority; they tend to believe that all digits of a printed answer are significant. Disillusioned computer users have just the opposite approach; they are constantly afraid that their answers -are almost meaningless.}@* -Donald Knuth@footnote{Donald E.@: Knuth. +are almost meaningless.}@footnote{Donald E.@: Knuth. @cite{The Art of Computer Programming}. Volume 2, @cite{Seminumerical Algorithms}, third edition, 1998, ISBN 0-201-89683-4, p.@: 229.} +@author Donald Knuth @end quotation This @value{CHAPTER} discusses issues that you may encounter @@ -27264,7 +27362,7 @@ This makes it clear that the full numeric value is different from what the default string representations show. @code{CONVFMT}'s default value is @code{"%.6g"}, which yields a value with -at least six significant digits. For some applications, you might want to +at most six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, most of the time, 17 digits is enough to capture a floating-point number's @@ -27293,7 +27391,7 @@ $ @kbd{awk '@{ printf("%010d\n", $1 * 100) @}'} @print{} 0000051580 515.82 @print{} 0000051582 -@kbd{@value{CTL}-d} +@kbd{Ctrl-d} @end example @noindent @@ -28133,11 +28231,10 @@ floating-point format to a precision lower than working precision. Do we promote them to full membership of the high-precision club, or do we treat them and all their associates as second-class citizens? Sometimes the first course is proper, sometimes the second, and it takes -careful analysis to tell which.} - -Dirk Laurie@footnote{Dirk Laurie. +careful analysis to tell which.}@footnote{Dirk Laurie. @cite{Variable-precision Arithmetic Considered Perilous --- A Detective Story}. Electronic Transactions on Numerical Analysis. Volume 28, pp. 168-173, 2008.} +@author Dirk Laurie @end quotation @command{gawk} does not implicitly modify the precision of any previously @@ -28675,12 +28772,12 @@ the macros as if they were functions. @subsection General Purpose Data Types @quotation -@i{I have a true love/hate relationship with unions.}@* -Arnold Robbins +@i{I have a true love/hate relationship with unions.} +@author Arnold Robbins @i{That's the thing about unions: the compiler will arrange things so they -can accommodate both love and hate.}@* -Chet Ramey +can accommodate both love and hate.} +@author Chet Ramey @end quotation The extension API defines a number of simple types and structures for general @@ -30613,8 +30710,8 @@ path with a list of directories to search for compiled extensions. @section Example: Some File Functions @quotation -@i{No matter where you go, there you are.} @* -Buckaroo Bonzai +@i{No matter where you go, there you are.} +@author Buckaroo Bonzai @end quotation @c It's enough to show chdir and stat, no need for fts @@ -31397,7 +31494,7 @@ Return zero if there were no errors, otherwise return @minus{}1. The @code{fts()} function provides a hook to the C library @code{fts()} routines for traversing file hierarchies. Instead of returning data -about one file at a time in a stream, it fills in a multi-dimensional +about one file at a time in a stream, it fills in a multidimensional array with data about each file and directory encountered in the requested hierarchies. @@ -31498,7 +31595,7 @@ be 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 -creating a multi-dimensional array to represent the file hierarchy and +creating a multidimensional array to represent the file hierarchy and its information. @end quotation @@ -32156,7 +32253,7 @@ Multiple @code{BEGIN} and @code{END} rules @item Multidimensional arrays -(@pxref{Multi-dimensional}). +(@pxref{Multidimensional}). @end itemize @c ENDOFRANGE gawkv1 @@ -32363,7 +32460,7 @@ Special files in I/O redirections: @itemize @minus{} @item The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and -@file{/dev/fd/@var{N}} special @value{FN}s +@file{/dev/fd/@var{N}} special file names (@pxref{Special Files}). @item @@ -32587,7 +32684,7 @@ long options @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} @value{PVERSION} 4.0: +and the documentation for @command{gawk} version 4.0: @c nested table @itemize @minus @@ -32770,8 +32867,8 @@ cases: the default regexp matching; with @option{--traditional}, and with @appendixsec Major Contributors to @command{gawk} @cindex @command{gawk}, list of contributors to @quotation -@i{Always give credit where credit is due.}@* -Anonymous +@i{Always give credit where credit is due.} +@author Anonymous @end quotation This @value{SECTION} names the major contributors to @command{gawk} @@ -32968,6 +33065,10 @@ The modifications to convert @command{gawk} into a byte-code interpreter, including the debugger. @item +The addition of true multidimensional arrays. +@ref{Arrays of Arrays}. + +@item The additional modifications for support of arbitrary precision arithmetic. @item @@ -32980,6 +33081,10 @@ into one, for the 4.1 release. @item Improved array internals for arrays indexed by integers. + +@item +The improved array sorting features were driven by John together +with Pat Rankin. @end itemize @item @@ -33101,7 +33206,7 @@ Extracting the archive creates a directory named @file{gawk-@value{VERSION}.@value{PATCHLEVEL}} in the current directory. -The distribution @value{FN} is of the form +The distribution file name is of the form @file{gawk-@var{V}.@var{R}.@var{P}.tar.gz}. The @var{V} represents the major version of @command{gawk}, the @var{R} represents the current release of version @var{V}, and @@ -33133,6 +33238,13 @@ The actual @command{gawk} source code. @end table @table @file +@item ABOUT-NLS +Information about GNU @command{gettext} and translations. + +@item AUTHORS +A file with some information about the authorship of @command{gawk}. +It exists only to satisfy the pedants at the Free Software Foundation. + @item README @itemx README_d/README.* Descriptive files: @file{README} for @command{gawk} under Unix and the @@ -33156,16 +33268,6 @@ An older list of changes to @command{gawk}. @item COPYING The GNU General Public License. -@item FUTURES -A brief list of features and changes being contemplated for future -releases, with some indication of the time frame for the feature, based -on its difficulty. - -@item LIMITATIONS -A list of those factors that limit @command{gawk}'s performance. -Most of these depend on the hardware or operating system software and -are not limits in @command{gawk} itself. - @item POSIX.STD A description of behaviors in the POSIX standard for @command{awk} which are left undefined, or where @command{gawk} may not comply fully, as well @@ -33198,12 +33300,19 @@ The @command{troff} source for a manual page describing @command{gawk}. This is distributed for the convenience of Unix users. @cindex Texinfo -@item doc/gawk.texi +@item doc/gawktexi.in +@itemx doc/sidebar.awk The Texinfo source file for this @value{DOCUMENT}. -It should be processed with @TeX{} -(via @command{texi2dvi} or @command{texi2pdf}) +It should be processed by @file{doc/sidebar.awk} +before processing with @command{texi2dvi} or @command{texi2pdf} to produce a printed document, and with @command{makeinfo} to produce an Info or HTML file. +The @file{Makefile} takes care of this processing and produces +printable output via @command{texi2dvi} or @command{texi2pdf}. + +@item doc/gawk.texi +The file produced after processing @file{gawktexi.in} +with @file{sidebar.awk}. @item doc/gawk.info The generated Info file for this @value{DOCUMENT}. @@ -33242,15 +33351,21 @@ the @file{Makefile.in} files used by @command{autoconf} and @item Makefile.in @itemx aclocal.m4 +@itemx bisonfix.awk +@itemx config.guess @itemx configh.in @itemx configure.ac @itemx configure @itemx custom.h +@itemx depcomp +@itemx install-sh @itemx missing_d/* +@itemx mkinstalldirs @itemx m4/* -These files and subdirectories are used when configuring @command{gawk} -for various Unix systems. They are explained in -@ref{Unix Installation}. +These files and subdirectories are used when configuring and compiling +@command{gawk} for various Unix systems. Most of them are explained +in @ref{Unix Installation}. The rest are there to support the main +infrastructure. @item po/* The @file{po} library contains message translations. @@ -33394,6 +33509,14 @@ command line when compiling @command{gawk} from scratch, including: @table @code +@cindex @code{--disable-extensions} configuration option +@cindex configuration option, @code{--disable-extensions} +@item --disable-extensions +Disable configuring and building the sample extensions in the +@file{extension} directory. This is useful for cross-compiling. +The default action is to dynamically check if the extensions +can be configured and compiled. + @cindex @code{--disable-lint} configuration option @cindex configuration option, @code{--disable-lint} @item --disable-lint @@ -33953,7 +34076,7 @@ provides information about both the @command{gawk} implementation and the The logical name @samp{AWK_LIBRARY} can designate a default location for @command{awk} program files. For the @option{-f} option, if the specified -@value{FN} has no device or directory path information in it, @command{gawk} +file name has no device or directory path information in it, @command{gawk} looks in the current directory first, then in the directory specified by the translation of @samp{AWK_LIBRARY} if the file is not found. If, after searching in both directories, the file still is not found, @@ -33986,7 +34109,7 @@ One side effect of dual command-line parsing is that if there is only a single parameter (as in the quoted string program above), the command becomes ambiguous. To work around this, the normally optional @option{--} flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any -other dash-type options (or multiple parameters such as @value{DF}s to +other dash-type options (or multiple parameters such as data files to process) are present, there is no ambiguity and @option{--} can be omitted. @c @cindex directory search @@ -34047,7 +34170,7 @@ define a symbol, as follows: $ @kbd{gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe} @end example -This is apparently @value{PVERSION} 2.15.6, which is extremely old. We +This is apparently version 2.15.6, which is extremely old. We recommend compiling and using the current version. @c ENDOFRANGE opgawx @@ -34057,8 +34180,8 @@ recommend compiling and using the current version. @appendixsec Reporting Problems and Bugs @cindex archeologists @quotation -@i{There is nothing more dangerous than a bored archeologist.}@* -The Hitchhiker's Guide to the Galaxy +@i{There is nothing more dangerous than a bored archeologist.} +@author The Hitchhiker's Guide to the Galaxy @end quotation @c the radio show, not the book. :-) @@ -34076,8 +34199,8 @@ what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it -to the smallest possible @command{awk} program and input @value{DF} that -reproduces the problem. Then send us the program and @value{DF}, +to the smallest possible @command{awk} program and input data file that +reproduces the problem. Then send us the program and data file, some idea of what kind of Unix system you're using, the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps @@ -34174,8 +34297,8 @@ Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) @cindex Brennan, Michael @quotation @i{It's kind of fun to put comments like this in your awk code.}@* -@ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course}@* -Michael Brennan +@ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course} +@author Michael Brennan @end quotation There are a number of other freely available @command{awk} implementations. @@ -34217,10 +34340,8 @@ repository in a directory named @file{bwkawk}. If you leave that argument off the @command{git} command line, the repository copy is created in a directory named @file{awk}. -This version requires an ISO C (1990 standard) compiler; -the C compiler from -GCC (the GNU Compiler Collection) -works quite nicely. +This version requires an ISO C (1990 standard) compiler; the C compiler +from GCC (the GNU Compiler Collection) works quite nicely. @xref{Common Extensions}, for a list of extensions in this @command{awk} that are not in POSIX @command{awk}. @@ -34301,15 +34422,22 @@ information, see the @uref{http://busybox.net, project's home page}. @cindex source code, Solaris @command{awk} @item The OpenSolaris POSIX @command{awk} The version of @command{awk} in @file{/usr/xpg4/bin} on Solaris is -more-or-less -POSIX-compliant. It is based on the @command{awk} from Mortice Kern -Systems for PCs. The source code can be downloaded from -the @uref{http://www.opensolaris.org, OpenSolaris web site}. +more-or-less POSIX-compliant. It is based on the @command{awk} from +Mortice Kern Systems for PCs. This author was able to make it compile and work under GNU/Linux with 1--2 hours of work. Making it more generally portable (using GNU Autoconf and/or Automake) would take more work, and this has not been done, at least to our knowledge. +@cindex Illumos +@cindex Illumos, POSIX-compliant @command{awk} +@cindex source code, Illumos @command{awk} +The source code used to be available from the OpenSolaris web site. +However, that project was ended and the web site shut down. Fortunately, the +@uref{http://wiki.illumos.org/display/illumos/illumos+Home, Illumos project} +makes this implementation available. You can view the files one at a time from +@uref{https://github.com/joyent/illumos-joyent/blob/master/usr/src/cmd/awk_xpg4}. + @cindex @command{jawk} @cindex Java implementation of @command{awk} @cindex source code, @command{jawk} @@ -34350,6 +34478,10 @@ under the GPL. It has a large number of extensions over standard See @uref{http://www.quiktrim.org/QTawk.html} for more information, including the manual and a download link. +@item Other Versions +See also the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, +Wikipedia article}, for information on additional versions. + @end table @c ENDOFRANGE gligawk @c ENDOFRANGE ingawk @@ -34960,11 +35092,11 @@ Larry @cindex Wall, Larry @cindex Robbins, Arnold @quotation -@i{AWK is a language similar to PERL, only considerably more elegant.}@* -Arnold Robbins +@i{AWK is a language similar to PERL, only considerably more elegant.} +@author Arnold Robbins -@i{Hey!}@* -Larry Wall +@i{Hey!} +@author Larry Wall @end quotation The @file{TODO} file in the @command{gawk} Git repository lists possible @@ -35096,7 +35228,7 @@ in order to loop over all the element in an easy fashion for C code. @item The ability to create arrays (including @command{gawk}'s true -multi-dimensional arrays). +multidimensional arrays). @end itemize @end itemize @@ -35229,11 +35361,11 @@ to any of the above. @ref{Dynamic Extensions}, describes the supported API and mechanisms for writing extensions for @command{gawk}. This API was introduced -in @value{PVERSION} 4.1. However, for many years @command{gawk} +in version 4.1. However, for many years @command{gawk} provided an extension mechanism that required knowledge of @command{gawk} internals and that was not as well designed. -In order to provide a transition period, @command{gawk} @value{PVERSION} +In order to provide a transition period, @command{gawk} version 4.1 continues to support the original extension mechanism. This will be true for the life of exactly one major release. This support will be withdrawn, and removed from the source code, at the next major @@ -36201,7 +36333,7 @@ numeric values. It is the C type @code{float}. The character generated by hitting the space bar on the keyboard. @item Special File -A @value{FN} interpreted internally by @command{gawk}, instead of being handed +A file name interpreted internally by @command{gawk}, instead of being handed directly to the underlying operating system---for example, @file{/dev/stderr}. (@xref{Special Files}.) @@ -37582,6 +37714,7 @@ Consistency issues: Use MS-Windows not MS Windows Use MS-DOS not MS-DOS Use an empty set of parentheses after built-in and awk function names. + Use "multiFOO" without a hyphen. Date: Wed, 13 Apr 94 15:20:52 -0400 From: rms@gnu.org (Richard Stallman) diff --git a/doc/texinfo.tex b/doc/texinfo.tex index a0c9d080..9cf29f2e 100644 --- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -3,7 +3,7 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2013-03-19.11} +\def\texinfoversion{2013-06-21.17} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, @@ -2475,14 +2475,14 @@ end } % We *must* turn on hyphenation at `-' and `_' in @code. +% (But see \codedashfinish below.) % Otherwise, it is too hard to avoid overfull hboxes % in the Emacs manual, the Library manual, etc. % % Unfortunately, TeX uses one parameter (\hyphenchar) to control % both hyphenation at - and hyphenation within words. % We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate at a dash. -% -- rms. +% and arrange explicitly to hyphenate at a dash. -- rms. { \catcode`\-=\active \catcode`\_=\active \catcode`\'=\active \catcode`\`=\active @@ -2499,14 +2499,33 @@ end \let-\normaldash \let_\realunder \fi + % Given -foo (with a single dash), we do not want to allow a break + % after the hyphen. + \global\let\codedashprev=\codedash + % \codex } + % + \gdef\codedash{\futurelet\next\codedashfinish} + \gdef\codedashfinish{% + \normaldash % always output the dash character itself. + % + % Now, output a discretionary to allow a line break, unless + % (a) the next character is a -, or + % (b) the preceding character is a -. + % E.g., given --posix, we do not want to allow a break after either -. + % Given --foo-bar, we do want to allow a break between the - and the b. + \ifx\next\codedash \else + \ifx\codedashprev\codedash + \else \discretionary{}{}{}\fi + \fi + \global\let\codedashprev=\next + } } - +\def\normaldash{-} +% \def\codex #1{\tclose{#1}\endgroup} -\def\normaldash{-} -\def\codedash{-\discretionary{}{}{}} \def\codeunder{% % this is all so @math{@code{var_name}+1} can work. In math mode, _ % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) |