diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 3435 |
1 files changed, 1774 insertions, 1661 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 25120ddb..7e013b6e 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -90,10 +90,10 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Library Functions:: A Library of `awk' Functions. * Sample Programs:: Many `awk' programs with complete explanations. -* Internationalization:: Getting `gawk' to speak your - language. * Advanced Features:: Stuff for advanced users, specific to `gawk'. +* Internationalization:: Getting `gawk' to speak your + language. * Debugger:: The `gawk' debugger. * Arbitrary Precision Arithmetic:: Arbitrary precision arithmetic with `gawk'. @@ -446,17 +446,6 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Anagram Program:: Finding anagrams from a dictionary. * Signature Program:: People do amazing things with too much time on their hands. -* I18N and L10N:: Internationalization and Localization. -* Explaining gettext:: How GNU `gettext' works. -* Programmer i18n:: Features for the programmer. -* Translator i18n:: Features for the translator. -* String Extraction:: Extracting marked strings. -* Printf Ordering:: Rearranging `printf' arguments. -* I18N Portability:: `awk'-level portability - issues. -* I18N Example:: A simple i18n example. -* Gawk I18N:: `gawk' is also - internationalized. * Nondecimal Data:: Allowing nondecimal input data. * Array Sorting:: Facilities for controlling array traversal and sorting arrays. @@ -468,6 +457,17 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * TCP/IP Networking:: Using `gawk' for network programming. * Profiling:: Profiling your `awk' programs. +* I18N and L10N:: Internationalization and Localization. +* Explaining gettext:: How GNU `gettext' works. +* Programmer i18n:: Features for the programmer. +* Translator i18n:: Features for the translator. +* String Extraction:: Extracting marked strings. +* Printf Ordering:: Rearranging `printf' arguments. +* I18N Portability:: `awk'-level portability + issues. +* I18N Example:: A simple i18n example. +* Gawk I18N:: `gawk' is also + internationalized. * Debugging:: Introduction to `gawk' debugger. * Debugging Concepts:: Debugging in General. @@ -528,7 +528,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Output Wrappers:: Registering an output wrapper. * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. -* Updating `ERRNO':: Functions for updating `ERRNO'. +* Updating `ERRNO':: Functions for updating `ERRNO'. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -632,13 +632,14 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) `git' repository. * Future Extensions:: New features that may be implemented one day. -* Implementation Limitations:: Some limitations of the implementation. +* Implementation Limitations:: Some limitations of the + implementation. * Extension Design:: Design notes about the extension API. * Old Extension Problems:: Problems with the old mechanism. * Extension New Mechanism Goals:: Goals for the new mechanism. * Extension Other Design Decisions:: Some other design decisions. * Extension Future Growth:: Some room for future growth. -* Old Extension Mechansim:: Some compatibility for old extensions. +* Old Extension Mechanism:: Some compatibility for old extensions. * Basic High Level:: The high level view. * Basic Data Typing:: A very quick intro to data types. @@ -813,7 +814,7 @@ those systems has been removed.) ---------- Footnotes ---------- - (1) The 2008 POSIX standard can be found online at + (1) The 2008 POSIX standard is online at `http://www.opengroup.org/onlinepubs/9699919799/'. (2) These commands are available on POSIX-compliant systems, as well @@ -832,13 +833,13 @@ History of `awk' and `gawk' 1 part `egrep' 1 part `snobol' 2 parts `ed' 3 parts C - Blend all parts well using `lex' and `yacc'. Document minimally - and release. + Blend all parts well using `lex' and `yacc'. Document minimally and +release. - After eight years, add another part `egrep' and two more parts C. - Document very well and release. + After eight years, add another part `egrep' and two more parts C. +Document very well and release. - The name `awk' comes from the initials of its designers: Alfred V. +The name `awk' comes from the initials of its designers: Alfred V. Aho, Peter J. Weinberger and Brian W. Kernighan. The original version of `awk' was written in 1977 at AT&T Bell Laboratories. In 1985, a new version made the programming language more powerful, introducing @@ -928,11 +929,10 @@ differences between `gawk' and other `awk' implementations.(1) Finally, any `gawk' features that are not in the POSIX standard for `awk' are noted. - There are subsections labeled as *Advanced Notes* scattered -throughout the Info file. They add a more complete explanation of -points that are relevant, but not likely to be of interest on first -reading. All appear in the index, under the heading "advanced -features." + There are sidebars scattered throughout the Info file. They add a +more complete explanation of points that are relevant, but not likely +to be of interest on first reading. All appear in the index, under the +heading "sidebar." Most of the time, the examples use complete `awk' programs. Some of the more advanced sections show only the part of the `awk' program that @@ -997,14 +997,14 @@ problems. Part III focuses on features specific to `gawk'. It contains the following chapters: - *note Internationalization::, describes special features in `gawk' -for translating program messages into different languages at runtime. - *note Advanced Features::, describes a number of `gawk'-specific advanced features. Of particular note are the abilities to have two-way communications with another process, perform TCP/IP networking, and profile your `awk' programs. + *note Internationalization::, describes special features in `gawk' +for translating program messages into different languages at runtime. + *note Debugger::, describes the `awk' debugger. *note Arbitrary Precision Arithmetic::, describes advanced @@ -1054,11 +1054,11 @@ File: gawk.info, Node: Conventions, Next: Manual History, Prev: This Manual, Typographical Conventions ========================= -This Info file is written in Texinfo (http://texinfo.org), the GNU -documentation formatting language. A single Texinfo source file is -used to produce both the printed and online versions of the -documentation. This minor node briefly documents the typographical -conventions used in Texinfo. +This Info file is written in Texinfo +(http://www.gnu.org/software/texinfo/), the GNU documentation +formatting language. A single Texinfo source file is used to produce +both the printed and online versions of the documentation. This minor +node briefly documents the typographical conventions used in Texinfo. Examples you would type at the command-line are preceded by the common shell primary and secondary prompts, `$' and `>'. Input that @@ -1154,9 +1154,12 @@ Guide'. This edition maintains the basic structure of the previous editions. For Edition 4.0, the content has been thoroughly reviewed and updated. -All references to versions prior to 4.0 have been removed. Of +All references to `gawk' versions prior to 4.0 have been removed. Of significant note for this edition is *note Debugger::. + For edition 4.1, the content has been reorganized into parts, and +the major new addition is *note Dynamic Extensions::. + `GAWK: Effective AWK Programming' will undoubtedly continue to evolve. An electronic version comes with the `gawk' distribution from the FSF. If you find an error in this Info file, please report it! @@ -1252,30 +1255,25 @@ acknowledgements: Ulrich Drepper, provided invaluable help and feedback for the design of the internationalization features. - Chuck Toporek, Mary Sheehan, and Claire Coutier of O'Reilly & + Chuck Toporek, Mary Sheehan, and Claire Cloutier of O'Reilly & Associates contributed significant editorial help for this Info file for the 3.1 release of `gawk'. - Dr. Nelson Beebe, Andreas Buening, Antonio Colombo, Stephen Davies, -Scott Deifik, John H. DuBois III, Darrel Hankerson, Michal Jaegermann, -Ju"rgen Kahrs, Dave Pitts, Stepan Kasal, Pat Rankin, Andrew Schorr, -Corinna Vinschen, Anders Wallin, and Eli Zaretskii (in alphabetical -order) make up the current `gawk' "crack portability team." Without -their hard work and help, `gawk' would not be nearly the fine program -it is today. It has been and continues to be a pleasure working with -this team of fine people. - - John Haque contributed the modifications to convert `gawk' into a -byte-code interpreter, including the debugger, and the additional -modifications for support of arbitrary precision arithmetic. Stephen -Davies contributed to the effort to bring the byte-code changes into -the mainstream code base. Efraim Yawitz contributed the initial text -of *note Debugger::. John Haque contributed the initial text of *note -Arbitrary Precision Arithmetic::. + Dr. Nelson Beebe, Andreas Buening, Dr. Manuel Collado, Antonio +Colombo, Stephen Davies, Scott Deifik, Akim Demaille, Darrel Hankerson, +Michal Jaegermann, Ju"rgen Kahrs, Stepan Kasal, John Malmberg, Dave +Pitts, Chet Ramey, Pat Rankin, Andrew Schorr, Corinna Vinschen, Anders +Wallin, and Eli Zaretskii (in alphabetical order) make up the current +`gawk' "crack portability team." Without their hard work and help, +`gawk' would not be nearly the fine program it is today. It has been +and continues to be a pleasure working with this team of fine people. + + Notable code and documentation contributions were made by a number +of people. *Note Contributors::, for the full list. I would like to thank Brian Kernighan for invaluable assistance during the testing and debugging of `gawk', and for ongoing help and -advice in clarifying numerous points about the language. We could not +advice in clarifying numerous points about the language. We could not have done nearly as good a job on either `gawk' or its documentation without his help. @@ -1291,7 +1289,7 @@ to take advantage of those opportunities. Arnold Robbins Nof Ayalon ISRAEL -March, 2011 +April, 2013 File: gawk.info, Node: Getting Started, Next: Invoking Gawk, Prev: Preface, Up: Top @@ -1532,11 +1530,10 @@ at the shell.) program that users can invoke without their having to know that the program is written in `awk'. -Advanced Notes: Portability Issues with `#!' --------------------------------------------- + Portability Issues with `#!' -Some systems limit the length of the interpreter name to 32 characters. -Often, this can be dealt with by using a symbolic link. + Some systems limit the length of the interpreter name to 32 +characters. Often, this can be dealt with by using a symbolic link. You should not put more than one argument on the `#!' line after the path to `awk'. It does not work. The operating system treats the rest @@ -2320,10 +2317,10 @@ The following list describes options mandated by the POSIX standard: there are two important differences. First, when `-i' is used, the program source will not be loaded if it has been previously loaded, whereas the `-f' will always load the file. Second, - because this option is intended to be used with code libraries, the - `awk' command does not recognize such files as constituting main - program input. Thus, after processing an `-i' argument, we still - expect to find the main source code via the `-f' option or on the + because this option is intended to be used with code libraries, + `gawk' does not recognize such files as constituting main program + input. Thus, after processing an `-i' argument, `gawk' still + expects to find the main source code via the `-f' option or on the command-line. `-v VAR=VAL' @@ -2816,7 +2813,9 @@ variable, but it is used to search for shared libraries specified with the `-l' option rather than for source files. If the library is not found, the path is searched again after adding the appropriate shared library suffix for the platform. For example, on GNU/Linux systems, -the suffix `.so' is used. +the suffix `.so' is used. The search path specified is also used for +libraries loaded via the `@load' keyword (*note Loading Shared +Libraries::). File: gawk.info, Node: Other Environment Variables, Prev: AWKLIBPATH Variable, Up: Environment Variables @@ -3028,6 +3027,9 @@ For command-line usage, the `-l' option is more convenient, but `@load' is useful for embedding inside an `awk' source file that requires access to a shared library. + *note Dynamic Extensions::, describes how to write extensions (in C +or C++) that can be loaded with either `@load' or the `-l' option. + File: gawk.info, Node: Obsolete, Next: Undocumented, Prev: Loading Shared Libraries, Up: Invoking Gawk @@ -3256,11 +3258,10 @@ character not shown in the previous list. * A backslash before any other character means to treat that character literally. -Advanced Notes: Backslash Before Regular Characters ---------------------------------------------------- + Backslash Before Regular Characters -If you place a backslash in a string constant before something that is -not one of the characters previously listed, POSIX `awk' purposely + If you place a backslash in a string constant before something that +is not one of the characters previously listed, POSIX `awk' purposely leaves what happens as undefined. There are two choices: Strip the backslash out @@ -3275,10 +3276,9 @@ Leave the backslash alone Some other `awk' implementations do this. In such implementations, typing `"a\qc"' is the same as typing `"a\\qc"'. -Advanced Notes: Escape Sequences for Metacharacters ---------------------------------------------------- + Escape Sequences for Metacharacters -Suppose you use an octal or hexadecimal escape to represent a regexp + Suppose you use an octal or hexadecimal escape to represent a regexp metacharacter. (See *note Regexp Operators::.) Does `awk' treat the character as a literal character or as a regexp operator? @@ -3820,11 +3820,10 @@ constants," for several reasons: * Using regexp constants is better form; it shows clearly that you intend a regexp match. -Advanced Notes: Using `\n' in Bracket Expressions of Dynamic Regexps --------------------------------------------------------------------- + Using `\n' in Bracket Expressions of Dynamic Regexps -Some commercial versions of `awk' do not allow the newline character to -be used inside a bracket expression for a dynamic regexp: + Some commercial versions of `awk' do not allow the newline character +to be used inside a bracket expression for a dynamic regexp: $ awk '$0 ~ "[ \t\n]"' error--> awk: newline in character class [ @@ -4061,10 +4060,9 @@ that this will never happen. Options::). In compatibility mode, only the first character of the value of `RS' is used to determine the end of the record. -Advanced Notes: `RS = "\0"' Is Not Portable -------------------------------------------- + `RS = "\0"' Is Not Portable -There are times when you might want to treat an entire data file as a + 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 `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 @@ -4344,11 +4342,10 @@ fields using the _current_ value of `FS'. This also applies to any built-in function that updates `$0', such as `sub()' and `gsub()' (*note String Functions::). -Advanced Notes: Understanding `$0' ----------------------------------- + Understanding `$0' -It is important to remember that `$0' is the _full_ record, exactly as -it was read from the input. This includes any leading or trailing + It is important to remember that `$0' is the _full_ record, exactly +as it was read from the input. This includes any leading or trailing whitespace, and the exact whitespace (or other characters) that separate the fields. @@ -4677,14 +4674,13 @@ value of `FS' (`==' means "is equal to"): (This is a `gawk' extension; it is not specified by the POSIX standard.) -Advanced Notes: Changing `FS' Does Not Affect the Fields --------------------------------------------------------- + Changing `FS' Does Not Affect the Fields -According to the POSIX standard, `awk' is supposed to behave as if each -record is split into fields at the time it is read. In particular, -this means that if you change the value of `FS' after a record is read, -the value of the fields (i.e., how they were split) should reflect the -old value of `FS', not the new one. + According to the POSIX standard, `awk' is supposed to behave as if +each record is split into fields at the time it is read. In +particular, this means that if you change the value of `FS' after a +record is read, the value of the fields (i.e., how they were split) +should reflect the old value of `FS', not the new one. However, many older implementations of `awk' do not work this way. Instead, they defer splitting the fields until a field is actually @@ -4704,10 +4700,9 @@ like: root:nSijPlPhZZwgE:0:0:Root:/: -Advanced Notes: `FS' and `IGNORECASE' -------------------------------------- + `FS' and `IGNORECASE' -The `IGNORECASE' variable (*note User-modified::) affects field + The `IGNORECASE' variable (*note User-modified::) affects field splitting _only_ when the value of `FS' is a regexp. It has no effect when `FS' is a single character, even if that character is a letter. Thus, in the following code: @@ -5161,8 +5156,8 @@ searching for matches of a regular expression. (This program has a subtle problem--it does not work if one comment ends and another begins on the same line.) - This form of the `getline' command sets `NF', `NR', `FNR', and the -value of `$0'. + This form of the `getline' command sets `NF', `NR', `FNR', `RT', and +the value of `$0'. NOTE: The new value of `$0' is used to test the patterns of any subsequent rules. The original value of `$0' that triggered the @@ -5207,10 +5202,10 @@ and produces these results: phore free - The `getline' command used in this way sets only the variables `NR' -and `FNR' (and of course, VAR). The record is not split into fields, -so the values of the fields (including `$0') and the value of `NF' do -not change. + The `getline' command used in this way sets only the variables `NR', +`FNR' and `RT' (and of course, VAR). The record is not split into +fields, so the values of the fields (including `$0') and the value of +`NF' do not change. File: gawk.info, Node: Getline/File, Next: Getline/Variable/File, Prev: Getline/Variable, Up: Getline @@ -5236,7 +5231,7 @@ with a value equal to 10 in the current input file: Because the main input stream is not used, the values of `NR' and `FNR' are not changed. However, the record it reads is split into fields in the normal manner, so the values of `$0' and the other fields -are changed, resulting in a new value of `NF'. +are changed, resulting in a new value of `NF'. `RT' is also set. According to POSIX, `getline < EXPRESSION' is ambiguous if EXPRESSION contains unparenthesized operators other than `$'; for @@ -5343,7 +5338,7 @@ different results, depending upon who is logged in on your system.) This variation of `getline' splits the record into fields, sets the value of `NF', and recomputes the value of `$0'. The values of `NR' -and `FNR' are not changed. +and `FNR' are not changed. `RT' is set. According to POSIX, `EXPRESSION | getline' is ambiguous if EXPRESSION contains unparenthesized operators other than `$'--for @@ -5411,7 +5406,7 @@ which sends a query to `db_server' and then reads the results. The values of `NR' and `FNR' are not changed, because the main input stream is not used. However, the record is split into fields in the normal manner, thus changing the values of `$0', of the other fields, -and of `NF'. +and of `NF' and `RT'. Coprocesses are an advanced feature. They are discussed here only because this is the minor node on `getline'. *Note Two-way I/O::, @@ -5429,7 +5424,7 @@ variable VAR. In this version of `getline', none of the built-in variables are changed and the record is not split into fields. The only variable -changed is VAR. +changed is VAR. However, `RT' is set. Coprocesses are an advanced feature. They are discussed here only because this is the minor node on `getline'. *Note Two-way I/O::, @@ -5510,14 +5505,15 @@ Variant Effect Standard / Extension ------------------------------------------------------------------------- `getline' Sets `$0', `NF', `FNR', Standard - and `NR' -`getline' VAR Sets VAR, `FNR', and `NR' Standard -`getline <' FILE Sets `$0' and `NF' Standard -`getline VAR < FILE' Sets VAR Standard -COMMAND `| getline' Sets `$0' and `NF' Standard -COMMAND `| getline' VAR Sets VAR Standard -COMMAND `|& getline' Sets `$0' and `NF' Extension -COMMAND `|& getline' Sets VAR Extension + `NR', and `RT' +`getline' VAR Sets VAR, `FNR', `NR', and Standard + `RT' +`getline <' FILE Sets `$0', `NF', and `RT' Standard +`getline VAR < FILE' Sets VAR and `RT' Standard +COMMAND `| getline' Sets `$0', `NF', and `RT' Standard +COMMAND `| getline' VAR Sets VAR and `RT' Standard +COMMAND `|& getline' Sets `$0', `NF', and `RT' Extension +COMMAND `|& getline' Sets VAR and `RT' Extension VAR Table 4.1: `getline' Variants and What They Set @@ -5535,8 +5531,8 @@ special element in the `PROCINFO' array: PROCINFO["input_name", "READ_TIMEOUT"] = TIMEOUT IN MILLISECONDS - When set, this will cause `gawk' to time out and return failure if -no data is available to read within the specified timeout period. For + When set, this causes `gawk' to time out and return failure if no +data is available to read within the specified timeout period. For example, a TCP client can decide to give up on receiving any response from the server after a certain amount of time: @@ -6382,14 +6378,13 @@ an `awk' program may have open to just one! In `gawk', there is no such limit. `gawk' allows a program to open as many pipelines as the underlying operating system permits. -Advanced Notes: Piping into `sh' --------------------------------- + Piping into `sh' -A particularly powerful way to use redirection is to build command lines -and pipe them into the shell, `sh'. For example, suppose you 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: + A particularly powerful way to use redirection is to build command +lines and pipe them into the shell, `sh'. For example, suppose you +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: { printf("mv %s %s\n", $0, tolower($0)) | "sh" } @@ -6489,7 +6484,7 @@ redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. Finally, using the `close()' function on a file name of the form -`"/dev/fd/N"', for file descriptor numbers above two, will actually +`"/dev/fd/N"', for file descriptor numbers above two, does actually close the given file descriptor. The `/dev/stdin', `/dev/stdout', and `/dev/stderr' special files are @@ -6667,10 +6662,9 @@ The second argument should be a string, with either of the values feature, a more complete discussion is delayed until *note Two-way I/O::, which discusses it in more detail and gives an example. -Advanced Notes: Using `close()''s Return Value ----------------------------------------------- + Using `close()''s Return Value -In many versions of Unix `awk', the `close()' function is actually a + In many versions of Unix `awk', the `close()' function is actually a statement. It is a syntax error to try and use the return value from `close()': (d.c.) @@ -6867,10 +6861,9 @@ octal constants; e.g., `gawk' treats `018' as decimal 18: If `gawk' is in compatibility mode (*note Options::), they are not available. -Advanced Notes: A Constant's Base Does Not Affect Its Value ------------------------------------------------------------ + A Constant's Base Does Not Affect Its Value -Once a numeric constant has been converted internally into a number, + Once a numeric constant has been converted internally into a number, `gawk' no longer remembers what the original form of the constant was; the internal value is always used. This has particular consequences for conversion of numbers to strings: @@ -7536,12 +7529,11 @@ Table 6.2: Arithmetic Assignment Operators NOTE: Only the `^=' operator is specified by POSIX. For maximum portability, do not use the `**=' operator. -Advanced Notes: Syntactic Ambiguities Between `/=' and Regular Expressions --------------------------------------------------------------------------- + Syntactic Ambiguities Between `/=' and Regular Expressions -There is a syntactic ambiguity between the `/=' assignment operator and -regexp constants whose first character is an `='. (d.c.) This is most -notable in commercial `awk' versions. For example: + There is a syntactic ambiguity between the `/=' assignment operator +and regexp constants whose first character is an `='. (d.c.) This is +most notable in some commercial `awk' versions. For example: $ awk /==/ /dev/null error--> awk: syntax error at source line 1 @@ -7614,8 +7606,7 @@ is a summary of increment and decrement expressions: of the expression. (This expression is like `LVALUE++', but instead of adding, it subtracts.) -Advanced Notes: Operator Evaluation Order ------------------------------------------ + Operator Evaluation Order Doctor, doctor! It hurts when I do this! So don't do that! @@ -9337,7 +9328,7 @@ statement accomplishes this much more efficiently. In `gawk', execution of `nextfile' causes additional things to happen: any `ENDFILE' rules are executed except in the case as mentioned below, `ARGIND' is incremented, and any `BEGINFILE' rules are -executed (`ARGIND' hasn't been introduced yet. *Note Built-in +executed. (`ARGIND' hasn't been introduced yet. *Note Built-in Variables::.) With `gawk', `nextfile' is useful inside a `BEGINFILE' rule to skip @@ -9582,7 +9573,7 @@ specific to `gawk' are marked with a pound sign (`#'). `PREC #' The working precision of arbitrary precision floating-point - numbers, 53 by default (*note Setting Precision::). + numbers, 53 bits by default (*note Setting Precision::). `ROUNDMODE #' The rounding mode to use for arbitrary precision arithmetic on @@ -9744,10 +9735,10 @@ with a pound sign (`#'). Fields::. `FUNCTAB #' - An array whose indices are the names of all the user-defined or - extension functions in the program. *NOTE*: The array values - cannot currently be used. Also, you may not use the `delete' - statement with the `FUNCTAB' array. + 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. `NR' The number of input records `awk' has processed since the @@ -9844,14 +9835,31 @@ with a pound sign (`#'). `PROCINFO["prec_min"]' The minimum precision required by MPFR. + The following additional elements in the array are available to + provide information about the version of the extension API, if + your version of `gawk' supports dynamic loading of extension + functions (*note Dynamic Extensions::): + + `PROCINFO["api_major"]' + The major version of the extension API. + + `PROCINFO["api_minor"]' + The minor version of the extension API. + On some systems, there may be elements in the array, `"group1"' through `"groupN"' for some N. N is the number of supplementary groups that the process has. Use the `in' operator to test for these elements (*note Reference to Elements::). - The `PROCINFO' array is also used to cause coprocesses to - communicate over pseudo-ttys instead of through two-way pipes; - this is discussed further in *note Two-way I/O::. + The `PROCINFO' array has the following additional uses: + + * It may be used to cause coprocesses to communicate over + pseudo-ttys instead of through two-way pipes; this is + discussed further in *note Two-way I/O::. + + * It may be used to provide a timeout when reading from any + open input file, pipe, or coprocess. *Note Read Timeout::, + for more information. This array is a `gawk' extension. In other `awk' implementations, or if `gawk' is in compatibility mode (*note Options::), it is not @@ -9916,14 +9924,13 @@ with a pound sign (`#'). neither `FUNCTAB' nor `SYMTAB' are available as elements within the `SYMTAB' array. -Advanced Notes: Changing `NR' and `FNR' ---------------------------------------- + Changing `NR' and `FNR' -`awk' increments `NR' and `FNR' each time it reads a record, instead of -setting them to the absolute value of the number of records read. This -means that a program can change these variables and their new values -are incremented for each record. (d.c.) The following example shows -this: + `awk' increments `NR' and `FNR' each time it reads a record, instead +of setting them to the absolute value of the number of records read. +This means that a program can change these variables and their new +values are incremented for each record. (d.c.) The following example +shows this: $ echo '1 > 2 @@ -10403,15 +10410,15 @@ internal implementation of arrays and will vary from one version of Often, though, you may wish to do something simple, such as "traverse the array by comparing the indices in ascending order," or -"traverse the array by on comparing the values in descending order." +"traverse the array by comparing the values in descending order." `gawk' provides two mechanisms which give you this control. * Set `PROCINFO["sorted_in"]' to one of a set of predefined values. We describe this now. * Set `PROCINFO["sorted_in"]' to the name of a user-defined function - to be used for comparison of array elements. This advanced feature - is described later, in *note Array Sorting::. + to use for comparison of array elements. This advanced feature is + described later, in *note Array Sorting::. The following special values for `PROCINFO["sorted_in"]' are available: @@ -10467,10 +10474,8 @@ available: Subarrays, if present, come out first. The array traversal order is determined before the `for' loop starts -to run. Changing `PROCINFO["sorted_in"]' in the loop body will not -affect the loop. - - For example: +to run. Changing `PROCINFO["sorted_in"]' in the loop body does not +affect the loop. For example: $ gawk 'BEGIN { > a[4] = 4 @@ -10939,7 +10944,7 @@ the following code prints the elements of our main array `a': } } -*Note Walking Arrays::, for a user-defined function that will "walk" an +*Note Walking Arrays::, for a user-defined function that "walks" an arbitrarily-dimensioned array of arrays. Recall that a reference to an uninitialized array element yields a @@ -11873,10 +11878,9 @@ Table 9.5: Escape Sequence Processing For `gensub()' and the special cases for `sub()' and `gsub()', we recommend the use of `gawk' and `gensub()' when you have to do substitutions. -Advanced Notes: Matching the Null String ----------------------------------------- + Matching the Null String -In `awk', the `*' operator can match the null string. This is + In `awk', the `*' operator can match the null string. This is particularly important for the `sub()', `gsub()', and `gensub()' functions. For example: @@ -11997,12 +12001,11 @@ parameters are enclosed in square brackets ([ ]): is disabled (*note Options::). -Advanced Notes: Interactive Versus Noninteractive Buffering ------------------------------------------------------------ + Interactive Versus Noninteractive Buffering -As a side point, buffering issues can be even more confusing, depending -upon whether your program is "interactive", i.e., communicating with a -user sitting at a keyboard.(1) + As a side point, buffering issues can be even more confusing, +depending upon whether your program is "interactive", i.e., +communicating with a user sitting at a keyboard.(1) Interactive programs generally "line buffer" their output; i.e., they write out every line. Noninteractive programs wait until they have a @@ -12029,13 +12032,13 @@ this example: Here, no output is printed until after the `Ctrl-d' is typed, because it is all buffered and sent down the pipe to `cat' in one shot. -Advanced Notes: Controlling Output Buffering with `system()' ------------------------------------------------------------- + Controlling Output Buffering with `system()' -The `fflush()' function provides explicit control over output buffering -for individual files and pipes. However, its use is not portable to -many older `awk' implementations. An alternative method to flush output -buffers is to call `system()' with a null string as its argument: + The `fflush()' function provides explicit control over output +buffering for individual files and pipes. However, its use is not +portable to many older `awk' implementations. An alternative method to +flush output buffers is to call `system()' with a null string as its +argument: system("") # flush output @@ -13045,8 +13048,9 @@ problem if a program calls an undefined function. If `--lint' is specified (*note Options::), `gawk' reports calls to undefined functions. - Some `awk' implementations generate a runtime error if you use the -`next' statement (*note Next Statement::) inside a user-defined + Some `awk' implementations generate a runtime error if you use +either the `next' statement or the `nextfile' statement (*note Next +Statement::, also *note Nextfile Statement::) inside a user-defined function. `gawk' does not have this limitation. @@ -14214,12 +14218,11 @@ solves the problem: *note Wc Program::, shows how this library function can be used and how it simplifies writing the main program. -Advanced Notes: So Why Does `gawk' have `BEGINFILE' and `ENDFILE'? ------------------------------------------------------------------- + So Why Does `gawk' have `BEGINFILE' and `ENDFILE'? -You are probably wondering, if `beginfile()' and `endfile()' functions -can do the job, why does `gawk' have `BEGINFILE' and `ENDFILE' patterns -(*note BEGINFILE/ENDFILE::)? + You are probably wondering, if `beginfile()' and `endfile()' +functions can do the job, why does `gawk' have `BEGINFILE' and +`ENDFILE' patterns (*note BEGINFILE/ENDFILE::)? Good question. Normally, if `awk' cannot open a file, this causes an immediate fatal error. In this case, there is no way for a @@ -15221,8 +15224,20 @@ value. Here is a main program to demonstrate: -| a[2][2] = 22 -| a[3] = 3 + Walking an array and processing each element is a general-purpose +operation. You might want to consider generalizing the `walk_array()' +function by adding an additional parameter named `process'. + + Then, inside the loop, instead of simply printing the array element's +index and value, use the indirect function call syntax (*note Indirect +Calls::) on `process', passing it the index and the value. + + When calling `walk_array()', you would pass the name of a +user-defined function that expects to receive and index and a value, +and then processes the element. + -File: gawk.info, Node: Sample Programs, Next: Internationalization, Prev: Library Functions, Up: Top +File: gawk.info, Node: Sample Programs, Next: Advanced Features, Prev: Library Functions, Up: Top 11 Practical `awk' Programs *************************** @@ -17056,10 +17071,11 @@ to experiment with these programs, it is tedious to have to type them in by hand. Here we present a program that can extract parts of a Texinfo input file into separate files. -This Info file is written in Texinfo (http://texinfo.org), the GNU -project's document formatting language. A single Texinfo source file -can be used to produce both printed and online documentation. The -Texinfo language is described fully, starting with *note (Texinfo)Top:: +This Info file is written in Texinfo +(http://www.gnu.org/software/texinfo/), the GNU project's document +formatting language. A single Texinfo source file can be used to +produce both printed and online documentation. The Texinfo language is +described fully, starting with *note (Texinfo)Top:: texinfo,Texinfo--The GNU Documentation Format. For our purposes, it is enough to know three things about Texinfo @@ -17840,589 +17856,9 @@ supplies the following copyright terms: We leave it to you to determine what the program does. -File: gawk.info, Node: Internationalization, Next: Advanced Features, Prev: Sample Programs, Up: Top - -12 Internationalization with `gawk' -*********************************** - -Once upon a time, computer makers wrote software that worked only in -English. Eventually, hardware and software vendors noticed that if -their systems worked in the native languages of non-English-speaking -countries, they were able to sell more systems. As a result, -internationalization and localization of programs and software systems -became a common practice. - - For many years, the ability to provide internationalization was -largely restricted to programs written in C and C++. This major node -describes the underlying library `gawk' uses for internationalization, -as well as how `gawk' makes internationalization features available at -the `awk' program level. Having internationalization available at the -`awk' level gives software developers additional flexibility--they are -no longer forced to write in C or C++ when internationalization is a -requirement. - -* Menu: - -* I18N and L10N:: Internationalization and Localization. -* Explaining gettext:: How GNU `gettext' works. -* Programmer i18n:: Features for the programmer. -* Translator i18n:: Features for the translator. -* I18N Example:: A simple i18n example. -* Gawk I18N:: `gawk' is also internationalized. - - -File: gawk.info, Node: I18N and L10N, Next: Explaining gettext, Up: Internationalization - -12.1 Internationalization and Localization -========================================== - -"Internationalization" means writing (or modifying) a program once, in -such a way that it can use multiple languages without requiring further -source-code changes. "Localization" means providing the data necessary -for an internationalized program to work in a particular language. -Most typically, these terms refer to features such as the language used -for printing error messages, the language used to read responses, and -information related to how numerical and monetary values are printed -and read. - - -File: gawk.info, Node: Explaining gettext, Next: Programmer i18n, Prev: I18N and L10N, Up: Internationalization - -12.2 GNU `gettext' -================== - -The facilities in GNU `gettext' focus on messages; strings printed by a -program, either directly or via formatting with `printf' or -`sprintf()'.(1) - - When using GNU `gettext', each application has its own "text -domain". This is a unique name, such as `kpilot' or `gawk', that -identifies the application. A complete application may have multiple -components--programs written in C or C++, as well as scripts written in -`sh' or `awk'. All of the components use the same text domain. - - To make the discussion concrete, assume we're writing an application -named `guide'. Internationalization consists of the following steps, -in this order: - - 1. The programmer goes through the source for all of `guide''s - components and marks each string that is a candidate for - translation. For example, `"`-F': option required"' is a good - candidate for translation. A table with strings of option names - is not (e.g., `gawk''s `--profile' option should remain the same, - no matter what the local language). - - 2. The programmer indicates the application's text domain (`"guide"') - to the `gettext' library, by calling the `textdomain()' function. - - 3. Messages from the application are extracted from the source code - and collected into a portable object template file (`guide.pot'), - which lists the strings and their translations. The translations - are initially empty. The original (usually English) messages - serve as the key for lookup of the translations. - - 4. For each language with a translator, `guide.pot' is copied to a - portable object file (`.po') and translations are created and - shipped with the application. For example, there might be a - `fr.po' for a French translation. - - 5. Each language's `.po' file is converted into a binary message - object (`.mo') file. A message object file contains the original - messages and their translations in a binary format that allows - fast lookup of translations at runtime. - - 6. When `guide' is built and installed, the binary translation files - are installed in a standard place. - - 7. For testing and development, it is possible to tell `gettext' to - use `.mo' files in a different directory than the standard one by - using the `bindtextdomain()' function. - - 8. At runtime, `guide' looks up each string via a call to - `gettext()'. The returned string is the translated string if - available, or the original string if not. - - 9. If necessary, it is possible to access messages from a different - text domain than the one belonging to the application, without - having to switch the application's default text domain back and - forth. - - In C (or C++), the string marking and dynamic translation lookup are -accomplished by wrapping each string in a call to `gettext()': - - printf("%s", gettext("Don't Panic!\n")); - - The tools that extract messages from source code pull out all -strings enclosed in calls to `gettext()'. - - The GNU `gettext' developers, recognizing that typing `gettext(...)' -over and over again is both painful and ugly to look at, use the macro -`_' (an underscore) to make things easier: - - /* In the standard header file: */ - #define _(str) gettext(str) - - /* In the program text: */ - printf("%s", _("Don't Panic!\n")); - -This reduces the typing overhead to just three extra characters per -string and is considerably easier to read as well. - - There are locale "categories" for different types of locale-related -information. The defined locale categories that `gettext' knows about -are: - -`LC_MESSAGES' - Text messages. This is the default category for `gettext' - operations, but it is possible to supply a different one - explicitly, if necessary. (It is almost never necessary to supply - a different category.) - -`LC_COLLATE' - Text-collation information; i.e., how different characters and/or - groups of characters sort in a given language. - -`LC_CTYPE' - Character-type information (alphabetic, digit, upper- or - lowercase, and so on). This information is accessed via the POSIX - character classes in regular expressions, such as `/[[:alnum:]]/' - (*note Regexp Operators::). - -`LC_MONETARY' - Monetary information, such as the currency symbol, and whether the - symbol goes before or after a number. - -`LC_NUMERIC' - Numeric information, such as which characters to use for the - decimal point and the thousands separator.(2) - -`LC_RESPONSE' - Response information, such as how "yes" and "no" appear in the - local language, and possibly other information as well. - -`LC_TIME' - Time- and date-related information, such as 12- or 24-hour clock, - month printed before or after the day in a date, local month - abbreviations, and so on. - -`LC_ALL' - All of the above. (Not too useful in the context of `gettext'.) - - ---------- Footnotes ---------- - - (1) For some operating systems, the `gawk' port doesn't support GNU -`gettext'. Therefore, these features are not available if you are -using one of those operating systems. Sorry. - - (2) Americans use a comma every three decimal places and a period -for the decimal point, while many Europeans do exactly the opposite: -1,234.56 versus 1.234,56. - - -File: gawk.info, Node: Programmer i18n, Next: Translator i18n, Prev: Explaining gettext, Up: Internationalization - -12.3 Internationalizing `awk' Programs -====================================== - -`gawk' provides the following variables and functions for -internationalization: - -`TEXTDOMAIN' - This variable indicates the application's text domain. For - compatibility with GNU `gettext', the default value is - `"messages"'. - -`_"your message here"' - String constants marked with a leading underscore are candidates - for translation at runtime. String constants without a leading - underscore are not translated. - -`dcgettext(STRING [, DOMAIN [, CATEGORY]])' - Return the translation of STRING in text domain DOMAIN for locale - category CATEGORY. The default value for DOMAIN is the current - value of `TEXTDOMAIN'. The default value for CATEGORY is - `"LC_MESSAGES"'. - - If you supply a value for CATEGORY, it must be a string equal to - one of the known locale categories described in *note Explaining - gettext::. You must also supply a text domain. Use `TEXTDOMAIN' - if you want to use the current domain. - - CAUTION: The order of arguments to the `awk' version of the - `dcgettext()' function is purposely different from the order - for the C version. The `awk' version's order was chosen to - be simple and to allow for reasonable `awk'-style default - arguments. - -`dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])' - Return the plural form used for NUMBER of the translation of - STRING1 and STRING2 in text domain DOMAIN for locale category - CATEGORY. STRING1 is the English singular variant of a message, - and STRING2 the English plural variant of the same message. The - default value for DOMAIN is the current value of `TEXTDOMAIN'. - The default value for CATEGORY is `"LC_MESSAGES"'. - - The same remarks about argument order as for the `dcgettext()' - function apply. - -`bindtextdomain(DIRECTORY [, DOMAIN])' - Change the directory in which `gettext' looks for `.mo' files, in - case they will not or cannot be placed in the standard locations - (e.g., during testing). Return the directory in which DOMAIN is - "bound." - - The default DOMAIN is the value of `TEXTDOMAIN'. If DIRECTORY is - the null string (`""'), then `bindtextdomain()' returns the - current binding for the given DOMAIN. - - To use these facilities in your `awk' program, follow the steps -outlined in *note Explaining gettext::, like so: - - 1. Set the variable `TEXTDOMAIN' to the text domain of your program. - This is best done in a `BEGIN' rule (*note BEGIN/END::), or it can - also be done via the `-v' command-line option (*note Options::): - - BEGIN { - TEXTDOMAIN = "guide" - ... - } - - 2. Mark all translatable strings with a leading underscore (`_') - character. It _must_ be adjacent to the opening quote of the - string. For example: - - print _"hello, world" - x = _"you goofed" - printf(_"Number of users is %d\n", nusers) - - 3. If you are creating strings dynamically, you can still translate - them, using the `dcgettext()' built-in function: - - message = nusers " users logged in" - message = dcgettext(message, "adminprog") - print message - - Here, the call to `dcgettext()' supplies a different text domain - (`"adminprog"') in which to find the message, but it uses the - default `"LC_MESSAGES"' category. - - 4. During development, you might want to put the `.mo' file in a - private directory for testing. This is done with the - `bindtextdomain()' built-in function: - - BEGIN { - TEXTDOMAIN = "guide" # our text domain - if (Testing) { - # where to find our files - bindtextdomain("testdir") - # joe is in charge of adminprog - bindtextdomain("../joe/testdir", "adminprog") - } - ... - } - - - *Note I18N Example::, for an example program showing the steps to -create and use translations from `awk'. - - -File: gawk.info, Node: Translator i18n, Next: I18N Example, Prev: Programmer i18n, Up: Internationalization - -12.4 Translating `awk' Programs -=============================== - -Once a program's translatable strings have been marked, they must be -extracted to create the initial `.po' file. As part of translation, it -is often helpful to rearrange the order in which arguments to `printf' -are output. - - `gawk''s `--gen-pot' command-line option extracts the messages and -is discussed next. After that, `printf''s ability to rearrange the -order for `printf' arguments at runtime is covered. - -* Menu: - -* String Extraction:: Extracting marked strings. -* Printf Ordering:: Rearranging `printf' arguments. -* I18N Portability:: `awk'-level portability issues. - - -File: gawk.info, Node: String Extraction, Next: Printf Ordering, Up: Translator i18n - -12.4.1 Extracting Marked Strings --------------------------------- - -Once your `awk' program is working, and all the strings have been -marked and you've set (and perhaps bound) the text domain, it is time -to produce translations. First, use the `--gen-pot' command-line -option to create the initial `.pot' file: - - $ gawk --gen-pot -f guide.awk > guide.pot - - When run with `--gen-pot', `gawk' does not execute your program. -Instead, it parses it as usual and prints all marked strings to -standard output in the format of a GNU `gettext' Portable Object file. -Also included in the output are any constant strings that appear as the -first argument to `dcgettext()' or as the first and second argument to -`dcngettext()'.(1) *Note I18N Example::, for the full list of steps to -go through to create and test translations for `guide'. - - ---------- Footnotes ---------- - - (1) The `xgettext' utility that comes with GNU `gettext' can handle -`.awk' files. - - -File: gawk.info, Node: Printf Ordering, Next: I18N Portability, Prev: String Extraction, Up: Translator i18n - -12.4.2 Rearranging `printf' Arguments -------------------------------------- - -Format strings for `printf' and `sprintf()' (*note Printf::) present a -special problem for translation. Consider the following:(1) - - printf(_"String `%s' has %d characters\n", - string, length(string))) - - A possible German translation for this might be: - - "%d Zeichen lang ist die Zeichenkette `%s'\n" - - The problem should be obvious: the order of the format -specifications is different from the original! Even though `gettext()' -can return the translated string at runtime, it cannot change the -argument order in the call to `printf'. - - To solve this problem, `printf' format specifiers may have an -additional optional element, which we call a "positional specifier". -For example: - - "%2$d Zeichen lang ist die Zeichenkette `%1$s'\n" - - Here, the positional specifier consists of an integer count, which -indicates which argument to use, and a `$'. Counts are one-based, and -the format string itself is _not_ included. Thus, in the following -example, `string' is the first argument and `length(string)' is the -second: - - $ gawk 'BEGIN { - > string = "Dont Panic" - > printf _"%2$d characters live in \"%1$s\"\n", - > string, length(string) - > }' - -| 10 characters live in "Dont Panic" - - If present, positional specifiers come first in the format -specification, before the flags, the field width, and/or the precision. - - Positional specifiers can be used with the dynamic field width and -precision capability: - - $ gawk 'BEGIN { - > printf("%*.*s\n", 10, 20, "hello") - > printf("%3$*2$.*1$s\n", 20, 10, "hello") - > }' - -| hello - -| hello - - NOTE: When using `*' with a positional specifier, the `*' comes - first, then the integer position, and then the `$'. This is - somewhat counterintuitive. - - `gawk' does not allow you to mix regular format specifiers and those -with positional specifiers in the same string: - - $ gawk 'BEGIN { printf _"%d %3$s\n", 1, 2, "hi" }' - error--> gawk: cmd. line:1: fatal: must use `count$' on all formats or none - - NOTE: There are some pathological cases that `gawk' may fail to - diagnose. In such cases, the output may not be what you expect. - It's still a bad idea to try mixing them, even if `gawk' doesn't - detect it. - - Although positional specifiers can be used directly in `awk' -programs, their primary purpose is to help in producing correct -translations of format strings into languages different from the one in -which the program is first written. - - ---------- Footnotes ---------- - - (1) This example is borrowed from the GNU `gettext' manual. - - -File: gawk.info, Node: I18N Portability, Prev: Printf Ordering, Up: Translator i18n - -12.4.3 `awk' Portability Issues -------------------------------- - -`gawk''s internationalization features were purposely chosen to have as -little impact as possible on the portability of `awk' programs that use -them to other versions of `awk'. Consider this program: - - BEGIN { - TEXTDOMAIN = "guide" - if (Test_Guide) # set with -v - bindtextdomain("/test/guide/messages") - print _"don't panic!" - } - -As written, it won't work on other versions of `awk'. However, it is -actually almost portable, requiring very little change: - - * Assignments to `TEXTDOMAIN' won't have any effect, since - `TEXTDOMAIN' is not special in other `awk' implementations. - - * Non-GNU versions of `awk' treat marked strings as the - concatenation of a variable named `_' with the string following - it.(1) Typically, the variable `_' has the null string (`""') as - its value, leaving the original string constant as the result. - - * By defining "dummy" functions to replace `dcgettext()', - `dcngettext()' and `bindtextdomain()', the `awk' program can be - made to run, but all the messages are output in the original - language. For example: - - function bindtextdomain(dir, domain) - { - return dir - } - - function dcgettext(string, domain, category) - { - return string - } - - function dcngettext(string1, string2, number, domain, category) - { - return (number == 1 ? string1 : string2) - } - - * The use of positional specifications in `printf' or `sprintf()' is - _not_ portable. To support `gettext()' at the C level, many - systems' C versions of `sprintf()' do support positional - specifiers. But it works only if enough arguments are supplied in - the function call. Many versions of `awk' pass `printf' formats - and arguments unchanged to the underlying C library version of - `sprintf()', but only one format and argument at a time. What - happens if a positional specification is used is anybody's guess. - However, since the positional specifications are primarily for use - in _translated_ format strings, and since non-GNU `awk's never - retrieve the translated string, this should not be a problem in - practice. - - ---------- Footnotes ---------- - - (1) This is good fodder for an "Obfuscated `awk'" contest. - - -File: gawk.info, Node: I18N Example, Next: Gawk I18N, Prev: Translator i18n, Up: Internationalization - -12.5 A Simple Internationalization Example -========================================== - -Now let's look at a step-by-step example of how to internationalize and -localize a simple `awk' program, using `guide.awk' as our original -source: - - BEGIN { - TEXTDOMAIN = "guide" - bindtextdomain(".") # for testing - print _"Don't Panic" - print _"The Answer Is", 42 - print "Pardon me, Zaphod who?" - } - -Run `gawk --gen-pot' to create the `.pot' file: - - $ gawk --gen-pot -f guide.awk > guide.pot - -This produces: - - #: guide.awk:4 - msgid "Don't Panic" - msgstr "" - - #: guide.awk:5 - msgid "The Answer Is" - msgstr "" - - This original portable object template file is saved and reused for -each language into which the application is translated. The `msgid' is -the original string and the `msgstr' is the translation. - - NOTE: Strings not marked with a leading underscore do not appear - in the `guide.pot' file. - - Next, the messages must be translated. Here is a translation to a -hypothetical dialect of English, called "Mellow":(1) - - $ cp guide.pot guide-mellow.po - ADD TRANSLATIONS TO guide-mellow.po ... - -Following are the translations: - - #: guide.awk:4 - msgid "Don't Panic" - msgstr "Hey man, relax!" - - #: guide.awk:5 - msgid "The Answer Is" - msgstr "Like, the scoop is" - - The next step is to make the directory to hold the binary message -object file and then to create the `guide.mo' file. The directory -layout shown here is standard for GNU `gettext' on GNU/Linux systems. -Other versions of `gettext' may use a different layout: - - $ mkdir en_US en_US/LC_MESSAGES - - The `msgfmt' utility does the conversion from human-readable `.po' -file to machine-readable `.mo' file. By default, `msgfmt' creates a -file named `messages'. This file must be renamed and placed in the -proper directory so that `gawk' can find it: - - $ msgfmt guide-mellow.po - $ mv messages en_US/LC_MESSAGES/guide.mo - - Finally, we run the program to test it: - - $ gawk -f guide.awk - -| Hey man, relax! - -| Like, the scoop is 42 - -| Pardon me, Zaphod who? - - If the three replacement functions for `dcgettext()', `dcngettext()' -and `bindtextdomain()' (*note I18N Portability::) are in a file named -`libintl.awk', then we can run `guide.awk' unchanged as follows: - - $ gawk --posix -f guide.awk -f libintl.awk - -| Don't Panic - -| The Answer Is 42 - -| Pardon me, Zaphod who? - - ---------- Footnotes ---------- - - (1) Perhaps it would be better if it were called "Hippy." Ah, well. - - -File: gawk.info, Node: Gawk I18N, Prev: I18N Example, Up: Internationalization - -12.6 `gawk' Can Speak Your Language -=================================== - -`gawk' itself has been internationalized using the GNU `gettext' -package. (GNU `gettext' is described in complete detail in *note (GNU -`gettext' utilities)Top:: gettext, GNU gettext tools.) As of this -writing, the latest version of GNU `gettext' is version 0.18.1 -(ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.1.tar.gz). +File: gawk.info, Node: Advanced Features, Next: Internationalization, Prev: Sample Programs, Up: Top - If a translation of `gawk''s messages exists, then `gawk' produces -usage messages, warnings, and fatal errors in the local language. - - -File: gawk.info, Node: Advanced Features, Next: Debugger, Prev: Internationalization, Up: Top - -13 Advanced Features of `gawk' +12 Advanced Features of `gawk' ****************************** Write documentation as if whoever reads it is a violent psychopath @@ -18439,9 +17875,21 @@ full detail, along with the basics of TCP/IP networking. Finally, `gawk' can "profile" an `awk' program, making it possible to tune it for performance. - *note Dynamic Extensions::, discusses the ability to dynamically add -new built-in functions to `gawk'. As this feature is still immature -and likely to change, its description is relegated to an appendix. + A number of advanced features require separate major nodes of their +own: + + * *note Internationalization::, discusses how to internationalize + your `awk' programs, so that they can speak multiple national + languages. + + * *note Debugger::, describes `gawk''s built-in command-line + debugger for debugging `awk' programs. + + * *note Arbitrary Precision Arithmetic::, describes how you can use + `gawk' to perform arbitrary-precision arithmetic. + + * *note Dynamic Extensions::, discusses the ability to dynamically + add new built-in functions to `gawk'. * Menu: @@ -18455,7 +17903,7 @@ and likely to change, its description is relegated to an appendix. File: gawk.info, Node: Nondecimal Data, Next: Array Sorting, Up: Advanced Features -13.1 Allowing Nondecimal Input Data +12.1 Allowing Nondecimal Input Data =================================== If you run `gawk' with the `--non-decimal-data' option, you can have @@ -18497,7 +17945,7 @@ request it. File: gawk.info, Node: Array Sorting, Next: Two-way I/O, Prev: Nondecimal Data, Up: Advanced Features -13.2 Controlling Array Traversal and Array Sorting +12.2 Controlling Array Traversal and Array Sorting ================================================== `gawk' lets you control the order in which a `for (i in array)' loop @@ -18516,7 +17964,7 @@ to order the elements during sorting. File: gawk.info, Node: Controlling Array Traversal, Next: Array Sorting Functions, Up: Array Sorting -13.2.1 Controlling Array Traversal +12.2.1 Controlling Array Traversal ---------------------------------- By default, the order in which a `for (i in array)' loop scans an array @@ -18747,7 +18195,7 @@ the default. File: gawk.info, Node: Array Sorting Functions, Prev: Controlling Array Traversal, Up: Array Sorting -13.2.2 Sorting Array Values and Indices with `gawk' +12.2.2 Sorting Array Values and Indices with `gawk' --------------------------------------------------- In most `awk' implementations, sorting an array requires writing a @@ -18842,7 +18290,7 @@ extensions, they are not available in that case. File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Array Sorting, Up: Advanced Features -13.3 Two-Way Communications with Another Process +12.3 Two-Way Communications with Another Process ================================================ From: brennan@whidbey.com (Mike Brennan) @@ -18977,7 +18425,7 @@ regular pipes. File: gawk.info, Node: TCP/IP Networking, Next: Profiling, Prev: Two-way I/O, Up: Advanced Features -13.4 Using `gawk' for Network Programming +12.4 Using `gawk' for Network Programming ========================================= `EMISTERED': @@ -19054,7 +18502,7 @@ examples. File: gawk.info, Node: Profiling, Prev: TCP/IP Networking, Up: Advanced Features -13.5 Profiling Your `awk' Programs +12.5 Profiling Your `awk' Programs ================================== You may produce execution traces of your `awk' programs. This is done @@ -19265,12 +18713,592 @@ generated by the keyboard. The `INT' signal is generated by the `Ctrl-<C>' or `Ctrl-<BREAK>' key, while the `QUIT' signal is generated by the `Ctrl-<\>' key. - Finally, `gawk' also accepts another option `--pretty-print'. When + Finally, `gawk' also accepts another option, `--pretty-print'. When called this way, `gawk' "pretty prints" the program into `awkprof.out', without any execution counts. -File: gawk.info, Node: Debugger, Next: Arbitrary Precision Arithmetic, Prev: Advanced Features, Up: Top +File: gawk.info, Node: Internationalization, Next: Debugger, Prev: Advanced Features, Up: Top + +13 Internationalization with `gawk' +*********************************** + +Once upon a time, computer makers wrote software that worked only in +English. Eventually, hardware and software vendors noticed that if +their systems worked in the native languages of non-English-speaking +countries, they were able to sell more systems. As a result, +internationalization and localization of programs and software systems +became a common practice. + + For many years, the ability to provide internationalization was +largely restricted to programs written in C and C++. This major node +describes the underlying library `gawk' uses for internationalization, +as well as how `gawk' makes internationalization features available at +the `awk' program level. Having internationalization available at the +`awk' level gives software developers additional flexibility--they are +no longer forced to write in C or C++ when internationalization is a +requirement. + +* Menu: + +* I18N and L10N:: Internationalization and Localization. +* Explaining gettext:: How GNU `gettext' works. +* Programmer i18n:: Features for the programmer. +* Translator i18n:: Features for the translator. +* I18N Example:: A simple i18n example. +* Gawk I18N:: `gawk' is also internationalized. + + +File: gawk.info, Node: I18N and L10N, Next: Explaining gettext, Up: Internationalization + +13.1 Internationalization and Localization +========================================== + +"Internationalization" means writing (or modifying) a program once, in +such a way that it can use multiple languages without requiring further +source-code changes. "Localization" means providing the data necessary +for an internationalized program to work in a particular language. +Most typically, these terms refer to features such as the language used +for printing error messages, the language used to read responses, and +information related to how numerical and monetary values are printed +and read. + + +File: gawk.info, Node: Explaining gettext, Next: Programmer i18n, Prev: I18N and L10N, Up: Internationalization + +13.2 GNU `gettext' +================== + +The facilities in GNU `gettext' focus on messages; strings printed by a +program, either directly or via formatting with `printf' or +`sprintf()'.(1) + + When using GNU `gettext', each application has its own "text +domain". This is a unique name, such as `kpilot' or `gawk', that +identifies the application. A complete application may have multiple +components--programs written in C or C++, as well as scripts written in +`sh' or `awk'. All of the components use the same text domain. + + To make the discussion concrete, assume we're writing an application +named `guide'. Internationalization consists of the following steps, +in this order: + + 1. The programmer goes through the source for all of `guide''s + components and marks each string that is a candidate for + translation. For example, `"`-F': option required"' is a good + candidate for translation. A table with strings of option names + is not (e.g., `gawk''s `--profile' option should remain the same, + no matter what the local language). + + 2. The programmer indicates the application's text domain (`"guide"') + to the `gettext' library, by calling the `textdomain()' function. + + 3. Messages from the application are extracted from the source code + and collected into a portable object template file (`guide.pot'), + which lists the strings and their translations. The translations + are initially empty. The original (usually English) messages + serve as the key for lookup of the translations. + + 4. For each language with a translator, `guide.pot' is copied to a + portable object file (`.po') and translations are created and + shipped with the application. For example, there might be a + `fr.po' for a French translation. + + 5. Each language's `.po' file is converted into a binary message + object (`.mo') file. A message object file contains the original + messages and their translations in a binary format that allows + fast lookup of translations at runtime. + + 6. When `guide' is built and installed, the binary translation files + are installed in a standard place. + + 7. For testing and development, it is possible to tell `gettext' to + use `.mo' files in a different directory than the standard one by + using the `bindtextdomain()' function. + + 8. At runtime, `guide' looks up each string via a call to + `gettext()'. The returned string is the translated string if + available, or the original string if not. + + 9. If necessary, it is possible to access messages from a different + text domain than the one belonging to the application, without + having to switch the application's default text domain back and + forth. + + In C (or C++), the string marking and dynamic translation lookup are +accomplished by wrapping each string in a call to `gettext()': + + printf("%s", gettext("Don't Panic!\n")); + + The tools that extract messages from source code pull out all +strings enclosed in calls to `gettext()'. + + The GNU `gettext' developers, recognizing that typing `gettext(...)' +over and over again is both painful and ugly to look at, use the macro +`_' (an underscore) to make things easier: + + /* In the standard header file: */ + #define _(str) gettext(str) + + /* In the program text: */ + printf("%s", _("Don't Panic!\n")); + +This reduces the typing overhead to just three extra characters per +string and is considerably easier to read as well. + + There are locale "categories" for different types of locale-related +information. The defined locale categories that `gettext' knows about +are: + +`LC_MESSAGES' + Text messages. This is the default category for `gettext' + operations, but it is possible to supply a different one + explicitly, if necessary. (It is almost never necessary to supply + a different category.) + +`LC_COLLATE' + Text-collation information; i.e., how different characters and/or + groups of characters sort in a given language. + +`LC_CTYPE' + Character-type information (alphabetic, digit, upper- or + lowercase, and so on). This information is accessed via the POSIX + character classes in regular expressions, such as `/[[:alnum:]]/' + (*note Regexp Operators::). + +`LC_MONETARY' + Monetary information, such as the currency symbol, and whether the + symbol goes before or after a number. + +`LC_NUMERIC' + Numeric information, such as which characters to use for the + decimal point and the thousands separator.(2) + +`LC_RESPONSE' + Response information, such as how "yes" and "no" appear in the + local language, and possibly other information as well. + +`LC_TIME' + Time- and date-related information, such as 12- or 24-hour clock, + month printed before or after the day in a date, local month + abbreviations, and so on. + +`LC_ALL' + All of the above. (Not too useful in the context of `gettext'.) + + ---------- Footnotes ---------- + + (1) For some operating systems, the `gawk' port doesn't support GNU +`gettext'. Therefore, these features are not available if you are +using one of those operating systems. Sorry. + + (2) Americans use a comma every three decimal places and a period +for the decimal point, while many Europeans do exactly the opposite: +1,234.56 versus 1.234,56. + + +File: gawk.info, Node: Programmer i18n, Next: Translator i18n, Prev: Explaining gettext, Up: Internationalization + +13.3 Internationalizing `awk' Programs +====================================== + +`gawk' provides the following variables and functions for +internationalization: + +`TEXTDOMAIN' + This variable indicates the application's text domain. For + compatibility with GNU `gettext', the default value is + `"messages"'. + +`_"your message here"' + String constants marked with a leading underscore are candidates + for translation at runtime. String constants without a leading + underscore are not translated. + +`dcgettext(STRING [, DOMAIN [, CATEGORY]])' + Return the translation of STRING in text domain DOMAIN for locale + category CATEGORY. The default value for DOMAIN is the current + value of `TEXTDOMAIN'. The default value for CATEGORY is + `"LC_MESSAGES"'. + + If you supply a value for CATEGORY, it must be a string equal to + one of the known locale categories described in *note Explaining + gettext::. You must also supply a text domain. Use `TEXTDOMAIN' + if you want to use the current domain. + + CAUTION: The order of arguments to the `awk' version of the + `dcgettext()' function is purposely different from the order + for the C version. The `awk' version's order was chosen to + be simple and to allow for reasonable `awk'-style default + arguments. + +`dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])' + Return the plural form used for NUMBER of the translation of + STRING1 and STRING2 in text domain DOMAIN for locale category + CATEGORY. STRING1 is the English singular variant of a message, + and STRING2 the English plural variant of the same message. The + default value for DOMAIN is the current value of `TEXTDOMAIN'. + The default value for CATEGORY is `"LC_MESSAGES"'. + + The same remarks about argument order as for the `dcgettext()' + function apply. + +`bindtextdomain(DIRECTORY [, DOMAIN])' + Change the directory in which `gettext' looks for `.mo' files, in + case they will not or cannot be placed in the standard locations + (e.g., during testing). Return the directory in which DOMAIN is + "bound." + + The default DOMAIN is the value of `TEXTDOMAIN'. If DIRECTORY is + the null string (`""'), then `bindtextdomain()' returns the + current binding for the given DOMAIN. + + To use these facilities in your `awk' program, follow the steps +outlined in *note Explaining gettext::, like so: + + 1. Set the variable `TEXTDOMAIN' to the text domain of your program. + This is best done in a `BEGIN' rule (*note BEGIN/END::), or it can + also be done via the `-v' command-line option (*note Options::): + + BEGIN { + TEXTDOMAIN = "guide" + ... + } + + 2. Mark all translatable strings with a leading underscore (`_') + character. It _must_ be adjacent to the opening quote of the + string. For example: + + print _"hello, world" + x = _"you goofed" + printf(_"Number of users is %d\n", nusers) + + 3. If you are creating strings dynamically, you can still translate + them, using the `dcgettext()' built-in function: + + message = nusers " users logged in" + message = dcgettext(message, "adminprog") + print message + + Here, the call to `dcgettext()' supplies a different text domain + (`"adminprog"') in which to find the message, but it uses the + default `"LC_MESSAGES"' category. + + 4. During development, you might want to put the `.mo' file in a + private directory for testing. This is done with the + `bindtextdomain()' built-in function: + + BEGIN { + TEXTDOMAIN = "guide" # our text domain + if (Testing) { + # where to find our files + bindtextdomain("testdir") + # joe is in charge of adminprog + bindtextdomain("../joe/testdir", "adminprog") + } + ... + } + + + *Note I18N Example::, for an example program showing the steps to +create and use translations from `awk'. + + +File: gawk.info, Node: Translator i18n, Next: I18N Example, Prev: Programmer i18n, Up: Internationalization + +13.4 Translating `awk' Programs +=============================== + +Once a program's translatable strings have been marked, they must be +extracted to create the initial `.po' file. As part of translation, it +is often helpful to rearrange the order in which arguments to `printf' +are output. + + `gawk''s `--gen-pot' command-line option extracts the messages and +is discussed next. After that, `printf''s ability to rearrange the +order for `printf' arguments at runtime is covered. + +* Menu: + +* String Extraction:: Extracting marked strings. +* Printf Ordering:: Rearranging `printf' arguments. +* I18N Portability:: `awk'-level portability issues. + + +File: gawk.info, Node: String Extraction, Next: Printf Ordering, Up: Translator i18n + +13.4.1 Extracting Marked Strings +-------------------------------- + +Once your `awk' program is working, and all the strings have been +marked and you've set (and perhaps bound) the text domain, it is time +to produce translations. First, use the `--gen-pot' command-line +option to create the initial `.pot' file: + + $ gawk --gen-pot -f guide.awk > guide.pot + + When run with `--gen-pot', `gawk' does not execute your program. +Instead, it parses it as usual and prints all marked strings to +standard output in the format of a GNU `gettext' Portable Object file. +Also included in the output are any constant strings that appear as the +first argument to `dcgettext()' or as the first and second argument to +`dcngettext()'.(1) *Note I18N Example::, for the full list of steps to +go through to create and test translations for `guide'. + + ---------- Footnotes ---------- + + (1) The `xgettext' utility that comes with GNU `gettext' can handle +`.awk' files. + + +File: gawk.info, Node: Printf Ordering, Next: I18N Portability, Prev: String Extraction, Up: Translator i18n + +13.4.2 Rearranging `printf' Arguments +------------------------------------- + +Format strings for `printf' and `sprintf()' (*note Printf::) present a +special problem for translation. Consider the following:(1) + + printf(_"String `%s' has %d characters\n", + string, length(string))) + + A possible German translation for this might be: + + "%d Zeichen lang ist die Zeichenkette `%s'\n" + + The problem should be obvious: the order of the format +specifications is different from the original! Even though `gettext()' +can return the translated string at runtime, it cannot change the +argument order in the call to `printf'. + + To solve this problem, `printf' format specifiers may have an +additional optional element, which we call a "positional specifier". +For example: + + "%2$d Zeichen lang ist die Zeichenkette `%1$s'\n" + + Here, the positional specifier consists of an integer count, which +indicates which argument to use, and a `$'. Counts are one-based, and +the format string itself is _not_ included. Thus, in the following +example, `string' is the first argument and `length(string)' is the +second: + + $ gawk 'BEGIN { + > string = "Dont Panic" + > printf _"%2$d characters live in \"%1$s\"\n", + > string, length(string) + > }' + -| 10 characters live in "Dont Panic" + + If present, positional specifiers come first in the format +specification, before the flags, the field width, and/or the precision. + + Positional specifiers can be used with the dynamic field width and +precision capability: + + $ gawk 'BEGIN { + > printf("%*.*s\n", 10, 20, "hello") + > printf("%3$*2$.*1$s\n", 20, 10, "hello") + > }' + -| hello + -| hello + + NOTE: When using `*' with a positional specifier, the `*' comes + first, then the integer position, and then the `$'. This is + somewhat counterintuitive. + + `gawk' does not allow you to mix regular format specifiers and those +with positional specifiers in the same string: + + $ gawk 'BEGIN { printf _"%d %3$s\n", 1, 2, "hi" }' + error--> gawk: cmd. line:1: fatal: must use `count$' on all formats or none + + NOTE: There are some pathological cases that `gawk' may fail to + diagnose. In such cases, the output may not be what you expect. + It's still a bad idea to try mixing them, even if `gawk' doesn't + detect it. + + Although positional specifiers can be used directly in `awk' +programs, their primary purpose is to help in producing correct +translations of format strings into languages different from the one in +which the program is first written. + + ---------- Footnotes ---------- + + (1) This example is borrowed from the GNU `gettext' manual. + + +File: gawk.info, Node: I18N Portability, Prev: Printf Ordering, Up: Translator i18n + +13.4.3 `awk' Portability Issues +------------------------------- + +`gawk''s internationalization features were purposely chosen to have as +little impact as possible on the portability of `awk' programs that use +them to other versions of `awk'. Consider this program: + + BEGIN { + TEXTDOMAIN = "guide" + if (Test_Guide) # set with -v + bindtextdomain("/test/guide/messages") + print _"don't panic!" + } + +As written, it won't work on other versions of `awk'. However, it is +actually almost portable, requiring very little change: + + * Assignments to `TEXTDOMAIN' won't have any effect, since + `TEXTDOMAIN' is not special in other `awk' implementations. + + * Non-GNU versions of `awk' treat marked strings as the + concatenation of a variable named `_' with the string following + it.(1) Typically, the variable `_' has the null string (`""') as + its value, leaving the original string constant as the result. + + * By defining "dummy" functions to replace `dcgettext()', + `dcngettext()' and `bindtextdomain()', the `awk' program can be + made to run, but all the messages are output in the original + language. For example: + + function bindtextdomain(dir, domain) + { + return dir + } + + function dcgettext(string, domain, category) + { + return string + } + + function dcngettext(string1, string2, number, domain, category) + { + return (number == 1 ? string1 : string2) + } + + * The use of positional specifications in `printf' or `sprintf()' is + _not_ portable. To support `gettext()' at the C level, many + systems' C versions of `sprintf()' do support positional + specifiers. But it works only if enough arguments are supplied in + the function call. Many versions of `awk' pass `printf' formats + and arguments unchanged to the underlying C library version of + `sprintf()', but only one format and argument at a time. What + happens if a positional specification is used is anybody's guess. + However, since the positional specifications are primarily for use + in _translated_ format strings, and since non-GNU `awk's never + retrieve the translated string, this should not be a problem in + practice. + + ---------- Footnotes ---------- + + (1) This is good fodder for an "Obfuscated `awk'" contest. + + +File: gawk.info, Node: I18N Example, Next: Gawk I18N, Prev: Translator i18n, Up: Internationalization + +13.5 A Simple Internationalization Example +========================================== + +Now let's look at a step-by-step example of how to internationalize and +localize a simple `awk' program, using `guide.awk' as our original +source: + + BEGIN { + TEXTDOMAIN = "guide" + bindtextdomain(".") # for testing + print _"Don't Panic" + print _"The Answer Is", 42 + print "Pardon me, Zaphod who?" + } + +Run `gawk --gen-pot' to create the `.pot' file: + + $ gawk --gen-pot -f guide.awk > guide.pot + +This produces: + + #: guide.awk:4 + msgid "Don't Panic" + msgstr "" + + #: guide.awk:5 + msgid "The Answer Is" + msgstr "" + + This original portable object template file is saved and reused for +each language into which the application is translated. The `msgid' is +the original string and the `msgstr' is the translation. + + NOTE: Strings not marked with a leading underscore do not appear + in the `guide.pot' file. + + Next, the messages must be translated. Here is a translation to a +hypothetical dialect of English, called "Mellow":(1) + + $ cp guide.pot guide-mellow.po + ADD TRANSLATIONS TO guide-mellow.po ... + +Following are the translations: + + #: guide.awk:4 + msgid "Don't Panic" + msgstr "Hey man, relax!" + + #: guide.awk:5 + msgid "The Answer Is" + msgstr "Like, the scoop is" + + The next step is to make the directory to hold the binary message +object file and then to create the `guide.mo' file. The directory +layout shown here is standard for GNU `gettext' on GNU/Linux systems. +Other versions of `gettext' may use a different layout: + + $ mkdir en_US en_US/LC_MESSAGES + + The `msgfmt' utility does the conversion from human-readable `.po' +file to machine-readable `.mo' file. By default, `msgfmt' creates a +file named `messages'. This file must be renamed and placed in the +proper directory so that `gawk' can find it: + + $ msgfmt guide-mellow.po + $ mv messages en_US/LC_MESSAGES/guide.mo + + Finally, we run the program to test it: + + $ gawk -f guide.awk + -| Hey man, relax! + -| Like, the scoop is 42 + -| Pardon me, Zaphod who? + + If the three replacement functions for `dcgettext()', `dcngettext()' +and `bindtextdomain()' (*note I18N Portability::) are in a file named +`libintl.awk', then we can run `guide.awk' unchanged as follows: + + $ gawk --posix -f guide.awk -f libintl.awk + -| Don't Panic + -| The Answer Is 42 + -| Pardon me, Zaphod who? + + ---------- Footnotes ---------- + + (1) Perhaps it would be better if it were called "Hippy." Ah, well. + + +File: gawk.info, Node: Gawk I18N, Prev: I18N Example, Up: Internationalization + +13.6 `gawk' Can Speak Your Language +=================================== + +`gawk' itself has been internationalized using the GNU `gettext' +package. (GNU `gettext' is described in complete detail in *note (GNU +`gettext' utilities)Top:: gettext, GNU gettext tools.) As of this +writing, the latest version of GNU `gettext' is version 0.18.2.1 +(ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz). + + If a translation of `gawk''s messages exists, then `gawk' produces +usage messages, warnings, and fatal errors in the local language. + + +File: gawk.info, Node: Debugger, Next: Arbitrary Precision Arithmetic, Prev: Internationalization, Up: Top 14 Debugging `awk' Programs *************************** @@ -19456,10 +19484,10 @@ this: where both `getopt.awk' and `uniq.awk' are in `$AWKPATH'. (Experienced users of GDB or similar debuggers should note that this syntax is -slightly different from what they are used to. With `gawk' debugger, -the arguments for running the program are given in the command line to -the debugger rather than as part of the `run' command at the debugger -prompt.) +slightly different from what they are used to. With the `gawk' +debugger, you give the arguments for running the program in the command +line to the debugger rather than as part of the `run' command at the +debugger prompt.) Instead of immediately running the program on `inputfile', as `gawk' would ordinarily do, the debugger merely loads all the program source @@ -20124,7 +20152,7 @@ from a file. The commands are: In addition to, or instead of the `source' command, you can use the `-D FILE' or `--debug=FILE' command-line options to execute - commands from a file non-interactively (*note Options::. + commands from a file non-interactively (*note Options::). File: gawk.info, Node: Miscellaneous Debugger Commands, Prev: Debugger Info, Up: List of Debugger Commands @@ -20144,54 +20172,52 @@ categories, as follows: Program::) demonstrates: gawk> dump - -| # BEGIN + -| # BEGIN -| - -| [ 2:0x89faef4] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] - -| [ 3:0x89fa428] Op_push_i : "~" [PERM|STRING|STRCUR] - -| [ 3:0x89fa464] Op_push_i : "~" [PERM|STRING|STRCUR] - -| [ 3:0x89fa450] Op_match : - -| [ 3:0x89fa3ec] Op_store_var : O [do_reference = FALSE] - -| [ 4:0x89fa48c] Op_push_i : "==" [PERM|STRING|STRCUR] - -| [ 4:0x89fa4c8] Op_push_i : "==" [PERM|STRING|STRCUR] - -| [ 4:0x89fa4b4] Op_equal : - -| [ 4:0x89fa400] Op_store_var : o [do_reference = FALSE] - -| [ 5:0x89fa4f0] Op_push : o - -| [ 5:0x89fa4dc] Op_plus_i : 0 [PERM|NUMCUR|NUMBER] - -| [ 5:0x89fa414] Op_push_lhs : o [do_reference = TRUE] - -| [ 5:0x89fa4a0] Op_assign_plus : - -| [ :0x89fa478] Op_pop : - -| [ 6:0x89fa540] Op_push : O - -| [ 6:0x89fa554] Op_push_i : "" [PERM|STRING|STRCUR] - -| [ :0x89fa5a4] Op_no_op : - -| [ 6:0x89fa590] Op_push : O - -| [ :0x89fa5b8] Op_concat : [expr_count = 3] [concat_flag = 0] - -| [ 6:0x89fa518] Op_store_var : x [do_reference = FALSE] - -| [ 7:0x89fa504] Op_push_loop : [target_continue = 0x89fa568] [target_break = 0x89fa680] - -| [ 7:0x89fa568] Op_push_lhs : X [do_reference = TRUE] - -| [ 7:0x89fa52c] Op_postincrement : - -| [ 7:0x89fa5e0] Op_push : x - -| [ 7:0x89fa61c] Op_push : o - -| [ 7:0x89fa5f4] Op_plus : - -| [ 7:0x89fa644] Op_push : o - -| [ 7:0x89fa630] Op_plus : - -| [ 7:0x89fa5cc] Op_leq : - -| [ :0x89fa57c] Op_jmp_false : [target_jmp = 0x89fa680] - -| [ 7:0x89fa694] Op_push_i : "%c" [PERM|STRING|STRCUR] - -| [ :0x89fa6d0] Op_no_op : - -| [ 7:0x89fa608] Op_assign_concat : c - -| [ :0x89fa6a8] Op_jmp : [target_jmp = 0x89fa568] - -| [ :0x89fa680] Op_pop_loop : + -| [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] + -| [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc280] Op_match : + -| [ 1:0xfcc1e0] Op_store_var : O + -| [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc320] Op_equal : + -| [ 1:0xfcc200] Op_store_var : o + -| [ 1:0xfcc380] Op_push : o + -| [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] + -| [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] + -| [ 1:0xfcc300] Op_assign_plus : + -| [ :0xfcc2c0] Op_pop : + -| [ 1:0xfcc400] Op_push : O + -| [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] + -| [ :0xfcc4a0] Op_no_op : + -| [ 1:0xfcc480] Op_push : O + -| [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] + -| [ 1:0xfcc3c0] Op_store_var : x + -| [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] + -| [ 1:0xfcc3a0] Op_postincrement : + -| [ 1:0xfcc4e0] Op_push : x + -| [ 1:0xfcc540] Op_push : o + -| [ 1:0xfcc500] Op_plus : + -| [ 1:0xfcc580] Op_push : o + -| [ 1:0xfcc560] Op_plus : + -| [ 1:0xfcc460] Op_leq : + -| [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] + -| [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] + -| [ :0xfcc660] Op_no_op : + -| [ 1:0xfcc520] Op_assign_concat : c + -| [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] -| ... -| - -| [ 8:0x89fa658] Op_K_printf : [expr_count = 17] [redir_type = ""] - -| [ :0x89fa374] Op_no_op : - -| [ :0x89fa3d8] Op_atexit : - -| [ :0x89fa6bc] Op_stop : - -| [ :0x89fa39c] Op_no_op : - -| [ :0x89fa3b0] Op_after_beginfile : - -| [ :0x89fa388] Op_no_op : - -| [ :0x89fa3c4] Op_after_endfile : + -| [ 2:0xfcc5a0] Op_K_printf : [expr_count = 17] [redir_type = ""] + -| [ :0xfcc140] Op_no_op : + -| [ :0xfcc1c0] Op_atexit : + -| [ :0xfcc640] Op_stop : + -| [ :0xfcc180] Op_no_op : + -| [ :0xfcd150] Op_after_beginfile : + -| [ :0xfcc160] Op_no_op : + -| [ :0xfcc1a0] Op_after_endfile : gawk> `help' @@ -20342,8 +20368,8 @@ attributes of computer arithmetic, along with how this can influence what you see when running `awk' programs. This discussion applies to all versions of `awk'. - Then the major node moves on to "arbitrary precision arithmetic", a -feature which is specific to `gawk'. + The major node then moves on to describe "arbitrary precision +arithmetic", a feature which is specific to `gawk'. * Menu: @@ -20435,7 +20461,7 @@ comparisons. It is important to note that the string value for a number may not reflect the full value (all the digits) that the numeric value actually -contains. The following program (`values.awk') illustrates this: +contains. The following program, `values.awk', illustrates this: { sum = $1 + $2 @@ -20621,12 +20647,12 @@ File: gawk.info, Node: Integer Programming, Prev: Floating Point Issues, Up: 15.1.2 Mixing Integers And Floating-point ----------------------------------------- -As has been mentioned already, `gawk' ordinarily uses hardware double -precision with 64-bit IEEE binary floating-point representation for -numbers on most systems. A large integer like 9,007,199,254,740,997 has -a binary representation that, although finite, is more than 53 bits -long; it must also be rounded to 53 bits. The biggest integer that can -be stored in a C `double' is usually the same as the largest possible +As has been mentioned already, `awk' uses hardware double precision +with 64-bit IEEE binary floating-point representation for numbers on +most systems. A large integer like 9,007,199,254,740,997 has a binary +representation that, although finite, is more than 53 bits long; it +must also be rounded to 53 bits. The biggest integer that can be +stored in a C `double' is usually the same as the largest possible value of a `double'. If your system `double' is an IEEE 64-bit `double', this largest possible value is an integer and can be represented precisely. What more should one know about integers? @@ -20637,7 +20663,7 @@ precision, then the answer is 2^53. The next representable number is the even number 2^53 + 2, meaning it is unlikely that you will be able to make `gawk' print 2^53 + 1 in integer format. The range of integers exactly representable by a 64-bit double is [-2^53, 2^53]. If you ever -see an integer outside this range in `gawk' using 64-bit doubles, you +see an integer outside this range in `awk' using 64-bit doubles, you have reason to be very suspicious about the accuracy of the output. Here is a simple program with erroneous output: @@ -20647,7 +20673,7 @@ Here is a simple program with erroneous output: -| 9007199254740992 -| 9007199254740994 - The lesson is to not assume that any large integer printed by `gawk' + The lesson is to not assume that any large integer printed by `awk' represents an exact result from your computation, especially if it wraps around on your screen. @@ -20660,9 +20686,9 @@ File: gawk.info, Node: Floating-point Programming, Next: Gawk and MPFR, Prev: Numerical programming is an extensive area; if you need to develop sophisticated numerical algorithms then `gawk' may not be the ideal tool, and this documentation may not be sufficient. It might require -digesting a book or two to really internalize how to compute with ideal -accuracy and precision, and the result often depends on the particular -application. +digesting a book or two(1) to really internalize how to compute with +ideal accuracy and precision, and the result often depends on the +particular application. NOTE: A floating-point calculation's "accuracy" is how close it comes to the real value. This is as opposed to the "precision", @@ -20676,7 +20702,7 @@ hardware floating-point (as used by standard `awk' and the default for `gawk'), and "arbitrary-precision" floating-point, which is software based. From this point forward, this major node aims to provide enough information to understand both, and then will focus on `gawk''s -facilities for the latter.(1) +facilities for the latter.(2) Binary floating-point representations and arithmetic are inexact. Simple values like 0.1 cannot be precisely represented using binary @@ -20756,7 +20782,7 @@ zero. representations yield an unexpected result: $ gawk 'BEGIN { - > for (d = 1.1; d <= 1.5; d += 0.1) + > for (d = 1.1; d <= 1.5; d += 0.1) # loop five times (?) > i++ > print i > }' @@ -20768,7 +20794,7 @@ examples? If you are impatient to know, see *note Exact Arithmetic::. Instead of arbitrary precision floating-point arithmetic, often all you need is an adjustment of your logic or a different order for the operations in your calculation. The stability and the accuracy of the -computation of the constant pi in the previous example can be enhanced +computation of the constant pi in the earlier example can be enhanced by using the following simple algebraic transformation: (sqrt(x * x + 1) - 1) / x = x / (sqrt(x * x + 1) + 1) @@ -20776,7 +20802,7 @@ by using the following simple algebraic transformation: After making this, change the program does converge to pi in under 30 iterations: - $ gawk -f /tmp/pi2.awk + $ gawk -f pi2.awk -| 3.215390309173473 -| 3.159659942097501 -| 3.146086215131436 @@ -20806,7 +20832,12 @@ implies better precision than is actually the case. ---------- Footnotes ---------- - (1) If you are interested in other tools that perform arbitrary + (1) One recommended title is `Numerical Computing with IEEE Floating +Point Arithmetic', Michael L. Overton, Society for Industrial and +Applied Mathematics, 2004. ISBN: 0-89871-482-6, ISBN-13: +978-0-89871-482-1. See `http://www.cs.nyu.edu/cs/faculty/overton/book'. + + (2) If you are interested in other tools that perform arbitrary precision arithmetic, you may want to investigate the POSIX `bc' tool. See the POSIX specification for it (http://pubs.opengroup.org/onlinepubs/009695399/utilities/bc.html), for @@ -20854,16 +20885,16 @@ components: Precision of the floating-point format in bits. "emax" - Maximum exponent allowed for this format. + Maximum exponent allowed for the format. "emin" - Minimum exponent allowed for this format. + Minimum exponent allowed for the format. "Underflow behavior" The format may or may not support gradual underflow. "Rounding" - The rounding mode of this context. + The rounding mode of the context. *note table-ieee-formats:: lists the precision and exponent field values for the basic IEEE-754 binary formats: @@ -20928,8 +20959,8 @@ between, things do not work the way you probably learned in school. In this case, the number is rounded to the nearest even digit. So rounding 0.125 to two digits rounds down to 0.12, but rounding 0.6875 to three digits rounds up to 0.688. You probably have already -encountered this rounding mode when using the `printf' routine to -format floating-point numbers. For example: +encountered this rounding mode when using `printf' to format +floating-point numbers. For example: BEGIN { x = -4.5 @@ -20939,7 +20970,7 @@ format floating-point numbers. For example: } } -produces the following output when run:(1) +produces the following output when run on the author's system:(1) -3.5 => -4 -2.5 => -2 @@ -20953,7 +20984,7 @@ produces the following output when run:(1) The theory behind the rounding mode `roundTiesToEven' is that it more or less evenly distributes upward and downward rounds of exact -halves, which might cause the round-off error to cancel itself out. +halves, which might cause any round-off error to cancel itself out. This is the default rounding mode used in IEEE-754 computing functions and operators. @@ -20980,7 +21011,7 @@ significant difference in output when you change the rounding mode. (1) It is possible for the output to be completely different if the C library in your system does not use the IEEE-754 even-rounding rule -to round halfway cases for `printf()'. +to round halfway cases for `printf'. File: gawk.info, Node: Gawk and MPFR, Next: Arbitrary Precision Floats, Prev: Floating-point Programming, Up: Arbitrary Precision Arithmetic @@ -20998,8 +21029,8 @@ arbitrary precision arithmetic. The easiest way to find out is to look at the output of the following command: $ gawk --version - -| GNU Awk 4.1.0 (GNU MPFR 3.1.0, GNU MP 5.0.3) - -| Copyright (C) 1989, 1991-2012 Free Software Foundation. + -| GNU Awk 4.1.0, API: 1.0 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) + -| Copyright (C) 1989, 1991-2013 Free Software Foundation. ... `gawk' uses the GNU MPFR (http://www.mpfr.org) and GNU MP @@ -21021,20 +21052,20 @@ File: gawk.info, Node: Arbitrary Precision Floats, Next: Arbitrary Precision I `gawk' uses the GNU MPFR library for arbitrary precision floating-point arithmetic. The MPFR library provides precise control over precisions and rounding modes, and gives correctly rounded, reproducible, -platform-independent results. With the command-line option `--bignum' -or `-M', all floating-point arithmetic operators and numeric functions -can yield results to any desired precision level supported by MPFR. -Two built-in variables, `PREC' and `ROUNDMODE', provide control over -the working precision and the rounding mode (*note Setting Precision::, -and *note Setting Rounding Mode::). The precision and the rounding -mode are set globally for every operation to follow. +platform-independent results. With one of the command-line options +`--bignum' or `-M', all floating-point arithmetic operators and numeric +functions can yield results to any desired precision level supported by +MPFR. Two built-in variables, `PREC' and `ROUNDMODE', provide control +over the working precision and the rounding mode (*note Setting +Precision::, and *note Setting Rounding Mode::). The precision and the +rounding mode are set globally for every operation to follow. The default working precision for arbitrary precision floating-point -values is 53, and the default value for `ROUNDMODE' is `"N"', which -selects the IEEE-754 `roundTiesToEven' rounding mode (*note Rounding -Mode::).(1) `gawk' uses the default exponent range in MPFR (EMAX = 2^30 -- 1, EMIN = -EMAX) for all floating-point contexts. There is no -explicit mechanism to adjust the exponent range. MPFR does not +values is 53 bits, and the default value for `ROUNDMODE' is `"N"', +which selects the IEEE-754 `roundTiesToEven' rounding mode (*note +Rounding Mode::).(1) `gawk' uses the default exponent range in MPFR +(EMAX = 2^30 - 1, EMIN = -EMAX) for all floating-point contexts. There +is no explicit mechanism to adjust the exponent range. MPFR does not implement subnormal numbers by default, and this behavior cannot be changed in `gawk'. @@ -21059,7 +21090,7 @@ changed in `gawk'. ---------- Footnotes ---------- - (1) The default precision is 53, since according to the MPFR + (1) The default precision is 53 bits, since according to the MPFR documentation, the library should be able to exactly reproduce all computations with double-precision machine floating-point numbers (`double' type in C), except the default exponent range is much wider @@ -21074,10 +21105,11 @@ File: gawk.info, Node: Setting Precision, Next: Setting Rounding Mode, Up: Ar `gawk' uses a global working precision; it does not keep track of the precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the -current working precision. The default working precision is 53, which -can be modified using the built-in variable `PREC'. You can also set the -value to one of the following pre-defined case-insensitive strings to -emulate an IEEE-754 binary format: +current working precision. The default working precision is 53 bits, +which can be modified using the built-in variable `PREC'. You can also +set the value to one of the pre-defined case-insensitive strings shown +in *note table-predefined-precision-strings::, to emulate an IEEE-754 +binary format. `PREC' IEEE-754 Binary Format --------------------------------------------------- @@ -21087,10 +21119,12 @@ emulate an IEEE-754 binary format: `"quad"' Basic 128-bit quadruple precision. `"oct"' 256-bit octuple precision. +Table 15.3: Predefined precision strings for `PREC' + The following example illustrates the effects of changing precision on arithmetic operations: - $ gawk -M -v PREC=100 'BEGIN { x = 1.0e-400; print x + 0; \ + $ gawk -M -v PREC=100 'BEGIN { x = 1.0e-400; print x + 0 > PREC = "double"; print x + 0 }' -| 1e-400 -| 0 @@ -21148,11 +21182,11 @@ Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero -Table 15.3: `gawk' Rounding Modes +Table 15.4: `gawk' Rounding Modes `ROUNDMODE' has the default value `"N"', which selects the IEEE-754 -rounding mode `roundTiesToEven'. *note Table 15.3: -table-gawk-rounding-modes, lists `"A"' to select the IEEE-754 mode +rounding mode `roundTiesToEven'. In *note Table 15.4: +table-gawk-rounding-modes, `"A"' is listed to select the IEEE-754 mode `roundTiesToAway'. This is only available if your version of the MPFR library supports it; otherwise setting `ROUNDMODE' to this value has no effect. *Note Rounding Mode::, for the meanings of the various rounding @@ -21192,7 +21226,7 @@ print a floating-point constant: -| 0.1000000000000000000000000 In the first case, the number is stored with the default precision -of 53. +of 53 bits. File: gawk.info, Node: Changing Precision, Next: Exact Arithmetic, Prev: Floating-point Constants, Up: Arbitrary Precision Floats @@ -21252,8 +21286,8 @@ loss and underflow are often troublesome. When `gawk' tests the expressions `0.1 + 12.2' and `12.3' for equality using the machine double precision arithmetic, it decides that they are not equal! (*Note Floating-point Programming::.) You can get -the result you want by increasing the precision; 56 in this case will -get the job done: +the result you want by increasing the precision; 56 bits in this case +will get the job done: $ gawk -M -v PREC=56 'BEGIN { print (0.1 + 12.2 == 12.3) }' -| 1 @@ -21294,7 +21328,7 @@ floating-point arithmetic. In the example in *note Floating-point Programming::: $ gawk 'BEGIN { - > for (d = 1.1; d <= 1.5; d += 0.1) + > for (d = 1.1; d <= 1.5; d += 0.1) # loop five times (?) > i++ > print i > }' @@ -21310,14 +21344,14 @@ File: gawk.info, Node: Arbitrary Precision Integers, Prev: Arbitrary Precision 15.5 Arbitrary Precision Integer Arithmetic with `gawk' ======================================================= -If the option `--bignum' or `-M' is specified, `gawk' performs all -integer arithmetic using GMP arbitrary precision integers. Any number -that looks like an integer in a program source or data file is stored -as an arbitrary precision integer. The size of the integer is limited -only by your computer's memory. The current floating-point context has -no effect on operations involving integers. For example, the following -computes 5^4^3^2, the result of which is beyond the limits of ordinary -`gawk' numbers: +If one of the options `--bignum' or `-M' is specified, `gawk' performs +all integer arithmetic using GMP arbitrary precision integers. Any +number that looks like an integer in a program source or data file is +stored as an arbitrary precision integer. The size of the integer is +limited only by your computer's memory. The current floating-point +context has no effect on operations involving integers. For example, +the following computes 5^4^3^2, the result of which is beyond the +limits of ordinary `gawk' numbers: $ gawk -M 'BEGIN { > x = 5^4^3^2 @@ -21347,10 +21381,11 @@ term in Sylvester's sequence(1) using a recurrence: The output differs from the actual number, 113,423,713,055,421,844,361,000,443, because the default precision of -53 is not enough to represent the floating-point results exactly. You -can either increase the precision (100 is enough in this case), or -replace the floating-point constant `2.0' with an integer, to perform -all computations using integer arithmetic to get the correct output. +53 bits is not enough to represent the floating-point results exactly. +You can either increase the precision (100 bits is enough in this +case), or replace the floating-point constant `2.0' with an integer, to +perform all computations using integer arithmetic to get the correct +output. It will sometimes be necessary for `gawk' to implicitly convert an arbitrary precision integer into an arbitrary precision floating-point @@ -21386,7 +21421,7 @@ File: gawk.info, Node: Dynamic Extensions, Next: Language History, Prev: Arbi 16 Writing Extensions for `gawk' ******************************** -It is possible to add new built-in functions to `gawk' using +It is possible to add new functions written in C or C++ to `gawk' using dynamically loaded libraries. This facility is available on systems that support the C `dlopen()' and `dlsym()' functions. This major node describes how to create extensions using code written in C or C++. @@ -21406,6 +21441,7 @@ sample extensions are automatically built and installed when `gawk' is. * Plugin License:: A note about licensing. * Extension Mechanism Outline:: An outline of how it works. * Extension API Description:: A full description of the API. +* Finding Extensions:: How `gawk' finds compiled extensions. * Extension Example:: Example C code for an extension. * Extension Samples:: The sample extensions that ship with `gawk'. @@ -21431,11 +21467,12 @@ write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the "Application Programming Interface" (API) defined for this purpose by the `gawk' -developers. The rest of this major node explains the design decisions -behind the API, the facilities that it provides and how to use them, -and presents a small sample extension. In addition, it documents the -sample extensions included in the `gawk' distribution, and describes -the `gawkextlib' project. +developers. The rest of this major node explains the facilities that +the API provides and how to use them, and presents a small sample +extension. In addition, it documents the sample extensions included in +the `gawk' distribution, and describes the `gawkextlib' project. *Note +Extension Design::, for a discussion of the extension mechanism goals +and design. File: gawk.info, Node: Plugin License, Next: Extension Mechanism Outline, Prev: Extension Intro, Up: Dynamic Extensions @@ -21549,7 +21586,7 @@ Example::) and also the `testext.c' code for testing the APIs. * The API provides access to `gawk''s `do_XXX' values, reflecting command line options, like `do_lint', `do_profiling' and so on (*note Extension API Variables::). These are informational: an - extension cannot affect these inside `gawk'. In addition, + extension cannot affect their values inside `gawk'. In addition, attempting to assign to them produces a compile-time error. * The API also provides major and minor version numbers, so that an @@ -21559,7 +21596,7 @@ Example::) and also the `testext.c' code for testing the APIs. Versioning::, for details. -File: gawk.info, Node: Extension API Description, Next: Extension Example, Prev: Extension Mechanism Outline, Up: Dynamic Extensions +File: gawk.info, Node: Extension API Description, Next: Finding Extensions, Prev: Extension Mechanism Outline, Up: Dynamic Extensions 16.4 API Description ==================== @@ -21575,15 +21612,13 @@ This (rather large) minor node describes the API in detail. * Registration Functions:: Functions to register things with `gawk'. * Printing Messages:: Functions for printing messages. -* Updating `ERRNO':: Functions for updating `ERRNO'. +* Updating `ERRNO':: Functions for updating `ERRNO'. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. * Array Manipulation:: Functions for working with arrays. * Extension API Variables:: Variables provided by the API. * Extension API Boilerplate:: Boilerplate code for using the API. -* Finding Extensions:: How `gawk' finds compiled - extensions. File: gawk.info, Node: Extension API Functions Introduction, Next: General Data Types, Up: Extension API Description @@ -21619,14 +21654,14 @@ operations: into an array. * Symbol table access: retrieving a global variable, creating one, - or changing one. This also includes the ability to create a scalar - variable that will be _constant_ within `awk' code. + or changing one. * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. * Manipulating arrays: + - Retrieving, adding, deleting, and modifying elements - Getting the count of elements in an array @@ -21646,10 +21681,13 @@ operations: C Entity Header File ------------------------------------------- + `EOF' `<stdio.h>' `FILE' `<stdio.h>' `NULL' `<stddef.h>' `malloc()' `<stdlib.h>' - `memset()', `memcpy()' `<string.h>' + `memcpy()' `<string.h>' + `memset()' `<string.h>' + `realloc()' `<stdlib.h>' `size_t' `<sys/types.h>' `struct stat' `<sys/stat.h>' @@ -21657,7 +21695,8 @@ operations: fully standards-compliant, it is your responsibility to include the correct files in the correct way. This requirement is necessary in order to keep `gawkapi.h' clean, instead of becoming - a portability hodge-podge as can be seen in the `gawk' source code. + a portability hodge-podge as can be seen in some parts of the + `gawk' source code. To pass reasonable integer values for `ERRNO', you will also need to include `<errno.h>'. @@ -21676,17 +21715,17 @@ operations: _all_ strings passed into `gawk' from the extension _must_ come from `malloc()' and is managed by `gawk' from then on. - * The API defines several simple structs that map values as seen + * The API defines several simple `struct's that map values as seen from `awk'. A value can be a `double', a string, or an array (as - in multidimensional arrays, or when creating a new array). - Strings maintain both pointer and length since embedded `NUL' + in multidimensional arrays, or when creating a new array). String + values maintain both pointer and length since embedded `NUL' characters are allowed. - By intent, strings are maintained using the current multibyte - encoding (as defined by `LC_XXX' environment variables) and not - using wide characters. This matches how `gawk' stores strings - internally and also how characters are likely to be input and - output from files. + NOTE: By intent, strings are maintained using the current + multibyte encoding (as defined by `LC_XXX' environment + variables) and not using wide characters. This matches how + `gawk' stores strings internally and also how characters are + likely to be input and output from files. * When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type @@ -21697,7 +21736,7 @@ operations: However, if the request and actual type don't match, the access function returns "false" and fills in the type of the actual value that is there, so that the extension can, e.g., print an error - message ("scalar passed where array expected"). + message (such as "scalar passed where array expected"). While you may call the API functions by using the function pointers @@ -21720,7 +21759,7 @@ File: gawk.info, Node: General Data Types, Next: Requesting Values, Prev: Ext Chet Ramey The extension API defines a number of simple types and structures -for general purpose use. Additional, more specialized, data structures, +for general purpose use. Additional, more specialized, data structures are introduced in subsequent minor nodes, together with the functions that use them. @@ -21761,7 +21800,7 @@ that use them. ` AWK_STRING,' ` AWK_ARRAY,' ` AWK_SCALAR, /* opaque access to a variable */' -` AWK_VALUE_COOKIE /* for updating a previously created value */' +` AWK_VALUE_COOKIE /* for updating a previously created value */' `} awk_valtype_t;' This `enum' indicates the type of a value. It is used in the following `struct'. @@ -21929,7 +21968,7 @@ extension code would use them. to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. -`emalloc(pointer, type, size, message)' +`#define emalloc(pointer, type, size, message) ...' The arguments to this macro are as follows: `pointer' The pointer variable to point at the allocated storage. @@ -21955,7 +21994,7 @@ procedure calls that do not return a value. strcpy(message, greet); make_malloced_string(message, strlen(message), & result); -`erealloc(pointer, type, size, message)' +`#define erealloc(pointer, type, size, message) ...' This is like `emalloc()', but it calls `realloc()', instead of `malloc()'. The arguments are the same as for the `emalloc()' macro. @@ -22001,6 +22040,7 @@ Extension functions are described by the following record: Function names must obey the rules for `awk' identifiers. That is, they must begin with either a letter or an underscore, which may be followed by any number of letters, digits, and underscores. + Letter case in function names is significant. `awk_value_t *(*function)(int num_actual_args, awk_value_t *result);' This is a pointer to the C function that provides the desired @@ -22048,7 +22088,7 @@ function with `gawk' using the following function. A pointer to the function to be called before `gawk' exits. The `data' parameter will be the original value of `arg0'. The `exit_status' parameter is the exit status value that - `gawk' will pass to the `exit()' system call. + `gawk' intends to pass to the `exit()' system call. `arg0' A pointer to private data which `gawk' saves in order to pass @@ -22082,8 +22122,9 @@ File: gawk.info, Node: Input Parsers, Next: Output Wrappers, Prev: Extension By default, `gawk' reads text files as its input. It uses the value of `RS' to find the end of the record, and then uses `FS' (or -`FIELDWIDTHS') to split it into fields (*note Reading Files::). -Additionally, it sets the value of `RT' (*note Built-in Variables::). +`FIELDWIDTHS' or `FPAT') to split it into fields (*note Reading +Files::). Additionally, it sets the value of `RT' (*note Built-in +Variables::). If you want, you can provide your own custom input parser. An input parser's job is to return a record to the `gawk' record processing @@ -22116,7 +22157,7 @@ used for `RT', if any. const char *name; /* name of parser */ awk_bool_t (*can_take_file)(const awk_input_buf_t *iobuf); awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf); - awk_const struct awk_input_parser *awk_const next; /* for use by gawk */ + awk_const struct awk_input_parser *awk_const next; /* for gawk */ } awk_input_parser_t; The fields are: @@ -22182,10 +22223,10 @@ the `struct stat', or any combination of the above. Once `XXX_can_take_file()' has returned true, and `gawk' has decided to use your input parser, it calls `XXX_take_control_of()'. That -function then fills in at least the `get_record' field of the -`awk_input_buf_t'. It must also ensure that `fd' is not set to -`INVALID_HANDLE'. All of the fields that may be filled by -`XXX_take_control_of()' are as follows: +function then fills one of either the `get_record' field or the +`read_func' field in the `awk_input_buf_t'. It must also ensure that +`fd' is _not_ set to `INVALID_HANDLE'. All of the fields that may be +filled by `XXX_take_control_of()' are as follows: `void *opaque;' This is used to hold any state information needed by the input @@ -22256,8 +22297,8 @@ there is no need to set it unless an error occurs. If an error does occur, the function should return `EOF' and set `*errcode' to a non-zero value. In that case, if `*errcode' does not equal -1, `gawk' automatically updates the `ERRNO' variable based on -the value of `*errcode' (e.g., setting `*errcode = errno' should do the -right thing). +the value of `*errcode'. (In general, setting `*errcode = errno' +should do the right thing.) As an alternative to supplying a function that returns an input record, you may instead supply a function that simply reads bytes, and @@ -22303,7 +22344,7 @@ File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev: Input An "output wrapper" is the mirror image of an input parser. It allows an extension to take over the output to a file opened with the `>' or -`>>' operators (*note Redirection::). +`>>' I/O redirection operators (*note Redirection::). The output wrapper is very similar to the input parser structure: @@ -22311,7 +22352,7 @@ an extension to take over the output to a file opened with the `>' or const char *name; /* name of the wrapper */ awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf); awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf); - awk_const struct awk_output_wrapper *awk_const next; /* for use by gawk */ + awk_const struct awk_output_wrapper *awk_const next; /* for gawk */ } awk_output_wrapper_t; The members are as follows: @@ -22334,7 +22375,8 @@ an extension to take over the output to a file opened with the `>' or false otherwise. `awk_const struct output_wrapper *awk_const next;' - This is for use by `gawk'. + This is for use by `gawk'; therefore they are marked `awk_const' + so that the extension cannot modify them. The `awk_output_buf_t' structure looks like this: @@ -22420,7 +22462,7 @@ structures as described earlier. awk_bool_t (*take_control_of)(const char *name, awk_input_buf_t *inbuf, awk_output_buf_t *outbuf); - awk_const struct awk_two_way_processor *awk_const next; /* for use by gawk */ + awk_const struct awk_two_way_processor *awk_const next; /* for gawk */ } awk_two_way_processor_t; The fields are as follows: @@ -22441,7 +22483,8 @@ structures as described earlier. respectively. These structures were described earlier. `awk_const struct two_way_processor *awk_const next;' - This is for use by `gawk'. + This is for use by `gawk'; therefore they are marked `awk_const' + so that the extension cannot modify them. As with the input parser and output processor, you provide "yes I can take this" and "take over for this" functions, @@ -22578,13 +22621,17 @@ termed a "symbol table". an array. This routine cannot be used to update any of the predefined variables (such as `ARGC' or `NF'). + An extension can look up the value of `gawk''s special variables. +However, with the exception of the `PROCINFO' array, an extension +cannot change any of those variables. + File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Symbol table by name, Up: Symbol Table Access 16.4.9.2 Variable Access and Update by Cookie ............................................. -A "scalar cookie" is an opaque handle that provide access to a global +A "scalar cookie" is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in `gawk''s symbol table every time access is needed. This was discussed earlier, in *note General Data Types::. @@ -22605,11 +22652,11 @@ was discussed earlier, in *note General Data Types::. too, the built-in variables may not be updated. It is not obvious at first glance how to work with scalar cookies or -what their raison de^tre really is. In theory, the `sym_lookup()' and +what their raison d'e^tre really is. In theory, the `sym_lookup()' and `sym_update()' routines are all you really need to work with variables. -For example, you might have code that looked up the value of a -variable, evaluated a condition, and then possibly changed the value of -the variable based on the result of that evaluation, like so: +For example, you might have code that looks up the value of a variable, +evaluates a condition, and then possibly changes the value of the +variable based on the result of that evaluation, like so: /* do_magic --- do something really great */ @@ -22772,10 +22819,10 @@ changed too?" That's a great question. The answer is that no, it's not a problem. Internally, `gawk' uses reference-counted strings. This means that many -variables can share the same string, and `gawk' keeps track of the -usage. When a variable's value changes, `gawk' simply decrements the -reference count on the old value and updates the variable to use the -new value. +variables can share the same string value, and `gawk' keeps track of +the usage. When a variable's value changes, `gawk' simply decrements +the reference count on the old value and updates the variable to use +the new value. Finally, as part of your clean up action (*note Exit Callback Functions::) you should release any cached values that you created, @@ -22966,7 +23013,7 @@ File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array To "flatten" an array is create a structure that represents the full array in a fashion that makes it easy for C code to traverse the entire array. Test code in `extension/testext.c' does this, and also serves -as a nice example to show how to use the APIs. +as a nice example showing how to use the APIs. First, the `gawk' script that drives the test extension: @@ -22986,10 +23033,10 @@ as a nice example to show how to use the APIs. This code creates an array with `split()' (*note String Functions::) and then calls `dump_array_and_delete()'. That function looks up the array whose name is passed as the first argument, and deletes the -element at the index passed in the second argument. It then prints the -return value and checks if the element was indeed deleted. Here is the -C code that implements `dump_array_and_delete()'. It has been edited -slightly for presentation. +element at the index passed in the second argument. The `awk' code +then prints the return value and checks if the element was indeed +deleted. Here is the C code that implements `dump_array_and_delete()'. +It has been edited slightly for presentation. The first part declares variables, sets up the default return value in `result', and checks that the function was called with the correct @@ -23078,7 +23125,7 @@ over every element in the array, printing the index and element values. In addition, upon finding the element with the index that is supposed to be deleted, the function sets the `AWK_ELEMENT_DELETE' bit in the `flags' field of the element. When the array is released, `gawk' -traverses the flattened array, and deletes any element which have this +traverses the flattened array, and deletes any elements which have this flag bit set: for (i = 0; i < flat_array->count; i++) { @@ -23163,17 +23210,15 @@ code: value passed in to `sym_update()' before doing anything else with it, like so: - awk_value_t index, value; + awk_value_t value; awk_array_t new_array; - make_const_string("an index", 8, & index); - new_array = create_array(); val.val_type = AWK_ARRAY; val.array_cookie = new_array; /* install array in the symbol table */ - sym_update("array", & index, & val); + sym_update("array", & val); new_array = val.array_cookie; /* YOU MUST DO THIS */ @@ -23375,7 +23420,7 @@ built-in variable (*note Built-in Variables::). The others should not change during execution. -File: gawk.info, Node: Extension API Boilerplate, Next: Finding Extensions, Prev: Extension API Variables, Up: Extension API Description +File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variables, Up: Extension API Description 16.4.12 Boilerplate Code ------------------------ @@ -23476,10 +23521,10 @@ standard work. It does the following: `gawk'. -File: gawk.info, Node: Finding Extensions, Prev: Extension API Boilerplate, Up: Extension API Description +File: gawk.info, Node: Finding Extensions, Next: Extension Example, Prev: Extension API Description, Up: Dynamic Extensions -16.4.13 How `gawk' Finds Extensions ------------------------------------ +16.5 How `gawk' Finds Extensions +================================ Compiled extensions have to be installed in a directory where `gawk' can find them. If `gawk' is configured and built in the default @@ -23489,9 +23534,9 @@ of directories to search for compiled extensions. *Note AWKLIBPATH Variable::, for more information. -File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev: Extension API Description, Up: Dynamic Extensions +File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev: Finding Extensions, Up: Dynamic Extensions -16.5 Example: Some File Functions +16.6 Example: Some File Functions ================================= No matter where you go, there you are. @@ -23511,7 +23556,7 @@ implements these functions for `gawk' in an extension. File: gawk.info, Node: Internal File Description, Next: Internal File Ops, Up: Extension Example -16.5.1 Using `chdir()' and `stat()' +16.6.1 Using `chdir()' and `stat()' ----------------------------------- This minor node shows how to use the new functions at the `awk' level @@ -23634,7 +23679,7 @@ Elements::): File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops, Prev: Internal File Description, Up: Extension Example -16.5.2 C Code for `chdir()' and `stat()' +16.6.2 C Code for `chdir()' and `stat()' ---------------------------------------- Here is the C code for these extensions.(1) @@ -23888,13 +23933,15 @@ declarations and argument checking: awk_array_t array; int ret; struct stat sbuf; - int (*statfunc)(const char *path, struct stat *sbuf) = lstat; /* default */ + /* default is stat() */ + int (*statfunc)(const char *path, struct stat *sbuf) = lstat; assert(result != NULL); if (nargs != 2 && nargs != 3) { if (do_lint) - lintwarn(ext_id, _("stat: called with wrong number of arguments")); + lintwarn(ext_id, + _("stat: called with wrong number of arguments")); return make_number(-1, result); } @@ -23982,7 +24029,7 @@ version. File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops, Up: Extension Example -16.5.3 Integrating The Extensions +16.6.3 Integrating The Extensions --------------------------------- Now that the code is written, it must be possible to add it at runtime @@ -24062,7 +24109,7 @@ this Info file. *Note gawkextlib::, for WWW links to the tools. File: gawk.info, Node: Extension Samples, Next: gawkextlib, Prev: Extension Example, Up: Dynamic Extensions -16.6 The Sample Extensions In The `gawk' Distribution +16.7 The Sample Extensions In The `gawk' Distribution ===================================================== This minor node provides brief overviews of the sample extensions that @@ -24092,7 +24139,7 @@ the extension API. File: gawk.info, Node: Extension Sample File Functions, Next: Extension Sample Fnmatch, Up: Extension Samples -16.6.1 File Related Functions +16.7.1 File Related Functions ----------------------------- The `filefuncs' extension provides three different functions, as @@ -24150,7 +24197,7 @@ follows: The usage is: the `struct stat'. This element is only present for device files. `statdata["blksize"]' Corresponds to the `st_blksize' field - in the `struct stat'. if this field is + in the `struct stat', if this field is present on your system. (It is present on all modern systems that we know of.) `statdata["pmode"]' A human-readable version of the mode @@ -24170,8 +24217,8 @@ follows: The usage is: `result = fts(pathlist, flags, filedata)' Walk the file trees provided in `pathlist' and fill in the `filedata' array as described below. `flags' is the bitwise OR of - several predefined constant values, also as described below. - Return zero if there were no errors, otherwise return -1. + several predefined constant values, also described below. Return + zero if there were no errors, otherwise return -1. The `fts()' function provides a hook to the C library `fts()' routines for traversing file hierarchies. Instead of returning data @@ -24212,10 +24259,10 @@ requested hierarchies. whether or not `FTS_LOGICAL' is set. `FTS_SEEDOT' - By default, the `fts()' routines do not return entries for `.' - and `..'. This option causes entries for `..' to also be - included. (The extension always includes an entry for `.', - see below.) + By default, the `fts()' routines do not return entries for + `.' (dot) and `..' (dot-dot). This option causes entries for + dot-dot to also be included. (The extension always includes + an entry for dot, see below.) `FTS_XDEV' During a traversal, do not cross onto a different mounted @@ -24227,7 +24274,7 @@ requested hierarchies. is the name of the directory or file given in `pathlist'. The element for this index is itself an array. There are two cases. - _The path is a file._ + _The path is a file_ In this case, the array contains two or three elements: `"path"' @@ -24246,7 +24293,7 @@ requested hierarchies. also contain an element named `"error"', which is a string describing the error. - _The path is a directory._ + _The path is a directory_ In this case, the array contains one element for each entry in the directory. If an entry is a file, that element is as for files, just described. If the entry is a directory, that @@ -24278,7 +24325,7 @@ Otherwise it returns -1. File: gawk.info, Node: Extension Sample Fnmatch, Next: Extension Sample Fork, Prev: Extension Sample File Functions, Up: Extension Samples -16.6.2 Interface To `fnmatch()' +16.7.2 Interface To `fnmatch()' ------------------------------- This extension provides an interface to the C library `fnmatch()' @@ -24297,7 +24344,7 @@ one constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. The filename wildcard to match. `string' - The filename string, + The filename string. `flag' Either zero, or the bitwise OR of one or more of the flags in the @@ -24333,7 +24380,7 @@ occurred. File: gawk.info, Node: Extension Sample Fork, Next: Extension Sample Inplace, Prev: Extension Sample Fnmatch, Up: Extension Samples -16.6.3 Interface To `fork()', `wait()' and `waitpid()' +16.7.3 Interface To `fork()', `wait()' and `waitpid()' ------------------------------------------------------ The `fork' extension adds three functions, as follows. @@ -24370,11 +24417,11 @@ The `fork' extension adds three functions, as follows. File: gawk.info, Node: Extension Sample Inplace, Next: Extension Sample Ord, Prev: Extension Sample Fork, Up: Extension Samples -16.6.4 Enabling in-place file editing. --------------------------------------- +16.7.4 Enabling In-Place File Editing +------------------------------------- -The `inplace' extension emulates the `sed' `-i' option which performs -"in placed" editing of each input file. It uses the bundled +The `inplace' extension emulates GNU `sed''s `-i' option which performs +"in place" editing of each input file. It uses the bundled `inplace.awk' include file to invoke the extension properly: # inplace --- load and invoke the inplace extension. @@ -24413,22 +24460,25 @@ processing immediately without damaging the original file. > { print }' file1 file2 file3 We leave it as an exercise to write a wrapper script that presents an -interface similar to the `sed' `-i' option. +interface similar to `sed -i'. File: gawk.info, Node: Extension Sample Ord, Next: Extension Sample Readdir, Prev: Extension Sample Inplace, Up: Extension Samples -16.6.5 Character and Numeric values: `ord()' and `chr()' +16.7.5 Character and Numeric values: `ord()' and `chr()' -------------------------------------------------------- The `ordchr' extension adds two functions, named `ord()' and `chr()', as follows. +`@load "ordchr"' + This is how you load the extension. + `number = ord(string)' Return the numeric value of the first character in `string'. `char = chr(number)' - Return the string whose first character is that represented by + Return a string whose first character is that represented by `number'. These functions are inspired by the Pascal language functions of the @@ -24442,7 +24492,7 @@ same name. Here is an example: File: gawk.info, Node: Extension Sample Readdir, Next: Extension Sample Revout, Prev: Extension Sample Ord, Up: Extension Samples -16.6.6 Reading Directories +16.7.6 Reading Directories -------------------------- The `readdir' extension adds an input parser for directories. The @@ -24457,8 +24507,8 @@ returned as a record. The record consists of three fields. The first two are the inode number and the filename, separated by a forward slash character. On systems where the directory entry contains the file type, the record -has a third field which is a single letter indicating the type of the -file: +has a third field (also separated by a slash) which is a single letter +indicating the type of the file: Letter File Type -------------------------------------------------------------------------- @@ -24490,7 +24540,7 @@ always `u'. File: gawk.info, Node: Extension Sample Revout, Next: Extension Sample Rev2way, Prev: Extension Sample Readdir, Up: Extension Samples -16.6.7 Reversing Output +16.7.7 Reversing Output ----------------------- The `revoutput' extension adds a simple output wrapper that reverses @@ -24510,7 +24560,7 @@ unwary. Here is an example: File: gawk.info, Node: Extension Sample Rev2way, Next: Extension Sample Read write array, Prev: Extension Sample Revout, Up: Extension Samples -16.6.8 Two-Way I/O Example +16.7.8 Two-Way I/O Example -------------------------- The `revtwoway' extension adds a simple two-way processor that reverses @@ -24532,7 +24582,7 @@ example shows how to use it: File: gawk.info, Node: Extension Sample Read write array, Next: Extension Sample Readfile, Prev: Extension Sample Rev2way, Up: Extension Samples -16.6.9 Dumping and Restoring An Array +16.7.9 Dumping and Restoring An Array ------------------------------------- The `rwarray' extension adds two functions, named `writea()' and @@ -24554,10 +24604,10 @@ The `rwarray' extension adds two functions, named `writea()' and `writea()' in the sense that the contents are the same. However, due to implementation issues, the array traversal order of the recreated array is likely to be different from that of the original array. As array -traversal order in `awk' is by default undefined, this is not -(technically) a problem. If you need to guarantee a particular -traversal order, use the array sorting features in `gawk' to do so -(*note Array Sorting::). +traversal order in `awk' is by default undefined, this is (technically) +not a problem. If you need to guarantee a particular traversal order, +use the array sorting features in `gawk' to do so (*note Array +Sorting::). The file contains binary data. All integral values are written in network byte order. However, double precision floating-point values @@ -24576,11 +24626,14 @@ restored on systems with a different one, but this has not been tried. File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample API Tests, Prev: Extension Sample Read write array, Up: Extension Samples -16.6.10 Reading An Entire File +16.7.10 Reading An Entire File ------------------------------ The `readfile' extension adds a single function named `readfile()': +`@load "readfile"' + This is how you load the extension. + `result = readfile("/some/path")' The argument is the name of the file to read. The return value is a string containing the entire contents of the requested file. @@ -24599,7 +24652,7 @@ The `readfile' extension adds a single function named `readfile()': File: gawk.info, Node: Extension Sample API Tests, Next: Extension Sample Time, Prev: Extension Sample Readfile, Up: Extension Samples -16.6.11 API Tests +16.7.11 API Tests ----------------- The `testext' extension exercises parts of the extension API that are @@ -24611,13 +24664,16 @@ code and runs the tests. See the source file for more information. File: gawk.info, Node: Extension Sample Time, Prev: Extension Sample API Tests, Up: Extension Samples -16.6.12 Extension Time Functions +16.7.12 Extension Time Functions -------------------------------- -These functions can be used by either invoking `gawk' with a +These functions can be used either by invoking `gawk' with a command-line argument of `-l time' or by inserting `@load "time"' in your script. +`@load "time"' + This is how you load the extension. + `the_time = gettimeofday()' Return the time in seconds that has elapsed since 1970-01-01 UTC as a floating point value. If the time is unavailable on this @@ -24640,7 +24696,7 @@ your script. File: gawk.info, Node: gawkextlib, Prev: Extension Samples, Up: Dynamic Extensions -16.7 The `gawkextlib' Project +16.8 The `gawkextlib' Project ============================= The `gawkextlib' (http://sourceforge.net/projects/gawkextlib/) project @@ -24696,7 +24752,8 @@ follows. First, build and install `gawk': make && make check Build and check that all is OK If you write an extension that you wish to share with other `gawk' -users, please consider doing so through the `gawkextlib' project. +users, please consider doing so through the `gawkextlib' project. See +the project's web site for more information. File: gawk.info, Node: Language History, Next: Installation, Prev: Dynamic Extensions, Up: Top @@ -24859,6 +24916,18 @@ introduced the following changes into the language: * More complete documentation of many of the previously undocumented features of the language. + In 2012, a number of extensions that had been commonly available for +many years were finally added to POSIX. They are: + + * The `fflush()' built-in function for flushing buffered output + (*note I/O Functions::). + + * The `nextfile' statement (*note Nextfile Statement::). + + * The ability to delete all of an array at once with `delete ARRAY' + (*note Delete::). + + *Note Common Extensions::, for a list of common extensions not permitted by the POSIX standard. @@ -24884,8 +24953,7 @@ in his version of `awk'. Definition Syntax::). * The `fflush()' built-in function for flushing buffered output - (*note I/O Functions::). As of December 2012, this function is - now standardized by POSIX. + (*note I/O Functions::). *Note Common Extensions::, for a full list of the extensions @@ -25065,6 +25133,7 @@ Feature BWK Awk Mawk GNU Awk `/dev/stdout' special file X X X `/dev/stderr' special file X X X `**' and `**=' operators X X +`fflush()' function X X X `func' keyword X X `nextfile' statement X X X `delete' without subscript X X X @@ -25281,11 +25350,25 @@ Info file, in approximate chronological order: * Patrick T.J. McPhee contributed the code for dynamic loading in Windows32 environments. (This is no longer supported) - * John Haque reworked the `gawk' internals to use a byte-code engine, - providing the `gawk' debugger for `awk' programs. + * John Haque made the following contributions: + + - The modifications to convert `gawk' into a byte-code + interpreter, including the debugger. + + - The additional modifications for support of arbitrary + precision arithmetic. + + - The initial text of *note Arbitrary Precision Arithmetic::. + + - The work to merge the three versions of `gawk' into one, for + the 4.1 release. * Efraim Yawitz contributed the original text for *note Debugger::. + * The development of the extension API first released with `gawk' + 4.1 was driven primarily by Arnold Robbins and Andrew Schorr, with + notable contributions from the rest of the development team. + * Arnold Robbins has been working on `gawk' since 1988, at first helping David Trueman, and as the primary maintainer since around 1994. @@ -26345,6 +26428,12 @@ Libmawk This is an embeddable `awk' interpreter derived from `mawk'. For more information see `http://repo.hu/projects/libmawk/'. +`pawk' + This is a Python module that claims to bring `awk'-like features + to Python. See `https://github.com/alecthomas/pawk' for more + information. (This is not related to Nelson Beebe's modified + version of Brian Kernighan's `awk', described earlier.) + QSE Awk This is an embeddable `awk' interpreter. For more information see `http://code.google.com/p/qse/' and `http://awk.info/?tools/qse'. @@ -26375,7 +26464,7 @@ and maintainers of `gawk'. Everything in it applies specifically to * Future Extensions:: New features that may be implemented one day. * Implementation Limitations:: Some limitations of the implementation. * Extension Design:: Design notes about the extension API. -* Old Extension Mechansim:: Some compatibility for old extensions. +* Old Extension Mechanism:: Some compatibility for old extensions. File: gawk.info, Node: Compatibility Mode, Next: Additions, Up: Notes @@ -26453,15 +26542,10 @@ access the repository using: patch, and send that to the `gawk' maintainer; see *note Bugs::, for how to do that. - Finally, if you cannot install Git (e.g., if it hasn't been ported -yet to your operating system), you can use the Git-CVS gateway to check -out a copy using CVS, as follows: - - cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/gawk.git co -d gawk master - - Note that this gateway is flakey; you may have better luck using a -more modern version control system like Bazaar, that has a Git plug-in -for working with Git repositories. + Once upon a time there was Git-CVS gateway for use by people who +could not install Git. However, this gateway no longer works, so you +may have better luck using a more modern version control system like +Bazaar, that has a Git plug-in for working with Git repositories. File: gawk.info, Node: Adding Code, Next: New Ports, Prev: Accessing The Source, Up: Additions @@ -26538,7 +26622,7 @@ possible to include your changes: of `switch' statements, instead of just the plain pointer or character value. - * Use `true', `false' for `bool' values, the `NULL' symbolic + * Use `true' and `false' for `bool' values, the `NULL' symbolic constant for pointer values, and the character constant `'\0'' where appropriate, instead of `1' and `0'. @@ -26870,7 +26954,7 @@ Size of a literal string `MAX_INT ' Size of a printf string `MAX_INT ' -File: gawk.info, Node: Extension Design, Next: Old Extension Mechansim, Prev: Implementation Limitations, Up: Notes +File: gawk.info, Node: Extension Design, Next: Old Extension Mechanism, Prev: Implementation Limitations, Up: Notes C.5 Extension API Design ======================== @@ -26888,7 +26972,7 @@ mechanisms and design remained unchanged for close to 15 years, until `gawk' included some sample extensions, of which a few were really useful. However, it was clear from the outset that the extension -mechanism was bolted onto the side and was not really thought out. +mechanism was bolted onto the side and was not really well thought out. * Menu: @@ -26948,9 +27032,9 @@ Some goals for the new API were: * The API should provide _binary_ compatibility across `gawk' releases as long as the API itself does not change. - * The API should enable extensions written in C to have roughly the - same "appearance" to `awk'-level code as `awk' functions do. This - means that extensions should have: + * The API should enable extensions written in C or C++ to have + roughly the same "appearance" to `awk'-level code as `awk' + functions do. This means that extensions should have: - The ability to access function parameters. @@ -27076,30 +27160,29 @@ The API can later be expanded, in two ways: identify the extension calling into it, should it need to know. * Similarly, the extension passes a "name space" into `gawk' when it - registers each extension function. This allows a future mechanism - for grouping extension functions and possibly avoiding name - conflicts. + registers each extension function. This accommodates a possible + future mechanism for grouping extension functions and possibly + avoiding name conflicts. Of course, as of this writing, no decisions have been made with respect to any of the above. -File: gawk.info, Node: Old Extension Mechansim, Prev: Extension Design, Up: Notes +File: gawk.info, Node: Old Extension Mechanism, Prev: Extension Design, Up: Notes C.6 Compatibility For Old Extensions ==================================== *note Dynamic Extensions::, describes the supported API and mechanisms -for writing extensions for `gawk'. This API was introduced in *FIXME: -VERSION*. However, for many years `gawk' provided an extension -mechanism that required knowledge of `gawk' internals and that was not -as well designed. - - In order to provide a transition period, `gawk' version *FIXME: -VERSION* 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 -release. +for writing extensions for `gawk'. This API was introduced in version +4.1. However, for many years `gawk' provided an extension mechanism +that required knowledge of `gawk' internals and that was not as well +designed. + + In order to provide a transition period, `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 release. Briefly, original-style extensions should be compiled by including the `awk.h' header file in the extension source code. Additionally, you @@ -27114,7 +27197,7 @@ This function in turn finds and loads the shared object file containing the extension and calls its `dl_load()' C routine. Because original-style and new-style extensions use different -initialiation routines (`dl_load()' versus `dlload()'), they may safely +initialization routines (`dl_load()' versus `dlload()'), they may safely be installed in the same directory (to be found by `AWKLIBPATH') without conflict. @@ -27779,6 +27862,11 @@ Pattern the input record against a regular expression. (*Note Pattern Overview::.) +PEBKAC + An acronym describing what is possibly the most frequent source of + computer usage problems. (Problem Exists Between Keyboard And + Chair.) + POSIX The name for a series of standards that specify a Portable Operating System interface. The "IX" denotes the Unix heritage of @@ -29209,7 +29297,7 @@ Index * * (asterisk), * operator, as regexp operator: Regexp Operators. (line 87) * * (asterisk), * operator, null strings, matching: Gory Details. - (line 165) + (line 164) * * (asterisk), ** operator <1>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) * * (asterisk), **= operator <1>: Precedence. (line 95) @@ -29324,9 +29412,9 @@ Index * / (forward slash), /= operator <1>: Precedence. (line 95) * / (forward slash), /= operator: Assignment Ops. (line 129) * / (forward slash), /= operator, vs. /=.../ regexp constant: Assignment Ops. - (line 148) + (line 147) * / (forward slash), patterns and: Expression Patterns. (line 24) -* /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) +* /= operator vs. /=.../ regexp constant: Assignment Ops. (line 147) * /dev/... special files (gawk): Special FD. (line 46) * /dev/fd/N special files: Special FD. (line 46) * /inet/... special files (gawk): TCP/IP Networking. (line 6) @@ -29411,7 +29499,7 @@ Index * \ (backslash), in bracket expressions: Bracket Expressions. (line 17) * \ (backslash), in escape sequences: Escape Sequences. (line 6) * \ (backslash), in escape sequences, POSIX and: Escape Sequences. - (line 113) + (line 112) * \ (backslash), regexp constants: Computed Regexps. (line 28) * ^ (caret) <1>: GNU Regexp Operators. (line 59) @@ -29438,14 +29526,7 @@ Index * Ada programming language: Glossary. (line 20) * adding, features to gawk: Adding Code. (line 6) * adding, fields: Changing Fields. (line 53) -* advanced features, buffering: I/O Functions. (line 107) -* advanced features, close() function: Close Files And Pipes. - (line 131) -* advanced features, constants, values of: Nondecimal-numbers. - (line 67) -* advanced features, data files as single record: Records. (line 180) * advanced features, fixed-width data: Constant Size. (line 9) -* advanced features, FNR/NR variables: Auto-set. (line 295) * advanced features, gawk: Advanced Features. (line 6) * advanced features, gawk, network programming: TCP/IP Networking. (line 6) @@ -29455,10 +29536,6 @@ Index (line 23) * advanced features, network connections, See Also networks, connections: Advanced Features. (line 6) -* advanced features, null strings, matching: Gory Details. (line 165) -* advanced features, operators, precedence: Increment Ops. (line 61) -* advanced features, piping into sh: Redirection. (line 143) -* advanced features, regexp constants: Assignment Ops. (line 148) * advanced features, specifying field content: Splitting By Content. (line 9) * Aho, Alfred <1>: Contributors. (line 12) @@ -29470,7 +29547,7 @@ Index * amazing awk assembler (aaa): Glossary. (line 12) * amazingly workable formatter (awf): Glossary. (line 25) * ambiguity, syntactic: /= operator vs. /=.../ regexp constant: Assignment Ops. - (line 148) + (line 147) * ampersand (&), && operator <1>: Precedence. (line 86) * ampersand (&), && operator: Boolean Ops. (line 57) * ampersand (&), gsub()/gensub()/sub() functions and: Gory Details. @@ -29487,7 +29564,7 @@ Index * ARGC/ARGV variables: Auto-set. (line 11) * ARGC/ARGV variables, command-line arguments: Other Arguments. (line 12) -* ARGC/ARGV variables, portability and: Executable Scripts. (line 43) +* ARGC/ARGV variables, portability and: Executable Scripts. (line 42) * ARGIND variable: Auto-set. (line 40) * ARGIND variable, command-line arguments: Other Arguments. (line 12) * arguments, command-line <1>: ARGC and ARGV. (line 6) @@ -29549,7 +29626,7 @@ Index * asterisk (*), * operator, as regexp operator: Regexp Operators. (line 87) * asterisk (*), * operator, null strings, matching: Gory Details. - (line 165) + (line 164) * asterisk (*), ** operator <1>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) * asterisk (*), **= operator <1>: Precedence. (line 95) @@ -29667,7 +29744,7 @@ Index * backslash (\), in bracket expressions: Bracket Expressions. (line 17) * backslash (\), in escape sequences: Escape Sequences. (line 6) * backslash (\), in escape sequences, POSIX and: Escape Sequences. - (line 113) + (line 112) * backslash (\), regexp constants: Computed Regexps. (line 28) * backtrace debugger command: Execution Stack. (line 13) * BBS-list file: Sample Data Files. (line 6) @@ -29745,14 +29822,14 @@ Index * Brian Kernighan's awk, extensions: BTL. (line 6) * Broder, Alan J.: Contributors. (line 88) * Brown, Martin: Contributors. (line 82) -* BSD-based operating systems: Glossary. (line 619) +* 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 92) * Buening, Andreas: Acknowledgments. (line 60) * buffering, input/output <1>: Two-way I/O. (line 70) -* buffering, input/output: I/O Functions. (line 139) -* buffering, interactive vs. noninteractive: I/O Functions. (line 107) +* buffering, input/output: I/O Functions. (line 137) +* buffering, interactive vs. noninteractive: I/O Functions. (line 106) * buffers, flushing: I/O Functions. (line 29) * buffers, operators for: GNU Regexp Operators. (line 48) @@ -29809,10 +29886,11 @@ Index * close() function: Getline/Variable/File. (line 30) * close() function, return values: Close Files And Pipes. - (line 131) + (line 130) * close() function, two-way pipes and: Two-way I/O. (line 77) * Close, Diane <1>: Contributors. (line 21) * Close, Diane: Manual History. (line 41) +* Collado, Manuel: Acknowledgments. (line 60) * collating elements: Bracket Expressions. (line 69) * collating symbols: Bracket Expressions. (line 76) * Colombo, Antonio: Acknowledgments. (line 60) @@ -29930,7 +30008,7 @@ Index * d.c., See dark corner: Conventions. (line 38) * dark corner <1>: Glossary. (line 197) * dark corner <2>: Truth Values. (line 24) -* dark corner <3>: Assignment Ops. (line 148) +* dark corner <3>: Assignment Ops. (line 147) * dark corner: Conventions. (line 38) * dark corner, ^, in FS: Regexp Field Splitting. (line 59) @@ -29938,19 +30016,19 @@ Index (line 43) * dark corner, break statement: Break Statement. (line 51) * dark corner, close() function: Close Files And Pipes. - (line 131) + (line 130) * dark corner, command-line arguments: Assignment Options. (line 43) * dark corner, continue statement: Continue Statement. (line 43) * dark corner, CONVFMT variable: Conversion. (line 40) * dark corner, escape sequences: Other Arguments. (line 31) * dark corner, escape sequences, for metacharacters: Escape Sequences. - (line 136) + (line 134) * dark corner, exit statement: Exit Statement. (line 30) * dark corner, field separators: Field Splitting Summary. - (line 47) + (line 46) * dark corner, FILENAME variable <1>: Auto-set. (line 93) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 295) +* dark corner, FNR/NR variables: Auto-set. (line 311) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) @@ -29963,11 +30041,11 @@ Index * dark corner, regexp constants: Using Constant Regexps. (line 6) * dark corner, regexp constants, /= operator and: Assignment Ops. - (line 148) + (line 147) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) * dark corner, split() function: String Functions. (line 361) -* dark corner, strings, storing: Records. (line 196) +* dark corner, strings, storing: Records. (line 195) * dark corner, value of ARGV[0]: Auto-set. (line 35) * data, fixed-width: Constant Size. (line 9) * data-driven languages: Basic High Level. (line 85) @@ -30020,16 +30098,16 @@ Index (line 39) * debugger commands, frame: Execution Stack. (line 25) * debugger commands, h (help): Miscellaneous Debugger Commands. - (line 68) + (line 66) * debugger commands, help: Miscellaneous Debugger Commands. - (line 68) + (line 66) * debugger commands, i (info): Debugger Info. (line 13) * debugger commands, ignore: Breakpoint Control. (line 87) * debugger commands, info: Debugger Info. (line 13) * debugger commands, l (list): Miscellaneous Debugger Commands. - (line 74) + (line 72) * debugger commands, list: Miscellaneous Debugger Commands. - (line 74) + (line 72) * debugger commands, n (next): Debugger Execution Control. (line 43) * debugger commands, next: Debugger Execution Control. @@ -30047,9 +30125,9 @@ Index * debugger commands, printf: Viewing And Changing Data. (line 54) * debugger commands, q (quit): Miscellaneous Debugger Commands. - (line 101) + (line 99) * debugger commands, quit: Miscellaneous Debugger Commands. - (line 101) + (line 99) * debugger commands, r (run): Debugger Execution Control. (line 62) * debugger commands, return: Debugger Execution Control. @@ -30071,7 +30149,7 @@ Index * debugger commands, t (tbreak): Breakpoint Control. (line 90) * debugger commands, tbreak: Breakpoint Control. (line 90) * debugger commands, trace: Miscellaneous Debugger Commands. - (line 110) + (line 108) * debugger commands, u (until): Debugger Execution Control. (line 83) * debugger commands, undisplay: Viewing And Changing Data. @@ -30097,6 +30175,7 @@ Index * 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 196) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 88) @@ -30152,16 +30231,16 @@ Index * 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 246) +* differences in awk and gawk, RT variable: Auto-set. (line 263) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. (line 349) * differences in awk and gawk, strings: Scalar Constants. (line 20) -* differences in awk and gawk, strings, storing: Records. (line 192) +* differences in awk and gawk, strings, storing: Records. (line 191) * differences in awk and gawk, strtonum() function (gawk): String Functions. (line 404) -* differences in awk and gawk, SYMTAB variable: Auto-set. (line 254) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 271) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 162) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. @@ -30191,7 +30270,6 @@ Index * double quote ("), regexp constants: Computed Regexps. (line 28) * down debugger command: Execution Stack. (line 21) * Drepper, Ulrich: Acknowledgments. (line 52) -* DuBois, John: Acknowledgments. (line 60) * dump debugger command: Miscellaneous Debugger Commands. (line 9) * dupword.awk program: Dupword Program. (line 31) @@ -30246,7 +30324,7 @@ Index * ERRNO variable <2>: Auto-set. (line 73) * ERRNO variable <3>: BEGINFILE/ENDFILE. (line 26) * ERRNO variable <4>: Close Files And Pipes. - (line 139) + (line 138) * ERRNO variable: Getline. (line 19) * error handling: Special FD. (line 16) * error handling, ERRNO variable and: Auto-set. (line 73) @@ -30256,7 +30334,7 @@ Index * escape sequences: Escape Sequences. (line 6) * eval debugger command: Viewing And Changing Data. (line 23) -* evaluation order: Increment Ops. (line 61) +* evaluation order: Increment Ops. (line 60) * evaluation order, concatenation: Concatenation. (line 42) * evaluation order, functions: Calling Built-in. (line 30) * examining fields: Fields. (line 6) @@ -30309,7 +30387,7 @@ Index * extensions, common, single character fields: Single Character Fields. (line 6) * extensions, in gawk, not in POSIX awk: POSIX/GNU. (line 6) -* extract.awk program: Extract Program. (line 78) +* extract.awk program: Extract Program. (line 79) * extraction, of marked strings (internationalization): String Extraction. (line 6) * f debugger command (alias for frame): Execution Stack. (line 25) @@ -30335,7 +30413,7 @@ Index * field separators, on command line: Command Line Field Separator. (line 6) * field separators, POSIX and <1>: Field Splitting Summary. - (line 41) + (line 40) * field separators, POSIX and: Fields. (line 6) * field separators, regular expressions as <1>: Regexp Field Splitting. (line 6) @@ -30377,7 +30455,7 @@ Index * files, /inet/... (gawk): TCP/IP Networking. (line 6) * files, /inet4/... (gawk): TCP/IP Networking. (line 6) * files, /inet6/... (gawk): TCP/IP Networking. (line 6) -* files, as single records: Records. (line 201) +* files, as single records: Records. (line 200) * files, awk programs in: Long. (line 6) * files, awkprof.out: Profiling. (line 6) * files, awkvars.out: Options. (line 107) @@ -30428,7 +30506,7 @@ Index * floating-point, numbers: General Arithmetic. (line 6) * FNR variable <1>: Auto-set. (line 103) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 295) +* FNR variable, changing: Auto-set. (line 311) * for statement: For Statement. (line 6) * for statement, in arrays: Scanning an Array. (line 20) * format specifiers, mixing regular with positional specifiers: Printf Ordering. @@ -30444,7 +30522,7 @@ Index * forward slash (/), /= operator <1>: Precedence. (line 95) * forward slash (/), /= operator: Assignment Ops. (line 129) * forward slash (/), /= operator, vs. /=.../ regexp constant: Assignment Ops. - (line 148) + (line 147) * forward slash (/), patterns and: Expression Patterns. (line 24) * FPAT variable <1>: User-modified. (line 45) * FPAT variable: Splitting By Content. @@ -30455,7 +30533,7 @@ Index * Free Software Foundation (FSF) <1>: Glossary. (line 305) * Free Software Foundation (FSF) <2>: Getting. (line 10) * Free Software Foundation (FSF): Manual History. (line 6) -* FreeBSD: Glossary. (line 619) +* FreeBSD: Glossary. (line 624) * FS variable <1>: User-modified. (line 56) * FS variable: Field Separators. (line 14) * FS variable, --field-separator option and: Options. (line 21) @@ -30517,7 +30595,7 @@ Index (line 47) * functions, user-defined, next/nextfile statements and: Next Statement. (line 45) -* G-d: Acknowledgments. (line 83) +* G-d: Acknowledgments. (line 78) * Garfinkle, Scott: Contributors. (line 35) * gawk program, dynamic profiling: Profiling. (line 171) * gawk, ARGIND variable in: Other Arguments. (line 12) @@ -30543,9 +30621,9 @@ Index * gawk, ERRNO variable in <2>: Auto-set. (line 73) * gawk, ERRNO variable in <3>: BEGINFILE/ENDFILE. (line 26) * gawk, ERRNO variable in <4>: Close Files And Pipes. - (line 139) + (line 138) * gawk, ERRNO variable in: Getline. (line 19) -* gawk, escape sequences: Escape Sequences. (line 125) +* gawk, escape sequences: Escape Sequences. (line 124) * gawk, extensions, disabling: Options. (line 247) * gawk, features, adding: Adding Code. (line 6) * gawk, features, advanced: Advanced Features. (line 6) @@ -30596,7 +30674,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 246) +* gawk, RT variable in <1>: Auto-set. (line 263) * gawk, RT variable in <2>: Getline/Variable/File. (line 10) * gawk, RT variable in <3>: Multiple Line. (line 129) @@ -30605,7 +30683,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 254) +* gawk, SYMTAB array in: Auto-set. (line 271) * gawk, TEXTDOMAIN variable in: User-modified. (line 162) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 36) @@ -30657,7 +30735,7 @@ Index * gettext library, locale categories: Explaining gettext. (line 80) * gettext() function (C library): Explaining gettext. (line 62) * gettimeofday time extension function: Extension Sample Time. - (line 10) + (line 13) * GMP: Arbitrary Precision Arithmetic. (line 6) * GNITS mailing list: Acknowledgments. (line 52) @@ -30671,7 +30749,7 @@ Index * GNU long options, printing list of: Options. (line 168) * GNU Project <1>: Glossary. (line 323) * GNU Project: Manual History. (line 11) -* GNU/Linux <1>: Glossary. (line 619) +* GNU/Linux <1>: Glossary. (line 624) * GNU/Linux <2>: I18N Example. (line 55) * GNU/Linux: Manual History. (line 28) * GPL (General Public License) <1>: Glossary. (line 314) @@ -30688,16 +30766,15 @@ Index * gsub() function, arguments of: String Functions. (line 462) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Debugger Commands. - (line 68) + (line 66) * Hankerson, Darrel <1>: Contributors. (line 61) * Hankerson, Darrel: Acknowledgments. (line 60) -* Haque, John <1>: Contributors. (line 103) -* Haque, John: Acknowledgments. (line 60) +* Haque, John: Contributors. (line 103) * Hartholz, Elaine: Acknowledgments. (line 38) * Hartholz, Marshall: Acknowledgments. (line 38) * Hasegawa, Isamu: Contributors. (line 94) * help debugger command: Miscellaneous Debugger Commands. - (line 68) + (line 66) * hexadecimal numbers: Nondecimal-numbers. (line 6) * hexadecimal values, enabling interpretation of: Options. (line 207) * histsort.awk program: History Sorting. (line 25) @@ -30822,7 +30899,7 @@ Index * Kernighan, Brian <3>: Contributors. (line 12) * Kernighan, Brian <4>: BTL. (line 6) * Kernighan, Brian <5>: Concatenation. (line 6) -* Kernighan, Brian <6>: Acknowledgments. (line 77) +* Kernighan, Brian <6>: Acknowledgments. (line 72) * Kernighan, Brian <7>: Conventions. (line 34) * Kernighan, Brian: History. (line 17) * kill command, dynamic profiling: Profiling. (line 180) @@ -30831,7 +30908,7 @@ Index (line 6) * Kwok, Conrad: Contributors. (line 35) * l debugger command (alias for list): Miscellaneous Debugger Commands. - (line 74) + (line 72) * labels.awk program: Labels Program. (line 51) * languages, data-driven: Basic High Level. (line 85) * Laurie, Dirk: Changing Precision. (line 6) @@ -30901,11 +30978,11 @@ Index * lint checking, undefined functions: Pass By Value/Reference. (line 88) * LINT variable: User-modified. (line 98) -* Linux <1>: Glossary. (line 619) +* Linux <1>: Glossary. (line 624) * Linux <2>: I18N Example. (line 55) * Linux: Manual History. (line 28) * list debugger command: Miscellaneous Debugger Commands. - (line 74) + (line 72) * loading, library: Options. (line 173) * local variables: Variable Scope. (line 6) * locale categories: Explaining gettext. (line 80) @@ -30930,18 +31007,19 @@ Index * lvalues/rvalues: Assignment Ops. (line 32) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 52) +* Malmberg, John: Acknowledgments. (line 60) * mark parity: Ordinal Functions. (line 45) * marked string extraction (internationalization): String Extraction. (line 6) * marked strings, extracting: String Extraction. (line 6) -* Marx, Groucho: Increment Ops. (line 61) +* Marx, Groucho: Increment Ops. (line 60) * match() function: String Functions. (line 206) * match() function, RSTART/RLENGTH variables: String Functions. (line 223) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) -* matching, null strings: Gory Details. (line 165) +* matching, null strings: Gory Details. (line 164) * mawk program: Other Versions. (line 44) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 41) @@ -30951,7 +31029,7 @@ Index (line 47) * message object files, specifying directory of: Explaining gettext. (line 53) -* metacharacters, escape sequences for: Escape Sequences. (line 132) +* metacharacters, escape sequences for: Escape Sequences. (line 130) * mktime() function (gawk): Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 103) @@ -30971,7 +31049,7 @@ Index * namespace issues, functions: Definition Syntax. (line 20) * nawk utility: Names. (line 17) * negative zero: Unexpected Results. (line 34) -* NetBSD: Glossary. (line 619) +* NetBSD: Glossary. (line 624) * networks, programming: TCP/IP Networking. (line 6) * networks, support for: Special Network. (line 6) * newlines <1>: Boolean Ops. (line 67) @@ -30980,8 +31058,8 @@ Index * newlines, as field separators: Default Field Splitting. (line 6) * newlines, as record separators: Records. (line 20) -* newlines, in dynamic regexps: Computed Regexps. (line 59) -* newlines, in regexp constants: Computed Regexps. (line 69) +* newlines, in dynamic regexps: Computed Regexps. (line 58) +* newlines, in regexp constants: Computed Regexps. (line 68) * newlines, printing: Print Examples. (line 12) * newlines, separating statements in actions <1>: Statements. (line 10) * newlines, separating statements in actions: Action Overview. @@ -31012,7 +31090,7 @@ Index * not Boolean-logic operator: Boolean Ops. (line 6) * NR variable <1>: Auto-set. (line 125) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 295) +* NR variable, changing: Auto-set. (line 311) * null strings <1>: Basic Data Typing. (line 26) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -31022,7 +31100,7 @@ Index * null strings, as array subscripts: Uninitialized Subscripts. (line 43) * null strings, converting numbers to strings: Conversion. (line 21) -* null strings, matching: Gory Details. (line 165) +* null strings, matching: Gory Details. (line 164) * null strings, quoting and: Quoting. (line 62) * number sign (#), #! (executable scripts): Executable Scripts. (line 6) @@ -31057,7 +31135,7 @@ Index * OFS variable <1>: User-modified. (line 124) * OFS variable <2>: Output Separators. (line 6) * OFS variable: Changing Fields. (line 64) -* OpenBSD: Glossary. (line 619) +* OpenBSD: Glossary. (line 624) * OpenSolaris: Other Versions. (line 96) * operating systems, BSD-based: Manual History. (line 28) * operating systems, PC, gawk on: PC Using. (line 6) @@ -31081,7 +31159,7 @@ Index * operators, input/output: Getline/File. (line 6) * operators, logical, See Boolean expressions: Boolean Ops. (line 6) * operators, precedence <1>: Precedence. (line 6) -* operators, precedence: Increment Ops. (line 61) +* operators, precedence: Increment Ops. (line 60) * operators, relational, See operators, comparison: Typing and Comparison. (line 9) * operators, short-circuit: Boolean Ops. (line 57) @@ -31144,6 +31222,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) * 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) @@ -31169,16 +31248,16 @@ Index * plus sign (+), += operator: Assignment Ops. (line 82) * pointers to functions: Indirect Calls. (line 6) * portability: Escape Sequences. (line 94) -* portability, #! (executable scripts): Executable Scripts. (line 34) +* portability, #! (executable scripts): Executable Scripts. (line 33) * portability, ** operator and: Arithmetic Ops. (line 81) * portability, **= operator and: Assignment Ops. (line 142) -* portability, ARGV variable: Executable Scripts. (line 43) +* portability, ARGV variable: Executable Scripts. (line 42) * portability, backslash continuation and: Statements/Lines. (line 30) * portability, backslash in escape sequences: Escape Sequences. - (line 113) + (line 112) * portability, close() function and: Close Files And Pipes. (line 81) -* portability, data files as single record: Records. (line 180) +* portability, data files as single record: Records. (line 179) * portability, deleting array elements: Delete. (line 56) * portability, example programs: Library Functions. (line 42) * portability, fflush() function and: I/O Functions. (line 29) @@ -31191,7 +31270,7 @@ Index * portability, next statement in user-defined functions: Pass By Value/Reference. (line 91) * portability, NF variable, decrementing: Changing Fields. (line 115) -* portability, operators: Increment Ops. (line 61) +* 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 512) @@ -31215,7 +31294,7 @@ Index * POSIX awk, < operator and: Getline/File. (line 26) * POSIX awk, arithmetic operators and: Arithmetic Ops. (line 36) * POSIX awk, backslashes in string constants: Escape Sequences. - (line 113) + (line 112) * POSIX awk, BEGIN/END patterns: I/O And BEGIN/END. (line 16) * POSIX awk, bracket expressions and: Bracket Expressions. (line 24) * POSIX awk, bracket expressions and, character classes: Bracket Expressions. @@ -31226,7 +31305,7 @@ Index * POSIX awk, CONVFMT variable and: User-modified. (line 28) * POSIX awk, date utility and: Time Functions. (line 262) * POSIX awk, field separators and <1>: Field Splitting Summary. - (line 41) + (line 40) * POSIX awk, field separators and: Fields. (line 6) * POSIX awk, FS variable and: User-modified. (line 66) * POSIX awk, function keyword in: Definition Syntax. (line 83) @@ -31251,7 +31330,7 @@ Index * PREC variable <1>: Setting Precision. (line 6) * PREC variable: User-modified. (line 134) * precedence <1>: Precedence. (line 6) -* precedence: Increment Ops. (line 61) +* precedence: Increment Ops. (line 60) * precedence, regexp operators: Regexp Operators. (line 156) * print debugger command: Viewing And Changing Data. (line 36) @@ -31324,15 +31403,15 @@ Index * programming, concepts: Basic Concepts. (line 6) * pwcat program: Passwd Functions. (line 23) * q debugger command (alias for quit): Miscellaneous Debugger Commands. - (line 101) -* QSE Awk: Other Versions. (line 118) + (line 99) +* QSE Awk: Other Versions. (line 124) * 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 122) +* QuikTrim Awk: Other Versions. (line 128) * quit debugger command: Miscellaneous Debugger Commands. - (line 101) + (line 99) * QUIT signal (MS-Windows): Profiling. (line 206) * quoting <1>: Comments. (line 27) * quoting <2>: Long. (line 26) @@ -31342,6 +31421,7 @@ Index * r debugger command (alias for run): Debugger Execution Control. (line 62) * Rakitzis, Byron: History Sorting. (line 25) +* Ramey, Chet: Acknowledgments. (line 60) * rand() function: Numeric Functions. (line 34) * random numbers, Cliff: Cliff Random Function. (line 6) @@ -31368,7 +31448,7 @@ Index * records, printing: Print. (line 22) * records, splitting input into: Records. (line 6) * records, terminating: Records. (line 117) -* records, treating files as: Records. (line 201) +* records, treating files as: Records. (line 200) * recursive functions: Definition Syntax. (line 73) * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) @@ -31378,7 +31458,7 @@ Index (line 103) * regexp constants <2>: Regexp Constants. (line 6) * regexp constants: Regexp Usage. (line 57) -* regexp constants, /=.../, /= operator and: Assignment Ops. (line 148) +* regexp constants, /=.../, /= operator and: Assignment Ops. (line 147) * regexp constants, as patterns: Expression Patterns. (line 36) * regexp constants, in gawk: Using Constant Regexps. (line 28) @@ -31400,7 +31480,7 @@ Index (line 57) * regular expressions, dynamic: Computed Regexps. (line 6) * regular expressions, dynamic, with embedded newlines: Computed Regexps. - (line 59) + (line 58) * regular expressions, gawk, command-line options: GNU Regexp Operators. (line 70) * regular expressions, interval expressions and: Options. (line 272) @@ -31423,7 +31503,7 @@ Index (line 54) * return statement, user-defined functions: Return Statement. (line 6) * return values, close() function: Close Files And Pipes. - (line 131) + (line 130) * rev() user-defined function: Function Example. (line 52) * rewind() user-defined function: Rewind Function. (line 16) * right angle bracket (>), > operator <1>: Precedence. (line 65) @@ -31437,22 +31517,22 @@ 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 233) +* RLENGTH variable: Auto-set. (line 250) * RLENGTH variable, match() function and: String Functions. (line 223) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) -* Robbins, Arnold <3>: Contributors. (line 108) +* Robbins, Arnold <3>: Contributors. (line 122) * Robbins, Arnold <4>: Alarm Program. (line 6) * Robbins, Arnold <5>: Passwd Functions. (line 90) * Robbins, Arnold <6>: Getline/Pipe. (line 40) * Robbins, Arnold: Command Line Field Separator. (line 80) * Robbins, Bill: Getline/Pipe. (line 40) -* Robbins, Harry: Acknowledgments. (line 83) -* Robbins, Jean: Acknowledgments. (line 83) +* 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: Acknowledgments. (line 83) +* Robbins, Miriam: Acknowledgments. (line 78) * Rommel, Kai Uwe: Contributors. (line 43) * round() user-defined function: Round Function. (line 16) * rounding mode, floating-point: Rounding Mode. (line 6) @@ -31464,9 +31544,9 @@ 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 239) +* RSTART variable: Auto-set. (line 256) * RSTART variable, match() function and: String Functions. (line 223) -* RT variable <1>: Auto-set. (line 246) +* RT variable <1>: Auto-set. (line 263) * RT variable <2>: Getline/Variable/File. (line 10) * RT variable <3>: Multiple Line. (line 129) @@ -31481,6 +31561,7 @@ Index (line 68) * sandbox mode: Options. (line 279) * scalar values: Basic Data Typing. (line 13) +* Schorr, Andrew <1>: Contributors. (line 118) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) @@ -31500,7 +31581,7 @@ Index * sed utility <1>: Glossary. (line 12) * sed utility <2>: Simple Sed. (line 6) * sed utility: Field Splitting Summary. - (line 47) + (line 46) * semicolon (;): Statements/Lines. (line 91) * semicolon (;), AWKPATH variable and: PC Using. (line 11) * semicolon (;), separating statements in actions <1>: Statements. @@ -31518,7 +31599,7 @@ Index * separators, subscript: User-modified. (line 156) * set debugger command: Viewing And Changing Data. (line 59) -* shells, piping commands into: Redirection. (line 143) +* shells, piping commands into: Redirection. (line 142) * shells, quoting: Using Shell Variables. (line 12) * shells, quoting, rules for: Quoting. (line 18) @@ -31542,6 +31623,36 @@ Index * side effects, FILENAME variable: Getline Notes. (line 19) * side effects, function calls: Function Calls. (line 54) * side effects, statements: Action Overview. (line 32) +* sidebar, A Constant's Base Does Not Affect Its Value: Nondecimal-numbers. + (line 64) +* sidebar, Backslash Before Regular Characters: Escape Sequences. + (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, Controlling Output Buffering with system(): I/O Functions. + (line 135) +* sidebar, Escape Sequences for Metacharacters: Escape Sequences. + (line 128) +* sidebar, FS and IGNORECASE: Field Splitting Summary. + (line 64) +* sidebar, Interactive Versus Noninteractive Buffering: I/O Functions. + (line 104) +* sidebar, Matching the Null String: Gory Details. (line 162) +* sidebar, Operator Evaluation Order: Increment Ops. (line 58) +* sidebar, Piping into sh: Redirection. (line 140) +* sidebar, Portability Issues with #!: Executable Scripts. (line 31) +* sidebar, Recipe For A Programming Language: History. (line 6) +* sidebar, RS = "\0" Is Not Portable: Records. (line 177) +* sidebar, So Why Does gawk have BEGINFILE and ENDFILE?: Filetrans Function. + (line 83) +* sidebar, Syntactic Ambiguities Between /= and Regular Expressions: Assignment Ops. + (line 145) +* sidebar, Understanding $0: Changing Fields. (line 134) +* sidebar, Using \n in Bracket Expressions of Dynamic Regexps: Computed Regexps. + (line 56) +* sidebar, Using close()'s Return Value: Close Files And Pipes. + (line 128) * SIGHUP signal: Profiling. (line 203) * SIGINT signal (MS-Windows): Profiling. (line 206) * signals, HUP/SIGHUP: Profiling. (line 203) @@ -31565,7 +31676,7 @@ Index * sleep: Extension Sample Time. (line 6) * sleep time extension function: Extension Sample Time. - (line 20) + (line 23) * sleep utility: Alarm Program. (line 109) * Solaris, POSIX-compliant awk: Other Versions. (line 96) * sort function, arrays, sorting: Array Sorting Functions. @@ -31583,8 +31694,8 @@ Index * 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 118) -* source code, QuikTrim Awk: Other Versions. (line 122) +* source code, QSE Awk: Other Versions. (line 124) +* source code, QuikTrim Awk: Other Versions. (line 128) * source code, Solaris awk: Other Versions. (line 96) * source files, search path for: Igawk Program. (line 368) * sparse arrays: Array Intro. (line 71) @@ -31618,7 +31729,7 @@ Index (line 76) * stream editors <1>: Simple Sed. (line 6) * stream editors: Field Splitting Summary. - (line 47) + (line 46) * strftime() function (gawk): Time Functions. (line 48) * string constants: Scalar Constants. (line 15) * string constants, vs. regexp constants: Computed Regexps. (line 38) @@ -31660,9 +31771,9 @@ Index * substr() function: String Functions. (line 481) * Sumner, Andrew: Other Versions. (line 64) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 254) +* SYMTAB array: Auto-set. (line 271) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. - (line 148) + (line 147) * system() function: I/O Functions. (line 72) * systime() function (gawk): Time Functions. (line 65) * t debugger command (alias for tbreak): Breakpoint Control. (line 90) @@ -31716,14 +31827,14 @@ Index * toupper() function: String Functions. (line 529) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. - (line 110) + (line 108) * translate.awk program: Translate Program. (line 55) * troubleshooting, --non-decimal-data option: Options. (line 207) * troubleshooting, == operator: Comparison Operators. (line 37) * troubleshooting, awk uses FS not IFS: Field Separators. (line 29) * troubleshooting, backslash before nonspecial character: Escape Sequences. - (line 113) + (line 112) * troubleshooting, division: Arithmetic Ops. (line 44) * troubleshooting, fatal errors, field widths, specifying: Constant Size. (line 22) @@ -31774,11 +31885,11 @@ Index (line 6) * uniq utility: Uniq Program. (line 6) * uniq.awk program: Uniq Program. (line 65) -* Unix: Glossary. (line 619) +* Unix: Glossary. (line 624) * Unix awk, backslashes in escape sequences: Escape Sequences. - (line 125) + (line 124) * Unix awk, close() function and: Close Files And Pipes. - (line 131) + (line 130) * Unix awk, password files, field separators and: Command Line Field Separator. (line 72) * Unix, awk scripts and: Executable Scripts. (line 6) @@ -31875,7 +31986,7 @@ 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 106) +* Yawitz, Efraim: Contributors. (line 116) * Zaretskii, Eli <1>: Bugs. (line 70) * Zaretskii, Eli <2>: Contributors. (line 56) * Zaretskii, Eli: Acknowledgments. (line 60) @@ -31910,518 +32021,520 @@ Index Tag Table: Node: Top1358 -Node: Foreword40301 -Node: Preface44646 -Ref: Preface-Footnote-147699 -Ref: Preface-Footnote-247805 -Node: History48037 -Node: Names50428 -Ref: Names-Footnote-151905 -Node: This Manual51977 -Ref: This Manual-Footnote-157883 -Node: Conventions57983 -Node: Manual History60117 -Ref: Manual History-Footnote-163387 -Ref: Manual History-Footnote-263428 -Node: How To Contribute63502 -Node: Acknowledgments64646 -Node: Getting Started69142 -Node: Running gawk71521 -Node: One-shot72707 -Node: Read Terminal73932 -Ref: Read Terminal-Footnote-175582 -Ref: Read Terminal-Footnote-275858 -Node: Long76029 -Node: Executable Scripts77405 -Ref: Executable Scripts-Footnote-179274 -Ref: Executable Scripts-Footnote-279376 -Node: Comments79923 -Node: Quoting82390 -Node: DOS Quoting87013 -Node: Sample Data Files87688 -Node: Very Simple90720 -Node: Two Rules95319 -Node: More Complex97466 -Ref: More Complex-Footnote-1100396 -Node: Statements/Lines100481 -Ref: Statements/Lines-Footnote-1104943 -Node: Other Features105208 -Node: When106136 -Node: Invoking Gawk108283 -Node: Command Line109744 -Node: Options110527 -Ref: Options-Footnote-1125925 -Node: Other Arguments125950 -Node: Naming Standard Input128608 -Node: Environment Variables129702 -Node: AWKPATH Variable130260 -Ref: AWKPATH Variable-Footnote-1133018 -Node: AWKLIBPATH Variable133278 -Node: Other Environment Variables133875 -Node: Exit Status136370 -Node: Include Files137045 -Node: Loading Shared Libraries140614 -Node: Obsolete141839 -Node: Undocumented142536 -Node: Regexp142779 -Node: Regexp Usage144168 -Node: Escape Sequences146194 -Node: Regexp Operators151957 -Ref: Regexp Operators-Footnote-1159337 -Ref: Regexp Operators-Footnote-2159484 -Node: Bracket Expressions159582 -Ref: table-char-classes161472 -Node: GNU Regexp Operators163995 -Node: Case-sensitivity167718 -Ref: Case-sensitivity-Footnote-1170686 -Ref: Case-sensitivity-Footnote-2170921 -Node: Leftmost Longest171029 -Node: Computed Regexps172230 -Node: Reading Files175640 -Node: Records177643 -Ref: Records-Footnote-1186567 -Node: Fields186604 -Ref: Fields-Footnote-1189637 -Node: Nonconstant Fields189723 -Node: Changing Fields191925 -Node: Field Separators197906 -Node: Default Field Splitting200535 -Node: Regexp Field Splitting201652 -Node: Single Character Fields204994 -Node: Command Line Field Separator206053 -Node: Field Splitting Summary209494 -Ref: Field Splitting Summary-Footnote-1212686 -Node: Constant Size212787 -Node: Splitting By Content217371 -Ref: Splitting By Content-Footnote-1221097 -Node: Multiple Line221137 -Ref: Multiple Line-Footnote-1226984 -Node: Getline227163 -Node: Plain Getline229379 -Node: Getline/Variable231468 -Node: Getline/File232609 -Node: Getline/Variable/File233931 -Ref: Getline/Variable/File-Footnote-1235530 -Node: Getline/Pipe235617 -Node: Getline/Variable/Pipe238303 -Node: Getline/Coprocess239410 -Node: Getline/Variable/Coprocess240653 -Node: Getline Notes241367 -Node: Getline Summary244154 -Ref: table-getline-variants244562 -Node: Read Timeout245420 -Ref: Read Timeout-Footnote-1249165 -Node: Command line directories249222 -Node: Printing249852 -Node: Print251483 -Node: Print Examples252820 -Node: Output Separators255604 -Node: OFMT257364 -Node: Printf258722 -Node: Basic Printf259628 -Node: Control Letters261167 -Node: Format Modifiers264979 -Node: Printf Examples270988 -Node: Redirection273703 -Node: Special Files280687 -Node: Special FD281220 -Ref: Special FD-Footnote-1284845 -Node: Special Network284919 -Node: Special Caveats285769 -Node: Close Files And Pipes286565 -Ref: Close Files And Pipes-Footnote-1293588 -Ref: Close Files And Pipes-Footnote-2293736 -Node: Expressions293886 -Node: Values295018 -Node: Constants295694 -Node: Scalar Constants296374 -Ref: Scalar Constants-Footnote-1297233 -Node: Nondecimal-numbers297415 -Node: Regexp Constants300474 -Node: Using Constant Regexps300949 -Node: Variables304004 -Node: Using Variables304659 -Node: Assignment Options306383 -Node: Conversion308255 -Ref: table-locale-affects313746 -Ref: Conversion-Footnote-1314370 -Node: All Operators314479 -Node: Arithmetic Ops315109 -Node: Concatenation317614 -Ref: Concatenation-Footnote-1320407 -Node: Assignment Ops320527 -Ref: table-assign-ops325515 -Node: Increment Ops326923 -Node: Truth Values and Conditions330393 -Node: Truth Values331476 -Node: Typing and Comparison332525 -Node: Variable Typing333314 -Ref: Variable Typing-Footnote-1337211 -Node: Comparison Operators337333 -Ref: table-relational-ops337743 -Node: POSIX String Comparison341292 -Ref: POSIX String Comparison-Footnote-1342248 -Node: Boolean Ops342386 -Ref: Boolean Ops-Footnote-1346464 -Node: Conditional Exp346555 -Node: Function Calls348287 -Node: Precedence351881 -Node: Locales355550 -Node: Patterns and Actions356639 -Node: Pattern Overview357693 -Node: Regexp Patterns359362 -Node: Expression Patterns359905 -Node: Ranges363590 -Node: BEGIN/END366556 -Node: Using BEGIN/END367318 -Ref: Using BEGIN/END-Footnote-1370049 -Node: I/O And BEGIN/END370155 -Node: BEGINFILE/ENDFILE372437 -Node: Empty375341 -Node: Using Shell Variables375657 -Node: Action Overview377942 -Node: Statements380299 -Node: If Statement382153 -Node: While Statement383652 -Node: Do Statement385696 -Node: For Statement386852 -Node: Switch Statement390004 -Node: Break Statement392101 -Node: Continue Statement394091 -Node: Next Statement395884 -Node: Nextfile Statement398274 -Node: Exit Statement400915 -Node: Built-in Variables403331 -Node: User-modified404426 -Ref: User-modified-Footnote-1412781 -Node: Auto-set412843 -Ref: Auto-set-Footnote-1425194 -Ref: Auto-set-Footnote-2425399 -Node: ARGC and ARGV425455 -Node: Arrays429306 -Node: Array Basics430811 -Node: Array Intro431637 -Node: Reference to Elements435955 -Node: Assigning Elements438225 -Node: Array Example438716 -Node: Scanning an Array440448 -Node: Controlling Scanning442762 -Ref: Controlling Scanning-Footnote-1447695 -Node: Delete448011 -Ref: Delete-Footnote-1450776 -Node: Numeric Array Subscripts450833 -Node: Uninitialized Subscripts453016 -Node: Multi-dimensional454644 -Node: Multi-scanning457738 -Node: Arrays of Arrays459329 -Node: Functions463974 -Node: Built-in464793 -Node: Calling Built-in465871 -Node: Numeric Functions467859 -Ref: Numeric Functions-Footnote-1471691 -Ref: Numeric Functions-Footnote-2472048 -Ref: Numeric Functions-Footnote-3472096 -Node: String Functions472365 -Ref: String Functions-Footnote-1495862 -Ref: String Functions-Footnote-2495991 -Ref: String Functions-Footnote-3496239 -Node: Gory Details496326 -Ref: table-sub-escapes498005 -Ref: table-sub-posix-92499359 -Ref: table-sub-proposed500710 -Ref: table-posix-sub502064 -Ref: table-gensub-escapes503609 -Ref: Gory Details-Footnote-1504816 -Ref: Gory Details-Footnote-2504867 -Node: I/O Functions505018 -Ref: I/O Functions-Footnote-1512123 -Node: Time Functions512270 -Ref: Time Functions-Footnote-1523203 -Ref: Time Functions-Footnote-2523271 -Ref: Time Functions-Footnote-3523429 -Ref: Time Functions-Footnote-4523540 -Ref: Time Functions-Footnote-5523652 -Ref: Time Functions-Footnote-6523879 -Node: Bitwise Functions524145 -Ref: table-bitwise-ops524703 -Ref: Bitwise Functions-Footnote-1528924 -Node: Type Functions529108 -Node: I18N Functions529578 -Node: User-defined531205 -Node: Definition Syntax532009 -Ref: Definition Syntax-Footnote-1536919 -Node: Function Example536988 -Node: Function Caveats539582 -Node: Calling A Function540003 -Node: Variable Scope541118 -Node: Pass By Value/Reference544081 -Node: Return Statement547521 -Node: Dynamic Typing550502 -Node: Indirect Calls551433 -Node: Library Functions561118 -Ref: Library Functions-Footnote-1564631 -Ref: Library Functions-Footnote-2564774 -Node: Library Names564945 -Ref: Library Names-Footnote-1568416 -Ref: Library Names-Footnote-2568636 -Node: General Functions568722 -Node: Strtonum Function569675 -Node: Assert Function572605 -Node: Round Function575931 -Node: Cliff Random Function577474 -Node: Ordinal Functions578490 -Ref: Ordinal Functions-Footnote-1581560 -Ref: Ordinal Functions-Footnote-2581812 -Node: Join Function582021 -Ref: Join Function-Footnote-1583792 -Node: Getlocaltime Function583992 -Node: Data File Management587707 -Node: Filetrans Function588339 -Node: Rewind Function592478 -Node: File Checking593865 -Node: Empty Files594959 -Node: Ignoring Assigns597189 -Node: Getopt Function598742 -Ref: Getopt Function-Footnote-1610046 -Node: Passwd Functions610249 -Ref: Passwd Functions-Footnote-1619224 -Node: Group Functions619312 -Node: Walking Arrays627396 -Node: Sample Programs628965 -Node: Running Examples629642 -Node: Clones630370 -Node: Cut Program631594 -Node: Egrep Program641439 -Ref: Egrep Program-Footnote-1649212 -Node: Id Program649322 -Node: Split Program652938 -Ref: Split Program-Footnote-1656457 -Node: Tee Program656585 -Node: Uniq Program659388 -Node: Wc Program666817 -Ref: Wc Program-Footnote-1671083 -Ref: Wc Program-Footnote-2671283 -Node: Miscellaneous Programs671375 -Node: Dupword Program672563 -Node: Alarm Program674594 -Node: Translate Program679343 -Ref: Translate Program-Footnote-1683730 -Ref: Translate Program-Footnote-2683958 -Node: Labels Program684092 -Ref: Labels Program-Footnote-1687463 -Node: Word Sorting687547 -Node: History Sorting691431 -Node: Extract Program693270 -Ref: Extract Program-Footnote-1700753 -Node: Simple Sed700881 -Node: Igawk Program703943 -Ref: Igawk Program-Footnote-1719100 -Ref: Igawk Program-Footnote-2719301 -Node: Anagram Program719439 -Node: Signature Program722507 -Node: Internationalization723607 -Node: I18N and L10N725039 -Node: Explaining gettext725725 -Ref: Explaining gettext-Footnote-1730791 -Ref: Explaining gettext-Footnote-2730975 -Node: Programmer i18n731140 -Node: Translator i18n735340 -Node: String Extraction736133 -Ref: String Extraction-Footnote-1737094 -Node: Printf Ordering737180 -Ref: Printf Ordering-Footnote-1739964 -Node: I18N Portability740028 -Ref: I18N Portability-Footnote-1742477 -Node: I18N Example742540 -Ref: I18N Example-Footnote-1745175 -Node: Gawk I18N745247 -Node: Advanced Features745864 -Node: Nondecimal Data747368 -Node: Array Sorting748951 -Node: Controlling Array Traversal749648 -Node: Array Sorting Functions757886 -Ref: Array Sorting Functions-Footnote-1761560 -Ref: Array Sorting Functions-Footnote-2761653 -Node: Two-way I/O761847 -Ref: Two-way I/O-Footnote-1767279 -Node: TCP/IP Networking767349 -Node: Profiling770193 -Node: Debugger777647 -Node: Debugging778615 -Node: Debugging Concepts779048 -Node: Debugging Terms780904 -Node: Awk Debugging783501 -Node: Sample Debugging Session784393 -Node: Debugger Invocation784913 -Node: Finding The Bug786242 -Node: List of Debugger Commands792730 -Node: Breakpoint Control794064 -Node: Debugger Execution Control797728 -Node: Viewing And Changing Data801088 -Node: Execution Stack804444 -Node: Debugger Info805911 -Node: Miscellaneous Debugger Commands809892 -Node: Readline Support815337 -Node: Limitations816168 -Node: Arbitrary Precision Arithmetic818420 -Ref: Arbitrary Precision Arithmetic-Footnote-1820062 -Node: General Arithmetic820210 -Node: Floating Point Issues821930 -Node: String Conversion Precision822811 -Ref: String Conversion Precision-Footnote-1824517 -Node: Unexpected Results824626 -Node: POSIX Floating Point Problems826779 -Ref: POSIX Floating Point Problems-Footnote-1830604 -Node: Integer Programming830642 -Node: Floating-point Programming832395 -Ref: Floating-point Programming-Footnote-1838704 -Node: Floating-point Representation838968 -Node: Floating-point Context840133 -Ref: table-ieee-formats840975 -Node: Rounding Mode842359 -Ref: table-rounding-modes842838 -Ref: Rounding Mode-Footnote-1845842 -Node: Gawk and MPFR846023 -Node: Arbitrary Precision Floats847265 -Ref: Arbitrary Precision Floats-Footnote-1849694 -Node: Setting Precision850005 -Node: Setting Rounding Mode852738 -Ref: table-gawk-rounding-modes853142 -Node: Floating-point Constants854322 -Node: Changing Precision855746 -Ref: Changing Precision-Footnote-1857146 -Node: Exact Arithmetic857320 -Node: Arbitrary Precision Integers860428 -Ref: Arbitrary Precision Integers-Footnote-1863428 -Node: Dynamic Extensions863575 -Node: Extension Intro864952 -Node: Plugin License866160 -Node: Extension Mechanism Outline866845 -Ref: load-extension867262 -Ref: load-new-function868740 -Ref: call-new-function869735 -Node: Extension API Description871743 -Node: Extension API Functions Introduction873082 -Node: General Data Types877860 -Ref: General Data Types-Footnote-1883462 -Node: Requesting Values883761 -Ref: table-value-types-returned884492 -Node: Constructor Functions885446 -Node: Registration Functions888442 -Node: Extension Functions889127 -Node: Exit Callback Functions891301 -Node: Extension Version String892544 -Node: Input Parsers893194 -Node: Output Wrappers902911 -Node: Two-way processors907327 -Node: Printing Messages909457 -Ref: Printing Messages-Footnote-1910534 -Node: Updating `ERRNO'910686 -Node: Accessing Parameters911425 -Node: Symbol Table Access912655 -Node: Symbol table by name913167 -Node: Symbol table by cookie914740 -Ref: Symbol table by cookie-Footnote-1918869 -Node: Cached values918932 -Ref: Cached values-Footnote-1922375 -Node: Array Manipulation922466 -Ref: Array Manipulation-Footnote-1923564 -Node: Array Data Types923603 -Ref: Array Data Types-Footnote-1926306 -Node: Array Functions926398 -Node: Flattening Arrays930164 -Node: Creating Arrays937003 -Node: Extension API Variables941798 -Node: Extension Versioning942434 -Node: Extension API Informational Variables944335 -Node: Extension API Boilerplate945421 -Node: Finding Extensions949252 -Node: Extension Example949799 -Node: Internal File Description950537 -Node: Internal File Ops954225 -Ref: Internal File Ops-Footnote-1965672 -Node: Using Internal File Ops965812 -Ref: Using Internal File Ops-Footnote-1968165 -Node: Extension Samples968431 -Node: Extension Sample File Functions969955 -Node: Extension Sample Fnmatch978428 -Node: Extension Sample Fork980154 -Node: Extension Sample Inplace981372 -Node: Extension Sample Ord983164 -Node: Extension Sample Readdir983943 -Node: Extension Sample Revout985447 -Node: Extension Sample Rev2way986040 -Node: Extension Sample Read write array986730 -Node: Extension Sample Readfile988613 -Node: Extension Sample API Tests989370 -Node: Extension Sample Time989895 -Node: gawkextlib991202 -Node: Language History993583 -Node: V7/SVR3.1995105 -Node: SVR4997426 -Node: POSIX998868 -Node: BTL999876 -Node: POSIX/GNU1000681 -Node: Common Extensions1006216 -Node: Ranges and Locales1007323 -Ref: Ranges and Locales-Footnote-11011941 -Ref: Ranges and Locales-Footnote-21011968 -Ref: Ranges and Locales-Footnote-31012228 -Node: Contributors1012449 -Node: Installation1016745 -Node: Gawk Distribution1017639 -Node: Getting1018123 -Node: Extracting1018949 -Node: Distribution contents1020641 -Node: Unix Installation1025902 -Node: Quick Installation1026519 -Node: Additional Configuration Options1028481 -Node: Configuration Philosophy1029958 -Node: Non-Unix Installation1032300 -Node: PC Installation1032758 -Node: PC Binary Installation1034057 -Node: PC Compiling1035905 -Node: PC Testing1038849 -Node: PC Using1040025 -Node: Cygwin1044210 -Node: MSYS1045210 -Node: VMS Installation1045724 -Node: VMS Compilation1046327 -Ref: VMS Compilation-Footnote-11047334 -Node: VMS Installation Details1047392 -Node: VMS Running1049027 -Node: VMS Old Gawk1050634 -Node: Bugs1051108 -Node: Other Versions1054960 -Node: Notes1060290 -Node: Compatibility Mode1061090 -Node: Additions1061873 -Node: Accessing The Source1062800 -Node: Adding Code1064403 -Node: New Ports1070445 -Node: Derived Files1074580 -Ref: Derived Files-Footnote-11079901 -Ref: Derived Files-Footnote-21079935 -Ref: Derived Files-Footnote-31080535 -Node: Future Extensions1080633 -Node: Implementation Limitations1081214 -Node: Extension Design1082466 -Node: Old Extension Problems1083615 -Ref: Old Extension Problems-Footnote-11085123 -Node: Extension New Mechanism Goals1085180 -Ref: Extension New Mechanism Goals-Footnote-11088539 -Node: Extension Other Design Decisions1088725 -Node: Extension Future Growth1090831 -Node: Old Extension Mechansim1091652 -Node: Basic Concepts1093409 -Node: Basic High Level1094090 -Ref: figure-general-flow1094361 -Ref: figure-process-flow1094960 -Ref: Basic High Level-Footnote-11098189 -Node: Basic Data Typing1098374 -Node: Glossary1101729 -Node: Copying1127040 -Node: GNU Free Documentation License1164597 -Node: Index1189734 +Node: Foreword40334 +Node: Preface44679 +Ref: Preface-Footnote-147732 +Ref: Preface-Footnote-247828 +Node: History48060 +Node: Names50434 +Ref: Names-Footnote-151911 +Node: This Manual51983 +Ref: This Manual-Footnote-157848 +Node: Conventions57948 +Node: Manual History60100 +Ref: Manual History-Footnote-163501 +Ref: Manual History-Footnote-263542 +Node: How To Contribute63616 +Node: Acknowledgments64760 +Node: Getting Started68971 +Node: Running gawk71350 +Node: One-shot72536 +Node: Read Terminal73761 +Ref: Read Terminal-Footnote-175411 +Ref: Read Terminal-Footnote-275687 +Node: Long75858 +Node: Executable Scripts77234 +Ref: Executable Scripts-Footnote-179067 +Ref: Executable Scripts-Footnote-279169 +Node: Comments79716 +Node: Quoting82183 +Node: DOS Quoting86806 +Node: Sample Data Files87481 +Node: Very Simple90513 +Node: Two Rules95112 +Node: More Complex97259 +Ref: More Complex-Footnote-1100189 +Node: Statements/Lines100274 +Ref: Statements/Lines-Footnote-1104736 +Node: Other Features105001 +Node: When105929 +Node: Invoking Gawk108076 +Node: Command Line109537 +Node: Options110320 +Ref: Options-Footnote-1125712 +Node: Other Arguments125737 +Node: Naming Standard Input128395 +Node: Environment Variables129489 +Node: AWKPATH Variable130047 +Ref: AWKPATH Variable-Footnote-1132805 +Node: AWKLIBPATH Variable133065 +Node: Other Environment Variables133783 +Node: Exit Status136278 +Node: Include Files136953 +Node: Loading Shared Libraries140522 +Node: Obsolete141886 +Node: Undocumented142583 +Node: Regexp142826 +Node: Regexp Usage144215 +Node: Escape Sequences146241 +Node: Regexp Operators151910 +Ref: Regexp Operators-Footnote-1159290 +Ref: Regexp Operators-Footnote-2159437 +Node: Bracket Expressions159535 +Ref: table-char-classes161425 +Node: GNU Regexp Operators163948 +Node: Case-sensitivity167671 +Ref: Case-sensitivity-Footnote-1170639 +Ref: Case-sensitivity-Footnote-2170874 +Node: Leftmost Longest170982 +Node: Computed Regexps172183 +Node: Reading Files175520 +Node: Records177523 +Ref: Records-Footnote-1186412 +Node: Fields186449 +Ref: Fields-Footnote-1189482 +Node: Nonconstant Fields189568 +Node: Changing Fields191770 +Node: Field Separators197729 +Node: Default Field Splitting200358 +Node: Regexp Field Splitting201475 +Node: Single Character Fields204817 +Node: Command Line Field Separator205876 +Node: Field Splitting Summary209317 +Ref: Field Splitting Summary-Footnote-1212428 +Node: Constant Size212529 +Node: Splitting By Content217113 +Ref: Splitting By Content-Footnote-1220839 +Node: Multiple Line220879 +Ref: Multiple Line-Footnote-1226726 +Node: Getline226905 +Node: Plain Getline229121 +Node: Getline/Variable231216 +Node: Getline/File232363 +Node: Getline/Variable/File233704 +Ref: Getline/Variable/File-Footnote-1235303 +Node: Getline/Pipe235390 +Node: Getline/Variable/Pipe238090 +Node: Getline/Coprocess239197 +Node: Getline/Variable/Coprocess240449 +Node: Getline Notes241186 +Node: Getline Summary243973 +Ref: table-getline-variants244381 +Node: Read Timeout245293 +Ref: Read Timeout-Footnote-1249034 +Node: Command line directories249091 +Node: Printing249721 +Node: Print251352 +Node: Print Examples252689 +Node: Output Separators255473 +Node: OFMT257233 +Node: Printf258591 +Node: Basic Printf259497 +Node: Control Letters261036 +Node: Format Modifiers264848 +Node: Printf Examples270857 +Node: Redirection273572 +Node: Special Files280537 +Node: Special FD281070 +Ref: Special FD-Footnote-1284695 +Node: Special Network284769 +Node: Special Caveats285619 +Node: Close Files And Pipes286415 +Ref: Close Files And Pipes-Footnote-1293398 +Ref: Close Files And Pipes-Footnote-2293546 +Node: Expressions293696 +Node: Values294828 +Node: Constants295504 +Node: Scalar Constants296184 +Ref: Scalar Constants-Footnote-1297043 +Node: Nondecimal-numbers297225 +Node: Regexp Constants300225 +Node: Using Constant Regexps300700 +Node: Variables303755 +Node: Using Variables304410 +Node: Assignment Options306134 +Node: Conversion308006 +Ref: table-locale-affects313497 +Ref: Conversion-Footnote-1314121 +Node: All Operators314230 +Node: Arithmetic Ops314860 +Node: Concatenation317365 +Ref: Concatenation-Footnote-1320158 +Node: Assignment Ops320278 +Ref: table-assign-ops325266 +Node: Increment Ops326597 +Node: Truth Values and Conditions330032 +Node: Truth Values331115 +Node: Typing and Comparison332164 +Node: Variable Typing332953 +Ref: Variable Typing-Footnote-1336850 +Node: Comparison Operators336972 +Ref: table-relational-ops337382 +Node: POSIX String Comparison340931 +Ref: POSIX String Comparison-Footnote-1341887 +Node: Boolean Ops342025 +Ref: Boolean Ops-Footnote-1346103 +Node: Conditional Exp346194 +Node: Function Calls347926 +Node: Precedence351520 +Node: Locales355189 +Node: Patterns and Actions356278 +Node: Pattern Overview357332 +Node: Regexp Patterns359001 +Node: Expression Patterns359544 +Node: Ranges363229 +Node: BEGIN/END366195 +Node: Using BEGIN/END366957 +Ref: Using BEGIN/END-Footnote-1369688 +Node: I/O And BEGIN/END369794 +Node: BEGINFILE/ENDFILE372076 +Node: Empty374980 +Node: Using Shell Variables375296 +Node: Action Overview377581 +Node: Statements379938 +Node: If Statement381792 +Node: While Statement383291 +Node: Do Statement385335 +Node: For Statement386491 +Node: Switch Statement389643 +Node: Break Statement391740 +Node: Continue Statement393730 +Node: Next Statement395523 +Node: Nextfile Statement397913 +Node: Exit Statement400556 +Node: Built-in Variables402972 +Node: User-modified404067 +Ref: User-modified-Footnote-1412427 +Node: Auto-set412489 +Ref: Auto-set-Footnote-1425420 +Ref: Auto-set-Footnote-2425625 +Node: ARGC and ARGV425681 +Node: Arrays429532 +Node: Array Basics431037 +Node: Array Intro431863 +Node: Reference to Elements436181 +Node: Assigning Elements438451 +Node: Array Example438942 +Node: Scanning an Array440674 +Node: Controlling Scanning442988 +Ref: Controlling Scanning-Footnote-1447911 +Node: Delete448227 +Ref: Delete-Footnote-1450992 +Node: Numeric Array Subscripts451049 +Node: Uninitialized Subscripts453232 +Node: Multi-dimensional454860 +Node: Multi-scanning457954 +Node: Arrays of Arrays459545 +Node: Functions464186 +Node: Built-in465005 +Node: Calling Built-in466083 +Node: Numeric Functions468071 +Ref: Numeric Functions-Footnote-1471903 +Ref: Numeric Functions-Footnote-2472260 +Ref: Numeric Functions-Footnote-3472308 +Node: String Functions472577 +Ref: String Functions-Footnote-1496074 +Ref: String Functions-Footnote-2496203 +Ref: String Functions-Footnote-3496451 +Node: Gory Details496538 +Ref: table-sub-escapes498217 +Ref: table-sub-posix-92499571 +Ref: table-sub-proposed500922 +Ref: table-posix-sub502276 +Ref: table-gensub-escapes503821 +Ref: Gory Details-Footnote-1504997 +Ref: Gory Details-Footnote-2505048 +Node: I/O Functions505199 +Ref: I/O Functions-Footnote-1512184 +Node: Time Functions512331 +Ref: Time Functions-Footnote-1523264 +Ref: Time Functions-Footnote-2523332 +Ref: Time Functions-Footnote-3523490 +Ref: Time Functions-Footnote-4523601 +Ref: Time Functions-Footnote-5523713 +Ref: Time Functions-Footnote-6523940 +Node: Bitwise Functions524206 +Ref: table-bitwise-ops524764 +Ref: Bitwise Functions-Footnote-1528985 +Node: Type Functions529169 +Node: I18N Functions529639 +Node: User-defined531266 +Node: Definition Syntax532070 +Ref: Definition Syntax-Footnote-1536980 +Node: Function Example537049 +Node: Function Caveats539643 +Node: Calling A Function540064 +Node: Variable Scope541179 +Node: Pass By Value/Reference544142 +Node: Return Statement547650 +Node: Dynamic Typing550631 +Node: Indirect Calls551562 +Node: Library Functions561247 +Ref: Library Functions-Footnote-1564760 +Ref: Library Functions-Footnote-2564903 +Node: Library Names565074 +Ref: Library Names-Footnote-1568545 +Ref: Library Names-Footnote-2568765 +Node: General Functions568851 +Node: Strtonum Function569804 +Node: Assert Function572734 +Node: Round Function576060 +Node: Cliff Random Function577603 +Node: Ordinal Functions578619 +Ref: Ordinal Functions-Footnote-1581689 +Ref: Ordinal Functions-Footnote-2581941 +Node: Join Function582150 +Ref: Join Function-Footnote-1583921 +Node: Getlocaltime Function584121 +Node: Data File Management587836 +Node: Filetrans Function588468 +Node: Rewind Function592537 +Node: File Checking593924 +Node: Empty Files595018 +Node: Ignoring Assigns597248 +Node: Getopt Function598801 +Ref: Getopt Function-Footnote-1610105 +Node: Passwd Functions610308 +Ref: Passwd Functions-Footnote-1619283 +Node: Group Functions619371 +Node: Walking Arrays627455 +Node: Sample Programs629592 +Node: Running Examples630266 +Node: Clones630994 +Node: Cut Program632218 +Node: Egrep Program642063 +Ref: Egrep Program-Footnote-1649836 +Node: Id Program649946 +Node: Split Program653562 +Ref: Split Program-Footnote-1657081 +Node: Tee Program657209 +Node: Uniq Program660012 +Node: Wc Program667441 +Ref: Wc Program-Footnote-1671707 +Ref: Wc Program-Footnote-2671907 +Node: Miscellaneous Programs671999 +Node: Dupword Program673187 +Node: Alarm Program675218 +Node: Translate Program679967 +Ref: Translate Program-Footnote-1684354 +Ref: Translate Program-Footnote-2684582 +Node: Labels Program684716 +Ref: Labels Program-Footnote-1688087 +Node: Word Sorting688171 +Node: History Sorting692055 +Node: Extract Program693894 +Ref: Extract Program-Footnote-1701395 +Node: Simple Sed701523 +Node: Igawk Program704585 +Ref: Igawk Program-Footnote-1719742 +Ref: Igawk Program-Footnote-2719943 +Node: Anagram Program720081 +Node: Signature Program723149 +Node: Advanced Features724249 +Node: Nondecimal Data726131 +Node: Array Sorting727714 +Node: Controlling Array Traversal728411 +Node: Array Sorting Functions736649 +Ref: Array Sorting Functions-Footnote-1740323 +Ref: Array Sorting Functions-Footnote-2740416 +Node: Two-way I/O740610 +Ref: Two-way I/O-Footnote-1746042 +Node: TCP/IP Networking746112 +Node: Profiling748956 +Node: Internationalization756411 +Node: I18N and L10N757836 +Node: Explaining gettext758522 +Ref: Explaining gettext-Footnote-1763588 +Ref: Explaining gettext-Footnote-2763772 +Node: Programmer i18n763937 +Node: Translator i18n768137 +Node: String Extraction768930 +Ref: String Extraction-Footnote-1769891 +Node: Printf Ordering769977 +Ref: Printf Ordering-Footnote-1772761 +Node: I18N Portability772825 +Ref: I18N Portability-Footnote-1775274 +Node: I18N Example775337 +Ref: I18N Example-Footnote-1777972 +Node: Gawk I18N778044 +Node: Debugger778665 +Node: Debugging779636 +Node: Debugging Concepts780069 +Node: Debugging Terms781925 +Node: Awk Debugging784522 +Node: Sample Debugging Session785414 +Node: Debugger Invocation785934 +Node: Finding The Bug787266 +Node: List of Debugger Commands793754 +Node: Breakpoint Control795088 +Node: Debugger Execution Control798752 +Node: Viewing And Changing Data802112 +Node: Execution Stack805468 +Node: Debugger Info806935 +Node: Miscellaneous Debugger Commands810917 +Node: Readline Support816093 +Node: Limitations816924 +Node: Arbitrary Precision Arithmetic819176 +Ref: Arbitrary Precision Arithmetic-Footnote-1820827 +Node: General Arithmetic820975 +Node: Floating Point Issues822695 +Node: String Conversion Precision823576 +Ref: String Conversion Precision-Footnote-1825282 +Node: Unexpected Results825391 +Node: POSIX Floating Point Problems827544 +Ref: POSIX Floating Point Problems-Footnote-1831369 +Node: Integer Programming831407 +Node: Floating-point Programming833146 +Ref: Floating-point Programming-Footnote-1839477 +Ref: Floating-point Programming-Footnote-2839747 +Node: Floating-point Representation840011 +Node: Floating-point Context841176 +Ref: table-ieee-formats842015 +Node: Rounding Mode843399 +Ref: table-rounding-modes843878 +Ref: Rounding Mode-Footnote-1846893 +Node: Gawk and MPFR847072 +Node: Arbitrary Precision Floats848327 +Ref: Arbitrary Precision Floats-Footnote-1850770 +Node: Setting Precision851086 +Ref: table-predefined-precision-strings851772 +Node: Setting Rounding Mode853917 +Ref: table-gawk-rounding-modes854321 +Node: Floating-point Constants855508 +Node: Changing Precision856937 +Ref: Changing Precision-Footnote-1858337 +Node: Exact Arithmetic858511 +Node: Arbitrary Precision Integers861649 +Ref: Arbitrary Precision Integers-Footnote-1864667 +Node: Dynamic Extensions864814 +Node: Extension Intro866272 +Node: Plugin License867537 +Node: Extension Mechanism Outline868222 +Ref: load-extension868639 +Ref: load-new-function870117 +Ref: call-new-function871112 +Node: Extension API Description873127 +Node: Extension API Functions Introduction874340 +Node: General Data Types879206 +Ref: General Data Types-Footnote-1884808 +Node: Requesting Values885107 +Ref: table-value-types-returned885838 +Node: Constructor Functions886792 +Node: Registration Functions889812 +Node: Extension Functions890497 +Node: Exit Callback Functions892722 +Node: Extension Version String893971 +Node: Input Parsers894621 +Node: Output Wrappers904378 +Node: Two-way processors908888 +Node: Printing Messages911096 +Ref: Printing Messages-Footnote-1912173 +Node: Updating `ERRNO'912325 +Node: Accessing Parameters913064 +Node: Symbol Table Access914294 +Node: Symbol table by name914806 +Node: Symbol table by cookie916553 +Ref: Symbol table by cookie-Footnote-1920683 +Node: Cached values920746 +Ref: Cached values-Footnote-1924195 +Node: Array Manipulation924286 +Ref: Array Manipulation-Footnote-1925384 +Node: Array Data Types925423 +Ref: Array Data Types-Footnote-1928126 +Node: Array Functions928218 +Node: Flattening Arrays931984 +Node: Creating Arrays938836 +Node: Extension API Variables943561 +Node: Extension Versioning944197 +Node: Extension API Informational Variables946098 +Node: Extension API Boilerplate947184 +Node: Finding Extensions950988 +Node: Extension Example951548 +Node: Internal File Description952279 +Node: Internal File Ops955967 +Ref: Internal File Ops-Footnote-1967451 +Node: Using Internal File Ops967591 +Ref: Using Internal File Ops-Footnote-1969944 +Node: Extension Samples970210 +Node: Extension Sample File Functions971734 +Node: Extension Sample Fnmatch980221 +Node: Extension Sample Fork981947 +Node: Extension Sample Inplace983165 +Node: Extension Sample Ord984943 +Node: Extension Sample Readdir985779 +Node: Extension Sample Revout987311 +Node: Extension Sample Rev2way987904 +Node: Extension Sample Read write array988594 +Node: Extension Sample Readfile990477 +Node: Extension Sample API Tests991295 +Node: Extension Sample Time991820 +Node: gawkextlib993184 +Node: Language History995615 +Node: V7/SVR3.1997137 +Node: SVR4999458 +Node: POSIX1000900 +Node: BTL1002286 +Node: POSIX/GNU1003020 +Node: Common Extensions1008555 +Node: Ranges and Locales1009710 +Ref: Ranges and Locales-Footnote-11014328 +Ref: Ranges and Locales-Footnote-21014355 +Ref: Ranges and Locales-Footnote-31014615 +Node: Contributors1014836 +Node: Installation1019640 +Node: Gawk Distribution1020534 +Node: Getting1021018 +Node: Extracting1021844 +Node: Distribution contents1023536 +Node: Unix Installation1028797 +Node: Quick Installation1029414 +Node: Additional Configuration Options1031376 +Node: Configuration Philosophy1032853 +Node: Non-Unix Installation1035195 +Node: PC Installation1035653 +Node: PC Binary Installation1036952 +Node: PC Compiling1038800 +Node: PC Testing1041744 +Node: PC Using1042920 +Node: Cygwin1047105 +Node: MSYS1048105 +Node: VMS Installation1048619 +Node: VMS Compilation1049222 +Ref: VMS Compilation-Footnote-11050229 +Node: VMS Installation Details1050287 +Node: VMS Running1051922 +Node: VMS Old Gawk1053529 +Node: Bugs1054003 +Node: Other Versions1057855 +Node: Notes1063456 +Node: Compatibility Mode1064256 +Node: Additions1065039 +Node: Accessing The Source1065966 +Node: Adding Code1067406 +Node: New Ports1073451 +Node: Derived Files1077586 +Ref: Derived Files-Footnote-11082907 +Ref: Derived Files-Footnote-21082941 +Ref: Derived Files-Footnote-31083541 +Node: Future Extensions1083639 +Node: Implementation Limitations1084220 +Node: Extension Design1085472 +Node: Old Extension Problems1086626 +Ref: Old Extension Problems-Footnote-11088134 +Node: Extension New Mechanism Goals1088191 +Ref: Extension New Mechanism Goals-Footnote-11091557 +Node: Extension Other Design Decisions1091743 +Node: Extension Future Growth1093849 +Node: Old Extension Mechanism1094685 +Node: Basic Concepts1096425 +Node: Basic High Level1097106 +Ref: figure-general-flow1097377 +Ref: figure-process-flow1097976 +Ref: Basic High Level-Footnote-11101205 +Node: Basic Data Typing1101390 +Node: Glossary1104745 +Node: Copying1130216 +Node: GNU Free Documentation License1167773 +Node: Index1192910 End Tag Table |