diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 3764 |
1 files changed, 1871 insertions, 1893 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 3c290463..a5ef90b9 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -14,7 +14,7 @@ Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, This is Edition 3 of `GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 3.1.2 (or later) version of the GNU +Guide for GNU Awk', for the 3.1.3 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document @@ -32,7 +32,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) funds for GNU development." -File: gawk.info, Node: Top, Next: Foreword, Prev: (dir), Up: (dir) +File: gawk.info, Node: Top, Next: Foreword, Up: (dir) General Introduction ******************** @@ -45,7 +45,7 @@ Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, This is Edition 3 of `GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 3.1.2 (or later) version of the GNU +Guide for GNU Awk', for the 3.1.3 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document @@ -252,6 +252,8 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) some condition is satisfied. * For Statement:: Another looping statement, that provides initialization and increment clauses. +* Switch Statement:: Switch/case evaluation for conditional + execution of statements based on a value. * Break Statement:: Immediately exit the innermost enclosing loop. * Continue Statement:: Skip to the end of the innermost enclosing @@ -348,6 +350,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) transitions. * Rewind Function:: A function for rereading the current file. * File Checking:: Checking that data files are readable. +* Empty Files:: Checking for zero-length files. * Ignoring Assigns:: Treating assignments as file names. * Getopt Function:: A function for processing command-line arguments. @@ -401,10 +404,12 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * PC Installation:: Installing and Compiling `gawk' on MS-DOS and OS/2. * PC Binary Installation:: Installing a prepared distribution. -* PC Compiling:: Compiling `gawk' for MS-DOS, Win32, +* PC Compiling:: Compiling `gawk' for MS-DOS, Windows32, and OS/2. -* PC Using:: Running `gawk' on MS-DOS, Win32 and +* PC Using:: Running `gawk' on MS-DOS, Windows32 and OS/2. +* PC Dynamic:: Compiling `gawk' for dynamic + libraries. * Cygwin:: Building and running `gawk' for Cygwin. * VMS Installation:: Installing `gawk' on VMS. @@ -616,7 +621,7 @@ operating system, you still need to be familiar with the ideas of I/O redirection and pipes. -File: gawk.info, Node: History, Next: Names, Prev: Preface, Up: Preface +File: gawk.info, Node: History, Next: Names, Up: Preface History of `awk' and `gawk' =========================== @@ -659,8 +664,8 @@ Internetworking with `gawk'' (a separate document, available as part of the `gawk' distribution). His code finally became part of the main `gawk' distribution with `gawk' version 3.1. - *Note Major Contributors to `gawk': Contributors, for a complete -list of those who made important contributions to `gawk'. + *Note Contributors::, for a complete list of those who made +important contributions to `gawk'. File: gawk.info, Node: Names, Next: This Manual, Prev: History, Up: Preface @@ -669,9 +674,8 @@ A Rose by Any Other Name ======================== The `awk' language has evolved over the years. Full details are -provided in *Note The Evolution of the `awk' Language: Language History. -The language described in this Info file is often referred to as "new -`awk'" (`nawk'). +provided in *Note Language History::. The language described in this +Info file is often referred to as "new `awk'" (`nawk'). Because of this, many systems have multiple versions of `awk'. Some systems have an `awk' utility that implements the original version of @@ -730,82 +734,76 @@ illustrates the concept currently being described is shown. While this Info file is aimed principally at people who have not been exposed to `awk', there is a lot of information here that even the `awk' expert should find useful. In particular, the description of POSIX -`awk' and the example programs in *Note A Library of `awk' Functions: -Library Functions, and in *Note Practical `awk' Programs: Sample -Programs, should be of interest. +`awk' and the example programs in *Note Library Functions::, and in +*Note Sample Programs::, should be of interest. - *Note Getting Started with `awk': Getting Started, provides the -essentials you need to know to begin using `awk'. + *Note Getting Started::, provides the essentials you need to know to +begin using `awk'. - *Note Regular Expressions: Regexp, introduces regular expressions in -general, and in particular the flavors supported by POSIX `awk' and -`gawk'. + *Note Regexp::, introduces regular expressions in general, and in +particular the flavors supported by POSIX `awk' and `gawk'. - *Note Reading Input Files: Reading Files, describes how `awk' reads -your data. It introduces the concepts of records and fields, as well -as the `getline' command. I/O redirection is first described here. + *Note Reading Files::, describes how `awk' reads your data. It +introduces the concepts of records and fields, as well as the `getline' +command. I/O redirection is first described here. - *Note Printing Output: Printing, describes how `awk' programs can -produce output with `print' and `printf'. + *Note Printing::, describes how `awk' programs can produce output +with `print' and `printf'. *Note Expressions::, describes expressions, which are the basic building blocks for getting most things done in a program. - *Note Patterns Actions and Variables: Patterns and Actions, -describes how to write patterns for matching records, actions for doing -something when a record is matched, and the built-in variables `awk' -and `gawk' use. + *Note Patterns and Actions::, describes how to write patterns for +matching records, actions for doing something when a record is matched, +and the built-in variables `awk' and `gawk' use. - *Note Arrays in `awk': Arrays, covers `awk''s one-and-only data -structure: associative arrays. Deleting array elements and whole -arrays is also described, as well as sorting arrays in `gawk'. + *Note Arrays::, covers `awk''s one-and-only data structure: +associative arrays. Deleting array elements and whole arrays is also +described, as well as sorting arrays in `gawk'. *Note Functions::, describes the built-in functions `awk' and `gawk' provide, as well as how to define your own functions. - *Note Internationalization with `gawk': Internationalization, -describes special features in `gawk' for translating program messages -into different languages at runtime. + *Note Internationalization::, describes special features in `gawk' +for translating program messages into different languages at runtime. - *Note Advanced Features of `gawk': 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 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 Running `awk' and `gawk': Invoking Gawk, describes how to run -`gawk', the meaning of its command-line options, and how it finds `awk' -program source files. + *Note Invoking Gawk::, describes how to run `gawk', the meaning of +its command-line options, and how it finds `awk' program source files. - *Note A Library of `awk' Functions: Library Functions, and *Note -Practical `awk' Programs: Sample Programs, provide many sample `awk' -programs. Reading them allows you to see `awk' solving real problems. + *Note Library Functions::, and *Note Sample Programs::, provide many +sample `awk' programs. Reading them allows you to see `awk' solving +real problems. - *Note The Evolution of the `awk' Language: Language History, -describes how the `awk' language has evolved since first release to -present. It also describes how `gawk' has acquired features over time. + *Note Language History::, describes how the `awk' language has +evolved since first release to present. It also describes how `gawk' +has acquired features over time. - *Note Installing `gawk': Installation, describes how to get `gawk', -how to compile it under Unix, and how to compile and use it on different -non-Unix systems. It also describes how to report bugs in `gawk' and -where to get three other freely available implementations of `awk'. + *Note Installation::, describes how to get `gawk', how to compile it +under Unix, and how to compile and use it on different non-Unix +systems. It also describes how to report bugs in `gawk' and where to +get three other freely available implementations of `awk'. - *Note Implementation Notes: Notes, describes how to disable `gawk''s -extensions, as well as how to contribute new code to `gawk', how to -write extension libraries, and some possible future directions for -`gawk' development. + *Note Notes::, describes how to disable `gawk''s extensions, as well +as how to contribute new code to `gawk', how to write extension +libraries, and some possible future directions for `gawk' development. - *Note Basic Programming Concepts: Basic Concepts, provides some very -cursory background material for those who are completely unfamiliar -with computer programming. Also centralized there is a discussion of -some of the issues surrounding floating-point numbers. + *Note Basic Concepts::, provides some very cursory background +material for those who are completely unfamiliar with computer +programming. Also centralized there is a discussion of some of the +issues surrounding floating-point numbers. The *Note Glossary::, defines most, if not all, the significant terms used throughout the book. If you find terms that you aren't familiar with, try looking them up here. - *Note GNU General Public License: Copying, and *Note GNU Free -Documentation License::, present the licenses that cover the `gawk' -source code and this Info file, respectively. + *Note Copying::, and *Note GNU Free Documentation License::, present +the licenses that cover the `gawk' source code and this Info file, +respectively. ---------- Footnotes ---------- @@ -875,11 +873,11 @@ Software Foundation to create a complete, freely distributable, POSIX-compliant computing environment. The FSF uses the "GNU General Public License" (GPL) to ensure that their software's source code is always available to the end user. A copy of the GPL is included for -your reference (*note GNU General Public License: Copying.). The GPL -applies to the C language source code for `gawk'. To find out more -about the FSF and the GNU Project online, see the GNU Project's home -page (http://www.gnu.org). This Info file may also be read from their -web site (http://www.gnu.org/manual/gawk/). +your reference (*note Copying::). The GPL applies to the C language +source code for `gawk'. To find out more about the FSF and the GNU +Project online, see the GNU Project's home page (http://www.gnu.org). +This Info file may also be read from their web site +(http://www.gnu.org/manual/gawk/). A shell, an editor (Emacs), highly portable optimizing C, C++, and Objective-C compilers, a symbolic debugger and dozens of large and @@ -913,18 +911,15 @@ Guide'. This edition maintains the basic structure of Edition 1.0, but with significant additional material, reflecting the host of new features in -`gawk' version 3.1. Of particular note is *Note Sorting Array Values -and Indices with `gawk': Array Sorting, as well as *Note Using `gawk''s -Bit Manipulation Functions: Bitwise Functions, *Note -Internationalization with `gawk': Internationalization, and also *Note -Advanced Features of `gawk': Advanced Features, and *Note Adding New -Built-in Functions to `gawk': Dynamic Extensions. +`gawk' version 3.1. Of particular note is *Note Array Sorting::, as +well as *Note Bitwise Functions::, *Note Internationalization::, and +also *Note Advanced Features::, and *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! -*Note Reporting Problems and Bugs: Bugs, for information on submitting -problem reports electronically, or write to me in care of the publisher. +*Note Bugs::, for information on submitting problem reports +electronically, or write to me in care of the publisher. ---------- Footnotes ---------- @@ -1054,9 +1049,8 @@ often refreshingly easy to read and write. When you run `awk', you specify an `awk' "program" that tells `awk' what to do. The program consists of a series of "rules". (It may also contain "function definitions", an advanced feature that we will ignore -for now. *Note User-Defined Functions: User-defined.) Each rule -specifies one pattern to search for and one action to perform upon -finding the pattern. +for now. *Note User-defined::.) Each rule specifies one pattern to +search for and one action to perform upon finding the pattern. Syntactically, a rule consists of a pattern followed by an action. The action is enclosed in curly braces to separate it from the pattern. @@ -1084,7 +1078,7 @@ like this: other things. -File: gawk.info, Node: Running gawk, Next: Sample Data Files, Prev: Getting Started, Up: Getting Started +File: gawk.info, Node: Running gawk, Next: Sample Data Files, Up: Getting Started How to Run `awk' Programs ========================= @@ -1117,7 +1111,7 @@ variations of each. * Quoting:: More discussion of shell quoting issues. -File: gawk.info, Node: One-shot, Next: Read Terminal, Prev: Running gawk, Up: Running gawk +File: gawk.info, Node: One-shot, Next: Read Terminal, Up: Running gawk One-Shot Throwaway `awk' Programs --------------------------------- @@ -1143,8 +1137,7 @@ programs from shell scripts, because it avoids the need for a separate file for the `awk' program. A self-contained shell script is more reliable because there are no other files to misplace. - *Note Some Simple Examples: Very Simple, presents several short, -self-contained programs. + *Note Very Simple::, presents several short, self-contained programs. File: gawk.info, Node: Read Terminal, Next: Long, Prev: One-shot, Up: Running gawk @@ -1223,13 +1216,12 @@ does the same thing as this one: awk "BEGIN { print \"Don't Panic!\" }" -This was explained earlier (*note Running `awk' Without Input Files: -Read Terminal.). Note that you don't usually need single quotes around -the file name that you specify with `-f', because most file names don't -contain any of the shell's special characters. Notice that in -`advice', the `awk' program did not have single quotes around it. The -quotes are only needed for programs that are provided on the `awk' -command line. +This was explained earlier (*note Read Terminal::). Note that you +don't usually need single quotes around the file name that you specify +with `-f', because most file names don't contain any of the shell's +special characters. Notice that in `advice', the `awk' program did not +have single quotes around it. The quotes are only needed for programs +that are provided on the `awk' command line. If you want to identify your `awk' program files clearly as such, you can add the extension `.awk' to the file name. This doesn't affect @@ -1326,15 +1318,15 @@ programs, but this usually isn't very useful; the purpose of a comment is to help you or another person understand the program when reading it at a later time. - *Caution:* As mentioned in *Note One-Shot Throwaway `awk' Programs: -One-shot, you can enclose small to medium programs in single quotes, in -order to keep your shell scripts self-contained. When doing so, -_don't_ put an apostrophe (i.e., a single quote) into a comment (or -anywhere else in your program). The shell interprets the quote as the -closing quote for the entire program. As a result, usually the shell -prints a message about mismatched quotes, and if `awk' actually runs, -it will probably print strange messages about syntax errors. For -example, look at the following: + *Caution:* As mentioned in *Note One-shot::, you can enclose small +to medium programs in single quotes, in order to keep your shell +scripts self-contained. When doing so, _don't_ put an apostrophe +(i.e., a single quote) into a comment (or anywhere else in your +program). The shell interprets the quote as the closing quote for the +entire program. As a result, usually the shell prints a message about +mismatched quotes, and if `awk' actually runs, it will probably print +strange messages about syntax errors. For example, look at the +following: $ awk '{ print "hello" } # let's be cute' > @@ -1384,8 +1376,7 @@ Bourne-Again Shell). If you use `csh', you're on your own. quotes. The shell does no interpretation of the quoted text, passing it on verbatim to the command. It is _impossible_ to embed a single quote inside single-quoted text. Refer back to - *Note Comments in `awk' Programs: Comments, for an example of what - happens if you try. + *Note Comments::, for an example of what happens if you try. * Double quotes protect most things between the opening and closing quotes. The shell does at least variable and command substitution @@ -1397,8 +1388,8 @@ Bourne-Again Shell). If you use `csh', you're on your own. the characters `$', ``', `\', and `"', all of which must be preceded by a backslash within double-quoted text if they are to be passed on literally to the program. (The leading backslash is - stripped first.) Thus, the example seen in *Note Running `awk' - Without Input Files: Read Terminal, is applicable: + stripped first.) Thus, the example seen in *Note Read Terminal::, + is applicable: $ awk "BEGIN { print \"Don't Panic!\" }" -| Don't Panic! @@ -1516,10 +1507,9 @@ Miscellaneous File Operations: (emacs)Misc File Ops, for more information). Using this information, create your own `BBS-list' and `inventory-shipped' files and practice what you learn in this Info file. - If you are using the stand-alone version of Info, see *Note -Extracting Programs from Texinfo Source Files: Extract Program, for an -`awk' program that extracts these data files from `gawk.texi', the -Texinfo source file for this Info file. + If you are using the stand-alone version of Info, see *Note Extract +Program::, for an `awk' program that extracts these data files from +`gawk.texi', the Texinfo source file for this Info file. File: gawk.info, Node: Very Simple, Next: Two Rules, Prev: Sample Data Files, Up: Getting Started @@ -1542,10 +1532,10 @@ the same thing, so we could have written that instead.) You will notice that slashes (`/') surround the string `foo' in the `awk' program. The slashes indicate that `foo' is the pattern to search for. This type of pattern is called a "regular expression", -which is covered in more detail later (*note Regular Expressions: -Regexp.). The pattern is allowed to match parts of words. There are -single quotes around the `awk' program so that the shell won't -interpret any of it as special shell characters. +which is covered in more detail later (*note Regexp::). The pattern is +allowed to match parts of words. There are single quotes around the +`awk' program so that the shell won't interpret any of it as special +shell characters. Here is what this program prints: @@ -1650,11 +1640,10 @@ appear in the `awk' program. If no patterns match, then no actions are run. After processing all the rules that match the line (and perhaps -there are none), `awk' reads the next line. (However, *note The `next' -Statement: Next Statement., and also *note Using `gawk''s `nextfile' -Statement: Nextfile Statement.). This continues until the program -reaches the end of the file. For example, the following `awk' program -contains two rules: +there are none), `awk' reads the next line. (However, *note Next +Statement::, and also *note Nextfile Statement::). This continues +until the program reaches the end of the file. For example, the +following `awk' program contains two rules: /12/ { print $0 } /21/ { print $0 } @@ -1742,22 +1731,21 @@ variables are automatically initialized to zero.) the value of `sum' is 80600. These more advanced `awk' techniques are covered in later sections -(*note Actions: Action Overview.). Before you can move on to more -advanced `awk' programming, you have to know how `awk' interprets your -input and displays your output. By manipulating fields and using -`print' statements, you can produce some very useful and -impressive-looking reports. +(*note Action Overview::). Before you can move on to more advanced +`awk' programming, you have to know how `awk' interprets your input and +displays your output. By manipulating fields and using `print' +statements, you can produce some very useful and impressive-looking +reports. ---------- Footnotes ---------- (1) In the C shell (`csh'), you need to type a semicolon and then a -backslash at the end of the first line; see *Note `awk' Statements -Versus Lines: Statements/Lines, for an explanation. In a -POSIX-compliant shell, such as the Bourne shell or `bash', you can type -the example as shown. If the command `echo $path' produces an empty -output line, you are most likely using a POSIX-compliant shell. -Otherwise, you are probably using the C shell or a shell derived from -it. +backslash at the end of the first line; see *Note Statements/Lines::, +for an explanation. In a POSIX-compliant shell, such as the Bourne +shell or `bash', you can type the example as shown. If the command +`echo $path' produces an empty output line, you are most likely using a +POSIX-compliant shell. Otherwise, you are probably using the C shell +or a shell derived from it. (2) On some very old systems, you may need to use `ls -lg' to get this output. @@ -1868,10 +1856,9 @@ action. ---------- Footnotes ---------- (1) The `?' and `:' referred to here is the three-operand -conditional expression described in *Note Conditional Expressions: -Conditional Exp. Splitting lines after `?' and `:' is a minor `gawk' -extension; if `--posix' is specified (*note Command-Line Options: -Options.), then this extension is disabled. +conditional expression described in *Note Conditional Exp::. Splitting +lines after `?' and `:' is a minor `gawk' extension; if `--posix' is +specified (*note Options::), then this extension is disabled. File: gawk.info, Node: Other Features, Next: When, Prev: Statements/Lines, Up: Getting Started @@ -1891,8 +1878,7 @@ manipulation, and for runtime string translation. As we develop our presentation of the `awk' language, we introduce most of the variables and many of the functions. They are defined -systematically in *Note Built-in Variables::, and *Note Built-in -Functions: Built-in. +systematically in *Note Built-in Variables::, and *Note Built-in::. File: gawk.info, Node: When, Prev: Other Features, Up: Getting Started @@ -1906,7 +1892,7 @@ patterns, field separators, arithmetic statements, and other selection criteria, you can produce much more complex output. The `awk' language is very useful for producing reports from large amounts of raw data, such as summarizing information from the output of other utility -programs like `ls'. (*Note A More Complex Example: More Complex.) +programs like `ls'. (*Note More Complex::.) Programs written with `awk' are usually much smaller than they would be in other languages. This makes `awk' programs easy to compose and @@ -1964,7 +1950,7 @@ you specify more complicated classes of strings. * Locales:: How the locale affects things. -File: gawk.info, Node: Regexp Usage, Next: Escape Sequences, Prev: Regexp, Up: Regexp +File: gawk.info, Node: Regexp Usage, Next: Escape Sequences, Up: Regexp How to Use Regular Expressions ============================== @@ -1988,7 +1974,7 @@ string to match against; it need not be the entire current input record. The two operators `~' and `!~' perform regular expression comparisons. Expressions using these operators can be used as patterns, or in `if', `while', `for', and `do' statements. (*Note -Control Statements in Actions: Statements.) For example: +Statements::.) For example: EXP ~ /REGEXP/ @@ -2110,14 +2096,14 @@ apply to both string constants and regexp constants: string. In `gawk', a number of additional two-character sequences that begin -with a backslash have special meaning in regexps. *Note -`gawk'-Specific Regexp Operators: GNU Regexp Operators. +with a backslash have special meaning in regexps. *Note GNU Regexp +Operators::. In a regexp, a backslash before any character that is not in the -previous list and not listed in *Note `gawk'-Specific Regexp Operators: -GNU Regexp Operators, means that the next character should be taken -literally, even if it would normally be a regexp operator. For -example, `/a\+b/' matches the three characters `a+b'. +previous list and not listed in *Note GNU Regexp Operators::, means +that the next character should be taken literally, even if it would +normally be a regexp operator. For example, `/a\+b/' matches the three +characters `a+b'. For complete portability, do not use a backslash before any character not shown in the previous list. @@ -2129,9 +2115,8 @@ character not shown in the previous list. early, as soon as `awk' reads your program. * `gawk' processes both regexp constants and dynamic regexps (*note - Using Dynamic Regexps: Computed Regexps.), for the special - operators listed in *Note `gawk'-Specific Regexp Operators: GNU - Regexp Operators. + Computed Regexps::), for the special operators listed in *Note GNU + Regexp Operators::. * A backslash before any other character means to treat that character literally. @@ -2159,16 +2144,15 @@ Advanced Notes: Escape Sequences for Metacharacters --------------------------------------------------- Suppose you use an octal or hexadecimal escape to represent a regexp -metacharacter. (See *Note Regular Expression Operators: Regexp -Operators.) Does `awk' treat the character as a literal character or -as a regexp operator? +metacharacter. (See *Note Regexp Operators::.) Does `awk' treat the +character as a literal character or as a regexp operator? Historically, such characters were taken literally. (d.c.) However, the POSIX standard indicates that they should be treated as real metacharacters, which is what `gawk' does. In compatibility mode -(*note Command-Line Options: Options.), `gawk' treats the characters -represented by octal and hexadecimal escape sequences literally when -used in regexp constants. Thus, `/a\52b/' is equivalent to `/a\*b/'. +(*note Options::), `gawk' treats the characters represented by octal +and hexadecimal escape sequences literally when used in regexp +constants. Thus, `/a\52b/' is equivalent to `/a\*b/'. File: gawk.info, Node: Regexp Operators, Next: Character Lists, Prev: Escape Sequences, Up: Regexp @@ -2220,18 +2204,17 @@ sequences and that are not listed in the table stand for themselves: regular expression such as `U.A', which matches any three-character sequence that begins with `U' and ends with `A'. - In strict POSIX mode (*note Command-Line Options: Options.), `.' - does not match the NUL character, which is a character with all - bits equal to zero. Otherwise, NUL is just another character. - Other versions of `awk' may not be able to match the NUL character. + In strict POSIX mode (*note Options::), `.' does not match the NUL + character, which is a character with all bits equal to zero. + Otherwise, NUL is just another character. Other versions of `awk' + may not be able to match the NUL character. `[...]' This is called a "character list".(1) It matches any _one_ of the characters that are enclosed in the square brackets. For example, `[MVX]' matches any one of the characters `M', `V', or `X' in a string. A full discussion of what can be inside the square - brackets of a character list is given in *Note Using Character - Lists: Character Lists. + brackets of a character list is given in *Note Character Lists::. `[^ ...]' This is a "complemented character list". The first character after @@ -2312,8 +2295,8 @@ sequences and that are not listed in the table stand for themselves: However, because old programs may use `{' and `}' in regexp constants, by default `gawk' does _not_ match interval expressions in regexps. If either `--posix' or `--re-interval' are specified - (*note Command-Line Options: Options.), then interval expressions - are allowed in regexps. + (*note Options::), then interval expressions are allowed in + regexps. For new programs that use `{' and `}' in regexp constants, it is good practice to always escape them with a backslash. Then the @@ -2330,9 +2313,9 @@ themselves when there is nothing in the regexp that precedes them. For example, `/+/' matches a literal plus sign. However, many other versions of `awk' treat such a usage as a syntax error. - If `gawk' is in compatibility mode (*note Command-Line Options: -Options.), POSIX character classes and interval expressions are not -available in regular expressions. + If `gawk' is in compatibility mode (*note Options::), POSIX +character classes and interval expressions are not available in regular +expressions. ---------- Footnotes ---------- @@ -2497,14 +2480,13 @@ would have been to require two backslashes in the GNU operators, but this was deemed too confusing. The current method of using `\y' for the GNU `\b' appears to be the lesser of two evils. - The various command-line options (*note Command-Line Options: -Options.) control how `gawk' interprets characters in regexps: + The various command-line options (*note Options::) control how +`gawk' interprets characters in regexps: No options In the default case, `gawk' provides all the facilities of POSIX - regexps and the GNU regexp operators described in *Note Regular - Expression Operators: Regexp Operators. However, interval - expressions are not supported. + regexps and the GNU regexp operators described in *Note Regexp + Operators::. However, interval expressions are not supported. `--posix' Only POSIX regexps are supported; the GNU operators are not special @@ -2543,8 +2525,7 @@ read. There are two alternatives that you might prefer. One way to perform a case-insensitive match at a particular point in the program is to convert the data to a single case, using the `tolower' or `toupper' built-in string functions (which we haven't -discussed yet; *note String Manipulation Functions: String Functions.). -For example: +discussed yet; *note String Functions::). For example: tolower($1) ~ /foo/ { ... } @@ -2573,10 +2554,9 @@ particular rule.(1) To do this, use either character lists or dynamically turn case-sensitivity on or off for all the rules at once. `IGNORECASE' can be set on the command line or in a `BEGIN' rule -(*note Other Command-Line Arguments: Other Arguments.; also *note -Startup and Cleanup Actions: Using BEGIN/END.). Setting `IGNORECASE' -from the command line is a way to make a program case-insensitive -without having to edit it. +(*note Other Arguments::; also *note Using BEGIN/END::). Setting +`IGNORECASE' from the command line is a way to make a program +case-insensitive without having to edit it. Prior to `gawk' 3.0, the value of `IGNORECASE' affected regexp operations only. It did not affect string comparison with `==', `!=', @@ -2590,8 +2570,8 @@ ASCII characters, which also provides a number of characters suitable for use with European languages. The value of `IGNORECASE' has no effect if `gawk' is in -compatibility mode (*note Command-Line Options: Options.). Case is -always significant in compatibility mode. +compatibility mode (*note Options::). Case is always significant in +compatibility mode. ---------- Footnotes ---------- @@ -2611,9 +2591,9 @@ How Much Text Matches? echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }' This example uses the `sub' function (which we haven't discussed yet; -*note String Manipulation Functions: String Functions.) to make a -change to the input record. Here, the regexp `/a+/' indicates "one or -more `a' characters," and the replacement text is `<A>'. +*note String Functions::) to make a change to the input record. Here, +the regexp `/a+/' indicates "one or more `a' characters," and the +replacement text is `<A>'. The input contains four `a' characters. `awk' (and POSIX) regular expressions always match the leftmost, _longest_ sequence of input @@ -2625,12 +2605,10 @@ with `<A>' in this example: For simple match/no-match tests, this is not so important. But when doing text matching and substitutions with the `match', `sub', `gsub', -and `gensub' functions, it is very important. *Note String -Manipulation Functions: String Functions, for more information on these -functions. Understanding this principle is also important for -regexp-based record and field splitting (*note How Input Is Split into -Records: Records., and also *note Specifying How Fields Are Separated: -Field Separators.). +and `gensub' functions, it is very important. *Note String Functions::, +for more information on these functions. Understanding this principle +is also important for regexp-based record and field splitting (*note +Records::, and also *note Field Separators::). File: gawk.info, Node: Computed Regexps, Next: Locales, Prev: Leftmost Longest, Up: Regexp @@ -2724,8 +2702,8 @@ ways. In particular, many locales do case-insensitive matching, even when you may have specified characters of only one particular case. The following example uses the `sub' function, which does text -replacement (*note String-Manipulation Functions: String Functions.). -Here, the intent is to remove trailing uppercase characters: +replacement (*note String Functions::). Here, the intent is to remove +trailing uppercase characters: $ echo something1234abc | gawk '{ sub("[A-Z]*$", ""); print }' -| something1234 @@ -2745,6 +2723,18 @@ statements: manner, where case distinctions do matter. You may wish to put these statements into your shell startup file, e.g., `$HOME/.profile'. + Similar considerations apply to other ranges. For example, `["-/]' +is perfectly valid in ASCII, but is not valid in many Unicode locales, +such as `en_US.UTF-8'. (In general, such ranges should be avoided; +either list the characters individually, or use a POSIX character class +such as `[[:punct:]]'.) + + For the normal case of `RS = "\n"', the locale is largely irrelevant. +For other single byte record separators, using `LC_ALL=C' will give you +much better performance when reading records. Otherwise, `gawk' has to +make several function calls, _per input character_ to find the record +terminator. + File: gawk.info, Node: Reading Files, Next: Printing, Prev: Regexp, Up: Top @@ -2768,8 +2758,7 @@ parts of a record. On rare occasions, you may need to use the `getline' command. The `getline' command is valuable, both because it can do explicit input from any number of files, and because the files used with it do not -have to be named on the `awk' command line (*note Explicit Input with -`getline': Getline.). +have to be named on the `awk' command line (*note Getline::). * Menu: @@ -2784,7 +2773,7 @@ have to be named on the `awk' command line (*note Explicit Input with using the `getline' function. -File: gawk.info, Node: Records, Next: Fields, Prev: Reading Files, Up: Reading Files +File: gawk.info, Node: Records, Next: Fields, Up: Reading Files How Input Is Split into Records =============================== @@ -2805,13 +2794,12 @@ built-in variable `RS'. Like any other variable, the value of `RS' can be changed in the `awk' program with the assignment operator, `=' (*note Assignment -Expressions: Assignment Ops.). The new record-separator character -should be enclosed in quotation marks, which indicate a string -constant. Often the right time to do this is at the beginning of -execution, before any input is processed, so that the very first record -is read with the proper separator. To do this, use the special `BEGIN' -pattern (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.). -For example: +Ops::). The new record-separator character should be enclosed in +quotation marks, which indicate a string constant. Often the right +time to do this is at the beginning of execution, before any input is +processed, so that the very first record is read with the proper +separator. To do this, use the special `BEGIN' pattern (*note +BEGIN/END::). For example: awk 'BEGIN { RS = "/" } { print $0 }' BBS-list @@ -2854,8 +2842,8 @@ newline. Here are the results of running the program on `BBS-list': -| Note that the entry for the `camelot' BBS is not split. In the -original data file (*note Data Files for the Examples: Sample Data -Files.), the line looks like this: +original data file (*note Sample Data Files::), the line looks like +this: camelot 555-0542 300 C @@ -2866,8 +2854,7 @@ separating them in the output is the original newline in the data file, not the one added by `awk' when it printed the record! Another way to change the record separator is on the command line, -using the variable-assignment feature (*note Other Command-Line -Arguments: Other Arguments.): +using the variable-assignment feature (*note Other Arguments::): awk '{ print $0 }' RS="/" BBS-list @@ -2889,8 +2876,8 @@ record, even if the last character in the file is not the character in The empty string `""' (a string without any characters) has a special meaning as the value of `RS'. It means that records are -separated by one or more blank lines and nothing else. *Note -Multiple-Line Records: Multiple Line, for more details. +separated by one or more blank lines and nothing else. *Note Multiple +Line::, for more details. If you change the value of `RS' in the middle of an `awk' run, the new value is used to delimit subsequent records, but the record @@ -2900,15 +2887,14 @@ affected. After the end of the record has been determined, `gawk' sets the variable `RT' to the text in the input that matched `RS'. When using `gawk', the value of `RS' is not limited to a one-character string. It -can be any regular expression (*note Regular Expressions: Regexp.). In -general, each record ends at the next string that matches the regular -expression; the next record starts at the end of the matching string. -This general rule is actually at work in the usual case, where `RS' -contains just a newline: a record ends at the beginning of the next -matching string (the next newline in the input), and the following -record starts just after the end of this string (at the first character -of the following line). The newline, because it matches `RS', is not -part of either record. +can be any regular expression (*note Regexp::). In general, each record +ends at the next string that matches the regular expression; the next +record starts at the end of the matching string. This general rule is +actually at work in the usual case, where `RS' contains just a newline: +a record ends at the beginning of the next matching string (the next +newline in the input), and the following record starts just after the +end of this string (at the first character of the following line). The +newline, because it matches `RS', is not part of either record. When `RS' is a single character, `RT' contains the same single character. However, when `RS' is a regular expression, `RT' contains @@ -2929,8 +2915,8 @@ trailing whitespace: The final line of output has an extra blank line. This is because the value of `RT' is a newline, and the `print' statement supplies its own -terminating newline. *Note A Simple Stream Editor: Simple Sed, for a -more useful example of `RS' as a regexp and `RT'. +terminating newline. *Note Simple Sed::, for a more useful example of +`RS' as a regexp and `RT'. If you set `RS' to a regular expression that allows optional trailing text, such as `RS = "abc(XYZ)?"' it is possible, due to @@ -2942,9 +2928,8 @@ that this will never happen. The use of `RS' as a regular expression and the `RT' variable are `gawk' extensions; they are not available in compatibility mode (*note -Command-Line Options: Options.). In compatibility mode, only the first -character of the value of `RS' is used to determine the end of the -record. +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 ------------------------------------------- @@ -3031,9 +3016,8 @@ are not interested in specific fields. Here are some more examples: This example prints each record in the file `BBS-list' whose first field contains the string `foo'. The operator `~' is called a -"matching operator" (*note How to Use Regular Expressions: Regexp -Usage.); it tests whether a string (here, the field `$1') matches a -given regular expression. +"matching operator" (*note Regexp Usage::); it tests whether a string +(here, the field `$1') matches a given regular expression. By contrast, the following example looks for `foo' in _the entire record_ and prints the first field and the last field for each matching @@ -3081,7 +3065,7 @@ necessary whenever there is a binary operator in the field-number expression. This example, then, prints the hours of operation (the fourth field) for every line of the file `BBS-list'. (All of the `awk' operators are listed, in order of decreasing precedence, in *Note -Operator Precedence (How Operators Nest): Precedence.) +Precedence::.) If the field number you compute is zero, you get the entire record. Thus, `$(2-2)' has the same value as `$0'. Negative field numbers are @@ -3090,11 +3074,11 @@ not allowed; trying to reference one usually terminates the program. negative field number. `gawk' notices this and terminates your program. Other `awk' implementations may behave differently.) - As mentioned in *Note Examining Fields: Fields, `awk' stores the -current record's number of fields in the built-in variable `NF' (also -*note Built-in Variables::). The expression `$NF' is not a special -feature--it is the direct consequence of evaluating `NF' and using its -value as a field number. + As mentioned in *Note Fields::, `awk' stores the current record's +number of fields in the built-in variable `NF' (also *note Built-in +Variables::). The expression `$NF' is not a special feature--it is the +direct consequence of evaluating `NF' and using its value as a field +number. File: gawk.info, Node: Changing Fields, Next: Field Separators, Prev: Nonconstant Fields, Up: Reading Files @@ -3117,17 +3101,15 @@ input file.) Consider the following example and its output: The program first saves the original value of field three in the variable `nboxes'. The `-' sign represents subtraction, so this program reassigns field three, `$3', as the original value of field -three minus ten: `$3 - 10'. (*Note Arithmetic Operators: Arithmetic -Ops.) Then it prints the original and new values for field three. -(Someone in the warehouse made a consistent mistake while inventorying -the red boxes.) +three minus ten: `$3 - 10'. (*Note Arithmetic Ops::.) Then it prints +the original and new values for field three. (Someone in the warehouse +made a consistent mistake while inventorying the red boxes.) For this to work, the text in field `$3' must make sense as a number; the string of characters must be converted to a number for the computer to do arithmetic on it. The number resulting from the subtraction is converted back to a string of characters that then -becomes field three. *Note Conversion of Strings and Numbers: -Conversion. +becomes field three. *Note Conversion::. When the value of a field is changed (as perceived by `awk'), the text of the input record is recalculated to contain the new field where @@ -3163,11 +3145,11 @@ the appropriate number of field separators between it and the previously existing fields. This recomputation affects and is affected by `NF' (the number of -fields; *note Examining Fields: Fields.). For example, the value of -`NF' is set to the number of the highest field you create. The exact -format of `$0' is also affected by a feature that has not been -discussed yet: the "output field separator", `OFS', used to separate -the fields (*note Output Separators::). +fields; *note Fields::). For example, the value of `NF' is set to the +number of the highest field you create. The exact format of `$0' is +also affected by a feature that has not been discussed yet: the "output +field separator", `OFS', used to separate the fields (*note Output +Separators::). Note, however, that merely _referencing_ an out-of-range field does _not_ change the value of either `$0' or `NF'. Referencing an @@ -3179,10 +3161,9 @@ out-of-range field only produces an empty string. For example: print "everything is normal" should print `everything is normal', because `NF+1' is certain to be -out of range. (*Note The `if'-`else' Statement: If Statement, for more -information about `awk''s `if-else' statements. *Note Variable Typing -and Comparison Expressions: Typing and Comparison, for more information -about the `!=' operator.) +out of range. (*Note If Statement::, for more information about +`awk''s `if-else' statements. *Note Typing and Comparison::, for more +information about the `!=' operator.) It is important to note that making an assignment to an existing field changes the value of `$0' but does not change the value of `NF', @@ -3231,7 +3212,7 @@ as we've shown here. fields. Any assignment to `$0' causes the record to be reparsed into 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-Manipulation Functions: String Functions.). +String Functions::). File: gawk.info, Node: Field Separators, Next: Constant Size, Prev: Changing Fields, Up: Reading Files @@ -3267,12 +3248,12 @@ is used by the POSIX-compliant shells (such as the Unix Bourne shell, `sh', or `bash'). The value of `FS' can be changed in the `awk' program with the -assignment operator, `=' (*note Assignment Expressions: Assignment -Ops.). Often the right time to do this is at the beginning of execution -before any input has been processed, so that the very first record is -read with the proper separator. To do this, use the special `BEGIN' -pattern (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.). -For example, here we set the value of `FS' to the string `","': +assignment operator, `=' (*note Assignment Ops::). Often the right +time to do this is at the beginning of execution before any input has +been processed, so that the very first record is read with the proper +separator. To do this, use the special `BEGIN' pattern (*note +BEGIN/END::). For example, here we set the value of `FS' to the string +`","': awk 'BEGIN { FS = "," } ; { print $2 }' @@ -3314,7 +3295,7 @@ space character is the only single character that does not follow these rules. -File: gawk.info, Node: Regexp Field Splitting, Next: Single Character Fields, Prev: Field Separators, Up: Field Separators +File: gawk.info, Node: Regexp Field Splitting, Next: Single Character Fields, Up: Field Separators Using Regular Expressions to Separate Fields -------------------------------------------- @@ -3335,8 +3316,7 @@ of similar escape sequences.) For a less trivial example of a regular expression, try using single spaces to separate fields the way single commas are used. `FS' can be set to `"[ ]"' (left bracket, space, right bracket). This regular -expression matches a single space and nothing else (*note Regular -Expressions: Regexp.). +expression matches a single space and nothing else (*note Regexp::). There is an important difference between the two cases of `FS = " "' (a single space) and `FS = "[ \t\n]+"' (a regular expression matching @@ -3396,8 +3376,8 @@ the record becomes a separate field. For example: Traditionally, the behavior of `FS' equal to `""' was not defined. In this case, most versions of Unix `awk' simply treat the entire record as only having one field. (d.c.) In compatibility mode (*note -Command-Line Options: Options.), if `FS' is the null string, then -`gawk' also behaves this way. +Options::), if `FS' is the null string, then `gawk' also behaves this +way. File: gawk.info, Node: Command Line Field Separator, Next: Field Splitting Summary, Prev: Single Character Fields, Up: Field Separators @@ -3431,13 +3411,12 @@ Because `\' is used for quoting in the shell, `awk' sees `-F\\'. Then Sequences::), finally yielding a single `\' to use for the field separator. - As a special case, in compatibility mode (*note Command-Line -Options: Options.), if the argument to `-F' is `t', then `FS' is set to -the TAB character. If you type `-F\t' at the shell, without any -quotes, the `\' gets deleted, so `awk' figures that you really want -your fields to be separated with tabs and not `t's. Use `-v FS="t"' or -`-F"[t]"' on the command line if you really do want to separate your -fields with `t's. + As a special case, in compatibility mode (*note Options::), if the +argument to `-F' is `t', then `FS' is set to the TAB character. If you +type `-F\t' at the shell, without any quotes, the `\' gets deleted, so +`awk' figures that you really want your fields to be separated with +tabs and not `t's. Use `-v FS="t"' or `-F"[t]"' on the command line if +you really do want to separate your fields with `t's. For example, let's use an `awk' program file called `baud.awk' that contains the pattern `/300/' and the action `print $1': @@ -3555,10 +3534,10 @@ like: Advanced Notes: `FS' and `IGNORECASE' ------------------------------------- - The `IGNORECASE' variable (*note Built-in Variables That Control -`awk': 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: + 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: FS = "c" IGNORECASE = 1 @@ -3594,9 +3573,8 @@ anticipate the use of their output as input for other programs. up by the use of a variable number of spaces and _empty fields are just spaces_. Clearly, `awk''s normal field splitting based on `FS' does not work well in this case. Although a portable `awk' program can use -a series of `substr' calls on `$0' (*note String Manipulation -Functions: String Functions.), this is awkward and inefficient for a -large number of fields. +a series of `substr' calls on `$0' (*note String Functions::), this is +awkward and inefficient for a large number of fields. The splitting of an input record into fixed-width fields is specified by assigning a string containing space-separated numbers to @@ -3666,10 +3644,9 @@ run on a system with card readers is another story!) Assigning a value to `FS' causes `gawk' to use `FS' for field splitting again. Use `FS = FS' to make this happen, without having to know the current value of `FS'. In order to tell which kind of field -splitting is in effect, use `PROCINFO["FS"]' (*note Built-in Variables -That Convey Information: Auto-set.). The value is `"FS"' if regular -field splitting is being used, or it is `"FIELDWIDTHS"' if fixed-width -field splitting is being used: +splitting is in effect, use `PROCINFO["FS"]' (*note Auto-set::). The +value is `"FS"' if regular field splitting is being used, or it is +`"FIELDWIDTHS"' if fixed-width field splitting is being used: if (PROCINFO["FS"] == "FS") REGULAR FIELD SPLITTING ... @@ -3678,8 +3655,8 @@ field splitting is being used: This information is useful when writing a function that needs to temporarily change `FS' or `FIELDWIDTHS', read some records, and then -restore the original settings (*note Reading the User Database: Passwd -Functions., for an example of such a function). +restore the original settings (*note Passwd Functions::, for an example +of such a function). File: gawk.info, Node: Multiple Line, Next: Getline, Prev: Constant Size, Up: Reading Files @@ -3711,10 +3688,10 @@ empty; lines that contain only whitespace do not count.) `"\n\n+"' to `RS'. This regexp matches the newline at the end of the record and one or more blank lines after the record. In addition, a regular expression always matches the longest possible sequence when -there is a choice (*note How Much Text Matches?: Leftmost Longest.). -So the next record doesn't start until the first nonblank line that -follows--no matter how many blank lines appear in a row, they are -considered one record separator. +there is a choice (*note Leftmost Longest::). So the next record +doesn't start until the first nonblank line that follows--no matter how +many blank lines appear in a row, they are considered one record +separator. There is an important difference between `RS = ""' and `RS = "\n\n+"'. In the first case, leading newlines in the input data file @@ -3735,12 +3712,11 @@ provide useful behavior in the default case (i.e., `FS' is equal to `" "'). This feature can be a problem if you really don't want the newline character to separate fields, because there is no way to prevent it. However, you can work around this by using the `split' -function to break up the record manually (*note String Manipulation -Functions: String Functions.). If you have a single character field -separator, you can work around the special feature in a different way, -by making `FS' into a regexp for that single character. For example, -if the field separator is a percent character, instead of `FS = "%"', -use `FS = "[%]"'. +function to break up the record manually (*note String Functions::). +If you have a single character field separator, you can work around the +special feature in a different way, by making `FS' into a regexp for +that single character. For example, if the field separator is a +percent character, instead of `FS = "%"', use `FS = "[%]"'. Another way to separate fields is to put each field on a separate line: to do this, just set the variable `FS' to the string `"\n"'. @@ -3786,10 +3762,9 @@ A simple program to process this file is as follows: -| ... - *Note Printing Mailing Labels: Labels Program, for a more realistic -program that deals with address lists. The following table summarizes -how records are split, based on the value of `RS'. (`==' means "is -equal to.") + *Note Labels Program::, for a more realistic program that deals with +address lists. The following table summarizes how records are split, +based on the value of `RS'. (`==' means "is equal to.") `RS == "\n"' Records are separated by the newline character (`\n'). In effect, @@ -3866,7 +3841,7 @@ represents a shell command. * Getline Summary:: Summary of `getline' Variants. -File: gawk.info, Node: Plain Getline, Next: Getline/Variable, Prev: Getline, Up: Getline +File: gawk.info, Node: Plain Getline, Next: Getline/Variable, Up: Getline Using `getline' with No Arguments --------------------------------- @@ -3913,8 +3888,7 @@ value of `$0'. subsequent rules. The original value of `$0' that triggered the rule that executed `getline' is lost. By contrast, the `next' statement reads a new record but immediately begins processing it normally, -starting with the first rule in the program. *Note The `next' -Statement: Next Statement. +starting with the first rule in the program. *Note Next Statement::. File: gawk.info, Node: Getline/Variable, Next: Getline/File, Prev: Plain Getline, Up: Getline @@ -3988,8 +3962,7 @@ EXPRESSION contains unparenthesized operators other than `$'; for example, `getline < dir "/" file' is ambiguous because the concatenation operator is not parenthesized. You should write it as `getline < (dir "/" file)' if you want your program to be portable to -other `awk' implementations. (It happens that `gawk' gets it right, -but you should not rely on this. Parentheses make it easier to read.) +other `awk' implementations. File: gawk.info, Node: Getline/Variable/File, Next: Getline/Pipe, Prev: Getline/File, Up: Getline @@ -4023,14 +3996,12 @@ second field on the `@include' line. The `close' function is called to ensure that if two identical `@include' lines appear in the input, the entire specified file is -included twice. *Note Closing Input and Output Redirections: Close -Files And Pipes. +included twice. *Note Close Files And Pipes::. One deficiency of this program is that it does not process nested `@include' statements (i.e., `@include' statements in included files) -the way a true macro preprocessor would. *Note An Easy Way to Use -Library Functions: Igawk Program, for a program that does handle nested -`@include' statements. +the way a true macro preprocessor would. *Note Igawk Program::, for a +program that does handle nested `@include' statements. File: gawk.info, Node: Getline/Pipe, Next: Getline/Variable/Pipe, Prev: Getline/Variable/File, Up: Getline @@ -4058,8 +4029,7 @@ produced by running the rest of the line as a shell command: The `close' function is called to ensure that if two identical `@execute' lines appear in the input, the command is run for each one. -*Note Closing Input and Output Redirections: Close Files And Pipes. -Given the input: +*Note Close Files And Pipes::. Given the input: foo bar @@ -4090,9 +4060,7 @@ EXPRESSION contains unparenthesized operators other than `$'--for example, `"echo " "date" | getline' is ambiguous because the concatenation operator is not parenthesized. You should write it as `("echo " "date") | getline' if you want your program to be portable to -other `awk' implementations. (It happens that `gawk' gets it right, -but you should not rely on this. Parentheses make it easier to read, -anyway.) +other `awk' implementations. File: gawk.info, Node: Getline/Variable/Pipe, Next: Getline/Coprocess, Prev: Getline/Pipe, Up: Getline @@ -4119,9 +4087,7 @@ EXPRESSION contains unparenthesized operators other than `$'; for example, `"echo " "date" | getline VAR' is ambiguous because the concatenation operator is not parenthesized. You should write it as `("echo " "date") | getline VAR' if you want your program to be -portable to other `awk' implementations. (It happens that `gawk' gets -it right, but you should not rely on this. Parentheses make it easier -to read, anyway.) +portable to other `awk' implementations. File: gawk.info, Node: Getline/Coprocess, Next: Getline/Variable/Coprocess, Prev: Getline/Variable/Pipe, Up: Getline @@ -4150,9 +4116,8 @@ normal manner, thus changing the values of `$0', of the other fields, and of `NF'. Coprocesses are an advanced feature. They are discussed here only -because this is the minor node on `getline'. *Note Two-Way -Communications with Another Process: Two-way I/O, where coprocesses are -discussed in more detail. +because this is the minor node on `getline'. *Note Two-way I/O::, +where coprocesses are discussed in more detail. File: gawk.info, Node: Getline/Variable/Coprocess, Next: Getline Notes, Prev: Getline/Coprocess, Up: Getline @@ -4169,9 +4134,8 @@ changed and the record is not split into fields. The only variable changed is VAR. Coprocesses are an advanced feature. They are discussed here only -because this is the minor node on `getline'. *Note Two-Way -Communications with Another Process: Two-way I/O, where coprocesses are -discussed in more detail. +because this is the minor node on `getline'. *Note Two-way I/O::, +where coprocesses are discussed in more detail. File: gawk.info, Node: Getline Notes, Next: Getline Summary, Prev: Getline/Variable/Coprocess, Up: Getline @@ -4198,9 +4162,7 @@ bear in mind: `getline' command causes `awk' to set the value of `FILENAME'. Normally, `FILENAME' does not have a value inside `BEGIN' rules, because you have not yet started to process the command-line data - files. (d.c.) (*Note The `BEGIN' and `END' Special Patterns: - BEGIN/END, also *note Built-in Variables That Convey Information: - Auto-set..) + files. (d.c.) (*Note BEGIN/END::, also *note Auto-set::.) * Using `FILENAME' with `getline' (`getline < FILENAME') is likely to be a source for confusion. `awk' opens a separate input stream @@ -4241,9 +4203,8 @@ statement is not limited when computing _which_ values to print. However, with two exceptions, you cannot specify _how_ to print them--how many columns, whether to use exponential notation or not, and so on. (For the exceptions, *note Output Separators::, and *Note -Controlling Numeric Output with `print': OFMT.) For printing with -specifications, you need the `printf' statement (*note Using `printf' -Statements for Fancier Printing: Printf.). +OFMT::.) For printing with specifications, you need the `printf' +statement (*note Printf::). Besides basic and formatted printing, this major node also covers I/O redirections to files and pipes, introduces the special file names @@ -4265,7 +4226,7 @@ function. * Close Files And Pipes:: Closing Input and Output Files and Pipes. -File: gawk.info, Node: Print, Next: Print Examples, Prev: Printing, Up: Printing +File: gawk.info, Node: Print, Next: Print Examples, Up: Printing The `print' Statement ===================== @@ -4280,7 +4241,7 @@ spaces, followed by a newline. The statement looks like this: The entire list of items may be optionally enclosed in parentheses. The parentheses are necessary if any of the item expressions uses the `>' relational operator; otherwise it could be confused with a redirection -(*note Redirecting Output of `print' and `printf': Redirection.). +(*note Redirection::). The items to print can be constant strings or numbers, fields of the current record (such as `$1'), variables, or any `awk' expression. @@ -4341,8 +4302,7 @@ Here is the same program, without the comma: example's output makes much sense. A heading line at the beginning would make it clearer. Let's add some headings to our table of months (`$1') and green crates shipped (`$2'). We do this using the `BEGIN' -pattern (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.) so -that the headings are only printed once: +pattern (*note BEGIN/END::) so that the headings are only printed once: awk 'BEGIN { print "Month Crates" print "----- ------" } @@ -4368,13 +4328,11 @@ fields: Lining up columns this way can get pretty complicated when there are many columns to fix. Counting spaces for two or three columns is simple, but any more than this can take up a lot of time. This is why -the `printf' statement was created (*note Using `printf' Statements for -Fancier Printing: Printf.); one of its specialties is lining up columns -of data. +the `printf' statement was created (*note Printf::); one of its +specialties is lining up columns of data. *Note:* You can continue either a `print' or `printf' statement -simply by putting a newline after any comma (*note `awk' Statements -Versus Lines: Statements/Lines.). +simply by putting a newline after any comma (*note Statements/Lines::). File: gawk.info, Node: Output Separators, Next: OFMT, Prev: Print Examples, Up: Printing @@ -4398,11 +4356,10 @@ Thus, each `print' statement normally makes a separate line. In order to change how output fields and records are separated, assign new values to the variables `OFS' and `ORS'. The usual place to -do this is in the `BEGIN' rule (*note The `BEGIN' and `END' Special -Patterns: BEGIN/END.), so that it happens before any input is -processed. It can also be done with assignments on the command line, -before the names of the input files, or using the `-v' command-line -option (*note Command-Line Options: Options.). The following example +do this is in the `BEGIN' rule (*note BEGIN/END::), so that it happens +before any input is processed. It can also be done with assignments on +the command line, before the names of the input files, or using the +`-v' command-line option (*note Options::). The following example prints the first and second fields of each input record, separated by a semicolon, with a blank line added after each newline: @@ -4427,12 +4384,11 @@ Controlling Numeric Output with `print' When the `print' statement is used to print numeric values, `awk' internally converts the number to a string of characters and prints that string. `awk' uses the `sprintf' function to do this conversion -(*note String Manipulation Functions: String Functions.). For now, it -suffices to say that the `sprintf' function accepts a "format -specification" that tells it how to format numbers (or strings), and -that there are a number of different ways in which numbers can be -formatted. The different format specifications are discussed more -fully in *Note Format-Control Letters: Control Letters. +(*note String Functions::). For now, it suffices to say that the +`sprintf' function accepts a "format specification" that tells it how +to format numbers (or strings), and that there are a number of +different ways in which numbers can be formatted. The different format +specifications are discussed more fully in *Note Control Letters::. The built-in variable `OFMT' contains the default format specification that `print' uses with `sprintf' when it wants to convert @@ -4473,7 +4429,7 @@ arguments. * Printf Examples:: Several examples. -File: gawk.info, Node: Basic Printf, Next: Control Letters, Prev: Printf, Up: Printf +File: gawk.info, Node: Basic Printf, Next: Control Letters, Up: Printf Introduction to the `printf' Statement -------------------------------------- @@ -4485,8 +4441,7 @@ Introduction to the `printf' Statement The entire list of arguments may optionally be enclosed in parentheses. The parentheses are necessary if any of the item expressions use the `>' relational operator; otherwise, it can be confused with a -redirection (*note Redirecting Output of `print' and `printf': -Redirection.). +redirection (*note Redirection::). The difference between `printf' and `print' is the FORMAT argument. This is an expression whose value is taken as a string; it specifies @@ -4583,9 +4538,11 @@ width. Here is a list of the format-control letters: it ignores any modifiers. *Note:* When using the integer format-control letters for values -that are outside the range of a C `long' integer, `gawk' switches to the -`%g' format specifier. Other versions of `awk' may print invalid values -or do something else entirely. (d.c.) +that are outside the range of the widest C integer type, `gawk' +switches to the the `%g' format specifier. If `--lint' is provided on +the command line (*note Options::), `gawk' warns about this. Other +versions of `awk' may print invalid values or do something else +entirely. (d.c.) File: gawk.info, Node: Format Modifiers, Next: Printf Examples, Prev: Control Letters, Up: Printf @@ -4615,9 +4572,9 @@ which they may appear: At first glance, this feature doesn't seem to be of much use. It is in fact a `gawk' extension, intended for use in translating - messages at runtime. *Note Rearranging `printf' Arguments: Printf - Ordering, which describes how and why to use positional specifiers. - For now, we will not use them. + messages at runtime. *Note Printf Ordering::, which describes how + and why to use positional specifiers. For now, we will not use + them. `-' The minus sign, used before the width modifier (see later on in @@ -4727,9 +4684,9 @@ This is not particularly easy to read but it does work. C programmers may be used to supplying additional `l', `L', and `h' modifiers in `printf' format strings. These are not valid in `awk'. Most `awk' implementations silently ignore these modifiers. If -`--lint' is provided on the command line (*note Command-Line Options: -Options.), `gawk' warns about their use. If `--posix' is supplied, -their use is a fatal error. +`--lint' is provided on the command line (*note Options::), `gawk' +warns about their use. If `--posix' is supplied, their use is a fatal +error. File: gawk.info, Node: Printf Examples, Prev: Format Modifiers, Up: Printf @@ -4770,9 +4727,9 @@ they are last on their lines. They don't need to have spaces after them. The table could be made to look even nicer by adding headings to the -tops of the columns. This is done using the `BEGIN' pattern (*note The -`BEGIN' and `END' Special Patterns: BEGIN/END.) so that the headers -are only printed once, at the beginning of the `awk' program: +tops of the columns. This is done using the `BEGIN' pattern (*note +BEGIN/END::) so that the headers are only printed once, at the +beginning of the `awk' program: awk 'BEGIN { print "Name Number" print "---- ------" } @@ -4800,7 +4757,7 @@ be emphasized by storing it in a variable, like this: At this point, it would be a worthwhile exercise to use the `printf' statement to line up the headings and table data for the `inventory-shipped' example that was covered earlier in the minor node -on the `print' statement (*note The `print' Statement: Print.). +on the `print' statement (*note Print::). File: gawk.info, Node: Redirection, Next: Special Files, Prev: Printf, Up: Printing @@ -4889,12 +4846,11 @@ work identically for `printf': The message is built using string concatenation and saved in the variable `m'. It's then sent down the pipeline to the `mail' program. (The parentheses group the items to concatenate--see - *Note String Concatenation: Concatenation.) + *Note Concatenation::.) The `close' function is called here because it's a good idea to close the pipe as soon as all the intended output has been sent to - it. *Note Closing Input and Output Redirections: Close Files And - Pipes, for more information. + it. *Note Close Files And Pipes::, for more information. This example also illustrates the use of a variable to represent a FILE or COMMAND--it is not necessary to always use a string @@ -4910,8 +4866,7 @@ work identically for `printf': the `awk' program. This feature is a `gawk' extension, and is not available in POSIX - `awk'. *Note Two-Way Communications with Another Process: Two-way - I/O, for a more complete discussion. + `awk'. *Note Two-way I/O::, for a more complete discussion. Redirecting output using `>', `>>', `|', or `|&' asks the system to open a file, pipe, or coprocess only if the particular FILE or COMMAND @@ -4951,10 +4906,9 @@ all lowercase. The following program is both simple and efficient: END { close("sh") } The `tolower' function returns its argument string with all -uppercase characters converted to lowercase (*note String Manipulation -Functions: String Functions.). The program builds up a list of command -lines, using the `mv' utility to rename the files. It then sends the -list to the shell for execution. +uppercase characters converted to lowercase (*note String Functions::). +The program builds up a list of command lines, using the `mv' utility +to rename the files. It then sends the list to the shell for execution. File: gawk.info, Node: Special Files, Next: Close Files And Pipes, Prev: Redirection, Up: Printing @@ -4974,7 +4928,7 @@ descriptors, process-related information, and TCP/IP networking. * Special Caveats:: Things to watch out for. -File: gawk.info, Node: Special FD, Next: Special Process, Prev: Special Files, Up: Special Files +File: gawk.info, Node: Special FD, Next: Special Process, Up: Special Files Special Files for Standard Descriptors -------------------------------------- @@ -5049,9 +5003,8 @@ Special Files for Process-Related Information `gawk' also provides special file names that give access to information about the running `gawk' process. Each of these "files" provides a single record of information. To read them more than once, -they must first be closed with the `close' function (*note Closing -Input and Output Redirections: Close Files And Pipes.). The file names -are: +they must first be closed with the `close' function (*note Close Files +And Pipes::). The file names are: `/dev/pid' Reading this file returns the process ID of the current process, @@ -5098,8 +5051,7 @@ may not be used as source files with the `-f' option. are now considered obsolete and will disappear entirely in the next release of `gawk'. `gawk' prints a warning message every time you use one of these files. To obtain process-related information, use the -`PROCINFO' array. *Note Built-in Variables That Convey Information: -Auto-set. +`PROCINFO' array. *Note Auto-set::. File: gawk.info, Node: Special Network, Next: Special Caveats, Prev: Special Process, Up: Special Files @@ -5116,11 +5068,9 @@ is done using a special file name of the form: The PROTOCOL is one of `tcp', `udp', or `raw', and the other fields represent the other essential pieces of information for making a networking connection. These file names are used with the `|&' -operator for communicating with a coprocess (*note Two-Way -Communications with Another Process: Two-way I/O.). This is an -advanced feature, mentioned here only for completeness. Full -discussion is delayed until *Note Using `gawk' for Network Programming: -TCP/IP Networking. +operator for communicating with a coprocess (*note Two-way I/O::). +This is an advanced feature, mentioned here only for completeness. +Full discussion is delayed until *Note TCP/IP Networking::. File: gawk.info, Node: Special Caveats, Prev: Special Network, Up: Special Files @@ -5132,7 +5082,7 @@ Special File Name Caveats names that `gawk' provides: * Recognition of these special file names is disabled if `gawk' is in - compatibility mode (*note Command-Line Options: Options.). + compatibility mode (*note Options::). * The special files that provide process-related information are now considered obsolete and will disappear entirely in the next @@ -5165,11 +5115,10 @@ Closing Input and Output Redirections If the same file name or the same shell command is used with `getline' more than once during the execution of an `awk' program -(*note Explicit Input with `getline': Getline.), the file is opened (or -the command is executed) the first time only. At that time, the first -record of input is read from that file or command. The next time the -same file or command is used with `getline', another record is read -from it, and so on. +(*note Getline::), the file is opened (or the command is executed) the +first time only. At that time, the first record of input is read from +that file or command. The next time the same file or command is used +with `getline', another record is read from it, and so on. Similarly, when a file or pipe is opened for output, the file name or command associated with it is remembered by `awk', and subsequent @@ -5282,9 +5231,8 @@ to `close'. As in any other call to `close', the first argument is the name of the command or special file used to start the coprocess. The second argument should be a string, with either of the values `"to"' or `"from"'. Case does not matter. As this is an advanced feature, a -more complete discussion is delayed until *Note Two-Way Communications -with Another Process: Two-way I/O, which discusses it in more detail -and gives an example. +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 -------------------------------------------- @@ -5309,22 +5257,10 @@ the system's `close' or `fclose' C functions when closing input or output files, respectively. This value is zero if the close succeeds, or -1 if it fails. - The return value for closing a pipeline is particularly useful. It -allows you to get the output from a command as well as its exit status. - - For POSIX-compliant systems, if the exit status is a number above -128, then the program was terminated by a signal. Subtract 128 to get -the signal number: - - exit_val = close(command) - if (exit_val > 128) - print command, "died with signal", exit_val - 128 - else - print command, "exited with code", exit_val - - Currently, in `gawk', this only works for commands piping into -`getline'. For commands piped into from `print' or `printf', the -return value from `close' is that of the library's `pclose' function. + The POSIX standard is very vague; it says that `close' returns zero +on success and non-zero otherwise. In general, different +implementations vary in what they report when closing pipes; thus the +return value cannot be used portably. (d.c.) ---------- Footnotes ---------- @@ -5380,7 +5316,7 @@ operators. * Precedence:: How various operators nest. -File: gawk.info, Node: Constants, Next: Using Constant Regexps, Prev: Expressions, Up: Expressions +File: gawk.info, Node: Constants, Next: Using Constant Regexps, Up: Expressions Constant Expressions ==================== @@ -5400,7 +5336,7 @@ forms, but are stored identically internally. * Regexp Constants:: Regular Expression constants. -File: gawk.info, Node: Scalar Constants, Next: Nondecimal-numbers, Prev: Constants, Up: Constants +File: gawk.info, Node: Scalar Constants, Next: Nondecimal-numbers, Up: Constants Numeric and String Constants ---------------------------- @@ -5477,13 +5413,12 @@ of various sorts. program text. However, such numbers in the input data are not treated differently; doing so by default would break old programs. (If you really need to do this, use the `--non-decimal-data' command-line -option; *note Allowing Nondecimal Input Data: Nondecimal Data..) If -you have octal or hexadecimal data, you can use the `strtonum' function -(*note String Manipulation Functions: String Functions.) to convert -the data into a number. Most of the time, you will want to use octal -or hexadecimal constants when working with the built-in bit -manipulation functions; see *Note Using `gawk''s Bit Manipulation -Functions: Bitwise Functions, for more information. +option; *note Nondecimal Data::.) If you have octal or hexadecimal +data, you can use the `strtonum' function (*note String Functions::) to +convert the data into a number. Most of the time, you will want to use +octal or hexadecimal constants when working with the built-in bit +manipulation functions; see *Note Bitwise Functions::, for more +information. Unlike some early C implementations, `8' and `9' are not valid in octal constants; e.g., `gawk' treats `018' as decimal 18: @@ -5493,8 +5428,8 @@ octal constants; e.g., `gawk' treats `018' as decimal 18: -| 18 Octal and hexadecimal source code constants are a `gawk' extension. -If `gawk' is in compatibility mode (*note Command-Line Options: -Options.), they are not available. +If `gawk' is in compatibility mode (*note Options::), they are not +available. Advanced Notes: A Constant's Base Does Not Affect Its Value ----------------------------------------------------------- @@ -5530,8 +5465,8 @@ regexp constant merely stands for the regexp that is to be matched. However, regexp constants (such as `/foo/') may be used like simple expressions. When a regexp constant appears by itself, it has the same meaning as if it appeared in a pattern, i.e., `($0 ~ /foo/)' (d.c.) -*Note Expressions as Patterns: Expression Patterns. This means that -the following two code segments: +*Note Expression Patterns::. This means that the following two code +segments: if ($0 ~ /barfly/ || $0 ~ /camelot/) print "found" @@ -5566,12 +5501,12 @@ has never been well documented until the POSIX specification. Constant regular expressions are also used as the first argument for the `gensub', `sub', and `gsub' functions, and as the second argument -of the `match' function (*note String Manipulation Functions: String -Functions.). Modern implementations of `awk', including `gawk', allow -the third argument of `split' to be a regexp constant, but some older -implementations do not. (d.c.) This can lead to confusion when -attempting to use regexp constants as arguments to user-defined -functions (*note User-Defined Functions: User-defined.). For example: +of the `match' function (*note String Functions::). Modern +implementations of `awk', including `gawk', allow the third argument of +`split' to be a regexp constant, but some older implementations do not. +(d.c.) This can lead to confusion when attempting to use regexp +constants as arguments to user-defined functions (*note User-defined::). +For example: function mysub(pat, repl, str, global) { @@ -5616,7 +5551,7 @@ on the `awk' command line. advanced method of input. -File: gawk.info, Node: Using Variables, Next: Assignment Options, Prev: Variables, Up: Variables +File: gawk.info, Node: Using Variables, Next: Assignment Options, Up: Variables Using Variables in a Program ---------------------------- @@ -5630,7 +5565,7 @@ it may not begin with a digit. Case is significant in variable names; A variable name is a valid expression by itself; it represents the variable's current value. Variables are given new values with "assignment operators", "increment operators", and "decrement -operators". *Note Assignment Expressions: Assignment Ops. +operators". *Note Assignment Ops::. A few variables have special built-in meanings, such as `FS' (the field separator), and `NF' (the number of fields in the current input @@ -5655,8 +5590,7 @@ Assigning Variables on the Command Line Any `awk' variable can be set by including a "variable assignment" among the arguments on the command line when `awk' is invoked (*note -Other Command-Line Arguments: Other Arguments.). Such an assignment -has the following form: +Other Arguments::). Such an assignment has the following form: VARIABLE=TEXT @@ -5668,11 +5602,11 @@ option, as in the following: the variable is set at the very beginning, even before the `BEGIN' rules are run. The `-v' option and its assignment must precede all the -file name arguments, as well as the program text. (*Note Command-Line -Options: Options, for more information about the `-v' option.) -Otherwise, the variable assignment is performed at a time determined by -its position among the input file arguments--after the processing of the -preceding input file argument. For example: +file name arguments, as well as the program text. (*Note Options::, +for more information about the `-v' option.) Otherwise, the variable +assignment is performed at a time determined by its position among the +input file arguments--after the processing of the preceding input file +argument. For example: awk '{ print $n }' n=4 inventory-shipped n=2 BBS-list @@ -5692,9 +5626,9 @@ second field is printed in lines from `BBS-list': ... Command-line arguments are made available for explicit examination by -the `awk' program in the `ARGV' array (*note Using `ARGC' and `ARGV': -ARGC and ARGV.). `awk' processes the values of command-line -assignments for escape sequences (*note Escape Sequences::). (d.c.) +the `awk' program in the `ARGV' array (*note ARGC and ARGV::). `awk' +processes the values of command-line assignments for escape sequences +(*note Escape Sequences::). (d.c.) File: gawk.info, Node: Conversion, Next: Arithmetic Ops, Prev: Variables, Up: Expressions @@ -5728,8 +5662,7 @@ interpreted as valid numbers convert to zero. The exact manner in which numbers are converted into strings is controlled by the `awk' built-in variable `CONVFMT' (*note Built-in Variables::). Numbers are converted using the `sprintf' function with -`CONVFMT' as the format specifier (*note String Manipulation Functions: -String Functions.). +`CONVFMT' as the format specifier (*note String Functions::). `CONVFMT''s default value is `"%.6g"', which prints a value with at least six significant digits. For some applications, you might want to @@ -5760,8 +5693,41 @@ printing. Both `CONVFMT' and `OFMT' have the same default value: change their behavior. However, these semantics for `OFMT' are something to keep in mind if you must port your new style program to older implementations of `awk'. We recommend that instead of changing -your programs, just port `gawk' itself. *Note The `print' Statement: -Print, for more information on the `print' statement. +your programs, just port `gawk' itself. *Note Print::, for more +information on the `print' statement. + + Finally, once again, where you are can matter when it comes to +converting between numbers and strings. In *Note Locales::, we +mentioned that the local character set and language (the locale) can +affect how `gawk' matches characters. The locale also affects numeric +formats. In particular, for `awk' programs, it affects the decimal +point character. The `"C"' locale, and most English-language locales, +use the period character (`.') as the decimal point. However, many (if +not most) European and non-English locales use the comma (`,') as the +decimal point character. + + The POSIX standard says that `awk' always uses the period as the +decimal point when reading the `awk' program source code, and for +command-line variable assignments (*note Other Arguments::). However, +when interpreting input data, for `print' and `printf' output, and for +number to string conversion, the local decimal point character is used. +As of version 3.1.3, `gawk' fully complies with this aspect of the +standard. Here are some examples indicating the difference in behavior, +on a GNU/Linux system: + + $ gawk 'BEGIN { printf "%g\n", 3.1415927 }' + -| 3.14159 + $ LC_ALL=en_DK gawk 'BEGIN { printf "%g\n", 3.1415927 }' + -| 3,14159 + $ echo 4,321 | gawk '{ print $1 + 1 }' + -| 5 + $ echo 4,321 | LC_ALL=en_DK gawk '{ print $1 + 1 }' + -| 5,321 + +The `en_DK' locale is for English in Denmark, where the comma acts as +the decimal point separator. In the normal `"C"' locale, `gawk' treats +`4,321' as `4', while in the Danish locale, it's treated as the full +number, `4.321'. ---------- Footnotes ---------- @@ -5966,13 +5932,12 @@ if you ignore it, the assignment still makes itself felt through the alteration of the variable. We call this a "side effect". The lefthand operand of an assignment need not be a variable (*note -Variables::); it can also be a field (*note Changing the Contents of a -Field: Changing Fields.) or an array element (*note Arrays in `awk': -Arrays.). These are all called "lvalues", which means they can appear -on the lefthand side of an assignment operator. The righthand operand -may be any expression; it produces the new value that the assignment -stores in the specified variable, field, or array element. (Such values -are called "rvalues".) +Variables::); it can also be a field (*note Changing Fields::) or an +array element (*note Arrays::). These are all called "lvalues", which +means they can appear on the lefthand side of an assignment operator. +The righthand operand may be any expression; it produces the new value +that the assignment stores in the specified variable, field, or array +element. (Such values are called "rvalues".) It is important to note that variables do _not_ have permanent types. A variable's type is simply the type of whatever value it happens to @@ -6046,12 +6011,12 @@ righthand expression. For example: The indices of `bar' are practically guaranteed to be different, because `rand' returns different values each time it is called. (Arrays and -the `rand' function haven't been covered yet. *Note Arrays in `awk': -Arrays, and see *Note Numeric Functions::, for more information). This -example illustrates an important fact about assignment operators: the -lefthand expression is only evaluated _once_. It is up to the -implementation as to which expression is evaluated first, the lefthand -or the righthand. Consider this example: +the `rand' function haven't been covered yet. *Note Arrays::, and see +*Note Numeric Functions::, for more information). This example +illustrates an important fact about assignment operators: the lefthand +expression is only evaluated _once_. It is up to the implementation as +to which expression is evaluated first, the lefthand or the righthand. +Consider this example: i = 1 a[i += 2] = i + 1 @@ -6092,8 +6057,7 @@ A workaround is: awk '/[=]=/' /dev/null `gawk' does not have this problem, nor do the other freely available -versions described in *Note Other Freely Available `awk' -Implementations: Other Versions. +versions described in *Note Other Versions::. File: gawk.info, Node: Increment Ops, Next: Truth Values, Prev: Assignment Ops, Up: Expressions @@ -6314,8 +6278,7 @@ them: Comparison expressions have the value one if true and zero if false. When comparing operands of mixed types, numeric operands are converted -to strings using the value of `CONVFMT' (*note Conversion of Strings -and Numbers: Conversion.). +to strings using the value of `CONVFMT' (*note Conversion::). Strings are compared by comparing the first character of each, then the second character of each, and so on. Thus, `"10"' is less than @@ -6386,8 +6349,7 @@ I!"'. The righthand operand of the `~' and `!~' operators may be either a regexp constant (`/.../') or an ordinary expression. In the latter case, the value of the expression as a string is used as a dynamic -regexp (*note How to Use Regular Expressions: Regexp Usage.; also *note -Using Dynamic Regexps: Computed Regexps.). +regexp (*note Regexp Usage::; also *note Computed Regexps::). In modern implementations of `awk', a constant regular expression in slashes by itself is also an expression. The regexp `/REGEXP/' is an @@ -6397,8 +6359,7 @@ abbreviation for the following comparison expression: One special place where `/foo/' is _not_ an abbreviation for `$0 ~ /foo/' is when it is the righthand operand of `~' or `!~'. *Note Using -Regular Expression Constants: Using Constant Regexps, where this is -discussed in more detail. +Constant Regexps::, where this is discussed in more detail. ---------- Footnotes ---------- @@ -6421,10 +6382,9 @@ also referred to as "logical expressions". The terms are equivalent. Boolean expressions can be used wherever comparison and matching expressions can be used. They can be used in `if', `while', `do', and -`for' statements (*note Control Statements in Actions: Statements.). -They have numeric values (one if true, zero if false) that come into -play if the result of the Boolean expression is stored in a variable or -used in arithmetic. +`for' statements (*note Statements::). They have numeric values (one +if true, zero if false) that come into play if the result of the +Boolean expression is stored in a variable or used in arithmetic. In addition, every Boolean expression is also a valid pattern, so you can use one as a pattern to control the execution of rules. The @@ -6462,8 +6422,7 @@ Boolean operators are: BEGIN { if (! ("HOME" in ENVIRON)) print "no home!" } - (The `in' operator is described in *Note Referring to an Array - Element: Reference to Elements.) + (The `in' operator is described in *Note Reference to Elements::.) The `&&' and `||' operators are called "short-circuit" operators because of the way they work. Evaluation of the full expression is @@ -6472,8 +6431,8 @@ evaluation. Statements that use `&&' or `||' can be continued simply by putting a newline after them. But you cannot put a newline in front of either -of these operators without using backslash continuation (*note `awk' -Statements Versus Lines: Statements/Lines.). +of these operators without using backslash continuation (*note +Statements/Lines::). The actual value of an expression using the `!' operator is either one or zero, depending upon the truth value of the expression it is @@ -6493,11 +6452,10 @@ using `!'. The next rule prints lines as long as `interested' is true. When a line is seen whose first field is `END', `interested' is toggled back to false. - *Note:* The `next' statement is discussed in *Note The `next' -Statement: Next Statement. `next' tells `awk' to skip the rest of the -rules, get the next record, and start processing the rules over again -at the top. The reason it's there is to avoid printing the bracketing -`START' and `END' lines. + *Note:* The `next' statement is discussed in *Note Next Statement::. +`next' tells `awk' to skip the rest of the rules, get the next record, +and start processing the rules over again at the top. The reason it's +there is to avoid printing the bracketing `START' and `END' lines. File: gawk.info, Node: Conditional Exp, Next: Function Calls, Prev: Boolean Ops, Up: Expressions @@ -6531,14 +6489,13 @@ array `b', and increments `i': This is guaranteed to increment `i' exactly once, because each time only one of the two increment expressions is executed and the other is -not. *Note Arrays in `awk': Arrays, for more information about arrays. +not. *Note Arrays::, for more information about arrays. As a minor `gawk' extension, a statement that uses `?:' can be continued simply by putting a newline after either character. However, putting a newline in front of either character does not work without -using backslash continuation (*note `awk' Statements Versus Lines: -Statements/Lines.). If `--posix' is specified (*note Command-Line -Options: Options.), then this extension is disabled. +using backslash continuation (*note Statements/Lines::). If `--posix' +is specified (*note Options::), then this extension is disabled. File: gawk.info, Node: Function Calls, Next: Precedence, Prev: Conditional Exp, Up: Expressions @@ -6552,10 +6509,9 @@ the function `sqrt' computes the square root of a number. A fixed set of functions are "built-in", which means they are available in every `awk' program. The `sqrt' function is one of these. -*Note Built-in Functions: Built-in, for a list of built-in functions -and their descriptions. In addition, you can define functions for use -in your program. *Note User-Defined Functions: User-defined, for -instructions on how to do this. +*Note Built-in::, for a list of built-in functions and their +descriptions. In addition, you can define functions for use in your +program. *Note User-defined::, for instructions on how to do this. The way to use a function is with a "function call" expression, which consists of the function name followed immediately by a list of @@ -6585,10 +6541,10 @@ square root: Some of the built-in functions have one or more optional arguments. If those arguments are not supplied, the functions use a reasonable -default value. *Note Built-in Functions: Built-in, for full details. -If arguments are omitted in calls to user-defined functions, then those -arguments are treated as local variables and initialized to the empty -string (*note User-Defined Functions: User-defined.). +default value. *Note Built-in::, for full details. If arguments are +omitted in calls to user-defined functions, then those arguments are +treated as local variables and initialized to the empty string (*note +User-defined::). Like every other expression, the function call has a value, which is computed by the function based on the arguments you give it. In this @@ -6664,8 +6620,7 @@ presents `awk''s operators, in order of highest to lowest precedence: `String Concatenation' No special symbol is used to indicate concatenation. The operands - are simply written side by side (*note String Concatenation: - Concatenation.). + are simply written side by side (*note Concatenation::). `< <= == !=' `> >= >> | |&' @@ -6731,7 +6686,7 @@ top of. Now it's time to start building something useful. * Built-in Variables:: Summarizes the built-in variables. -File: gawk.info, Node: Pattern Overview, Next: Using Shell Variables, Prev: Patterns and Actions, Up: Patterns and Actions +File: gawk.info, Node: Pattern Overview, Next: Using Shell Variables, Up: Patterns and Actions Pattern Elements ================ @@ -6750,31 +6705,27 @@ summary of the types of `awk' patterns: `/REGULAR EXPRESSION/' A regular expression. It matches when the text of the input record - fits the regular expression. (*Note Regular Expressions: Regexp.) + fits the regular expression. (*Note Regexp::.) `EXPRESSION' A single expression. It matches when its value is nonzero (if a - number) or non-null (if a string). (*Note Expressions as - Patterns: Expression Patterns.) + number) or non-null (if a string). (*Note Expression Patterns::.) `PAT1, PAT2' A pair of patterns separated by a comma, specifying a range of records. The range includes both the initial record that matches - PAT1 and the final record that matches PAT2. (*Note Specifying - Record Ranges with Patterns: Ranges.) + PAT1 and the final record that matches PAT2. (*Note Ranges::.) `BEGIN' `END' Special patterns for you to supply startup or cleanup actions for - your `awk' program. (*Note The `BEGIN' and `END' Special - Patterns: BEGIN/END.) + your `awk' program. (*Note BEGIN/END::.) `EMPTY' - The empty pattern matches every input record. (*Note The Empty - Pattern: Empty.) + The empty pattern matches every input record. (*Note Empty::.) -File: gawk.info, Node: Regexp Patterns, Next: Expression Patterns, Prev: Pattern Overview, Up: Pattern Overview +File: gawk.info, Node: Regexp Patterns, Next: Expression Patterns, Up: Pattern Overview Regular Expressions as Patterns ------------------------------- @@ -6802,14 +6753,14 @@ otherwise, it depends on only what has happened so far in the execution of the `awk' program. Comparison expressions, using the comparison operators described in -*Note Variable Typing and Comparison Expressions: Typing and Comparison, -are a very common kind of pattern. Regexp matching and nonmatching are -also very common expressions. The left operand of the `~' and `!~' -operators is a string. The right operand is either a constant regular -expression enclosed in slashes (`/REGEXP/'), or any expression whose -string value is used as a dynamic regular expression (*note Using -Dynamic Regexps: Computed Regexps.). The following example prints the -second field of each input record whose first field is precisely `foo': +*Note Typing and Comparison::, are a very common kind of pattern. +Regexp matching and nonmatching are also very common expressions. The +left operand of the `~' and `!~' operators is a string. The right +operand is either a constant regular expression enclosed in slashes +(`/REGEXP/'), or any expression whose string value is used as a dynamic +regular expression (*note Computed Regexps::). The following example +prints the second field of each input record whose first field is +precisely `foo': $ awk '$1 == "foo" { print $2 }' BBS-list @@ -6903,10 +6854,9 @@ executed for just that record. For example, suppose there is text between two identical markers (e.g., the `%' symbol), each on its own line, that should be ignored. A first attempt would be to combine a range pattern that describes the delimited text with the `next' -statement (not discussed yet, *note The `next' Statement: Next -Statement.). This causes `awk' to skip any further processing of the -current record and start over again with the next input record. Such a -program looks like this: +statement (not discussed yet, *note Next Statement::). This causes +`awk' to skip any further processing of the current record and start +over again with the next input record. Such a program looks like this: /^%$/,/^%$/ { next } { print } @@ -6955,7 +6905,7 @@ rules are often referred to as "`BEGIN' and `END' blocks" by long-time * I/O And BEGIN/END:: I/O issues in BEGIN/END rules. -File: gawk.info, Node: Using BEGIN/END, Next: I/O And BEGIN/END, Prev: BEGIN/END, Up: BEGIN/END +File: gawk.info, Node: Using BEGIN/END, Next: I/O And BEGIN/END, Up: BEGIN/END Startup and Cleanup Actions ........................... @@ -6998,10 +6948,9 @@ functions, because each library file can have its own `BEGIN' and/or which library functions are named on the command line controls the order in which their `BEGIN' and `END' rules are executed. Therefore, you have to be careful when writing such rules in library files so that -the order in which they are executed doesn't matter. *Note -Command-Line Options: Options, for more information on using library -functions. *Note A Library of `awk' Functions: Library Functions, for -a number of useful library functions. +the order in which they are executed doesn't matter. *Note Options::, +for more information on using library functions. *Note Library +Functions::, for a number of useful library functions. If an `awk' program has only a `BEGIN' rule and no other rules, then the program exits after the `BEGIN' rule is run.(1) However, if an @@ -7027,8 +6976,8 @@ any input is read, there simply is no input record, and therefore no fields, when executing `BEGIN' rules. References to `$0' and the fields yield a null string or zero, depending upon the context. One way to give `$0' a real value is to execute a `getline' command without a -variable (*note Explicit Input with `getline': Getline.). Another way -is simply to assign a value to `$0'. +variable (*note Getline::). Another way is simply to assign a value to +`$0'. The second point is similar to the first but from the other direction. Traditionally, due largely to implementation issues, `$0' @@ -7054,8 +7003,8 @@ explicitly. `BEGIN' rule, because the implicit read-a-record-and-match-against-the-rules loop has not started yet. Similarly, those statements are not valid in an `END' rule, since all -the input has been read. (*Note The `next' Statement: Next Statement, -and see *Note Using `gawk''s `nextfile' Statement: Nextfile Statement.) +the input has been read. (*Note Next Statement::, and see *Note +Nextfile Statement::.) File: gawk.info, Node: Empty, Prev: BEGIN/END, Up: Pattern Overview @@ -7098,14 +7047,13 @@ inside the quotes. The second part is single-quoted. Variable substitution via quoting works, but can be potentially messy. It requires a good understanding of the shell's quoting rules -(*note Shell Quoting Issues: Quoting.), and it's often difficult to -correctly match up the quotes when reading the program. +(*note Quoting::), and it's often difficult to correctly match up the +quotes when reading the program. A better method is to use `awk''s variable assignment feature (*note -Assigning Variables on the Command Line: Assignment Options.) to -assign the shell variable's value to an `awk' variable's value. Then -use dynamic regexps to match the pattern (*note Using Dynamic Regexps: -Computed Regexps.). The following shows how to redo the previous +Assignment Options::) to assign the shell variable's value to an `awk' +variable's value. Then use dynamic regexps to match the pattern (*note +Computed Regexps::). The following shows how to redo the previous example using this technique: echo -n "Enter search pattern: " @@ -7130,11 +7078,10 @@ Actions An `awk' program or script consists of a series of rules and function definitions interspersed. (Functions are described later. -*Note User-Defined Functions: User-defined.) A rule contains a pattern -and an action, either of which (but not both) may be omitted. The -purpose of the "action" is to tell `awk' what to do once a match for -the pattern is found. Thus, in outline, an `awk' program generally -looks like this: +*Note User-defined::.) A rule contains a pattern and an action, either +of which (but not both) may be omitted. The purpose of the "action" is +to tell `awk' what to do once a match for the pattern is found. Thus, +in outline, an `awk' program generally looks like this: [PATTERN] [{ ACTION }] [PATTERN] [{ ACTION }] @@ -7159,13 +7106,12 @@ Expressions Call functions or assign values to variables (*note Expressions::). Executing this kind of statement simply computes the value of the expression. This is useful when the expression - has side effects (*note Assignment Expressions: Assignment Ops.). + has side effects (*note Assignment Ops::). Control statements Specify the control flow of `awk' programs. The `awk' language gives you C-like constructs (`if', `for', `while', and `do') as - well as a few special ones (*note Control Statements in Actions: - Statements.). + well as a few special ones (*note Statements::). Compound statements Consist of one or more statements enclosed in curly braces. A @@ -7173,17 +7119,15 @@ Compound statements together in the body of an `if', `while', `do', or `for' statement. Input statements - Use the `getline' command (*note Explicit Input with `getline': - Getline.). Also supplied in `awk' are the `next' statement (*note - The `next' Statement: Next Statement.), and the `nextfile' - statement (*note Using `gawk''s `nextfile' Statement: Nextfile - Statement.). + Use the `getline' command (*note Getline::). Also supplied in + `awk' are the `next' statement (*note Next Statement::), and the + `nextfile' statement (*note Nextfile Statement::). Output statements - Such as `print' and `printf'. *Note Printing Output: Printing. + Such as `print' and `printf'. *Note Printing::. Deletion statements - For deleting array elements. *Note The `delete' Statement: Delete. + For deleting array elements. *Note Delete::. File: gawk.info, Node: Statements, Next: Built-in Variables, Prev: Action Overview, Up: Patterns and Actions @@ -7212,6 +7156,8 @@ with curly braces, separating them with newlines or semicolons. condition is satisfied. * For Statement:: Another looping statement, that provides initialization and increment clauses. +* Switch Statement:: Switch/case evaluation for conditional + execution of statements based on a value. * Break Statement:: Immediately exit the innermost enclosing loop. * Continue Statement:: Skip to the end of the innermost enclosing loop. @@ -7220,7 +7166,7 @@ with curly braces, separating them with newlines or semicolons. * Exit Statement:: Stop execution of `awk'. -File: gawk.info, Node: If Statement, Next: While Statement, Prev: Statements, Up: Statements +File: gawk.info, Node: If Statement, Next: While Statement, Up: Statements The `if'-`else' Statement ------------------------- @@ -7342,7 +7288,7 @@ just as well. This situation reflects actual experience; only occasionally is there a real use for a `do' statement. -File: gawk.info, Node: For Statement, Next: Break Statement, Prev: Do Statement, Up: Statements +File: gawk.info, Node: For Statement, Next: Switch Statement, Prev: Do Statement, Up: Statements The `for' Statement ------------------- @@ -7404,10 +7350,10 @@ as shown here: INCREMENT } -The only exception is when the `continue' statement (*note The -`continue' Statement: Continue Statement.) is used inside the loop. -Changing a `for' statement to a `while' statement in this way can -change the effect of the `continue' statement inside the loop. +The only exception is when the `continue' statement (*note Continue +Statement::) is used inside the loop. Changing a `for' statement to a +`while' statement in this way can change the effect of the `continue' +statement inside the loop. The `awk' language has a `for' statement in addition to a `while' statement because a `for' loop is often both less work to type and more @@ -7421,11 +7367,65 @@ all the indices of an array: for (i in array) DO SOMETHING WITH array[i] -*Note Scanning All Elements of an Array: Scanning an Array, for more -information on this version of the `for' loop. +*Note Scanning an Array::, for more information on this version of the +`for' loop. -File: gawk.info, Node: Break Statement, Next: Continue Statement, Prev: For Statement, Up: Statements +File: gawk.info, Node: Switch Statement, Next: Break Statement, Prev: For Statement, Up: Statements + +The `switch' Statement +---------------------- + + *NOTE:* This node describes an experimental feature added in `gawk' +3.1.3. It is _not_ enabled by default. To enable it, use the +`--enable-switch' option to `configure' when `gawk' is being configured +and built. *Note Additional Configuration Options::, for more +information. + + The `switch' statement allows the evaluation of an expression and +the execution of statements based on a `case' match. Case statements +are checked for a match in the order they are defined. If no suitable +`case' is found, the `default' section is executed, if supplied. The +general form of the `switch' statement looks like this: + + switch (EXPRESSION) { + case VALUE OR REGULAR EXPRESSION: + CASE-BODY + default: + DEFAULT-BODY + } + + The `switch' statement works as it does in C. Once a match to a given +case is made, case statement bodies are executed until a `break', +`continue', `next', `nextfile' or `exit' is encountered, or the end of +the `switch' statement itself. For example: + + switch (NR * 2 + 1) { + case 3: + case "11": + print NR - 1 + break + + case /2[[:digit:]]+/: + print NR + + default: + print NR + 1 + + case -1: + print NR * -1 + } + + Note that if none of the statements specified above halt execution +of a matched `case' statement, execution falls through to the next +`case' until execution halts. In the above example, for any case value +starting with `2' followed by one or more digits, the `print' statement +is executed and then falls through into the `default' section, +executing its `print' statement. In turn, the -1 case will also be +executed since the `default' does not halt execution. + + +File: gawk.info, Node: Break Statement, Next: Continue Statement, Prev: Switch Statement, Up: Statements The `break' Statement --------------------- @@ -7450,8 +7450,8 @@ divisor of any integer, and also identifies prime numbers: immediately "breaks out" of the containing `for' loop. This means that `awk' proceeds immediately to the statement following the loop and continues processing. (This is very different from the `exit' -statement, which stops the entire `awk' program. *Note The `exit' -Statement: Exit Statement.) +statement, which stops the entire `awk' program. *Note Exit +Statement::.) Th following program illustrates how the CONDITION of a `for' or `while' statement could be replaced with a `break' inside an `if': @@ -7474,13 +7474,12 @@ Statement: Exit Statement.) The `break' statement has no meaning when used outside the body of a loop. However, although it was never documented, historical implementations of `awk' treated the `break' statement outside of a -loop as if it were a `next' statement (*note The `next' Statement: Next -Statement.). Recent versions of Unix `awk' no longer allow this usage. -`gawk' supports this use of `break' only if `--traditional' has been -specified on the command line (*note Command-Line Options: Options.). -Otherwise, it is treated as an error, since the POSIX standard -specifies that `break' should only be used inside the body of a loop. -(d.c.) +loop as if it were a `next' statement (*note Next Statement::). Recent +versions of Unix `awk' no longer allow this usage. `gawk' supports +this use of `break' only if `--traditional' has been specified on the +command line (*note Options::). Otherwise, it is treated as an error, +since the POSIX standard specifies that `break' should only be used +inside the body of a loop. (d.c.) File: gawk.info, Node: Continue Statement, Next: Next Statement, Prev: Break Statement, Up: Statements @@ -7528,12 +7527,12 @@ This program loops forever once `x' reaches 5. The `continue' statement has no meaning when used outside the body of a loop. Historical versions of `awk' treated a `continue' statement outside a loop the same way they treated a `break' statement outside a -loop: as if it were a `next' statement (*note The `next' Statement: -Next Statement.). Recent versions of Unix `awk' no longer work this -way, and `gawk' allows it only if `--traditional' is specified on the -command line (*note Command-Line Options: Options.). Just like the -`break' statement, the POSIX standard specifies that `continue' should -only be used inside the body of a loop. (d.c.) +loop: as if it were a `next' statement (*note Next Statement::). +Recent versions of Unix `awk' no longer work this way, and `gawk' +allows it only if `--traditional' is specified on the command line +(*note Options::). Just like the `break' statement, the POSIX standard +specifies that `continue' should only be used inside the body of a loop. +(d.c.) File: gawk.info, Node: Next Statement, Next: Nextfile Statement, Prev: Continue Statement, Up: Statements @@ -7547,10 +7546,9 @@ further rules are executed for the current record, and the rest of the current rule's action isn't executed. Contrast this with the effect of the `getline' function (*note -Explicit Input with `getline': Getline.). That also causes `awk' to -read the next record immediately, but it does not alter the flow of -control in any way (i.e., the rest of the current action executes with -a new input record). +Getline::). That also causes `awk' to read the next record +immediately, but it does not alter the flow of control in any way +(i.e., the rest of the current action executes with a new input record). At the highest level, `awk' program execution is a loop that reads an input record and then tests each rule's pattern against it. If you @@ -7573,18 +7571,17 @@ beginning, in the following manner: Because of the `next' statement, the program's subsequent rules won't see the bad record. The error message is redirected to the standard error output stream, as error messages should be. For more detail see -*Note Special File Names in `gawk': Special Files. +*Note Special Files::. According to the POSIX standard, the behavior is undefined if the `next' statement is used in a `BEGIN' or `END' rule. `gawk' treats it as a syntax error. Although POSIX permits it, some other `awk' implementations don't allow the `next' statement inside function bodies -(*note User-Defined Functions: User-defined.). Just as with any other -`next' statement, a `next' statement inside a function body reads the -next record and starts processing it with the first rule in the program. -If the `next' statement causes the end of the input to be reached, then -the code in any `END' rules is executed. *Note The `BEGIN' and `END' -Special Patterns: BEGIN/END. +(*note User-defined::). Just as with any other `next' statement, a +`next' statement inside a function body reads the next record and +starts processing it with the first rule in the program. If the `next' +statement causes the end of the input to be reached, then the code in +any `END' rules is executed. *Note BEGIN/END::. File: gawk.info, Node: Nextfile Statement, Next: Exit Statement, Prev: Next Statement, Up: Statements @@ -7599,7 +7596,7 @@ processing the current data file. The `nextfile' statement is a `gawk' extension. In most other `awk' implementations, or if `gawk' is in compatibility mode (*note -Command-Line Options: Options.), `nextfile' is not special. +Options::), `nextfile' is not special. Upon execution of the `nextfile' statement, `FILENAME' is updated to the name of the next data file listed on the command line, `FNR' is @@ -7607,7 +7604,7 @@ reset to one, `ARGIND' is incremented, and processing starts over with the first rule in the program. (`ARGIND' hasn't been introduced yet. *Note Built-in Variables::.) If the `nextfile' statement causes the end of the input to be reached, then the code in any `END' rules is -executed. *Note The `BEGIN' and `END' Special Patterns: BEGIN/END. +executed. *Note BEGIN/END::. The `nextfile' statement is useful when there are many data files to process but it isn't necessary to process every record in every file. @@ -7622,17 +7619,15 @@ not related to the main processing that `awk' does with the files listed in `ARGV'. If it's necessary to use an `awk' version that doesn't support -`nextfile', see *Note Implementing `nextfile' as a Function: Nextfile -Function, for a user-defined function that simulates the `nextfile' -statement. +`nextfile', see *Note Nextfile Function::, for a user-defined function +that simulates the `nextfile' statement. The current version of the Bell Laboratories `awk' (*note Other -Freely Available `awk' Implementations: Other Versions.) also supports -`nextfile'. However, it doesn't allow the `nextfile' statement inside -function bodies (*note User-Defined Functions: User-defined.). `gawk' -does; a `nextfile' inside a function body reads the next record and -starts processing it with the first rule in the program, just as any -other `nextfile' statement. +Versions::) also supports `nextfile'. However, it doesn't allow the +`nextfile' statement inside function bodies (*note User-defined::). +`gawk' does; a `nextfile' inside a function body reads the next record +and starts processing it with the first rule in the program, just as +any other `nextfile' statement. *Caution:* Versions of `gawk' prior to 3.0 used two words (`next file') for the `nextfile' statement. In version 3.0, this was changed @@ -7656,9 +7651,9 @@ ignored. The `exit' statement is written as follows: When an `exit' statement is executed from a `BEGIN' rule, the program stops processing everything immediately. No input records are read. However, if an `END' rule is present, as part of executing the -`exit' statement, the `END' rule is executed (*note The `BEGIN' and -`END' Special Patterns: BEGIN/END.). If `exit' is used as part of an -`END' rule, it causes the program to stop immediately. +`exit' statement, the `END' rule is executed (*note BEGIN/END::). If +`exit' is used as part of an `END' rule, it causes the program to stop +immediately. An `exit' statement that is not part of a `BEGIN' or `END' rule stops the execution of any further automatic rules for the current @@ -7667,8 +7662,8 @@ record, skips reading any remaining input records, and executes the In such a case, if you don't want the `END' rule to do its job, set a variable to nonzero before the `exit' statement and check that -variable in the `END' rule. *Note Assertions: Assert Function, for an -example that does this. +variable in the `END' rule. *Note Assert Function::, for an example +that does this. If an argument is supplied to `exit', its value is used as the exit status code for the `awk' process. If no argument is supplied, `exit' @@ -7719,7 +7714,7 @@ activity. * ARGC and ARGV:: Ways to use `ARGC' and `ARGV'. -File: gawk.info, Node: User-modified, Next: Auto-set, Prev: Built-in Variables, Up: Built-in Variables +File: gawk.info, Node: User-modified, Next: Auto-set, Up: Built-in Variables Built-in Variables That Control `awk' ------------------------------------- @@ -7737,20 +7732,17 @@ specific to `gawk' are marked with a pound sign (`#'). use binary I/O. A string value of `"rw"' or `"wr"' indicates that all files should use binary I/O. Any other string value is equivalent to `"rw"', but `gawk' generates a warning message. - `BINMODE' is described in more detail in *Note Using `gawk' on PC - Operating Systems: PC Using. + `BINMODE' is described in more detail in *Note PC Using::. This variable is a `gawk' extension. In other `awk' - implementations (except `mawk', *note Other Freely Available `awk' - Implementations: Other Versions.), or if `gawk' is in - compatibility mode (*note Command-Line Options: Options.), it is - not special. + implementations (except `mawk', *note Other Versions::), or if + `gawk' is in compatibility mode (*note Options::), it is not + special. `CONVFMT' This string controls conversion of numbers to strings (*note - Conversion of Strings and Numbers: Conversion.). It works by - being passed, in effect, as the first argument to the `sprintf' - function (*note String Manipulation Functions: String Functions.). + Conversion::). It works by being passed, in effect, as the first + argument to the `sprintf' function (*note String Functions::). Its default value is `"%.6g"'. `CONVFMT' was introduced by the POSIX standard. @@ -7758,22 +7750,20 @@ specific to `gawk' are marked with a pound sign (`#'). This is a space-separated list of columns that tells `gawk' how to split input with fixed columnar boundaries. Assigning a value to `FIELDWIDTHS' overrides the use of `FS' for field splitting. - *Note Reading Fixed-Width Data: Constant Size, for more - information. + *Note Constant Size::, for more information. - If `gawk' is in compatibility mode (*note Command-Line Options: - Options.), then `FIELDWIDTHS' has no special meaning, and - field-splitting operations occur based exclusively on the value of - `FS'. + If `gawk' is in compatibility mode (*note Options::), then + `FIELDWIDTHS' has no special meaning, and field-splitting + operations occur based exclusively on the value of `FS'. `FS' - This is the input field separator (*note Specifying How Fields Are - Separated: Field Separators.). The value is a single-character - string or a multi-character regular expression that matches the - separations between fields in an input record. If the value is - the null string (`""'), then each character in the record becomes - a separate field. (This behavior is a `gawk' extension. POSIX - `awk' does not specify the behavior when `FS' is the null string.) + This is the input field separator (*note Field Separators::). The + value is a single-character string or a multi-character regular + expression that matches the separations between fields in an input + record. If the value is the null string (`""'), then each + character in the record becomes a separate field. (This behavior + is a `gawk' extension. POSIX `awk' does not specify the behavior + when `FS' is the null string.) The default value is `" "', a string consisting of a single space. As a special exception, this value means that any sequence of @@ -7800,22 +7790,20 @@ specific to `gawk' are marked with a pound sign (`#'). case when doing their particular regexp operations. However, the value of `IGNORECASE' does _not_ affect array subscripting and it does not affect field splitting when using a single-character - field separator. *Note Case Sensitivity in Matching: - Case-sensitivity. + field separator. *Note Case-sensitivity::. - If `gawk' is in compatibility mode (*note Command-Line Options: - Options.), then `IGNORECASE' has no special meaning. Thus, string - and regexp operations are always case-sensitive. + If `gawk' is in compatibility mode (*note Options::), then + `IGNORECASE' has no special meaning. Thus, string and regexp + operations are always case-sensitive. `LINT #' When this variable is true (nonzero or non-null), `gawk' behaves as if the `--lint' command-line option is in effect. (*note - Command-Line Options: Options.). With a value of `"fatal"', lint - warnings become fatal errors. With a value of `"invalid"', only - warnings about things that are actually invalid are issued. (This - is not fully implemented yet.) Any other true value prints - nonfatal warnings. Assigning a false value to `LINT' turns off - the lint warnings. + Options::). With a value of `"fatal"', lint warnings become fatal + errors. With a value of `"invalid"', only warnings about things + that are actually invalid are issued. (This is not fully + implemented yet.) Any other true value prints nonfatal warnings. + Assigning a false value to `LINT' turns off the lint warnings. This variable is a `gawk' extension. It is not special in other `awk' implementations. Unlike the other special variables, @@ -7827,10 +7815,9 @@ specific to `gawk' are marked with a pound sign (`#'). `OFMT' This string controls conversion of numbers to strings (*note - Conversion of Strings and Numbers: Conversion.) for printing with - the `print' statement. It works by being passed as the first - argument to the `sprintf' function (*note String Manipulation - Functions: String Functions.). Its default value is `"%.6g"'. + Conversion::) for printing with the `print' statement. It works + by being passed as the first argument to the `sprintf' function + (*note String Functions::). Its default value is `"%.6g"'. Earlier versions of `awk' also used `OFMT' to specify the format for converting numbers to strings in general expressions; this is now done by `CONVFMT'. @@ -7851,32 +7838,30 @@ specific to `gawk' are marked with a pound sign (`#'). input record consists of a single line of text. It can also be the null string, in which case records are separated by runs of blank lines. If it is a regexp, records are separated by matches - of the regexp in the input text. (*Note How Input Is Split into - Records: Records.) + of the regexp in the input text. (*Note Records::.) The ability for `RS' to be a regular expression is a `gawk' extension. In most other `awk' implementations, or if `gawk' is - in compatibility mode (*note Command-Line Options: Options.), just - the first character of `RS''s value is used. + in compatibility mode (*note Options::), just the first character + of `RS''s value is used. `SUBSEP' This is the subscript separator. It has the default value of `"\034"' and is used to separate the parts of the indices of a multidimensional array. Thus, the expression `foo["A", "B"]' - really accesses `foo["A\034B"]' (*note Multidimensional Arrays: - Multi-dimensional.). + really accesses `foo["A\034B"]' (*note Multi-dimensional::). `TEXTDOMAIN #' This variable is used for internationalization of programs at the `awk' level. It sets the default text domain for specially marked string constants in the source text, as well as for the `dcgettext', `dcngettext' and `bindtextdomain' functions (*note - Internationalization with `gawk': Internationalization.). The - default value of `TEXTDOMAIN' is `"messages"'. + Internationalization::). The default value of `TEXTDOMAIN' is + `"messages"'. This variable is a `gawk' extension. In other `awk' implementations, or if `gawk' is in compatibility mode (*note - Command-Line Options: Options.), it is not special. + Options::), it is not special. ---------- Footnotes ---------- @@ -7896,9 +7881,9 @@ with a pound sign (`#'). `ARGC, ARGV' The command-line arguments available to `awk' programs are stored in an array called `ARGV'. `ARGC' is the number of command-line - arguments present. *Note Other Command-Line Arguments: Other - Arguments. Unlike most `awk' arrays, `ARGV' is indexed from 0 to - `ARGC' - 1. In the following example: + arguments present. *Note Other Arguments::. Unlike most `awk' + arrays, `ARGV' is indexed from 0 to `ARGC' - 1. In the following + example: $ awk 'BEGIN { > for (i = 0; i < ARGC; i++) @@ -7919,9 +7904,8 @@ with a pound sign (`#'). The value of `ARGV[0]' can vary from system to system. Also, you should note that the program text is _not_ included in `ARGV', nor - are any of `awk''s command-line options. *Note Using `ARGC' and - `ARGV': ARGC and ARGV, for information about how `awk' uses these - variables. + are any of `awk''s command-line options. *Note ARGC and ARGV::, + for information about how `awk' uses these variables. `ARGIND #' The index in `ARGV' of the current file being processed. Every @@ -7941,7 +7925,7 @@ with a pound sign (`#'). This variable is a `gawk' extension. In other `awk' implementations, or if `gawk' is in compatibility mode (*note - Command-Line Options: Options.), it is not special. + Options::), it is not special. `ENVIRON' An associative array that contains the values of the environment. @@ -7953,8 +7937,7 @@ with a pound sign (`#'). Some operating systems may not have environment variables. On such systems, the `ENVIRON' array is empty (except for - `ENVIRON["AWKPATH"]', *note The `AWKPATH' Environment Variable: - AWKPATH Variable.). + `ENVIRON["AWKPATH"]', *note AWKPATH Variable::). `ERRNO #' If a system error occurs during a redirection for `getline', @@ -7963,41 +7946,38 @@ with a pound sign (`#'). This variable is a `gawk' extension. In other `awk' implementations, or if `gawk' is in compatibility mode (*note - Command-Line Options: Options.), it is not special. + Options::), it is not special. `FILENAME' The name of the file that `awk' is currently reading. When no data files are listed on the command line, `awk' reads from the standard input and `FILENAME' is set to `"-"'. `FILENAME' is - changed each time a new file is read (*note Reading Input Files: - Reading Files.). Inside a `BEGIN' rule, the value of `FILENAME' is - `""', since there are no input files being processed yet.(1) - (d.c.) Note, though, that using `getline' (*note Explicit Input - with `getline': Getline.) inside a `BEGIN' rule can give - `FILENAME' a value. + changed each time a new file is read (*note Reading Files::). + Inside a `BEGIN' rule, the value of `FILENAME' is `""', since + there are no input files being processed yet.(1) (d.c.) Note, + though, that using `getline' (*note Getline::) inside a `BEGIN' + rule can give `FILENAME' a value. `FNR' The current record number in the current file. `FNR' is - incremented each time a new record is read (*note Explicit Input - with `getline': Getline.). It is reinitialized to zero each time - a new input file is started. + incremented each time a new record is read (*note Getline::). It + is reinitialized to zero each time a new input file is started. `NF' The number of fields in the current input record. `NF' is set each time a new record is read, when a new field is created or - when `$0' changes (*note Examining Fields: Fields.). + when `$0' changes (*note Fields::). Unlike most of the variables described in this node, assigning a value to `NF' has the potential to affect `awk''s internal workings. In particular, assignments to `NF' can be used to create or remove fields from the current record: *Note Changing - the Contents of a Field: Changing Fields. + Fields::. `NR' The number of input records `awk' has processed since the - beginning of the program's execution (*note How Input Is Split - into Records: Records.). `NR' is incremented each time a new - record is read. + beginning of the program's execution (*note Records::). `NR' is + incremented each time a new record is read. `PROCINFO #' The elements of this array provide access to information about the @@ -8033,25 +8013,24 @@ with a pound sign (`#'). 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 Referring to an Array Element: Reference to - Elements.). + these elements (*note Reference to Elements::). This array is a `gawk' extension. In other `awk' implementations, - or if `gawk' is in compatibility mode (*note Command-Line Options: - Options.), it is not special. + or if `gawk' is in compatibility mode (*note Options::), it is not + special. `RLENGTH' The length of the substring matched by the `match' function (*note - String Manipulation Functions: String Functions.). `RLENGTH' is - set by invoking the `match' function. Its value is the length of - the matched string, or -1 if no match is found. + String Functions::). `RLENGTH' is set by invoking the `match' + function. Its value is the length of the matched string, or -1 if + no match is found. `RSTART' The start-index in characters of the substring that is matched by - the `match' function (*note String Manipulation Functions: String - Functions.). `RSTART' is set by invoking the `match' function. - Its value is the position of the string where the matched - substring starts, or zero if no match was found. + the `match' function (*note String Functions::). `RSTART' is set + by invoking the `match' function. Its value is the position of + the string where the matched substring starts, or zero if no match + was found. `RT #' This is set each time a record is read. It contains the input text @@ -8059,7 +8038,7 @@ with a pound sign (`#'). This variable is a `gawk' extension. In other `awk' implementations, or if `gawk' is in compatibility mode (*note - Command-Line Options: Options.), it is not special. + Options::), it is not special. Advanced Notes: Changing `NR' and `FNR' --------------------------------------- @@ -8080,10 +8059,9 @@ in the following example: -| 18 -| 19 -Before `FNR' was added to the `awk' language (*note Major Changes -Between V7 and SVR3.1: V7/SVR3.1.), many `awk' programs used this -feature to track the number of records in a file by resetting `NR' to -zero when `FILENAME' changed. +Before `FNR' was added to the `awk' language (*note V7/SVR3.1::), many +`awk' programs used this feature to track the number of records in a +file by resetting `NR' to zero when `FILENAME' changed. ---------- Footnotes ---------- @@ -8097,9 +8075,8 @@ File: gawk.info, Node: ARGC and ARGV, Prev: Auto-set, Up: Built-in Variables Using `ARGC' and `ARGV' ----------------------- - *Note Built-in Variables That Convey Information: Auto-set, -presented the following program describing the information contained in -`ARGC' and `ARGV': + *Note Auto-set::, presented the following program describing the +information contained in `ARGC' and `ARGV': $ awk 'BEGIN { > for (i = 0; i < ARGC; i++) @@ -8114,9 +8091,8 @@ In this example, `ARGV[0]' contains `awk', `ARGV[1]' contains the `awk' program is not entered in `ARGV'. The other special command-line options, with their arguments, are also not entered. This includes variable assignments done with the `-v' option (*note -Command-Line Options: Options.). Normal variable assignments on the -command line _are_ treated as arguments and do show up in the `ARGV' -array: +Options::). Normal variable assignments on the command line _are_ +treated as arguments and do show up in the `ARGV' array: $ cat showargs.awk -| BEGIN { @@ -8148,14 +8124,13 @@ other than file names. string (`""') into `ARGV' in place of the file's name. As a special feature, `awk' ignores file names that have been replaced with the null string. Another option is to use the `delete' statement to remove -elements from `ARGV' (*note The `delete' Statement: Delete.). +elements from `ARGV' (*note Delete::). All of these actions are typically done in the `BEGIN' rule, before -actual processing of the input begins. *Note Splitting a Large File -into Pieces: Split Program, and see *Note Duplicating Output into -Multiple Files: Tee Program, for examples of each way of removing -elements from `ARGV'. The following fragment processes `ARGV' in order -to examine, and then remove, command-line options: +actual processing of the input begins. *Note Split Program::, and see +*Note Tee Program::, for examples of each way of removing elements from +`ARGV'. The following fragment processes `ARGV' in order to examine, +and then remove, command-line options: BEGIN { for (i = 1; i < ARGC; i++) { @@ -8208,9 +8183,9 @@ about array usage. The major node finishes with a discussion of `gawk''s facility for sorting an array based on its indices. `awk' maintains a single set of names that may be used for naming -variables, arrays, and functions (*note User-Defined Functions: -User-defined.). Thus, you cannot have a variable and an array with the -same name in the same `awk' program. +variables, arrays, and functions (*note User-defined::). Thus, you +cannot have a variable and an array with the same name in the same +`awk' program. * Menu: @@ -8232,7 +8207,7 @@ same name in the same `awk' program. * Array Sorting:: Sorting array values and indices. -File: gawk.info, Node: Array Intro, Next: Reference to Elements, Prev: Arrays, Up: Arrays +File: gawk.info, Node: Array Intro, Next: Reference to Elements, Up: Arrays Introduction to Arrays ====================== @@ -8315,16 +8290,15 @@ from English to French: Here we decided to translate the number one in both spelled-out and numeric form--thus illustrating that a single array can have both numbers and strings as indices. In fact, array subscripts are always -strings; this is discussed in more detail in *Note Using Numbers to -Subscript Arrays: Numeric Array Subscripts. Here, the number `1' isn't -double-quoted, since `awk' automatically converts it to a string. +strings; this is discussed in more detail in *Note Numeric Array +Subscripts::. Here, the number `1' isn't double-quoted, since `awk' +automatically converts it to a string. The value of `IGNORECASE' has no effect upon array subscripting. The identical string value used to store an array element must be used to retrieve it. When `awk' creates an array (e.g., with the `split' built-in function), that array's indices are consecutive integers -starting at one. (*Note String Manipulation Functions: String -Functions.) +starting at one. (*Note String Functions::.) `awk''s arrays are efficient--the time to access an element is independent of the number of elements in the array. @@ -8350,10 +8324,9 @@ array `foo' at index `4.3'. A reference to an array element that has no recorded value yields a value of `""', the null string. This includes elements that have not been assigned any value as well as elements that have been deleted -(*note The `delete' Statement: Delete.). Such a reference -automatically creates that array element, with the null string as its -value. (In some cases, this is unfortunate, because it might waste -memory inside `awk'.) +(*note Delete::). Such a reference automatically creates that array +element, with the null string as its value. (In some cases, this is +unfortunate, because it might waste memory inside `awk'.) To determine whether an element exists in an array at a certain index, use the following expression: @@ -8473,8 +8446,8 @@ least once) in the input, by storing a one into the array `used' with the word as index. The second rule scans the elements of `used' to find all the distinct words that appear in the input. It prints each word that is more than 10 characters long and also prints the number of -such words. *Note String Manipulation Functions: String Functions, for -more information on the built-in function `length'. +such words. *Note String Functions::, for more information on the +built-in function `length'. # Record a 1 for each word that is used at least once { @@ -8492,8 +8465,7 @@ more information on the built-in function `length'. print num_long_words, "words longer than 10 characters" } -*Note Generating Word Usage Counts: Word Sorting, for a more detailed -example of this type. +*Note Word Sorting::, for a more detailed example of this type. The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array @@ -8539,9 +8511,9 @@ as assigning it a null value (the empty string, `""'). For example: print "This is printed, even though foo[4] is empty" It is not an error to delete an element that does not exist. If -`--lint' is provided on the command line (*note Command-Line Options: -Options.), `gawk' issues a warning message when an element that is not -in the array is deleted. +`--lint' is provided on the command line (*note Options::), `gawk' +issues a warning message when an element that is not in the array is +deleted. All the elements of an array may be deleted with a single statement by leaving off the subscript in the `delete' statement, as follows: @@ -8549,7 +8521,7 @@ by leaving off the subscript in the `delete' statement, as follows: delete ARRAY This ability is a `gawk' extension; it is not available in -compatibility mode (*note Command-Line Options: Options.). +compatibility mode (*note Options::). Using this version of the `delete' statement is about three times more efficient than the equivalent loop that deletes each element one @@ -8560,10 +8532,10 @@ clear out an array:(1) split("", array) - The `split' function (*note String Manipulation Functions: String -Functions.) clears out the target array first. This call asks it to -split apart the null string. Because there is no data to split out, the -function simply clears the array and then returns. + The `split' function (*note String Functions::) clears out the +target array first. This call asks it to split apart the null string. +Because there is no data to split out, the function simply clears the +array and then returns. *Caution:* Deleting an array does not change its type; you cannot delete an array and then use the array's name as a scalar (i.e., a @@ -8584,9 +8556,9 @@ Using Numbers to Subscript Arrays An important aspect about arrays to remember is that _array subscripts are always strings_. When a numeric value is used as a subscript, it is converted to a string value before being used for -subscripting (*note Conversion of Strings and Numbers: Conversion.). -This means that the value of the built-in variable `CONVFMT' can affect -how your program accesses elements of an array. For example: +subscripting (*note Conversion::). This means that the value of the +built-in variable `CONVFMT' can affect how your program accesses +elements of an array. For example: xyz = 12.153 data[xyz] = 1 @@ -8606,20 +8578,20 @@ assigned the value one. The program then changes the value of two significant digits. This test fails, since `"12.15"' is a different string from `"12.153"'. - According to the rules for conversions (*note Conversion of Strings -and Numbers: Conversion.), integer values are always converted to -strings as integers, no matter what the value of `CONVFMT' may happen -to be. So the usual case of the following works: + According to the rules for conversions (*note Conversion::), integer +values are always converted to strings as integers, no matter what the +value of `CONVFMT' may happen to be. So the usual case of the +following works: for (i = 1; i <= maxsub; i++) do something with array[i] The "integer values always convert to strings as integers" rule has an additional consequence for array indexing. Octal and hexadecimal -constants (*note Octal and Hexadecimal Numbers: Nondecimal-numbers.) -are converted internally into numbers, and their original form is -forgotten. This means, for example, that `array[17]', `array[021]', and -`array[0x11]' all refer to the same element! +constants (*note Nondecimal-numbers::) are converted internally into +numbers, and their original form is forgotten. This means, for +example, that `array[17]', `array[021]', and `array[0x11]' all refer to +the same element! As with many things in `awk', the majority of the time things work as one would expect them to. But it is useful to have a precise @@ -8671,7 +8643,7 @@ subscript. Even though it is somewhat unusual, the null string (`""') is a valid array subscript. (d.c.) `gawk' warns about the use of the null string as a subscript if `--lint' is provided on the command line -(*note Command-Line Options: Options.). +(*note Options::). File: gawk.info, Node: Multi-dimensional, Next: Multi-scanning, Prev: Uninitialized Subscripts, Up: Arrays @@ -8687,12 +8659,11 @@ two-dimensional array named `grid' is with `grid[X,Y]'. Multidimensional arrays are supported in `awk' through concatenation of indices into one string. `awk' converts the indices into strings -(*note Conversion of Strings and Numbers: Conversion.) and concatenates -them together, with a separator between them. This creates a single -string that describes the values of the separate indices. The combined -string is used as a single index into an ordinary, one-dimensional -array. The separator used is the value of the built-in variable -`SUBSEP'. +(*note Conversion::) and concatenates them together, with a separator +between them. This creates a single string that describes the values +of the separate indices. The combined string is used as a single index +into an ordinary, one-dimensional array. The separator used is the +value of the built-in variable `SUBSEP'. For example, suppose we evaluate the expression `foo[5,12] = "value"' when the value of `SUBSEP' is `"@"'. The numbers 5 and 12 are @@ -8769,10 +8740,9 @@ multidimensional _way of accessing_ an array. However, if your program has an array that is always accessed as multidimensional, you can get the effect of scanning it by combining -the scanning `for' statement (*note Scanning All Elements of an Array: -Scanning an Array.) with the built-in `split' function (*note String -Manipulation Functions: String Functions.). It works in the following -manner: +the scanning `for' statement (*note Scanning an Array::) with the +built-in `split' function (*note String Functions::). It works in the +following manner: for (combined in array) { split(combined, separate, SUBSEP) @@ -8808,8 +8778,8 @@ loop is essentially arbitrary. In most `awk' implementations, sorting an array requires writing a `sort' function. While this can be educational for exploring different sorting algorithms, usually that's not the point of the program. `gawk' provides the built-in `asort' and -`asorti' functions (*note String Manipulation Functions: String -Functions.) for sorting arrays. For example: +`asorti' functions (*note String Functions::) for sorting arrays. For +example: POPULATE THE ARRAY data n = asort(data) @@ -8820,8 +8790,7 @@ Functions.) for sorting arrays. For example: some number N, the total number of elements in `data'. (This count is `asort''s return value.) `data[1]' <= `data[2]' <= `data[3]', and so on. The comparison of array elements is done using `gawk''s usual -comparison rules (*note Variable Typing and Comparison Expressions: -Typing and Comparison.). +comparison rules (*note Typing and Comparison::). An important side effect of calling `asort' is that _the array's original indices are irrevocably lost_. As this isn't always @@ -8904,7 +8873,7 @@ major node describes these "user-defined" functions. * User-defined:: Describes User-defined functions in detail. -File: gawk.info, Node: Built-in, Next: User-defined, Prev: Functions, Up: Functions +File: gawk.info, Node: Built-in, Next: User-defined, Up: Functions Built-in Functions ================== @@ -8927,7 +8896,7 @@ for your convenience. * I18N Functions:: Functions for string translation. -File: gawk.info, Node: Calling Built-in, Next: Numeric Functions, Prev: Built-in, Up: Built-in +File: gawk.info, Node: Calling Built-in, Next: Numeric Functions, Up: Built-in Calling Built-in Functions -------------------------- @@ -9011,7 +8980,7 @@ brackets ([ ]): `rand()' This returns a random number. The values of `rand' are uniformly - distributed between zero and one. The value is never zero and + distributed between zero and one. The value could be zero but is never one.(1) Often random integers are needed instead. Following is a @@ -9125,10 +9094,9 @@ with a pound sign (`#'): a[2] = "de" a[3] = "sac" - The `asort' function is described in more detail in *Note Sorting - Array Values and Indices with `gawk': Array Sorting. `asort' is a - `gawk' extension; it is not available in compatibility mode (*note - Command-Line Options: Options.). + The `asort' function is described in more detail in *Note Array + Sorting::. `asort' is a `gawk' extension; it is not available in + compatibility mode (*note Options::). `asorti(SOURCE [, DEST]) #' `asorti' is a `gawk'-specific extension, returning the number of @@ -9138,11 +9106,10 @@ with a pound sign (`#'): always a string comparison. (Here too, `IGNORECASE' affects the sorting.) - The `asorti' function is described in more detail in *Note Sorting - Array Values and Indices with `gawk': Array Sorting. It was added - in `gawk' 3.1.2. `asorti' is a `gawk' extension; it is not - available in compatibility mode (*note Command-Line Options: - Options.). + The `asorti' function is described in more detail in *Note Array + Sorting::. It was added in `gawk' 3.1.2. `asorti' is a `gawk' + extension; it is not available in compatibility mode (*note + Options::). `index(IN, FIND)' This searches the string IN for the first occurrence of the string @@ -9181,9 +9148,9 @@ with a pound sign (`#'): The REGEXP argument may be either a regexp constant (`/.../') or a string constant ("..."). In the latter case, the string is - treated as a regexp to be matched. *Note Using Dynamic Regexps: - Computed Regexps, for a discussion of the difference between the - two forms, and the implications for writing your program correctly. + treated as a regexp to be matched. *Note Computed Regexps::, for a + discussion of the difference between the two forms, and the + implications for writing your program correctly. The order of the first two arguments is backwards from most other string functions that work with regular expressions, such as `sub' @@ -9251,9 +9218,14 @@ with a pound sign (`#'): -| 1 5 -| 9 7 + There may not be subscripts for the start and index for every + parenthesized subexpressions, since they may not all have matched + text; thus they should be tested for with the `in' operator (*note + Reference to Elements::). + The ARRAY argument to `match' is a `gawk' extension. In - compatibility mode (*note Command-Line Options: Options.), using a - third argument is a fatal error. + compatibility mode (*note Options::), using a third argument is a + fatal error. `split(STRING, ARRAY [, FIELDSEP])' This function divides STRING into pieces separated by FIELDSEP and @@ -9292,17 +9264,17 @@ with a pound sign (`#'): Modern implementations of `awk', including `gawk', allow the third argument to be a regexp constant (`/abc/') as well as a string. - (d.c.) The POSIX standard allows this as well. *Note Using - Dynamic Regexps: Computed Regexps, for a discussion of the - difference between using a string constant or a regexp constant, - and the implications for writing your program correctly. + (d.c.) The POSIX standard allows this as well. *Note Computed + Regexps::, for a discussion of the difference between using a + string constant or a regexp constant, and the implications for + writing your program correctly. Before splitting the string, `split' deletes any previously existing elements in the array ARRAY. If STRING is null, the array has no elements. (So this is a portable way to delete an entire array with one statement. *Note - The `delete' Statement: Delete.) + Delete::.) If STRING does not match FIELDSEP at all (but is not null), ARRAY has one element only. The value of that element is the original @@ -9310,8 +9282,8 @@ with a pound sign (`#'): `sprintf(FORMAT, EXPRESSION1, ...)' This returns (without printing) the string that `printf' would - have printed out with the same arguments (*note Using `printf' - Statements for Fancier Printing: Printf.). For example: + have printed out with the same arguments (*note Printf::). For + example: pival = sprintf("pi = %.2f (approx.)", 22/7) @@ -9332,7 +9304,7 @@ with a pound sign (`#'): only for decimal data, not for octal or hexadecimal.(1) `strtonum' is a `gawk' extension; it is not available in - compatibility mode (*note Command-Line Options: Options.). + compatibility mode (*note Options::). `sub(REGEXP, REPLACEMENT [, TARGET])' The `sub' function alters the value of TARGET. It searches this @@ -9343,9 +9315,9 @@ with a pound sign (`#'): The REGEXP argument may be either a regexp constant (`/.../') or a string constant ("..."). In the latter case, the string is - treated as a regexp to be matched. *Note Using Dynamic Regexps: - Computed Regexps, for a discussion of the difference between the - two forms, and the implications for writing your program correctly. + treated as a regexp to be matched. *Note Computed Regexps::, for a + discussion of the difference between the two forms, and the + implications for writing your program correctly. This function is peculiar because TARGET is not simply used to compute a value, and not just any expression will do--it must be a @@ -9381,7 +9353,7 @@ with a pound sign (`#'): This shows how `&' can represent a nonconstant string and also illustrates the "leftmost, longest" rule in regexp matching (*note - How Much Text Matches?: Leftmost Longest.). + Leftmost Longest::). The effect of this special character (`&') can be turned off by putting a backslash before it in the string. As usual, to insert @@ -9476,7 +9448,7 @@ with a pound sign (`#'): original unchanged value of TARGET. `gensub' is a `gawk' extension; it is not available in - compatibility mode (*note Command-Line Options: Options.). + compatibility mode (*note Options::). `substr(STRING, START [, LENGTH])' This returns a LENGTH-character-long substring of STRING, starting @@ -9535,8 +9507,7 @@ with a pound sign (`#'): ---------- Footnotes ---------- (1) Unless you use the `--non-decimal-data' option, which isn't -recommended. *Note Allowing Nondecimal Input Data: Nondecimal Data, -for more information. +recommended. *Note Nondecimal Data::, for more information. (2) Note that this means that the record will first be regenerated using the value of `OFS' if any fields have been changed, and that the @@ -9547,7 +9518,7 @@ a "no-op" such as `sub(/^/, "")'. is number zero. -File: gawk.info, Node: Gory Details, Prev: String Functions, Up: String Functions +File: gawk.info, Node: Gory Details, Up: String Functions More About `\' and `&' with `sub', `gsub', and `gensub' ....................................................... @@ -9699,17 +9670,16 @@ parameters are enclosed in square brackets ([ ]): Close the file FILENAME for input or output. Alternatively, the argument may be a shell command that was used for creating a coprocess, or for redirecting to or from a pipe; then the - coprocess or pipe is closed. *Note Closing Input and Output - Redirections: Close Files And Pipes, for more information. + coprocess or pipe is closed. *Note Close Files And Pipes::, for + more information. When closing a coprocess, it is occasionally useful to first close one end of the two-way pipe and then to close the other. This is done by providing a second argument to `close'. This second argument should be one of the two string values `"to"' or `"from"', indicating which end of the pipe to close. Case in the string does - not matter. *Note Two-Way Communications with Another Process: - Two-way I/O, which discusses this feature in more detail and gives - an example. + not matter. *Note Two-way I/O::, which discusses this feature in + more detail and gives an example. `fflush([FILENAME])' Flush any buffered output associated with FILENAME, which is @@ -9730,7 +9700,7 @@ parameters are enclosed in square brackets ([ ]): `fflush' was added to the Bell Laboratories research version of `awk' in 1994; it is not part of the POSIX standard and is not available if `--posix' has been specified on the command line - (*note Command-Line Options: Options.). + (*note Options::). `gawk' extends the `fflush' function in two ways. The first is to allow no argument at all. In this case, the buffer for the @@ -9937,10 +9907,10 @@ file. The `strftime' function allows you to easily turn a timestamp into human-readable information. It is similar in nature to the `sprintf' -function (*note String Manipulation Functions: String Functions.), in -that it copies nonformat specification characters verbatim to the -returned string, while substituting date and time values for format -specifications in the FORMAT string. +function (*note String Functions::), in that it copies nonformat +specification characters verbatim to the returned string, while +substituting date and time values for format specifications in the +FORMAT string. `strftime' is guaranteed by the 1999 ISO C standard(4) to support the following date format specifications: @@ -10098,8 +10068,8 @@ of what most C programmers are used to. A public-domain C version of `strftime' is supplied with `gawk' for systems that are not yet fully standards-compliant. It supports all of the just listed format specifications. If that version is used to -compile `gawk' (*note Installing `gawk': Installation.), then the -following additional format specifications are available: +compile `gawk' (*note Installation::), then the following additional +format specifications are available: `%k' The hour (24-hour clock) as a decimal number (0-23). Single-digit @@ -10180,7 +10150,7 @@ necessarily supports all of the conversions listed here. (5) If you don't understand any of this, don't worry about it; these facilities are meant to make it easier to "internationalize" programs. Other internationalization features are described in *Note -Internationalization with `gawk': Internationalization. +Internationalization::. (6) This is because ISO C leaves the behavior of the C version of `strftime' undefined and `gawk' uses the system's version of `strftime' @@ -10235,13 +10205,13 @@ bitwise operations just described. They are: `rshift(VAL, COUNT)' Returns the value of VAL, shifted right by COUNT bits. For all of these functions, first the double-precision -floating-point value is converted to a C `unsigned long', then the -bitwise operation is performed and then the result is converted back -into a C `double'. (If you don't understand this paragraph, don't worry -about it.) +floating-point value is converted to the widest C unsigned integer +type, then the bitwise operation is performed and then the result is +converted back into a C `double'. (If you don't understand this +paragraph, don't worry about it.) - Here is a user-defined function (*note User-Defined Functions: -User-defined.) that illustrates the use of these functions: + Here is a user-defined function (*note User-defined::) that +illustrates the use of these functions: # bits2str --- turn a byte into readable 1's and 0's @@ -10295,9 +10265,9 @@ at the end, it pads the value with zeros to represent multiples of 8-bit quantities. This is typical in modern computers. The main code in the `BEGIN' rule shows the difference between the -decimal and octal values for the same numbers (*note Octal and -Hexadecimal Numbers: Nondecimal-numbers.), and then demonstrates the -results of the `compl', `lshift', and `rshift' functions. +decimal and octal values for the same numbers (*note +Nondecimal-numbers::), and then demonstrates the results of the +`compl', `lshift', and `rshift' functions. ---------- Footnotes ---------- @@ -10313,9 +10283,9 @@ Using `gawk''s String-Translation Functions `gawk' provides facilities for internationalizing `awk' programs. These include the functions described in the following list. The -descriptions here are purposely brief. *Note Internationalization with -`gawk': Internationalization, for the full story. Optional parameters -are enclosed in square brackets ([ ]): +descriptions here are purposely brief. *Note Internationalization::, +for the full story. Optional parameters are enclosed in square +brackets ([ ]): `dcgettext(STRING [, DOMAIN [, CATEGORY]])' This function returns the translation of STRING in text domain @@ -10362,7 +10332,7 @@ i.e., to tell `awk' what they should do. * Dynamic Typing:: How variable types can change at runtime. -File: gawk.info, Node: Definition Syntax, Next: Function Example, Prev: User-defined, Up: User-defined +File: gawk.info, Node: Definition Syntax, Next: Function Example, Up: User-defined Function Definition Syntax -------------------------- @@ -10438,8 +10408,7 @@ act of a function calling itself is called "recursion". `function' may be abbreviated `func'. However, POSIX only specifies the use of the keyword `function'. This actually has some practical implications. If `gawk' is in POSIX-compatibility mode (*note -Command-Line Options: Options.), then the following statement does -_not_ define a function: +Options::), then the following statement does _not_ define a function: func foo() { a = sqrt($1) ; print a } @@ -10494,11 +10463,10 @@ this program, using our function to format the results, prints: When working with arrays, it is often necessary to delete all the elements in an array and start over with a new list of elements (*note -The `delete' Statement: Delete.). Instead of having to repeat this -loop everywhere that you need to clear out an array, your program can -just call `delarray'. (This guarantees portability. The use of -`delete ARRAY' to delete the contents of an entire array is a -nonstandard extension.) +Delete::). Instead of having to repeat this loop everywhere that you +need to clear out an array, your program can just call `delarray'. +(This guarantees portability. The use of `delete ARRAY' to delete the +contents of an entire array is a nonstandard extension.) The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. @@ -10523,8 +10491,8 @@ way: The C `ctime' function takes a timestamp and returns it in a string, formatted in a well-known fashion. The following example uses the -built-in `strftime' function (*note Using `gawk''s Timestamp Functions: -Time Functions.) to create an `awk' version of `ctime': +built-in `strftime' function (*note Time Functions::) to create an +`awk' version of `ctime': # ctime.awk # @@ -10634,12 +10602,12 @@ Because the `if' statement will never be true, it is not really a problem that `foo' has not been defined. Usually, though, it is a problem if a program calls an undefined function. - If `--lint' is specified (*note Command-Line Options: Options.), -`gawk' reports calls to undefined functions. + 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 The `next' Statement: Next Statement.) inside -a user-defined function. `gawk' does not have this limitation. +`next' statement (*note Next Statement::) inside a user-defined +function. `gawk' does not have this limitation. File: gawk.info, Node: Return Statement, Next: Dynamic Typing, Prev: Function Caveats, Up: User-defined @@ -10780,7 +10748,7 @@ requirement. * Gawk I18N:: `gawk' is also internationalized. -File: gawk.info, Node: I18N and L10N, Next: Explaining gettext, Prev: Internationalization, Up: Internationalization +File: gawk.info, Node: I18N and L10N, Next: Explaining gettext, Up: Internationalization Internationalization and Localization ===================================== @@ -10891,7 +10859,7 @@ defined locale categories that `gettext' knows about are: 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 Regular Expression Operators: Regexp Operators.). + (*note Regexp Operators::). `LC_MONETARY' Monetary information, such as the currency symbol, and whether the @@ -10950,9 +10918,9 @@ internationalization: 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 GNU - `gettext': Explaining gettext. You must also supply a text - domain. Use `TEXTDOMAIN' if you want to use the current domain. + 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 @@ -10980,12 +10948,11 @@ internationalization: binding for the given DOMAIN. To use these facilities in your `awk' program, follow the steps -outlined in *Note GNU `gettext': Explaining gettext, like so: +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 The `BEGIN' and `END' - Special Patterns: BEGIN/END.), or it can also be done via the `-v' - command-line option (*note Command-Line Options: Options.): + 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" @@ -11027,9 +10994,8 @@ outlined in *Note GNU `gettext': Explaining gettext, like so: } - *Note A Simple Internationalization Example: I18N Example, for an -example program showing the steps to create and use translations from -`awk'. + *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 @@ -11053,7 +11019,7 @@ for `printf' arguments at runtime is covered. * I18N Portability:: `awk'-level portability issues. -File: gawk.info, Node: String Extraction, Next: Printf Ordering, Prev: Translator i18n, Up: Translator i18n +File: gawk.info, Node: String Extraction, Next: Printf Ordering, Up: Translator i18n Extracting Marked Strings ------------------------- @@ -11070,9 +11036,8 @@ 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 A Simple Internationalization Example: I18N -Example, for the full list of steps to go through to create and test -translations for `guide'. +`dcngettext'.(1) *Note I18N Example::, for the full list of steps to go +through to create and test translations for `guide'. ---------- Footnotes ---------- @@ -11085,9 +11050,8 @@ File: gawk.info, Node: Printf Ordering, Next: I18N Portability, Prev: String Rearranging `printf' Arguments ------------------------------ - Format strings for `printf' and `sprintf' (*note Using `printf' -Statements for Fancier Printing: Printf.) present a special problem -for translation. Consider the following:(1) + 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))) @@ -11298,9 +11262,8 @@ proper directory so that `gawk' can find it: -| Pardon me, Zaphod who? If the three replacement functions for `dcgettext', `dcngettext' and -`bindtextdomain' (*note `awk' Portability Issues: I18N Portability.) -are in a file named `libintl.awk', then we can run `guide.awk' -unchanged as follows: +`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 @@ -11350,10 +11313,9 @@ full detail, along with the basics of TCP/IP networking and BSD portal files. Finally, `gawk' can "profile" an `awk' program, making it possible to tune it for performance. - *Note Adding New Built-in Functions to `gawk': 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. + *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. * Menu: @@ -11364,7 +11326,7 @@ description is relegated to an appendix. * Profiling:: Profiling your `awk' programs. -File: gawk.info, Node: Nondecimal Data, Next: Two-way I/O, Prev: Advanced Features, Up: Advanced Features +File: gawk.info, Node: Nondecimal Data, Next: Two-way I/O, Up: Advanced Features Allowing Nondecimal Input Data ============================== @@ -11401,9 +11363,9 @@ request it. *Caution:* _Use of this option is not recommended._ It can break old programs very badly. Instead, use the `strtonum' function to convert -your data (*note Octal and Hexadecimal Numbers: Nondecimal-numbers.). -This makes your programs easier to write and easier to read, and leads -to less surprising results. +your data (*note Nondecimal-numbers::). This makes your programs +easier to write and easier to read, and leads to less surprising +results. File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Nondecimal Data, Up: Advanced Features @@ -11485,10 +11447,9 @@ or pipeline of programs, that can be started by the shell. It is possible to close just one end of the two-way pipe to a coprocess, by supplying a second argument to the `close' function of -either `"to"' or `"from"' (*note Closing Input and Output Redirections: -Close Files And Pipes.). These strings tell `gawk' to close the end of -the pipe that sends data to the process or the end that reads from it, -respectively. +either `"to"' or `"from"' (*note Close Files And Pipes::). These +strings tell `gawk' to close the end of the pipe that sends data to the +process or the end that reads from it, respectively. This is particularly necessary in order to use the system `sort' utility as part of a coprocess; `sort' must read _all_ of its input @@ -11526,8 +11487,7 @@ ensures traditional Unix (ASCII) sorting from `sort'. Beginning with `gawk' 3.1.2, you may use Pseudo-ttys (ptys) for two-way communication instead of pipes, if your system supports them. This is done on a per-command basis, by setting a special element in -the `PROCINFO' array (*note Built-in Variables That Convey Information: -Auto-set.), like so: +the `PROCINFO' array (*note Auto-set::), like so: command = "sort -nr" # command, saved in variable for convenience PROCINFO[command, "pty"] = 1 # update PROCINFO @@ -11556,9 +11516,9 @@ Using `gawk' for Network Programming is busy hung or dead. In addition to being able to open a two-way pipeline to a coprocess -on the same system (*note Two-Way Communications with Another Process: -Two-way I/O.), it is possible to make a two-way connection to another -process on another system across an IP networking connection. +on the same system (*note Two-way I/O::), it is possible to make a +two-way connection to another process on another system across an IP +networking connection. You can think of this as just a _very long_ two-way pipeline to a coprocess. The way `gawk' decides that you want to use TCP/IP @@ -11618,9 +11578,8 @@ Using `gawk' with BSD Portals ============================= Similar to the `/inet' special files, if `gawk' is configured with -the `--enable-portals' option (*note Compiling `gawk' for Unix: Quick -Installation.), then `gawk' treats files whose pathnames begin with -`/p' as 4.4 BSD-style portals. +the `--enable-portals' option (*note Quick Installation::), then `gawk' +treats files whose pathnames begin with `/p' as 4.4 BSD-style portals. When used with the `|&' operator, `gawk' opens the file for two-way communications. The operating system's portal mechanism then manages @@ -11877,7 +11836,7 @@ full details. * Known Bugs:: Known Bugs in `gawk'. -File: gawk.info, Node: Command Line, Next: Options, Prev: Invoking Gawk, Up: Invoking Gawk +File: gawk.info, Node: Command Line, Next: Options, Up: Invoking Gawk Invoking `awk' ============== @@ -11921,8 +11880,7 @@ options and their meanings are as follows: `-F FS' `--field-separator FS' - Sets the `FS' variable to FS (*note Specifying How Fields Are - Separated: Field Separators.). + Sets the `FS' variable to FS (*note Field Separators::). `-f SOURCE-FILE' `--file SOURCE-FILE' @@ -11933,8 +11891,7 @@ options and their meanings are as follows: `--assign VAR=VAL' Sets the variable VAR to the value VAL _before_ execution of the program begins. Such variable values are available inside the - `BEGIN' rule (*note Other Command-Line Arguments: Other - Arguments.). + `BEGIN' rule (*note Other Arguments::). The `-v' option can only set one variable, but it can be used more than once, setting another variable each time, like this: `awk @@ -11984,10 +11941,8 @@ The following list describes `gawk'-specific options: Specifies "compatibility mode", in which the GNU extensions to the `awk' language are disabled, so that `gawk' behaves just like the Bell Laboratories research version of Unix `awk'. `--traditional' - is the preferred form of this option. *Note Extensions in `gawk' - Not in POSIX `awk': POSIX/GNU, which summarizes the extensions. - Also see *Note Downward Compatibility and Debugging: Compatibility - Mode. + is the preferred form of this option. *Note POSIX/GNU::, which + summarizes the extensions. Also see *Note Compatibility Mode::. `-W copyright' `--copyright' @@ -12017,8 +11972,8 @@ The following list describes `gawk'-specific options: `--gen-po' Analyzes the source program and generates a GNU `gettext' Portable Object file on standard output for all string constants that have - been marked for translation. *Note Internationalization with - `gawk': Internationalization, for information about this option. + been marked for translation. *Note Internationalization::, for + information about this option. `-W help' `-W usage' @@ -12042,14 +11997,12 @@ The following list describes `gawk'-specific options: `-W lint-old' `--lint-old' Warns about constructs that are not available in the original - version of `awk' from Version 7 Unix (*note Major Changes Between - V7 and SVR3.1: V7/SVR3.1.). + version of `awk' from Version 7 Unix (*note V7/SVR3.1::). `-W non-decimal-data' `--non-decimal-data' Enable automatic interpretation of octal and hexadecimal values in - input data (*note Allowing Nondecimal Input Data: Nondecimal - Data.). + input data (*note Nondecimal Data::). *Caution:* This option can severely break old programs. Use with care. @@ -12064,26 +12017,24 @@ The following list describes `gawk'-specific options: Sequences::). * Newlines do not act as whitespace to separate fields when - `FS' is equal to a single space (*note Examining Fields: - Fields.). + `FS' is equal to a single space (*note Fields::). * Newlines are not allowed after `?' or `:' (*note Conditional - Expressions: Conditional Exp.). + Exp::). * The synonym `func' for the keyword `function' is not - recognized (*note Function Definition Syntax: Definition - Syntax.). + recognized (*note Definition Syntax::). * The `**' and `**=' operators cannot be used in place of `^' - and `^=' (*note Arithmetic Operators: Arithmetic Ops., and - also *note Assignment Expressions: Assignment Ops.). + and `^=' (*note Arithmetic Ops::, and also *note Assignment + Ops::). * Specifying `-Ft' on the command-line does not set the value - of `FS' to be a single TAB character (*note Specifying How - Fields Are Separated: Field Separators.). + of `FS' to be a single TAB character (*note Field + Separators::). - * The `fflush' built-in function is not supported (*note - Input/Output Functions: I/O Functions.). + * The `fflush' built-in function is not supported (*note I/O + Functions::). If you supply both `--traditional' and `--posix' on the command line, `--posix' takes precedence. `gawk' also issues a warning if @@ -12091,10 +12042,10 @@ The following list describes `gawk'-specific options: `-W profile[=FILE]' `--profile[=FILE]' - Enable profiling of `awk' programs (*note Profiling Your `awk' - Programs: Profiling.). By default, profiles are created in a file - named `awkprof.out'. The optional FILE argument allows you to - specify a different file name for the profile file. + Enable profiling of `awk' programs (*note Profiling::). By + default, profiles are created in a file named `awkprof.out'. The + optional FILE argument allows you to specify a different file name + for the profile file. When run with `gawk', the profile is just a "pretty printed" version of the program. When run with `pgawk', the profile @@ -12103,10 +12054,10 @@ The following list describes `gawk'-specific options: `-W re-interval' `--re-interval' - Allows interval expressions (*note Regular Expression Operators: - Regexp Operators.) in regexps. Because interval expressions were - traditionally not available in `awk', `gawk' does not provide them - by default. This prevents old `awk' programs from breaking. + Allows interval expressions (*note Regexp Operators::) in regexps. + Because interval expressions were traditionally not available in + `awk', `gawk' does not provide them by default. This prevents old + `awk' programs from breaking. `-W source PROGRAM-TEXT' `--source PROGRAM-TEXT' @@ -12114,15 +12065,14 @@ The following list describes `gawk'-specific options: enter on the command line. Program source code is taken from the PROGRAM-TEXT. This is particularly useful when you have library functions that you want to use from your command-line programs - (*note The `AWKPATH' Environment Variable: AWKPATH Variable.). + (*note AWKPATH Variable::). `-W version' `--version' Prints version information for this particular copy of `gawk'. This allows you to determine if your copy of `gawk' is up to date with respect to whatever the Free Software Foundation is currently - distributing. It is also useful for bug reports (*note Reporting - Problems and Bugs: Bugs.). + distributing. It is also useful for bug reports (*note Bugs::). As long as program text has been supplied, any other options are flagged as invalid with a warning message but are otherwise ignored. @@ -12130,7 +12080,7 @@ flagged as invalid with a warning message but are otherwise ignored. In compatibility mode, as a special case, if the value of FS supplied to the `-F' option is `t', then `FS' is set to the TAB character (`"\t"'). This is true only for `--traditional' and not for `--posix' -(*note Specifying How Fields Are Separated: Field Separators.). +(*note Field Separators::). The `-f' option may be used more than once on the command line. If it is, `awk' reads its program source from all of the named files, as @@ -12138,8 +12088,7 @@ if they had been concatenated together into one big file. This is useful for creating libraries of `awk' functions. These functions can be written once and then retrieved from a standard place, instead of having to be included into each individual program. (As mentioned in -*Note Function Definition Syntax: Definition Syntax, function names -must be unique.) +*Note Definition Syntax::, function names must be unique.) Library functions can still be used, even if the program is entered at the terminal, by specifying `-f /dev/tty'. After typing your @@ -12152,8 +12101,7 @@ source of data.) source file and command-line `awk' programs, `gawk' provides the `--source' option. This does not require you to pre-empt the standard input for your source code; it allows you to easily mix command-line -and library source code (*note The `AWKPATH' Environment Variable: -AWKPATH Variable.). +and library source code (*note AWKPATH Variable::). If no `-f' or `--source' option is specified, then `gawk' uses the first non-option command-line argument as the text of the program @@ -12195,8 +12143,7 @@ Other Command-Line Arguments input files to be processed in the order specified. However, an argument that has the form `VAR=VALUE', assigns the value VALUE to the variable VAR--it does not specify a file at all. (This was discussed -earlier in *Note Assigning Variables on the Command Line: Assignment -Options.) +earlier in *Note Assignment Options::.) All these arguments are made available to your `awk' program in the `ARGV' array (*note Built-in Variables::). Command-line options and @@ -12214,9 +12161,8 @@ reading a file. Therefore, the variables actually receive the given values after all previously specified files have been read. In particular, the values of variables assigned in this fashion are _not_ available inside a `BEGIN' -rule (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.), -because such rules are run before `awk' begins scanning the argument -list. +rule (*note BEGIN/END::), because such rules are run before `awk' +begins scanning the argument list. The variable values given on the command line are processed for escape sequences (*note Escape Sequences::). (d.c.) @@ -12271,10 +12217,10 @@ command line with a short file name. Otherwise, the full file name would have to be typed for each file. By using both the `--source' and `-f' options, your command-line -`awk' programs can use facilities in `awk' library files (*note A -Library of `awk' Functions: Library Functions.). Path searching is not -done if `gawk' is in compatibility mode. This is true for both -`--traditional' and `--posix'. *Note Command-Line Options: Options. +`awk' programs can use facilities in `awk' library files (*note Library +Functions::). Path searching is not done if `gawk' is in compatibility +mode. This is true for both `--traditional' and `--posix'. *Note +Options::. *Note:* If you want files in the current directory to be found, you must include the current directory in the path, either by including `.' @@ -12320,12 +12266,11 @@ options from the previous version of `gawk'. The use of `next file' worked. Starting with version 3.1, the two-word usage is no longer accepted. - The process-related special files described in *Note Special Files -for Process-Related Information: Special Process, work as described, but -are now considered deprecated. `gawk' prints a warning message every -time they are used. (Use `PROCINFO' instead; see *Note Built-in -Variables That Convey Information: Auto-set.) They will be removed -from the next release of `gawk'. + The process-related special files described in *Note Special +Process::, work as described, but are now considered deprecated. +`gawk' prints a warning message every time they are used. (Use +`PROCINFO' instead; see *Note Auto-set::.) They will be removed from +the next release of `gawk'. File: gawk.info, Node: Undocumented, Next: Known Bugs, Prev: Obsolete, Up: Invoking Gawk @@ -12344,10 +12289,9 @@ File: gawk.info, Node: Known Bugs, Prev: Undocumented, Up: Invoking Gawk Known Bugs in `gawk' ==================== - * The `-F' option for changing the value of `FS' (*note Command-Line - Options: Options.) is not necessary given the command-line - variable assignment feature; it remains only for backward - compatibility. + * The `-F' option for changing the value of `FS' (*note Options::) + is not necessary given the command-line variable assignment + feature; it remains only for backward compatibility. * Syntactically invalid single-character programs tend to overflow the parse stack, generating a rather unhelpful message. Such @@ -12360,46 +12304,42 @@ File: gawk.info, Node: Library Functions, Next: Sample Programs, Prev: Invoki A Library of `awk' Functions **************************** - *Note User-Defined Functions: User-defined, describes how to write -your own `awk' functions. Writing functions is important, because it -allows you to encapsulate algorithms and program tasks in a single -place. It simplifies programming, making program development more -manageable, and making programs more readable. + *Note User-defined::, describes how to write your own `awk' +functions. Writing functions is important, because it allows you to +encapsulate algorithms and program tasks in a single place. It +simplifies programming, making program development more manageable, and +making programs more readable. One valuable way to learn a new programming language is to _read_ programs in that language. To that end, this major node and *Note -Practical `awk' Programs: Sample Programs, provide a good-sized body of -code for you to read, and hopefully, to learn from. +Sample Programs::, provide a good-sized body of code for you to read, +and hopefully, to learn from. This major node presents a library of useful `awk' functions. Many of the sample programs presented later in this Info file use these functions. The functions are presented here in a progression from simple to complex. - *Note Extracting Programs from Texinfo Source Files: Extract Program, -presents a program that you can use to extract the source code for -these example library functions and programs from the Texinfo source -for this Info file. (This has already been done as part of the `gawk' -distribution.) + *Note Extract Program::, presents a program that you can use to +extract the source code for these example library functions and +programs from the Texinfo source for this Info file. (This has already +been done as part of the `gawk' distribution.) If you have written one or more useful, general-purpose `awk' functions and would like to contribute them to the author's collection -of `awk' programs, see *Note How to Contribute: How To Contribute, for -more information. +of `awk' programs, see *Note How To Contribute::, for more information. - The programs in this major node and in *Note Practical `awk' -Programs: Sample Programs, freely use features that are `gawk'-specific. -Rewriting these programs for different implementations of awk is pretty -straightforward. + The programs in this major node and in *Note Sample Programs::, +freely use features that are `gawk'-specific. Rewriting these programs +for different implementations of awk is pretty straightforward. Diagnostic error messages are sent to `/dev/stderr'. Use `| "cat 1>&2"' instead of `> "/dev/stderr"' if your system does not have a `/dev/stderr', or if you cannot use `gawk'. - A number of programs use `nextfile' (*note Using `gawk''s `nextfile' -Statement: Nextfile Statement.) to skip any remaining input in the -input file. *Note Implementing `nextfile' as a Function: Nextfile -Function, shows you how to write a function that does the same thing. + A number of programs use `nextfile' (*note Nextfile Statement::) to +skip any remaining input in the input file. *Note Nextfile Function::, +shows you how to write a function that does the same thing. Finally, some of the programs choose to ignore upper- and lowercase distinctions in their input. They do so by assigning one to @@ -12431,7 +12371,7 @@ will be in all lowercase, while `IGNORECASE' preserves the original contents of the input record. -File: gawk.info, Node: Library Names, Next: General Functions, Prev: Library Functions, Up: Library Functions +File: gawk.info, Node: Library Names, Next: General Functions, Up: Library Functions Naming Library Function Global Variables ======================================== @@ -12443,9 +12383,9 @@ specific function). There is no intermediate state analogous to Library functions often need to have global variables that they can use to preserve state information between calls to the function--for -example, `getopt''s variable `_opti' (*note Processing Command-Line -Options: Getopt Function.). Such variables are called "private", since -the only functions that need to use them are the ones in the library. +example, `getopt''s variable `_opti' (*note Getopt Function::). Such +variables are called "private", since the only functions that need to +use them are the ones in the library. When writing a library function, you should try to choose names for your private variables that will not conflict with any variables used by @@ -12461,20 +12401,19 @@ will be accidentally shared with the user's program. In addition, several of the library functions use a prefix that helps indicate what function or set of functions use the variables--for -example, `_pw_byname' in the user database routines (*note Reading the -User Database: Passwd Functions.). This convention is recommended, -since it even further decreases the chance of inadvertent conflict -among variable names. Note that this convention is used equally well -for variable names and for private function names as well.(1) +example, `_pw_byname' in the user database routines (*note Passwd +Functions::). This convention is recommended, since it even further +decreases the chance of inadvertent conflict among variable names. +Note that this convention is used equally well for variable names and +for private function names as well.(1) As a final note on variable naming, if a function makes global variables available for use by a main program, it is a good convention to start that variable's name with a capital letter--for example, -`getopt''s `Opterr' and `Optind' variables (*note Processing -Command-Line Options: Getopt Function.). The leading capital letter -indicates that it is global, while the fact that the variable name is -not all capital letters indicates that the variable is not one of -`awk''s built-in variables, such as `FS'. +`getopt''s `Opterr' and `Optind' variables (*note Getopt Function::). +The leading capital letter indicates that it is global, while the fact +that the variable name is not all capital letters indicates that the +variable is not one of `awk''s built-in variables, such as `FS'. It is also important that _all_ variables in library functions that do not need to save state are, in fact, declared local.(2) If this is @@ -12492,10 +12431,10 @@ program, leading to bugs that are very difficult to track down: single associative array to hold the values needed by the library function(s), or "package." This significantly decreases the number of actual global names in use. For example, the functions described in -*Note Reading the User Database: Passwd Functions, might have used -array elements `PW_data["inited"]', `PW_data["total"]', -`PW_data["count"]', and `PW_data["awklib"]', instead of `_pw_inited', -`_pw_awklib', `_pw_total', and `_pw_count'. +*Note Passwd Functions::, might have used array elements +`PW_data["inited"]', `PW_data["total"]', `PW_data["count"]', and +`PW_data["awklib"]', instead of `_pw_inited', `_pw_awklib', `_pw_total', +and `_pw_count'. The conventions presented in this minor node are exactly that: conventions. You are not required to write your programs this way--we @@ -12535,17 +12474,16 @@ programming use. * Gettimeofday Function:: A function to get formatted times. -File: gawk.info, Node: Nextfile Function, Next: Assert Function, Prev: General Functions, Up: General Functions +File: gawk.info, Node: Nextfile Function, Next: Assert Function, Up: General Functions Implementing `nextfile' as a Function ------------------------------------- - The `nextfile' statement, presented in *Note Using `gawk''s -`nextfile' Statement: Nextfile Statement, is a `gawk'-specific -extension--it is not available in most other implementations of `awk'. -This minor node shows two versions of a `nextfile' function that you -can use to simulate `gawk''s `nextfile' statement if you cannot use -`gawk'. + The `nextfile' statement, presented in *Note Nextfile Statement::, +is a `gawk'-specific extension--it is not available in most other +implementations of `awk'. This minor node shows two versions of a +`nextfile' function that you can use to simulate `gawk''s `nextfile' +statement if you cannot use `gawk'. A first attempt at writing a `nextfile' function is as follows: @@ -12561,8 +12499,7 @@ current data file's name (which is always in the `FILENAME' variable) to a private variable named `_abandon_'. If the file name matches, then the action part of the rule executes a `next' statement to go on to the next record. (The use of `_' in the variable name is a convention. It -is discussed more fully in *Note Naming Library Function Global -Variables: Library Names.) +is discussed more fully in *Note Library Names::.) The use of the `next' statement effectively creates a loop that reads all the records from the current data file. The end of the file is @@ -12703,8 +12640,8 @@ rule is automatically added to the program calling `assert'. Normally, if a program consists of just a `BEGIN' rule, the input files and/or standard input are not read. However, now that the program has an `END' rule, `awk' attempts to read the input data files or standard input -(*note Startup and Cleanup Actions: Using BEGIN/END.), most likely -causing the program to hang as it waits for input. +(*note Using BEGIN/END::), most likely causing the program to hang as +it waits for input. There is a simple workaround to this: make sure the `BEGIN' rule always ends with an `exit' statement. @@ -12715,16 +12652,15 @@ File: gawk.info, Node: Round Function, Next: Cliff Random Function, Prev: Ass Rounding Numbers ---------------- - The way `printf' and `sprintf' (*note Using `printf' Statements for -Fancier Printing: Printf.) perform rounding often depends upon the -system's C `sprintf' subroutine. On many machines, `sprintf' rounding -is "unbiased," which means it doesn't always round a trailing `.5' up, -contrary to naive expectations. In unbiased rounding, `.5' rounds to -even, rather than always up, so 1.5 rounds to 2 but 4.5 rounds to 4. -This means that if you are using a format that does rounding (e.g., -`"%.0f"'), you should check what your system does. The following -function does traditional rounding; it might be useful if your awk's -`printf' does unbiased rounding: + The way `printf' and `sprintf' (*note Printf::) perform rounding +often depends upon the system's C `sprintf' subroutine. On many +machines, `sprintf' rounding is "unbiased," which means it doesn't +always round a trailing `.5' up, contrary to naive expectations. In +unbiased rounding, `.5' rounds to even, rather than always up, so 1.5 +rounds to 2 but 4.5 rounds to 4. This means that if you are using a +format that does rounding (e.g., `"%.0f"'), you should check what your +system does. The following function does traditional rounding; it +might be useful if your awk's `printf' does unbiased rounding: # round.awk --- do normal rounding function round(x, ival, aval, fraction) @@ -12886,16 +12822,14 @@ Merging an Array into a String When doing string processing, it is often useful to be able to join all the strings in an array into one long string. The following function, `join', accomplishes this task. It is used later in several -of the application programs (*note Practical `awk' Programs: Sample -Programs.). +of the application programs (*note Sample Programs::). Good function design is important; this function needs to be general but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric--a reasonable assumption since the array was likely -created with `split' (*note String Manipulation Functions: String -Functions.): +created with `split' (*note String Functions::): # join.awk --- join an array into a string function join(array, start, end, sep, result, i) @@ -12931,12 +12865,11 @@ File: gawk.info, Node: Gettimeofday Function, Prev: Join Function, Up: Genera Managing the Time of Day ------------------------ - The `systime' and `strftime' functions described in *Note Using -`gawk''s Timestamp Functions: Time Functions, provide the minimum -functionality necessary for dealing with the time of day in human -readable form. While `strftime' is extensive, the control formats are -not necessarily easy to remember or intuitively obvious when reading a -program. + The `systime' and `strftime' functions described in *Note Time +Functions::, provide the minimum functionality necessary for dealing +with the time of day in human readable form. While `strftime' is +extensive, the control formats are not necessarily easy to remember or +intuitively obvious when reading a program. The following function, `gettimeofday', populates a user-supplied array with preformatted time information. It returns a string with the @@ -13004,10 +12937,9 @@ current time formatted in the same way as the `date' utility: The string indices are easier to use and read than the various formats required by `strftime'. The `alarm' program presented in *Note -An Alarm Clock Program: Alarm Program, uses this function. A more -general design for the `gettimeofday' function would have allowed the -user to supply an optional timestamp value to use instead of the -current time. +Alarm Program::, uses this function. A more general design for the +`gettimeofday' function would have allowed the user to supply an +optional timestamp value to use instead of the current time. File: gawk.info, Node: Data File Management, Next: Getopt Function, Prev: General Functions, Up: Library Functions @@ -13023,23 +12955,23 @@ command-line data files. * Filetrans Function:: A function for handling data file transitions. * Rewind Function:: A function for rereading the current file. * File Checking:: Checking that data files are readable. +* Empty Files:: Checking for zero-length files. * Ignoring Assigns:: Treating assignments as file names. -File: gawk.info, Node: Filetrans Function, Next: Rewind Function, Prev: Data File Management, Up: Data File Management +File: gawk.info, Node: Filetrans Function, Next: Rewind Function, Up: Data File Management Noting Data File Boundaries --------------------------- The `BEGIN' and `END' rules are each executed exactly once at the -beginning and end of your `awk' program, respectively (*note The -`BEGIN' and `END' Special Patterns: BEGIN/END.). We (the `gawk' -authors) once had a user who mistakenly thought that the `BEGIN' rule -is executed at the beginning of each data file and the `END' rule is -executed at the end of each data file. When informed that this was not -the case, the user requested that we add new special patterns to -`gawk', named `BEGIN_FILE' and `END_FILE', that would have the desired -behavior. He even supplied us the code to do so. +beginning and end of your `awk' program, respectively (*note +BEGIN/END::). We (the `gawk' authors) once had a user who mistakenly +thought that the `BEGIN' rule is executed at the beginning of each data +file and the `END' rule is executed at the end of each data file. When +informed that this was not the case, the user requested that we add new +special patterns to `gawk', named `BEGIN_FILE' and `END_FILE', that +would have the desired behavior. He even supplied us the code to do so. Adding these special patterns to `gawk' wasn't necessary; the job can be done cleanly in `awk' itself, as illustrated by the following @@ -13087,11 +13019,10 @@ supplied in the "main" program, `endfile' is called first. Once again the value of multiple `BEGIN' and `END' rules should be clear. This version has same problem as the first version of `nextfile' -(*note Implementing `nextfile' as a Function: Nextfile Function.). If -the same data file occurs twice in a row on the command line, then -`endfile' and `beginfile' are not executed at the end of the first pass -and at the beginning of the second pass. The following version solves -the problem: +(*note Nextfile Function::). If the same data file occurs twice in a +row on the command line, then `endfile' and `beginfile' are not +executed at the end of the first pass and at the beginning of the +second pass. The following version solves the problem: # ftrans.awk --- handle data file transitions # @@ -13105,8 +13036,8 @@ the problem: END { endfile(_filename_) } - *Note Counting Things: Wc Program, shows how this library function -can be used and how it simplifies writing the main program. + *Note Wc Program::, shows how this library function can be used and +how it simplifies writing the main program. File: gawk.info, Node: Rewind Function, Next: File Checking, Prev: Filetrans Function, Up: Data File Management @@ -13116,8 +13047,8 @@ Rereading the Current File Another request for a new built-in function was for a `rewind' function that would make it possible to reread the current file. The -requesting user didn't want to have to use `getline' (*note Explicit -Input with `getline': Getline.) inside a loop. +requesting user didn't want to have to use `getline' (*note Getline::) +inside a loop. However, as long as you are not in the `END' rule, it is quite easy to arrange to immediately close the current input file and then start @@ -13141,19 +13072,17 @@ over with it from the top. For lack of a better name, we'll call it nextfile } - This code relies on the `ARGIND' variable (*note Built-in Variables -That Convey Information: Auto-set.), which is specific to `gawk'. If -you are not using `gawk', you can use ideas presented in *Note Noting -Data File Boundaries: Filetrans Function, to either update `ARGIND' on + This code relies on the `ARGIND' variable (*note Auto-set::), which +is specific to `gawk'. If you are not using `gawk', you can use ideas +presented in *Note Filetrans Function::, to either update `ARGIND' on your own or modify this code as appropriate. The `rewind' function also relies on the `nextfile' keyword (*note -Using `gawk''s `nextfile' Statement: Nextfile Statement.). *Note -Implementing `nextfile' as a Function: Nextfile Function, for a -function version of `nextfile'. +Nextfile Statement::). *Note Nextfile Function::, for a function +version of `nextfile'. -File: gawk.info, Node: File Checking, Next: Ignoring Assigns, Prev: Rewind Function, Up: Data File Management +File: gawk.info, Node: File Checking, Next: Empty Files, Prev: Rewind Function, Up: Data File Management Checking for Readable Data Files -------------------------------- @@ -13181,16 +13110,71 @@ force). Removing the element from `ARGV' with `delete' skips the file (since it's no longer in the list). -File: gawk.info, Node: Ignoring Assigns, Prev: File Checking, Up: Data File Management +File: gawk.info, Node: Empty Files, Next: Ignoring Assigns, Prev: File Checking, Up: Data File Management + +Checking For Zero-length Files +------------------------------ + + All known `awk' implementations silently skip over zero-length files. +This is a by-product of `awk''s implicit +read-a-record-and-match-against-the-rules loop: when `awk' tries to +read a record from an empty file, it immediately receives an end of +file indication, closes the file, and proceeds on to the next +command-line data file, _without_ executing any user-level `awk' +program code. + + Using `gawk''s `ARGIND' variable (*note Built-in Variables::), it is +possible to detect when an empty data file has been skipped. Similar +to the library file presented in *Note Filetrans Function::, the +following library file calls a function named `zerofile' that the user +must provide. The arguments passed are the file name and the position +in `ARGV' where it was found: + + # zerofile.awk --- library file to process empty input files + BEGIN { Argind = 0 } + + ARGIND > Argind + 1 { + for (Argind++; Argind < ARGIND; Argind++) + zerofile(ARGV[Argind], Argind) + } + + ARGIND != Argind { Argind = ARGIND } + + END { + if (ARGIND > Argind) + for (Argind++; Argind <= ARGIND; Argind++) + zerofile(ARGV[Argind], Argind) + } + + The user-level variable `Argind' allows the `awk' program to track +its progress through `ARGV'. Whenever the program detects that +`ARGIND' is greater than `Argind + 1', it means that one or more empty +files were skipped. The action then calls `zerofile' for each such +file, incrementing `Argind' along the way. + + The `Argind != ARGIND' rule simply keeps `Argind' up to date in the +normal case. + + Finally, the `END' rule catches the case of any empty files at the +end of the command-line arguments. Note that the test in the condition +of the `for' loop uses the `<=' operator, not `<'. + + As an exercise, you might consider whether this same problem can be +solved without relying on `gawk''s `ARGIND' variable. + + As a second exercise, revise this code to handle the case where an +intervening value in `ARGV' is a variable assignment. + + +File: gawk.info, Node: Ignoring Assigns, Prev: Empty Files, Up: Data File Management Treating Assignments as File Names ---------------------------------- Occasionally, you might not want `awk' to process command-line -variable assignments (*note Assigning Variables on the Command Line: -Assignment Options.). In particular, if you have file names that -contain an `=' character, `awk' treats the file name as an assignment, -and does not process it. +variable assignments (*note Assignment Options::). In particular, if +you have file names that contain an `=' character, `awk' treats the +file name as an assignment, and does not process it. Some users have suggested an additional command-line option for `gawk' to disable command-line assignments. However, some simple @@ -13232,11 +13216,11 @@ Processing Command-Line Options Most utilities on POSIX compatible systems take options, or "switches," on the command line that can be used to change the way a program behaves. `awk' is an example of such a program (*note -Command-Line Options: Options.). Often, options take "arguments"; -i.e., data that the program needs to correctly obey the command-line -option. For example, `awk''s `-F' option requires a string to use as -the field separator. The first occurrence on the command line of -either `--' or a string that does not begin with `-' ends the options. +Options::). Often, options take "arguments"; i.e., data that the +program needs to correctly obey the command-line option. For example, +`awk''s `-F' option requires a string to use as the field separator. +The first occurrence on the command line of either `--' or a string +that does not begin with `-' ends the options. Modern Unix systems provide a C function named `getopt' for processing command-line arguments. The programmer provides a string @@ -13318,15 +13302,14 @@ command-line arguments for `awk': } As a side point, `gawk' actually uses the GNU `getopt_long' function -to process both normal and GNU-style long options (*note Command-Line -Options: Options.). +to process both normal and GNU-style long options (*note Options::). The abstraction provided by `getopt' is very useful and is quite handy in `awk' programs as well. Following is an `awk' version of `getopt'. This function highlights one of the greatest weaknesses in `awk', which is that it is very poor at manipulating single characters. Repeated calls to `substr' are necessary for accessing individual -characters (*note String Manipulation Functions: String Functions.).(1) +characters (*note String Functions::).(1) The discussion that follows walks through the code a bit at a time: @@ -13499,8 +13482,8 @@ result of two sample runs of the test program: In both runs, the first `--' terminates the arguments to `awk', so that it does not try to interpret the `-a', etc., as its own options. -Several of the sample programs presented in *Note Practical `awk' -Programs: Sample Programs, use `getopt' to process their arguments. +Several of the sample programs presented in *Note Sample Programs::, +use `getopt' to process their arguments. ---------- Footnotes ---------- @@ -13521,8 +13504,8 @@ are numbers, they do not provide very useful information to the average user. There needs to be some way to find the user information associated with the user and group ID numbers. This minor node presents a suite of functions for retrieving information from the user -database. *Note Reading the Group Database: Group Functions, for a -similar suite that retrieves information from the group database. +database. *Note Group Functions::, for a similar suite that retrieves +information from the group database. The POSIX standard does not define the file where user information is kept. Instead, it provides the `<pwd.h>' header file and several C @@ -13727,8 +13710,7 @@ once. If you are worried about squeezing every last cycle out of your this is not necessary, since most `awk' programs are I/O-bound, and it clutters up the code. - The `id' program in *Note Printing out User Information: Id Program, -uses these functions. + The `id' program in *Note Id Program::, uses these functions. ---------- Footnotes ---------- @@ -13741,14 +13723,14 @@ File: gawk.info, Node: Group Functions, Prev: Passwd Functions, Up: Library F Reading the Group Database ========================== - Much of the discussion presented in *Note Reading the User Database: -Passwd Functions, applies to the group database as well. Although -there has traditionally been a well-known file (`/etc/group') in a -well-known format, the POSIX standard only provides a set of C library -routines (`<grp.h>' and `getgrent') for accessing the information. -Even though this file may exist, it likely does not have complete -information. Therefore, as with the user database, it is necessary to -have a small C program that generates the group database as its output. + Much of the discussion presented in *Note Passwd Functions::, +applies to the group database as well. Although there has traditionally +been a well-known file (`/etc/group') in a well-known format, the POSIX +standard only provides a set of C library routines (`<grp.h>' and +`getgrent') for accessing the information. Even though this file may +exist, it likely does not have complete information. Therefore, as +with the user database, it is necessary to have a small C program that +generates the group database as its output. `grcat', a C program that "cats" the group database, is as follows: @@ -13872,11 +13854,11 @@ routine, we have chosen to put it in `/usr/local/libexec/awk'. You might want it to be in a different directory on your system. These routines follow the same general outline as the user database -routines (*note Reading the User Database: Passwd Functions.). The -`_gr_inited' variable is used to ensure that the database is scanned no -more than once. The `_gr_init' function first saves `FS', -`FIELDWIDTHS', `RS', and `$0', and then sets `FS' and `RS' to the -correct values for scanning the group information. +routines (*note Passwd Functions::). The `_gr_inited' variable is used +to ensure that the database is scanned no more than once. The +`_gr_init' function first saves `FS', `FIELDWIDTHS', `RS', and `$0', +and then sets `FS' and `RS' to the correct values for scanning the +group information. The group information is stored is several associative arrays. The arrays are indexed by group name (`_gr_byname'), by group ID number @@ -13965,8 +13947,7 @@ body of `_gr_init' into a `BEGIN' rule). associative arrays. The functions that the user calls are themselves very simple, relying on `awk''s associative arrays to do work. - The `id' program in *Note Printing out User Information: Id Program, -uses these functions. + The `id' program in *Note Id Program::, uses these functions. File: gawk.info, Node: Sample Programs, Next: Language History, Prev: Library Functions, Up: Top @@ -13974,13 +13955,13 @@ File: gawk.info, Node: Sample Programs, Next: Language History, Prev: Library Practical `awk' Programs ************************ - *Note A Library of `awk' Functions: Library Functions, presents the -idea that reading programs in a language contributes to learning that -language. This major node continues that theme, presenting a potpourri -of `awk' programs for your reading enjoyment. + *Note Library Functions::, presents the idea that reading programs +in a language contributes to learning that language. This major node +continues that theme, presenting a potpourri of `awk' programs for your +reading enjoyment. Many of these programs use the library functions presented in *Note -A Library of `awk' Functions: Library Functions. +Library Functions::. * Menu: @@ -13989,7 +13970,7 @@ A Library of `awk' Functions: Library Functions. * Miscellaneous Programs:: Some interesting `awk' programs. -File: gawk.info, Node: Running Examples, Next: Clones, Prev: Sample Programs, Up: Sample Programs +File: gawk.info, Node: Running Examples, Next: Clones, Up: Sample Programs Running the Example Programs ============================ @@ -14003,8 +13984,7 @@ OPTIONS are any command-line options for the program that start with a `-', and FILES are the actual data files. If your system supports the `#!' executable interpreter mechanism -(*note Executable `awk' Programs: Executable Scripts.), you can instead -run your program directly: +(*note Executable Scripts::), you can instead run your program directly: cut.awk -c1-8 myfiles > results @@ -14042,7 +14022,7 @@ tasks. * Wc Program:: The `wc' utility. -File: gawk.info, Node: Cut Program, Next: Egrep Program, Prev: Clones, Up: Clones +File: gawk.info, Node: Cut Program, Next: Egrep Program, Up: Clones Cutting out Fields and Columns ------------------------------ @@ -14078,9 +14058,8 @@ pipeline generates a sorted, unique list of the logged-on users: Suppress printing of lines that do not contain the field delimiter. The `awk' implementation of `cut' uses the `getopt' library function -(*note Processing Command-Line Options: Getopt Function.) and the -`join' library function (*note Merging an Array into a String: Join -Function.). +(*note Getopt Function::) and the `join' library function (*note Join +Function::). The program begins with a comment describing the options, the library functions needed, and a `usage' function that prints out a usage @@ -14208,9 +14187,9 @@ The program lets `awk' handle the job of doing the field splitting: } The `set_charlist' function is more complicated than `set_fieldlist'. -The idea here is to use `gawk''s `FIELDWIDTHS' variable (*note Reading -Fixed-Width Data: Constant Size.), which describes constant-width -input. When using a character list, that is exactly what we have. +The idea here is to use `gawk''s `FIELDWIDTHS' variable (*note Constant +Size::), which describes constant-width input. When using a character +list, that is exactly what we have. Setting up `FIELDWIDTHS' is more complicated than simply listing the fields that need to be printed. We have to keep track of the fields to @@ -14292,10 +14271,9 @@ out between the fields: This version of `cut' relies on `gawk''s `FIELDWIDTHS' variable to do the character-based cutting. While it is possible in other `awk' -implementations to use `substr' (*note String Manipulation Functions: -String Functions.), it is also extremely painful. The `FIELDWIDTHS' -variable supplies an elegant solution to the problem of picking the -input line apart by characters. +implementations to use `substr' (*note String Functions::), it is also +extremely painful. The `FIELDWIDTHS' variable supplies an elegant +solution to the problem of picking the input line apart by characters. File: gawk.info, Node: Egrep Program, Next: Id Program, Prev: Cut Program, Up: Clones @@ -14305,8 +14283,7 @@ Searching for Regular Expressions in Files The `egrep' utility searches files for patterns. It uses regular expressions that are almost identical to those available in `awk' -(*note Regular Expressions: Regexp.). It is used in the following -manner: +(*note Regexp::). It is used in the following manner: egrep [ OPTIONS ] 'PATTERN' FILES ... @@ -14343,10 +14320,9 @@ a colon. Use PATTERN as the regexp to match. The purpose of the `-e' option is to allow patterns that start with a `-'. - This version uses the `getopt' library function (*note Processing -Command-Line Options: Getopt Function.) and the file transition -library program (*note Noting Data File Boundaries: Filetrans -Function.). + This version uses the `getopt' library function (*note Getopt +Function::) and the file transition library program (*note Filetrans +Function::). The program begins with a descriptive comment and then a `BEGIN' rule that processes the command-line arguments with `getopt'. The `-i' @@ -14549,9 +14525,8 @@ array (*note Built-in Variables::). However, the `id' utility provides a more palatable output than just individual numbers. Here is a simple version of `id' written in `awk'. It uses the user -database library functions (*note Reading the User Database: Passwd -Functions.) and the group database library functions (*note Reading -the Group Database: Group Functions.): +database library functions (*note Passwd Functions::) and the group +database library functions (*note Group Functions::): The program is fairly straightforward. All the work is done in the `BEGIN' rule. The user and group ID numbers are obtained from @@ -14657,8 +14632,7 @@ to something like `myfileaa', `myfileab', and so on, supply an additional argument that specifies the file name prefix. Here is a version of `split' in `awk'. It uses the `ord' and `chr' -functions presented in *Note Translating Between Characters and -Numbers: Ordinal Functions. +functions presented in *Note Ordinal Functions::. The program first sets its defaults, and then tests to make sure there are not too many arguments. It then looks at each argument in @@ -14870,9 +14844,8 @@ usage is as follows: Normally `uniq' behaves as if both the `-d' and `-u' options are provided. - `uniq' uses the `getopt' library function (*note Processing -Command-Line Options: Getopt Function.) and the `join' library function -(*note Merging an Array into a String: Join Function.). + `uniq' uses the `getopt' library function (*note Getopt Function::) +and the `join' library function (*note Join Function::). The program begins with a `usage' function and then a brief outline of the options and their meanings in a comment. The `BEGIN' rule deals @@ -14955,13 +14928,13 @@ characters. If no field count and no character count are specified, `are_equal' simply returns one or zero depending upon the result of a simple string comparison of `last' and `$0'. Otherwise, things get more complicated. If fields have to be skipped, each line is broken into an -array using `split' (*note String Manipulation Functions: String -Functions.); the desired fields are then joined back into a line using -`join'. The joined lines are stored in `clast' and `cline'. If no -fields are skipped, `clast' and `cline' are set to `last' and `$0', -respectively. Finally, if characters are skipped, `substr' is used to -strip off the leading `charcount' characters in `clast' and `cline'. -The two strings are then compared and `are_equal' returns the result: +array using `split' (*note String Functions::); the desired fields are +then joined back into a line using `join'. The joined lines are stored +in `clast' and `cline'. If no fields are skipped, `clast' and `cline' +are set to `last' and `$0', respectively. Finally, if characters are +skipped, `substr' is used to strip off the leading `charcount' +characters in `clast' and `cline'. The two strings are then compared +and `are_equal' returns the result: function are_equal( n, m, clast, cline, alast, aline) { @@ -15076,9 +15049,8 @@ a lot of the work for us; it splits lines into words (i.e., fields) and counts them, it counts lines (i.e., records), and it can easily tell us how long a line is. - This uses the `getopt' library function (*note Processing -Command-Line Options: Getopt Function.) and the file-transition -functions (*note Noting Data File Boundaries: Filetrans Function.). + This uses the `getopt' library function (*note Getopt Function::) +and the file-transition functions (*note Filetrans Function::). This version has one notable difference from traditional versions of `wc': it always prints the counts in the order lines, words, and @@ -15182,9 +15154,8 @@ this line: ---------- Footnotes ---------- (1) `wc' can't just use the value of `FNR' in `endfile'. If you -examine the code in *Note Noting Data File Boundaries: Filetrans -Function you will see that `FNR' has already been reset by the time -`endfile' is called. +examine the code in *Note Filetrans Function:: you will see that `FNR' +has already been reset by the time `endfile' is called. File: gawk.info, Node: Miscellaneous Programs, Prev: Clones, Up: Sample Programs @@ -15211,7 +15182,7 @@ hope you find them both interesting and enjoyable. files. -File: gawk.info, Node: Dupword Program, Next: Alarm Program, Prev: Miscellaneous Programs, Up: Miscellaneous Programs +File: gawk.info, Node: Dupword Program, Next: Alarm Program, Up: Miscellaneous Programs Finding Duplicated Words in a Document -------------------------------------- @@ -15273,8 +15244,8 @@ prints the message on the standard output. In addition, you can give it the number of times to repeat the message as well as a delay between repetitions. - This program uses the `gettimeofday' function from *Note Managing -the Time of Day: Gettimeofday Function. + This program uses the `gettimeofday' function from *Note +Gettimeofday Function::. All the work is done in the `BEGIN' rule. The first part is argument checking and setting of defaults: the delay, the count, and the message @@ -15360,13 +15331,13 @@ alarm: exit 1 } - Finally, the program uses the `system' function (*note Input/Output -Functions: I/O Functions.) to call the `sleep' utility. The `sleep' -utility simply pauses for the given number of seconds. If the exit -status is not zero, the program assumes that `sleep' was interrupted -and exits. If `sleep' exited with an OK status (zero), then the program -prints the message in a loop, again using `sleep' to delay for however -many seconds are necessary: + Finally, the program uses the `system' function (*note I/O +Functions::) to call the `sleep' utility. The `sleep' utility simply +pauses for the given number of seconds. If the exit status is not zero, +the program assumes that `sleep' was interrupted and exits. If `sleep' +exited with an OK status (zero), then the program prints the message in +a loop, again using `sleep' to delay for however many seconds are +necessary: # zzzzzz..... go away if interrupted if (system(sprintf("sleep %d", naptime)) != 0) @@ -15413,9 +15384,8 @@ most of the job. The `translate' program demonstrates one of the few weaknesses of standard `awk': dealing with individual characters is very painful, requiring repeated use of the `substr', `index', and `gsub' built-in -functions (*note String Manipulation Functions: String Functions.).(2) -There are two functions. The first, `stranslate', takes three -arguments: +functions (*note String Functions::).(2) There are two functions. The +first, `stranslate', takes three arguments: `from' A list of characters from which to translate. @@ -15488,11 +15458,10 @@ record: function, it is not necessarily efficient, and we (the `gawk' authors) started to consider adding a built-in function. However, shortly after writing this program, we learned that the System V Release 4 `awk' had -added the `toupper' and `tolower' functions (*note String Manipulation -Functions: String Functions.). These functions handle the vast -majority of the cases where character transliteration is necessary, and -so we chose to simply add those functions to `gawk' as well and then -leave well enough alone. +added the `toupper' and `tolower' functions (*note String Functions::). +These functions handle the vast majority of the cases where character +transliteration is necessary, and so we chose to simply add those +functions to `gawk' as well and then leave well enough alone. An obvious improvement to this program would be to set up the `t_ar' array only once, in a `BEGIN' rule. However, this assumes that the @@ -15527,9 +15496,9 @@ of filling the `line' array and printing the page when 20 labels have been read. The `BEGIN' rule simply sets `RS' to the empty string, so that `awk' -splits records at blank lines (*note How Input Is Split into Records: -Records.). It sets `MAXLINES' to 100, since 100 is the maximum number -of lines on the page (20 * 5 = 100). +splits records at blank lines (*note Records::). It sets `MAXLINES' to +100, since 100 is the maximum number of lines on the page (20 * 5 = +100). Most of the work is done in the `printpage' function. The label lines are stored sequentially in the `line' array. But they have to @@ -15641,11 +15610,11 @@ program listing: This program has two rules. The first rule, because it has an empty pattern, is executed for every input line. It uses `awk''s -field-accessing mechanism (*note Examining Fields: Fields.) to pick out -the individual words from the line, and the built-in variable `NF' -(*note Built-in Variables::) to know how many fields are available. -For each input word, it increments an element of the array `freq' to -reflect that the word has been seen an additional time. +field-accessing mechanism (*note Fields::) to pick out the individual +words from the line, and the built-in variable `NF' (*note Built-in +Variables::) to know how many fields are available. For each input +word, it increments an element of the array `freq' to reflect that the +word has been seen an additional time. The second rule, because it has the pattern `END', is not executed until the input has been exhausted. It prints out the contents of the @@ -15726,8 +15695,8 @@ File: gawk.info, Node: History Sorting, Next: Extract Program, Prev: Word Sor Removing Duplicates from Unsorted Text -------------------------------------- - The `uniq' program (*note Printing Nonduplicated Lines of Text: Uniq -Program.), removes duplicate lines from _sorted_ data. + The `uniq' program (*note Uniq Program::), removes duplicate lines +from _sorted_ data. Suppose, however, you need to remove duplicate lines from a data file but that you want to preserve the order the lines are in. A good @@ -15772,12 +15741,11 @@ File: gawk.info, Node: Extract Program, Next: Simple Sed, Prev: History Sorti Extracting Programs from Texinfo Source Files --------------------------------------------- - The nodes *Note A Library of `awk' Functions: Library Functions, and -*Note Practical `awk' Programs: Sample Programs, are the top level -nodes for a large number of `awk' programs. If you want 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. + The nodes *Note Library Functions::, and *Note Sample Programs::, +are the top level nodes for a large number of `awk' programs. If you +want 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, the GNU project's document formatting language. A single Texinfo source file can be used to @@ -15803,14 +15771,13 @@ input files: The following program, `extract.awk', reads through a Texinfo source file and does two things, based on the special comments. Upon seeing `@c system ...', it runs a command, by extracting the command text from -the control line and passing it on to the `system' function (*note -Input/Output Functions: I/O Functions.). Upon seeing `@c file -FILENAME', each subsequent line is sent to the file FILENAME, until `@c -endfile' is encountered. The rules in `extract.awk' match either `@c' -or `@comment' by letting the `omment' part be optional. Lines -containing `@group' and `@end group' are simply removed. `extract.awk' -uses the `join' library function (*note Merging an Array into a String: -Join Function.). +the control line and passing it on to the `system' function (*note I/O +Functions::). Upon seeing `@c file FILENAME', each subsequent line is +sent to the file FILENAME, until `@c endfile' is encountered. The +rules in `extract.awk' match either `@c' or `@comment' by letting the +`omment' part be optional. Lines containing `@group' and `@end group' +are simply removed. `extract.awk' uses the `join' library function +(*note Join Function::). The example programs in the online Texinfo source for `GAWK: Effective AWK Programming' (`gawk.texi') have all been bracketed inside @@ -15877,21 +15844,21 @@ redirection for printing the contents, keeping open file management simple. The `for' loop does the work. It reads lines using `getline' (*note -Explicit Input with `getline': Getline.). For an unexpected end of -file, it calls the `unexpected_eof' function. If the line is an -"endfile" line, then it breaks out of the loop. If the line is an -`@group' or `@end group' line, then it ignores it and goes on to the -next line. Similarly, comments within examples are also ignored. +Getline::). For an unexpected end of file, it calls the +`unexpected_eof' function. If the line is an "endfile" line, then it +breaks out of the loop. If the line is an `@group' or `@end group' +line, then it ignores it and goes on to the next line. Similarly, +comments within examples are also ignored. Most of the work is in the following few lines. If the line has no `@' symbols, the program can print it directly. Otherwise, each leading `@' must be stripped off. To remove the `@' symbols, the line is split into separate elements of the array `a', using the `split' -function (*note String Manipulation Functions: String Functions.). The -`@' symbol is used as the separator character. Each element of `a' -that is empty indicates two successive `@' symbols in the original -line. For each two empty elements (`@@' in the original file), we have -to add a single `@' symbol back in. +function (*note String Functions::). The `@' symbol is used as the +separator character. Each element of `a' that is empty indicates two +successive `@' symbols in the original line. For each two empty +elements (`@@' in the original file), we have to add a single `@' +symbol back in. When the processing of the array is finished, `join' is called with the value of `SUBSEP', to rejoin the pieces back into a single line. @@ -15939,11 +15906,11 @@ That line is then printed to the output file: An important thing to note is the use of the `>' redirection. Output done with `>' only opens the file once; it stays open and -subsequent output is appended to the file (*note Redirecting Output of -`print' and `printf': Redirection.). This makes it easy to mix program -text and explanatory prose for the same sample source file (as has been -done here!) without any hassle. The file is only closed when a new -data file name is encountered or at the end of the input file. +subsequent output is appended to the file (*note Redirection::). This +makes it easy to mix program text and explanatory prose for the same +sample source file (as has been done here!) without any hassle. The +file is only closed when a new data file name is encountered or at the +end of the input file. Finally, the function `unexpected_eof' prints an appropriate error message and then exits. The `END' rule handles the final cleanup, @@ -15978,7 +15945,7 @@ the middle of a pipeline: Here, `s/old/new/g' tells `sed' to look for the regexp `old' on each input line and globally replace it with the text `new', i.e., all the occurrences on a line. This is similar to `awk''s `gsub' function -(*note String Manipulation Functions: String Functions.). +(*note String Functions::). The following program, `awksed.awk', accepts at least two command-line arguments: the pattern to look for and the text to replace @@ -16015,7 +15982,7 @@ process. If none are provided, the standard input is used: The program relies on `gawk''s ability to have `RS' be a regexp, as well as on the setting of `RT' to the actual text that terminates the -record (*note How Input Is Split into Records: Records.). +record (*note Records::). The idea is to have `RS' be the pattern to look for. `gawk' automatically sets `$0' to the text between matches of the pattern. @@ -16028,14 +15995,13 @@ record doesn't end with text that matches `RS'. Using a `print' statement unconditionally prints the replacement text, which is not correct. However, if the file did not end in text that matches `RS', `RT' is set to the null string. In this case, we can print `$0' using -`printf' (*note Using `printf' Statements for Fancier Printing: -Printf.). +`printf' (*note Printf::). The `BEGIN' rule handles the setup, checking for the right number of arguments and calling `usage' if there is a problem. Then it sets `RS' and `ORS' from the command-line arguments and sets `ARGV[1]' and `ARGV[2]' to the null string, so that they are not treated as file names -(*note Using `ARGC' and `ARGV': ARGC and ARGV.). +(*note ARGC and ARGV::). The `usage' function prints an error message and exits. Finally, the single rule handles the printing scheme outlined above, using @@ -16053,9 +16019,8 @@ smaller and therefore clearer. However, using library functions is only easy when writing `awk' programs; it is painful when running them, requiring multiple `-f' options. If `gawk' is unavailable, then so too is the `AWKPATH' environment variable and the ability to put `awk' -functions into a library directory (*note Command-Line Options: -Options.). It would be nice to be able to write programs in the -following manner: +functions into a library directory (*note Options::). It would be nice +to be able to write programs in the following manner: # library functions @include getopt.awk @@ -16237,24 +16202,23 @@ program. The `awk' program to process `@include' directives is stored in the shell variable `expand_prog'. Doing this keeps the shell script readable. The `awk' program reads through the user's program, one line -at a time, using `getline' (*note Explicit Input with `getline': -Getline.). The input file names and `@include' statements are managed -using a stack. As each `@include' is encountered, the current file -name is "pushed" onto the stack and the file named in the `@include' -directive becomes the current file name. As each file is finished, the -stack is "popped," and the previous input file becomes the current -input file again. The process is started by making the original file -the first one on the stack. +at a time, using `getline' (*note Getline::). The input file names and +`@include' statements are managed using a stack. As each `@include' is +encountered, the current file name is "pushed" onto the stack and the +file named in the `@include' directive becomes the current file name. +As each file is finished, the stack is "popped," and the previous input +file becomes the current input file again. The process is started by +making the original file the first one on the stack. The `pathto' function does the work of finding the full path to a file. It simulates `gawk''s behavior when searching the `AWKPATH' -environment variable (*note The `AWKPATH' Environment Variable: AWKPATH -Variable.). If a file name has a `/' in it, no path search is done. -Otherwise, the file name is concatenated with the name of each -directory in the path, and an attempt is made to open the generated -file name. The only way to test if a file can be read in `awk' is to go -ahead and try to read it with `getline'; this is what `pathto' does.(2) -If the file can be read, it is closed and the file name is returned: +environment variable (*note AWKPATH Variable::). If a file name has a +`/' in it, no path search is done. Otherwise, the file name is +concatenated with the name of each directory in the path, and an +attempt is made to open the generated file name. The only way to test +if a file can be read in `awk' is to go ahead and try to read it with +`getline'; this is what `pathto' does.(2) If the file can be read, it +is closed and the file name is returned: expand_prog=' @@ -16460,7 +16424,7 @@ you can find more information. * Contributors:: The major contributors to `gawk'. -File: gawk.info, Node: V7/SVR3.1, Next: SVR4, Prev: Language History, Up: Language History +File: gawk.info, Node: V7/SVR3.1, Next: SVR4, Up: Language History Major Changes Between V7 and SVR3.1 =================================== @@ -16470,61 +16434,53 @@ Version 7 Unix (1978) and the new version that was first made generally available in System V Release 3.1 (1987). This minor node summarizes the changes, with cross-references to further details: - * The requirement for `;' to separate rules on a line (*note `awk' - Statements Versus Lines: Statements/Lines.). + * The requirement for `;' to separate rules on a line (*note + Statements/Lines::). * User-defined functions and the `return' statement (*note - User-Defined Functions: User-defined.). + User-defined::). - * The `delete' statement (*note The `delete' Statement: Delete.). + * The `delete' statement (*note Delete::). - * The `do'-`while' statement (*note The `do'-`while' Statement: Do - Statement.). + * The `do'-`while' statement (*note Do Statement::). * The built-in functions `atan2', `cos', `sin', `rand', and `srand' (*note Numeric Functions::). * The built-in functions `gsub', `sub', and `match' (*note String - Manipulation Functions: String Functions.). + Functions::). - * The built-in functions `close' and `system' (*note Input/Output - Functions: I/O Functions.). + * The built-in functions `close' and `system' (*note I/O + Functions::). * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP' built-in variables (*note Built-in Variables::). * The conditional expression using the ternary operator `?:' (*note - Conditional Expressions: Conditional Exp.). + Conditional Exp::). - * The exponentiation operator `^' (*note Arithmetic Operators: - Arithmetic Ops.) and its assignment operator form `^=' (*note - Assignment Expressions: Assignment Ops.). + * The exponentiation operator `^' (*note Arithmetic Ops::) and its + assignment operator form `^=' (*note Assignment Ops::). * C-compatible operator precedence, which breaks some old `awk' - programs (*note Operator Precedence (How Operators Nest): - Precedence.). + programs (*note Precedence::). - * Regexps as the value of `FS' (*note Specifying How Fields Are - Separated: Field Separators.) and as the third argument to the - `split' function (*note String Manipulation Functions: String - Functions.). + * Regexps as the value of `FS' (*note Field Separators::) and as the + third argument to the `split' function (*note String Functions::). * Dynamic regexps as operands of the `~' and `!~' operators (*note - How to Use Regular Expressions: Regexp Usage.). + Regexp Usage::). * The escape sequences `\b', `\f', and `\r' (*note Escape Sequences::). (Some vendors have updated their old versions of `awk' to recognize `\b', `\f', and `\r', but this is not something you can rely on.) - * Redirection of input for the `getline' function (*note Explicit - Input with `getline': Getline.). + * Redirection of input for the `getline' function (*note Getline::). - * Multiple `BEGIN' and `END' rules (*note The `BEGIN' and `END' - Special Patterns: BEGIN/END.). + * Multiple `BEGIN' and `END' rules (*note BEGIN/END::). - * Multidimensional arrays (*note Multidimensional Arrays: - Multi-dimensional.). + * Multidimensional arrays (*note Multi-dimensional::). File: gawk.info, Node: SVR4, Next: POSIX, Prev: V7/SVR3.1, Up: Language History @@ -16537,11 +16493,10 @@ features (some of which originated in `gawk'): * The `ENVIRON' variable (*note Built-in Variables::). - * Multiple `-f' options on the command line (*note Command-Line - Options: Options.). + * Multiple `-f' options on the command line (*note Options::). * The `-v' option for assigning variables before program execution - begins (*note Command-Line Options: Options.). + begins (*note Options::). * The `--' option for terminating command-line options. @@ -16552,24 +16507,21 @@ features (some of which originated in `gawk'): Numeric Functions::). * The `toupper' and `tolower' built-in string functions for case - translation (*note String Manipulation Functions: String - Functions.). + translation (*note String Functions::). * A cleaner specification for the `%c' format-control letter in the - `printf' function (*note Format-Control Letters: Control Letters.). + `printf' function (*note Control Letters::). * The ability to dynamically pass the field width and precision (`"%*.*d"') in the argument list of the `printf' function (*note - Format-Control Letters: Control Letters.). + Control Letters::). * The use of regexp constants, such as `/foo/', as expressions, where they are equivalent to using the matching operator, as in `$0 ~ - /foo/' (*note Using Regular Expression Constants: Using Constant - Regexps.). + /foo/' (*note Using Constant Regexps::). * Processing of escape sequences inside command-line variable - assignments (*note Assigning Variables on the Command Line: - Assignment Options.). + assignments (*note Assignment Options::). File: gawk.info, Node: POSIX, Next: BTL, Prev: SVR4, Up: Language History @@ -16581,14 +16533,13 @@ Changes Between SVR4 and POSIX `awk' introduced the following changes into the language: * The use of `-W' for implementation-specific options (*note - Command-Line Options: Options.). + Options::). * The use of `CONVFMT' for controlling the conversion of numbers to - strings (*note Conversion of Strings and Numbers: Conversion.). + strings (*note Conversion::). * The concept of a numeric string and tighter comparison rules to go - with it (*note Variable Typing and Comparison Expressions: Typing - and Comparison.). + with it (*note Typing and Comparison::). * More complete documentation of many of the previously undocumented features of the language. @@ -16600,24 +16551,22 @@ standard: Sequences::). * Newlines do not act as whitespace to separate fields when `FS' is - equal to a single space (*note Examining Fields: Fields.). + equal to a single space (*note Fields::). * Newlines are not allowed after `?' or `:' (*note Conditional - Expressions: Conditional Exp.). + Exp::). * The synonym `func' for the keyword `function' is not recognized - (*note Function Definition Syntax: Definition Syntax.). + (*note Definition Syntax::). * The operators `**' and `**=' cannot be used in place of `^' and - `^=' (*note Arithmetic Operators: Arithmetic Ops., and *Note - Assignment Expressions: Assignment Ops). + `^=' (*note Arithmetic Ops::, and *Note Assignment Ops::). * Specifying `-Ft' on the command line does not set the value of - `FS' to be a single TAB character (*note Specifying How Fields Are - Separated: Field Separators.). + `FS' to be a single TAB character (*note Field Separators::). - * The `fflush' built-in function is not supported (*note - Input/Output Functions: I/O Functions.). + * The `fflush' built-in function is not supported (*note I/O + Functions::). File: gawk.info, Node: BTL, Next: POSIX/GNU, Prev: POSIX, Up: Language History @@ -16626,25 +16575,24 @@ Extensions in the Bell Laboratories `awk' ========================================= Brian Kernighan, one of the original designers of Unix `awk', has -made his version available via his home page (*note Other Freely -Available `awk' Implementations: Other Versions.). This minor node -describes extensions in his version of `awk' that are not in POSIX -`awk': +made his version available via his home page (*note Other Versions::). +This minor node describes extensions in his version of `awk' that are +not in POSIX `awk': * The `-mf N' and `-mr N' command-line options to set the maximum number of fields and the maximum record size, respectively (*note - Command-Line Options: Options.). As a side note, his `awk' no - longer needs these options; it continues to accept them to avoid - breaking old programs. + Options::). As a side note, his `awk' no longer needs these + options; it continues to accept them to avoid breaking old + programs. * The `fflush' built-in function for flushing buffered output (*note - Input/Output Functions: I/O Functions.). + I/O Functions::). - * The `**' and `**=' operators (*note Arithmetic Operators: - Arithmetic Ops. and *Note Assignment Expressions: Assignment Ops). + * The `**' and `**=' operators (*note Arithmetic Ops:: and *Note + Assignment Ops::). * The use of `func' as an abbreviation for `function' (*note - Function Definition Syntax: Definition Syntax.). + Definition Syntax::). The Bell Laboratories `awk' also incorporates the following @@ -16653,17 +16601,15 @@ extensions, originally developed for `gawk': * The `\x' escape sequence (*note Escape Sequences::). * The `/dev/stdin', `/dev/stdout', and `/dev/stderr' special files - (*note Special File Names in `gawk': Special Files.). + (*note Special Files::). * The ability for `FS' and for the third argument to `split' to be - null strings (*note Making Each Character a Separate Field: Single - Character Fields.). + null strings (*note Single Character Fields::). - * The `nextfile' statement (*note Using `gawk''s `nextfile' - Statement: Nextfile Statement.). + * The `nextfile' statement (*note Nextfile Statement::). * The ability to delete all of an array at once with `delete ARRAY' - (*note The `delete' Statement: Delete.). + (*note Delete::). File: gawk.info, Node: POSIX/GNU, Next: Contributors, Prev: BTL, Up: Language History @@ -16674,44 +16620,38 @@ Extensions in `gawk' Not in POSIX `awk' The GNU implementation, `gawk', adds a large number of features. This minor node lists them in the order they were added to `gawk'. They can all be disabled with either the `--traditional' or `--posix' -options (*note Command-Line Options: Options.). +options (*note Options::). Version 2.10 of `gawk' introduced the following features: * The `AWKPATH' environment variable for specifying a path search for - the `-f' command-line option (*note Command-Line Options: - Options.). + the `-f' command-line option (*note Options::). - * The `IGNORECASE' variable and its effects (*note Case Sensitivity - in Matching: Case-sensitivity.). + * The `IGNORECASE' variable and its effects (*note + Case-sensitivity::). * The `/dev/stdin', `/dev/stdout', `/dev/stderr' and `/dev/fd/N' - special file names (*note Special File Names in `gawk': Special - Files.). + special file names (*note Special Files::). Version 2.13 of `gawk' introduced the following features: - * The `FIELDWIDTHS' variable and its effects (*note Reading - Fixed-Width Data: Constant Size.). + * The `FIELDWIDTHS' variable and its effects (*note Constant Size::). * The `systime' and `strftime' built-in functions for obtaining and - printing timestamps (*note Using `gawk''s Timestamp Functions: - Time Functions.). + printing timestamps (*note Time Functions::). * The `-W lint' option to provide error and portability checking for - both the source code and at runtime (*note Command-Line Options: - Options.). + both the source code and at runtime (*note Options::). * The `-W compat' option to turn off the GNU extensions (*note - Command-Line Options: Options.). + Options::). - * The `-W posix' option for full POSIX compliance (*note - Command-Line Options: Options.). + * The `-W posix' option for full POSIX compliance (*note Options::). Version 2.14 of `gawk' introduced the following feature: * The `next file' statement for skipping to the next data file - (*note Using `gawk''s `nextfile' Statement: Nextfile Statement.). + (*note Nextfile Statement::). Version 2.15 of `gawk' introduced the following features: @@ -16722,74 +16662,65 @@ options (*note Command-Line Options: Options.). `getline' returns -1 or `close' fails (*note Built-in Variables::). * The `/dev/pid', `/dev/ppid', `/dev/pgrpid', and `/dev/user' file - name interpretation (*note Special File Names in `gawk': Special - Files.). + name interpretation (*note Special Files::). * The ability to delete all of an array at once with `delete ARRAY' - (*note The `delete' Statement: Delete.). + (*note Delete::). * The ability to use GNU-style long-named options that start with - `--' (*note Command-Line Options: Options.). + `--' (*note Options::). * The `--source' option for mixing command-line and library-file - source code (*note Command-Line Options: Options.). + source code (*note Options::). Version 3.0 of `gawk' introduced the following features: * `IGNORECASE' changed, now applying to string comparison as well as - regexp operations (*note Case Sensitivity in Matching: - Case-sensitivity.). + regexp operations (*note Case-sensitivity::). * The `RT' variable that contains the input text that matched `RS' - (*note How Input Is Split into Records: Records.). + (*note Records::). - * Full support for both POSIX and GNU regexps (*note Regular - Expressions: Regexp.). + * Full support for both POSIX and GNU regexps (*note Regexp::). * The `gensub' function for more powerful text manipulation (*note - String Manipulation Functions: String Functions.). + String Functions::). * The `strftime' function acquired a default time format, allowing - it to be called with no arguments (*note Using `gawk''s Timestamp - Functions: Time Functions.). + it to be called with no arguments (*note Time Functions::). * The ability for `FS' and for the third argument to `split' to be - null strings (*note Making Each Character a Separate Field: Single - Character Fields.). + null strings (*note Single Character Fields::). - * The ability for `RS' to be a regexp (*note How Input Is Split into - Records: Records.). + * The ability for `RS' to be a regexp (*note Records::). - * The `next file' statement became `nextfile' (*note Using `gawk''s - `nextfile' Statement: Nextfile Statement.). + * The `next file' statement became `nextfile' (*note Nextfile + Statement::). * The `--lint-old' option to warn about constructs that are not available in the original Version 7 Unix version of `awk' (*note - Major Changes Between V7 and SVR3.1: V7/SVR3.1.). + V7/SVR3.1::). * The `-m' option and the `fflush' function from the Bell - Laboratories research version of `awk' (*note Command-Line - Options: Options.; also *note Input/Output Functions: I/O - Functions.). + Laboratories research version of `awk' (*note Options::; also + *note I/O Functions::). * The `--re-interval' option to provide interval expressions in - regexps (*note Regular Expression Operators: Regexp Operators.). + regexps (*note Regexp Operators::). * The `--traditional' option was added as a better name for - `--compat' (*note Command-Line Options: Options.). + `--compat' (*note Options::). * The use of GNU Autoconf to control the configuration process - (*note Compiling `gawk' for Unix: Quick Installation.). + (*note Quick Installation::). - * Amiga support (*note Installing `gawk' on an Amiga: Amiga - Installation.). + * Amiga support (*note Amiga Installation::). Version 3.1 of `gawk' introduced the following features: * The `BINMODE' special variable for non-POSIX systems, which allows - binary I/O for input and/or output files (*note Using `gawk' on PC - Operating Systems: PC Using.). + binary I/O for input and/or output files (*note PC Using::). * The `LINT' special variable, which dynamically controls lint warnings (*note Built-in Variables::). @@ -16799,88 +16730,81 @@ options (*note Command-Line Options: Options.). * The `TEXTDOMAIN' special variable for setting an application's internationalization text domain (*note Built-in Variables::, and - *Note Internationalization with `gawk': Internationalization). + *Note Internationalization::). * The ability to use octal and hexadecimal constants in `awk' - program source code (*note Octal and Hexadecimal Numbers: - Nondecimal-numbers.). + program source code (*note Nondecimal-numbers::). - * The `|&' operator for two-way I/O to a coprocess (*note Two-Way - Communications with Another Process: Two-way I/O.). + * The `|&' operator for two-way I/O to a coprocess (*note Two-way + I/O::). * The `/inet' special files for TCP/IP networking using `|&' (*note - Using `gawk' for Network Programming: TCP/IP Networking.). + TCP/IP Networking::). * The optional second argument to `close' that allows closing one end - of a two-way pipe to a coprocess (*note Two-Way Communications - with Another Process: Two-way I/O.). + of a two-way pipe to a coprocess (*note Two-way I/O::). * The optional third argument to the `match' function for capturing text-matching subexpressions within a regexp (*note String - Manipulation Functions: String Functions.). + Functions::). * Positional specifiers in `printf' formats for making translations - easier (*note Rearranging `printf' Arguments: Printf Ordering.). + easier (*note Printf Ordering::). - * The `asort' and `asorti' functions for sorting arrays (*note - Sorting Array Values and Indices with `gawk': Array Sorting.). + * The `asort' and `asorti' functions for sorting arrays (*note Array + Sorting::). * The `bindtextdomain', `dcgettext' and `dcngettext' functions for - internationalization (*note Internationalizing `awk' Programs: - Programmer i18n.). + internationalization (*note Programmer i18n::). * The `extension' built-in function and the ability to add new - built-in functions dynamically (*note Adding New Built-in - Functions to `gawk': Dynamic Extensions.). + built-in functions dynamically (*note Dynamic Extensions::). - * The `mktime' built-in function for creating timestamps (*note - Using `gawk''s Timestamp Functions: Time Functions.). + * The `mktime' built-in function for creating timestamps (*note Time + Functions::). * The `and', `or', `xor', `compl', `lshift', `rshift', and - `strtonum' built-in functions (*note Using `gawk''s Bit - Manipulation Functions: Bitwise Functions.). + `strtonum' built-in functions (*note Bitwise Functions::). * The support for `next file' as two words was removed completely - (*note Using `gawk''s `nextfile' Statement: Nextfile Statement.). + (*note Nextfile Statement::). * The `--dump-variables' option to print a list of all global - variables (*note Command-Line Options: Options.). + variables (*note Options::). * The `--gen-po' command-line option and the use of a leading - underscore to mark strings that should be translated (*note - Extracting Marked Strings: String Extraction.). + underscore to mark strings that should be translated (*note String + Extraction::). * The `--non-decimal-data' option to allow non-decimal input data - (*note Allowing Nondecimal Input Data: Nondecimal Data.). + (*note Nondecimal Data::). * The `--profile' option and `pgawk', the profiling version of `gawk', for producing execution profiles of `awk' programs (*note - Profiling Your `awk' Programs: Profiling.). + Profiling::). * The `--enable-portals' configuration option to enable special treatment of pathnames that begin with `/p' as BSD portals (*note - Using `gawk' with BSD Portals: Portal Files.). + Portal Files::). * The use of GNU Automake to help in standardizing the configuration - process (*note Compiling `gawk' for Unix: Quick Installation.). + process (*note Quick Installation::). * The use of GNU `gettext' for `gawk''s own message output (*note - `gawk' Can Speak Your Language: Gawk I18N.). + Gawk I18N::). - * BeOS support (*note Installing `gawk' on BeOS: BeOS Installation.). + * BeOS support (*note BeOS Installation::). - * Tandem support (*note Installing `gawk' on a Tandem: Tandem - Installation.). + * Tandem support (*note Tandem Installation::). - * The Atari port became officially unsupported (*note Installing - `gawk' on the Atari ST: Atari Installation.). + * The Atari port became officially unsupported (*note Atari + Installation::). * The source code now uses new-style function definitions, with `ansi2knr' to convert the code on systems with old compilers. * The `--disable-lint' configuration option to disable lint checking - at compile time (*note Additional Configuration Options: - Additional Configuration Options.). + at compile time (*note Additional Configuration Options::). @@ -16937,7 +16861,7 @@ Info file, in approximate chronological order: * Scott Deifik currently maintains the MS-DOS port. - * Juan Grigera maintains the port to Win32 systems. + * Juan Grigera maintains the port to Windows32 systems. * Dr. Darrel Hankerson acts as coordinator for the various ports to different PC platforms and creates binary distributions for @@ -16968,6 +16892,12 @@ Info file, in approximate chronological order: Isamu Hasegawa, of IBM in Japan, contributed support for multibyte characters. + Michael Benzinger contributed the initial code for `switch' + statements. + + Patrick T.J. McPhee contributed the code for dynamic loading in + Windows32 environments. + * Arnold Robbins has been working on `gawk' since 1988, at first helping David Trueman, and as the primary maintainer since around 1994. @@ -16981,8 +16911,8 @@ Installing `gawk' This appendix provides instructions for installing `gawk' on the various platforms that are supported by the developers. The primary developer supports GNU/Linux (and Unix), whereas the other ports are -contributed. *Note Reporting Problems and Bugs: Bugs, for the -electronic mail addresses of the people who did the respective ports. +contributed. *Note Bugs::, for the electronic mail addresses of the +people who did the respective ports. * Menu: @@ -16996,7 +16926,7 @@ electronic mail addresses of the people who did the respective ports. implementations. -File: gawk.info, Node: Gawk Distribution, Next: Unix Installation, Prev: Installation, Up: Installation +File: gawk.info, Node: Gawk Distribution, Next: Unix Installation, Up: Installation The `gawk' Distribution ======================= @@ -17011,7 +16941,7 @@ extract it, and then what is in the various files and subdirectories. * Distribution contents:: What is in the distribution. -File: gawk.info, Node: Getting, Next: Extracting, Prev: Gawk Distribution, Up: Gawk Distribution +File: gawk.info, Node: Getting, Next: Extracting, Up: Gawk Distribution Getting the `gawk' Distribution ------------------------------- @@ -17053,20 +16983,20 @@ Extracting the Distribution `gawk' is distributed as a `tar' file compressed with the GNU Zip program, `gzip'. - Once you have the distribution (for example, `gawk-3.1.2.tar.gz'), + Once you have the distribution (for example, `gawk-3.1.3.tar.gz'), use `gzip' to expand the file and then use `tar' to extract it. You can use the following pipeline to produce the `gawk' distribution: # Under System V, add 'o' to the tar options - gzip -d -c gawk-3.1.2.tar.gz | tar -xvpf - + gzip -d -c gawk-3.1.3.tar.gz | tar -xvpf - -This creates a directory named `gawk-3.1.2' in the current directory. +This creates a directory named `gawk-3.1.3' in the current directory. The distribution file name is of the form `gawk-V.R.P.tar.gz'. The V represents the major version of `gawk', the R represents the current release of version V, and the P represents a "patch level", meaning that minor bugs have been fixed in the release. The current patch -level is 2, but when retrieving distributions, you should get the +level is 3, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note, however, that patch levels greater than or equal to 80 denote "beta" or nonproduction software; you might not want to retrieve such a version @@ -17082,9 +17012,8 @@ Contents of the `gawk' Distribution The `gawk' distribution has a number of C source files, documentation files, subdirectories, and files related to the -configuration process (*note Compiling and Installing `gawk' on Unix: -Unix Installation.), as well as several subdirectories related to -different non-Unix operating systems: +configuration process (*note Unix Installation::), as well as several +subdirectories related to different non-Unix operating systems: Various `.c', `.y', and `.h' files The actual `gawk' source code. @@ -17161,8 +17090,7 @@ Various `.c', `.y', and `.h' files `doc/igawk.1' The `troff' source for a manual page describing the `igawk' - program presented in *Note An Easy Way to Use Library Functions: - Igawk Program. + program presented in *Note Igawk Program::. `doc/Makefile.in' The input file used during the configuration process to generate @@ -17184,8 +17112,8 @@ Various `.c', `.y', and `.h' files `missing_d/*' `m4/*' These files and subdirectories are used when configuring `gawk' - for various Unix systems. They are explained in *Note Compiling - and Installing `gawk' on Unix: Unix Installation. + for various Unix systems. They are explained in *Note Unix + Installation::. `intl/*' `po/*' @@ -17198,38 +17126,35 @@ Various `.c', `.y', and `.h' files `awklib/Makefile.in' `awklib/eg/*' The `awklib' directory contains a copy of `extract.awk' (*note - Extracting Programs from Texinfo Source Files: Extract Program.), - which can be used to extract the sample programs from the Texinfo - source file for this Info file. It also contains a `Makefile.in' - file, which `configure' uses to generate a `Makefile'. - `Makefile.am' is used by GNU Automake to create `Makefile.in'. - The library functions from *Note A Library of `awk' Functions: - Library Functions, and the `igawk' program from *Note An Easy Way - to Use Library Functions: Igawk Program, are included as - ready-to-use files in the `gawk' distribution. They are installed - as part of the installation process. The rest of the programs in - this Info file are available in appropriate subdirectories of - `awklib/eg'. + Extract Program::), which can be used to extract the sample + programs from the Texinfo source file for this Info file. It also + contains a `Makefile.in' file, which `configure' uses to generate + a `Makefile'. `Makefile.am' is used by GNU Automake to create + `Makefile.in'. The library functions from *Note Library + Functions::, and the `igawk' program from *Note Igawk Program::, + are included as ready-to-use files in the `gawk' distribution. + They are installed as part of the installation process. The rest + of the programs in this Info file are available in appropriate + subdirectories of `awklib/eg'. `unsupported/atari/*' - Files needed for building `gawk' on an Atari ST (*note Installing - `gawk' on the Atari ST: Atari Installation., for details). + Files needed for building `gawk' on an Atari ST (*note Atari + Installation::, for details). `unsupported/tandem/*' - Files needed for building `gawk' on a Tandem (*note Installing - `gawk' on a Tandem: Tandem Installation., for details). + Files needed for building `gawk' on a Tandem (*note Tandem + Installation::, for details). `posix/*' Files needed for building `gawk' on POSIX-compliant systems. `pc/*' Files needed for building `gawk' under MS-DOS, MS Windows and OS/2 - (*note Installation on PC Operating Systems: PC Installation., for - details). + (*note PC Installation::, for details). `vms/*' - Files needed for building `gawk' under VMS (*note How to Compile - and Install `gawk' on VMS: VMS Installation., for details). + Files needed for building `gawk' under VMS (*note VMS + Installation::, for details). `test/*' A test suite for `gawk'. You can use `make check' from the @@ -17254,13 +17179,13 @@ configure `gawk' for your system yourself. * Configuration Philosophy:: How it's all supposed to work. -File: gawk.info, Node: Quick Installation, Next: Additional Configuration Options, Prev: Unix Installation, Up: Unix Installation +File: gawk.info, Node: Quick Installation, Next: Additional Configuration Options, Up: Unix Installation Compiling `gawk' for Unix ------------------------- After you have extracted the `gawk' distribution, `cd' to -`gawk-3.1.2'. Like most GNU software, `gawk' is configured +`gawk-3.1.3'. Like most GNU software, `gawk' is configured automatically for your Unix system by running the `configure' program. This program is a Bourne shell script that is generated automatically using GNU `autoconf'. (The `autoconf' software is described fully @@ -17295,7 +17220,7 @@ run `make check'. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the `README_d' directory to see if you've found a known problem. If the failure is not described there, please send in a bug report (*note -Reporting Problems and Bugs: Bugs..) +Bugs::.) File: gawk.info, Node: Additional Configuration Options, Next: Configuration Philosophy, Prev: Quick Installation, Up: Unix Installation @@ -17308,8 +17233,11 @@ command line when compiling `gawk' from scratch, including: `--enable-portals' Treat pathnames that begin with `/p' as BSD portal files when - doing two-way I/O with the `|&' operator (*note Using `gawk' with - BSD Portals: Portal Files.). + doing two-way I/O with the `|&' operator (*note Portal Files::). + +`--enable-switch' + Enable the recognition and execution of C-style `switch' statements + in `awk' programs (*note Switch Statement::.) `--with-included-gettext' Use the version of the `gettext' library that comes with `gawk'. @@ -17319,10 +17247,9 @@ command line when compiling `gawk' from scratch, including: `--disable-lint' This option disables all lint checking within `gawk'. The - `--lint' and `--lint-old' options (*note Command-Line Options: - Options.) are accepted, but silently do nothing. Similarly, - setting the `LINT' variable (*note Built-in Variables That Control - `awk': User-modified.) has no effect on the running `awk' program. + `--lint' and `--lint-old' options (*note Options::) are accepted, + but silently do nothing. Similarly, setting the `LINT' variable + (*note User-modified::) has no effect on the running `awk' program. When used with GCC's automatic dead-code-elimination, this option cuts almost 200K bytes off the size of the `gawk' executable on @@ -17380,10 +17307,9 @@ is automatically included by `config.h'. `autoconf' will not work on your system in some other fashion. If you do have a problem, the file `configure.in' is the input for `autoconf'. You may be able to change this file and generate a new version of -`configure' that works on your system (*note Reporting Problems and -Bugs: Bugs., for information on how to report problems in configuring -`gawk'). The same mechanism may be used to send in updates to -`configure.in' and/or `custom.h'. +`configure' that works on your system (*note Bugs::, for information on +how to report problems in configuring `gawk'). The same mechanism may +be used to send in updates to `configure.in' and/or `custom.h'. File: gawk.info, Node: Non-Unix Installation, Next: Unsupported, Prev: Unix Installation, Up: Installation @@ -17403,7 +17329,7 @@ systems. * VMS Installation:: Installing `gawk' on VMS. -File: gawk.info, Node: Amiga Installation, Next: BeOS Installation, Prev: Non-Unix Installation, Up: Non-Unix Installation +File: gawk.info, Node: Amiga Installation, Next: BeOS Installation, Up: Non-Unix Installation Installing `gawk' on an Amiga ----------------------------- @@ -17433,8 +17359,7 @@ running `configure': configure -v m68k-amigaos Then run `make' and you should be all set! If these steps do not -work, please send in a bug report (*note Reporting Problems and Bugs: -Bugs.). +work, please send in a bug report (*note Bugs::). File: gawk.info, Node: BeOS Installation, Next: PC Installation, Prev: Amiga Installation, Up: Non-Unix Installation @@ -17466,7 +17391,7 @@ then `make install': BeOS uses `bash' as its shell; thus, you use `gawk' the same way you would under Unix. If these steps do not work, please send in a bug -report (*note Reporting Problems and Bugs: Bugs.). +report (*note Bugs::). File: gawk.info, Node: PC Installation, Next: VMS Installation, Prev: BeOS Installation, Up: Non-Unix Installation @@ -17476,26 +17401,28 @@ Installation on PC Operating Systems This minor node covers installation and usage of `gawk' on x86 machines running DOS, any version of Windows, or OS/2. In this minor -node, the term "Win32" refers to any of Windows-95/98/ME/NT/2000. +node, the term "Windows32" refers to any of Windows-95/98/ME/NT/2000. The limitations of DOS (and DOS shells under Windows or OS/2) has meant that various "DOS extenders" are often used with programs such as -`gawk'. The varying capabilities of Microsoft Windows 3.1 and Win32 -can add to the confusion. For an overview of the considerations, -please refer to `README_d/README.pc' in the distribution. +`gawk'. The varying capabilities of Microsoft Windows 3.1 and +Windows32 can add to the confusion. For an overview of the +considerations, please refer to `README_d/README.pc' in the +distribution. * Menu: * PC Binary Installation:: Installing a prepared distribution. -* PC Compiling:: Compiling `gawk' for MS-DOS, Win32, +* PC Compiling:: Compiling `gawk' for MS-DOS, Windows32, and OS/2. -* PC Using:: Running `gawk' on MS-DOS, Win32 and +* PC Dynamic:: Compiling `gawk' for dynamic libraries. +* PC Using:: Running `gawk' on MS-DOS, Windows32 and OS/2. * Cygwin:: Building and running `gawk' for Cygwin. -File: gawk.info, Node: PC Binary Installation, Next: PC Compiling, Prev: PC Installation, Up: PC Installation +File: gawk.info, Node: PC Binary Installation, Next: PC Compiling, Up: PC Installation Installing a Prepared Distribution for PC Systems ................................................. @@ -17533,23 +17460,23 @@ set properly. additional or more detailed installation instructions. -File: gawk.info, Node: PC Compiling, Next: PC Using, Prev: PC Binary Installation, Up: PC Installation +File: gawk.info, Node: PC Compiling, Next: PC Dynamic, Prev: PC Binary Installation, Up: PC Installation Compiling `gawk' for PC Operating Systems ......................................... - `gawk' can be compiled for MS-DOS, Win32, and OS/2 using the GNU + `gawk' can be compiled for MS-DOS, Windows32, and OS/2 using the GNU development tools from DJ Delorie (DJGPP; MS-DOS only) or Eberhard -Mattes (EMX; MS-DOS, Win32 and OS/2). Microsoft Visual C/C++ can be -used to build a Win32 version, and Microsoft C/C++ can be used to build -16-bit versions for MS-DOS and OS/2. (As of `gawk' 3.1.2, the MSC -version doesn't work. However, the maintainer is working on fixing it.) -The file `README_d/README.pc' in the `gawk' distribution contains +Mattes (EMX; MS-DOS, Windows32 and OS/2). Microsoft Visual C/C++ can +be used to build a Windows32 version, and Microsoft C/C++ can be used +to build 16-bit versions for MS-DOS and OS/2. (As of `gawk' 3.1.2, the +MSC version doesn't work. However, the maintainer is working on fixing +it.) The file `README_d/README.pc' in the `gawk' distribution contains additional notes, and `pc/Makefile' contains important information on compilation options. - To build `gawk' for MS-DOS, Win32, and OS/2 (16 bit only; for 32 bit -(EMX) you can use the `configure' script and skip the following + To build `gawk' for MS-DOS, Windows32, and OS/2 (16 bit only; for 32 +bit (EMX) you can use the `configure' script and skip the following paragraphs; for details see below), copy the files in the `pc' directory (_except_ for `ChangeLog') to the directory with the rest of the `gawk' sources. The `Makefile' contains a configuration section @@ -17557,9 +17484,9 @@ with comments and may need to be edited in order to work with your `make' utility. The `Makefile' contains a number of targets for building various -MS-DOS, Win32, and OS/2 versions. A list of targets is printed if the -`make' command is given without a target. As an example, to build `gawk' -using the DJGPP tools, enter `make djgpp'. +MS-DOS, Windows32, and OS/2 versions. A list of targets is printed if +the `make' command is given without a target. As an example, to build +`gawk' using the DJGPP tools, enter `make djgpp'. Using `make' to run the standard tests and to install `gawk' requires additional Unix-like tools, including `sh', `sed', and `cp'. @@ -17641,22 +17568,67 @@ version on `http://www.unixos2.org/sw/pub/binary/make/' or on `ftp://hobbes.nmsu.edu/pub/os2/'. -File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Compiling, Up: PC Installation +File: gawk.info, Node: PC Dynamic, Next: PC Using, Prev: PC Compiling, Up: PC Installation + +Compiling `gawk' For Dynamic Libraries +...................................... + + To compile `gawk' with dynamic extension support, uncomment the +definitions of `DYN_FLAGS', `DYN_EXP', `DYN_OBJ', and `DYN_MAKEXP' in +the configuration section of the `Makefile'. There are two definitions +for `DYN_MAKEXP': pick the one that matches your target. + + To build some of the example extension libraries, `cd' to the +extension directory and copy `Makefile.pc' to `Makefile'. You can then +build using the same two targets. To run the example `awk' scripts, +you'll need to either change the call to the `extension' function to +match the name of the library (for instance, change `"./ordchr.so"' to +`"ordchr.dll"' or simply `"ordchr"'), or rename the library to match +the call (for instance, rename `ordchr.dll' to `ordchr.so'). + + If you build `gawk.exe' with one compiler but want to build an +extension library with the other, you need to copy the import library. +Visual C uses a library called `gawk.lib', while MinGW uses a library +called `libgawk.a'. These files are equivalent and will interoperate if +you give them the correct name. The resulting shared libraries are +also interoperable. + + To create your own extension library, you can use the examples as +models, but you're essentially on your own. Post to `comp.lang.awk' or +send electronic mail to <ptjm@interlog.com> if you have problems getting +started. If you need to access functions or variables which are not +exported by `gawk.exe', add them to `gawkw32.def' and rebuild. You +should also add `ATTRIBUTE_EXPORTED' to the declaration in `awk.h' of +any variables you add to `gawkw32.def'. + + Note that extension libraries have the name of the `awk' executable +embedded in them at link time, so they will work only with `gawk.exe'. +In particular, they won't work if you rename `gawk.exe' to `awk.exe' or +if you try to use `pgawk.exe'. You can perform profiling by temporarily +renaming `pgawk.exe' to `gawk.exe'. You can resolve this problem by +changing the program name in the definition of `DYN_MAKEXP' for your +compiler. + + On Windows32, libraries are sought first in the current directory, +then in the directory containing `gawk.exe', and finally through the +`PATH' environment variable. + + +File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Dynamic, Up: PC Installation Using `gawk' on PC Operating Systems .................................... With the exception of the Cygwin environment, the `|&' operator and -TCP/IP networking (*note Using `gawk' for Network Programming: TCP/IP -Networking.) are not supported for MS-DOS or MS-Windows. EMX (OS/2 -only) does support at least the `|&' operator. +TCP/IP networking (*note TCP/IP Networking::) are not supported for +MS-DOS or MS-Windows. EMX (OS/2 only) does support at least the `|&' +operator. The OS/2 and MS-DOS versions of `gawk' search for program files as -described in *Note The `AWKPATH' Environment Variable: AWKPATH Variable. -However, semicolons (rather than colons) separate elements in the -`AWKPATH' variable. If `AWKPATH' is not set or is empty, then the -default search path for OS/2 (16 bit) and MS-DOS versions is -`".;c:/lib/awk;c:/gnu/lib/awk"'. +described in *Note AWKPATH Variable::. However, semicolons (rather +than colons) separate elements in the `AWKPATH' variable. If `AWKPATH' +is not set or is empty, then the default search path for OS/2 (16 bit) +and MS-DOS versions is `".;c:/lib/awk;c:/gnu/lib/awk"'. The search path for OS/2 (32 bit, EMX) is determined by the prefix directory (most likely `/usr' or `c:/usr') that has been specified as @@ -17706,16 +17678,16 @@ accomplished by using an appropriate `-v BINMODE=N' option on the command line. `BINMODE' is set at the time a file or pipe is opened and cannot be changed mid-stream. - The name `BINMODE' was chosen to match `mawk' (*note Other Freely -Available `awk' Implementations: Other Versions.). Both `mawk' and -`gawk' handle `BINMODE' similarly; however, `mawk' adds a `-W -BINMODE=N' option and an environment variable that can set `BINMODE', -`RS', and `ORS'. The files `binmode[1-3].awk' (under `gnu/lib/awk' in -some of the prepared distributions) have been chosen to match `mawk''s -`-W BINMODE=N' option. These can be changed or discarded; in -particular, the setting of `RS' giving the fewest "surprises" is open -to debate. `mawk' uses `RS = "\r\n"' if binary mode is set on read, -which is appropriate for files with the DOS-style end-of-line. + The name `BINMODE' was chosen to match `mawk' (*note Other +Versions::). Both `mawk' and `gawk' handle `BINMODE' similarly; +however, `mawk' adds a `-W BINMODE=N' option and an environment +variable that can set `BINMODE', `RS', and `ORS'. The files +`binmode[1-3].awk' (under `gnu/lib/awk' in some of the prepared +distributions) have been chosen to match `mawk''s `-W BINMODE=N' +option. These can be changed or discarded; in particular, the setting +of `RS' giving the fewest "surprises" is open to debate. `mawk' uses +`RS = "\r\n"' if binary mode is set on read, which is appropriate for +files with the DOS-style end-of-line. To illustrate, the following examples set binary mode on writes for standard output and other files, and set `ORS' as the "usual" DOS-style @@ -17752,8 +17724,8 @@ simulation of Unix, using the GNU tools, such as `bash', the GNU Compiler Collection (GCC), GNU Make, and other GNU tools. Compilation and installation for Cygwin is the same as for a Unix system: - tar -xvpzf gawk-3.1.2.tar.gz - cd gawk-3.1.2 + tar -xvpzf gawk-3.1.3.tar.gz + cd gawk-3.1.3 ./configure make @@ -17761,10 +17733,9 @@ and installation for Cygwin is the same as for a Unix system: on Cygwin takes considerably longer. However, it does finish, and then the `make' proceeds as usual. - *Note:* The `|&' operator and TCP/IP networking (*note Using `gawk' -for Network Programming: TCP/IP Networking.) are fully supported in -the Cygwin environment. This is not true for any other environment for -MS-DOS or MS-Windows. + *Note:* The `|&' operator and TCP/IP networking (*note TCP/IP +Networking::) are fully supported in the Cygwin environment. This is +not true for any other environment for MS-DOS or MS-Windows. ---------- Footnotes ---------- @@ -17786,7 +17757,7 @@ How to Compile and Install `gawk' on VMS * VMS POSIX:: Alternate instructions for VMS POSIX. -File: gawk.info, Node: VMS Compilation, Next: VMS Installation Details, Prev: VMS Installation, Up: VMS Installation +File: gawk.info, Node: VMS Compilation, Next: VMS Installation Details, Up: VMS Installation Compiling `gawk' on VMS ....................... @@ -17950,7 +17921,7 @@ longer supported. * Tandem Installation:: Installing `gawk' on a Tandem. -File: gawk.info, Node: Atari Installation, Next: Tandem Installation, Prev: Unsupported, Up: Unsupported +File: gawk.info, Node: Atari Installation, Next: Tandem Installation, Up: Unsupported Installing `gawk' on the Atari ST --------------------------------- @@ -17967,12 +17938,12 @@ exactly right). In order to use `gawk', you need to have a shell, either text or graphics, that does not map all the characters of a command line to uppercase. Maintaining case distinction in option flags is very -important (*note Command-Line Options: Options.). These days this is -the default and it may only be a problem for some very old machines. -If your system does not preserve the case of option flags, you need to -upgrade your tools. Support for I/O redirection is necessary to make -it easy to import `awk' programs from other environments. Pipes are -nice to have but not vital. +important (*note Options::). These days this is the default and it may +only be a problem for some very old machines. If your system does not +preserve the case of option flags, you need to upgrade your tools. +Support for I/O redirection is necessary to make it easy to import +`awk' programs from other environments. Pipes are nice to have but not +vital. * Menu: @@ -17980,7 +17951,7 @@ nice to have but not vital. * Atari Using:: Running `gawk' on Atari. -File: gawk.info, Node: Atari Compiling, Next: Atari Using, Prev: Atari Installation, Up: Atari Installation +File: gawk.info, Node: Atari Compiling, Next: Atari Using, Up: Atari Installation Compiling `gawk' on the Atari ST ................................ @@ -18008,7 +17979,7 @@ versions and possibly make adjustments. `atarist'. This basically assumes the TOS environment with `gcc'. Modify these sections as appropriate if they are not right for your environment. Also see the remarks about `AWKPATH' and `envsep' in -*Note Running `gawk' on the Atari ST: Atari Using. +*Note Atari Using::. As shipped, the sample `config.h' claims that the `system' function is missing from the libraries, which is not true, and an alternative @@ -18036,17 +18007,17 @@ nor `TMPDIR' are found, then `gawk' uses the current directory for its temporary files. The ST version of `gawk' searches for its program files, as -described in *Note The `AWKPATH' Environment Variable: AWKPATH Variable. -The default value for the `AWKPATH' variable is taken from `DEFPATH' -defined in `Makefile'. The sample `gcc'/TOS `Makefile' for the ST in -the distribution sets `DEFPATH' to `".,c:\lib\awk,c:\gnu\lib\awk"'. -The search path can be modified by explicitly setting `AWKPATH' to -whatever you want. Note that colons cannot be used on the ST to -separate elements in the `AWKPATH' variable, since they have another -reserved meaning. Instead, you must use a comma to separate elements -in the path. When recompiling, the separating character can be -modified by initializing the `envsep' variable in -`unsupported/atari/gawkmisc.atr' to another value. +described in *Note AWKPATH Variable::. The default value for the +`AWKPATH' variable is taken from `DEFPATH' defined in `Makefile'. The +sample `gcc'/TOS `Makefile' for the ST in the distribution sets +`DEFPATH' to `".,c:\lib\awk,c:\gnu\lib\awk"'. The search path can be +modified by explicitly setting `AWKPATH' to whatever you want. Note +that colons cannot be used on the ST to separate elements in the +`AWKPATH' variable, since they have another reserved meaning. Instead, +you must use a comma to separate elements in the path. When +recompiling, the separating character can be modified by initializing +the `envsep' variable in `unsupported/atari/gawkmisc.atr' to another +value. Although `awk' allows great flexibility in doing I/O redirections from within a program, this facility should be used with care on the ST @@ -18081,10 +18052,9 @@ no longer has access to a Tandem system. The Tandem port was done on a Cyclone machine running D20. The port is pretty clean and all facilities seem to work except for the I/O -piping facilities (*note Using `getline' from a Pipe: Getline/Pipe., -*Note Using `getline' into a Variable from a Pipe: -Getline/Variable/Pipe, and *Note Redirecting Output of `print' and -`printf': Redirection), which is just too foreign a concept for Tandem. +piping facilities (*note Getline/Pipe::, *Note Getline/Variable/Pipe::, +and *Note Redirection::), which is just too foreign a concept for +Tandem. To build a Tandem executable from source, download all of the files so that the file names on the Tandem box conform to the restrictions of @@ -18103,10 +18073,10 @@ filename/' must be used instead of the usual Unix `<' and `>' for file redirection. (Redirection options on `getline', `print' etc., are supported.) - The `-mr VAL' option (*note Command-Line Options: Options.) has -been "stolen" to enable Tandem users to process fixed-length records -with no "end-of-line" character. That is, `-mr 74' tells `gawk' to read -the input file as fixed 74-byte records. + The `-mr VAL' option (*note Options::) has been "stolen" to enable +Tandem users to process fixed-length records with no "end-of-line" +character. That is, `-mr 74' tells `gawk' to read the input file as +fixed 74-byte records. File: gawk.info, Node: Bugs, Next: Other Versions, Prev: Unsupported, Up: Installation @@ -18208,13 +18178,13 @@ Unix `awk' This version requires an ISO C (1990 standard) compiler; the C compiler from GCC (the GNU Compiler Collection) works quite nicely. - *Note Extensions in the Bell Laboratories `awk': BTL, for a list - of extensions in this `awk' that are not in POSIX `awk'. + *Note BTL::, for a list of extensions in this `awk' that are not + in POSIX `awk'. `mawk' Michael Brennan has written an independent implementation of `awk', - called `mawk'. It is available under the GPL (*note GNU General - Public License: Copying.), just as `gawk' is. + called `mawk'. It is available under the GPL (*note Copying::), + just as `gawk' is. You can get it via anonymous `ftp' to the host `ftp.whidbey.net'. Change directory to `/pub/brennan'. Use "binary" or "image" mode, @@ -18222,39 +18192,35 @@ Unix `awk' there). `gunzip' may be used to decompress this file. Installation is - similar to `gawk''s (*note Compiling and Installing `gawk' on - Unix: Unix Installation.). + similar to `gawk''s (*note Unix Installation::). `mawk' has the following extensions that are not in POSIX `awk': * The `fflush' built-in function for flushing buffered output - (*note Input/Output Functions: I/O Functions.). + (*note I/O Functions::). - * The `**' and `**=' operators (*note Arithmetic Operators: - Arithmetic Ops. and also see *Note Assignment Expressions: - Assignment Ops). + * The `**' and `**=' operators (*note Arithmetic Ops:: and also + see *Note Assignment Ops::). * The use of `func' as an abbreviation for `function' (*note - Function Definition Syntax: Definition Syntax.). + Definition Syntax::). * The `\x' escape sequence (*note Escape Sequences::). * The `/dev/stdout', and `/dev/stderr' special files (*note - Special File Names in `gawk': Special Files.). Use `"-"' - instead of `"/dev/stdin"' with `mawk'. + Special Files::). Use `"-"' instead of `"/dev/stdin"' with + `mawk'. * The ability for `FS' and for the third argument to `split' to - be null strings (*note Making Each Character a Separate - Field: Single Character Fields.). + be null strings (*note Single Character Fields::). * The ability to delete all of an array at once with `delete - ARRAY' (*note The `delete' Statement: Delete.). + ARRAY' (*note Delete::). - * The ability for `RS' to be a regexp (*note How Input Is Split - into Records: Records.). + * The ability for `RS' to be a regexp (*note Records::). * The `BINMODE' special variable for non-Unix operating systems - (*note Using `gawk' on PC Operating Systems: PC Using.). + (*note PC Using::). The next version of `mawk' will support `nextfile'. @@ -18273,10 +18239,9 @@ Unix `awk' `pawk' Nelson H.F. Beebe at the University of Utah has modified the Bell Labs `awk' to provide timing and profiling information. It is - different from `pgawk' (*note Profiling Your `awk' Programs: - Profiling.), in that it uses CPU-based profiling, not line-count - profiling. You may find it at either - `ftp://ftp.math.utah.edu/pub/pawk/pawk-20020210.tar.gz' or + different from `pgawk' (*note Profiling::), in that it uses + CPU-based profiling, not line-count profiling. You may find it at + either `ftp://ftp.math.utah.edu/pub/pawk/pawk-20020210.tar.gz' or `http://www.math.utah.edu/pub/pawk/pawk-20020210.tar.gz'. @@ -18304,15 +18269,15 @@ specifically to `gawk' and not to other implementations. * Future Extensions:: New features that may be implemented one day. -File: gawk.info, Node: Compatibility Mode, Next: Additions, Prev: Notes, Up: Notes +File: gawk.info, Node: Compatibility Mode, Next: Additions, Up: Notes Downward Compatibility and Debugging ==================================== - *Note Extensions in `gawk' Not in POSIX `awk': POSIX/GNU, for a -summary of the GNU extensions to the `awk' language and program. All -of these features can be turned off by invoking `gawk' with the -`--traditional' option or with the `--posix' option. + *Note POSIX/GNU::, for a summary of the GNU extensions to the `awk' +language and program. All of these features can be turned off by +invoking `gawk' with the `--traditional' option or with the `--posix' +option. If `gawk' is compiled for debugging with `-DDEBUG', then there is one more option available on the command line: @@ -18335,7 +18300,7 @@ Making Additions to `gawk' If you find that you want to enhance `gawk' in a significant fashion, you are perfectly free to do so. That is the point of having free software; the source code is available and you are free to change -it as you want (*note GNU General Public License: Copying.). +it as you want (*note Copying::). This minor node discusses the ways you might want to change `gawk' as well as any considerations you should bear in mind. @@ -18348,7 +18313,7 @@ as well as any considerations you should bear in mind. system. -File: gawk.info, Node: Adding Code, Next: New Ports, Prev: Additions, Up: Additions +File: gawk.info, Node: Adding Code, Next: New Ports, Up: Additions Adding New Features ------------------- @@ -18359,16 +18324,15 @@ distribution, there are several steps that you need to take in order to make it possible for me to include your changes: 1. Before building the new feature into `gawk' itself, consider - writing it as an extension module (*note Adding New Built-in - Functions to `gawk': Dynamic Extensions.). If that's not - possible, continue with the rest of the steps in this list. + writing it as an extension module (*note Dynamic Extensions::). + If that's not possible, continue with the rest of the steps in + this list. 2. Get the latest version. It is much easier for me to integrate changes if they are relative to the most recent distributed version of `gawk'. If your version of `gawk' is very old, I may - not be able to integrate them at all. (*Note Getting the `gawk' - Distribution: Getting, for information on getting the latest - version of `gawk'.) + not be able to integrate them at all. (*Note Getting::, for + information on getting the latest version of `gawk'.) 3. See *note (Version)Top:: standards, GNU Coding Standards. This document describes how GNU software should be written. If you @@ -18443,8 +18407,8 @@ make it possible for me to include your changes: changes in the public domain and submit a signed statement to that effect, or assign the copyright in your changes to the FSF. Both of these actions are easy to do and _many_ people have done so - already. If you have questions, please contact me (*note Reporting - Problems and Bugs: Bugs.), or <gnu@gnu.org>. + already. If you have questions, please contact me (*note Bugs::), + or <gnu@gnu.org>. 6. Update the documentation. Along with your new code, please supply new sections and/or chapters for this Info file. If at all @@ -18463,8 +18427,8 @@ make it possible for me to include your changes: with your version. (I find context diffs to be more readable but unified diffs are more compact.) I recommend using the GNU version of `diff'. Send the output produced by either run of - `diff' to me when you submit your changes. (*Note Reporting - Problems and Bugs: Bugs, for the electronic mail information.) + `diff' to me when you submit your changes. (*Note Bugs::, for the + electronic mail information.) Using this format makes it easy for me to apply your changes to the master version of the `gawk' source code (using `patch'). If I @@ -18489,8 +18453,8 @@ Porting `gawk' to a New Operating System If you want to port `gawk' to a new operating system, there are several steps: - 1. Follow the guidelines in *Note Adding New Features: Adding Code, - concerning coding style, submission of diffs, and so on. + 1. Follow the guidelines in *Note Adding Code::, concerning coding + style, submission of diffs, and so on. 2. When doing a port, bear in mind that your code must coexist peacefully with the rest of `gawk' and the other ports. Avoid @@ -18501,8 +18465,7 @@ several steps: If the changes needed for a particular system affect too much of the code, I probably will not accept them. In such a case, you can, of course, distribute your changes on your own, as long as - you comply with the GPL (*note GNU General Public License: - Copying.). + you comply with the GPL (*note Copying::). 3. A number of the files that come with `gawk' are maintained by other people at the Free Software Foundation. Thus, you should not @@ -18589,7 +18552,7 @@ have to re-do everything, perhaps from scratch, upon the next release. * Sample Library:: A example of new functions. -File: gawk.info, Node: Internals, Next: Sample Library, Prev: Dynamic Extensions, Up: Dynamic Extensions +File: gawk.info, Node: Internals, Next: Sample Library, Up: Dynamic Extensions A Minimal Introduction to `gawk' Internals ------------------------------------------ @@ -18718,8 +18681,10 @@ when writing extensions. The next minor node shows how they are used: An argument that is supposed to be an array needs to be handled with some extra code, in case the array being passed in is actually from a -function parameter. The following boilerplate code shows how to do -this: +function parameter. + + In versions of `gawk' up to and including 3.1.2, the following +boilerplate code shows how to do this: NODE *the_arg; @@ -18741,6 +18706,20 @@ this: the_arg->type = Node_var_array; assoc_clear(the_arg); + For versions 3.1.3 and later, the internals changed. In particular, +the interface was actually _simplified_ drastically. The following +boilerplate code now suffices: + + NODE *the_arg; + + the_arg = get_argument(tree, 2); /* assume need 3rd arg, 0-based */ + + /* force it to be an array: */ + the_arg = get_array(the_arg); + + /* if necessary, clear it: */ + assoc_clear(the_arg); + Again, you should spend time studying the `gawk' internals; don't just blindly copy this code. @@ -18762,7 +18741,7 @@ implements these functions for `gawk' in an external extension library. * Using Internal File Ops:: How to use an external extension. -File: gawk.info, Node: Internal File Description, Next: Internal File Ops, Prev: Sample Library, Up: Sample Library +File: gawk.info, Node: Internal File Description, Next: Internal File Ops, Up: Sample Library Using `chdir' and `stat' ........................ @@ -18833,7 +18812,7 @@ fails. It fills in the following elements: `"ctime"' The file's last access, modification, and inode update times, respectively. These are numeric timestamps, suitable for - formatting with `strftime' (*note Built-in Functions: Built-in.). + formatting with `strftime' (*note Built-in::). `"pmode"' The file's "printable mode." This is a string representation of @@ -18866,8 +18845,8 @@ fails. It fills in the following elements: Several additional elements may be present depending upon the operating system and the type of the file. You can test for them in -your `awk' program by using the `in' operator (*note Referring to an -Array Element: Reference to Elements.): +your `awk' program by using the `in' operator (*note Reference to +Elements::): `"blksize"' The preferred block size for I/O to the file. This field is not @@ -19174,13 +19153,13 @@ More `lint' warnings source code easier to work with: Loadable module mechanics - The current extension mechanism works (*note Adding New Built-in - Functions to `gawk': Dynamic Extensions.), but is rather - primitive. It requires a fair amount of manual work to create and - integrate a loadable module. Nor is the current mechanism as - portable as might be desired. The GNU `libtool' package provides - a number of features that would make using loadable modules much - easier. `gawk' should be changed to use `libtool'. + The current extension mechanism works (*note Dynamic Extensions::), + but is rather primitive. It requires a fair amount of manual work + to create and integrate a loadable module. Nor is the current + mechanism as portable as might be desired. The GNU `libtool' + package provides a number of features that would make using + loadable modules much easier. `gawk' should be changed to use + `libtool'. Loadable module internals The API to its internals that `gawk' "exports" should be revised. @@ -19222,8 +19201,8 @@ Compilation of `awk' programs Finally, the programs in the test suite could use documenting in this Info file. - *Note Making Additions to `gawk': Additions, if you are interested -in tackling any of these projects. + *Note Additions::, if you are interested in tackling any of these +projects. File: gawk.info, Node: Basic Concepts, Next: Glossary, Prev: Notes, Up: Top @@ -19245,7 +19224,7 @@ other introductory texts that you should refer to instead.) * Floating Point Issues:: Stuff to know about floating-point numbers. -File: gawk.info, Node: Basic High Level, Next: Basic Data Typing, Prev: Basic Concepts, Up: Basic Concepts +File: gawk.info, Node: Basic High Level, Next: Basic Data Typing, Up: Basic Concepts What a Program Does =================== @@ -19282,7 +19261,7 @@ Initialization These are the things you do before actually starting to process data, such as checking arguments, initializing any data you need to work with, and so on. This step corresponds to `awk''s `BEGIN' - rule (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.). + rule (*note BEGIN/END::). If you were baking a cake, this might consist of laying out all the mixing bowls and the baking pan, and making sure you have all the @@ -19295,8 +19274,7 @@ Processing In most programming languages, you have to manually manage the reading of data, checking to see if there is more each time you read a chunk. `awk''s pattern-action paradigm (*note Getting - Started with `awk': Getting Started.) handles the mechanics of - this for you. + Started::) handles the mechanics of this for you. In baking a cake, the processing corresponds to the actual labor: breaking eggs, mixing the flour, water, and other ingredients, and @@ -19305,7 +19283,7 @@ Processing Clean Up Once you've processed all the data, you may have things you need to do before exiting. This step corresponds to `awk''s `END' rule - (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.). + (*note BEGIN/END::). After the cake comes out of the oven, you still have to wrap it in plastic wrap to keep anyone from tasting it, as well as wash the @@ -19381,8 +19359,7 @@ larger range of values. The disadvantage is that there are numbers that they cannot represent exactly. `awk' uses "double-precision" floating-point numbers, which can hold more digits than "single-precision" floating-point numbers. Floating-point issues are -discussed more fully in *Note Floating-Point Number Caveats: Floating -Point Issues. +discussed more fully in *Note Floating Point Issues::. At the very lowest level, computers store values as groups of binary digits, or "bits". Modern computers group bits into groups of eight, @@ -19405,8 +19382,8 @@ or "binary", base 8 or "octal", and base 16 or "hexadecimal". In binary, each column represents two times the value in the column to its right. Each column may contain either a 0 or a 1. Thus, binary 1010 represents 1 times 8, plus 0 times 4, plus 1 times 2, plus 0 times 1, -or decimal 10. Octal and hexadecimal are discussed more in *Note Octal -and Hexadecimal Numbers: Nondecimal-numbers. +or decimal 10. Octal and hexadecimal are discussed more in *Note +Nondecimal-numbers::. Programs are written in programming languages. Hundreds, if not thousands, of programming languages exist. One of the most popular is @@ -19446,9 +19423,9 @@ but it does require a background in computer science. Internally, `awk' keeps both the numeric value (double-precision floating-point) and the string value for a variable. Separately, `awk' -keeps track of what type the variable has (*note Variable Typing and -Comparison Expressions: Typing and Comparison.), which plays a role in -how variables are used in comparisons. +keeps track of what type the variable has (*note Typing and +Comparison::), which plays a role in how variables are used in +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 @@ -19543,8 +19520,8 @@ Glossary Action A series of `awk' statements attached to a rule. If the rule's pattern matches an input record, `awk' executes the rule's action. - Actions are always enclosed in curly braces. (*Note Actions: - Action Overview.) + Actions are always enclosed in curly braces. (*Note Action + Overview::.) Amazing `awk' Assembler Henry Spencer at the University of Toronto wrote a retargetable @@ -19584,7 +19561,7 @@ Assignment An `awk' expression that changes the value of some `awk' variable or data object. An object that you can assign to is called an "lvalue". The assigned values are called "rvalues". *Note - Assignment Expressions: Assignment Ops. + Assignment Ops::. Associative Array Arrays in which the indices may be numbers or strings, not just @@ -19616,8 +19593,7 @@ Bit floating-point numbers, character data, addresses of other memory objects, or other data. `awk' lets you work with floating-point numbers and strings. `gawk' lets you manipulate bit values with - the built-in functions described in *Note Using `gawk''s Bit - Manipulation Functions: Bitwise Functions. + the built-in functions described in *Note Bitwise Functions::. Computers are often defined by how many bits they use to represent integer values. Typical systems are 32-bit systems, but 64-bit @@ -19640,7 +19616,7 @@ Built-in Function `sqrt' (for the square root of a number) and `substr' (for a substring of a string). `gawk' provides functions for timestamp management, bit manipulation, and runtime string translation. - (*Note Built-in Functions: Built-in.) + (*Note Built-in::.) Built-in Variable `ARGC', `ARGV', `CONVFMT', `ENVIRON', `FILENAME', `FNR', `FS', @@ -19698,29 +19674,26 @@ Compiler Compound Statement A series of `awk' statements, enclosed in curly braces. Compound - statements may be nested. (*Note Control Statements in Actions: - Statements.) + statements may be nested. (*Note Statements::.) Concatenation Concatenating two strings means sticking them together, one after another, producing a new string. For example, the string `foo' concatenated with the string `bar' gives the string `foobar'. - (*Note String Concatenation: Concatenation.) + (*Note Concatenation::.) Conditional Expression An expression using the `?:' ternary operator, such as `EXPR1 ? EXPR2 : EXPR3'. The expression EXPR1 is evaluated; if the result is true, the value of the whole expression is the value of EXPR2; otherwise the value is EXPR3. In either case, only one of EXPR2 - and EXPR3 is evaluated. (*Note Conditional Expressions: - Conditional Exp.) + and EXPR3 is evaluated. (*Note Conditional Exp::.) Comparison Expression A relation that is either true or false, such as `(a < b)'. Comparison expressions are used in `if', `while', `do', and `for' statements, and in patterns to select which input records to - process. (*Note Variable Typing and Comparison Expressions: - Typing and Comparison.) + process. (*Note Typing and Comparison::.) Curly Braces The characters `{' and `}'. Curly braces are used in `awk' for @@ -19740,7 +19713,7 @@ Data Driven Data Objects These are numbers and strings of characters. Numbers are converted into strings and vice versa, as needed. (*Note - Conversion of Strings and Numbers: Conversion.) + Conversion::.) Deadlock The situation in which two communicating processes are each waiting @@ -19757,7 +19730,7 @@ Dynamic Regular Expression A dynamic regular expression is a regular expression written as an ordinary expression. It could be a string constant, such as `"foo"', but it may also be an expression whose value can vary. - (*Note Using Dynamic Regexps: Computed Regexps.) + (*Note Computed Regexps::.) Environment A collection of strings, of the form NAME`='VAL, that each program @@ -19791,8 +19764,7 @@ Field change by setting the built-in variable `FS'). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable `FIELDWIDTHS' to describe their lengths. (*Note - Specifying How Fields Are Separated: Field Separators, and *Note - Reading Fixed-Width Data: Constant Size.) + Field Separators::, and *Note Constant Size::.) Flag A variable whose truth value indicates the existence or @@ -19808,8 +19780,7 @@ Format `strftime' and `sprintf' functions, and are used in the `printf' statement as well. Also, data conversions from numbers to strings are controlled by the format string contained in the built-in - variable `CONVFMT'. (*Note Format-Control Letters: Control - Letters.) + variable `CONVFMT'. (*Note Control Letters::.) Free Documentation License This document describes the terms under which this Info file is @@ -19835,8 +19806,7 @@ Free Software Foundation General Public License This document describes the terms under which `gawk' and its source - code may be distributed. (*Note GNU General Public License: - Copying.) + code may be distributed. (*Note Copying::.) GMT "Greenwich Mean Time." This is the old term for UTC. It is the @@ -19872,8 +19842,8 @@ I/O Input Record A single chunk of data that is read in by `awk'. Usually, an - `awk' input record consists of one line of text. (*Note How Input - Is Split into Records: Records.) + `awk' input record consists of one line of text. (*Note + Records::.) Integer A whole number, i.e., a number that does not have a fractional @@ -19975,7 +19945,7 @@ Pattern input is tested. If the condition is satisfied, the pattern is said to "match" the input record. A typical pattern might compare the input record against a regular expression. (*Note Pattern - Elements: Pattern Overview.) + Overview::.) POSIX The name for a series of standards that specify a Portable @@ -19994,12 +19964,12 @@ Private Variables and/or functions that are meant for use exclusively by library functions and not for the main `awk' program. Special care must be taken when naming such variables and functions. (*Note - Naming Library Function Global Variables: Library Names.) + Library Names::.) Range (of input lines) A sequence of consecutive lines from the input file(s). A pattern can specify ranges of input lines for `awk' to process or it can - specify single lines. (*Note Pattern Elements: Pattern Overview.) + specify single lines. (*Note Pattern Overview::.) Recursion When a function calls itself, either directly or indirectly. If @@ -20013,9 +19983,8 @@ Redirection You can redirect the output of the `print' and `printf' statements to a file or a system command, using the `>', `>>', `|', and `|&' operators. You can redirect input to the `getline' statement using - the `<', `|', and `|&' operators. (*Note Redirecting Output of - `print' and `printf': Redirection, and *Note Explicit Input with - `getline': Getline.) + the `<', `|', and `|&' operators. (*Note Redirection::, and *Note + Getline::.) Regexp Short for "regular expression". A regexp is a pattern that @@ -20023,7 +19992,7 @@ Regexp the regexp `R.*xp' matches any string starting with the letter `R' and ending with the letters `xp'. In `awk', regexps are used in patterns and in conditional expressions. Regexps may contain - escape sequences. (*Note Regular Expressions: Regexp.) + escape sequences. (*Note Regexp::.) Regular Expression See "regexp." @@ -20032,7 +20001,7 @@ Regular Expression Constant A regular expression constant is a regular expression written within slashes, such as `/foo/'. This regular expression is chosen when you write the `awk' program and cannot be changed during its - execution. (*Note How to Use Regular Expressions: Regexp Usage.) + execution. (*Note Regexp Usage::.) Rule A segment of an `awk' program that specifies how to process single @@ -20071,13 +20040,13 @@ Short-Circuit The nature of the `awk' logical operators `&&' and `||'. If the value of the entire expression is determinable from evaluating just the lefthand side of these operators, the righthand side is not - evaluated. (*Note Boolean Expressions: Boolean Ops.) + evaluated. (*Note Boolean Ops::.) Side Effect A side effect occurs when an expression has an effect aside from merely producing a value. Assignment expressions, increment and decrement expressions, and function calls have side effects. - (*Note Assignment Expressions: Assignment Ops.) + (*Note Assignment Ops::.) Single-Precision An internal representation of numbers that can have fractional @@ -20093,8 +20062,7 @@ Space Special File A file name interpreted internally by `gawk', instead of being handed directly to the underlying operating system--for example, - `/dev/stderr'. (*Note Special File Names in `gawk': Special - Files.) + `/dev/stderr'. (*Note Special Files::.) Stream Editor A program that reads records from an input stream and processes @@ -21016,6 +20984,7 @@ Index * --dump-variables option: Options. * --enable-portals configuration option <1>: Additional Configuration Options. * --enable-portals configuration option: Portal Files. +* --enable-switch configuration option: Additional Configuration Options. * --field-separator option: Options. * --file option: Options. * --gen-po option <1>: Options. @@ -21362,6 +21331,7 @@ Index * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. * beginfile user-defined function: Filetrans Function. * Bell Laboratories awk extensions: BTL. +* Benzinger, Michael: Contributors. * BeOS: BeOS Installation. * Berry, Karl: Acknowledgments. * binary input/output: User-modified. @@ -21421,6 +21391,7 @@ Index * caret (^), ^= operator <2>: Precedence. * caret (^), ^= operator: Assignment Ops. * caret (^), in character lists: Character Lists. +* case keyword: Switch Statement. * case sensitivity, array indices and: Array Intro. * case sensitivity, converting case: String Functions. * case sensitivity, example programs: Library Functions. @@ -21497,6 +21468,7 @@ Index * configuration option, --disable-lint: Additional Configuration Options. * configuration option, --disable-nls: Additional Configuration Options. * configuration option, --enable-portals: Additional Configuration Options. +* configuration option, --enable-switch: Additional Configuration Options. * configuration option, --with-included-gettext <1>: Additional Configuration Options. * configuration option, --with-included-gettext: Gawk I18N. * configuration options, gawk: Additional Configuration Options. @@ -21579,6 +21551,7 @@ Index * debugging gawk: Known Bugs. * debugging gawk, bug reports: Bugs. * decrement operators: Increment Ops. +* default keyword: Switch Statement. * Deifik, Scott <1>: Bugs. * Deifik, Scott <2>: Contributors. * Deifik, Scott: Acknowledgments. @@ -22219,6 +22192,7 @@ Index * matching, leftmost longest: Multiple Line. * matching, null strings: Gory Details. * mawk program: Other Versions. +* McPhee, Patrick: Contributors. * memory, releasing: Internals. * memory, setting limits: Options. * message object files: Explaining gettext. @@ -22473,7 +22447,6 @@ Index * POSIX awk, OFMT variable and <1>: Conversion. * POSIX awk, OFMT variable and: OFMT. * POSIX awk, period (.), using: Regexp Operators. -* POSIX awk, pipes, closing: Close Files And Pipes. * POSIX awk, printf format strings and: Format Modifiers. * POSIX awk, regular expressions and: Regexp Operators. * POSIX awk, timestamps and: Time Functions. @@ -22791,6 +22764,7 @@ Index * SUBSEP variable, multidimensional arrays: Multi-dimensional. * substr function: String Functions. * Sumner, Andrew: Other Versions. +* switch statement: Switch Statement. * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. * system function: I/O Functions. * systime function (gawk): Time Functions. @@ -22957,6 +22931,7 @@ Index * xor function (gawk): Bitwise Functions. * Zaretskii, Eli: Acknowledgments. * zero, negative vs. positive: Floating Point Issues. +* zerofile.awk program: Empty Files. * Zoulas, Christos: Contributors. * {} (braces), actions and: Action Overview. * {} (braces), pgawk program: Profiling. @@ -22984,343 +22959,346 @@ Index Tag Table: Node: Top1322 -Node: Foreword26566 -Node: Preface30890 -Ref: Preface-Footnote-133772 -Node: History34004 -Node: Names36263 -Ref: Names-Footnote-137772 -Node: This Manual37844 -Ref: This Manual-Footnote-143037 -Node: Conventions43137 -Node: Manual History45014 -Ref: Manual History-Footnote-148700 -Ref: Manual History-Footnote-248741 -Node: How To Contribute48815 -Node: Acknowledgments49413 -Node: Getting Started53218 -Node: Running gawk55611 -Node: One-shot56816 -Node: Read Terminal58073 -Ref: Read Terminal-Footnote-159722 -Node: Long59893 -Node: Executable Scripts61294 -Ref: Executable Scripts-Footnote-163190 -Ref: Executable Scripts-Footnote-263341 -Node: Comments63792 -Node: Quoting66184 -Node: Sample Data Files70162 -Node: Very Simple73240 -Node: Two Rules77860 -Node: More Complex80059 -Ref: More Complex-Footnote-182981 -Ref: More Complex-Footnote-283457 -Node: Statements/Lines83540 -Ref: Statements/Lines-Footnote-187899 -Node: Other Features88208 -Node: When89073 -Node: Regexp91062 -Node: Regexp Usage92515 -Node: Escape Sequences94606 -Node: Regexp Operators100518 -Ref: Regexp Operators-Footnote-1107710 -Ref: Regexp Operators-Footnote-2107857 -Node: Character Lists107955 -Node: GNU Regexp Operators112424 -Node: Case-sensitivity116045 -Ref: Case-sensitivity-Footnote-1119170 -Node: Leftmost Longest119405 -Node: Computed Regexps120719 -Node: Locales124126 -Node: Reading Files125575 -Node: Records127361 -Ref: Records-Footnote-1135677 -Node: Fields135714 -Ref: Fields-Footnote-1138769 -Node: Nonconstant Fields138855 -Node: Changing Fields141107 -Node: Field Separators146549 -Node: Regexp Field Splitting150093 -Node: Single Character Fields152594 -Node: Command Line Field Separator153657 -Node: Field Splitting Summary157108 -Ref: Field Splitting Summary-Footnote-1160331 -Node: Constant Size160432 -Node: Multiple Line165006 -Ref: Multiple Line-Footnote-1170787 -Node: Getline170966 -Node: Plain Getline173029 -Node: Getline/Variable175079 -Node: Getline/File176211 -Node: Getline/Variable/File177636 -Node: Getline/Pipe179259 -Node: Getline/Variable/Pipe181466 -Node: Getline/Coprocess182682 -Node: Getline/Variable/Coprocess183956 -Node: Getline Notes184704 -Node: Getline Summary186429 -Node: Printing187136 -Node: Print188850 -Node: Print Examples190231 -Node: Output Separators193128 -Node: OFMT194944 -Node: Printf196346 -Node: Basic Printf197260 -Node: Control Letters198844 -Node: Format Modifiers201431 -Node: Printf Examples206483 -Node: Redirection209253 -Node: Special Files215977 -Node: Special FD216606 -Node: Special Process219645 -Node: Special Network221931 -Node: Special Caveats222846 -Ref: Special Caveats-Footnote-1224056 -Node: Close Files And Pipes224439 -Ref: Close Files And Pipes-Footnote-1231853 -Ref: Close Files And Pipes-Footnote-2232001 -Node: Expressions232149 -Node: Constants234337 -Node: Scalar Constants235033 -Ref: Scalar Constants-Footnote-1235897 -Node: Nondecimal-numbers236079 -Node: Regexp Constants239255 -Node: Using Constant Regexps239719 -Node: Variables242879 -Node: Using Variables243530 -Node: Assignment Options245071 -Node: Conversion247011 -Ref: Conversion-Footnote-1250242 -Node: Arithmetic Ops250351 -Node: Concatenation252848 -Node: Assignment Ops255543 -Node: Increment Ops261859 -Node: Truth Values265347 -Node: Typing and Comparison266392 -Ref: Typing and Comparison-Footnote-1272946 -Node: Boolean Ops273091 -Node: Conditional Exp277199 -Node: Function Calls278995 -Node: Precedence281968 -Node: Patterns and Actions285412 -Node: Pattern Overview286465 -Node: Regexp Patterns288078 -Node: Expression Patterns288637 -Node: Ranges292243 -Node: BEGIN/END295344 -Node: Using BEGIN/END296084 -Ref: Using BEGIN/END-Footnote-1298869 -Node: I/O And BEGIN/END298983 -Node: Empty301322 -Node: Using Shell Variables301621 -Node: Action Overview303981 -Node: Statements306547 -Node: If Statement308253 -Node: While Statement309762 -Node: Do Statement311785 -Node: For Statement312925 -Node: Break Statement316113 -Node: Continue Statement318217 -Node: Next Statement320156 -Node: Nextfile Statement322545 -Node: Exit Statement325299 -Node: Built-in Variables327408 -Node: User-modified328498 -Ref: User-modified-Footnote-1336321 -Node: Auto-set336383 -Ref: Auto-set-Footnote-1344724 -Node: ARGC and ARGV344929 -Node: Arrays348791 -Node: Array Intro350721 -Node: Reference to Elements354991 -Node: Assigning Elements356876 -Node: Array Example357338 -Node: Scanning an Array359061 -Node: Delete361385 -Ref: Delete-Footnote-1363835 -Node: Numeric Array Subscripts363892 -Node: Uninitialized Subscripts366171 -Node: Multi-dimensional367793 -Node: Multi-scanning370840 -Node: Array Sorting372512 -Node: Functions375934 -Node: Built-in376668 -Node: Calling Built-in377651 -Node: Numeric Functions379626 -Ref: Numeric Functions-Footnote-1383366 -Ref: Numeric Functions-Footnote-2383692 -Node: String Functions383961 -Ref: String Functions-Footnote-1403266 -Ref: String Functions-Footnote-2403425 -Ref: String Functions-Footnote-3403672 -Node: Gory Details403759 -Ref: Gory Details-Footnote-1410346 -Ref: Gory Details-Footnote-2410397 -Node: I/O Functions410604 -Ref: I/O Functions-Footnote-1417281 -Node: Time Functions417372 -Ref: Time Functions-Footnote-1428146 -Ref: Time Functions-Footnote-2428214 -Ref: Time Functions-Footnote-3428372 -Ref: Time Functions-Footnote-4428483 -Ref: Time Functions-Footnote-5428608 -Ref: Time Functions-Footnote-6428867 -Node: Bitwise Functions429129 -Ref: Bitwise Functions-Footnote-1433827 -Node: I18N Functions434011 -Node: User-defined435755 -Node: Definition Syntax436531 -Node: Function Example440923 -Node: Function Caveats443564 -Node: Return Statement447464 -Node: Dynamic Typing450122 -Node: Internationalization450860 -Node: I18N and L10N452278 -Node: Explaining gettext452987 -Ref: Explaining gettext-Footnote-1457923 -Ref: Explaining gettext-Footnote-2458162 -Node: Programmer i18n458331 -Node: Translator i18n462677 -Node: String Extraction463462 -Ref: String Extraction-Footnote-1464464 -Node: Printf Ordering464590 -Ref: Printf Ordering-Footnote-1467381 -Node: I18N Portability467445 -Ref: I18N Portability-Footnote-1469883 -Node: I18N Example469946 -Ref: I18N Example-Footnote-1472583 -Node: Gawk I18N472655 -Node: Advanced Features473477 -Node: Nondecimal Data474909 -Node: Two-way I/O476516 -Ref: Two-way I/O-Footnote-1482093 -Node: TCP/IP Networking482170 -Node: Portal Files484633 -Node: Profiling485296 -Node: Invoking Gawk492922 -Node: Command Line494099 -Node: Options494899 -Ref: Options-Footnote-1506946 -Node: Other Arguments506971 -Node: AWKPATH Variable509723 -Ref: AWKPATH Variable-Footnote-1512506 -Node: Obsolete512766 -Node: Undocumented513847 -Node: Known Bugs514099 -Node: Library Functions514718 -Ref: Library Functions-Footnote-1517902 -Node: Library Names518073 -Ref: Library Names-Footnote-1521682 -Ref: Library Names-Footnote-2521901 -Node: General Functions521987 -Node: Nextfile Function522923 -Node: Assert Function527388 -Node: Round Function530719 -Node: Cliff Random Function532278 -Ref: Cliff Random Function-Footnote-1533261 -Node: Ordinal Functions533332 -Ref: Ordinal Functions-Footnote-1536406 -Node: Join Function536622 -Ref: Join Function-Footnote-1538426 -Node: Gettimeofday Function538626 -Node: Data File Management542404 -Node: Filetrans Function542965 -Node: Rewind Function546516 -Node: File Checking548140 -Node: Ignoring Assigns549186 -Node: Getopt Function550770 -Ref: Getopt Function-Footnote-1561919 -Node: Passwd Functions562120 -Ref: Passwd Functions-Footnote-1570859 -Node: Group Functions570947 -Node: Sample Programs579048 -Node: Running Examples579778 -Node: Clones580549 -Node: Cut Program581674 -Node: Egrep Program591539 -Ref: Egrep Program-Footnote-1599404 -Node: Id Program599514 -Node: Split Program603199 -Node: Tee Program606708 -Node: Uniq Program609379 -Node: Wc Program616889 -Ref: Wc Program-Footnote-1621203 -Node: Miscellaneous Programs621425 -Node: Dupword Program622414 -Node: Alarm Program624465 -Node: Translate Program629089 -Ref: Translate Program-Footnote-1633405 -Ref: Translate Program-Footnote-2633642 -Node: Labels Program633776 -Ref: Labels Program-Footnote-1637133 -Node: Word Sorting637217 -Node: History Sorting641520 -Node: Extract Program643389 -Node: Simple Sed650971 -Node: Igawk Program654168 -Ref: Igawk Program-Footnote-1669060 -Ref: Igawk Program-Footnote-2669261 -Node: Language History669399 -Node: V7/SVR3.1670766 -Node: SVR4673361 -Node: POSIX675008 -Node: BTL676796 -Node: POSIX/GNU678613 -Node: Contributors687441 -Node: Installation690693 -Node: Gawk Distribution691672 -Node: Getting692172 -Node: Extracting693418 -Node: Distribution contents694797 -Node: Unix Installation700394 -Node: Quick Installation700980 -Node: Additional Configuration Options702727 -Node: Configuration Philosophy704634 -Node: Non-Unix Installation707017 -Node: Amiga Installation707599 -Node: BeOS Installation708744 -Node: PC Installation709916 -Node: PC Binary Installation711049 -Node: PC Compiling712903 -Node: PC Using717416 -Node: Cygwin722134 -Ref: Cygwin-Footnote-1723147 -Node: VMS Installation723179 -Node: VMS Compilation723698 -Node: VMS Installation Details725287 -Node: VMS Running726904 -Node: VMS POSIX728488 -Node: Unsupported729752 -Node: Atari Installation730150 -Node: Atari Compiling731471 -Node: Atari Using733400 -Node: Tandem Installation736264 -Node: Bugs738070 -Node: Other Versions741355 -Ref: Other Versions-Footnote-1745386 -Node: Notes745428 -Node: Compatibility Mode746101 -Node: Additions746943 -Node: Adding Code747715 -Node: New Ports753888 -Node: Dynamic Extensions757991 -Node: Internals759007 -Node: Sample Library765343 -Node: Internal File Description765993 -Node: Internal File Ops769745 -Ref: Internal File Ops-Footnote-1775161 -Node: Using Internal File Ops775309 -Node: Future Extensions777330 -Node: Basic Concepts781477 -Node: Basic High Level782215 -Ref: Basic High Level-Footnote-1786376 -Node: Basic Data Typing786570 -Node: Floating Point Issues791060 -Ref: Floating Point Issues-Footnote-1794983 -Ref: Floating Point Issues-Footnote-2795036 -Node: Glossary795145 -Node: Copying819454 -Node: GNU Free Documentation License838651 -Node: Index861054 +Node: Foreword26888 +Node: Preface31212 +Ref: Preface-Footnote-134094 +Node: History34326 +Node: Names36541 +Ref: Names-Footnote-138016 +Node: This Manual38088 +Ref: This Manual-Footnote-142846 +Node: Conventions42946 +Node: Manual History44823 +Ref: Manual History-Footnote-148271 +Ref: Manual History-Footnote-248312 +Node: How To Contribute48386 +Node: Acknowledgments48984 +Node: Getting Started52789 +Node: Running gawk55160 +Node: One-shot56341 +Node: Read Terminal57557 +Ref: Read Terminal-Footnote-159206 +Node: Long59377 +Node: Executable Scripts60744 +Ref: Executable Scripts-Footnote-162640 +Ref: Executable Scripts-Footnote-262791 +Node: Comments63242 +Node: Quoting65601 +Node: Sample Data Files69515 +Node: Very Simple72548 +Node: Two Rules77148 +Node: More Complex79290 +Ref: More Complex-Footnote-182204 +Ref: More Complex-Footnote-282652 +Node: Statements/Lines82735 +Ref: Statements/Lines-Footnote-187094 +Node: Other Features87359 +Node: When88206 +Node: Regexp90173 +Node: Regexp Usage91626 +Node: Escape Sequences93673 +Node: Regexp Operators99413 +Ref: Regexp Operators-Footnote-1106515 +Ref: Regexp Operators-Footnote-2106662 +Node: Character Lists106760 +Node: GNU Regexp Operators111229 +Node: Case-sensitivity114795 +Ref: Case-sensitivity-Footnote-1117813 +Node: Leftmost Longest118048 +Node: Computed Regexps119234 +Node: Locales122641 +Node: Reading Files124668 +Node: Records126424 +Ref: Records-Footnote-1134517 +Node: Fields134554 +Ref: Fields-Footnote-1137578 +Node: Nonconstant Fields137664 +Node: Changing Fields139860 +Node: Field Separators145136 +Node: Regexp Field Splitting148619 +Node: Single Character Fields151075 +Node: Command Line Field Separator152117 +Node: Field Splitting Summary155547 +Ref: Field Splitting Summary-Footnote-1158730 +Node: Constant Size158831 +Node: Multiple Line163306 +Ref: Multiple Line-Footnote-1169011 +Node: Getline169190 +Node: Plain Getline171253 +Node: Getline/Variable173267 +Node: Getline/File174399 +Node: Getline/Variable/File175714 +Node: Getline/Pipe177264 +Node: Getline/Variable/Pipe179317 +Node: Getline/Coprocess180415 +Node: Getline/Variable/Coprocess181646 +Node: Getline Notes182351 +Node: Getline Summary183985 +Node: Printing184692 +Node: Print186320 +Node: Print Examples187641 +Node: Output Separators190421 +Node: OFMT192177 +Node: Printf193527 +Node: Basic Printf194441 +Node: Control Letters195967 +Node: Format Modifiers198654 +Node: Printf Examples203656 +Node: Redirection206364 +Node: Special Files212947 +Node: Special FD213576 +Node: Special Process216593 +Node: Special Network218799 +Node: Special Caveats219632 +Ref: Special Caveats-Footnote-1220821 +Node: Close Files And Pipes221204 +Ref: Close Files And Pipes-Footnote-1228105 +Ref: Close Files And Pipes-Footnote-2228253 +Node: Expressions228401 +Node: Constants230589 +Node: Scalar Constants231265 +Ref: Scalar Constants-Footnote-1232111 +Node: Nondecimal-numbers232293 +Node: Regexp Constants235345 +Node: Using Constant Regexps235809 +Node: Variables238891 +Node: Using Variables239542 +Node: Assignment Options241043 +Node: Conversion242911 +Ref: Conversion-Footnote-1247679 +Node: Arithmetic Ops247788 +Node: Concatenation250285 +Node: Assignment Ops252980 +Node: Increment Ops259186 +Node: Truth Values262674 +Node: Typing and Comparison263719 +Ref: Typing and Comparison-Footnote-1270152 +Node: Boolean Ops270297 +Node: Conditional Exp274291 +Node: Function Calls276021 +Node: Precedence278914 +Node: Patterns and Actions282332 +Node: Pattern Overview283385 +Node: Regexp Patterns284814 +Node: Expression Patterns285348 +Node: Ranges288889 +Node: BEGIN/END291969 +Node: Using BEGIN/END292709 +Ref: Using BEGIN/END-Footnote-1295428 +Node: I/O And BEGIN/END295542 +Node: Empty297796 +Node: Using Shell Variables298095 +Node: Action Overview300371 +Node: Statements302723 +Node: If Statement304574 +Node: While Statement306064 +Node: Do Statement308087 +Node: For Statement309227 +Node: Switch Statement312358 +Node: Break Statement314216 +Node: Continue Statement316264 +Node: Next Statement318159 +Node: Nextfile Statement320430 +Node: Exit Statement323018 +Node: Built-in Variables325078 +Node: User-modified326168 +Ref: User-modified-Footnote-1333402 +Node: Auto-set333464 +Ref: Auto-set-Footnote-1341317 +Node: ARGC and ARGV341522 +Node: Arrays345226 +Node: Array Intro347133 +Node: Reference to Elements351326 +Node: Assigning Elements353188 +Node: Array Example353650 +Node: Scanning an Array355373 +Node: Delete357640 +Ref: Delete-Footnote-1360017 +Node: Numeric Array Subscripts360074 +Node: Uninitialized Subscripts362256 +Node: Multi-dimensional363857 +Node: Multi-scanning366870 +Node: Array Sorting368478 +Node: Functions371826 +Node: Built-in372560 +Node: Calling Built-in373525 +Node: Numeric Functions375483 +Ref: Numeric Functions-Footnote-1379226 +Ref: Numeric Functions-Footnote-2379552 +Node: String Functions379821 +Ref: String Functions-Footnote-1399010 +Ref: String Functions-Footnote-2399139 +Ref: String Functions-Footnote-3399386 +Node: Gory Details399473 +Ref: Gory Details-Footnote-1406035 +Ref: Gory Details-Footnote-2406086 +Node: I/O Functions406293 +Ref: I/O Functions-Footnote-1412864 +Node: Time Functions412955 +Ref: Time Functions-Footnote-1423681 +Ref: Time Functions-Footnote-2423749 +Ref: Time Functions-Footnote-3423907 +Ref: Time Functions-Footnote-4424018 +Ref: Time Functions-Footnote-5424143 +Ref: Time Functions-Footnote-6424370 +Node: Bitwise Functions424632 +Ref: Bitwise Functions-Footnote-1429291 +Node: I18N Functions429475 +Node: User-defined431187 +Node: Definition Syntax431963 +Node: Function Example436313 +Node: Function Caveats438894 +Node: Return Statement442751 +Node: Dynamic Typing445409 +Node: Internationalization446147 +Node: I18N and L10N447565 +Node: Explaining gettext448245 +Ref: Explaining gettext-Footnote-1453152 +Ref: Explaining gettext-Footnote-2453391 +Node: Programmer i18n453560 +Node: Translator i18n457778 +Node: String Extraction458563 +Ref: String Extraction-Footnote-1459504 +Node: Printf Ordering459630 +Ref: Printf Ordering-Footnote-1462373 +Node: I18N Portability462437 +Ref: I18N Portability-Footnote-1464875 +Node: I18N Example464938 +Ref: I18N Example-Footnote-1467550 +Node: Gawk I18N467622 +Node: Advanced Features468444 +Node: Nondecimal Data469837 +Node: Two-way I/O471389 +Ref: Two-way I/O-Footnote-1476885 +Node: TCP/IP Networking476962 +Node: Portal Files479381 +Node: Profiling480018 +Node: Invoking Gawk487644 +Node: Command Line488821 +Node: Options489599 +Ref: Options-Footnote-1500961 +Node: Other Arguments500986 +Node: AWKPATH Variable503660 +Ref: AWKPATH Variable-Footnote-1506394 +Node: Obsolete506654 +Node: Undocumented507647 +Node: Known Bugs507899 +Node: Library Functions508491 +Ref: Library Functions-Footnote-1511470 +Node: Library Names511641 +Ref: Library Names-Footnote-1515107 +Ref: Library Names-Footnote-2515326 +Node: General Functions515412 +Node: Nextfile Function516348 +Node: Assert Function520713 +Node: Round Function524016 +Node: Cliff Random Function525528 +Ref: Cliff Random Function-Footnote-1526511 +Node: Ordinal Functions526582 +Ref: Ordinal Functions-Footnote-1529656 +Node: Join Function529872 +Ref: Join Function-Footnote-1531621 +Node: Gettimeofday Function531821 +Node: Data File Management535543 +Node: Filetrans Function536168 +Node: Rewind Function539598 +Node: File Checking541048 +Node: Empty Files542089 +Node: Ignoring Assigns544318 +Node: Getopt Function545860 +Ref: Getopt Function-Footnote-1556912 +Node: Passwd Functions557113 +Ref: Passwd Functions-Footnote-1565797 +Node: Group Functions565885 +Node: Sample Programs573907 +Node: Running Examples574581 +Node: Clones575302 +Node: Cut Program576427 +Node: Egrep Program586158 +Ref: Egrep Program-Footnote-1593942 +Node: Id Program594052 +Node: Split Program597683 +Node: Tee Program601150 +Node: Uniq Program603821 +Node: Wc Program611238 +Ref: Wc Program-Footnote-1615491 +Node: Miscellaneous Programs615686 +Node: Dupword Program616675 +Node: Alarm Program618695 +Node: Translate Program623271 +Ref: Translate Program-Footnote-1627526 +Ref: Translate Program-Footnote-2627763 +Node: Labels Program627897 +Ref: Labels Program-Footnote-1631222 +Node: Word Sorting631306 +Node: History Sorting635593 +Node: Extract Program637425 +Node: Simple Sed644799 +Node: Igawk Program647863 +Ref: Igawk Program-Footnote-1662668 +Ref: Igawk Program-Footnote-2662869 +Node: Language History663007 +Node: V7/SVR3.1664374 +Node: SVR4666449 +Node: POSIX667883 +Node: BTL669388 +Node: POSIX/GNU670907 +Node: Contributors677998 +Node: Installation681436 +Node: Gawk Distribution682388 +Node: Getting682867 +Node: Extracting684087 +Node: Distribution contents685466 +Node: Unix Installation690677 +Node: Quick Installation691263 +Node: Additional Configuration Options692956 +Node: Configuration Philosophy694905 +Node: Non-Unix Installation697260 +Node: Amiga Installation697842 +Node: BeOS Installation698929 +Node: PC Installation700073 +Node: PC Binary Installation701294 +Node: PC Compiling703124 +Node: PC Dynamic707660 +Node: PC Using710008 +Node: Cygwin714608 +Ref: Cygwin-Footnote-1715583 +Node: VMS Installation715615 +Node: VMS Compilation716134 +Node: VMS Installation Details717698 +Node: VMS Running719315 +Node: VMS POSIX720899 +Node: Unsupported722163 +Node: Atari Installation722561 +Node: Atari Compiling723841 +Node: Atari Using725713 +Node: Tandem Installation728545 +Node: Bugs730216 +Node: Other Versions733501 +Ref: Other Versions-Footnote-1737100 +Node: Notes737142 +Node: Compatibility Mode737815 +Node: Additions738604 +Node: Adding Code739349 +Node: New Ports745372 +Node: Dynamic Extensions749424 +Node: Internals750440 +Node: Sample Library757218 +Node: Internal File Description757868 +Node: Internal File Ops761548 +Ref: Internal File Ops-Footnote-1766964 +Node: Using Internal File Ops767112 +Node: Future Extensions769133 +Node: Basic Concepts773214 +Node: Basic High Level773952 +Ref: Basic High Level-Footnote-1777979 +Node: Basic Data Typing778173 +Node: Floating Point Issues782605 +Ref: Floating Point Issues-Footnote-1786485 +Ref: Floating Point Issues-Footnote-2786538 +Node: Glossary786647 +Node: Copying810256 +Node: GNU Free Documentation License829453 +Node: Index851856 End Tag Table |