diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/gawk.info | 1140 | ||||
| -rw-r--r-- | doc/gawk.texi | 222 |
2 files changed, 714 insertions, 648 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 70091258..fde25465 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -304,6 +304,8 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Scanning an Array:: A variation of the `for' statement. It loops through the indices of an array's existing elements. +* Controlling Scanning:: Controlling the order in which arrays + are scanned. * Delete:: The `delete' statement removes an element from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in @@ -9411,10 +9413,10 @@ with a pound sign (`#'). order in which array indices will be processed by `for (index in array) ...' loops. The value should contain one to three words; separate pairs of words by a single space. One word - controls sort direction, "ascending" or "descending;" another - controls the sort key, "index" or "value;" and the remaining + controls sort direction, `ascending' or `descending'; another + controls the sort key, `index' or `value'; and the remaining one, which is only valid for sorting by index, is comparison - mode, "string" or "number." When two or three words are + mode, `string' or `number'. When two or three words are present, they may be specified in any order, so `ascending index string' and `string ascending index' are equivalent. Also, each word may be truncated, so `asc index str' and `a i @@ -9423,17 +9425,18 @@ with a pound sign (`#'). letter each. You can omit direction and/or key type and/or comparison - mode. Provided that at least one is present, missing parts - of a sort specification default to `ascending', `index', and - (for indices only) `string', respectively. An empty string, - `""', is the same as `unsorted' and will cause `for (index in - array) ...' to process the indices in arbitrary order. - Another thing to note is that the array sorting takes place - at the time `for (... in ...)' is about to start executing, - so changing the value of `PROCINFO["sorted_in"]' during loop - execution does not have any effect on the order in which any - remaining array elements get processed. *Note Scanning an - Array::, for more information. + mode. Provided that at least one is present, the missing + parts of a sort specification default to `ascending', + `index', and (for indices only) `string', respectively. An + empty string, `""', is the same as `unsorted' and will cause + `for (index in array) ...' to process the indices in + arbitrary order. Another thing to note is that the array + sorting takes place at the time the `for' loop is about to + start executing, so changing the value of + `PROCINFO["sorted_in"]' during loop execution does not have + any effect on the order in which any remaining array elements + get processed. *Note Scanning an Array::, for more + information. `PROCINFO["strftime"]' The default time format string for `strftime()'. Assigning a @@ -9900,7 +9903,11 @@ File: gawk.info, Node: Scanning an Array, Prev: Array Example, Up: Array Basi 8.1.5 Scanning All Elements of an Array --------------------------------------- -In programs that use arrays, it is often necessary to use a loop that +* Menu: + +* Controlling Scanning:: Controlling the order in which arrays are scanned. + + In programs that use arrays, it is often necessary to use a loop that executes once for each element of an array. In other languages, where arrays are contiguous and indices are limited to positive integers, this is easy: all the valid indices can be found by counting from the @@ -9950,41 +9957,51 @@ statements in the loop body; it is not predictable whether the `for' loop will reach them. Similarly, changing VAR inside the loop may produce strange results. It is best to avoid such things. - As an extension, `gawk' makes it possible for you to loop over the + +File: gawk.info, Node: Controlling Scanning, Up: Scanning an Array + +8.1.5.1 Controlling Array Scanning Order +........................................ + +As an extension, `gawk' makes it possible for you to loop over the elements of an array in order, based on the value of `PROCINFO["sorted_in"]' (*note Auto-set::). Several sorting options are available: -`"ascending index string"' - Order by indices compared as strings, the most basic sort. +`ascending index string' + 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 actually `"10"' rather than numeric 10.) -`"ascending index number"' +`ascending index number' Order by indices but force them to be treated as numbers in the process. Any index with non-numeric value will end up positioned - as if it were 0. + as if it were zero. -`"ascending value"' +`ascending value' Order by element values rather than by indices. Comparisons are done as numeric when both values being compared are numeric, or - done as strings when either or both aren't numeric. Sub-arrays, - if present, come out last. + done as strings when either or both aren't numeric (*note Variable + Typing::). Subarrays, if present, come out last. -`"descending index string"' +`descending index string' Reverse order from the most basic sort. -`"descending index number"' +`descending index number' Numeric indices ordered from high to low. -`"descending value"' - Element values ordered from high to low. Sub-arrays, if present, +`descending value' + Element values ordered from high to low. Subarrays, if present, come out first. -`"unsorted"' +`unsorted' Array elements are processed in arbitrary order, the normal `awk' behavior. + The array traversal order is determined before the `for' loop starts +to run. Changing `PROCINFO["sorted_in"]' in the looop body will not +affect the loop. + Portions of the sort specification string may be truncated or omitted. The default is `ascending' for direction, `index' for sort key type, and (when sorting by index only) `string' for comparison mode. @@ -10008,31 +10025,31 @@ For example: -| 3 3 -| 4 4 - As a side note, sorting the array indices before traversing the -array has been reported to add 15% to 20% overhead to the execution -time of `awk' programs. For this reason, sorted array traversal is not -the default. - When sorting an array by element values, if a value happens to be a -sub-array then it is considered to be greater than any string or -numeric value, regardless of what the sub-array itself contains, and -all sub-arrays are treated as being equal to each other. Their order +subarray then it is considered to be greater than any string or numeric +value, regardless of what the subarray itself contains, and all +subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. - Sorting by array element values (for values other than sub-arrays) + Sorting by array element values (for values other than subarrays) always uses basic `awk' comparison mode: if both values happen to be numbers then they're compared as numbers, otherwise they're compared as strings. When string comparisons are made during a sort, either for element values where one or both aren't numbers or for element indices handled -as strings, the value of `IGNORECASE' controls whether the comparisons -treat corresponding upper and lower case letters as equivalent or -distinct. +as strings, the value of `IGNORECASE' (*note Built-in Variables::) +controls whether the comparisons treat corresponding upper and lower +case letters as equivalent or distinct. This sorting extension is disabled in POSIX mode, since the `PROCINFO' array is not special in that case. + As a side note, sorting the array indices before traversing the +array has been reported to add 15% to 20% overhead to the execution +time of `awk' programs. For this reason, sorted array traversal is not +the default. + File: gawk.info, Node: Delete, Next: Numeric Array Subscripts, Prev: Array Basics, Up: Arrays @@ -20013,7 +20030,7 @@ File: gawk.info, Node: Extracting, Next: Distribution contents, Prev: Getting B.1.2 Extracting the Distribution --------------------------------- -`gawk' is distributed as several `tar' file compressed with different +`gawk' is distributed as several `tar' files compressed with different compression programs: `gzip', `bzip2', and `xz'. For simplicity, the rest of these instructions assume you are using the one compressed with the GNU Zip program, `gzip'. @@ -20072,9 +20089,15 @@ Various `.c', `.y', and `.h' files A detailed list of source code changes as bugs are fixed or improvements made. +`ChangeLog.0' + An older list of source code changes. + `NEWS' A list of changes to `gawk' since the last release or patch. +`NEWS.0' + An older list of changes to `gawk'. + `COPYING' The GNU General Public License. @@ -20089,12 +20112,14 @@ Various `.c', `.y', and `.h' files not limits in `gawk' itself. `POSIX.STD' - A description of one area in which the POSIX standard for `awk' is - incorrect as well as how `gawk' handles the problem. + A description of behaviors in the POSIX standard for `awk' which + are left undefined, or where `gawk' may not comply fully, as well + as a list of things that the POSIX standard should describe but + does not. `doc/awkforai.txt' - A short article describing why `gawk' is a good language for AI - (Artificial Intelligence) programming. + A short article describing why `gawk' is a good language for + Artificial Intelligence (AI) programming. `doc/bc_notes' A brief description of `gawk''s "byte code" internals. @@ -20259,7 +20284,7 @@ run `make check'. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the `README_d' directory to see if you've found a known problem. If the failure is not described there, please send in a bug report (*note -Bugs::.) +Bugs::). File: gawk.info, Node: Additional Configuration Options, Next: Configuration Philosophy, Prev: Quick Installation, Up: Unix Installation @@ -20270,10 +20295,6 @@ 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: -`--with-whiny-user-strftime' - Force use of the included version of the `strftime()' function for - deficient systems. - `--disable-lint' Disable all lint checking within `gawk'. The `--lint' and `--lint-old' options (*note Options::) are accepted, but silently @@ -20294,6 +20315,10 @@ command line when compiling `gawk' from scratch, including: desirable, but it may bring you some slight performance improvement. +`--with-whiny-user-strftime' + Force use of the included version of the `strftime()' function for + deficient systems. + Use the command `./configure --help' to see the full list of options that `configure' supplies. @@ -20630,8 +20655,8 @@ B.3.1.5 Using `gawk' In The Cygwin Environment are using the Cygwin environment (http://www.cygwin.com). This environment provides an excellent simulation of Unix, using the GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and -other GNU tools. Compilation and installation for Cygwin is the same -as for a Unix system: +other GNU programs. Compilation and installation for Cygwin is the +same as for a Unix system: tar -xvpzf gawk-4.0.0.tar.gz cd gawk-4.0.0 @@ -20666,9 +20691,8 @@ File: gawk.info, Node: VMS Installation, Prev: PC Installation, Up: Non-Unix B.3.2 How to Compile and Install `gawk' on VMS ---------------------------------------------- -This node describes how to compile and install `gawk' under VMS. - - The older designation "VMS" is used throughout to refer to OpenVMS. +This node describes how to compile and install `gawk' under VMS. The +older designation "VMS" is used throughout to refer to OpenVMS. * Menu: @@ -20868,11 +20892,11 @@ considered authoritative if it conflicts with this Info file. The people maintaining the non-Unix ports of `gawk' are as follows: -MS-Windows using MINGW Eli Zaretskii, <eliz@gnu.org>. - Scott Deifik, <scottd.mail@sbcglobal.net>. -OS/2 Andreas Buening, <andreas.buening@nexgo.de>. -VMS Pat Rankin, <rankin@pactechdata.com>. -z/OS (OS/390) Dave Pitts, <dpitts@cozx.com>. +MS-Windows with MINGW and DJGPP Eli Zaretskii, <eliz@gnu.org>. + Scott Deifik, <scottd.mail@sbcglobal.net>. +OS/2 Andreas Buening, <andreas.buening@nexgo.de>. +VMS Pat Rankin, <rankin@pactechdata.com>. +z/OS (OS/390) Dave Pitts, <dpitts@cozx.com>. If your bug is also reproducible under Unix, please send a copy of your report to the <bug-gawk@gnu.org> email list as well. @@ -21073,7 +21097,7 @@ File: gawk.info, Node: Accessing The Source, Next: Adding Code, Up: Additions C.2.1 Accessing The `gawk' Git Repository ----------------------------------------- -As `gawk' is Free Software, the source code is always available *note +As `gawk' is Free Software, the source code is always available. *note Gawk Distribution::, describes how to get and build the formal, released versions of `gawk'. @@ -21118,13 +21142,21 @@ possible to include your changes: If that's not possible, continue with the rest of the steps in this list. - 2. Get the latest version. It is much easier for me to integrate + 2. Be prepared to sign the appropriate paperwork. In order for the + FSF to distribute your changes, you must either place those + changes in the public domain and submit a signed statement to that + effect, or assign the copyright in your changes to the FSF. Both + of these actions are easy to do and _many_ people have done so + already. If you have questions, please contact me (*note Bugs::), + or <assign@gnu.org>. + + 3. Get the latest version. It is much easier for me to integrate changes if they are relative to the most recent distributed version of `gawk'. If your version of `gawk' is very old, I may not be able to integrate them at all. (*Note Getting::, for information on getting the latest version of `gawk'.) - 3. See *note (Version)Top:: standards, GNU Coding Standards. This + 4. See *note (Version)Top:: standards, GNU Coding Standards. This document describes how GNU software should be written. If you haven't read it, please do so, preferably _before_ starting to modify `gawk'. (The `GNU Coding Standards' are available from the @@ -21132,7 +21164,7 @@ possible to include your changes: (http://www.gnu.org/prep/standards_toc.html). Texinfo, Info, and DVI versions are also available.) - 4. Use the `gawk' coding style. The C code for `gawk' follows the + 5. Use the `gawk' coding style. The C code for `gawk' follows the instructions in the `GNU Coding Standards', with minor exceptions. The code is formatted using the traditional "K&R" style, particularly as regards to the placement of braces and the use of @@ -21143,8 +21175,8 @@ possible to include your changes: * Put the name of the function at the beginning of its own line. - * Put the return type of the function, even if it is `int()', - on the line above the line with the name and arguments of the + * Put the return type of the function, even if it is `int', on + the line above the line with the name and arguments of the function. * Put spaces around parentheses used in control structures @@ -21180,18 +21212,19 @@ possible to include your changes: worth the minor benefit of not having to free the storage. Instead, use `malloc()' and `free()'. + * Do not use comparisons of the form `! strcmp(a, b)' or + similar. As Henry Spencer once said, "`strcmp()' is not a + boolean!" Instead, use `strcmp(a, b) == 0'. + + * If adding new bit flag values, use explicit hexadecimal + constants (`0x001', `0x002', `0x004', and son on) instead of + shifting one left by successive amounts (`(1<<0)', `(1<<1)', + and so on). + NOTE: If I have to reformat your code to follow the coding style used in `gawk', I may not bother to integrate your changes at all. - 5. Be prepared to sign the appropriate paperwork. In order for the - FSF to distribute your changes, you must either place those - changes in the public domain and submit a signed statement to that - effect, or assign the copyright in your changes to the FSF. Both - of these actions are easy to do and _many_ people have done so - already. If you have questions, please contact me (*note Bugs::), - or <assign@gnu.org>. - 6. Update the documentation. Along with your new code, please supply new sections and/or chapters for this Info file. If at all possible, please use real Texinfo, instead of just supplying @@ -21236,7 +21269,14 @@ steps: 1. Follow the guidelines in *note Adding Code::, concerning coding style, submission of diffs, and so on. - 2. When doing a port, bear in mind that your code must coexist + 2. Be prepared to sign the appropriate paperwork. In order for the + FSF to distribute your code, you must either place your code in + the public domain and submit a signed statement to that effect, or + assign the copyright in your code to the FSF. Both of these + actions are easy to do and _many_ people have done so already. If + you have questions, please contact me, or <gnu@gnu.org>. + + 3. When doing a port, bear in mind that your code must coexist peacefully with the rest of `gawk' and the other ports. Avoid gratuitous changes to the system-independent parts of the code. If at all possible, avoid sprinkling `#ifdef's just for your port @@ -21247,7 +21287,7 @@ steps: can, of course, distribute your changes on your own, as long as you comply with the GPL (*note Copying::). - 3. A number of the files that come with `gawk' are maintained by other + 4. A number of the files that come with `gawk' are maintained by other people. Thus, you should not change them unless it is for a very good reason; i.e., changes are not out of the question, but changes to these files are scrutinized extra carefully. The files @@ -21256,13 +21296,13 @@ steps: `regexec.c', `regexex.c', `regex.h', `regex_internal.c', and `regex_internal.h'. - 4. Be willing to continue to maintain the port. Non-Unix operating + 5. Be willing to continue to maintain the port. Non-Unix operating systems are supported by volunteers who maintain the code needed to compile and run `gawk' on their systems. If noone volunteers to maintain a port, it becomes unsupported and it may be necessary to remove it from the distribution. - 5. Supply an appropriate `gawkmisc.???' file. Each port has its own + 6. Supply an appropriate `gawkmisc.???' file. Each port has its own `gawkmisc.???' that implements certain operating system specific functions. This is cleaner than a plethora of `#ifdef's scattered throughout the code. The `gawkmisc.c' in the main source @@ -21278,7 +21318,7 @@ steps: (Currently, this is only an issue for the PC operating system ports.) - 6. Supply a `Makefile' as well as any other C source and header files + 7. Supply a `Makefile' as well as any other C source and header files that are necessary for your operating system. All your code should be in a separate subdirectory, with a name that is the same as, or reminiscent of, either your operating system or the @@ -21288,17 +21328,10 @@ steps: avoid using names for your files that duplicate the names of files in the main source directory. - 7. Update the documentation. Please write a section (or sections) + 8. Update the documentation. Please write a section (or sections) for this Info file describing the installation and compilation steps needed to compile and/or install `gawk' for your system. - 8. Be prepared to sign the appropriate paperwork. In order for the - FSF to distribute your code, you must either place your code in - the public domain and submit a signed statement to that effect, or - assign the copyright in your code to the FSF. Both of these - actions are easy to do and _many_ people have done so already. If - you have questions, please contact me, or <gnu@gnu.org>. - Following these steps makes it much easier to integrate your changes into `gawk' and have them coexist happily with other operating systems' code that is already there. @@ -21423,7 +21456,7 @@ when writing extensions. The next minor node shows how they are used: `NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference)' Finds, and installs if necessary, array elements. `symbol' is the array, `subs' is the subscript. This is usually a value created - with `make_string' (see below). `reference' should be `TRUE' if + with `make_string()' (see below). `reference' should be `TRUE' if it is an error to use the value before it is created. Typically, `FALSE' is the correct value to use from extension functions. @@ -21444,7 +21477,7 @@ when writing extensions. The next minor node shows how they are used: `void unref(NODE *n)' This macro releases the memory associated with a `NODE' allocated - with `make_string' or `make_number'. Understanding of `gawk' + with `make_string()' or `make_number()'. Understanding of `gawk' memory management is helpful. `void make_builtin(const char *name, NODE *(*func)(NODE *), int count)' @@ -21483,13 +21516,12 @@ when writing extensions. The next minor node shows how they are used: `void update_ERRNO(void)' This function is called from within a C extension function to set the value of `gawk''s `ERRNO' variable, based on the current value - of the C `errno' variable. It is provided as a convenience. + of the C `errno' global variable. It is provided as a convenience. `void update_ERRNO_saved(int errno_saved)' This function is called from within a C extension function to set - the value of `gawk''s `ERRNO' variable, based on the saved value - of the C `errno' variable provided as the argument. It is - provided as a convenience. + the value of `gawk''s `ERRNO' variable, based on the error value + provided as the argument. It is provided as a convenience. `void register_deferred_variable(const char *name, NODE *(*load_func)(void))' This function is called to register a function to be called when a @@ -21514,13 +21546,13 @@ when writing extensions. The next minor node shows how they are used: containing additional state associated with the input processing), and no further open hooks are called. - The function called will most likely want to set the `IOBUF' - `get_record()' method to indicate that future input records should + The function called will most likely want to set the `IOBUF''s + `get_record' method to indicate that future input records should be retrieved by calling that method instead of using the standard `gawk' input processing. - And the function will also probably want to set the `IOBUF' - `close_func()' method to be called when the file is closed to clean + And the function will also probably want to set the `IOBUF''s + `close_func' method to be called when the file is closed to clean up any state associated with the input. Finally, hook functions should be prepared to receive an `IOBUF' @@ -21541,7 +21573,8 @@ function parameter. NODE *the_arg; - the_arg = get_array_argument(2, FALSE); /* assume need 3rd arg, 0-based */ + /* assume need 3rd arg, 0-based */ + the_arg = get_array_argument(2, FALSE); Again, you should spend time studying the `gawk' internals; don't just blindly copy this code. @@ -21583,8 +21616,8 @@ implements these functions for `gawk' in an external extension library. File: gawk.info, Node: Internal File Description, Next: Internal File Ops, Up: Sample Library -C.3.3.1 Using `chdir' and `stat' -................................ +C.3.3.1 Using `chdir()' and `stat()' +.................................... This minor node shows how to use the new functions at the `awk' level once they've been integrated into the running `gawk' interpreter. @@ -21734,18 +21767,18 @@ other POSIX-compliant systems:(1) The file includes the `"awk.h"' header file for definitions for the `gawk' internals. It includes `<sys/sysmacros.h>' for access to the -`major' and `minor' macros. +`major()' and `minor'() macros. By convention, for an `awk' function `foo', the function that implements it is called `do_foo'. The function should take a `int' argument, usually called `nargs', that represents the number of defined arguments for the function. The `newdir' variable represents the new -directory to change to, retrieved with `get_scalar_argument'. Note +directory to change to, retrieved with `get_scalar_argument()'. Note that the first argument is numbered zero. - This code actually accomplishes the `chdir'. It first forces the -argument to be a string and passes the string value to the `chdir' -system call. If the `chdir' fails, `ERRNO' is updated. + This code actually accomplishes the `chdir()'. It first forces the +argument to be a string and passes the string value to the `chdir()' +system call. If the `chdir()' fails, `ERRNO' is updated. (void) force_string(newdir); ret = chdir(newdir->stptr); @@ -21757,7 +21790,7 @@ system call. If the `chdir' fails, `ERRNO' is updated. return make_number((AWKNUM) ret); } - The `stat' built-in is more involved. First comes a function that + The `stat()' built-in is more involved. First comes a function that turns a numeric mode into a printable representation (e.g., 644 becomes `-rw-r--r--'). This is omitted here for brevity: @@ -21769,7 +21802,7 @@ turns a numeric mode into a printable representation (e.g., 644 becomes ... } - Next comes the `do_stat' function. It starts with variable + Next comes the `do_stat()' function. It starts with variable declarations and argument checking: /* do_stat --- provide a stat() function for gawk */ @@ -21792,7 +21825,7 @@ Then, it always clears the array. The code use `lstat()' (instead of `stat()') to get the file information, in case the file is a symbolic link. If there's an error, it sets `ERRNO' and returns: - /* directory is first arg, array to hold results is second */ + /* file is first arg, array to hold results is second */ file = get_scalar_argument(0, FALSE); array = get_array_argument(1, FALSE); @@ -21832,7 +21865,7 @@ calls are shown here, since they all follow the same pattern: Finally, it's necessary to provide the "glue" that loads the new function(s) into `gawk'. By convention, each library has a routine -named `dlload' that does the job: +named `dlload()' that does the job: /* dlload --- load new builtins in this library */ @@ -21849,9 +21882,9 @@ implement system calls such as `chown()', `chmod()', and `umask()'. ---------- Footnotes ---------- - (1) This version is edited slightly for presentation. The complete -version can be found in `extension/filefuncs.c' in the `gawk' -distribution. + (1) This version is edited slightly for presentation. See +`extension/filefuncs.c' in the `gawk' distribution for the complete +version. File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops, Up: Sample Library @@ -24312,9 +24345,9 @@ Index * --command option: Options. (line 229) * --copyright option: Options. (line 85) * --disable-lint configuration option: Additional Configuration Options. - (line 13) + (line 9) * --disable-nls configuration option: Additional Configuration Options. - (line 28) + (line 24) * --dump-variables option <1>: Library Names. (line 45) * --dump-variables option: Options. (line 90) * --exec option: Options. (line 112) @@ -24349,7 +24382,7 @@ Index * --use-lc-numeric option: Options. (line 173) * --version option: Options. (line 248) * --with-whiny-user-strftime configuration option: Additional Configuration Options. - (line 9) + (line 29) * -b option: Options. (line 68) * -C option: Options. (line 85) * -d option: Options. (line 90) @@ -24512,7 +24545,7 @@ Index (line 67) * advanced features, data files as single record: Records. (line 175) * advanced features, fixed-width data: Constant Size. (line 9) -* advanced features, FNR/NR variables: Auto-set. (line 229) +* advanced features, FNR/NR variables: Auto-set. (line 230) * advanced features, gawk: Advanced Features. (line 6) * advanced features, gawk, network programming: TCP/IP Networking. (line 6) @@ -24573,11 +24606,11 @@ Index * arrays, elements, assigning: Assigning Elements. (line 6) * arrays, elements, deleting: Delete. (line 6) * arrays, elements, installing: Internals. (line 79) -* arrays, elements, order of: Scanning an Array. (line 48) +* arrays, elements, order of: Scanning an Array. (line 52) * arrays, elements, referencing: Reference to Elements. (line 6) * arrays, elements, retrieving number of: String Functions. (line 29) -* arrays, for statement and: Scanning an Array. (line 20) +* arrays, for statement and: Scanning an Array. (line 24) * arrays, IGNORECASE variable and: Array Intro. (line 92) * arrays, indexing: Array Intro. (line 50) * arrays, merging into strings: Join Function. (line 6) @@ -24593,7 +24626,7 @@ Index * arrays, subscripts, uninitialized variables as: Uninitialized Subscripts. (line 6) * artificial intelligence, gawk and: Distribution contents. - (line 47) + (line 55) * ASCII <1>: Glossary. (line 137) * ASCII: Ordinal Functions. (line 45) * asort() function (gawk) <1>: String Functions. (line 29) @@ -24879,7 +24912,7 @@ Index * close() function, two-way pipes and: Two-way I/O. (line 77) * Close, Diane <1>: Contributors. (line 21) * Close, Diane: Manual History. (line 41) -* close_func() input method: Internals. (line 161) +* close_func() input method: Internals. (line 160) * collating elements: Bracket Expressions. (line 70) * collating symbols: Bracket Expressions. (line 77) * Colombo, Antonio: Acknowledgments. (line 60) @@ -24949,11 +24982,11 @@ Index * condition debugger command: Breakpoint Control. (line 54) * conditional expressions: Conditional Exp. (line 6) * configuration option, --disable-lint: Additional Configuration Options. - (line 13) + (line 9) * configuration option, --disable-nls: Additional Configuration Options. - (line 28) + (line 24) * configuration option, --with-whiny-user-strftime: Additional Configuration Options. - (line 9) + (line 29) * configuration options, gawk: Additional Configuration Options. (line 6) * constants, nondecimal: Nondecimal Data. (line 6) @@ -25012,7 +25045,7 @@ Index (line 47) * dark corner, FILENAME variable <1>: Auto-set. (line 92) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 229) +* dark corner, FNR/NR variables: Auto-set. (line 230) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) @@ -25211,7 +25244,7 @@ Index * differences in awk and gawk, regular expressions: Case-sensitivity. (line 26) * differences in awk and gawk, RS/RT variables: Records. (line 167) -* differences in awk and gawk, RT variable: Auto-set. (line 218) +* differences in awk and gawk, RT variable: Auto-set. (line 219) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. @@ -25263,7 +25296,7 @@ Index (line 6) * elements in arrays, assigning: Assigning Elements. (line 6) * elements in arrays, deleting: Delete. (line 6) -* elements in arrays, order of: Scanning an Array. (line 48) +* elements in arrays, order of: Scanning an Array. (line 52) * elements in arrays, scanning: Scanning an Array. (line 6) * email address for bug reports, bug-gawk@gnu.org: Bugs. (line 30) * EMISTERED: TCP/IP Networking. (line 6) @@ -25293,7 +25326,7 @@ Index * endgrent() user-defined function: Group Functions. (line 218) * endpwent() function (C library): Passwd Functions. (line 210) * endpwent() user-defined function: Passwd Functions. (line 213) -* ENVIRON array <1>: Internals. (line 150) +* ENVIRON array <1>: Internals. (line 149) * ENVIRON array: Auto-set. (line 60) * environment variables: Auto-set. (line 60) * epoch, definition of: Glossary. (line 235) @@ -25351,7 +25384,7 @@ Index (line 9) * expressions, selecting: Conditional Exp. (line 6) * Extended Regular Expressions (EREs): Bracket Expressions. (line 23) -* eXtensible Markup Language (XML): Internals. (line 161) +* eXtensible Markup Language (XML): Internals. (line 160) * extension() function (gawk): Using Internal File Ops. (line 15) * extensions, Brian Kernighan's awk <1>: Other Versions. (line 13) @@ -25492,9 +25525,9 @@ Index * floating-point, numbers, AWKNUM internal type: Internals. (line 19) * FNR variable <1>: Auto-set. (line 102) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 229) +* FNR variable, changing: Auto-set. (line 230) * for statement: For Statement. (line 6) -* for statement, in arrays: Scanning an Array. (line 20) +* for statement, in arrays: Scanning an Array. (line 24) * force_number() internal function: Internals. (line 27) * force_string() internal function: Internals. (line 32) * force_wstring() internal function: Internals. (line 37) @@ -25595,7 +25628,7 @@ Index * gawk, break statement in: Break Statement. (line 51) * gawk, built-in variables and: Built-in Variables. (line 14) * gawk, character classes and: Bracket Expressions. (line 91) -* gawk, coding style in: Adding Code. (line 30) +* gawk, coding style in: Adding Code. (line 38) * gawk, command-line options: GNU Regexp Operators. (line 70) * gawk, comparison operators and: Comparison Operators. @@ -25666,7 +25699,7 @@ Index * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 157) -* gawk, RT variable in <1>: Auto-set. (line 218) +* gawk, RT variable in <1>: Auto-set. (line 219) * gawk, RT variable in <2>: Getline/Variable/File. (line 10) * gawk, RT variable in <3>: Multiple Line. (line 129) @@ -25692,7 +25725,7 @@ Index * get_argument() internal function: Internals. (line 120) * get_array_argument() internal macro: Internals. (line 136) * get_curfunc_arg_count() internal function: Internals. (line 42) -* get_record() input method: Internals. (line 161) +* get_record() input method: Internals. (line 160) * get_scalar_argument() internal macro: Internals. (line 133) * getaddrinfo() function (C library): TCP/IP Networking. (line 38) * getgrent() function (C library): Group Functions. (line 6) @@ -25807,7 +25840,7 @@ Index * in operator <3>: Precedence. (line 83) * in operator: Comparison Operators. (line 11) -* in operator, arrays and <1>: Scanning an Array. (line 17) +* in operator, arrays and <1>: Scanning an Array. (line 21) * in operator, arrays and: Reference to Elements. (line 37) * increment operators: Increment Ops. (line 6) @@ -25845,7 +25878,7 @@ Index * integers: Basic Data Typing. (line 21) * integers, unsigned: Basic Data Typing. (line 30) * interacting with other programs: I/O Functions. (line 63) -* internal constant, INVALID_HANDLE: Internals. (line 161) +* internal constant, INVALID_HANDLE: Internals. (line 160) * internal function, assoc_clear(): Internals. (line 75) * internal function, assoc_lookup(): Internals. (line 79) * internal function, dupnode(): Internals. (line 96) @@ -25855,18 +25888,18 @@ Index * internal function, get_actual_argument(): Internals. (line 125) * internal function, get_argument(): Internals. (line 120) * internal function, get_curfunc_arg_count(): Internals. (line 42) -* internal function, iop_alloc(): Internals. (line 161) +* internal function, iop_alloc(): Internals. (line 160) * internal function, make_builtin(): Internals. (line 106) * internal function, make_number(): Internals. (line 91) * internal function, make_string(): Internals. (line 86) -* internal function, register_deferred_variable(): Internals. (line 150) -* internal function, register_open_hook(): Internals. (line 161) +* internal function, register_deferred_variable(): Internals. (line 149) +* internal function, register_open_hook(): Internals. (line 160) * internal function, unref(): Internals. (line 101) * internal function, update_ERRNO(): Internals. (line 139) * internal function, update_ERRNO_saved(): Internals. (line 144) * internal macro, get_array_argument(): Internals. (line 136) * internal macro, get_scalar_argument(): Internals. (line 133) -* internal structure, IOBUF: Internals. (line 161) +* internal structure, IOBUF: Internals. (line 160) * internal type, AWKNUM: Internals. (line 19) * internal type, NODE: Internals. (line 23) * internal variable, nargs: Internals. (line 49) @@ -25895,10 +25928,10 @@ Index * interpreted programs <1>: Glossary. (line 356) * interpreted programs: Basic High Level. (line 14) * interval expressions: Regexp Operators. (line 116) -* INVALID_HANDLE internal constant: Internals. (line 161) +* INVALID_HANDLE internal constant: Internals. (line 160) * inventory-shipped file: Sample Data Files. (line 32) -* IOBUF internal structure: Internals. (line 161) -* iop_alloc() internal function: Internals. (line 161) +* IOBUF internal structure: Internals. (line 160) +* iop_alloc() internal function: Internals. (line 160) * isarray() function (gawk): Type Functions. (line 11) * ISO: Glossary. (line 367) * ISO 8859-1: Glossary. (line 137) @@ -26113,7 +26146,7 @@ Index * not Boolean-logic operator: Boolean Ops. (line 6) * NR variable <1>: Auto-set. (line 118) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 229) +* NR variable, changing: Auto-set. (line 230) * null strings <1>: Basic Data Typing. (line 50) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -26396,7 +26429,7 @@ Index * private variables: Library Names. (line 11) * processes, two-way communications with: Two-way I/O. (line 23) * processing data: Basic High Level. (line 6) -* PROCINFO array <1>: Internals. (line 150) +* PROCINFO array <1>: Internals. (line 149) * PROCINFO array <2>: Id Program. (line 15) * PROCINFO array <3>: Group Functions. (line 6) * PROCINFO array <4>: Passwd Functions. (line 6) @@ -26491,8 +26524,8 @@ Index * regexp constants, slashes vs. quotes: Computed Regexps. (line 28) * regexp constants, vs. string constants: Computed Regexps. (line 38) * regexp, See regular expressions: Regexp. (line 6) -* register_deferred_variable() internal function: Internals. (line 150) -* register_open_hook() internal function: Internals. (line 161) +* register_deferred_variable() internal function: Internals. (line 149) +* register_open_hook() internal function: Internals. (line 160) * regular expressions: Regexp. (line 6) * regular expressions as field separators: Field Separators. (line 50) * regular expressions, anchors in: Regexp Operators. (line 22) @@ -26545,7 +26578,7 @@ Index * right angle bracket (>), >> operator (I/O): Redirection. (line 50) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 74) -* RLENGTH variable: Auto-set. (line 205) +* RLENGTH variable: Auto-set. (line 206) * RLENGTH variable, match() function and: String Functions. (line 205) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) @@ -26570,9 +26603,9 @@ Index * RS variable: Records. (line 20) * RS variable, multiline records and: Multiple Line. (line 17) * rshift() function (gawk): Bitwise Functions. (line 51) -* RSTART variable: Auto-set. (line 211) +* RSTART variable: Auto-set. (line 212) * RSTART variable, match() function and: String Functions. (line 205) -* RT variable <1>: Auto-set. (line 218) +* RT variable <1>: Auto-set. (line 219) * RT variable <2>: Getline/Variable/File. (line 10) * RT variable <3>: Multiple Line. (line 129) @@ -26777,9 +26810,9 @@ Index * tee.awk program: Tee Program. (line 26) * terminating records: Records. (line 112) * testbits.awk program: Bitwise Functions. (line 68) -* Texinfo <1>: Adding Code. (line 90) +* Texinfo <1>: Adding Code. (line 99) * Texinfo <2>: Distribution contents. - (line 71) + (line 79) * Texinfo <3>: Extract Program. (line 12) * Texinfo <4>: Dupword Program. (line 17) * Texinfo <5>: Library Functions. (line 22) @@ -26981,7 +27014,7 @@ Index * wstptr internal variable: Internals. (line 61) * xgawk: Other Versions. (line 119) * xgettext utility: String Extraction. (line 13) -* XML (eXtensible Markup Language): Internals. (line 161) +* XML (eXtensible Markup Language): Internals. (line 160) * XOR bitwise operation: Bitwise Functions. (line 6) * xor() function (gawk): Bitwise Functions. (line 54) * Yawitz, Efraim: Contributors. (line 104) @@ -27018,406 +27051,407 @@ Index Tag Table: Node: Top1346 -Node: Foreword29921 -Node: Preface34266 -Ref: Preface-Footnote-137233 -Ref: Preface-Footnote-237339 -Node: History37571 -Node: Names39962 -Ref: Names-Footnote-141439 -Node: This Manual41511 -Ref: This Manual-Footnote-146459 -Node: Conventions46559 -Node: Manual History48693 -Ref: Manual History-Footnote-151963 -Ref: Manual History-Footnote-252004 -Node: How To Contribute52078 -Node: Acknowledgments53222 -Node: Getting Started57553 -Node: Running gawk59932 -Node: One-shot61118 -Node: Read Terminal62343 -Ref: Read Terminal-Footnote-163993 -Ref: Read Terminal-Footnote-264269 -Node: Long64440 -Node: Executable Scripts65816 -Ref: Executable Scripts-Footnote-167685 -Ref: Executable Scripts-Footnote-267787 -Node: Comments68238 -Node: Quoting70705 -Node: DOS Quoting75328 -Node: Sample Data Files76003 -Node: Very Simple79035 -Node: Two Rules83634 -Node: More Complex85781 -Ref: More Complex-Footnote-188711 -Node: Statements/Lines88796 -Ref: Statements/Lines-Footnote-193258 -Node: Other Features93523 -Node: When94451 -Node: Invoking Gawk96598 -Node: Command Line97983 -Node: Options98766 -Ref: Options-Footnote-1111898 -Node: Other Arguments111923 -Node: Naming Standard Input114581 -Node: Environment Variables115675 -Node: AWKPATH Variable116119 -Ref: AWKPATH Variable-Footnote-1118716 -Node: Other Environment Variables118976 -Node: Exit Status121316 -Node: Include Files121991 -Node: Obsolete125476 -Node: Undocumented126162 -Node: Regexp126403 -Node: Regexp Usage127855 -Node: Escape Sequences129881 -Node: Regexp Operators135644 -Ref: Regexp Operators-Footnote-1142841 -Ref: Regexp Operators-Footnote-2142988 -Node: Bracket Expressions143086 -Ref: table-char-classes144889 -Node: GNU Regexp Operators147533 -Node: Case-sensitivity151256 -Ref: Case-sensitivity-Footnote-1154224 -Ref: Case-sensitivity-Footnote-2154459 -Node: Leftmost Longest154567 -Node: Computed Regexps155768 -Node: Locales159194 -Node: Reading Files162901 -Node: Records164842 -Ref: Records-Footnote-1173516 -Node: Fields173553 -Ref: Fields-Footnote-1176586 -Node: Nonconstant Fields176672 -Node: Changing Fields178874 -Node: Field Separators184852 -Node: Default Field Splitting187481 -Node: Regexp Field Splitting188598 -Node: Single Character Fields191940 -Node: Command Line Field Separator192999 -Node: Field Splitting Summary196440 -Ref: Field Splitting Summary-Footnote-1199632 -Node: Constant Size199733 -Node: Splitting By Content204317 -Ref: Splitting By Content-Footnote-1208043 -Node: Multiple Line208083 -Ref: Multiple Line-Footnote-1213930 -Node: Getline214109 -Node: Plain Getline216337 -Node: Getline/Variable218426 -Node: Getline/File219567 -Node: Getline/Variable/File220889 -Ref: Getline/Variable/File-Footnote-1222488 -Node: Getline/Pipe222575 -Node: Getline/Variable/Pipe225135 -Node: Getline/Coprocess226242 -Node: Getline/Variable/Coprocess227485 -Node: Getline Notes228199 -Node: Getline Summary230141 -Ref: table-getline-variants230484 -Node: Command line directories231340 -Node: Printing231965 -Node: Print233596 -Node: Print Examples234933 -Node: Output Separators237717 -Node: OFMT239477 -Node: Printf240835 -Node: Basic Printf241741 -Node: Control Letters243280 -Node: Format Modifiers247092 -Node: Printf Examples253101 -Node: Redirection255816 -Node: Special Files262800 -Node: Special FD263333 -Ref: Special FD-Footnote-1266957 -Node: Special Network267031 -Node: Special Caveats267881 -Node: Close Files And Pipes268677 -Ref: Close Files And Pipes-Footnote-1275700 -Ref: Close Files And Pipes-Footnote-2275848 -Node: Expressions275998 -Node: Values277067 -Node: Constants277743 -Node: Scalar Constants278423 -Ref: Scalar Constants-Footnote-1279282 -Node: Nondecimal-numbers279464 -Node: Regexp Constants282523 -Node: Using Constant Regexps282998 -Node: Variables286053 -Node: Using Variables286708 -Node: Assignment Options288432 -Node: Conversion290304 -Ref: table-locale-affects295680 -Ref: Conversion-Footnote-1296304 -Node: All Operators296413 -Node: Arithmetic Ops297043 -Node: Concatenation299548 -Ref: Concatenation-Footnote-1302341 -Node: Assignment Ops302461 -Ref: table-assign-ops307449 -Node: Increment Ops308857 -Node: Truth Values and Conditions312327 -Node: Truth Values313410 -Node: Typing and Comparison314459 -Node: Variable Typing315248 -Ref: Variable Typing-Footnote-1319145 -Node: Comparison Operators319267 -Ref: table-relational-ops319677 -Node: POSIX String Comparison323226 -Ref: POSIX String Comparison-Footnote-1324182 -Node: Boolean Ops324320 -Ref: Boolean Ops-Footnote-1328398 -Node: Conditional Exp328489 -Node: Function Calls330221 -Node: Precedence333815 -Node: Patterns and Actions337468 -Node: Pattern Overview338522 -Node: Regexp Patterns340188 -Node: Expression Patterns340731 -Node: Ranges344305 -Node: BEGIN/END347271 -Node: Using BEGIN/END348033 -Ref: Using BEGIN/END-Footnote-1350764 -Node: I/O And BEGIN/END350870 -Node: BEGINFILE/ENDFILE353152 -Node: Empty355983 -Node: Using Shell Variables356299 -Node: Action Overview358584 -Node: Statements360941 -Node: If Statement362795 -Node: While Statement364294 -Node: Do Statement366338 -Node: For Statement367494 -Node: Switch Statement370646 -Node: Break Statement372743 -Node: Continue Statement374733 -Node: Next Statement376520 -Node: Nextfile Statement378910 -Node: Exit Statement381386 -Node: Built-in Variables383802 -Node: User-modified384897 -Ref: User-modified-Footnote-1392923 -Node: Auto-set392985 -Ref: Auto-set-Footnote-1403716 -Node: ARGC and ARGV403921 -Node: Arrays407772 -Node: Array Basics409343 -Node: Array Intro410054 -Node: Reference to Elements414372 -Node: Assigning Elements416642 -Node: Array Example417133 -Node: Scanning an Array418865 -Node: Delete424132 -Ref: Delete-Footnote-1426567 -Node: Numeric Array Subscripts426624 -Node: Uninitialized Subscripts428807 -Node: Multi-dimensional430435 -Node: Multi-scanning433526 -Node: Array Sorting435110 -Ref: Array Sorting-Footnote-1438204 -Node: Arrays of Arrays438398 -Node: Functions442971 -Node: Built-in443793 -Node: Calling Built-in444871 -Node: Numeric Functions446859 -Ref: Numeric Functions-Footnote-1450624 -Ref: Numeric Functions-Footnote-2450981 -Ref: Numeric Functions-Footnote-3451029 -Node: String Functions451298 -Ref: String Functions-Footnote-1473800 -Ref: String Functions-Footnote-2473929 -Ref: String Functions-Footnote-3474177 -Node: Gory Details474264 -Ref: table-sub-escapes475943 -Ref: table-posix-sub477257 -Ref: table-gensub-escapes478170 -Node: I/O Functions479341 -Ref: I/O Functions-Footnote-1485996 -Node: Time Functions486143 -Ref: Time Functions-Footnote-1497035 -Ref: Time Functions-Footnote-2497103 -Ref: Time Functions-Footnote-3497261 -Ref: Time Functions-Footnote-4497372 -Ref: Time Functions-Footnote-5497484 -Ref: Time Functions-Footnote-6497711 -Node: Bitwise Functions497977 -Ref: table-bitwise-ops498535 -Ref: Bitwise Functions-Footnote-1502695 -Node: Type Functions502879 -Node: I18N Functions503349 -Node: User-defined504976 -Node: Definition Syntax505780 -Ref: Definition Syntax-Footnote-1510690 -Node: Function Example510759 -Node: Function Caveats513353 -Node: Calling A Function513774 -Node: Variable Scope514889 -Node: Pass By Value/Reference516864 -Node: Return Statement520304 -Node: Dynamic Typing523285 -Node: Indirect Calls524020 -Node: Internationalization533705 -Node: I18N and L10N535131 -Node: Explaining gettext535817 -Ref: Explaining gettext-Footnote-1540883 -Ref: Explaining gettext-Footnote-2541067 -Node: Programmer i18n541232 -Node: Translator i18n545432 -Node: String Extraction546225 -Ref: String Extraction-Footnote-1547186 -Node: Printf Ordering547272 -Ref: Printf Ordering-Footnote-1550056 -Node: I18N Portability550120 -Ref: I18N Portability-Footnote-1552569 -Node: I18N Example552632 -Ref: I18N Example-Footnote-1555267 -Node: Gawk I18N555339 -Node: Advanced Features555956 -Node: Nondecimal Data557275 -Node: Two-way I/O558856 -Ref: Two-way I/O-Footnote-1564290 -Node: TCP/IP Networking564360 -Node: Profiling567204 -Node: Library Functions574678 -Ref: Library Functions-Footnote-1577783 -Node: Library Names577954 -Ref: Library Names-Footnote-1581425 -Ref: Library Names-Footnote-2581645 -Node: General Functions581731 -Node: Nextfile Function582794 -Node: Strtonum Function587175 -Node: Assert Function590131 -Node: Round Function593457 -Node: Cliff Random Function595000 -Node: Ordinal Functions596016 -Ref: Ordinal Functions-Footnote-1599086 -Ref: Ordinal Functions-Footnote-2599338 -Node: Join Function599547 -Ref: Join Function-Footnote-1601318 -Node: Gettimeofday Function601518 -Node: Data File Management605233 -Node: Filetrans Function605865 -Node: Rewind Function610101 -Node: File Checking611554 -Node: Empty Files612648 -Node: Ignoring Assigns614878 -Node: Getopt Function616431 -Ref: Getopt Function-Footnote-1627735 -Node: Passwd Functions627938 -Ref: Passwd Functions-Footnote-1636913 -Node: Group Functions637001 -Node: Walking Arrays645085 -Node: Sample Programs646654 -Node: Running Examples647319 -Node: Clones648047 -Node: Cut Program649271 -Node: Egrep Program659116 -Ref: Egrep Program-Footnote-1666889 -Node: Id Program666999 -Node: Split Program670615 -Ref: Split Program-Footnote-1674134 -Node: Tee Program674262 -Node: Uniq Program677065 -Node: Wc Program684494 -Ref: Wc Program-Footnote-1688760 -Ref: Wc Program-Footnote-2688960 -Node: Miscellaneous Programs689052 -Node: Dupword Program690240 -Node: Alarm Program692271 -Node: Translate Program697020 -Ref: Translate Program-Footnote-1701407 -Ref: Translate Program-Footnote-2701635 -Node: Labels Program701769 -Ref: Labels Program-Footnote-1705140 -Node: Word Sorting705224 -Node: History Sorting709108 -Node: Extract Program710947 -Ref: Extract Program-Footnote-1718430 -Node: Simple Sed718558 -Node: Igawk Program721620 -Ref: Igawk Program-Footnote-1736653 -Ref: Igawk Program-Footnote-2736854 -Node: Anagram Program736992 -Node: Signature Program740060 -Node: Debugger741160 -Node: Debugging742071 -Node: Debugging Concepts742484 -Node: Debugging Terms744340 -Node: Awk Debugging746962 -Node: Sample dgawk session747854 -Node: dgawk invocation748346 -Node: Finding The Bug749528 -Node: List of Debugger Commands756014 -Node: Breakpoint Control757325 -Node: Dgawk Execution Control760961 -Node: Viewing And Changing Data764312 -Node: Dgawk Stack767649 -Node: Dgawk Info769109 -Node: Miscellaneous Dgawk Commands773057 -Node: Readline Support778485 -Node: Dgawk Limitations779323 -Node: Language History781512 -Node: V7/SVR3.1782950 -Node: SVR4785271 -Node: POSIX786713 -Node: BTL787721 -Node: POSIX/GNU788455 -Node: Common Extensions793556 -Node: Contributors794657 -Node: Installation798796 -Node: Gawk Distribution799690 -Node: Getting800174 -Node: Extracting801000 -Node: Distribution contents802691 -Node: Unix Installation807709 -Node: Quick Installation808326 -Node: Additional Configuration Options810288 -Node: Configuration Philosophy811765 -Node: Non-Unix Installation814107 -Node: PC Installation814565 -Node: PC Binary Installation815864 -Node: PC Compiling817712 -Node: PC Testing820656 -Node: PC Using821832 -Node: Cygwin826017 -Node: MSYS827014 -Node: VMS Installation827528 -Node: VMS Compilation828134 -Ref: VMS Compilation-Footnote-1829141 -Node: VMS Installation Details829199 -Node: VMS Running830834 -Node: VMS Old Gawk832441 -Node: Bugs832915 -Node: Other Versions836780 -Node: Notes842059 -Node: Compatibility Mode842751 -Node: Additions843534 -Node: Accessing The Source844346 -Node: Adding Code845769 -Node: New Ports851317 -Node: Dynamic Extensions855430 -Node: Internals856806 -Node: Plugin License865922 -Node: Sample Library866556 -Node: Internal File Description867242 -Node: Internal File Ops870949 -Ref: Internal File Ops-Footnote-1875717 -Node: Using Internal File Ops875865 -Node: Future Extensions878242 -Node: Basic Concepts880746 -Node: Basic High Level881503 -Ref: Basic High Level-Footnote-1885538 -Node: Basic Data Typing885723 -Node: Floating Point Issues890248 -Node: String Conversion Precision891331 -Ref: String Conversion Precision-Footnote-1893025 -Node: Unexpected Results893134 -Node: POSIX Floating Point Problems894960 -Ref: POSIX Floating Point Problems-Footnote-1898662 -Node: Glossary898700 -Node: Copying922843 -Node: GNU Free Documentation License960400 -Node: Index985537 +Node: Foreword30042 +Node: Preface34387 +Ref: Preface-Footnote-137354 +Ref: Preface-Footnote-237460 +Node: History37692 +Node: Names40083 +Ref: Names-Footnote-141560 +Node: This Manual41632 +Ref: This Manual-Footnote-146580 +Node: Conventions46680 +Node: Manual History48814 +Ref: Manual History-Footnote-152084 +Ref: Manual History-Footnote-252125 +Node: How To Contribute52199 +Node: Acknowledgments53343 +Node: Getting Started57674 +Node: Running gawk60053 +Node: One-shot61239 +Node: Read Terminal62464 +Ref: Read Terminal-Footnote-164114 +Ref: Read Terminal-Footnote-264390 +Node: Long64561 +Node: Executable Scripts65937 +Ref: Executable Scripts-Footnote-167806 +Ref: Executable Scripts-Footnote-267908 +Node: Comments68359 +Node: Quoting70826 +Node: DOS Quoting75449 +Node: Sample Data Files76124 +Node: Very Simple79156 +Node: Two Rules83755 +Node: More Complex85902 +Ref: More Complex-Footnote-188832 +Node: Statements/Lines88917 +Ref: Statements/Lines-Footnote-193379 +Node: Other Features93644 +Node: When94572 +Node: Invoking Gawk96719 +Node: Command Line98104 +Node: Options98887 +Ref: Options-Footnote-1112019 +Node: Other Arguments112044 +Node: Naming Standard Input114702 +Node: Environment Variables115796 +Node: AWKPATH Variable116240 +Ref: AWKPATH Variable-Footnote-1118837 +Node: Other Environment Variables119097 +Node: Exit Status121437 +Node: Include Files122112 +Node: Obsolete125597 +Node: Undocumented126283 +Node: Regexp126524 +Node: Regexp Usage127976 +Node: Escape Sequences130002 +Node: Regexp Operators135765 +Ref: Regexp Operators-Footnote-1142962 +Ref: Regexp Operators-Footnote-2143109 +Node: Bracket Expressions143207 +Ref: table-char-classes145010 +Node: GNU Regexp Operators147654 +Node: Case-sensitivity151377 +Ref: Case-sensitivity-Footnote-1154345 +Ref: Case-sensitivity-Footnote-2154580 +Node: Leftmost Longest154688 +Node: Computed Regexps155889 +Node: Locales159315 +Node: Reading Files163022 +Node: Records164963 +Ref: Records-Footnote-1173637 +Node: Fields173674 +Ref: Fields-Footnote-1176707 +Node: Nonconstant Fields176793 +Node: Changing Fields178995 +Node: Field Separators184973 +Node: Default Field Splitting187602 +Node: Regexp Field Splitting188719 +Node: Single Character Fields192061 +Node: Command Line Field Separator193120 +Node: Field Splitting Summary196561 +Ref: Field Splitting Summary-Footnote-1199753 +Node: Constant Size199854 +Node: Splitting By Content204438 +Ref: Splitting By Content-Footnote-1208164 +Node: Multiple Line208204 +Ref: Multiple Line-Footnote-1214051 +Node: Getline214230 +Node: Plain Getline216458 +Node: Getline/Variable218547 +Node: Getline/File219688 +Node: Getline/Variable/File221010 +Ref: Getline/Variable/File-Footnote-1222609 +Node: Getline/Pipe222696 +Node: Getline/Variable/Pipe225256 +Node: Getline/Coprocess226363 +Node: Getline/Variable/Coprocess227606 +Node: Getline Notes228320 +Node: Getline Summary230262 +Ref: table-getline-variants230605 +Node: Command line directories231461 +Node: Printing232086 +Node: Print233717 +Node: Print Examples235054 +Node: Output Separators237838 +Node: OFMT239598 +Node: Printf240956 +Node: Basic Printf241862 +Node: Control Letters243401 +Node: Format Modifiers247213 +Node: Printf Examples253222 +Node: Redirection255937 +Node: Special Files262921 +Node: Special FD263454 +Ref: Special FD-Footnote-1267078 +Node: Special Network267152 +Node: Special Caveats268002 +Node: Close Files And Pipes268798 +Ref: Close Files And Pipes-Footnote-1275821 +Ref: Close Files And Pipes-Footnote-2275969 +Node: Expressions276119 +Node: Values277188 +Node: Constants277864 +Node: Scalar Constants278544 +Ref: Scalar Constants-Footnote-1279403 +Node: Nondecimal-numbers279585 +Node: Regexp Constants282644 +Node: Using Constant Regexps283119 +Node: Variables286174 +Node: Using Variables286829 +Node: Assignment Options288553 +Node: Conversion290425 +Ref: table-locale-affects295801 +Ref: Conversion-Footnote-1296425 +Node: All Operators296534 +Node: Arithmetic Ops297164 +Node: Concatenation299669 +Ref: Concatenation-Footnote-1302462 +Node: Assignment Ops302582 +Ref: table-assign-ops307570 +Node: Increment Ops308978 +Node: Truth Values and Conditions312448 +Node: Truth Values313531 +Node: Typing and Comparison314580 +Node: Variable Typing315369 +Ref: Variable Typing-Footnote-1319266 +Node: Comparison Operators319388 +Ref: table-relational-ops319798 +Node: POSIX String Comparison323347 +Ref: POSIX String Comparison-Footnote-1324303 +Node: Boolean Ops324441 +Ref: Boolean Ops-Footnote-1328519 +Node: Conditional Exp328610 +Node: Function Calls330342 +Node: Precedence333936 +Node: Patterns and Actions337589 +Node: Pattern Overview338643 +Node: Regexp Patterns340309 +Node: Expression Patterns340852 +Node: Ranges344426 +Node: BEGIN/END347392 +Node: Using BEGIN/END348154 +Ref: Using BEGIN/END-Footnote-1350885 +Node: I/O And BEGIN/END350991 +Node: BEGINFILE/ENDFILE353273 +Node: Empty356104 +Node: Using Shell Variables356420 +Node: Action Overview358705 +Node: Statements361062 +Node: If Statement362916 +Node: While Statement364415 +Node: Do Statement366459 +Node: For Statement367615 +Node: Switch Statement370767 +Node: Break Statement372864 +Node: Continue Statement374854 +Node: Next Statement376641 +Node: Nextfile Statement379031 +Node: Exit Statement381507 +Node: Built-in Variables383923 +Node: User-modified385018 +Ref: User-modified-Footnote-1393044 +Node: Auto-set393106 +Ref: Auto-set-Footnote-1403848 +Node: ARGC and ARGV404053 +Node: Arrays407904 +Node: Array Basics409475 +Node: Array Intro410186 +Node: Reference to Elements414504 +Node: Assigning Elements416774 +Node: Array Example417265 +Node: Scanning an Array418997 +Node: Controlling Scanning421373 +Node: Delete424711 +Ref: Delete-Footnote-1427146 +Node: Numeric Array Subscripts427203 +Node: Uninitialized Subscripts429386 +Node: Multi-dimensional431014 +Node: Multi-scanning434105 +Node: Array Sorting435689 +Ref: Array Sorting-Footnote-1438783 +Node: Arrays of Arrays438977 +Node: Functions443550 +Node: Built-in444372 +Node: Calling Built-in445450 +Node: Numeric Functions447438 +Ref: Numeric Functions-Footnote-1451203 +Ref: Numeric Functions-Footnote-2451560 +Ref: Numeric Functions-Footnote-3451608 +Node: String Functions451877 +Ref: String Functions-Footnote-1474379 +Ref: String Functions-Footnote-2474508 +Ref: String Functions-Footnote-3474756 +Node: Gory Details474843 +Ref: table-sub-escapes476522 +Ref: table-posix-sub477836 +Ref: table-gensub-escapes478749 +Node: I/O Functions479920 +Ref: I/O Functions-Footnote-1486575 +Node: Time Functions486722 +Ref: Time Functions-Footnote-1497614 +Ref: Time Functions-Footnote-2497682 +Ref: Time Functions-Footnote-3497840 +Ref: Time Functions-Footnote-4497951 +Ref: Time Functions-Footnote-5498063 +Ref: Time Functions-Footnote-6498290 +Node: Bitwise Functions498556 +Ref: table-bitwise-ops499114 +Ref: Bitwise Functions-Footnote-1503274 +Node: Type Functions503458 +Node: I18N Functions503928 +Node: User-defined505555 +Node: Definition Syntax506359 +Ref: Definition Syntax-Footnote-1511269 +Node: Function Example511338 +Node: Function Caveats513932 +Node: Calling A Function514353 +Node: Variable Scope515468 +Node: Pass By Value/Reference517443 +Node: Return Statement520883 +Node: Dynamic Typing523864 +Node: Indirect Calls524599 +Node: Internationalization534284 +Node: I18N and L10N535710 +Node: Explaining gettext536396 +Ref: Explaining gettext-Footnote-1541462 +Ref: Explaining gettext-Footnote-2541646 +Node: Programmer i18n541811 +Node: Translator i18n546011 +Node: String Extraction546804 +Ref: String Extraction-Footnote-1547765 +Node: Printf Ordering547851 +Ref: Printf Ordering-Footnote-1550635 +Node: I18N Portability550699 +Ref: I18N Portability-Footnote-1553148 +Node: I18N Example553211 +Ref: I18N Example-Footnote-1555846 +Node: Gawk I18N555918 +Node: Advanced Features556535 +Node: Nondecimal Data557854 +Node: Two-way I/O559435 +Ref: Two-way I/O-Footnote-1564869 +Node: TCP/IP Networking564939 +Node: Profiling567783 +Node: Library Functions575257 +Ref: Library Functions-Footnote-1578362 +Node: Library Names578533 +Ref: Library Names-Footnote-1582004 +Ref: Library Names-Footnote-2582224 +Node: General Functions582310 +Node: Nextfile Function583373 +Node: Strtonum Function587754 +Node: Assert Function590710 +Node: Round Function594036 +Node: Cliff Random Function595579 +Node: Ordinal Functions596595 +Ref: Ordinal Functions-Footnote-1599665 +Ref: Ordinal Functions-Footnote-2599917 +Node: Join Function600126 +Ref: Join Function-Footnote-1601897 +Node: Gettimeofday Function602097 +Node: Data File Management605812 +Node: Filetrans Function606444 +Node: Rewind Function610680 +Node: File Checking612133 +Node: Empty Files613227 +Node: Ignoring Assigns615457 +Node: Getopt Function617010 +Ref: Getopt Function-Footnote-1628314 +Node: Passwd Functions628517 +Ref: Passwd Functions-Footnote-1637492 +Node: Group Functions637580 +Node: Walking Arrays645664 +Node: Sample Programs647233 +Node: Running Examples647898 +Node: Clones648626 +Node: Cut Program649850 +Node: Egrep Program659695 +Ref: Egrep Program-Footnote-1667468 +Node: Id Program667578 +Node: Split Program671194 +Ref: Split Program-Footnote-1674713 +Node: Tee Program674841 +Node: Uniq Program677644 +Node: Wc Program685073 +Ref: Wc Program-Footnote-1689339 +Ref: Wc Program-Footnote-2689539 +Node: Miscellaneous Programs689631 +Node: Dupword Program690819 +Node: Alarm Program692850 +Node: Translate Program697599 +Ref: Translate Program-Footnote-1701986 +Ref: Translate Program-Footnote-2702214 +Node: Labels Program702348 +Ref: Labels Program-Footnote-1705719 +Node: Word Sorting705803 +Node: History Sorting709687 +Node: Extract Program711526 +Ref: Extract Program-Footnote-1719009 +Node: Simple Sed719137 +Node: Igawk Program722199 +Ref: Igawk Program-Footnote-1737232 +Ref: Igawk Program-Footnote-2737433 +Node: Anagram Program737571 +Node: Signature Program740639 +Node: Debugger741739 +Node: Debugging742650 +Node: Debugging Concepts743063 +Node: Debugging Terms744919 +Node: Awk Debugging747541 +Node: Sample dgawk session748433 +Node: dgawk invocation748925 +Node: Finding The Bug750107 +Node: List of Debugger Commands756593 +Node: Breakpoint Control757904 +Node: Dgawk Execution Control761540 +Node: Viewing And Changing Data764891 +Node: Dgawk Stack768228 +Node: Dgawk Info769688 +Node: Miscellaneous Dgawk Commands773636 +Node: Readline Support779064 +Node: Dgawk Limitations779902 +Node: Language History782091 +Node: V7/SVR3.1783529 +Node: SVR4785850 +Node: POSIX787292 +Node: BTL788300 +Node: POSIX/GNU789034 +Node: Common Extensions794135 +Node: Contributors795236 +Node: Installation799375 +Node: Gawk Distribution800269 +Node: Getting800753 +Node: Extracting801579 +Node: Distribution contents803271 +Node: Unix Installation808493 +Node: Quick Installation809110 +Node: Additional Configuration Options811072 +Node: Configuration Philosophy812549 +Node: Non-Unix Installation814891 +Node: PC Installation815349 +Node: PC Binary Installation816648 +Node: PC Compiling818496 +Node: PC Testing821440 +Node: PC Using822616 +Node: Cygwin826801 +Node: MSYS827801 +Node: VMS Installation828315 +Node: VMS Compilation828918 +Ref: VMS Compilation-Footnote-1829925 +Node: VMS Installation Details829983 +Node: VMS Running831618 +Node: VMS Old Gawk833225 +Node: Bugs833699 +Node: Other Versions837609 +Node: Notes842888 +Node: Compatibility Mode843580 +Node: Additions844363 +Node: Accessing The Source845175 +Node: Adding Code846600 +Node: New Ports852567 +Node: Dynamic Extensions856680 +Node: Internals858056 +Node: Plugin License867159 +Node: Sample Library867793 +Node: Internal File Description868479 +Node: Internal File Ops872194 +Ref: Internal File Ops-Footnote-1876975 +Node: Using Internal File Ops877115 +Node: Future Extensions879492 +Node: Basic Concepts881996 +Node: Basic High Level882753 +Ref: Basic High Level-Footnote-1886788 +Node: Basic Data Typing886973 +Node: Floating Point Issues891498 +Node: String Conversion Precision892581 +Ref: String Conversion Precision-Footnote-1894275 +Node: Unexpected Results894384 +Node: POSIX Floating Point Problems896210 +Ref: POSIX Floating Point Problems-Footnote-1899912 +Node: Glossary899950 +Node: Copying924093 +Node: GNU Free Documentation License961650 +Node: Index986787 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 1b346289..17df090e 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -501,6 +501,8 @@ particular records in a file and perform operations upon them. * Scanning an Array:: A variation of the @code{for} statement. It loops through the indices of an array's existing elements. +* Controlling Scanning:: Controlling the order in which arrays + are scanned. * Delete:: The @code{delete} statement removes an element from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in @@ -12759,10 +12761,10 @@ order in which array indices will be processed by @samp{for (index in array) @dots{}} loops. The value should contain one to three words; separate pairs of words by a single space. -One word controls sort direction, ``ascending'' or ``descending;'' -another controls the sort key, ``index'' or ``value;'' and the remaining +One word controls sort direction, @samp{ascending} or @samp{descending}; +another controls the sort key, @samp{index} or @samp{value}; and the remaining one, which is only valid for sorting by index, is comparison mode, -``string'' or ``number.'' When two or three words are present, they may +@samp{string} or @samp{number}. When two or three words are present, they may be specified in any order, so @samp{ascending index string} and @samp{string ascending index} are equivalent. Also, each word may be truncated, so @samp{asc index str} and @samp{a i s} are also @@ -12770,13 +12772,13 @@ equivalent. Note that a separating space is required even when the words have been shortened down to one letter each. You can omit direction and/or key type and/or comparison mode. Provided -that at least one is present, missing parts of a sort specification +that at least one is present, the missing parts of a sort specification default to @samp{ascending}, @samp{index}, and (for indices only) @samp{string}, respectively. An empty string, @code{""}, is the same as @samp{unsorted} and will cause @samp{for (index in array) @dots{}} to process the indices in arbitrary order. Another thing to note is that the array sorting -takes place at the time @samp{for (@dots{} in @dots{})} is about to +takes place at the time the @code{for} loop is about to start executing, so changing the value of @code{PROCINFO["sorted_in"]} during loop execution does not have any effect on the order in which any remaining array elements get processed. @@ -13385,6 +13387,10 @@ END @{ @cindex elements in arrays, scanning @cindex arrays, scanning +@menu +* Controlling Scanning:: Controlling the order in which arrays are scanned. +@end menu + In programs that use arrays, it is often necessary to use a loop that executes once for each element of an array. In other languages, where arrays are contiguous and indices are limited to positive integers, @@ -13449,42 +13455,49 @@ the loop body; it is not predictable whether the @code{for} loop will reach them. Similarly, changing @var{var} inside the loop may produce strange results. It is best to avoid such things. +@node Controlling Scanning +@subsubsection Controlling Array Scanning Order + As an extension, @command{gawk} makes it possible for you to loop over the elements of an array in order, based on the value of @code{PROCINFO["sorted_in"]} (@pxref{Auto-set}). Several sorting options are available: -@table @code -@item "ascending index string" -Order by indices compared as strings, the most basic sort. -(Internally, array indices are always strings, so with @code{a[2*5] = 1} +@table @samp +@item ascending index string +Order by indices 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 actually @code{"10"} rather than numeric 10.) -@item "ascending index number" +@item ascending index number Order by indices but force them to be treated as numbers in the process. -Any index with non-numeric value will end up positioned as if it were 0. +Any index with non-numeric value will end up positioned as if it were zero. -@item "ascending value" +@item ascending value Order by element values rather than by indices. Comparisons are done as numeric when both values being compared are numeric, or done as -strings when either or both aren't numeric. Sub-arrays, if present, -come out last. +strings when either or both aren't numeric (@pxref{Variable Typing}). +Subarrays, if present, come out last. -@item "descending index string" +@item descending index string Reverse order from the most basic sort. -@item "descending index number" +@item descending index number Numeric indices ordered from high to low. -@item "descending value" -Element values ordered from high to low. Sub-arrays, if present, +@item descending value +Element values ordered from high to low. Subarrays, if present, come out first. -@item "unsorted" +@item unsorted Array elements are processed in arbitrary order, the normal @command{awk} behavior. @end table +The array traversal order is determined before the @code{for} loop +starts to run. Changing @code{PROCINFO["sorted_in"]} in the looop body +will not affect the loop. + Portions of the sort specification string may be truncated or omitted. The default is @samp{ascending} for direction, @samp{index} for sort key type, and (when sorting by index only) @samp{string} for comparison mode. @@ -13510,34 +13523,35 @@ $ @kbd{gawk 'BEGIN @{} @print{} 4 4 @end example -As a side note, sorting the array indices before traversing -the array has been reported to add 15% to 20% overhead to the -execution time of @command{awk} programs. For this reason, -sorted array traversal is not the default. -@c The @command{gawk} -@c maintainers believe that only the people who wish to use a -@c feature should have to pay for it. - When sorting an array by element values, if a value happens to be -a sub-array then it is considered to be greater than any string or -numeric value, regardless of what the sub-array itself contains, -and all sub-arrays are treated as being equal to each other. Their +a subarray then it is considered to be greater than any string or +numeric value, regardless of what the subarray itself contains, +and all subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. -Sorting by array element values (for values other than sub-arrays) +Sorting by array element values (for values other than subarrays) always uses basic @command{awk} comparison mode: if both values happen to be numbers then they're compared as numbers, otherwise they're compared as strings. When string comparisons are made during a sort, either for element values where one or both aren't numbers or for element indices -handled as strings, the value of @code{IGNORECASE} controls whether +handled as strings, the value of @code{IGNORECASE} +(@pxref{Built-in Variables}) controls whether the comparisons treat corresponding upper and lower case letters as equivalent or distinct. This sorting extension is disabled in POSIX mode, since the @code{PROCINFO} array is not special in that case. +As a side note, sorting the array indices before traversing +the array has been reported to add 15% to 20% overhead to the +execution time of @command{awk} programs. For this reason, +sorted array traversal is not the default. +@c The @command{gawk} +@c maintainers believe that only the people who wish to use a +@c feature should have to pay for it. + @node Delete @section The @code{delete} Statement @cindex @code{delete} statement @@ -26983,7 +26997,7 @@ will be less busy, and you can usually find one closer to your site. @node Extracting @appendixsubsec Extracting the Distribution -@command{gawk} is distributed as several @code{tar} file compressed with +@command{gawk} is distributed as several @code{tar} files compressed with different compression programs: @command{gzip}, @command{bzip2}, and @command{xz}. For simplicity, the rest of these instructions assume you are using the one compressed with the GNU Zip program, @code{gzip}. @@ -27054,9 +27068,15 @@ A file providing an overview of the configuration and installation process. @item ChangeLog A detailed list of source code changes as bugs are fixed or improvements made. +@item ChangeLog.0 +An older list of source code changes. + @item NEWS A list of changes to @command{gawk} since the last release or patch. +@item NEWS.0 +An older list of changes to @command{gawk}. + @item COPYING The GNU General Public License. @@ -27071,13 +27091,14 @@ 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 one area in which the POSIX standard for @command{awk} is -incorrect as well as how @command{gawk} handles the problem. +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 +as a list of things that the POSIX standard should describe but does not. @cindex artificial intelligence@comma{} @command{gawk} and @item doc/awkforai.txt A short article describing why @command{gawk} is a good language for -AI (Artificial Intelligence) programming. +Artificial Intelligence (AI) programming. @item doc/bc_notes A brief description of @command{gawk}'s ``byte code'' internals. @@ -27275,8 +27296,7 @@ run @samp{make check}. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the @file{README_d} directory to see if you've found a known problem. If the failure is not described there, -please send in a bug report -(@pxref{Bugs}.) +please send in a bug report (@pxref{Bugs}). @node Additional Configuration Options @appendixsubsec Additional Configuration Options @@ -27288,12 +27308,6 @@ command line when compiling @command{gawk} from scratch, including: @table @code -@cindex @code{--with-whiny-user-strftime} configuration option -@cindex configuration option, @code{--with-whiny-user-strftime} -@item --with-whiny-user-strftime -Force use of the included version of the @code{strftime()} -function for deficient systems. - @cindex @code{--disable-lint} configuration option @cindex configuration option, @code{--disable-lint} @item --disable-lint @@ -27320,6 +27334,12 @@ to fail. This option may be removed at a later date. Disable all message-translation facilities. This is usually not desirable, but it may bring you some slight performance improvement. + +@cindex @code{--with-whiny-user-strftime} configuration option +@cindex configuration option, @code{--with-whiny-user-strftime} +@item --with-whiny-user-strftime +Force use of the included version of the @code{strftime()} +function for deficient systems. @end table Use the command @samp{./configure --help} to see the full list of @@ -27725,7 +27745,7 @@ moved into the @code{BEGIN} rule. if you are using the @uref{http://www.cygwin.com, Cygwin environment}. This environment provides an excellent simulation of Unix, using the GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, -and other GNU tools. Compilation and installation for Cygwin is the +and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: @example @@ -27766,7 +27786,6 @@ translation of @code{"\r\n"}, since it won't. Caveat Emptor! @cindex @command{gawk}, VMS version of @cindex installation, VMS This @value{SUBSECTION} describes how to compile and install @command{gawk} under VMS. - The older designation ``VMS'' is used throughout to refer to OpenVMS. @menu @@ -28032,10 +28051,10 @@ authoritative if it conflicts with this @value{DOCUMENT}. The people maintaining the non-Unix ports of @command{gawk} are as follows: -@multitable {MS-Windows using MINGW} {123456789012345678901234567890123456789001234567890} +@multitable {MS-Windows with MINGW and DJGPP} {123456789012345678901234567890123456789001234567890} @cindex Zaretskii, Eli @cindex Deifik, Scott -@item MS-Windows using MINGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. +@item MS-Windows with MINGW and DJGPP @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. @item @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. @cindex Buening, Andreas @@ -28209,7 +28228,7 @@ This is an embeddable @command{awk} interpreter derived from @command{mawk}. For more information see @uref{http://repo.hu/projects/libmawk/}. -@item QSE Awk +@item @w{QSE Awk} @cindex QSE Awk @cindex source code, QSE Awk This is an embeddable @command{awk} interpreter. For more information @@ -28307,7 +28326,7 @@ as well as any considerations you should bear in mind. @node Accessing The Source @appendixsubsec Accessing The @command{gawk} Git Repository -As @command{gawk} is Free Software, the source code is always available +As @command{gawk} is Free Software, the source code is always available. @ref{Gawk Distribution}, describes how to get and build the formal, released versions of @command{gawk}. @@ -28366,6 +28385,16 @@ consider writing it as an extension module If that's not possible, continue with the rest of the steps in this list. @item +Be prepared to sign the appropriate paperwork. +In order for the FSF to distribute your changes, you must either place +those changes in the public domain and submit a signed statement to that +effect, or assign the copyright in your changes to the FSF. +Both of these actions are easy to do and @emph{many} people have done so +already. If you have questions, please contact me +(@pxref{Bugs}), +or @EMAIL{assign@@gnu.org,assign at gnu dot org}. + +@item Get the latest version. It is much easier for me to integrate changes if they are relative to the most recent distributed version of @command{gawk}. If your version of @@ -28404,7 +28433,7 @@ Use ANSI/ISO style (prototype) function headers when defining functions. Put the name of the function at the beginning of its own line. @item -Put the return type of the function, even if it is @code{int()}, on the +Put the return type of the function, even if it is @code{int}, on the line above the line with the name and arguments of the function. @item @@ -28447,6 +28476,17 @@ Do not use the @code{alloca()} function for allocating memory off the stack. Its use causes more portability trouble than is worth the minor benefit of not having to free the storage. Instead, use @code{malloc()} and @code{free()}. + +@item +Do not use comparisons of the form @samp{! strcmp(a, b)} or similar. +As Henry Spencer once said, ``@code{strcmp()} is not a boolean!'' +Instead, use @samp{strcmp(a, b) == 0}. + +@item +If adding new bit flag values, use explicit hexadecimal constants +(@code{0x001}, @code{0x002}, @code{0x004}, and son on) instead of +shifting one left by successive amounts (@samp{(1<<0)}, @samp{(1<<1)}, +and so on). @end itemize @quotation NOTE @@ -28454,16 +28494,6 @@ If I have to reformat your code to follow the coding style used in @command{gawk}, I may not bother to integrate your changes at all. @end quotation -@item -Be prepared to sign the appropriate paperwork. -In order for the FSF to distribute your changes, you must either place -those changes in the public domain and submit a signed statement to that -effect, or assign the copyright in your changes to the FSF. -Both of these actions are easy to do and @emph{many} people have done so -already. If you have questions, please contact me -(@pxref{Bugs}), -or @EMAIL{assign@@gnu.org,assign at gnu dot org}. - @cindex Texinfo @item Update the documentation. @@ -28527,6 +28557,17 @@ the previous @value{SECTION} concerning coding style, submission of diffs, and so on. @item +Be prepared to sign the appropriate paperwork. +In order for the FSF to distribute your code, you must either place +your code in the public domain and submit a signed statement to that +effect, or assign the copyright in your code to the FSF. +@ifinfo +Both of these actions are easy to do and @emph{many} people have done so +already. If you have questions, please contact me, or +@email{gnu@@gnu.org}. +@end ifinfo + +@item When doing a port, bear in mind that your code must coexist peacefully with the rest of @command{gawk} and the other ports. Avoid gratuitous changes to the system-independent parts of the code. If at all possible, @@ -28588,17 +28629,6 @@ Update the documentation. Please write a section (or sections) for this @value{DOCUMENT} describing the installation and compilation steps needed to compile and/or install @command{gawk} for your system. - -@item -Be prepared to sign the appropriate paperwork. -In order for the FSF to distribute your code, you must either place -your code in the public domain and submit a signed statement to that -effect, or assign the copyright in your code to the FSF. -@ifinfo -Both of these actions are easy to do and @emph{many} people have done so -already. If you have questions, please contact me, or -@email{gnu@@gnu.org}. -@end ifinfo @end enumerate Following these steps makes it much easier to integrate your changes @@ -28782,7 +28812,7 @@ Make sure that @samp{n->type == Node_var_array} first. @item NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference) Finds, and installs if necessary, array elements. @code{symbol} is the array, @code{subs} is the subscript. -This is usually a value created with @code{make_string} (see below). +This is usually a value created with @code{make_string()} (see below). @code{reference} should be @code{TRUE} if it is an error to use the value before it is created. Typically, @code{FALSE} is the correct value to use from extension functions. @@ -28817,7 +28847,7 @@ understanding of @command{gawk} memory management is helpful. @cindex internal function, @code{unref()} @item void unref(NODE *n) This macro releases the memory associated with a @code{NODE} -allocated with @code{make_string} or @code{make_number}. +allocated with @code{make_string()} or @code{make_number()}. Understanding of @command{gawk} memory management is helpful. @cindex @code{make_builtin()} internal function @@ -28874,7 +28904,7 @@ This is a convenience macro that calls @code{get_actual_argument()}. @item void update_ERRNO(void) This function is called from within a C extension function to set the value of @command{gawk}'s @code{ERRNO} variable, based on the current -value of the C @code{errno} variable. +value of the C @code{errno} global variable. It is provided as a convenience. @cindex @code{ERRNO} variable @@ -28882,8 +28912,8 @@ It is provided as a convenience. @cindex internal function, @code{update_ERRNO_saved()} @item void update_ERRNO_saved(int errno_saved) This function is called from within a C extension function to set -the value of @command{gawk}'s @code{ERRNO} variable, based on the saved -value of the C @code{errno} variable provided as the argument. +the value of @command{gawk}'s @code{ERRNO} variable, based on the error +value provided as the argument. It is provided as a convenience. @cindex @code{ENVIRON} array @@ -28924,13 +28954,13 @@ to the @code{IOBUF}'s @code{opaque} field (which will presumably point to a structure containing additional state associated with the input processing), and no further open hooks are called. -The function called will most likely want to set the @code{IOBUF} -@code{get_record()} method to indicate that future input records should +The function called will most likely want to set the @code{IOBUF}'s +@code{get_record} method to indicate that future input records should be retrieved by calling that method instead of using the standard @command{gawk} input processing. -And the function will also probably want to set the @code{IOBUF} -@code{close_func()} method to be called when the file is closed to clean +And the function will also probably want to set the @code{IOBUF}'s +@code{close_func} method to be called when the file is closed to clean up any state associated with the input. Finally, hook functions should be prepared to receive an @code{IOBUF} @@ -28950,11 +28980,12 @@ from a function parameter. The following boilerplate code shows how to do this: -@smallexample +@example NODE *the_arg; -the_arg = get_array_argument(2, FALSE); /* assume need 3rd arg, 0-based */ -@end smallexample +/* assume need 3rd arg, 0-based */ +the_arg = get_array_argument(2, FALSE); +@end example Again, you should spend time studying the @command{gawk} internals; don't just blindly copy this code. @@ -29001,7 +29032,7 @@ external extension library. @end menu @node Internal File Description -@appendixsubsubsec Using @code{chdir} and @code{stat} +@appendixsubsubsec Using @code{chdir()} and @code{stat()} This @value{SECTION} shows how to use the new functions at the @command{awk} level once they've been integrated into the running @command{gawk} @@ -29148,8 +29179,9 @@ of that number, respectively. Here is the C code for these extensions. They were written for GNU/Linux. The code needs some more work for complete portability to other POSIX-compliant systems:@footnote{This version is edited -slightly for presentation. The complete version can be found in -@file{extension/filefuncs.c} in the @command{gawk} distribution.} +slightly for presentation. See +@file{extension/filefuncs.c} in the @command{gawk} distribution +for the complete version.} @c break line for page breaking @example @@ -29175,7 +29207,7 @@ do_chdir(int nargs) The file includes the @code{"awk.h"} header file for definitions for the @command{gawk} internals. It includes @code{<sys/sysmacros.h>} -for access to the @code{major} and @code{minor} macros. +for access to the @code{major()} and @code{minor}() macros. @cindex programming conventions, @command{gawk} internals By convention, for an @command{awk} function @code{foo}, the function that @@ -29183,12 +29215,12 @@ implements it is called @samp{do_foo}. The function should take a @samp{int} argument, usually called @code{nargs}, that represents the number of defined arguments for the function. The @code{newdir} variable represents the new directory to change to, retrieved -with @code{get_scalar_argument}. Note that the first argument is +with @code{get_scalar_argument()}. Note that the first argument is numbered zero. -This code actually accomplishes the @code{chdir}. It first forces +This code actually accomplishes the @code{chdir()}. It first forces the argument to be a string and passes the string value to the -@code{chdir} system call. If the @code{chdir} fails, @code{ERRNO} +@code{chdir()} system call. If the @code{chdir()} fails, @code{ERRNO} is updated. @example @@ -29205,7 +29237,7 @@ Finally, the function returns the return value to the @command{awk} level: @} @end example -The @code{stat} built-in is more involved. First comes a function +The @code{stat()} built-in is more involved. First comes a function that turns a numeric mode into a printable representation (e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity: @@ -29220,7 +29252,7 @@ format_mode(unsigned long fmode) @} @end example -Next comes the @code{do_stat} function. It starts with +Next comes the @code{do_stat()} function. It starts with variable declarations and argument checking: @ignore @@ -29253,7 +29285,7 @@ If there's an error, it sets @code{ERRNO} and returns: @c comment made multiline for page breaking @example - /* directory is first arg, array to hold results is second */ + /* file is first arg, array to hold results is second */ file = get_scalar_argument(0, FALSE); array = get_array_argument(1, FALSE); @@ -29299,7 +29331,7 @@ When done, return the @code{lstat()} return value: @cindex programming conventions, @command{gawk} internals Finally, it's necessary to provide the ``glue'' that loads the new function(s) into @command{gawk}. By convention, each library has -a routine named @code{dlload} that does the job: +a routine named @code{dlload()} that does the job: @example /* dlload --- load new builtins in this library */ |