diff options
| -rw-r--r-- | NEWS | 5 | ||||
| -rw-r--r-- | awklib/eg/data/BBS-list | 11 | ||||
| -rw-r--r-- | awklib/eg/data/mail-list | 11 | ||||
| -rw-r--r-- | doc/ChangeLog | 20 | ||||
| -rw-r--r-- | doc/gawk.info | 2371 | ||||
| -rw-r--r-- | doc/gawk.texi | 1074 | ||||
| -rw-r--r-- | doc/gawktexi.in | 1068 | ||||
| -rw-r--r-- | extension/ChangeLog | 6 | ||||
| -rw-r--r-- | extension/readfile.3am | 20 | ||||
| -rw-r--r-- | extension/readfile.c | 148 | ||||
| -rw-r--r-- | test/ChangeLog | 5 | ||||
| -rw-r--r-- | test/Makefile.am | 8 | ||||
| -rw-r--r-- | test/Makefile.in | 8 | ||||
| -rw-r--r-- | test/readfile2.awk | 12 | ||||
| -rw-r--r-- | test/readfile2.ok | 21 |
15 files changed, 2829 insertions, 1959 deletions
@@ -57,7 +57,10 @@ Changes from 4.1.0 to 4.1.1 If the thousands separator is a string, it will be correctly added to decimal numbers. -14. A number of bugs have been fixed. See the ChangeLog. +14. The readfile extension now has an input parser that will read whole + files as a single record. + +15. A number of bugs have been fixed. See the ChangeLog. Changes from 4.0.2 to 4.1.0 --------------------------- diff --git a/awklib/eg/data/BBS-list b/awklib/eg/data/BBS-list deleted file mode 100644 index 1007417f..00000000 --- a/awklib/eg/data/BBS-list +++ /dev/null @@ -1,11 +0,0 @@ -aardvark 555-5553 1200/300 B -alpo-net 555-3412 2400/1200/300 A -barfly 555-7685 1200/300 A -bites 555-1675 2400/1200/300 A -camelot 555-0542 300 C -core 555-2912 1200/300 C -fooey 555-1234 2400/1200/300 B -foot 555-6699 1200/300 B -macfoo 555-6480 1200/300 A -sdace 555-3430 2400/1200/300 A -sabafoo 555-2127 1200/300 C diff --git a/awklib/eg/data/mail-list b/awklib/eg/data/mail-list new file mode 100644 index 00000000..37ff350a --- /dev/null +++ b/awklib/eg/data/mail-list @@ -0,0 +1,11 @@ +Amelia 555-5553 amelia.zodiacusque@gmail.com F +Anthony 555-3412 anthony.asserturo@hotmail.com A +Becky 555-7685 becky.algebrarum@gmail.com A +Bill 555-1675 bill.drowning@hotmail.com A +Broderick 555-0542 broderick.aliquotiens@yahoo.com R +Camilla 555-2912 camilla.infusarum@skynet.be R +Fabius 555-1234 fabius.undevicesimus@ucb.edu F +Julie 555-6699 julie.perscrutabor@skeeve.com F +Martin 555-6480 martin.codicibus@hotmail.com A +Samuel 555-3430 samuel.lanceolis@shu.edu A +Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R diff --git a/doc/ChangeLog b/doc/ChangeLog index 0b34c55f..8d6166a8 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,23 @@ +2014-03-27 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Finish the massive indexing improvements such that + functions are indexed the way I want in TeX and the way Eli + wants in Info. + + Unrelated: + + * gawktexi.in: Add a note in extension chapter that lookup of + PROCINFO can fail. + +2014-03-27 Eli Zaretskii <eliz@gnu.org> + + * gawktexi.in: First round of massive indexing improvements. + +2014-03-27 Antonio Giovanni Colombo <azc100@gmail.com> + + * gawktexi.in: Redo all the examples using BBS-list to a different + file that doesn't use out-of-date concepts. + 2014-03-10 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Finish indexing improvements. (For now, anyway.) diff --git a/doc/gawk.info b/doc/gawk.info index 13f5ea77..4c1d5972 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1767,30 +1767,30 @@ File: gawk.info, Node: Sample Data Files, Next: Very Simple, Prev: Running ga =============================== Many of the examples in this Info file take their input from two sample -data files. The first, `BBS-list', represents a list of computer -bulletin board systems together with information about those systems. +data files. The first, `mail-list', represents a list of peoples' names +together with their email addresses and information about those people. The second data file, called `inventory-shipped', contains information about monthly shipments. In both files, each line is considered to be one "record". - In the data file `BBS-list', each record contains the name of a -computer bulletin board, its phone number, the board's baud rate(s), -and a code for the number of hours it is operational. An `A' in the -last column means the board operates 24 hours a day. A `B' in the last -column means the board only operates on evening and weekend hours. A -`C' means the board operates only on weekends: - - aardvark 555-5553 1200/300 B - alpo-net 555-3412 2400/1200/300 A - barfly 555-7685 1200/300 A - bites 555-1675 2400/1200/300 A - camelot 555-0542 300 C - core 555-2912 1200/300 C - fooey 555-1234 2400/1200/300 B - foot 555-6699 1200/300 B - macfoo 555-6480 1200/300 A - sdace 555-3430 2400/1200/300 A - sabafoo 555-2127 1200/300 C + In the data file `mail-list', each record contains the name of a +person, his/her phone number, his/her email-address, and a code for +their relationship with the author of the list. An `A' in the last +column means that the person is an acquaintance. An `F' in the last +column means that the person is a friend. An `R' means that the person +is a relative: + + Amelia 555-5553 amelia.zodiacusque@gmail.com F + Anthony 555-3412 anthony.asserturo@hotmail.com A + Becky 555-7685 becky.algebrarum@gmail.com A + Bill 555-1675 bill.drowning@hotmail.com A + Broderick 555-0542 broderick.aliquotiens@yahoo.com R + Camilla 555-2912 camilla.infusarum@skynet.be R + Fabius 555-1234 fabius.undevicesimus@ucb.edu F + Julie 555-6699 julie.perscrutabor@skeeve.com F + Martin 555-6480 martin.codicibus@hotmail.com A + Samuel 555-3430 samuel.lanceolis@shu.edu A + Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R The data file `inventory-shipped' represents information about shipments during the year. Each record contains the month, the number @@ -1827,32 +1827,32 @@ File: gawk.info, Node: Very Simple, Next: Two Rules, Prev: Sample Data Files, ======================== The following command runs a simple `awk' program that searches the -input file `BBS-list' for the character string `foo' (a grouping of +input file `mail-list' for the character string `li' (a grouping of characters is usually called a "string"; the term "string" is based on similar usage in English, such as "a string of pearls," or "a string of cars in a train"): - awk '/foo/ { print $0 }' BBS-list + awk '/li/ { print $0 }' mail-list -When lines containing `foo' are found, they are printed because +When lines containing `li' are found, they are printed because `print $0' means print the current line. (Just `print' by itself means 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 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. + You will notice that slashes (`/') surround the string `li' in the +`awk' program. The slashes indicate that `li' is the pattern to search +for. This type of pattern is called a "regular expression", 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: - $ awk '/foo/ { print $0 }' BBS-list - -| fooey 555-1234 2400/1200/300 B - -| foot 555-6699 1200/300 B - -| macfoo 555-6480 1200/300 A - -| sabafoo 555-2127 1200/300 C + $ awk '/li/ { print $0 }' mail-list + -| Amelia 555-5553 amelia.zodiacusque@gmail.com F + -| Broderick 555-0542 broderick.aliquotiens@yahoo.com R + -| Julie 555-6699 julie.perscrutabor@skeeve.com F + -| Samuel 555-3430 samuel.lanceolis@shu.edu A In an `awk' rule, either the pattern or the action can be omitted, but not both. If the pattern is omitted, then the action is performed @@ -1861,7 +1861,7 @@ is to print all lines that match the pattern. Thus, we could leave out the action (the `print' statement and the curly braces) in the previous example and the result would be the same: -`awk' prints all lines matching the pattern `foo'. By comparison, +`awk' prints all lines matching the pattern `li'. By comparison, omitting the `print' statement but retaining the curly braces makes an empty action that does nothing (i.e., no lines are printed). @@ -1967,25 +1967,19 @@ the string `21'. If a line contains both strings, it is printed twice, once by each rule. This is what happens if we run this program on our two sample data -files, `BBS-list' and `inventory-shipped': +files, `mail-list' and `inventory-shipped': $ awk '/12/ { print $0 } - > /21/ { print $0 }' BBS-list inventory-shipped - -| aardvark 555-5553 1200/300 B - -| alpo-net 555-3412 2400/1200/300 A - -| barfly 555-7685 1200/300 A - -| bites 555-1675 2400/1200/300 A - -| core 555-2912 1200/300 C - -| fooey 555-1234 2400/1200/300 B - -| foot 555-6699 1200/300 B - -| macfoo 555-6480 1200/300 A - -| sdace 555-3430 2400/1200/300 A - -| sabafoo 555-2127 1200/300 C - -| sabafoo 555-2127 1200/300 C + > /21/ { print $0 }' mail-list inventory-shipped + -| Anthony 555-3412 anthony.asserturo@hotmail.com A + -| Camilla 555-2912 camilla.infusarum@skynet.be R + -| Fabius 555-1234 fabius.undevicesimus@ucb.edu F + -| Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R + -| Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R -| Jan 21 36 64 620 -| Apr 21 70 74 514 -Note how the line beginning with `sabafoo' in `BBS-list' was printed +Note how the line beginning with `Jean-Paul' in `mail-list' was printed twice, once for each rule. @@ -2061,7 +2055,7 @@ Most often, each line in an `awk' program is a separate statement or separate rule, like this: awk '/12/ { print $0 } - /21/ { print $0 }' BBS-list inventory-shipped + /21/ { print $0 }' mail-list inventory-shipped However, `gawk' ignores newlines after any of the following symbols and keywords: @@ -2481,7 +2475,7 @@ The following list describes options mandated by the POSIX standard: `--bignum' Force arbitrary precision arithmetic on numbers. This option has no effect if `gawk' is not compiled to use the GNU MPFR and MP - libraries (*note Arbitrary Precision Arithmetic::). + libraries (*note Gawk and MPFR::). `-n' `--non-decimal-data' @@ -2749,13 +2743,14 @@ on the command-line with the `-f' option. In most `awk' implementations, you must supply a precise path name for each program file, unless the file is in the current directory. But in `gawk', if the file name supplied to the `-f' or `-i' options does not contain a -`/', then `gawk' searches a list of directories (called the "search -path"), one by one, looking for a file with the specified name. +directory separator `/', then `gawk' searches a list of directories +(called the "search path"), one by one, looking for a file with the +specified name. The search path is a string consisting of directory names separated by -colons. `gawk' gets its search path from the `AWKPATH' environment +colons(1). `gawk' gets its search path from the `AWKPATH' environment variable. If that variable does not exist, `gawk' uses a default path, -`.:/usr/local/share/awk'.(1) +`.:/usr/local/share/awk'.(2) The search path feature is particularly useful for building libraries of useful `awk' functions. The library files can be placed in a @@ -2796,7 +2791,9 @@ found, and `gawk' no longer needs to use `AWKPATH'. ---------- Footnotes ---------- - (1) Your version of `gawk' may use a different directory; it will + (1) Semicolons on MS-Windows and MS-DOS. + + (2) Your version of `gawk' may use a different directory; it will depend upon how `gawk' was built and installed. The actual directory is the value of `$(datadir)' generated when `gawk' was configured. You probably don't need to worry about this, though. @@ -3106,14 +3103,14 @@ A regular expression can be used as a pattern by enclosing it in slashes. Then the regular expression is tested against the entire text of each record. (Normally, it only needs to match some part of the text in order to succeed.) For example, the following prints the -second field of each record that contains the string `foo' anywhere in +second field of each record that contains the string `li' anywhere in it: - $ awk '/foo/ { print $2 }' BBS-list - -| 555-1234 + $ awk '/li/ { print $2 }' mail-list + -| 555-5553 + -| 555-0542 -| 555-6699 - -| 555-6480 - -| 555-2127 + -| 555-3430 Regular expressions can also be used in matching expressions. These expressions allow you to specify the string to match against; it need @@ -3921,67 +3918,82 @@ 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 - -changes the value of `RS' to `"/"', before reading any input. This is -a string whose first character is a slash; as a result, records are -separated by slashes. Then the input file is read, and the second rule -in the `awk' program (the action with no pattern) prints each record. -Because each `print' statement adds a newline at the end of its output, -this `awk' program copies the input with each slash changed to a -newline. Here are the results of running the program on `BBS-list': - - $ awk 'BEGIN { RS = "/" } - > { print $0 }' BBS-list - -| aardvark 555-5553 1200 - -| 300 B - -| alpo-net 555-3412 2400 - -| 1200 - -| 300 A - -| barfly 555-7685 1200 - -| 300 A - -| bites 555-1675 2400 - -| 1200 - -| 300 A - -| camelot 555-0542 300 C - -| core 555-2912 1200 - -| 300 C - -| fooey 555-1234 2400 - -| 1200 - -| 300 B - -| foot 555-6699 1200 - -| 300 B - -| macfoo 555-6480 1200 - -| 300 A - -| sdace 555-3430 2400 - -| 1200 - -| 300 A - -| sabafoo 555-2127 1200 - -| 300 C + awk 'BEGIN { RS = "u" } + { print $0 }' mail-list + +changes the value of `RS' to `u', before reading any input. This is a +string whose first character is the letter "u;" as a result, records +are separated by the letter "u." Then the input file is read, and the +second rule in the `awk' program (the action with no pattern) prints +each record. Because each `print' statement adds a newline at the end +of its output, this `awk' program copies the input with each `u' +changed to a newline. Here are the results of running the program on +`mail-list': + + $ awk 'BEGIN { RS = "u" } + > { print $0 }' mail-list + -| Amelia 555-5553 amelia.zodiac + -| sq + -| e@gmail.com F + -| Anthony 555-3412 anthony.assert + -| ro@hotmail.com A + -| Becky 555-7685 becky.algebrar + -| m@gmail.com A + -| Bill 555-1675 bill.drowning@hotmail.com A + -| Broderick 555-0542 broderick.aliq + -| otiens@yahoo.com R + -| Camilla 555-2912 camilla.inf + -| sar + -| m@skynet.be R + -| Fabi + -| s 555-1234 fabi + -| s. + -| ndevicesim + -| s@ + -| cb.ed + -| F + -| J + -| lie 555-6699 j + -| lie.perscr + -| tabor@skeeve.com F + -| Martin 555-6480 martin.codicib + -| s@hotmail.com A + -| Sam + -| el 555-3430 sam + -| el.lanceolis@sh + -| .ed + -| A + -| Jean-Pa + -| l 555-2127 jeanpa + -| l.campanor + -| m@ny + -| .ed + -| R -| -Note that the entry for the `camelot' BBS is not split. In the -original data file (*note Sample Data Files::), the line looks like -this: +Note that the entry for the name `Bill' is not split. In the original +data file (*note Sample Data Files::), the line looks like this: - camelot 555-0542 300 C + Bill 555-1675 bill.drowning@hotmail.com A -It has one baud rate only, so there are no slashes in the record, -unlike the others which have two or more baud rates. In fact, this -record is treated as part of the record for the `core' BBS; the newline +It contains no `u' so there is no reason to split the record, unlike +the others which have one or more occurrences of the `u'. In fact, +this record is treated as part of the previous record; the newline 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 Arguments::): - awk '{ print $0 }' RS="/" BBS-list + awk '{ print $0 }' RS="u" mail-list -This sets `RS' to `/' before processing `BBS-list'. +This sets `RS' to `u' before processing `mail-list'. - Using an unusual character such as `/' for the record separator -produces correct behavior in the vast majority of cases. + Using an alphabetic character such as `u' for the record separator +is highly likely to produce strange results. Using an unusual +character such as `/' is more likely to produce correct behavior in the +majority of cases, but there are no guarantees. The moral is: Know Your +Data. There is one unusual case, that occurs when `gawk' is being fully POSIX-compliant (*note Options::). Then, the following (extreme) @@ -4150,26 +4162,24 @@ get the empty string. (If used in a numeric operation, you get zero.) field, is a special case: it represents the whole input record when you are not interested in specific fields. Here are some more examples: - $ awk '$1 ~ /foo/ { print $0 }' BBS-list - -| fooey 555-1234 2400/1200/300 B - -| foot 555-6699 1200/300 B - -| macfoo 555-6480 1200/300 A - -| sabafoo 555-2127 1200/300 C + $ awk '$1 ~ /li/ { print $0 }' mail-list + -| Amelia 555-5553 amelia.zodiacusque@gmail.com F + -| Julie 555-6699 julie.perscrutabor@skeeve.com F -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 Regexp Usage::); it tests whether a string -(here, the field `$1') matches a given regular expression. +This example prints each record in the file `mail-list' whose first +field contains the string `li'. The operator `~' is called a "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 + By contrast, the following example looks for `li' in _the entire record_ and prints the first field and the last field for each matching input record: - $ awk '/foo/ { print $1, $NF }' BBS-list - -| fooey B - -| foot B - -| macfoo A - -| sabafoo C + $ awk '/li/ { print $1, $NF }' mail-list + -| Amelia F + -| Broderick R + -| Julie F + -| Samuel A ---------- Footnotes ---------- @@ -4197,16 +4207,16 @@ For the twentieth record, field number 20 is printed; most likely, the record has fewer than 20 fields, so this prints a blank line. Here is another example of using expressions as field numbers: - awk '{ print $(2*2) }' BBS-list + awk '{ print $(2*2) }' mail-list `awk' evaluates the expression `(2*2)' and uses its value as the number of the field to print. The `*' sign represents multiplication, so the expression `2*2' evaluates to four. The parentheses are used so that the multiplication is done before the `$' operation; they are 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 +expression. This example, then, prints the type of relationship (the +fourth field) for every line of the file `mail-list'. (All of the +`awk' operators are listed, in order of decreasing precedence, in *note Precedence::.) If the field number you compute is zero, you get the entire record. @@ -4603,53 +4613,46 @@ type `-F\t' at the shell, without any quotes, the `\' gets deleted, so 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 an example, let's use an `awk' program file called `baud.awk' -that contains the pattern `/300/' and the action `print $1': + As an example, let's use an `awk' program file called `edu.awk' that +contains the pattern `/edu/' and the action `print $1': - /300/ { print $1 } + /edu/ { print $1 } Let's also set `FS' to be the `-' character and run the program on -the file `BBS-list'. The following command prints a list of the names -of the bulletin boards that operate at 300 baud and the first three +the file `mail-list'. The following command prints a list of the names +of the people that work at or attend a university, and the first three digits of their phone numbers: - $ awk -F- -f baud.awk BBS-list - -| aardvark 555 - -| alpo - -| barfly 555 - -| bites 555 - -| camelot 555 - -| core 555 - -| fooey 555 - -| foot 555 - -| macfoo 555 - -| sdace 555 - -| sabafoo 555 - -Note the second line of output. The second line in the original file + $ awk -F- -f edu.awk mail-list + -| Fabius 555 + -| Samuel 555 + -| Jean + +Note the third line of output. The third line in the original file looked like this: - alpo-net 555-3412 2400/1200/300 A + Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R - The `-' as part of the system's name was used as the field + The `-' as part of the person's name was used as the field separator, instead of the `-' in the phone number that was originally intended. This demonstrates why you have to be careful in choosing your field and record separators. Perhaps the most common use of a single character as the field separator occurs when processing the Unix system password file. On -many Unix systems, each user has a separate entry in the system password -file, one line per user. The information in these lines is separated -by colons. The first field is the user's login name and the second is -the user's (encrypted or shadow) password. A password file entry might -look like this: +many Unix systems, each user has a separate entry in the system +password file, one line per user. The information in these lines is +separated by colons. The first field is the user's login name and the +second is the user's encrypted or shadow password. (A shadow password +is indicated by the presence of a single `x' in the second field.) A +password file entry might look like this: - arnold:xyzzy:2076:10:Arnold Robbins:/home/arnold:/bin/bash + arnold:x:2076:10:Arnold Robbins:/home/arnold:/bin/bash The following program searches the system password file and prints -the entries for users who have no password: +the entries for users whose full name is not indicated: - awk -F: '$2 == ""' /etc/passwd + awk -F: '$5 == ""' /etc/passwd File: gawk.info, Node: Full Line Fields, Next: Field Splitting Summary, Prev: Command Line Field Separator, Up: Field Separators @@ -5835,13 +5838,29 @@ prints the first and second fields of each input record, separated by a semicolon, with a blank line added after each newline: $ awk 'BEGIN { OFS = ";"; ORS = "\n\n" } - > { print $1, $2 }' BBS-list - -| aardvark;555-5553 + > { print $1, $2 }' mail-list + -| Amelia;555-5553 -| - -| alpo-net;555-3412 + -| Anthony;555-3412 + -| + -| Becky;555-7685 + -| + -| Bill;555-1675 + -| + -| Broderick;555-0542 + -| + -| Camilla;555-2912 + -| + -| Fabius;555-1234 + -| + -| Julie;555-6699 + -| + -| Martin;555-6480 + -| + -| Samuel;555-3430 + -| + -| Jean-Paul;555-2127 -| - -| barfly;555-7685 - ... If the value of `ORS' does not contain a newline, the program's output runs together on a single line. @@ -6210,25 +6229,25 @@ File: gawk.info, Node: Printf Examples, Prev: Format Modifiers, Up: Printf The following simple example shows how to use `printf' to make an aligned table: - awk '{ printf "%-10s %s\n", $1, $2 }' BBS-list + awk '{ printf "%-10s %s\n", $1, $2 }' mail-list -This command prints the names of the bulletin boards (`$1') in the file -`BBS-list' as a string of 10 characters that are left-justified. It +This command prints the names of the people (`$1') in the file +`mail-list' as a string of 10 characters that are left-justified. It also prints the phone numbers (`$2') next on the line. This produces an aligned two-column table of names and phone numbers, as shown here: - $ awk '{ printf "%-10s %s\n", $1, $2 }' BBS-list - -| aardvark 555-5553 - -| alpo-net 555-3412 - -| barfly 555-7685 - -| bites 555-1675 - -| camelot 555-0542 - -| core 555-2912 - -| fooey 555-1234 - -| foot 555-6699 - -| macfoo 555-6480 - -| sdace 555-3430 - -| sabafoo 555-2127 + $ awk '{ printf "%-10s %s\n", $1, $2 }' mail-list + -| Amelia 555-5553 + -| Anthony 555-3412 + -| Becky 555-7685 + -| Bill 555-1675 + -| Broderick 555-0542 + -| Camilla 555-2912 + -| Fabius 555-1234 + -| Julie 555-6699 + -| Martin 555-6480 + -| Samuel 555-3430 + -| Jean-Paul 555-2127 In this case, the phone numbers had to be printed as strings because the numbers are separated by a dash. Printing the phone numbers as @@ -6246,14 +6265,14 @@ beginning of the `awk' program: awk 'BEGIN { print "Name Number" print "---- ------" } - { printf "%-10s %s\n", $1, $2 }' BBS-list + { printf "%-10s %s\n", $1, $2 }' mail-list The above example mixes `print' and `printf' statements in the same program. Using just `printf' statements can produce the same results: awk 'BEGIN { printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" } - { printf "%-10s %s\n", $1, $2 }' BBS-list + { printf "%-10s %s\n", $1, $2 }' mail-list Printing each column heading with the same format specification used for the column elements ensures that the headings are aligned just like @@ -6265,7 +6284,7 @@ be emphasized by storing it in a variable, like this: awk 'BEGIN { format = "%-10s %s\n" printf format, "Name", "Number" printf format, "----", "------" } - { printf format, $1, $2 }' BBS-list + { printf format, $1, $2 }' mail-list At this point, it would be a worthwhile exercise to use the `printf' statement to line up the headings and table data for the @@ -6305,19 +6324,19 @@ work identically for `printf': the same OUTPUT-FILE do not erase OUTPUT-FILE, but append to it. (This is different from how you use redirections in shell scripts.) If OUTPUT-FILE does not exist, it is created. For example, here - is how an `awk' program can write a list of BBS names to one file - named `name-list', and a list of phone numbers to another file + is how an `awk' program can write a list of peoples' names to one + file named `name-list', and a list of phone numbers to another file named `phone-list': $ awk '{ print $2 > "phone-list" - > print $1 > "name-list" }' BBS-list + > print $1 > "name-list" }' mail-list $ cat phone-list -| 555-5553 -| 555-3412 ... $ cat name-list - -| aardvark - -| alpo-net + -| Amelia + -| Anthony ... Each output file contains one name or number per line. @@ -6338,12 +6357,12 @@ work identically for `printf': The redirection argument COMMAND is actually an `awk' expression. Its value is converted to a string whose contents give the shell command to be run. For example, the following produces two files, - one unsorted list of BBS names, and one list sorted in reverse + one unsorted list of peoples' names, and one list sorted in reverse alphabetical order: awk '{ print $1 > "names.unsorted" command = "sort -r > names.sorted" - print $1 | command }' BBS-list + print $1 | command }' mail-list The unsorted list is written with an ordinary redirection, while the sorted list is written by piping through the `sort' utility. @@ -7073,16 +7092,16 @@ 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 + awk '{ print $n }' n=4 inventory-shipped n=2 mail-list prints the value of field number `n' for all input records. Before the first file is read, the command line sets the variable `n' equal to four. This causes the fourth field to be printed in lines from `inventory-shipped'. After the first file has finished, but before the second file is started, `n' is set to two, so that the second field is -printed in lines from `BBS-list': +printed in lines from `mail-list': - $ awk '{ print $n }' n=4 inventory-shipped n=2 BBS-list + $ awk '{ print $n }' n=4 inventory-shipped n=2 mail-list -| 15 -| 24 ... @@ -7343,17 +7362,17 @@ a specific operator to represent it. Instead, concatenation is performed by writing expressions next to one another, with no operator. For example: - $ awk '{ print "Field number one: " $1 }' BBS-list - -| Field number one: aardvark - -| Field number one: alpo-net + $ awk '{ print "Field number one: " $1 }' mail-list + -| Field number one: Amelia + -| Field number one: Anthony ... Without the space in the string constant after the `:', the line runs together. For example: - $ awk '{ print "Field number one:" $1 }' BBS-list - -| Field number one:aardvark - -| Field number one:alpo-net + $ awk '{ print "Field number one:" $1 }' mail-list + -| Field number one:Amelia + -| Field number one:Anthony ... Because string concatenation does not have an explicit operator, it @@ -7999,9 +8018,9 @@ Boolean operators are: `BOOLEAN1 && BOOLEAN2' True if both BOOLEAN1 and BOOLEAN2 are true. For example, the following statement prints the current input record if it contains - both `2400' and `foo': + both `edu' and `li': - if ($0 ~ /2400/ && $0 ~ /foo/) print + if ($0 ~ /edu/ && $0 ~ /li/) print The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is true. This can make a difference when BOOLEAN2 contains expressions that @@ -8012,9 +8031,9 @@ Boolean operators are: `BOOLEAN1 || BOOLEAN2' True if at least one of BOOLEAN1 or BOOLEAN2 is true. For example, the following statement prints all records in the input - that contain _either_ `2400' or `foo' or both: + that contain _either_ `edu' or `li' or both: - if ($0 ~ /2400/ || $0 ~ /foo/) print + if ($0 ~ /edu/ || $0 ~ /li/) print The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is false. This can make a difference when BOOLEAN2 contains expressions that @@ -8434,56 +8453,53 @@ 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': +precisely `li': - $ awk '$1 == "foo" { print $2 }' BBS-list + $ awk '$1 == "li" { print $2 }' mail-list -(There is no output, because there is no BBS site with the exact name -`foo'.) Contrast this with the following regular expression match, -which accepts any record with a first field that contains `foo': +(There is no output, because there is no person with the exact name +`li'.) Contrast this with the following regular expression match, which +accepts any record with a first field that contains `li': - $ awk '$1 ~ /foo/ { print $2 }' BBS-list - -| 555-1234 + $ awk '$1 ~ /foo/ { print $2 }' mail-list + -| 555-5553 -| 555-6699 - -| 555-6480 - -| 555-2127 A regexp constant as a pattern is also a special case of an -expression pattern. The expression `/foo/' has the value one if `foo' -appears in the current input record. Thus, as a pattern, `/foo/' -matches any record containing `foo'. +expression pattern. The expression `/li/' has the value one if `li' +appears in the current input record. Thus, as a pattern, `/li/' matches +any record containing `li'. Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions match. For example, the following command prints all the records in -`BBS-list' that contain both `2400' and `foo': - - $ awk '/2400/ && /foo/' BBS-list - -| fooey 555-1234 2400/1200/300 B - - The following command prints all records in `BBS-list' that contain -_either_ `2400' or `foo' (or both, of course): - - $ awk '/2400/ || /foo/' BBS-list - -| alpo-net 555-3412 2400/1200/300 A - -| bites 555-1675 2400/1200/300 A - -| fooey 555-1234 2400/1200/300 B - -| foot 555-6699 1200/300 B - -| macfoo 555-6480 1200/300 A - -| sdace 555-3430 2400/1200/300 A - -| sabafoo 555-2127 1200/300 C - - The following command prints all records in `BBS-list' that do _not_ -contain the string `foo': - - $ awk '! /foo/' BBS-list - -| aardvark 555-5553 1200/300 B - -| alpo-net 555-3412 2400/1200/300 A - -| barfly 555-7685 1200/300 A - -| bites 555-1675 2400/1200/300 A - -| camelot 555-0542 300 C - -| core 555-2912 1200/300 C - -| sdace 555-3430 2400/1200/300 A +`mail-list' that contain both `edu' and `li': + + $ awk '/edu/ && /li/' mail-list + -| Samuel 555-3430 samuel.lanceolis@shu.edu A + + The following command prints all records in `mail-list' that contain +_either_ `edu' or `li' (or both, of course): + + $ awk '/edu/ || /li/' mail-list + -| Amelia 555-5553 amelia.zodiacusque@gmail.com F + -| Broderick 555-0542 broderick.aliquotiens@yahoo.com R + -| Fabius 555-1234 fabius.undevicesimus@ucb.edu F + -| Julie 555-6699 julie.perscrutabor@skeeve.com F + -| Samuel 555-3430 samuel.lanceolis@shu.edu A + -| Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R + + The following command prints all records in `mail-list' that do +_not_ contain the string `li': + + $ awk '! /li/' mail-list + -| Anthony 555-3412 anthony.asserturo@hotmail.com A + -| Becky 555-7685 becky.algebrarum@gmail.com A + -| Bill 555-1675 bill.drowning@hotmail.com A + -| Camilla 555-2912 camilla.infusarum@skynet.be R + -| Fabius 555-1234 fabius.undevicesimus@ucb.edu F + -| Martin 555-6480 martin.codicibus@hotmail.com A + -| Jean-Paul 555-2127 jeanpaul.campanorum@nyu.edu R The subexpressions of a Boolean operator in a pattern can be constant regular expressions, comparisons, or any other `awk' @@ -8594,19 +8610,19 @@ read. Likewise, an `END' rule is executed once only, after all the input is read. For example: $ awk ' - > BEGIN { print "Analysis of \"foo\"" } - > /foo/ { ++n } - > END { print "\"foo\" appears", n, "times." }' BBS-list - -| Analysis of "foo" - -| "foo" appears 4 times. - - This program finds the number of records in the input file `BBS-list' -that contain the string `foo'. The `BEGIN' rule prints a title for the -report. There is no need to use the `BEGIN' rule to initialize the -counter `n' to zero, since `awk' does this automatically (*note -Variables::). The second rule increments the variable `n' every time a -record containing the pattern `foo' is read. The `END' rule prints the -value of `n' at the end of the run. + > BEGIN { print "Analysis of \"li\"" } + > /li/ { ++n } + > END { print "\"li\" appears in", n, "records." }' mail-list + -| Analysis of "li" + -| "li" appears in 4 records. + + This program finds the number of records in the input file +`mail-list' that contain the string `li'. The `BEGIN' rule prints a +title for the report. There is no need to use the `BEGIN' rule to +initialize the counter `n' to zero, since `awk' does this automatically +(*note Variables::). The second rule increments the variable `n' every +time a record containing the pattern `li' is read. The `END' rule +prints the value of `n' at the end of the run. The special patterns `BEGIN' and `END' cannot be used in ranges or with Boolean operators (indeed, they cannot be used with any operators). @@ -8757,7 +8773,7 @@ File: gawk.info, Node: Empty, Prev: BEGINFILE/ENDFILE, Up: Pattern Overview An empty (i.e., nonexistent) pattern is considered to match _every_ input record. For example, the program: - awk '{ print $1 }' BBS-list + awk '{ print $1 }' mail-list prints the first field of every record. @@ -9673,13 +9689,13 @@ with a pound sign (`#'). $ awk 'BEGIN { > for (i = 0; i < ARGC; i++) > print ARGV[i] - > }' inventory-shipped BBS-list + > }' inventory-shipped mail-list -| awk -| inventory-shipped - -| BBS-list + -| mail-list `ARGV[0]' contains `awk', `ARGV[1]' contains `inventory-shipped', - and `ARGV[2]' contains `BBS-list'. The value of `ARGC' is three, + and `ARGV[2]' contains `mail-list'. The value of `ARGC' is three, one more than the index of the last element in `ARGV', because the elements are numbered from zero. @@ -9869,8 +9885,8 @@ with a pound sign (`#'). The following additional elements in the array are available to provide information about the MPFR and GMP libraries if your - version of `gawk' supports arbitrary precision numbers (*note - Arbitrary Precision Arithmetic::): + version of `gawk' supports arbitrary precision numbers (*note Gawk + and MPFR::): `PROCINFO["mpfr_version"]' The version of the GNU MPFR library. @@ -10015,13 +10031,13 @@ information contained in `ARGC' and `ARGV': $ awk 'BEGIN { > for (i = 0; i < ARGC; i++) > print ARGV[i] - > }' inventory-shipped BBS-list + > }' inventory-shipped mail-list -| awk -| inventory-shipped - -| BBS-list + -| mail-list In this example, `ARGV[0]' contains `awk', `ARGV[1]' contains -`inventory-shipped', and `ARGV[2]' contains `BBS-list'. Notice that +`inventory-shipped', and `ARGV[2]' contains `mail-list'. Notice that the `awk' program is not entered in `ARGV'. The other command-line options, with their arguments, are also not entered. This includes variable assignments done with the `-v' option (*note Options::). @@ -11268,9 +11284,10 @@ pound sign (`#'): SOURCE is duplicated into DEST. DEST is then sorted, leaving the indices of SOURCE unchanged. - When comparing strings, `IGNORECASE' affects the sorting. If the - SOURCE array contains subarrays as values (*note Arrays of - Arrays::), they will come last, after all scalar values. + When comparing strings, `IGNORECASE' affects the sorting (*note + Array Sorting Functions::). If the SOURCE array contains + subarrays as values (*note Arrays of Arrays::), they will come + last, after all scalar values. For example, if the contents of `a' are as follows: @@ -11309,7 +11326,7 @@ pound sign (`#'): `$0'. It returns the modified string as the result of the function and the original target string is _not_ changed. - `gensub()' is a general substitution function. It's purpose is to + `gensub()' is a general substitution function. Its purpose is to provide more features than the standard `sub()' and `gsub()' functions. @@ -12191,7 +12208,8 @@ enclosed in square brackets ([ ]): Variables::). The default string value is `"%a %b %e %H:%M:%S %Z %Y"'. This format string produces output that is equivalent to that of the `date' utility. You can assign - a new value to `PROCINFO["strftime"]' to change the default format. + a new value to `PROCINFO["strftime"]' to change the default + format; see below for the various format directives. `systime()' Return the current time as the number of seconds since the system @@ -16024,9 +16042,9 @@ groups in the `PROCINFO' array have the indices `"group1"' through However, we don't know in advance how many of these groups there are. This loop works by starting at one, concatenating the value with -`"group"', and then using `in' to see if that value is in the array. -Eventually, `i' is incremented past the last group in the array and the -loop exits. +`"group"', and then using `in' to see if that value is in the array +(*note Reference to Elements::). Eventually, `i' is incremented past +the last group in the array and the loop exits. The loop is also correct if there are _no_ supplementary groups; then the condition is false the first time it's tested, and the loop @@ -22803,6 +22821,11 @@ termed a "symbol table". However, with the exception of the `PROCINFO' array, an extension cannot change any of those variables. + NOTE: It is possible for the lookup of `PROCINFO' to fail. This + happens if the `awk' program being run does not reference + `PROCINFO'; in this case `gawk' doesn't bother to create the array + and populate it. + File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Symbol table by name, Up: Symbol Table Access @@ -24816,7 +24839,8 @@ File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample API T 16.7.10 Reading An Entire File ------------------------------ -The `readfile' extension adds a single function named `readfile()': +The `readfile' extension adds a single function named `readfile()', and +an input parser: `@load "readfile"' This is how you load the extension. @@ -24826,6 +24850,12 @@ The `readfile' extension adds a single function named `readfile()': a string containing the entire contents of the requested file. Upon error, the function returns the empty string and sets `ERRNO'. +`BEGIN { PROCINFO["readfile"] = 1 }' + In addition, the extension adds an input parser that is activated + if `PROCINFO["readfile"]' exists. When activated, each input file + is returned in its entirety as `$0'. `RT' is set to the null + string. + Here is an example: @load "readfile" @@ -25967,6 +25997,10 @@ Info file, in approximate chronological order: 4.1 was driven primarily by Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. + * Antonio Giovanni Colombo rewrote a number of examples in the early + chapters that were severely dated, for which I am incredibly + grateful. + * Arnold Robbins has been working on `gawk' since 1988, at first helping David Trueman, and as the primary maintainer since around 1994. @@ -28222,9 +28256,6 @@ Bash The GNU version of the standard shell (the Bourne-Again SHell). See also "Bourne Shell." -BBS - See "Bulletin Board System." - Bit Short for "Binary Digit." All values in computer memory ultimately reduce to binary digits: values that are either zero or @@ -28270,11 +28301,6 @@ Built-in Variable Braces See "Curly Braces." -Bulletin Board System - A computer system allowing users to log in and read and/or leave - messages for other users of the system, much like leaving paper - notes on a bulletin board. - C The system programming language that most GNU software is written in. The `awk' programming language has C-like syntax, and this @@ -30024,9 +30050,9 @@ Index * ! (exclamation point), !~ operator <5>: Computed Regexps. (line 6) * ! (exclamation point), !~ operator <6>: Case-sensitivity. (line 26) * ! (exclamation point), !~ operator: Regexp Usage. (line 19) -* " (double quote) <1>: Quoting. (line 37) -* " (double quote): Read Terminal. (line 25) +* " (double quote) in shell commands: Read Terminal. (line 25) * " (double quote), in regexp constants: Computed Regexps. (line 28) +* " (double quote), in shell commands: Quoting. (line 37) * # (number sign), #! (executable scripts): Executable Scripts. (line 6) * # (number sign), commenting: Comments. (line 6) @@ -30042,13 +30068,13 @@ Index * & (ampersand), && operator: Boolean Ops. (line 57) * & (ampersand), gsub()/gensub()/sub() functions and: Gory Details. (line 6) -* ' (single quote) <1>: Quoting. (line 31) -* ' (single quote) <2>: Long. (line 33) * ' (single quote): One-shot. (line 15) +* ' (single quote) in gawk command lines: Long. (line 33) +* ' (single quote), in shell commands: Quoting. (line 31) * ' (single quote), vs. apostrophe: Comments. (line 27) * ' (single quote), with double quotes: Quoting. (line 53) -* () (parentheses) <1>: Profiling. (line 146) -* () (parentheses): Regexp Operators. (line 79) +* () (parentheses), in a profile: Profiling. (line 146) +* () (parentheses), regexp operator: Regexp Operators. (line 79) * * (asterisk), * operator, as multiplication operator: Precedence. (line 55) * * (asterisk), * operator, as regexp operator: Regexp Operators. @@ -30086,8 +30112,9 @@ Index (line 15) * --disable-nls configuration option: Additional Configuration Options. (line 30) -* --dump-variables option <1>: Library Names. (line 45) * --dump-variables option: Options. (line 93) +* --dump-variables option, using for library functions: Library Names. + (line 45) * --exec option: Options. (line 125) * --field-separator option: Options. (line 21) * --file option: Options. (line 25) @@ -30130,12 +30157,12 @@ Index * -d option: Options. (line 93) * -E option: Options. (line 125) * -e option: Options. (line 117) -* -F option: Command Line Field Separator. - (line 6) * -f option: Options. (line 25) * -F option: Options. (line 21) * -f option: Long. (line 12) * -F option, -Ft sets FS to TAB: Options. (line 301) +* -F option, command line: Command Line Field Separator. + (line 6) * -f option, multiple uses: Options. (line 306) * -g option: Options. (line 147) * -h option: Options. (line 154) @@ -30155,7 +30182,7 @@ Index * -V option: Options. (line 293) * -v option: Options. (line 32) * -W option: Options. (line 46) -* . (period): Regexp Operators. (line 43) +* . (period), regexp operator: Regexp Operators. (line 43) * .gmo files: Explaining gettext. (line 41) * .gmo files, converting from .po: I18N Example. (line 62) * .gmo files, specifying directory of <1>: Programmer i18n. (line 47) @@ -30164,7 +30191,7 @@ Index * .po files: Explaining gettext. (line 36) * .po files, converting to .gmo: I18N Example. (line 62) * .pot files: Explaining gettext. (line 30) -* / (forward slash): Regexp. (line 10) +* / (forward slash) to enclose regular expressions: Regexp. (line 10) * / (forward slash), / operator: Precedence. (line 55) * / (forward slash), /= operator <1>: Precedence. (line 95) * / (forward slash), /= operator: Assignment Ops. (line 129) @@ -30208,11 +30235,9 @@ Index * ? (question mark), regexp operator <1>: GNU Regexp Operators. (line 59) * ? (question mark), regexp operator: Regexp Operators. (line 111) -* [] (square brackets): Regexp Operators. (line 55) -* \ (backslash) <1>: Regexp Operators. (line 18) -* \ (backslash) <2>: Quoting. (line 31) -* \ (backslash) <3>: Comments. (line 50) -* \ (backslash): Read Terminal. (line 25) +* [] (square brackets), regexp operator: Regexp Operators. (line 55) +* \ (backslash): Comments. (line 50) +* \ (backslash) in shell commands: Read Terminal. (line 25) * \ (backslash), \" escape sequence: Escape Sequences. (line 76) * \ (backslash), \' operator (gawk): GNU Regexp Operators. (line 56) @@ -30259,6 +30284,8 @@ Index * \ (backslash), in escape sequences, POSIX and: Escape Sequences. (line 112) * \ (backslash), in regexp constants: Computed Regexps. (line 28) +* \ (backslash), in shell commands: Quoting. (line 31) +* \ (backslash), regexp operator: Regexp Operators. (line 18) * ^ (caret), ^ operator: Precedence. (line 49) * ^ (caret), ^= operator <1>: Precedence. (line 95) * ^ (caret), ^= operator: Assignment Ops. (line 129) @@ -30276,6 +30303,8 @@ Index * _ord_init() user-defined function: Ordinal Functions. (line 16) * _pw_init() user-defined function: Passwd Functions. (line 105) * accessing fields: Fields. (line 6) +* accessing global variables from extensions: Symbol Table Access. + (line 6) * account information <1>: Group Functions. (line 6) * account information: Passwd Functions. (line 16) * actions: Action Overview. (line 6) @@ -30298,6 +30327,8 @@ Index * alarm clock example program: Alarm Program. (line 11) * alarm.awk program: Alarm Program. (line 31) * algorithms: Basic High Level. (line 68) +* allocating memory for extensions: Memory Allocation Functions. + (line 6) * Alpha (DEC): Manual History. (line 28) * amazing awk assembler (aaa): Glossary. (line 12) * amazingly workable formatter (awf): Glossary. (line 25) @@ -30309,17 +30340,24 @@ Index (line 6) * anagram.awk program: Anagram Program. (line 22) * anagrams, finding: Anagram Program. (line 6) +* and: Bitwise Functions. (line 39) * AND bitwise operation: Bitwise Functions. (line 6) * and Boolean-logic operator: Boolean Ops. (line 6) -* and() function (gawk): Bitwise Functions. (line 39) * ANSI: Glossary. (line 35) +* API informational variables: Extension API Informational Variables. + (line 6) +* API version: Extension Versioning. + (line 6) * arbitrary precision: Arbitrary Precision Arithmetic. (line 6) +* arbitrary precision integers: Arbitrary Precision Integers. + (line 6) * archeologists: Bugs. (line 6) -* ARGC/ARGV variables <1>: ARGC and ARGV. (line 6) +* arctangent: Numeric Functions. (line 11) * ARGC/ARGV variables: Auto-set. (line 11) * ARGC/ARGV variables, command-line arguments: Other Arguments. (line 12) +* ARGC/ARGV variables, how to use: ARGC and ARGV. (line 6) * ARGC/ARGV variables, portability and: Executable Scripts. (line 42) * ARGIND variable: Auto-set. (line 40) * ARGIND variable, command-line arguments: Other Arguments. (line 12) @@ -30329,53 +30367,69 @@ Index * arguments, command-line, invoking awk: Command Line. (line 6) * arguments, in function calls: Function Calls. (line 16) * arguments, processing: Getopt Function. (line 6) +* ARGV array, indexing into: Other Arguments. (line 12) * arithmetic operators: Arithmetic Ops. (line 6) +* array manipulation in extensions: Array Manipulation. (line 6) +* array members: Reference to Elements. + (line 6) +* array scanning order, controlling: Controlling Scanning. + (line 12) +* array, number of elements: String Functions. (line 194) * arrays: Arrays. (line 6) +* arrays of arrays: Arrays of Arrays. (line 6) +* arrays, an example of using: Array Example. (line 6) +* arrays, and IGNORECASE variable: Array Intro. (line 91) * arrays, as parameters to functions: Pass By Value/Reference. (line 47) * arrays, associative: Array Intro. (line 49) * arrays, associative, library functions and: Library Names. (line 57) * arrays, deleting entire contents: Delete. (line 39) -* arrays, elements, assigning: Assigning Elements. (line 6) +* arrays, elements that don't exist: Reference to Elements. + (line 23) +* arrays, elements, assigning values: Assigning Elements. (line 6) * arrays, elements, deleting: Delete. (line 6) -* arrays, elements, order of: Scanning an Array. (line 48) -* arrays, elements, referencing: Reference to Elements. - (line 6) +* arrays, elements, order of access by in operator: Scanning an Array. + (line 48) * arrays, elements, retrieving number of: String Functions. (line 32) * arrays, for statement and: Scanning an Array. (line 20) -* arrays, IGNORECASE variable and: Array Intro. (line 91) * arrays, indexing: Array Intro. (line 49) * arrays, merging into strings: Join Function. (line 6) * arrays, multidimensional: Multidimensional. (line 10) * arrays, multidimensional, scanning: Multiscanning. (line 11) -* arrays, names of: Arrays. (line 18) +* arrays, names of, and names of functions/variables: Arrays. (line 18) +* arrays, numeric subscripts: Numeric Array Subscripts. + (line 6) +* arrays, referencing elements: Reference to Elements. + (line 6) * arrays, scanning: Scanning an Array. (line 6) * arrays, sorting: Array Sorting Functions. (line 6) -* arrays, sorting, IGNORECASE variable and: Array Sorting Functions. +* arrays, sorting, and IGNORECASE variable: Array Sorting Functions. (line 83) * arrays, sparse: Array Intro. (line 70) -* arrays, subscripts: Numeric Array Subscripts. - (line 6) * arrays, subscripts, uninitialized variables as: Uninitialized Subscripts. (line 6) +* arrays, unassigned elements: Reference to Elements. + (line 18) * artificial intelligence, gawk and: Distribution contents. (line 52) -* ASCII <1>: Glossary. (line 141) +* ASCII <1>: Glossary. (line 133) * ASCII: Ordinal Functions. (line 45) -* asort() function (gawk) <1>: Array Sorting Functions. +* asort <1>: Array Sorting Functions. (line 6) -* asort() function (gawk): String Functions. (line 32) +* asort: String Functions. (line 32) * asort() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) -* asorti() function (gawk) <1>: Array Sorting Functions. +* asorti <1>: Array Sorting Functions. (line 6) -* asorti() function (gawk): String Functions. (line 32) +* asorti: String Functions. (line 32) * asorti() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) * assert() function (C library): Assert Function. (line 6) * assert() user-defined function: Assert Function. (line 28) * assertions: Assert Function. (line 6) +* assign values to variables, in debugger: Viewing And Changing Data. + (line 59) * assignment operators: Assignment Ops. (line 6) * assignment operators, evaluation order: Assignment Ops. (line 111) * assignment operators, lvalues/rvalues: Assignment Ops. (line 32) @@ -30394,6 +30448,7 @@ Index * asterisk (*), *= operator <1>: Precedence. (line 95) * asterisk (*), *= operator: Assignment Ops. (line 129) * atan2() function: Numeric Functions. (line 11) +* automatic displays, in debugger: Debugger Info. (line 24) * awf (amazingly workable formatter) program: Glossary. (line 25) * awk debugging, enabling: Options. (line 108) * awk language, POSIX version: Assignment Ops. (line 136) @@ -30455,10 +30510,8 @@ Index * awksed.awk program: Simple Sed. (line 25) * awkvars.out file: Options. (line 93) * b debugger command (alias for break): Breakpoint Control. (line 11) -* backslash (\) <1>: Regexp Operators. (line 18) -* backslash (\) <2>: Quoting. (line 31) -* backslash (\) <3>: Comments. (line 50) -* backslash (\): Read Terminal. (line 25) +* backslash (\): Comments. (line 50) +* backslash (\) in shell commands: Read Terminal. (line 25) * backslash (\), \" escape sequence: Escape Sequences. (line 76) * backslash (\), \' operator (gawk): GNU Regexp Operators. (line 56) @@ -30505,17 +30558,18 @@ Index * backslash (\), in escape sequences, POSIX and: Escape Sequences. (line 112) * backslash (\), in regexp constants: Computed Regexps. (line 28) +* backslash (\), in shell commands: Quoting. (line 31) +* backslash (\), regexp operator: Regexp Operators. (line 18) * backtrace debugger command: Execution Stack. (line 13) -* BBS-list file: Sample Data Files. (line 6) * Beebe, Nelson H.F. <1>: Other Versions. (line 78) * Beebe, Nelson H.F.: Acknowledgments. (line 60) -* BEGIN pattern <1>: Profiling. (line 62) +* BEGIN pattern <1>: Using BEGIN/END. (line 6) * BEGIN pattern <2>: BEGIN/END. (line 6) -* BEGIN pattern <3>: Field Separators. (line 45) -* BEGIN pattern: Records. (line 29) +* BEGIN pattern: Field Separators. (line 45) +* BEGIN pattern, and profiling: Profiling. (line 62) * BEGIN pattern, assert() user-defined function and: Assert Function. (line 83) -* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 73) +* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 70) * BEGIN pattern, exit statement and: Exit Statement. (line 12) * BEGIN pattern, getline and: Getline Notes. (line 19) * BEGIN pattern, headings, adding: Print Examples. (line 43) @@ -30532,28 +30586,33 @@ Index * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. (line 60) * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. - (line 73) + (line 70) * beginfile() user-defined function: Filetrans Function. (line 62) -* Bentley, Jon: Glossary. (line 151) +* Bentley, Jon: Glossary. (line 143) * Benzinger, Michael: Contributors. (line 97) * Berry, Karl <1>: Ranges and Locales. (line 74) * Berry, Karl: Acknowledgments. (line 33) * binary input/output: User-modified. (line 10) +* bindtextdomain <1>: Programmer i18n. (line 47) +* bindtextdomain: I18N Functions. (line 12) * bindtextdomain() function (C library): Explaining gettext. (line 49) -* bindtextdomain() function (gawk) <1>: Programmer i18n. (line 47) -* bindtextdomain() function (gawk): I18N Functions. (line 12) * bindtextdomain() function (gawk), portability and: I18N Portability. (line 33) * BINMODE variable <1>: PC Using. (line 33) * BINMODE variable: User-modified. (line 10) +* bit-manipulation functions: Bitwise Functions. (line 6) * bits2str() user-defined function: Bitwise Functions. (line 70) +* bitwise AND: Bitwise Functions. (line 39) +* bitwise complement: Bitwise Functions. (line 43) +* bitwise OR: Bitwise Functions. (line 49) +* bitwise XOR: Bitwise Functions. (line 55) * bitwise, complement: Bitwise Functions. (line 25) * bitwise, operations: Bitwise Functions. (line 6) * bitwise, shift: Bitwise Functions. (line 32) * body, in actions: Statements. (line 10) * body, in loops: While Statement. (line 14) * Boolean expressions: Boolean Ops. (line 6) -* Boolean expressions, as patterns: Expression Patterns. (line 41) +* Boolean expressions, as patterns: Expression Patterns. (line 39) * Boolean operators, See Boolean expressions: Boolean Ops. (line 6) * Bourne shell, quoting rules for: Quoting. (line 18) * braces ({}): Profiling. (line 142) @@ -30575,6 +30634,14 @@ Index (line 6) * break debugger command: Breakpoint Control. (line 11) * break statement: Break Statement. (line 6) +* breakpoint: Debugging Terms. (line 33) +* breakpoint at location, how to delete: Breakpoint Control. (line 36) +* breakpoint commands: Debugger Execution Control. + (line 10) +* breakpoint condition: Breakpoint Control. (line 54) +* breakpoint, delete by number: Breakpoint Control. (line 64) +* breakpoint, how to disable or enable: Breakpoint Control. (line 69) +* breakpoint, setting: Breakpoint Control. (line 11) * Brennan, Michael <1>: Other Versions. (line 6) * Brennan, Michael <2>: Two-way I/O. (line 6) * Brennan, Michael <3>: Simple Sed. (line 25) @@ -30582,7 +30649,7 @@ Index * Brennan, Michael: Foreword. (line 83) * Brian Kernighan's awk <1>: I/O Functions. (line 40) * Brian Kernighan's awk <2>: Gory Details. (line 15) -* Brian Kernighan's awk <3>: String Functions. (line 489) +* Brian Kernighan's awk <3>: String Functions. (line 490) * Brian Kernighan's awk <4>: Delete. (line 48) * Brian Kernighan's awk <5>: Nextfile Statement. (line 47) * Brian Kernighan's awk <6>: Continue Statement. (line 43) @@ -30602,7 +30669,7 @@ Index * Brini, Davide: Signature Program. (line 6) * Broder, Alan J.: Contributors. (line 88) * Brown, Martin: Contributors. (line 82) -* BSD-based operating systems: Glossary. (line 624) +* BSD-based operating systems: Glossary. (line 616) * bt debugger command (alias for backtrace): Execution Stack. (line 13) * Buening, Andreas <1>: Bugs. (line 71) * Buening, Andreas <2>: Contributors. (line 92) @@ -30626,6 +30693,7 @@ Index (line 47) * call by value: Pass By Value/Reference. (line 18) +* call stack, display in debugger: Execution Stack. (line 13) * caret (^), ^ operator: Precedence. (line 49) * caret (^), ^= operator <1>: Precedence. (line 95) * caret (^), ^= operator: Assignment Ops. (line 129) @@ -30634,18 +30702,20 @@ Index (line 59) * caret (^), regexp operator: Regexp Operators. (line 22) * case keyword: Switch Statement. (line 6) +* case sensitivity, and regexps: User-modified. (line 82) +* case sensitivity, and string comparisons: User-modified. (line 82) * case sensitivity, array indices and: Array Intro. (line 91) -* case sensitivity, converting case: String Functions. (line 519) +* case sensitivity, converting case: String Functions. (line 520) * case sensitivity, example programs: Library Functions. (line 53) * case sensitivity, gawk: Case-sensitivity. (line 26) -* case sensitivity, regexps and <1>: User-modified. (line 82) * case sensitivity, regexps and: Case-sensitivity. (line 6) -* case sensitivity, string comparisons and: User-modified. (line 82) * CGI, awk scripts for: Options. (line 125) +* changing precision of a number: Changing Precision. (line 6) * character classes, See bracket expressions: Regexp Operators. (line 55) +* character lists in regular expression: Bracket Expressions. (line 6) * character lists, See bracket expressions: Regexp Operators. (line 55) -* character sets (machine character encodings) <1>: Glossary. (line 141) +* character sets (machine character encodings) <1>: Glossary. (line 133) * character sets (machine character encodings): Ordinal Functions. (line 45) * character sets, See Also bracket expressions: Regexp Operators. @@ -30656,7 +30726,7 @@ Index * Chassell, Robert J.: Acknowledgments. (line 33) * chdir() extension function: Extension Sample File Functions. (line 12) -* chem utility: Glossary. (line 151) +* chem utility: Glossary. (line 143) * chr() extension function: Extension Sample Ord. (line 15) * chr() user-defined function: Ordinal Functions. (line 16) @@ -30665,12 +30735,12 @@ Index (line 6) * cliff_rand() user-defined function: Cliff Random Function. (line 12) -* close() function <1>: I/O Functions. (line 10) -* close() function <2>: Close Files And Pipes. +* close <1>: I/O Functions. (line 10) +* close: Close Files And Pipes. (line 18) -* close() function <3>: Getline/Pipe. (line 27) -* close() function: Getline/Variable/File. - (line 30) +* close file or coprocess: I/O Functions. (line 10) +* close() function, portability: Close Files And Pipes. + (line 81) * close() function, return value: Close Files And Pipes. (line 130) * close() function, two-way pipes and: Two-way I/O. (line 77) @@ -30679,10 +30749,12 @@ Index * Collado, Manuel: Acknowledgments. (line 60) * collating elements: Bracket Expressions. (line 69) * collating symbols: Bracket Expressions. (line 76) +* Colombo, Antonio <1>: Contributors. (line 135) * Colombo, Antonio: Acknowledgments. (line 60) * columns, aligning: Print Examples. (line 70) * columns, cutting: Cut Program. (line 6) * comma (,), in range patterns: Ranges. (line 6) +* command completion, in debugger: Readline Support. (line 6) * command line, arguments <1>: ARGC and ARGV. (line 6) * command line, arguments <2>: Auto-set. (line 11) * command line, arguments: Other Arguments. (line 6) @@ -30692,16 +30764,16 @@ Index * command line, FS on, setting: Command Line Field Separator. (line 6) * command line, invoking awk from: Command Line. (line 6) -* command line, options <1>: Command Line Field Separator. - (line 6) -* command line, options <2>: Options. (line 6) -* command line, options: Long. (line 12) +* command line, option -f: Long. (line 12) +* command line, options: Options. (line 6) * command line, options, end of: Options. (line 54) * command line, variables, assigning on: Assignment Options. (line 6) * command-line options, processing: Getopt Function. (line 6) * command-line options, string extraction: String Extraction. (line 6) * commands debugger command: Debugger Execution Control. (line 10) +* commands to execute at breakpoint: Debugger Execution Control. + (line 10) * commenting: Comments. (line 6) * commenting, backslash continuation and: Statements/Lines. (line 76) * common extensions, ** operator: Arithmetic Ops. (line 30) @@ -30714,8 +30786,8 @@ Index * common extensions, delete to delete entire arrays: Delete. (line 39) * common extensions, func keyword: Definition Syntax. (line 83) * common extensions, length() applied to an array: String Functions. - (line 193) -* common extensions, RS as a regexp: Records. (line 120) + (line 194) +* common extensions, RS as a regexp: Records. (line 135) * common extensions, single character fields: Single Character Fields. (line 6) * comp.lang.awk newsgroup: Bugs. (line 38) @@ -30731,13 +30803,13 @@ Index * compatibility mode (gawk), octal numbers: Nondecimal-numbers. (line 60) * compatibility mode (gawk), specifying: Options. (line 81) -* compiled programs <1>: Glossary. (line 165) +* compiled programs <1>: Glossary. (line 157) * compiled programs: Basic High Level. (line 15) * compiling gawk for Cygwin: Cygwin. (line 6) * compiling gawk for MS-DOS and MS-Windows: PC Compiling. (line 13) * compiling gawk for VMS: VMS Compilation. (line 6) * compiling gawk with EMX for OS/2: PC Compiling. (line 28) -* compl() function (gawk): Bitwise Functions. (line 43) +* compl: Bitwise Functions. (line 43) * complement, bitwise: Bitwise Functions. (line 25) * compound statements, control statements and: Statements. (line 10) * concatenating: Concatenation. (line 8) @@ -30753,46 +30825,59 @@ Index (line 35) * configuration options, gawk: Additional Configuration Options. (line 6) +* constant regexps: Regexp Usage. (line 57) * constants, floating-point: Floating-point Constants. (line 6) * constants, nondecimal: Nondecimal Data. (line 6) +* constants, numeric: Scalar Constants. (line 6) * constants, types of: Constants. (line 6) * context, floating-point: Floating-point Context. (line 6) +* continue program, in debugger: Debugger Execution Control. + (line 33) * continue statement: Continue Statement. (line 6) * control statements: Statements. (line 6) -* converting, case: String Functions. (line 519) -* converting, dates to timestamps: Time Functions. (line 75) -* converting, during subscripting: Numeric Array Subscripts. +* controlling array scanning order: Controlling Scanning. + (line 12) +* convert string to lower case: String Functions. (line 521) +* convert string to number: String Functions. (line 385) +* convert string to upper case: String Functions. (line 527) +* converting integer array subscripts: Numeric Array Subscripts. (line 31) +* converting, dates to timestamps: Time Functions. (line 76) * converting, numbers to strings <1>: Bitwise Functions. (line 109) * converting, numbers to strings: Conversion. (line 6) * converting, strings to numbers <1>: Bitwise Functions. (line 109) * converting, strings to numbers: Conversion. (line 6) * CONVFMT variable <1>: User-modified. (line 28) * CONVFMT variable: Conversion. (line 29) -* CONVFMT variable, array subscripts and: Numeric Array Subscripts. +* CONVFMT variable, and array subscripts: Numeric Array Subscripts. (line 6) -* cookie: Glossary. (line 157) +* cookie: Glossary. (line 149) * coprocesses <1>: Two-way I/O. (line 44) * coprocesses: Redirection. (line 102) * coprocesses, closing: Close Files And Pipes. (line 6) * coprocesses, getline from: Getline/Coprocess. (line 6) -* cos() function: Numeric Functions. (line 15) +* cos: Numeric Functions. (line 15) +* cosine: Numeric Functions. (line 15) * counting: Wc Program. (line 6) * csh utility: Statements/Lines. (line 44) * csh utility, POSIXLY_CORRECT environment variable: Options. (line 348) * csh utility, |& operator, comparison with: Two-way I/O. (line 44) * ctime() user-defined function: Function Example. (line 73) * currency symbols, localization: Explaining gettext. (line 103) +* current system time: Time Functions. (line 66) * custom.h file: Configuration Philosophy. (line 30) +* customized input parser: Input Parsers. (line 6) +* customized output wrapper: Output Wrappers. (line 6) +* customized two-way processor: Two-way processors. (line 6) * cut utility: Cut Program. (line 6) * cut.awk program: Cut Program. (line 45) * d debugger command (alias for delete): Breakpoint Control. (line 64) * d.c., See dark corner: Conventions. (line 38) -* dark corner <1>: Glossary. (line 197) +* dark corner <1>: Glossary. (line 189) * dark corner: Conventions. (line 38) * dark corner, "0" is actually true: Truth Values. (line 24) * dark corner, /= operator vs. /=.../ regexp constant: Assignment Ops. @@ -30819,9 +30904,9 @@ Index * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) -* dark corner, input files: Records. (line 103) +* dark corner, input files: Records. (line 118) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 179) +* dark corner, length() function: String Functions. (line 180) * dark corner, locale's decimal point character: Conversion. (line 77) * dark corner, multiline records: Multiple Line. (line 35) * dark corner, NF variable, decrementing: Changing Fields. (line 107) @@ -30832,26 +30917,26 @@ Index (line 147) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 358) -* dark corner, strings, storing: Records. (line 195) +* dark corner, split() function: String Functions. (line 359) +* dark corner, strings, storing: Records. (line 210) * dark corner, value of ARGV[0]: Auto-set. (line 35) * data, fixed-width: Constant Size. (line 10) * data-driven languages: Basic High Level. (line 85) * database, group, reading: Group Functions. (line 6) * database, users, reading: Passwd Functions. (line 6) * date utility, GNU: Time Functions. (line 17) -* date utility, POSIX: Time Functions. (line 262) -* dates, converting to timestamps: Time Functions. (line 75) +* date utility, POSIX: Time Functions. (line 263) +* dates, converting to timestamps: Time Functions. (line 76) * dates, information related to, localization: Explaining gettext. (line 115) * Davies, Stephen <1>: Contributors. (line 74) * Davies, Stephen: Acknowledgments. (line 60) -* dcgettext() function (gawk) <1>: Programmer i18n. (line 19) -* dcgettext() function (gawk): I18N Functions. (line 22) +* dcgettext <1>: Programmer i18n. (line 19) +* dcgettext: I18N Functions. (line 22) * dcgettext() function (gawk), portability and: I18N Portability. (line 33) -* dcngettext() function (gawk) <1>: Programmer i18n. (line 36) -* dcngettext() function (gawk): I18N Functions. (line 28) +* dcngettext <1>: Programmer i18n. (line 36) +* dcngettext: I18N Functions. (line 28) * dcngettext() function (gawk), portability and: I18N Portability. (line 33) * deadlocks: Two-way I/O. (line 70) @@ -30951,6 +31036,12 @@ Index (line 67) * debugger commands, watch: Viewing And Changing Data. (line 67) +* debugger history file: Debugger Info. (line 80) +* debugger history size: Debugger Info. (line 65) +* debugger options: Debugger Info. (line 57) +* debugger prompt: Debugger Info. (line 77) +* debugger, how to start: Debugger Invocation. (line 6) +* debugger, read commands from a file: Debugger Info. (line 96) * debugging awk programs: Debugger. (line 6) * debugging gawk, bug reports: Bugs. (line 9) * decimal point character, locale specific: Options. (line 263) @@ -30959,12 +31050,18 @@ Index * Deifik, Scott <1>: Bugs. (line 70) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) +* delete ARRAY: Delete. (line 39) +* delete breakpoint at location: Breakpoint Control. (line 36) +* delete breakpoint by number: Breakpoint Control. (line 64) * delete debugger command: Breakpoint Control. (line 64) * delete statement: Delete. (line 6) +* delete watchpoint: Viewing And Changing Data. + (line 84) * deleting elements in arrays: Delete. (line 6) * deleting entire arrays: Delete. (line 39) * Demaille, Akim: Acknowledgments. (line 60) -* differences between gawk and awk: String Functions. (line 193) +* describe call stack frame, in debugger: Debugger Info. (line 27) +* differences between gawk and awk: String Functions. (line 194) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 88) * differences in awk and gawk, ARGIND variable: Auto-set. (line 40) @@ -31011,23 +31108,23 @@ Index (line 34) * differences in awk and gawk, LINT variable: User-modified. (line 98) * differences in awk and gawk, match() function: String Functions. - (line 256) + (line 257) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) * differences in awk and gawk, PROCINFO array: Auto-set. (line 142) -* differences in awk and gawk, record separators: Records. (line 117) +* differences in awk and gawk, record separators: Records. (line 132) * differences in awk and gawk, regexp constants: Using Constant Regexps. (line 43) * differences in awk and gawk, regular expressions: Case-sensitivity. (line 26) -* differences in awk and gawk, RS/RT variables: Records. (line 172) +* differences in awk and gawk, RS/RT variables: Records. (line 187) * differences in awk and gawk, RT variable: Auto-set. (line 275) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. - (line 346) + (line 347) * differences in awk and gawk, strings: Scalar Constants. (line 20) -* differences in awk and gawk, strings, storing: Records. (line 191) +* differences in awk and gawk, strings, storing: Records. (line 206) * differences in awk and gawk, SYMTAB variable: Auto-set. (line 283) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 162) @@ -31035,15 +31132,18 @@ Index (line 66) * directories, command line: Command line directories. (line 6) -* directories, searching <1>: Igawk Program. (line 368) -* directories, searching <2>: AWKLIBPATH Variable. (line 6) -* directories, searching: AWKPATH Variable. (line 6) +* directories, searching: Igawk Program. (line 368) +* directories, searching for shared libraries: AWKLIBPATH Variable. + (line 6) +* directories, searching for source files: AWKPATH Variable. (line 6) +* disable breakpoint: Breakpoint Control. (line 69) * disable debugger command: Breakpoint Control. (line 69) * display debugger command: Viewing And Changing Data. (line 8) +* display debugger options: Debugger Info. (line 57) * division: Arithmetic Ops. (line 44) -* do-while statement <1>: Do Statement. (line 6) -* do-while statement: Regexp Usage. (line 19) +* do-while statement: Do Statement. (line 6) +* do-while statement, use of regexps in: Regexp Usage. (line 19) * documentation, of awk programs: Library Names. (line 6) * documentation, online: Manual History. (line 11) * documents, searching: Dupword Program. (line 6) @@ -31053,39 +31153,50 @@ Index (line 30) * dollar sign ($), regexp operator: Regexp Operators. (line 35) * double precision floating-point: General Arithmetic. (line 21) -* double quote (") <1>: Quoting. (line 37) -* double quote ("): Read Terminal. (line 25) +* double quote (") in shell commands: Read Terminal. (line 25) * double quote ("), in regexp constants: Computed Regexps. (line 28) +* double quote ("), in shell commands: Quoting. (line 37) * down debugger command: Execution Stack. (line 21) * Drepper, Ulrich: Acknowledgments. (line 52) +* dump all variables of a program: Options. (line 93) * dump debugger command: Miscellaneous Debugger Commands. (line 9) * dupword.awk program: Dupword Program. (line 31) +* dynamic profiling: Profiling. (line 179) +* dynamically loaded extensions: Dynamic Extensions. (line 6) * e debugger command (alias for enable): Breakpoint Control. (line 73) * EBCDIC: Ordinal Functions. (line 45) +* effective group id of gawk user: Auto-set. (line 147) +* effective user id of gawk user: Auto-set. (line 151) * egrep utility <1>: Egrep Program. (line 6) * egrep utility: Bracket Expressions. (line 24) * egrep.awk program: Egrep Program. (line 54) -* elements in arrays: Reference to Elements. - (line 6) -* elements in arrays, assigning: Assigning Elements. (line 6) +* elements in arrays, assigning values: Assigning Elements. (line 6) * elements in arrays, deleting: Delete. (line 6) -* elements in arrays, order of: Scanning an Array. (line 48) +* elements in arrays, order of access by in operator: Scanning an Array. + (line 48) * elements in arrays, scanning: Scanning an Array. (line 6) +* elements of arrays: Reference to Elements. + (line 6) * email address for bug reports, bug-gawk@gnu.org: Bugs. (line 30) * EMISTERED: TCP/IP Networking. (line 6) +* empty array elements: Reference to Elements. + (line 18) * empty pattern: Empty. (line 6) +* empty strings: Records. (line 122) * empty strings, See null strings: Regexp Field Splitting. (line 43) +* enable breakpoint: Breakpoint Control. (line 73) * enable debugger command: Breakpoint Control. (line 73) * end debugger command: Debugger Execution Control. (line 10) -* END pattern <1>: Profiling. (line 62) +* END pattern <1>: Using BEGIN/END. (line 6) * END pattern: BEGIN/END. (line 6) +* END pattern, and profiling: Profiling. (line 62) * END pattern, assert() user-defined function and: Assert Function. (line 75) * END pattern, backslash continuation and: Egrep Program. (line 220) -* END pattern, Boolean patterns and: Expression Patterns. (line 73) +* END pattern, Boolean patterns and: Expression Patterns. (line 70) * END pattern, exit statement and: Exit Statement. (line 12) * END pattern, next/nextfile statements and <1>: Next Statement. (line 45) @@ -31094,34 +31205,38 @@ Index * END pattern, operators and: Using BEGIN/END. (line 17) * END pattern, print statement and: I/O And BEGIN/END. (line 16) * ENDFILE pattern: BEGINFILE/ENDFILE. (line 6) -* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 73) +* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 70) * endfile() user-defined function: Filetrans Function. (line 62) * endgrent() function (C library): Group Functions. (line 215) * endgrent() user-defined function: Group Functions. (line 218) * endpwent() function (C library): Passwd Functions. (line 210) * endpwent() user-defined function: Passwd Functions. (line 213) * ENVIRON array: Auto-set. (line 60) -* environment variables: Auto-set. (line 60) -* epoch, definition of: Glossary. (line 243) +* environment variables used by gawk: Environment Variables. + (line 6) +* environment variables, in ENVIRON array: Auto-set. (line 60) +* epoch, definition of: Glossary. (line 235) * equals sign (=), = operator: Assignment Ops. (line 6) * equals sign (=), == operator <1>: Precedence. (line 65) * equals sign (=), == operator: Comparison Operators. (line 11) * EREs (Extended Regular Expressions): Bracket Expressions. (line 24) * ERRNO variable <1>: TCP/IP Networking. (line 54) -* ERRNO variable <2>: Auto-set. (line 82) -* ERRNO variable <3>: BEGINFILE/ENDFILE. (line 26) -* ERRNO variable <4>: Close Files And Pipes. +* ERRNO variable: Auto-set. (line 82) +* ERRNO variable, with BEGINFILE pattern: BEGINFILE/ENDFILE. (line 26) +* ERRNO variable, with close() function: Close Files And Pipes. (line 138) -* ERRNO variable: Getline. (line 19) +* ERRNO variable, with getline command: Getline. (line 19) * error handling: Special FD. (line 16) * error handling, ERRNO variable and: Auto-set. (line 82) * error output: Special FD. (line 6) * escape processing, gsub()/gensub()/sub() functions: Gory Details. (line 6) -* escape sequences: Escape Sequences. (line 6) +* escape sequences, in strings: Escape Sequences. (line 6) * eval debugger command: Viewing And Changing Data. (line 23) +* evaluate expressions, in debugger: Viewing And Changing Data. + (line 23) * evaluation order: Increment Ops. (line 60) * evaluation order, concatenation: Concatenation. (line 41) * evaluation order, functions: Calling Built-in. (line 30) @@ -31144,9 +31259,12 @@ Index * exit statement: Exit Statement. (line 6) * exit status, of gawk: Exit Status. (line 6) * exit status, of VMS: VMS Running. (line 29) -* exp() function: Numeric Functions. (line 18) +* exit the debugger: Miscellaneous Debugger Commands. + (line 99) +* exp: Numeric Functions. (line 18) * expand utility: Very Simple. (line 69) * Expat XML parser library: gawkextlib. (line 35) +* exponent: Numeric Functions. (line 18) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) * expressions, assignment: Assignment Ops. (line 6) @@ -31158,6 +31276,20 @@ Index (line 9) * expressions, selecting: Conditional Exp. (line 6) * Extended Regular Expressions (EREs): Bracket Expressions. (line 24) +* extension API: Extension API Description. + (line 6) +* extension API informational variables: Extension API Informational Variables. + (line 6) +* extension API version: Extension Versioning. + (line 6) +* extension API, version number: Auto-set. (line 238) +* extension example: Extension Example. (line 6) +* extension registration: Registration Functions. + (line 6) +* extension search path: Finding Extensions. (line 6) +* extensions distributed with gawk: Extension Samples. (line 6) +* extensions, allocating memory: Memory Allocation Functions. + (line 6) * extensions, Brian Kernighan's awk <1>: Common Extensions. (line 6) * extensions, Brian Kernighan's awk: BTL. (line 6) * extensions, common, ** operator: Arithmetic Ops. (line 30) @@ -31171,12 +31303,13 @@ Index * extensions, common, fflush() function: I/O Functions. (line 40) * extensions, common, func keyword: Definition Syntax. (line 83) * extensions, common, length() applied to an array: String Functions. - (line 193) -* extensions, common, RS as a regexp: Records. (line 120) + (line 194) +* extensions, common, RS as a regexp: Records. (line 135) * extensions, common, single character fields: Single Character Fields. (line 6) * extensions, in gawk, not in POSIX awk: POSIX/GNU. (line 6) * extensions, mawk: Common Extensions. (line 6) +* extensions, where to find: gawkextlib. (line 6) * extract.awk program: Extract Program. (line 79) * extraction, of marked strings (internationalization): String Extraction. (line 6) @@ -31190,20 +31323,20 @@ Index * features, undocumented: Undocumented. (line 6) * Fenlason, Jay <1>: Contributors. (line 18) * Fenlason, Jay: History. (line 30) -* fflush() function: I/O Functions. (line 25) +* fflush: I/O Functions. (line 25) * field numbers: Nonconstant Fields. (line 6) * field operator $: Fields. (line 19) * field operators, dollar sign as: Fields. (line 19) +* field separator, in multiline records: Multiple Line. (line 41) +* field separator, on command line: Command Line Field Separator. + (line 6) +* field separator, POSIX and: Field Splitting Summary. + (line 40) * field separators <1>: User-modified. (line 56) * field separators: Field Separators. (line 15) * field separators, choice of: Field Separators. (line 51) * field separators, FIELDWIDTHS variable and: User-modified. (line 35) * field separators, FPAT variable and: User-modified. (line 45) -* field separators, in multiline records: Multiple Line. (line 41) -* field separators, on command line: Command Line Field Separator. - (line 6) -* field separators, POSIX and <1>: Field Splitting Summary. - (line 40) * field separators, POSIX and: Fields. (line 6) * field separators, regular expressions as <1>: Regexp Field Splitting. (line 6) @@ -31245,7 +31378,6 @@ Index * files, /inet/... (gawk): TCP/IP Networking. (line 6) * files, /inet4/... (gawk): TCP/IP Networking. (line 6) * files, /inet6/... (gawk): TCP/IP Networking. (line 6) -* files, as single records: Records. (line 204) * files, awk programs in: Long. (line 6) * files, awkprof.out: Profiling. (line 6) * files, awkvars.out: Options. (line 93) @@ -31284,6 +31416,8 @@ Index * files, source, search path for: Igawk Program. (line 368) * files, splitting: Split Program. (line 6) * files, Texinfo, extracting programs from: Extract Program. (line 6) +* find substring in string: String Functions. (line 151) +* finding extensions: Finding Extensions. (line 6) * finish debugger command: Debugger Execution Control. (line 39) * Fish, Fred: Contributors. (line 50) @@ -31295,6 +31429,7 @@ Index * floating-point, numbers, arbitrary precision: Arbitrary Precision Arithmetic. (line 6) * floating-point, VAX/VMS: VMS Running. (line 51) +* flush buffered output: I/O Functions. (line 25) * fnmatch() extension function: Extension Sample Fnmatch. (line 12) * FNR variable <1>: Auto-set. (line 112) @@ -31309,10 +31444,12 @@ Index (line 57) * format specifiers, printf statement: Control Letters. (line 6) * format specifiers, strftime() function (gawk): Time Functions. - (line 88) + (line 89) +* format time string: Time Functions. (line 48) * formats, numeric output: OFMT. (line 6) * formatting output: Printf. (line 6) -* forward slash (/): Regexp. (line 10) +* formatting strings: String Functions. (line 378) +* forward slash (/) to enclose regular expressions: Regexp. (line 10) * forward slash (/), / operator: Precedence. (line 55) * forward slash (/), /= operator <1>: Precedence. (line 95) * forward slash (/), /= operator: Assignment Ops. (line 129) @@ -31325,10 +31462,10 @@ Index * frame debugger command: Execution Stack. (line 25) * Free Documentation License (FDL): GNU Free Documentation License. (line 6) -* Free Software Foundation (FSF) <1>: Glossary. (line 305) +* Free Software Foundation (FSF) <1>: Glossary. (line 297) * Free Software Foundation (FSF) <2>: Getting. (line 10) * Free Software Foundation (FSF): Manual History. (line 6) -* FreeBSD: Glossary. (line 624) +* FreeBSD: Glossary. (line 616) * FS variable <1>: User-modified. (line 56) * FS variable: Field Separators. (line 15) * FS variable, --field-separator option and: Options. (line 21) @@ -31341,7 +31478,8 @@ Index (line 6) * FS, containing ^: Regexp Field Splitting. (line 59) -* FSF (Free Software Foundation) <1>: Glossary. (line 305) +* FS, in multiline records: Multiple Line. (line 41) +* FSF (Free Software Foundation) <1>: Glossary. (line 297) * FSF (Free Software Foundation) <2>: Getting. (line 10) * FSF (Free Software Foundation): Manual History. (line 6) * fts() extension function: Extension Sample File Functions. @@ -31349,6 +31487,7 @@ Index * FUNCTAB array: Auto-set. (line 128) * function calls: Function Calls. (line 6) * function calls, indirect: Indirect Calls. (line 6) +* function definition example: Function Example. (line 6) * function pointers: Indirect Calls. (line 6) * functions, arrays as parameters to: Pass By Value/Reference. (line 47) @@ -31386,7 +31525,7 @@ Index (line 71) * functions, user-defined: User-defined. (line 6) * functions, user-defined, calling: Function Caveats. (line 6) -* functions, user-defined, counts: Profiling. (line 137) +* functions, user-defined, counts, in a profile: Profiling. (line 137) * functions, user-defined, library of: Library Functions. (line 6) * functions, user-defined, next/nextfile statements and <1>: Nextfile Statement. (line 47) @@ -31395,6 +31534,7 @@ Index * G-d: Acknowledgments. (line 78) * Garfinkle, Scott: Contributors. (line 34) * gawk program, dynamic profiling: Profiling. (line 179) +* gawk version: Auto-set. (line 213) * gawk, ARGIND variable in: Other Arguments. (line 12) * gawk, awk and <1>: This Manual. (line 14) * gawk, awk and: Preface. (line 23) @@ -31403,7 +31543,7 @@ Index * gawk, built-in variables and: Built-in Variables. (line 14) * gawk, character classes and: Bracket Expressions. (line 90) * gawk, coding style in: Adding Code. (line 38) -* gawk, command-line options: GNU Regexp Operators. +* gawk, command-line options, and regular expressions: GNU Regexp Operators. (line 70) * gawk, comparison operators and: Comparison Operators. (line 50) @@ -31437,7 +31577,7 @@ Index * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: Array Sorting Functions. (line 83) -* gawk, IGNORECASE variable in <2>: String Functions. (line 32) +* gawk, IGNORECASE variable in <2>: String Functions. (line 48) * gawk, IGNORECASE variable in <3>: Array Intro. (line 91) * gawk, IGNORECASE variable in <4>: User-modified. (line 82) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) @@ -31472,10 +31612,8 @@ Index (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 161) * gawk, RT variable in <1>: Auto-set. (line 275) -* gawk, RT variable in <2>: Getline/Variable/File. - (line 10) -* gawk, RT variable in <3>: Multiple Line. (line 129) -* gawk, RT variable in: Records. (line 117) +* gawk, RT variable in <2>: Multiple Line. (line 129) +* gawk, RT variable in: Records. (line 132) * gawk, See Also awk: Preface. (line 36) * gawk, source code, obtaining: Getting. (line 6) * gawk, splitting fields and: Constant Size. (line 88) @@ -31488,11 +31626,13 @@ Index * gawk, VMS version of: VMS Installation. (line 6) * gawk, word-boundary operator: GNU Regexp Operators. (line 63) +* gawkextlib: gawkextlib. (line 6) * gawkextlib project: gawkextlib. (line 6) -* General Public License (GPL): Glossary. (line 314) +* General Public License (GPL): Glossary. (line 306) * General Public License, See GPL: Manual History. (line 11) -* gensub() function (gawk) <1>: String Functions. (line 81) -* gensub() function (gawk): Using Constant Regexps. +* generate time values: Time Functions. (line 25) +* gensub <1>: String Functions. (line 82) +* gensub: Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) * getaddrinfo() function (C library): TCP/IP Networking. (line 38) @@ -31517,6 +31657,8 @@ Index * getline command, FILENAME variable and: Getline Notes. (line 19) * getline command, return values: Getline. (line 19) * getline command, variants: Getline Summary. (line 6) +* getline from a file: Getline/File. (line 6) +* getline into a variable: Getline/Variable. (line 6) * getline statement, BEGINFILE/ENDFILE patterns and: BEGINFILE/ENDFILE. (line 54) * getlocaltime() user-defined function: Getlocaltime Function. @@ -31540,35 +31682,35 @@ Index * git utility <3>: Other Versions. (line 29) * git utility: gawkextlib. (line 29) * git, use of for gawk source code: Derived Files. (line 6) -* GMP: Arbitrary Precision Arithmetic. - (line 6) +* GMP: Gawk and MPFR. (line 6) * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 49) * GNU Free Documentation License: GNU Free Documentation License. (line 6) -* GNU General Public License: Glossary. (line 314) -* GNU Lesser General Public License: Glossary. (line 405) +* GNU General Public License: Glossary. (line 306) +* GNU Lesser General Public License: Glossary. (line 397) * GNU long options <1>: Options. (line 6) * GNU long options: Command Line. (line 13) * GNU long options, printing list of: Options. (line 154) -* GNU Project <1>: Glossary. (line 323) +* GNU Project <1>: Glossary. (line 315) * GNU Project: Manual History. (line 11) -* GNU/Linux <1>: Glossary. (line 624) +* GNU/Linux <1>: Glossary. (line 616) * GNU/Linux <2>: I18N Example. (line 55) * GNU/Linux: Manual History. (line 28) * Gordon, Assaf: Contributors. (line 105) -* GPL (General Public License) <1>: Glossary. (line 314) +* GPL (General Public License) <1>: Glossary. (line 306) * GPL (General Public License): Manual History. (line 11) * GPL (General Public License), printing: Options. (line 88) * grcat program: Group Functions. (line 16) * Grigera, Juan: Contributors. (line 57) * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) +* group id of gawk user: Auto-set. (line 186) * groups, information about: Group Functions. (line 6) -* gsub() function <1>: String Functions. (line 134) -* gsub() function: Using Constant Regexps. +* gsub <1>: String Functions. (line 135) +* gsub: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 459) +* gsub() function, arguments of: String Functions. (line 460) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Debugger Commands. (line 66) @@ -31582,9 +31724,10 @@ Index (line 66) * hexadecimal numbers: Nondecimal-numbers. (line 6) * hexadecimal values, enabling interpretation of: Options. (line 207) +* history expansion, in debugger: Readline Support. (line 6) * histsort.awk program: History Sorting. (line 25) * Hughes, Phil: Acknowledgments. (line 43) -* HUP signal: Profiling. (line 211) +* HUP signal, for dynamic profiling: Profiling. (line 211) * hyphen (-), - operator: Precedence. (line 52) * hyphen (-), -- operator <1>: Precedence. (line 46) * hyphen (-), -- operator: Increment Ops. (line 48) @@ -31597,38 +31740,38 @@ Index * id.awk program: Id Program. (line 30) * IEEE-754 format: Floating-point Representation. (line 6) -* if statement <1>: If Statement. (line 6) -* if statement: Regexp Usage. (line 19) +* if statement: If Statement. (line 6) * if statement, actions, changing: Ranges. (line 25) +* if statement, use of regexps in: Regexp Usage. (line 19) * igawk.sh program: Igawk Program. (line 124) +* ignore breakpoint: Breakpoint Control. (line 87) * ignore debugger command: Breakpoint Control. (line 87) -* IGNORECASE variable <1>: Array Sorting Functions. +* IGNORECASE variable: User-modified. (line 82) +* IGNORECASE variable, and array indices: Array Intro. (line 91) +* IGNORECASE variable, and array sorting functions: Array Sorting Functions. (line 83) -* IGNORECASE variable <2>: String Functions. (line 32) -* IGNORECASE variable <3>: Array Intro. (line 91) -* IGNORECASE variable <4>: User-modified. (line 82) -* IGNORECASE variable: Case-sensitivity. (line 26) -* IGNORECASE variable, array sorting and: Array Sorting Functions. - (line 83) -* IGNORECASE variable, array subscripts and: Array Intro. (line 91) * IGNORECASE variable, in example programs: Library Functions. (line 53) +* IGNORECASE variable, with ~ and !~ operators: Case-sensitivity. + (line 26) * Illumos: Other Versions. (line 104) * Illumos, POSIX-compliant awk: Other Versions. (line 104) * implementation issues, gawk: Notes. (line 6) * implementation issues, gawk, debugging: Compatibility Mode. (line 6) * implementation issues, gawk, limits <1>: Redirection. (line 135) * implementation issues, gawk, limits: Getline Notes. (line 14) -* in operator <1>: Id Program. (line 93) -* in operator <2>: Scanning an Array. (line 17) -* in operator <3>: Reference to Elements. - (line 37) -* in operator <4>: For Statement. (line 75) -* in operator <5>: Precedence. (line 83) +* in operator <1>: For Statement. (line 75) +* in operator <2>: Precedence. (line 83) * in operator: Comparison Operators. (line 11) +* in operator, index existence in multidimensional arrays: Multidimensional. + (line 43) +* in operator, order of array access: Scanning an Array. (line 48) +* in operator, testing if array element exists: Reference to Elements. + (line 37) +* in operator, use in loops: Scanning an Array. (line 17) * increment operators: Increment Ops. (line 6) -* index() function: String Functions. (line 150) +* index: String Functions. (line 151) * indexing arrays: Array Intro. (line 49) * indirect function calls: Indirect Calls. (line 6) * infinite precision: Arbitrary Precision Arithmetic. @@ -31646,6 +31789,7 @@ Index * input files, running awk without: Read Terminal. (line 6) * input files, variable assignments and: Other Arguments. (line 19) * input pipeline: Getline/Pipe. (line 9) +* input record, length of: String Functions. (line 171) * input redirection: Getline/File. (line 6) * input, data, nondecimal: Nondecimal Data. (line 6) * input, explicit: Getline. (line 6) @@ -31654,14 +31798,18 @@ Index * input, splitting into records: Records. (line 6) * input, standard <1>: Special FD. (line 6) * input, standard: Read Terminal. (line 6) +* input/output functions: I/O Functions. (line 6) * input/output, binary: User-modified. (line 10) * input/output, from BEGIN and END: I/O And BEGIN/END. (line 6) * input/output, two-way: Two-way I/O. (line 44) * insomnia, cure for: Alarm Program. (line 6) * installation, VMS: VMS Installation. (line 6) * installing gawk: Installation. (line 6) +* instruction tracing, in debugger: Debugger Info. (line 89) +* int: Numeric Functions. (line 23) * INT signal (MS-Windows): Profiling. (line 214) -* int() function: Numeric Functions. (line 23) +* integer array indices: Numeric Array Subscripts. + (line 31) * integers: General Arithmetic. (line 6) * integers, arbitrary precision: Arbitrary Precision Integers. (line 6) @@ -31683,19 +31831,20 @@ Index * internationalization, localization, portability and: I18N Portability. (line 6) * internationalizing a program: Explaining gettext. (line 6) -* interpreted programs <1>: Glossary. (line 365) +* interpreted programs <1>: Glossary. (line 357) * interpreted programs: Basic High Level. (line 15) -* interval expressions: Regexp Operators. (line 116) +* interval expressions, regexp operator: Regexp Operators. (line 116) * inventory-shipped file: Sample Data Files. (line 32) -* isarray() function (gawk): Type Functions. (line 11) -* ISO: Glossary. (line 376) -* ISO 8859-1: Glossary. (line 141) -* ISO Latin-1: Glossary. (line 141) +* invoke shell command: I/O Functions. (line 72) +* isarray: Type Functions. (line 11) +* ISO: Glossary. (line 368) +* ISO 8859-1: Glossary. (line 133) +* ISO Latin-1: Glossary. (line 133) * Jacobs, Andrew: Passwd Functions. (line 90) * Jaegermann, Michal <1>: Contributors. (line 45) * Jaegermann, Michal: Acknowledgments. (line 60) * Java implementation of awk: Other Versions. (line 112) -* Java programming language: Glossary. (line 388) +* Java programming language: Glossary. (line 380) * jawk: Other Versions. (line 112) * Jedi knights: Undocumented. (line 6) * join() user-defined function: Join Function. (line 18) @@ -31703,7 +31852,7 @@ Index * Kahrs, Ju"rgen: Acknowledgments. (line 60) * Kasal, Stepan: Acknowledgments. (line 60) * Kenobi, Obi-Wan: Undocumented. (line 6) -* Kernighan, Brian <1>: Glossary. (line 151) +* Kernighan, Brian <1>: Glossary. (line 143) * Kernighan, Brian <2>: Basic Data Typing. (line 55) * Kernighan, Brian <3>: Other Versions. (line 13) * Kernighan, Brian <4>: Contributors. (line 11) @@ -31741,11 +31890,14 @@ Index * left angle bracket (<), <= operator <1>: Precedence. (line 65) * left angle bracket (<), <= operator: Comparison Operators. (line 11) +* left shift: Bitwise Functions. (line 46) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length() function: String Functions. (line 163) -* Lesser General Public License (LGPL): Glossary. (line 405) -* LGPL (Lesser General Public License): Glossary. (line 405) +* length: String Functions. (line 164) +* length of input record: String Functions. (line 171) +* length of string: String Functions. (line 164) +* Lesser General Public License (LGPL): Glossary. (line 397) +* LGPL (Lesser General Public License): Glossary. (line 397) * libmawk: Other Versions. (line 120) * libraries of awk functions: Library Functions. (line 6) * libraries of awk functions, assertions: Assert Function. (line 6) @@ -31790,21 +31942,24 @@ Index * lint checking, undefined functions: Pass By Value/Reference. (line 88) * LINT variable: User-modified. (line 98) -* Linux <1>: Glossary. (line 624) +* Linux <1>: Glossary. (line 616) * Linux <2>: I18N Example. (line 55) * Linux: Manual History. (line 28) +* list all global variables, in debugger: Debugger Info. (line 48) * list debugger command: Miscellaneous Debugger Commands. (line 72) +* list function definitions, in debugger: Debugger Info. (line 30) * loading, library: Options. (line 173) -* local variables: Variable Scope. (line 6) +* local variables, in a function: Variable Scope. (line 6) * locale categories: Explaining gettext. (line 80) * locale decimal point character: Options. (line 263) * locale, definition of: Locales. (line 6) * localization: I18N and L10N. (line 6) * localization, See internationalization, localization: I18N and L10N. (line 6) +* log: Numeric Functions. (line 30) * log files, timestamps in: Time Functions. (line 6) -* log() function: Numeric Functions. (line 30) +* logarithm: Numeric Functions. (line 30) * logical false/true: Truth Values. (line 6) * logical operators, See Boolean expressions: Boolean Ops. (line 6) * login information: Passwd Functions. (line 16) @@ -31812,7 +31967,7 @@ Index * loops: While Statement. (line 6) * loops, break statement and: Break Statement. (line 6) * loops, continue statements and: For Statement. (line 64) -* loops, count for header: Profiling. (line 131) +* loops, count for header, in a profile: Profiling. (line 131) * loops, do-while: Do Statement. (line 6) * loops, exiting: Break Statement. (line 6) * loops, for, array scanning: Scanning an Array. (line 6) @@ -31820,8 +31975,9 @@ Index * loops, See Also while statement: While Statement. (line 6) * loops, while: While Statement. (line 6) * ls utility: More Complex. (line 15) -* lshift() function (gawk): Bitwise Functions. (line 46) +* lshift: Bitwise Functions. (line 46) * lvalues/rvalues: Assignment Ops. (line 32) +* mail-list file: Sample Data Files. (line 6) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 52) * Malmberg, John <1>: Bugs. (line 72) @@ -31831,9 +31987,10 @@ Index (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 60) -* match() function: String Functions. (line 203) +* match: String Functions. (line 204) +* match regexp in string: String Functions. (line 204) * match() function, RSTART/RLENGTH variables: String Functions. - (line 220) + (line 221) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) @@ -31843,6 +32000,7 @@ Index * mawk utility <3>: Concatenation. (line 36) * mawk utility <4>: Getline/Pipe. (line 62) * mawk utility: Escape Sequences. (line 124) +* maximum precision supported by MPFR library: Auto-set. (line 227) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 41) * message object files, converting from portable object files: I18N Example. @@ -31851,15 +32009,18 @@ Index (line 47) * message object files, specifying directory of: Explaining gettext. (line 53) +* messages from extensions: Printing Messages. (line 6) +* metacharacters in regular expressions: Regexp Operators. (line 6) * metacharacters, escape sequences for: Escape Sequences. (line 130) -* mktime() function (gawk): Time Functions. (line 25) +* minimum precision supported by MPFR library: Auto-set. (line 230) +* mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 103) -* MPFR: Arbitrary Precision Arithmetic. - (line 6) +* MPFR: Gawk and MPFR. (line 6) * msgfmt utility: I18N Example. (line 62) * multiple precision: Arbitrary Precision Arithmetic. (line 6) +* multiple-line records: Multiple Line. (line 6) * n debugger command (alias for next): Debugger Execution Control. (line 43) * names, arrays/variables <1>: Library Names. (line 6) @@ -31871,7 +32032,7 @@ Index * namespace issues, functions: Definition Syntax. (line 20) * nawk utility: Names. (line 17) * negative zero: Unexpected Results. (line 34) -* NetBSD: Glossary. (line 624) +* NetBSD: Glossary. (line 616) * networks, programming: TCP/IP Networking. (line 6) * networks, support for: Special Network. (line 6) * newlines <1>: Boolean Ops. (line 67) @@ -31910,6 +32071,8 @@ Index * ni debugger command (alias for nexti): Debugger Execution Control. (line 49) * noassign.awk program: Ignoring Assigns. (line 15) +* non-existent array elements: Reference to Elements. + (line 23) * not Boolean-logic operator: Boolean Ops. (line 6) * NR variable <1>: Auto-set. (line 137) * NR variable: Records. (line 6) @@ -31918,13 +32081,15 @@ Index * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. (line 43) -* null strings: Records. (line 107) -* null strings, array elements and: Delete. (line 27) +* null strings: Records. (line 122) +* null strings in gawk arguments, quoting and: Quoting. (line 62) +* null strings, and deleting array elements: Delete. (line 27) * null strings, as array subscripts: Uninitialized Subscripts. (line 43) * null strings, converting numbers to strings: Conversion. (line 21) * null strings, matching: Gory Details. (line 164) -* null strings, quoting and: Quoting. (line 62) +* number as string of bits: Bitwise Functions. (line 109) +* number of array elements: String Functions. (line 194) * number sign (#), #! (executable scripts): Executable Scripts. (line 6) * number sign (#), commenting: Comments. (line 6) @@ -31939,9 +32104,9 @@ Index * numbers, floating-point: General Arithmetic. (line 6) * numbers, hexadecimal: Nondecimal-numbers. (line 6) * numbers, octal: Nondecimal-numbers. (line 6) -* numbers, random: Numeric Functions. (line 64) * numbers, rounding: Round Function. (line 6) -* numeric, constants: Scalar Constants. (line 6) +* numeric constants: Scalar Constants. (line 6) +* numeric functions: Numeric Functions. (line 6) * numeric, output format: OFMT. (line 6) * numeric, strings: Variable Typing. (line 6) * o debugger command (alias for option): Debugger Info. (line 57) @@ -31956,7 +32121,7 @@ Index * OFS variable <1>: User-modified. (line 124) * OFS variable <2>: Output Separators. (line 6) * OFS variable: Changing Fields. (line 64) -* OpenBSD: Glossary. (line 624) +* OpenBSD: Glossary. (line 616) * OpenSolaris: Other Versions. (line 96) * operating systems, BSD-based: Manual History. (line 28) * operating systems, PC, gawk on: PC Using. (line 6) @@ -31991,10 +32156,7 @@ Index * operators, word-boundary (gawk): GNU Regexp Operators. (line 63) * option debugger command: Debugger Info. (line 57) -* options, command-line <1>: Command Line Field Separator. - (line 6) -* options, command-line <2>: Options. (line 6) -* options, command-line: Long. (line 12) +* options, command-line: Options. (line 6) * options, command-line, end of: Options. (line 54) * options, command-line, invoking awk: Command Line. (line 6) * options, command-line, processing: Getopt Function. (line 6) @@ -32002,9 +32164,9 @@ Index * options, long <1>: Options. (line 6) * options, long: Command Line. (line 13) * options, printing list of: Options. (line 154) +* or: Bitwise Functions. (line 49) * OR bitwise operation: Bitwise Functions. (line 6) * or Boolean-logic operator: Boolean Ops. (line 6) -* or() function (gawk): Bitwise Functions. (line 49) * ord() extension function: Extension Sample Ord. (line 12) * ord() user-defined function: Ordinal Functions. (line 16) @@ -32015,6 +32177,7 @@ Index * output record separator, See ORS variable: Output Separators. (line 20) * output redirection: Redirection. (line 6) +* output wrapper: Output Wrappers. (line 6) * output, buffering: I/O Functions. (line 29) * output, duplicating into files: Tee Program. (line 6) * output, files, closing: Close Files And Pipes. @@ -32027,20 +32190,21 @@ Index * output, standard: Special FD. (line 6) * p debugger command (alias for print): Viewing And Changing Data. (line 36) -* P1003.1 POSIX standard: Glossary. (line 462) -* parentheses () <1>: Profiling. (line 146) -* parentheses (): Regexp Operators. (line 79) +* P1003.1 POSIX standard: Glossary. (line 454) +* parent process id of gawk process: Auto-set. (line 195) +* parentheses (), in a profile: Profiling. (line 146) +* parentheses (), regexp operator: Regexp Operators. (line 79) * password file: Passwd Functions. (line 16) -* patsplit() function (gawk): String Functions. (line 290) +* patsplit: String Functions. (line 291) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) -* patterns, counts: Profiling. (line 118) +* patterns, counts, in a profile: Profiling. (line 118) * patterns, default: Very Simple. (line 34) * patterns, empty: Empty. (line 6) * patterns, expressions as: Regexp Patterns. (line 6) * patterns, ranges in: Ranges. (line 6) -* patterns, regexp constants as: Expression Patterns. (line 36) +* patterns, regexp constants as: Expression Patterns. (line 34) * patterns, types of: Pattern Overview. (line 15) * pawk (profiling version of Brian Kernighan's awk): Other Versions. (line 78) @@ -32050,17 +32214,18 @@ Index * percent sign (%), % operator: Precedence. (line 55) * percent sign (%), %= operator <1>: Precedence. (line 95) * percent sign (%), %= operator: Assignment Ops. (line 129) -* period (.): Regexp Operators. (line 43) +* period (.), regexp operator: Regexp Operators. (line 43) * Perl: Future Extensions. (line 6) * Peters, Arno: Contributors. (line 85) * Peterson, Hal: Contributors. (line 39) -* pipes, closing: Close Files And Pipes. +* pipe, closing: Close Files And Pipes. (line 6) -* pipes, input: Getline/Pipe. (line 9) -* pipes, output: Redirection. (line 57) +* pipe, input: Getline/Pipe. (line 9) +* pipe, output: Redirection. (line 57) * Pitts, Dave <1>: Bugs. (line 73) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) +* plug-in: Extension Intro. (line 6) * plus sign (+), + operator: Precedence. (line 52) * plus sign (+), ++ operator <1>: Precedence. (line 46) * plus sign (+), ++ operator: Increment Ops. (line 11) @@ -32078,14 +32243,14 @@ Index (line 112) * portability, close() function and: Close Files And Pipes. (line 81) -* portability, data files as single record: Records. (line 179) +* portability, data files as single record: Records. (line 194) * portability, deleting array elements: Delete. (line 56) * portability, example programs: Library Functions. (line 42) * portability, functions, defining: Definition Syntax. (line 99) * portability, gawk: New Ports. (line 6) * portability, gettext library and: Explaining gettext. (line 10) * portability, internationalization and: I18N Portability. (line 6) -* portability, length() function: String Functions. (line 172) +* portability, length() function: String Functions. (line 173) * portability, new awk vs. old awk: Conversion. (line 55) * portability, next statement in user-defined functions: Pass By Value/Reference. (line 91) @@ -32093,7 +32258,7 @@ Index * portability, operators: Increment Ops. (line 60) * portability, operators, not in POSIX awk: Precedence. (line 98) * portability, POSIXLY_CORRECT environment variable: Options. (line 353) -* portability, substr() function: String Functions. (line 509) +* portability, substr() function: String Functions. (line 510) * portable object files <1>: Translator i18n. (line 6) * portable object files: Explaining gettext. (line 36) * portable object files, converting to message object files: I18N Example. @@ -32123,14 +32288,14 @@ Index * POSIX awk, changes in awk versions: POSIX. (line 6) * POSIX awk, continue statement and: Continue Statement. (line 43) * POSIX awk, CONVFMT variable and: User-modified. (line 28) -* POSIX awk, date utility and: Time Functions. (line 262) +* POSIX awk, date utility and: Time Functions. (line 263) * POSIX awk, field separators and <1>: Field Splitting Summary. (line 40) * POSIX awk, field separators and: Fields. (line 6) * POSIX awk, FS variable and: User-modified. (line 66) * POSIX awk, function keyword in: Definition Syntax. (line 83) * POSIX awk, functions and, gsub()/sub(): Gory Details. (line 54) -* POSIX awk, functions and, length(): String Functions. (line 172) +* POSIX awk, functions and, length(): String Functions. (line 173) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 135) * POSIX awk, next/nextfile statements and: Next Statement. (line 45) @@ -32163,6 +32328,8 @@ Index * print statement, See Also redirection, of output: Redirection. (line 17) * print statement, sprintf() function and: Round Function. (line 6) +* print variables, in debugger: Viewing And Changing Data. + (line 36) * printf debugger command: Viewing And Changing Data. (line 54) * printf statement <1>: Printf. (line 6) @@ -32182,22 +32349,30 @@ Index * printf statement, sprintf() function and: Round Function. (line 6) * printf statement, syntax of: Basic Printf. (line 6) * printing: Printing. (line 6) +* printing messages from extensions: Printing Messages. (line 6) * printing, list of options: Options. (line 154) * printing, mailing labels: Labels Program. (line 6) * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) * private variables: Library Names. (line 11) +* process group id of gawk process: Auto-set. (line 189) +* process id of gawk process: Auto-set. (line 192) * processes, two-way communications with: Two-way I/O. (line 23) * processing data: Basic High Level. (line 6) -* PROCINFO array <1>: Two-way I/O. (line 116) -* PROCINFO array <2>: Id Program. (line 15) -* PROCINFO array <3>: Group Functions. (line 6) -* PROCINFO array <4>: Passwd Functions. (line 6) -* PROCINFO array <5>: Time Functions. (line 47) -* PROCINFO array <6>: Auto-set. (line 142) -* PROCINFO array: Obsolete. (line 11) +* PROCINFO array <1>: Passwd Functions. (line 6) +* PROCINFO array <2>: Time Functions. (line 47) +* PROCINFO array: Auto-set. (line 142) +* PROCINFO array, and communications via ptys: Two-way I/O. (line 116) +* PROCINFO array, and group membership: Group Functions. (line 6) +* PROCINFO array, and user and group ID numbers: Id Program. (line 15) +* PROCINFO array, testing the field splitting: Passwd Functions. + (line 161) +* PROCINFO array, uses: Auto-set. (line 248) +* PROCINFO, values of sorted_in: Controlling Scanning. + (line 24) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 179) +* program identifiers: Auto-set. (line 160) * program, definition of: Getting Started. (line 21) * programmers, attractiveness of: Two-way I/O. (line 6) * programming conventions, --non-decimal-data option: Nondecimal Data. @@ -32218,7 +32393,7 @@ Index * programming languages, Ada: Glossary. (line 20) * programming languages, data-driven vs. procedural: Getting Started. (line 12) -* programming languages, Java: Glossary. (line 388) +* programming languages, Java: Glossary. (line 380) * programming, basic steps: Basic High Level. (line 20) * programming, concepts: Basic Concepts. (line 6) * pwcat program: Passwd Functions. (line 23) @@ -32234,17 +32409,15 @@ Index * quit debugger command: Miscellaneous Debugger Commands. (line 99) * QUIT signal (MS-Windows): Profiling. (line 214) -* quoting <1>: Comments. (line 27) -* quoting <2>: Long. (line 26) -* quoting: Read Terminal. (line 25) -* quoting, rules for: Quoting. (line 6) -* quoting, tricks for: Quoting. (line 71) +* quoting in gawk command lines: Long. (line 26) +* quoting in gawk command lines, tricks for: Quoting. (line 71) +* quoting, for small awk programs: Comments. (line 27) * r debugger command (alias for run): Debugger Execution Control. (line 62) * Rakitzis, Byron: History Sorting. (line 25) * Ramey, Chet <1>: General Data Types. (line 6) * Ramey, Chet: Acknowledgments. (line 60) -* rand() function: Numeric Functions. (line 34) +* rand: Numeric Functions. (line 34) * random numbers, Cliff: Cliff Random Function. (line 6) * random numbers, rand()/srand() functions: Numeric Functions. @@ -32264,37 +32437,41 @@ Index * readdir extension: Extension Sample Readdir. (line 9) * readfile() extension function: Extension Sample Readfile. - (line 11) + (line 12) * readfile() user-defined function: Readfile Function. (line 30) +* reading input files: Reading Files. (line 6) * recipe for a programming language: History. (line 6) * record separators <1>: User-modified. (line 143) * record separators: Records. (line 14) -* record separators, changing: Records. (line 81) -* record separators, regular expressions as: Records. (line 117) +* record separators, changing: Records. (line 93) +* record separators, regular expressions as: Records. (line 132) * record separators, with multiline records: Multiple Line. (line 10) * records <1>: Basic High Level. (line 73) * records: Reading Files. (line 14) * records, multiline: Multiple Line. (line 6) * records, printing: Print. (line 22) * records, splitting input into: Records. (line 6) -* records, terminating: Records. (line 117) -* records, treating files as: Records. (line 204) +* records, terminating: Records. (line 132) +* records, treating files as: Records. (line 219) * recursive functions: Definition Syntax. (line 73) +* redirect gawk output, in debugger: Debugger Info. (line 72) * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) * reference counting, sorting arrays: Array Sorting Functions. (line 77) +* regexp: Regexp. (line 6) * regexp constants <1>: Comparison Operators. (line 102) * regexp constants <2>: Regexp Constants. (line 6) * regexp constants: Regexp Usage. (line 57) * regexp constants, /=.../, /= operator and: Assignment Ops. (line 147) -* regexp constants, as patterns: Expression Patterns. (line 36) +* regexp constants, as patterns: Expression Patterns. (line 34) * regexp constants, in gawk: Using Constant Regexps. (line 28) * regexp constants, slashes vs. quotes: Computed Regexps. (line 28) * regexp constants, vs. string constants: Computed Regexps. (line 38) -* regexp, See regular expressions: Regexp. (line 6) +* register extension: Registration Functions. + (line 6) * regular expressions: Regexp. (line 6) * regular expressions as field separators: Field Separators. (line 51) * regular expressions, anchors in: Regexp Operators. (line 22) @@ -32302,7 +32479,7 @@ Index (line 6) * regular expressions, as patterns <1>: Regexp Patterns. (line 6) * regular expressions, as patterns: Regexp Usage. (line 6) -* regular expressions, as record separators: Records. (line 117) +* regular expressions, as record separators: Records. (line 132) * regular expressions, case sensitivity <1>: User-modified. (line 82) * regular expressions, case sensitivity: Case-sensitivity. (line 6) * regular expressions, computed: Computed Regexps. (line 6) @@ -32329,6 +32506,7 @@ Index * regular expressions, searching for: Egrep Program. (line 6) * relational operators, See comparison operators: Typing and Comparison. (line 9) +* replace in string: String Functions. (line 406) * return debugger command: Debugger Execution Control. (line 54) * return statement, user-defined functions: Return Statement. (line 6) @@ -32349,19 +32527,20 @@ Index (line 11) * right angle bracket (>), >> operator (I/O) <1>: Precedence. (line 65) * right angle bracket (>), >> operator (I/O): Redirection. (line 50) +* right shift: Bitwise Functions. (line 52) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 55) * RLENGTH variable: Auto-set. (line 262) -* RLENGTH variable, match() function and: String Functions. (line 220) +* RLENGTH variable, match() function and: String Functions. (line 221) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) -* Robbins, Arnold <3>: Contributors. (line 135) +* Robbins, Arnold <3>: Contributors. (line 139) * Robbins, Arnold <4>: General Data Types. (line 6) * Robbins, Arnold <5>: Alarm Program. (line 6) * Robbins, Arnold <6>: Passwd Functions. (line 90) * Robbins, Arnold <7>: Getline/Pipe. (line 39) * Robbins, Arnold: Command Line Field Separator. - (line 80) + (line 73) * Robbins, Bill: Getline/Pipe. (line 39) * Robbins, Harry: Acknowledgments. (line 78) * Robbins, Jean: Acknowledgments. (line 78) @@ -32369,6 +32548,7 @@ Index * Robbins, Miriam <2>: Getline/Pipe. (line 39) * Robbins, Miriam: Acknowledgments. (line 78) * Rommel, Kai Uwe: Contributors. (line 42) +* round to nearest integer: Numeric Functions. (line 23) * round() user-defined function: Round Function. (line 16) * rounding mode, floating-point: Rounding Mode. (line 6) * rounding numbers: Round Function. (line 6) @@ -32378,14 +32558,12 @@ Index * RS variable <1>: User-modified. (line 143) * RS variable: Records. (line 20) * RS variable, multiline records and: Multiple Line. (line 17) -* rshift() function (gawk): Bitwise Functions. (line 52) +* rshift: Bitwise Functions. (line 52) * RSTART variable: Auto-set. (line 268) -* RSTART variable, match() function and: String Functions. (line 220) +* RSTART variable, match() function and: String Functions. (line 221) * RT variable <1>: Auto-set. (line 275) -* RT variable <2>: Getline/Variable/File. - (line 10) -* RT variable <3>: Multiple Line. (line 129) -* RT variable: Records. (line 117) +* RT variable <2>: Multiple Line. (line 129) +* RT variable: Records. (line 132) * Rubin, Paul <1>: Contributors. (line 15) * Rubin, Paul: History. (line 30) * rule, definition of: Getting Started. (line 21) @@ -32394,29 +32572,35 @@ Index * rvalues/lvalues: Assignment Ops. (line 32) * s debugger command (alias for step): Debugger Execution Control. (line 68) +* sample debugging session: Sample Debugging Session. + (line 6) * sandbox mode: Options. (line 279) +* save debugger options: Debugger Info. (line 84) +* scalar or array: Type Functions. (line 11) * scalar values: Basic Data Typing. (line 13) +* scanning arrays: Scanning an Array. (line 6) +* scanning multidimensional arrays: Multiscanning. (line 11) * Schorr, Andrew <1>: Contributors. (line 131) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) +* search and replace in strings: String Functions. (line 82) +* search in string: String Functions. (line 151) * search paths <1>: VMS Running. (line 58) * search paths <2>: PC Using. (line 10) -* search paths <3>: Igawk Program. (line 368) -* search paths <4>: AWKLIBPATH Variable. (line 6) -* search paths: AWKPATH Variable. (line 6) +* search paths: Igawk Program. (line 368) * search paths, for shared libraries: AWKLIBPATH Variable. (line 6) * search paths, for source files <1>: VMS Running. (line 58) * search paths, for source files <2>: PC Using. (line 10) * search paths, for source files <3>: Igawk Program. (line 368) * search paths, for source files: AWKPATH Variable. (line 6) -* searching: String Functions. (line 150) * searching, files for regular expressions: Egrep Program. (line 6) * searching, for words: Dupword Program. (line 6) * sed utility <1>: Glossary. (line 12) * sed utility <2>: Simple Sed. (line 6) * sed utility: Field Splitting Summary. (line 46) +* seeding random number generator: Numeric Functions. (line 64) * semicolon (;), AWKPATH variable and: PC Using. (line 10) * semicolon (;), separating statements in actions <1>: Statements. (line 10) @@ -32430,11 +32614,21 @@ Index * separators, field, POSIX and: Fields. (line 6) * separators, for records <1>: User-modified. (line 143) * separators, for records: Records. (line 14) -* separators, for records, regular expressions as: Records. (line 117) +* separators, for records, regular expressions as: Records. (line 132) * separators, for statements in actions: Action Overview. (line 19) * separators, subscript: User-modified. (line 156) +* set breakpoint: Breakpoint Control. (line 11) * set debugger command: Viewing And Changing Data. (line 59) +* set directory of message catalogs: I18N Functions. (line 12) +* set watchpoint: Viewing And Changing Data. + (line 67) +* setting rounding mode: Setting Rounding Mode. + (line 6) +* setting working precision: Setting Precision. (line 6) +* shadowing of variable values: Definition Syntax. (line 61) +* shell quoting, double quote: Read Terminal. (line 25) +* shell quoting, rules for: Quoting. (line 6) * shells, piping commands into: Redirection. (line 142) * shells, quoting: Using Shell Variables. (line 12) @@ -32445,6 +32639,13 @@ Index (line 6) * shift, bitwise: Bitwise Functions. (line 32) * short-circuit operators: Boolean Ops. (line 57) +* show all source files, in debugger: Debugger Info. (line 45) +* show breakpoints: Debugger Info. (line 21) +* show function arguments, in debugger: Debugger Info. (line 18) +* show local variables, in debugger: Debugger Info. (line 34) +* show name of current source file, in debugger: Debugger Info. + (line 37) +* show watchpoints: Debugger Info. (line 51) * si debugger command (alias for stepi): Debugger Execution Control. (line 76) * side effects <1>: Increment Ops. (line 11) @@ -32480,7 +32681,7 @@ Index * sidebar, Piping into sh: Redirection. (line 140) * sidebar, Portability Issues with #!: Executable Scripts. (line 31) * sidebar, Recipe For A Programming Language: History. (line 6) -* sidebar, RS = "\0" Is Not Portable: Records. (line 177) +* sidebar, RS = "\0" Is Not Portable: Records. (line 192) * sidebar, So Why Does gawk have BEGINFILE and ENDFILE?: Filetrans Function. (line 83) * sidebar, Syntactic Ambiguities Between /= and Regular Expressions: Assignment Ops. @@ -32490,31 +32691,36 @@ Index (line 56) * sidebar, Using close()'s Return Value: Close Files And Pipes. (line 128) -* SIGHUP signal: Profiling. (line 211) +* SIGHUP signal, for dynamic profiling: Profiling. (line 211) * SIGINT signal (MS-Windows): Profiling. (line 214) -* signals, HUP/SIGHUP: Profiling. (line 211) +* signals, HUP/SIGHUP, for profiling: Profiling. (line 211) * signals, INT/SIGINT (MS-Windows): Profiling. (line 214) * signals, QUIT/SIGQUIT (MS-Windows): Profiling. (line 214) -* signals, USR1/SIGUSR1: Profiling. (line 188) +* signals, USR1/SIGUSR1, for profiling: Profiling. (line 188) * signature program: Signature Program. (line 6) * SIGQUIT signal (MS-Windows): Profiling. (line 214) -* SIGUSR1 signal: Profiling. (line 188) +* SIGUSR1 signal, for dynamic profiling: Profiling. (line 188) * silent debugger command: Debugger Execution Control. (line 10) -* sin() function: Numeric Functions. (line 75) +* sin: Numeric Functions. (line 75) +* sine: Numeric Functions. (line 75) * single precision floating-point: General Arithmetic. (line 21) -* single quote (') <1>: Quoting. (line 31) -* single quote (') <2>: Long. (line 33) * single quote ('): One-shot. (line 15) +* single quote (') in gawk command lines: Long. (line 33) +* single quote ('), in shell commands: Quoting. (line 31) * single quote ('), vs. apostrophe: Comments. (line 27) * single quote ('), with double quotes: Quoting. (line 53) * single-character fields: Single Character Fields. (line 6) +* single-step execution, in the debugger: Debugger Execution Control. + (line 43) * Skywalker, Luke: Undocumented. (line 6) * sleep utility: Alarm Program. (line 111) * sleep() extension function: Extension Sample Time. (line 23) * Solaris, POSIX-compliant awk: Other Versions. (line 96) +* sort array: String Functions. (line 32) +* sort array indices: String Functions. (line 32) * sort function, arrays, sorting: Array Sorting Functions. (line 6) * sort utility: Word Sorting. (line 50) @@ -32538,19 +32744,22 @@ Index * source files, search path for: Igawk Program. (line 368) * sparse arrays: Array Intro. (line 70) * Spencer, Henry: Glossary. (line 12) +* split: String Functions. (line 313) +* split string into array: String Functions. (line 291) * split utility: Split Program. (line 6) -* split() function: String Functions. (line 312) * split() function, array elements, deleting: Delete. (line 61) * split.awk program: Split Program. (line 30) -* sprintf() function <1>: String Functions. (line 377) -* sprintf() function: OFMT. (line 15) +* sprintf <1>: String Functions. (line 378) +* sprintf: OFMT. (line 15) * sprintf() function, OFMT variable and: User-modified. (line 124) * sprintf() function, print/printf statements and: Round Function. (line 6) -* sqrt() function: Numeric Functions. (line 78) -* square brackets ([]): Regexp Operators. (line 55) -* srand() function: Numeric Functions. (line 82) -* Stallman, Richard <1>: Glossary. (line 305) +* sqrt: Numeric Functions. (line 78) +* square brackets ([]), regexp operator: Regexp Operators. (line 55) +* square root: Numeric Functions. (line 78) +* srand: Numeric Functions. (line 82) +* stack frame: Debugging Terms. (line 10) +* Stallman, Richard <1>: Glossary. (line 297) * Stallman, Richard <2>: Contributors. (line 23) * Stallman, Richard <3>: Acknowledgments. (line 18) * Stallman, Richard: Manual History. (line 6) @@ -32558,6 +32767,7 @@ Index * standard input <1>: Special FD. (line 6) * standard input: Read Terminal. (line 6) * standard output: Special FD. (line 6) +* starting the debugger: Debugger Invocation. (line 6) * stat() extension function: Extension Sample File Functions. (line 18) * statements, compound, control statements and: Statements. (line 10) @@ -32567,35 +32777,42 @@ Index (line 68) * stepi debugger command: Debugger Execution Control. (line 76) +* stop automatic display, in debugger: Viewing And Changing Data. + (line 80) * stream editors <1>: Simple Sed. (line 6) * stream editors: Field Splitting Summary. (line 46) -* strftime() function (gawk): Time Functions. (line 48) +* strftime: Time Functions. (line 48) * string constants: Scalar Constants. (line 15) * string constants, vs. regexp constants: Computed Regexps. (line 38) * string extraction (internationalization): String Extraction. (line 6) +* string length: String Functions. (line 164) * string operators: Concatenation. (line 8) +* string, regular expression match: String Functions. (line 204) +* string-manipulation functions: String Functions. (line 6) * string-matching operators: Regexp Usage. (line 19) +* string-translation functions: I18N Functions. (line 6) +* strings splitting, example: String Functions. (line 333) * strings, converting <1>: Bitwise Functions. (line 109) * strings, converting: Conversion. (line 6) +* strings, converting letter case: String Functions. (line 520) * strings, converting, numbers to: User-modified. (line 28) -* strings, empty, See null strings: Records. (line 107) +* strings, empty, See null strings: Records. (line 122) * strings, extracting: String Extraction. (line 6) * strings, for localization: Programmer i18n. (line 14) -* strings, length of: Scalar Constants. (line 20) +* strings, length limitations: Scalar Constants. (line 20) * strings, merging arrays into: Join Function. (line 6) * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strings, splitting: String Functions. (line 332) -* strtonum() function (gawk): String Functions. (line 384) +* strtonum: String Functions. (line 385) * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data. (line 36) -* sub() function <1>: String Functions. (line 405) -* sub() function: Using Constant Regexps. +* sub <1>: String Functions. (line 406) +* sub: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 459) +* sub() function, arguments of: String Functions. (line 460) * sub() function, escape processing: Gory Details. (line 6) * subscript separators: User-modified. (line 156) * subscripts in arrays, multidimensional: Multidimensional. (line 10) @@ -32606,15 +32823,19 @@ Index * subscripts in arrays, uninitialized variables as: Uninitialized Subscripts. (line 6) * SUBSEP variable: User-modified. (line 156) -* SUBSEP variable, multidimensional arrays: Multidimensional. (line 16) -* substr() function: String Functions. (line 478) +* SUBSEP variable, and multidimensional arrays: Multidimensional. + (line 16) +* substitute in string: String Functions. (line 82) +* substr: String Functions. (line 479) +* substring: String Functions. (line 479) * Sumner, Andrew: Other Versions. (line 64) +* supplementary groups of gawk process: Auto-set. (line 243) * switch statement: Switch Statement. (line 6) * SYMTAB array: Auto-set. (line 283) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 147) -* system() function: I/O Functions. (line 72) -* systime() function (gawk): Time Functions. (line 65) +* system: I/O Functions. (line 72) +* systime: Time Functions. (line 66) * t debugger command (alias for tbreak): Breakpoint Control. (line 90) * tbreak debugger command: Breakpoint Control. (line 90) * Tcl: Library Names. (line 57) @@ -32622,7 +32843,8 @@ Index * TCP/IP, support for: Special Network. (line 6) * tee utility: Tee Program. (line 6) * tee.awk program: Tee Program. (line 26) -* terminating records: Records. (line 117) +* temporary breakpoint: Breakpoint Control. (line 90) +* terminating records: Records. (line 132) * testbits.awk program: Bitwise Functions. (line 70) * testext extension: Extension Sample API Tests. (line 6) @@ -32651,6 +32873,7 @@ Index * tilde (~), ~ operator <5>: Computed Regexps. (line 6) * tilde (~), ~ operator <6>: Case-sensitivity. (line 26) * tilde (~), ~ operator: Regexp Usage. (line 19) +* time functions: Time Functions. (line 6) * time, alarm clock example program: Alarm Program. (line 11) * time, localization and: Explaining gettext. (line 115) * time, managing: Getlocaltime Function. @@ -32658,15 +32881,18 @@ Index * time, retrieving: Time Functions. (line 17) * timeout, reading input: Read Timeout. (line 6) * timestamps: Time Functions. (line 6) -* timestamps, converting dates to: Time Functions. (line 75) +* timestamps, converting dates to: Time Functions. (line 76) * timestamps, formatted: Getlocaltime Function. (line 6) -* tolower() function: String Functions. (line 520) -* toupper() function: String Functions. (line 526) +* tolower: String Functions. (line 521) +* toupper: String Functions. (line 527) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. (line 108) +* traceback, display in debugger: Execution Stack. (line 13) +* translate string: I18N Functions. (line 22) * translate.awk program: Translate Program. (line 55) +* treating files, as single records: Records. (line 219) * troubleshooting, --non-decimal-data option: Options. (line 207) * troubleshooting, == operator: Comparison Operators. (line 37) @@ -32685,9 +32911,9 @@ Index * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in. (line 16) * troubleshooting, getline function: File Checking. (line 25) -* troubleshooting, gsub()/sub() functions: String Functions. (line 469) -* troubleshooting, match() function: String Functions. (line 285) -* troubleshooting, patsplit() function: String Functions. (line 308) +* troubleshooting, gsub()/sub() functions: String Functions. (line 470) +* troubleshooting, match() function: String Functions. (line 286) +* troubleshooting, patsplit() function: String Functions. (line 309) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) * troubleshooting, printing: Redirection. (line 118) @@ -32696,7 +32922,7 @@ Index * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 38) * troubleshooting, string concatenation: Concatenation. (line 26) -* troubleshooting, substr() function: String Functions. (line 496) +* troubleshooting, substr() function: String Functions. (line 497) * troubleshooting, system() function: I/O Functions. (line 94) * troubleshooting, typographical errors, global variables: Options. (line 98) @@ -32709,6 +32935,8 @@ Index * type conversion: Conversion. (line 21) * u debugger command (alias for until): Debugger Execution Control. (line 83) +* unassigned array elements: Reference to Elements. + (line 18) * undefined functions: Pass By Value/Reference. (line 71) * underscore (_), C macro: Explaining gettext. (line 70) @@ -32718,20 +32946,20 @@ Index * undisplay debugger command: Viewing And Changing Data. (line 80) * undocumented features: Undocumented. (line 6) -* Unicode <1>: Glossary. (line 141) +* Unicode <1>: Glossary. (line 133) * Unicode <2>: Ranges and Locales. (line 61) * Unicode: Ordinal Functions. (line 45) * uninitialized variables, as array subscripts: Uninitialized Subscripts. (line 6) * uniq utility: Uniq Program. (line 6) * uniq.awk program: Uniq Program. (line 65) -* Unix: Glossary. (line 624) +* Unix: Glossary. (line 616) * Unix awk, backslashes in escape sequences: Escape Sequences. (line 124) * Unix awk, close() function and: Close Files And Pipes. (line 130) * Unix awk, password files, field separators and: Command Line Field Separator. - (line 72) + (line 64) * Unix, awk scripts and: Executable Scripts. (line 6) * UNIXROOT variable, on OS/2 systems: PC Using. (line 16) * unsigned integers: General Arithmetic. (line 15) @@ -32741,15 +32969,16 @@ Index (line 84) * up debugger command: Execution Stack. (line 33) * user database, reading: Passwd Functions. (line 6) -* user-defined, functions: User-defined. (line 6) -* user-defined, functions, counts: Profiling. (line 137) +* user-defined functions: User-defined. (line 6) +* user-defined, functions, counts, in a profile: Profiling. (line 137) * user-defined, variables: Variables. (line 6) * user-modifiable variables: User-modified. (line 6) * users, information about, printing: Id Program. (line 6) * users, information about, retrieving: Passwd Functions. (line 16) -* USR1 signal: Profiling. (line 188) +* USR1 signal, for dynamic profiling: Profiling. (line 188) * values, numeric: Basic Data Typing. (line 13) * values, string: Basic Data Typing. (line 13) +* variable assignments and input files: Other Arguments. (line 19) * variable typing: Typing and Comparison. (line 9) * variables <1>: Basic Data Typing. (line 6) @@ -32770,7 +32999,7 @@ Index * variables, global, for library functions: Library Names. (line 11) * variables, global, printing list of: Options. (line 93) * variables, initializing: Using Variables. (line 20) -* variables, local: Variable Scope. (line 6) +* variables, local to a function: Variable Scope. (line 6) * variables, names of: Arrays. (line 18) * variables, private: Library Names. (line 11) * variables, setting: Options. (line 32) @@ -32781,6 +33010,10 @@ Index * variables, uninitialized, as array subscripts: Uninitialized Subscripts. (line 6) * variables, user-defined: Variables. (line 6) +* version of gawk: Auto-set. (line 213) +* version of gawk extension API: Auto-set. (line 238) +* version of GNU MP library: Auto-set. (line 224) +* version of GNU MPFR library: Auto-set. (line 220) * vertical bar (|): Regexp Operators. (line 69) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) @@ -32804,12 +33037,13 @@ Index * warnings, issuing: Options. (line 182) * watch debugger command: Viewing And Changing Data. (line 67) +* watchpoint: Debugging Terms. (line 42) * wc utility: Wc Program. (line 6) * wc.awk program: Wc Program. (line 46) * Weinberger, Peter <1>: Contributors. (line 11) * Weinberger, Peter: History. (line 17) -* while statement <1>: While Statement. (line 6) -* while statement: Regexp Usage. (line 19) +* while statement: While Statement. (line 6) +* while statement, use of regexps in: Regexp Usage. (line 19) * whitespace, as field separators: Default Field Splitting. (line 6) * whitespace, functions, calling: Calling Built-in. (line 10) @@ -32830,8 +33064,8 @@ Index * writea() extension function: Extension Sample Read write array. (line 9) * xgettext utility: String Extraction. (line 13) +* xor: Bitwise Functions. (line 55) * XOR bitwise operation: Bitwise Functions. (line 6) -* xor() function (gawk): Bitwise Functions. (line 55) * Yawitz, Efraim: Contributors. (line 129) * Zaretskii, Eli <1>: Bugs. (line 70) * Zaretskii, Eli <2>: Contributors. (line 55) @@ -32896,499 +33130,500 @@ Node: Comments80254 Node: Quoting82721 Node: DOS Quoting87344 Node: Sample Data Files88019 -Node: Very Simple90405 -Node: Two Rules95004 -Node: More Complex97151 -Ref: More Complex-Footnote-1100081 -Node: Statements/Lines100166 -Ref: Statements/Lines-Footnote-1104628 -Node: Other Features104893 -Node: When105821 -Node: Invoking Gawk107968 -Node: Command Line109431 -Node: Options110214 -Ref: Options-Footnote-1125609 -Node: Other Arguments125634 -Node: Naming Standard Input128292 -Node: Environment Variables129386 -Node: AWKPATH Variable129944 -Ref: AWKPATH Variable-Footnote-1132702 -Node: AWKLIBPATH Variable132962 -Node: Other Environment Variables133680 -Node: Exit Status136643 -Node: Include Files137318 -Node: Loading Shared Libraries140887 -Node: Obsolete142251 -Node: Undocumented142948 -Node: Regexp143190 -Node: Regexp Usage144579 -Node: Escape Sequences146605 -Node: Regexp Operators152274 -Ref: Regexp Operators-Footnote-1159654 -Ref: Regexp Operators-Footnote-2159801 -Node: Bracket Expressions159899 -Ref: table-char-classes161789 -Node: GNU Regexp Operators164312 -Node: Case-sensitivity168035 -Ref: Case-sensitivity-Footnote-1171003 -Ref: Case-sensitivity-Footnote-2171238 -Node: Leftmost Longest171346 -Node: Computed Regexps172547 -Node: Reading Files175884 -Node: Records177886 -Ref: Records-Footnote-1186974 -Node: Fields187011 -Ref: Fields-Footnote-1190044 -Node: Nonconstant Fields190130 -Node: Changing Fields192332 -Node: Field Separators198291 -Node: Default Field Splitting200993 -Node: Regexp Field Splitting202110 -Node: Single Character Fields205452 -Node: Command Line Field Separator206511 -Node: Full Line Fields209945 -Ref: Full Line Fields-Footnote-1210453 -Node: Field Splitting Summary210499 -Ref: Field Splitting Summary-Footnote-1213598 -Node: Constant Size213699 -Node: Splitting By Content218306 -Ref: Splitting By Content-Footnote-1222055 -Node: Multiple Line222095 -Ref: Multiple Line-Footnote-1227942 -Node: Getline228121 -Node: Plain Getline230337 -Node: Getline/Variable232432 -Node: Getline/File233579 -Node: Getline/Variable/File234920 -Ref: Getline/Variable/File-Footnote-1236519 -Node: Getline/Pipe236606 -Node: Getline/Variable/Pipe239305 -Node: Getline/Coprocess240412 -Node: Getline/Variable/Coprocess241664 -Node: Getline Notes242401 -Node: Getline Summary245188 -Ref: table-getline-variants245596 -Node: Read Timeout246508 -Ref: Read Timeout-Footnote-1250249 -Node: Command line directories250306 -Node: Printing250936 -Node: Print252567 -Node: Print Examples253904 -Node: Output Separators256688 -Node: OFMT258448 -Node: Printf259806 -Node: Basic Printf260712 -Node: Control Letters262251 -Node: Format Modifiers266063 -Node: Printf Examples272072 -Node: Redirection274787 -Node: Special Files281752 -Node: Special FD282285 -Ref: Special FD-Footnote-1285910 -Node: Special Network285984 -Node: Special Caveats286834 -Node: Close Files And Pipes287630 -Ref: Close Files And Pipes-Footnote-1294613 -Ref: Close Files And Pipes-Footnote-2294761 -Node: Expressions294911 -Node: Values296043 -Node: Constants296719 -Node: Scalar Constants297399 -Ref: Scalar Constants-Footnote-1298258 -Node: Nondecimal-numbers298440 -Node: Regexp Constants301440 -Node: Using Constant Regexps301915 -Node: Variables304970 -Node: Using Variables305625 -Node: Assignment Options307349 -Node: Conversion309221 -Ref: table-locale-affects314721 -Ref: Conversion-Footnote-1315345 -Node: All Operators315454 -Node: Arithmetic Ops316084 -Node: Concatenation318589 -Ref: Concatenation-Footnote-1321381 -Node: Assignment Ops321501 -Ref: table-assign-ops326489 -Node: Increment Ops327820 -Node: Truth Values and Conditions331254 -Node: Truth Values332337 -Node: Typing and Comparison333386 -Node: Variable Typing334179 -Ref: Variable Typing-Footnote-1338076 -Node: Comparison Operators338198 -Ref: table-relational-ops338608 -Node: POSIX String Comparison342156 -Ref: POSIX String Comparison-Footnote-1343112 -Node: Boolean Ops343250 -Ref: Boolean Ops-Footnote-1347328 -Node: Conditional Exp347419 -Node: Function Calls349151 -Node: Precedence352745 -Node: Locales356414 -Node: Patterns and Actions357503 -Node: Pattern Overview358557 -Node: Regexp Patterns360226 -Node: Expression Patterns360769 -Node: Ranges364454 -Node: BEGIN/END367558 -Node: Using BEGIN/END368320 -Ref: Using BEGIN/END-Footnote-1371051 -Node: I/O And BEGIN/END371157 -Node: BEGINFILE/ENDFILE373439 -Node: Empty376353 -Node: Using Shell Variables376669 -Node: Action Overview378954 -Node: Statements381311 -Node: If Statement383165 -Node: While Statement384664 -Node: Do Statement386708 -Node: For Statement387864 -Node: Switch Statement391016 -Node: Break Statement393170 -Node: Continue Statement395160 -Node: Next Statement396953 -Node: Nextfile Statement399343 -Node: Exit Statement401998 -Node: Built-in Variables404414 -Node: User-modified405509 -Ref: User-modified-Footnote-1413867 -Node: Auto-set413929 -Ref: Auto-set-Footnote-1427399 -Ref: Auto-set-Footnote-2427604 -Node: ARGC and ARGV427660 -Node: Arrays431511 -Node: Array Basics433016 -Node: Array Intro433842 -Node: Reference to Elements438159 -Node: Assigning Elements440429 -Node: Array Example440920 -Node: Scanning an Array442652 -Node: Controlling Scanning444966 -Ref: Controlling Scanning-Footnote-1450053 -Node: Delete450369 -Ref: Delete-Footnote-1453134 -Node: Numeric Array Subscripts453191 -Node: Uninitialized Subscripts455374 -Node: Multidimensional457001 -Node: Multiscanning460094 -Node: Arrays of Arrays461683 -Node: Functions466323 -Node: Built-in467142 -Node: Calling Built-in468220 -Node: Numeric Functions470208 -Ref: Numeric Functions-Footnote-1474040 -Ref: Numeric Functions-Footnote-2474397 -Ref: Numeric Functions-Footnote-3474445 -Node: String Functions474714 -Ref: String Functions-Footnote-1497634 -Ref: String Functions-Footnote-2497763 -Ref: String Functions-Footnote-3498011 -Node: Gory Details498098 -Ref: table-sub-escapes499777 -Ref: table-sub-posix-92501131 -Ref: table-sub-proposed502482 -Ref: table-posix-sub503836 -Ref: table-gensub-escapes505381 -Ref: Gory Details-Footnote-1506557 -Ref: Gory Details-Footnote-2506608 -Node: I/O Functions506759 -Ref: I/O Functions-Footnote-1513749 -Node: Time Functions513896 -Ref: Time Functions-Footnote-1524829 -Ref: Time Functions-Footnote-2524897 -Ref: Time Functions-Footnote-3525055 -Ref: Time Functions-Footnote-4525166 -Ref: Time Functions-Footnote-5525278 -Ref: Time Functions-Footnote-6525505 -Node: Bitwise Functions525771 -Ref: table-bitwise-ops526333 -Ref: Bitwise Functions-Footnote-1530554 -Node: Type Functions530738 -Node: I18N Functions531889 -Node: User-defined533516 -Node: Definition Syntax534320 -Ref: Definition Syntax-Footnote-1539234 -Node: Function Example539303 -Ref: Function Example-Footnote-1541952 -Node: Function Caveats541974 -Node: Calling A Function542492 -Node: Variable Scope543447 -Node: Pass By Value/Reference546410 -Node: Return Statement549918 -Node: Dynamic Typing552899 -Node: Indirect Calls553830 -Node: Library Functions563517 -Ref: Library Functions-Footnote-1567030 -Ref: Library Functions-Footnote-2567173 -Node: Library Names567344 -Ref: Library Names-Footnote-1570817 -Ref: Library Names-Footnote-2571037 -Node: General Functions571123 -Node: Strtonum Function572151 -Node: Assert Function575081 -Node: Round Function578407 -Node: Cliff Random Function579948 -Node: Ordinal Functions580964 -Ref: Ordinal Functions-Footnote-1584041 -Ref: Ordinal Functions-Footnote-2584293 -Node: Join Function584504 -Ref: Join Function-Footnote-1586275 -Node: Getlocaltime Function586475 -Node: Readfile Function590216 -Node: Data File Management592055 -Node: Filetrans Function592687 -Node: Rewind Function596756 -Node: File Checking598143 -Node: Empty Files599237 -Node: Ignoring Assigns601467 -Node: Getopt Function603021 -Ref: Getopt Function-Footnote-1614324 -Node: Passwd Functions614527 -Ref: Passwd Functions-Footnote-1623505 -Node: Group Functions623593 -Node: Walking Arrays631677 -Node: Sample Programs633813 -Node: Running Examples634487 -Node: Clones635215 -Node: Cut Program636439 -Node: Egrep Program646290 -Ref: Egrep Program-Footnote-1654063 -Node: Id Program654173 -Node: Split Program657789 -Ref: Split Program-Footnote-1661308 -Node: Tee Program661436 -Node: Uniq Program664239 -Node: Wc Program671668 -Ref: Wc Program-Footnote-1675934 -Ref: Wc Program-Footnote-2676134 -Node: Miscellaneous Programs676226 -Node: Dupword Program677414 -Node: Alarm Program679445 -Node: Translate Program684252 -Ref: Translate Program-Footnote-1688639 -Ref: Translate Program-Footnote-2688887 -Node: Labels Program689021 -Ref: Labels Program-Footnote-1692392 -Node: Word Sorting692476 -Node: History Sorting696360 -Node: Extract Program698199 -Ref: Extract Program-Footnote-1705702 -Node: Simple Sed705830 -Node: Igawk Program708892 -Ref: Igawk Program-Footnote-1724049 -Ref: Igawk Program-Footnote-2724250 -Node: Anagram Program724388 -Node: Signature Program727456 -Node: Advanced Features728556 -Node: Nondecimal Data730442 -Node: Array Sorting732025 -Node: Controlling Array Traversal732722 -Node: Array Sorting Functions741006 -Ref: Array Sorting Functions-Footnote-1744875 -Node: Two-way I/O745069 -Ref: Two-way I/O-Footnote-1750501 -Node: TCP/IP Networking750583 -Node: Profiling753427 -Node: Internationalization760930 -Node: I18N and L10N762355 -Node: Explaining gettext763041 -Ref: Explaining gettext-Footnote-1768109 -Ref: Explaining gettext-Footnote-2768293 -Node: Programmer i18n768458 -Node: Translator i18n772660 -Node: String Extraction773454 -Ref: String Extraction-Footnote-1774415 -Node: Printf Ordering774501 -Ref: Printf Ordering-Footnote-1777283 -Node: I18N Portability777347 -Ref: I18N Portability-Footnote-1779796 -Node: I18N Example779859 -Ref: I18N Example-Footnote-1782497 -Node: Gawk I18N782569 -Node: Debugger783190 -Node: Debugging784161 -Node: Debugging Concepts784594 -Node: Debugging Terms786450 -Node: Awk Debugging789047 -Node: Sample Debugging Session789939 -Node: Debugger Invocation790459 -Node: Finding The Bug791792 -Node: List of Debugger Commands798279 -Node: Breakpoint Control799613 -Node: Debugger Execution Control803277 -Node: Viewing And Changing Data806637 -Node: Execution Stack809993 -Node: Debugger Info811460 -Node: Miscellaneous Debugger Commands815442 -Node: Readline Support820618 -Node: Limitations821449 -Node: Arbitrary Precision Arithmetic823701 -Ref: Arbitrary Precision Arithmetic-Footnote-1825350 -Node: General Arithmetic825498 -Node: Floating Point Issues827218 -Node: String Conversion Precision828099 -Ref: String Conversion Precision-Footnote-1829804 -Node: Unexpected Results829913 -Node: POSIX Floating Point Problems832066 -Ref: POSIX Floating Point Problems-Footnote-1835891 -Node: Integer Programming835929 -Node: Floating-point Programming837668 -Ref: Floating-point Programming-Footnote-1843999 -Ref: Floating-point Programming-Footnote-2844269 -Node: Floating-point Representation844533 -Node: Floating-point Context845698 -Ref: table-ieee-formats846537 -Node: Rounding Mode847921 -Ref: table-rounding-modes848400 -Ref: Rounding Mode-Footnote-1851415 -Node: Gawk and MPFR851594 -Node: Arbitrary Precision Floats852849 -Ref: Arbitrary Precision Floats-Footnote-1855292 -Node: Setting Precision855608 -Ref: table-predefined-precision-strings856294 -Node: Setting Rounding Mode858439 -Ref: table-gawk-rounding-modes858843 -Node: Floating-point Constants860030 -Node: Changing Precision861459 -Ref: Changing Precision-Footnote-1862856 -Node: Exact Arithmetic863030 -Node: Arbitrary Precision Integers866168 -Ref: Arbitrary Precision Integers-Footnote-1869183 -Node: Dynamic Extensions869330 -Node: Extension Intro870788 -Node: Plugin License872053 -Node: Extension Mechanism Outline872738 -Ref: load-extension873155 -Ref: load-new-function874633 -Ref: call-new-function875628 -Node: Extension API Description877643 -Node: Extension API Functions Introduction878930 -Node: General Data Types883857 -Ref: General Data Types-Footnote-1889552 -Node: Requesting Values889851 -Ref: table-value-types-returned890588 -Node: Memory Allocation Functions891542 -Ref: Memory Allocation Functions-Footnote-1894288 -Node: Constructor Functions894384 -Node: Registration Functions896142 -Node: Extension Functions896827 -Node: Exit Callback Functions899129 -Node: Extension Version String900378 -Node: Input Parsers901028 -Node: Output Wrappers910785 -Node: Two-way processors915295 -Node: Printing Messages917503 -Ref: Printing Messages-Footnote-1918580 -Node: Updating `ERRNO'918732 -Node: Accessing Parameters919471 -Node: Symbol Table Access920701 -Node: Symbol table by name921215 -Node: Symbol table by cookie922964 -Ref: Symbol table by cookie-Footnote-1927096 -Node: Cached values927159 -Ref: Cached values-Footnote-1930649 -Node: Array Manipulation930740 -Ref: Array Manipulation-Footnote-1931838 -Node: Array Data Types931877 -Ref: Array Data Types-Footnote-1934580 -Node: Array Functions934672 -Node: Flattening Arrays938508 -Node: Creating Arrays945360 -Node: Extension API Variables950085 -Node: Extension Versioning950721 -Node: Extension API Informational Variables952622 -Node: Extension API Boilerplate953708 -Node: Finding Extensions957512 -Node: Extension Example958072 -Node: Internal File Description958802 -Node: Internal File Ops962893 -Ref: Internal File Ops-Footnote-1974402 -Node: Using Internal File Ops974542 -Ref: Using Internal File Ops-Footnote-1976895 -Node: Extension Samples977161 -Node: Extension Sample File Functions978685 -Node: Extension Sample Fnmatch987170 -Node: Extension Sample Fork988939 -Node: Extension Sample Inplace990152 -Node: Extension Sample Ord991930 -Node: Extension Sample Readdir992766 -Node: Extension Sample Revout994298 -Node: Extension Sample Rev2way994891 -Node: Extension Sample Read write array995581 -Node: Extension Sample Readfile997464 -Node: Extension Sample API Tests998282 -Node: Extension Sample Time998807 -Node: gawkextlib1000171 -Node: Language History1002952 -Node: V7/SVR3.11004545 -Node: SVR41006865 -Node: POSIX1008307 -Node: BTL1009693 -Node: POSIX/GNU1010427 -Node: Feature History1016026 -Node: Common Extensions1029002 -Node: Ranges and Locales1030314 -Ref: Ranges and Locales-Footnote-11034931 -Ref: Ranges and Locales-Footnote-21034958 -Ref: Ranges and Locales-Footnote-31035192 -Node: Contributors1035413 -Node: Installation1040640 -Node: Gawk Distribution1041534 -Node: Getting1042018 -Node: Extracting1042844 -Node: Distribution contents1044536 -Node: Unix Installation1050241 -Node: Quick Installation1050858 -Node: Additional Configuration Options1053304 -Node: Configuration Philosophy1055040 -Node: Non-Unix Installation1057394 -Node: PC Installation1057852 -Node: PC Binary Installation1059151 -Node: PC Compiling1060999 -Node: PC Testing1063943 -Node: PC Using1065119 -Node: Cygwin1069287 -Node: MSYS1070096 -Node: VMS Installation1070610 -Node: VMS Compilation1071374 -Ref: VMS Compilation-Footnote-11072626 -Node: VMS Dynamic Extensions1072684 -Node: VMS Installation Details1074057 -Node: VMS Running1076308 -Node: VMS GNV1079142 -Node: VMS Old Gawk1079865 -Node: Bugs1080335 -Node: Other Versions1084253 -Node: Notes1090337 -Node: Compatibility Mode1091137 -Node: Additions1091920 -Node: Accessing The Source1092847 -Node: Adding Code1094287 -Node: New Ports1100332 -Node: Derived Files1104467 -Ref: Derived Files-Footnote-11109788 -Ref: Derived Files-Footnote-21109822 -Ref: Derived Files-Footnote-31110422 -Node: Future Extensions1110520 -Node: Implementation Limitations1111103 -Node: Extension Design1112355 -Node: Old Extension Problems1113509 -Ref: Old Extension Problems-Footnote-11115017 -Node: Extension New Mechanism Goals1115074 -Ref: Extension New Mechanism Goals-Footnote-11118439 -Node: Extension Other Design Decisions1118625 -Node: Extension Future Growth1120731 -Node: Old Extension Mechanism1121567 -Node: Basic Concepts1123307 -Node: Basic High Level1123988 -Ref: figure-general-flow1124259 -Ref: figure-process-flow1124858 -Ref: Basic High Level-Footnote-11128087 -Node: Basic Data Typing1128272 -Node: Glossary1131627 -Node: Copying1157089 -Node: GNU Free Documentation License1194646 -Node: Index1219783 +Node: Very Simple90534 +Node: Two Rules95185 +Node: More Complex97083 +Ref: More Complex-Footnote-1100013 +Node: Statements/Lines100098 +Ref: Statements/Lines-Footnote-1104561 +Node: Other Features104826 +Node: When105754 +Node: Invoking Gawk107901 +Node: Command Line109364 +Node: Options110147 +Ref: Options-Footnote-1125525 +Node: Other Arguments125550 +Node: Naming Standard Input128208 +Node: Environment Variables129302 +Node: AWKPATH Variable129860 +Ref: AWKPATH Variable-Footnote-1132641 +Ref: AWKPATH Variable-Footnote-2132686 +Node: AWKLIBPATH Variable132946 +Node: Other Environment Variables133664 +Node: Exit Status136627 +Node: Include Files137302 +Node: Loading Shared Libraries140871 +Node: Obsolete142235 +Node: Undocumented142932 +Node: Regexp143174 +Node: Regexp Usage144563 +Node: Escape Sequences146588 +Node: Regexp Operators152257 +Ref: Regexp Operators-Footnote-1159637 +Ref: Regexp Operators-Footnote-2159784 +Node: Bracket Expressions159882 +Ref: table-char-classes161772 +Node: GNU Regexp Operators164295 +Node: Case-sensitivity168018 +Ref: Case-sensitivity-Footnote-1170986 +Ref: Case-sensitivity-Footnote-2171221 +Node: Leftmost Longest171329 +Node: Computed Regexps172530 +Node: Reading Files175867 +Node: Records177869 +Ref: Records-Footnote-1187392 +Node: Fields187429 +Ref: Fields-Footnote-1190385 +Node: Nonconstant Fields190471 +Node: Changing Fields192677 +Node: Field Separators198636 +Node: Default Field Splitting201338 +Node: Regexp Field Splitting202455 +Node: Single Character Fields205797 +Node: Command Line Field Separator206856 +Node: Full Line Fields210198 +Ref: Full Line Fields-Footnote-1210706 +Node: Field Splitting Summary210752 +Ref: Field Splitting Summary-Footnote-1213851 +Node: Constant Size213952 +Node: Splitting By Content218559 +Ref: Splitting By Content-Footnote-1222308 +Node: Multiple Line222348 +Ref: Multiple Line-Footnote-1228195 +Node: Getline228374 +Node: Plain Getline230590 +Node: Getline/Variable232685 +Node: Getline/File233832 +Node: Getline/Variable/File235173 +Ref: Getline/Variable/File-Footnote-1236772 +Node: Getline/Pipe236859 +Node: Getline/Variable/Pipe239558 +Node: Getline/Coprocess240665 +Node: Getline/Variable/Coprocess241917 +Node: Getline Notes242654 +Node: Getline Summary245441 +Ref: table-getline-variants245849 +Node: Read Timeout246761 +Ref: Read Timeout-Footnote-1250502 +Node: Command line directories250559 +Node: Printing251189 +Node: Print252820 +Node: Print Examples254157 +Node: Output Separators256941 +Node: OFMT258957 +Node: Printf260315 +Node: Basic Printf261221 +Node: Control Letters262760 +Node: Format Modifiers266572 +Node: Printf Examples272581 +Node: Redirection275293 +Node: Special Files282267 +Node: Special FD282800 +Ref: Special FD-Footnote-1286425 +Node: Special Network286499 +Node: Special Caveats287349 +Node: Close Files And Pipes288145 +Ref: Close Files And Pipes-Footnote-1295128 +Ref: Close Files And Pipes-Footnote-2295276 +Node: Expressions295426 +Node: Values296558 +Node: Constants297234 +Node: Scalar Constants297914 +Ref: Scalar Constants-Footnote-1298773 +Node: Nondecimal-numbers298955 +Node: Regexp Constants301955 +Node: Using Constant Regexps302430 +Node: Variables305485 +Node: Using Variables306140 +Node: Assignment Options307864 +Node: Conversion309739 +Ref: table-locale-affects315239 +Ref: Conversion-Footnote-1315863 +Node: All Operators315972 +Node: Arithmetic Ops316602 +Node: Concatenation319107 +Ref: Concatenation-Footnote-1321895 +Node: Assignment Ops322015 +Ref: table-assign-ops327003 +Node: Increment Ops328334 +Node: Truth Values and Conditions331768 +Node: Truth Values332851 +Node: Typing and Comparison333900 +Node: Variable Typing334693 +Ref: Variable Typing-Footnote-1338590 +Node: Comparison Operators338712 +Ref: table-relational-ops339122 +Node: POSIX String Comparison342670 +Ref: POSIX String Comparison-Footnote-1343626 +Node: Boolean Ops343764 +Ref: Boolean Ops-Footnote-1347834 +Node: Conditional Exp347925 +Node: Function Calls349657 +Node: Precedence353251 +Node: Locales356920 +Node: Patterns and Actions358009 +Node: Pattern Overview359063 +Node: Regexp Patterns360732 +Node: Expression Patterns361275 +Node: Ranges365056 +Node: BEGIN/END368160 +Node: Using BEGIN/END368922 +Ref: Using BEGIN/END-Footnote-1371658 +Node: I/O And BEGIN/END371764 +Node: BEGINFILE/ENDFILE374046 +Node: Empty376960 +Node: Using Shell Variables377277 +Node: Action Overview379562 +Node: Statements381919 +Node: If Statement383773 +Node: While Statement385272 +Node: Do Statement387316 +Node: For Statement388472 +Node: Switch Statement391624 +Node: Break Statement393778 +Node: Continue Statement395768 +Node: Next Statement397561 +Node: Nextfile Statement399951 +Node: Exit Statement402606 +Node: Built-in Variables405022 +Node: User-modified406117 +Ref: User-modified-Footnote-1414475 +Node: Auto-set414537 +Ref: Auto-set-Footnote-1427993 +Ref: Auto-set-Footnote-2428198 +Node: ARGC and ARGV428254 +Node: Arrays432108 +Node: Array Basics433613 +Node: Array Intro434439 +Node: Reference to Elements438756 +Node: Assigning Elements441026 +Node: Array Example441517 +Node: Scanning an Array443249 +Node: Controlling Scanning445563 +Ref: Controlling Scanning-Footnote-1450650 +Node: Delete450966 +Ref: Delete-Footnote-1453731 +Node: Numeric Array Subscripts453788 +Node: Uninitialized Subscripts455971 +Node: Multidimensional457598 +Node: Multiscanning460691 +Node: Arrays of Arrays462280 +Node: Functions466920 +Node: Built-in467739 +Node: Calling Built-in468817 +Node: Numeric Functions470805 +Ref: Numeric Functions-Footnote-1474637 +Ref: Numeric Functions-Footnote-2474994 +Ref: Numeric Functions-Footnote-3475042 +Node: String Functions475311 +Ref: String Functions-Footnote-1498269 +Ref: String Functions-Footnote-2498398 +Ref: String Functions-Footnote-3498646 +Node: Gory Details498733 +Ref: table-sub-escapes500412 +Ref: table-sub-posix-92501766 +Ref: table-sub-proposed503117 +Ref: table-posix-sub504471 +Ref: table-gensub-escapes506016 +Ref: Gory Details-Footnote-1507192 +Ref: Gory Details-Footnote-2507243 +Node: I/O Functions507394 +Ref: I/O Functions-Footnote-1514384 +Node: Time Functions514531 +Ref: Time Functions-Footnote-1525514 +Ref: Time Functions-Footnote-2525582 +Ref: Time Functions-Footnote-3525740 +Ref: Time Functions-Footnote-4525851 +Ref: Time Functions-Footnote-5525963 +Ref: Time Functions-Footnote-6526190 +Node: Bitwise Functions526456 +Ref: table-bitwise-ops527018 +Ref: Bitwise Functions-Footnote-1531239 +Node: Type Functions531423 +Node: I18N Functions532574 +Node: User-defined534201 +Node: Definition Syntax535005 +Ref: Definition Syntax-Footnote-1539919 +Node: Function Example539988 +Ref: Function Example-Footnote-1542637 +Node: Function Caveats542659 +Node: Calling A Function543177 +Node: Variable Scope544132 +Node: Pass By Value/Reference547095 +Node: Return Statement550603 +Node: Dynamic Typing553584 +Node: Indirect Calls554515 +Node: Library Functions564202 +Ref: Library Functions-Footnote-1567715 +Ref: Library Functions-Footnote-2567858 +Node: Library Names568029 +Ref: Library Names-Footnote-1571502 +Ref: Library Names-Footnote-2571722 +Node: General Functions571808 +Node: Strtonum Function572836 +Node: Assert Function575766 +Node: Round Function579092 +Node: Cliff Random Function580633 +Node: Ordinal Functions581649 +Ref: Ordinal Functions-Footnote-1584726 +Ref: Ordinal Functions-Footnote-2584978 +Node: Join Function585189 +Ref: Join Function-Footnote-1586960 +Node: Getlocaltime Function587160 +Node: Readfile Function590901 +Node: Data File Management592740 +Node: Filetrans Function593372 +Node: Rewind Function597441 +Node: File Checking598828 +Node: Empty Files599922 +Node: Ignoring Assigns602152 +Node: Getopt Function603706 +Ref: Getopt Function-Footnote-1615009 +Node: Passwd Functions615212 +Ref: Passwd Functions-Footnote-1624190 +Node: Group Functions624278 +Node: Walking Arrays632362 +Node: Sample Programs634498 +Node: Running Examples635172 +Node: Clones635900 +Node: Cut Program637124 +Node: Egrep Program646975 +Ref: Egrep Program-Footnote-1654748 +Node: Id Program654858 +Node: Split Program658507 +Ref: Split Program-Footnote-1662026 +Node: Tee Program662154 +Node: Uniq Program664957 +Node: Wc Program672386 +Ref: Wc Program-Footnote-1676652 +Ref: Wc Program-Footnote-2676852 +Node: Miscellaneous Programs676944 +Node: Dupword Program678132 +Node: Alarm Program680163 +Node: Translate Program684970 +Ref: Translate Program-Footnote-1689357 +Ref: Translate Program-Footnote-2689605 +Node: Labels Program689739 +Ref: Labels Program-Footnote-1693110 +Node: Word Sorting693194 +Node: History Sorting697078 +Node: Extract Program698917 +Ref: Extract Program-Footnote-1706420 +Node: Simple Sed706548 +Node: Igawk Program709610 +Ref: Igawk Program-Footnote-1724767 +Ref: Igawk Program-Footnote-2724968 +Node: Anagram Program725106 +Node: Signature Program728174 +Node: Advanced Features729274 +Node: Nondecimal Data731160 +Node: Array Sorting732743 +Node: Controlling Array Traversal733440 +Node: Array Sorting Functions741724 +Ref: Array Sorting Functions-Footnote-1745593 +Node: Two-way I/O745787 +Ref: Two-way I/O-Footnote-1751219 +Node: TCP/IP Networking751301 +Node: Profiling754145 +Node: Internationalization761648 +Node: I18N and L10N763073 +Node: Explaining gettext763759 +Ref: Explaining gettext-Footnote-1768827 +Ref: Explaining gettext-Footnote-2769011 +Node: Programmer i18n769176 +Node: Translator i18n773378 +Node: String Extraction774172 +Ref: String Extraction-Footnote-1775133 +Node: Printf Ordering775219 +Ref: Printf Ordering-Footnote-1778001 +Node: I18N Portability778065 +Ref: I18N Portability-Footnote-1780514 +Node: I18N Example780577 +Ref: I18N Example-Footnote-1783215 +Node: Gawk I18N783287 +Node: Debugger783908 +Node: Debugging784879 +Node: Debugging Concepts785312 +Node: Debugging Terms787168 +Node: Awk Debugging789765 +Node: Sample Debugging Session790657 +Node: Debugger Invocation791177 +Node: Finding The Bug792510 +Node: List of Debugger Commands798997 +Node: Breakpoint Control800331 +Node: Debugger Execution Control803995 +Node: Viewing And Changing Data807355 +Node: Execution Stack810711 +Node: Debugger Info812178 +Node: Miscellaneous Debugger Commands816160 +Node: Readline Support821336 +Node: Limitations822167 +Node: Arbitrary Precision Arithmetic824419 +Ref: Arbitrary Precision Arithmetic-Footnote-1826068 +Node: General Arithmetic826216 +Node: Floating Point Issues827936 +Node: String Conversion Precision828817 +Ref: String Conversion Precision-Footnote-1830522 +Node: Unexpected Results830631 +Node: POSIX Floating Point Problems832784 +Ref: POSIX Floating Point Problems-Footnote-1836609 +Node: Integer Programming836647 +Node: Floating-point Programming838386 +Ref: Floating-point Programming-Footnote-1844717 +Ref: Floating-point Programming-Footnote-2844987 +Node: Floating-point Representation845251 +Node: Floating-point Context846416 +Ref: table-ieee-formats847255 +Node: Rounding Mode848639 +Ref: table-rounding-modes849118 +Ref: Rounding Mode-Footnote-1852133 +Node: Gawk and MPFR852312 +Node: Arbitrary Precision Floats853567 +Ref: Arbitrary Precision Floats-Footnote-1856010 +Node: Setting Precision856326 +Ref: table-predefined-precision-strings857012 +Node: Setting Rounding Mode859157 +Ref: table-gawk-rounding-modes859561 +Node: Floating-point Constants860748 +Node: Changing Precision862177 +Ref: Changing Precision-Footnote-1863574 +Node: Exact Arithmetic863748 +Node: Arbitrary Precision Integers866886 +Ref: Arbitrary Precision Integers-Footnote-1869901 +Node: Dynamic Extensions870048 +Node: Extension Intro871506 +Node: Plugin License872771 +Node: Extension Mechanism Outline873456 +Ref: load-extension873873 +Ref: load-new-function875351 +Ref: call-new-function876346 +Node: Extension API Description878361 +Node: Extension API Functions Introduction879648 +Node: General Data Types884575 +Ref: General Data Types-Footnote-1890270 +Node: Requesting Values890569 +Ref: table-value-types-returned891306 +Node: Memory Allocation Functions892260 +Ref: Memory Allocation Functions-Footnote-1895006 +Node: Constructor Functions895102 +Node: Registration Functions896860 +Node: Extension Functions897545 +Node: Exit Callback Functions899847 +Node: Extension Version String901096 +Node: Input Parsers901746 +Node: Output Wrappers911503 +Node: Two-way processors916013 +Node: Printing Messages918221 +Ref: Printing Messages-Footnote-1919298 +Node: Updating `ERRNO'919450 +Node: Accessing Parameters920189 +Node: Symbol Table Access921419 +Node: Symbol table by name921933 +Node: Symbol table by cookie923909 +Ref: Symbol table by cookie-Footnote-1928041 +Node: Cached values928104 +Ref: Cached values-Footnote-1931594 +Node: Array Manipulation931685 +Ref: Array Manipulation-Footnote-1932783 +Node: Array Data Types932822 +Ref: Array Data Types-Footnote-1935525 +Node: Array Functions935617 +Node: Flattening Arrays939453 +Node: Creating Arrays946305 +Node: Extension API Variables951030 +Node: Extension Versioning951666 +Node: Extension API Informational Variables953567 +Node: Extension API Boilerplate954653 +Node: Finding Extensions958457 +Node: Extension Example959017 +Node: Internal File Description959747 +Node: Internal File Ops963838 +Ref: Internal File Ops-Footnote-1975347 +Node: Using Internal File Ops975487 +Ref: Using Internal File Ops-Footnote-1977840 +Node: Extension Samples978106 +Node: Extension Sample File Functions979630 +Node: Extension Sample Fnmatch988115 +Node: Extension Sample Fork989884 +Node: Extension Sample Inplace991097 +Node: Extension Sample Ord992875 +Node: Extension Sample Readdir993711 +Node: Extension Sample Revout995243 +Node: Extension Sample Rev2way995836 +Node: Extension Sample Read write array996526 +Node: Extension Sample Readfile998409 +Node: Extension Sample API Tests999509 +Node: Extension Sample Time1000034 +Node: gawkextlib1001398 +Node: Language History1004179 +Node: V7/SVR3.11005772 +Node: SVR41008092 +Node: POSIX1009534 +Node: BTL1010920 +Node: POSIX/GNU1011654 +Node: Feature History1017253 +Node: Common Extensions1030229 +Node: Ranges and Locales1031541 +Ref: Ranges and Locales-Footnote-11036158 +Ref: Ranges and Locales-Footnote-21036185 +Ref: Ranges and Locales-Footnote-31036419 +Node: Contributors1036640 +Node: Installation1042021 +Node: Gawk Distribution1042915 +Node: Getting1043399 +Node: Extracting1044225 +Node: Distribution contents1045917 +Node: Unix Installation1051622 +Node: Quick Installation1052239 +Node: Additional Configuration Options1054685 +Node: Configuration Philosophy1056421 +Node: Non-Unix Installation1058775 +Node: PC Installation1059233 +Node: PC Binary Installation1060532 +Node: PC Compiling1062380 +Node: PC Testing1065324 +Node: PC Using1066500 +Node: Cygwin1070668 +Node: MSYS1071477 +Node: VMS Installation1071991 +Node: VMS Compilation1072755 +Ref: VMS Compilation-Footnote-11074007 +Node: VMS Dynamic Extensions1074065 +Node: VMS Installation Details1075438 +Node: VMS Running1077689 +Node: VMS GNV1080523 +Node: VMS Old Gawk1081246 +Node: Bugs1081716 +Node: Other Versions1085634 +Node: Notes1091718 +Node: Compatibility Mode1092518 +Node: Additions1093301 +Node: Accessing The Source1094228 +Node: Adding Code1095668 +Node: New Ports1101713 +Node: Derived Files1105848 +Ref: Derived Files-Footnote-11111169 +Ref: Derived Files-Footnote-21111203 +Ref: Derived Files-Footnote-31111803 +Node: Future Extensions1111901 +Node: Implementation Limitations1112484 +Node: Extension Design1113736 +Node: Old Extension Problems1114890 +Ref: Old Extension Problems-Footnote-11116398 +Node: Extension New Mechanism Goals1116455 +Ref: Extension New Mechanism Goals-Footnote-11119820 +Node: Extension Other Design Decisions1120006 +Node: Extension Future Growth1122112 +Node: Old Extension Mechanism1122948 +Node: Basic Concepts1124688 +Node: Basic High Level1125369 +Ref: figure-general-flow1125640 +Ref: figure-process-flow1126239 +Ref: Basic High Level-Footnote-11129468 +Node: Basic Data Typing1129653 +Node: Glossary1133008 +Node: Copying1158237 +Node: GNU Free Documentation License1195794 +Node: Index1220931 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 1b610c42..b9d65bd0 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -134,6 +134,30 @@ @end macro @end ifnothtml +@c Indexing macros +@ifinfo + +@macro cindexawkfunc{name} +@cindex @code{\name\} +@end macro + +@macro cindexgawkfunc{name} +@cindex @code{\name\} +@end macro + +@end ifinfo + +@ifnotinfo + +@macro cindexawkfunc{name} +@cindex @code{\name\()} function +@end macro + +@macro cindexgawkfunc{name} +@cindex @code{\name\()} function (@command{gawk}) +@end macro +@end ifnotinfo + @ignore Some comments on the layout for TeX. 1. Use at least texinfo.tex 2014-01-30.15 @@ -2070,11 +2094,11 @@ $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @print{} Don't Panic! @end example -@cindex quoting -@cindex double quote (@code{"}) -@cindex @code{"} (double quote) -@cindex @code{\} (backslash) -@cindex backslash (@code{\}) +@cindex shell quoting, double quote +@cindex double quote (@code{"}) in shell commands +@cindex @code{"} (double quote) in shell commands +@cindex @code{\} (backslash) in shell commands +@cindex backslash (@code{\}) in shell commands This program does not read any input. The @samp{\} before each of the inner double quotes is necessary because of the shell's quoting rules---in particular because it mixes both single quotes and @@ -2114,8 +2138,7 @@ awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{} @end example @cindex @option{-f} option -@cindex command line, options -@cindex options, command-line +@cindex command line, option @option{-f} The @option{-f} instructs the @command{awk} utility to get the @command{awk} program from the file @var{source-file}. Any file name can be used for @var{source-file}. For example, you could put the program: @@ -2138,7 +2161,7 @@ does the same thing as this one: awk "BEGIN @{ print \"Don't Panic!\" @}" @end example -@cindex quoting +@cindex quoting in @command{gawk} command lines @noindent This was explained earlier (@pxref{Read Terminal}). @@ -2149,9 +2172,9 @@ program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. @c STARTOFRANGE sq1x -@cindex single quote (@code{'}) +@cindex single quote (@code{'}) in @command{gawk} command lines @c STARTOFRANGE qs2x -@cindex @code{'} (single quote) +@cindex @code{'} (single quote) in @command{gawk} command lines If you want to clearly identify your @command{awk} program files as such, you can add the extension @file{.awk} to the file name. This doesn't affect the execution of the @command{awk} program but it does make @@ -2300,7 +2323,7 @@ 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. -@cindex quoting +@cindex quoting, for small awk programs @cindex single quote (@code{'}), vs.@: apostrophe @cindex @code{'} (single quote), vs.@: apostrophe @quotation CAUTION @@ -2341,7 +2364,7 @@ The next @value{SUBSECTION} describes the shell's quoting rules. @node Quoting @subsection Shell-Quoting Issues -@cindex quoting, rules for +@cindex shell quoting, rules for @menu * DOS Quoting:: Quoting in Windows Batch Files. @@ -2376,10 +2399,10 @@ that character. The shell removes the backslash and passes the quoted character on to the command. @item -@cindex @code{\} (backslash) -@cindex backslash (@code{\}) -@cindex single quote (@code{'}) -@cindex @code{'} (single quote) +@cindex @code{\} (backslash), in shell commands +@cindex backslash (@code{\}), in shell commands +@cindex single quote (@code{'}), in shell commands +@cindex @code{'} (single quote), in shell commands Single quotes protect everything between the opening and closing quotes. The shell does no interpretation of the quoted text, passing it on verbatim to the command. @@ -2389,8 +2412,8 @@ Refer back to for an example of what happens if you try. @item -@cindex double quote (@code{"}) -@cindex @code{"} (double quote) +@cindex double quote (@code{"}), in shell commands +@cindex @code{"} (double quote), in shell commands Double quotes protect most things between the opening and closing quotes. The shell does at least variable and command substitution on the quoted text. Different shells may do additional kinds of processing on double-quoted text. @@ -2427,7 +2450,7 @@ awk -F "" '@var{program}' @var{files} # correct @end example @noindent -@cindex null strings, quoting and +@cindex null strings in @command{gawk} arguments, quoting and Don't use this: @example @@ -2440,7 +2463,7 @@ as the value of @code{FS}, and the first file name as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize -@cindex quoting, tricks for +@cindex quoting in @command{gawk} command lines, tricks for Mixing single and double quotes is difficult. You have to resort to shell quoting tricks, like this: @@ -2555,40 +2578,39 @@ gawk "@{ print \"\042\" $0 \"\042\" @}" @var{file} @c For gawk >= 4.0, update these data files. No-one has such slow modems! @cindex input files, examples -@cindex @code{BBS-list} file +@cindex @code{mail-list} file Many of the examples in this @value{DOCUMENT} take their input from two sample -data files. The first, @file{BBS-list}, represents a list of -computer bulletin board systems together with information about those systems. +data files. The first, @file{mail-list}, represents a list of peoples' names +together with their email addresses and information about those people. The second data file, called @file{inventory-shipped}, contains information about monthly shipments. In both files, each line is considered to be one @dfn{record}. -In the data file @file{BBS-list}, each record contains the name of a computer -bulletin board, its phone number, the board's baud rate(s), and a code for -the number of hours it is operational. An @samp{A} in the last column -means the board operates 24 hours a day. A @samp{B} in the last -column means the board only operates on evening and weekend hours. -A @samp{C} means the board operates only on weekends: +In the data file @file{mail-list}, each record contains the name of a person, +his/her phone number, his/her email-address, and a code for their relationship +with the author of the list. An @samp{A} in the last column +means that the person is an acquaintance. An @samp{F} in the last +column means that the person is a friend. +An @samp{R} means that the person is a relative: -@c 2e: Update the baud rates to reflect today's faster modems @example @c system if test ! -d eg ; then mkdir eg ; fi @c system if test ! -d eg/lib ; then mkdir eg/lib ; fi @c system if test ! -d eg/data ; then mkdir eg/data ; fi @c system if test ! -d eg/prog ; then mkdir eg/prog ; fi @c system if test ! -d eg/misc ; then mkdir eg/misc ; fi -@c file eg/data/BBS-list -aardvark 555-5553 1200/300 B -alpo-net 555-3412 2400/1200/300 A -barfly 555-7685 1200/300 A -bites 555-1675 2400/1200/300 A -camelot 555-0542 300 C -core 555-2912 1200/300 C -fooey 555-1234 2400/1200/300 B -foot 555-6699 1200/300 B -macfoo 555-6480 1200/300 A -sdace 555-3430 2400/1200/300 A -sabafoo 555-2127 1200/300 C +@c file eg/data/mail-list +Amelia 555-5553 amelia.zodiacusque@@gmail.com F +Anthony 555-3412 anthony.asserturo@@hotmail.com A +Becky 555-7685 becky.algebrarum@@gmail.com A +Bill 555-1675 bill.drowning@@hotmail.com A +Broderick 555-0542 broderick.aliquotiens@@yahoo.com R +Camilla 555-2912 camilla.infusarum@@skynet.be R +Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +Julie 555-6699 julie.perscrutabor@@skeeve.com F +Martin 555-6480 martin.codicibus@@hotmail.com A +Samuel 555-3430 samuel.lanceolis@@shu.edu A +Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @c endfile @end example @@ -2630,23 +2652,23 @@ in the directory @file{awklib/eg/data}. @section Some Simple Examples The following command runs a simple @command{awk} program that searches the -input file @file{BBS-list} for the character string @samp{foo} (a +input file @file{mail-list} for the character string @samp{li} (a grouping of characters is usually called a @dfn{string}; the term @dfn{string} is based on similar usage in English, such as ``a string of pearls,'' or ``a string of cars in a train''): @example -awk '/foo/ @{ print $0 @}' BBS-list +awk '/li/ @{ print $0 @}' mail-list @end example @noindent -When lines containing @samp{foo} are found, they are printed because +When lines containing @samp{li} are found, they are printed because @w{@samp{print $0}} means print the current line. (Just @samp{print} by itself means the same thing, so we could have written that instead.) -You will notice that slashes (@samp{/}) surround the string @samp{foo} -in the @command{awk} program. The slashes indicate that @samp{foo} +You will notice that slashes (@samp{/}) surround the string @samp{li} +in the @command{awk} program. The slashes indicate that @samp{li} is the pattern to search for. This type of pattern is called a @dfn{regular expression}, which is covered in more detail later (@pxref{Regexp}). @@ -2658,11 +2680,11 @@ interpret any of it as special shell characters. Here is what this program prints: @example -$ @kbd{awk '/foo/ @{ print $0 @}' BBS-list} -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sabafoo 555-2127 1200/300 C +$ @kbd{awk '/li/ @{ print $0 @}' mail-list} +@print{} Amelia 555-5553 amelia.zodiacusque@@gmail.com F +@print{} Broderick 555-0542 broderick.aliquotiens@@yahoo.com R +@print{} Julie 555-6699 julie.perscrutabor@@skeeve.com F +@print{} Samuel 555-3430 samuel.lanceolis@@shu.edu A @end example @cindex actions, default @@ -2675,7 +2697,7 @@ action is to print all lines that match the pattern. @cindex actions, empty Thus, we could leave out the action (the @code{print} statement and the curly braces) in the previous example and the result would be the same: -@command{awk} prints all lines matching the pattern @samp{foo}. By comparison, +@command{awk} prints all lines matching the pattern @samp{li}. By comparison, omitting the @code{print} statement but retaining the curly braces makes an empty action that does nothing (i.e., no lines are printed). @@ -2820,29 +2842,23 @@ This program prints every line that contains the string strings, it is printed twice, once by each rule. This is what happens if we run this program on our two sample data files, -@file{BBS-list} and @file{inventory-shipped}: +@file{mail-list} and @file{inventory-shipped}: @example $ @kbd{awk '/12/ @{ print $0 @}} -> @kbd{/21/ @{ print $0 @}' BBS-list inventory-shipped} -@print{} aardvark 555-5553 1200/300 B -@print{} alpo-net 555-3412 2400/1200/300 A -@print{} barfly 555-7685 1200/300 A -@print{} bites 555-1675 2400/1200/300 A -@print{} core 555-2912 1200/300 C -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sdace 555-3430 2400/1200/300 A -@print{} sabafoo 555-2127 1200/300 C -@print{} sabafoo 555-2127 1200/300 C +> @kbd{/21/ @{ print $0 @}' mail-list inventory-shipped} +@print{} Anthony 555-3412 anthony.asserturo@@hotmail.com A +@print{} Camilla 555-2912 camilla.infusarum@@skynet.be R +@print{} Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @print{} Jan 21 36 64 620 @print{} Apr 21 70 74 514 @end example @noindent -Note how the line beginning with @samp{sabafoo} -in @file{BBS-list} was printed twice, once for each rule. +Note how the line beginning with @samp{Jean-Paul} +in @file{mail-list} was printed twice, once for each rule. @node More Complex @section A More Complex Example @@ -2921,7 +2937,7 @@ separate rule, like this: @example awk '/12/ @{ print $0 @} - /21/ @{ print $0 @}' BBS-list inventory-shipped + /21/ @{ print $0 @}' mail-list inventory-shipped @end example @cindex @command{gawk}, newlines in @@ -3329,6 +3345,7 @@ Print the short version of the General Public License and then exit. @itemx --dump-variables@r{[}=@var{file}@r{]} @cindex @option{-d} option @cindex @option{--dump-variables} option +@cindex dump all variables of a program @cindex @file{awkvars.out} file @cindex files, @file{awkvars.out} @cindex variables, global, printing list of @@ -3482,7 +3499,7 @@ care to search for all occurrences of each inappropriate construct. As @cindex @option{--bignum} option Force arbitrary precision arithmetic on numbers. This option has no effect if @command{gawk} is not compiled to use the GNU MPFR and MP libraries -(@pxref{Arbitrary Precision Arithmetic}). +(@pxref{Gawk and MPFR}). @item -n @itemx --non-decimal-data @@ -3735,6 +3752,7 @@ file at all. @cindex @command{gawk}, @code{ARGIND} variable in @cindex @code{ARGIND} variable, command-line arguments +@cindex @code{ARGV} array, indexing into @cindex @code{ARGC}/@code{ARGV} variables, command-line arguments All these arguments are made available to your @command{awk} program in the @code{ARGV} array (@pxref{Built-in Variables}). Command-line options @@ -3745,6 +3763,7 @@ sets the variable @code{ARGIND} to the index in @code{ARGV} of the current element. @cindex input files, variable assignments and +@cindex variable assignments and input files The distinction between file name arguments and variable-assignment arguments is made when @command{awk} is about to open the next input file. At that point in execution, it checks the file name to see whether @@ -3822,6 +3841,7 @@ this file name itself.) @node Environment Variables @section The Environment Variables @command{gawk} Uses +@cindex environment variables used by @command{gawk} A number of environment variables influence how @command{gawk} behaves. @@ -3837,8 +3857,7 @@ behaves. @node AWKPATH Variable @subsection The @env{AWKPATH} Environment Variable @cindex @env{AWKPATH} environment variable -@cindex directories, searching -@cindex search paths +@cindex directories, searching for source files @cindex search paths, for source files @cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable @ifinfo @@ -3850,12 +3869,12 @@ implementations, you must supply a precise path name for each program file, unless the file is in the current directory. But in @command{gawk}, if the file name supplied to the @option{-f} or @option{-i} options -does not contain a @samp{/}, then @command{gawk} searches a list of +does not contain a directory separator @samp{/}, then @command{gawk} searches a list of directories (called the @dfn{search path}), one by one, looking for a file with the specified name. The search path is a string consisting of directory names -separated by colons. @command{gawk} gets its search path from the +separated by colons@footnote{Semicolons on MS-Windows and MS-DOS.}. @command{gawk} gets its search path from the @env{AWKPATH} environment variable. If that variable does not exist, @command{gawk} uses a default path, @samp{.:/usr/local/share/awk}.@footnote{Your version of @command{gawk} @@ -3913,8 +3932,7 @@ found, and @command{gawk} no longer needs to use @env{AWKPATH}. @node AWKLIBPATH Variable @subsection The @env{AWKLIBPATH} Environment Variable @cindex @env{AWKLIBPATH} environment variable -@cindex directories, searching -@cindex search paths +@cindex directories, searching for shared libraries @cindex search paths, for shared libraries @cindex differences in @command{awk} and @command{gawk}, @code{AWKLIBPATH} environment variable @@ -4199,7 +4217,6 @@ they will @emph{not} be in the next release). @c update this section for each release! -@cindex @code{PROCINFO} array The process-related special files @file{/dev/pid}, @file{/dev/ppid}, @file{/dev/pgrpid}, and @file{/dev/user} were deprecated in @command{gawk} 3.1, but still worked. As of version 4.0, they are no longer @@ -4284,7 +4301,7 @@ long-undocumented ``feature'' of Unix @code{awk}. @node Regexp @chapter Regular Expressions -@cindex regexp, See regular expressions +@cindex regexp @c STARTOFRANGE regexp @cindex regular expressions @@ -4293,8 +4310,8 @@ set of strings. Because regular expressions are such a fundamental part of @command{awk} programming, their format and use deserve a separate @value{CHAPTER}. -@cindex forward slash (@code{/}) -@cindex @code{/} (forward slash) +@cindex forward slash (@code{/}) to enclose regular expressions +@cindex @code{/} (forward slash) to enclose regular expressions A regular expression enclosed in slashes (@samp{/}) is an @command{awk} pattern that matches every input record whose text belongs to that set. @@ -4331,14 +4348,14 @@ slashes. Then the regular expression is tested against the entire text of each record. (Normally, it only needs to match some part of the text in order to succeed.) For example, the following prints the second field of each record that contains the string -@samp{foo} anywhere in it: +@samp{li} anywhere in it: @example -$ @kbd{awk '/foo/ @{ print $2 @}' BBS-list} -@print{} 555-1234 +$ @kbd{awk '/li/ @{ print $2 @}' mail-list} +@print{} 555-5553 +@print{} 555-0542 @print{} 555-6699 -@print{} 555-6480 -@print{} 555-2127 +@print{} 555-3430 @end example @cindex regular expressions, operators @@ -4350,9 +4367,9 @@ $ @kbd{awk '/foo/ @{ print $2 @}' BBS-list} @cindex @code{!} (exclamation point), @code{!~} operator @cindex exclamation point (@code{!}), @code{!~} operator @c @cindex operators, @code{!~} -@cindex @code{if} statement -@cindex @code{while} statement -@cindex @code{do}-@code{while} statement +@cindex @code{if} statement, use of regexps in +@cindex @code{while} statement, use of regexps in +@cindex @code{do}-@code{while} statement, use of regexps in @c @cindex statements, @code{if} @c @cindex statements, @code{while} @c @cindex statements, @code{do} @@ -4411,6 +4428,7 @@ $ @kbd{awk '$1 !~ /J/' inventory-shipped} @end example @cindex regexp constants +@cindex constant regexps @cindex regular expressions, constants, See regexp constants When a regexp is enclosed in slashes, such as @code{/foo/}, we call it a @dfn{regexp constant}, much like @code{5.27} is a numeric constant and @@ -4419,7 +4437,7 @@ a @dfn{regexp constant}, much like @code{5.27} is a numeric constant and @node Escape Sequences @section Escape Sequences -@cindex escape sequences +@cindex escape sequences, in strings @cindex backslash (@code{\}), in escape sequences @cindex @code{\} (backslash), in escape sequences Some characters cannot be included literally in string constants @@ -4713,6 +4731,7 @@ escape sequences literally when used in regexp constants. Thus, @section Regular Expression Operators @c STARTOFRANGE regexpo @cindex regular expressions, operators +@cindex metacharacters in regular expressions You can combine regular expressions with special characters, called @dfn{regular expression operators} or @dfn{metacharacters}, to @@ -4731,8 +4750,8 @@ Here is a list of metacharacters. All characters that are not escape sequences and that are not listed in the table stand for themselves: @table @code -@cindex backslash (@code{\}) -@cindex @code{\} (backslash) +@cindex backslash (@code{\}), regexp operator +@cindex @code{\} (backslash), regexp operator @item \ This is used to suppress the special meaning of a character when matching. For example, @samp{\$} @@ -4770,8 +4789,8 @@ The condition in the following example is not true: if ("line1\nLINE 2" ~ /1$/) @dots{} @end example -@cindex @code{.} (period) -@cindex period (@code{.}) +@cindex @code{.} (period), regexp operator +@cindex period (@code{.}), regexp operator @item . @r{(period)} This matches any single character, @emph{including} the newline character. For example, @samp{.P} @@ -4787,8 +4806,8 @@ character, which is a character with all bits equal to zero. Otherwise, @sc{nul} is just another character. Other versions of @command{awk} may not be able to match the @sc{nul} character. -@cindex @code{[]} (square brackets) -@cindex square brackets (@code{[]}) +@cindex @code{[]} (square brackets), regexp operator +@cindex square brackets (@code{[]}), regexp operator @cindex bracket expressions @cindex character sets, See Also bracket expressions @cindex character lists, See bracket expressions @@ -4825,8 +4844,8 @@ means it matches any string that starts with @samp{P} or contains a digit. The alternation applies to the largest possible regexps on either side. -@cindex @code{()} (parentheses) -@cindex parentheses @code{()} +@cindex @code{()} (parentheses), regexp operator +@cindex parentheses @code{()}, regexp operator @item (@dots{}) Parentheses are used for grouping in regular expressions, as in arithmetic. They can be used to concatenate regular expressions @@ -4875,7 +4894,7 @@ This symbol is similar to @samp{*}, except that the preceding expression can be matched either once or not at all. For example, @samp{fe?d} matches @samp{fed} and @samp{fd}, but nothing else. -@cindex interval expressions +@cindex interval expressions, regexp operator @item @{@var{n}@} @itemx @{@var{n},@} @itemx @{@var{n},@var{m}@} @@ -4952,6 +4971,7 @@ expressions are not available in regular expressions. @cindex bracket expressions @cindex bracket expressions, range expressions @cindex range expressions (regexps) +@cindex character lists in regular expression As mentioned earlier, a bracket expression matches any character amongst those listed between the opening and closing square brackets. @@ -5215,7 +5235,7 @@ lesser of two evils. @c @c Should really do this with file inclusion. @cindex regular expressions, @command{gawk}, command-line options -@cindex @command{gawk}, command-line options +@cindex @command{gawk}, command-line options, and regular expressions The various command-line options (@pxref{Options}) control how @command{gawk} interprets characters in regexps: @@ -5294,7 +5314,7 @@ This works in any POSIX-compliant @command{awk}. @cindex tilde (@code{~}), @code{~} operator @cindex @code{!} (exclamation point), @code{!~} operator @cindex exclamation point (@code{!}), @code{!~} operator -@cindex @code{IGNORECASE} variable +@cindex @code{IGNORECASE} variable, with @code{~} and @code{!~} operators @cindex @command{gawk}, @code{IGNORECASE} variable in @c @cindex variables, @code{IGNORECASE} Another method, specific to @command{gawk}, is to set the variable @@ -5559,6 +5579,7 @@ occur often in practice, but it's worth noting for future reference. @chapter Reading Input Files @c STARTOFRANGE infir +@cindex reading input files @cindex input files, reading @cindex input files @cindex @code{FILENAME} variable @@ -5645,68 +5666,79 @@ To do this, use the special @code{BEGIN} pattern (@pxref{BEGIN/END}). For example: -@cindex @code{BEGIN} pattern @example -awk 'BEGIN @{ RS = "/" @} - @{ print $0 @}' BBS-list +awk 'BEGIN @{ RS = "u" @} + @{ print $0 @}' mail-list @end example @noindent -changes the value of @code{RS} to @code{"/"}, before reading any input. -This is a string whose first character is a slash; as a result, records -are separated by slashes. Then the input file is read, and the second +changes the value of @code{RS} to @samp{u}, before reading any input. +This is a string whose first character is the letter ``u;'' as a result, records +are separated by the letter ``u.'' Then the input file is read, and the second rule in the @command{awk} program (the action with no pattern) prints each record. Because each @code{print} statement adds a newline at the end of its output, this @command{awk} program copies the input -with each slash changed to a newline. Here are the results of running -the program on @file{BBS-list}: - -@example -$ @kbd{awk 'BEGIN @{ RS = "/" @}} -> @kbd{@{ print $0 @}' BBS-list} -@print{} aardvark 555-5553 1200 -@print{} 300 B -@print{} alpo-net 555-3412 2400 -@print{} 1200 -@print{} 300 A -@print{} barfly 555-7685 1200 -@print{} 300 A -@print{} bites 555-1675 2400 -@print{} 1200 -@print{} 300 A -@print{} camelot 555-0542 300 C -@print{} core 555-2912 1200 -@print{} 300 C -@print{} fooey 555-1234 2400 -@print{} 1200 -@print{} 300 B -@print{} foot 555-6699 1200 -@print{} 300 B -@print{} macfoo 555-6480 1200 -@print{} 300 A -@print{} sdace 555-3430 2400 -@print{} 1200 -@print{} 300 A -@print{} sabafoo 555-2127 1200 -@print{} 300 C -@print{} +with each @samp{u} changed to a newline. Here are the results of running +the program on @file{mail-list}: + +@example +$ @kbd{awk 'BEGIN @{ RS = "u" @}} +> @kbd{@{ print $0 @}' mail-list} +@print{} Amelia 555-5553 amelia.zodiac +@print{} sq +@print{} e@@gmail.com F +@print{} Anthony 555-3412 anthony.assert +@print{} ro@@hotmail.com A +@print{} Becky 555-7685 becky.algebrar +@print{} m@@gmail.com A +@print{} Bill 555-1675 bill.drowning@@hotmail.com A +@print{} Broderick 555-0542 broderick.aliq +@print{} otiens@@yahoo.com R +@print{} Camilla 555-2912 camilla.inf +@print{} sar +@print{} m@@skynet.be R +@print{} Fabi +@print{} s 555-1234 fabi +@print{} s. +@print{} ndevicesim +@print{} s@@ +@print{} cb.ed +@print{} F +@print{} J +@print{} lie 555-6699 j +@print{} lie.perscr +@print{} tabor@@skeeve.com F +@print{} Martin 555-6480 martin.codicib +@print{} s@@hotmail.com A +@print{} Sam +@print{} el 555-3430 sam +@print{} el.lanceolis@@sh +@print{} .ed +@print{} A +@print{} Jean-Pa +@print{} l 555-2127 jeanpa +@print{} l.campanor +@print{} m@@ny +@print{} .ed +@print{} R +@print{} @end example @noindent -Note that the entry for the @samp{camelot} BBS is not split. +Note that the entry for the name @samp{Bill} is not split. In the original data file (@pxref{Sample Data Files}), the line looks like this: @example -camelot 555-0542 300 C +Bill 555-1675 bill.drowning@@hotmail.com A @end example @noindent -It has one baud rate only, so there are no slashes in the record, -unlike the others which have two or more baud rates. -In fact, this record is treated as part of the record -for the @samp{core} BBS; the newline separating them in the output +It contains no @samp{u} so there is no reason to split the record, +unlike the others which have one or more occurrences of the @samp{u}. +In fact, this record is treated as part of the previous record; +the newline separating them in the output is the original newline in the data file, not the one added by @command{awk} when it printed the record! @@ -5717,14 +5749,17 @@ using the variable-assignment feature (@pxref{Other Arguments}): @example -awk '@{ print $0 @}' RS="/" BBS-list +awk '@{ print $0 @}' RS="u" mail-list @end example @noindent -This sets @code{RS} to @samp{/} before processing @file{BBS-list}. +This sets @code{RS} to @samp{u} before processing @file{mail-list}. -Using an unusual character such as @samp{/} for the record separator -produces correct behavior in the vast majority of cases. +Using an alphabetic character such as @samp{u} for the record separator +is highly likely to produce strange results. +Using an unusual character such as @samp{/} is more likely to +produce correct behavior in the majority of cases, but there +are no guarantees. The moral is: Know Your Data. There is one unusual case, that occurs when @command{gawk} is being fully POSIX-compliant (@pxref{Options}). @@ -5746,6 +5781,7 @@ Reaching the end of an input file terminates the current input record, even if the last character in the file is not the character in @code{RS}. @value{DARKCORNER} +@cindex empty strings @cindex null strings @cindex strings, empty, See null strings The empty string @code{""} (a string without any characters) @@ -5882,7 +5918,7 @@ character as a record separator. However, this is a special case: @command{mawk} does not allow embedded @sc{nul} characters in strings. @cindex records, treating files as -@cindex files, as single records +@cindex treating files, as single records The best way to treat a whole file as a single record is to simply read the file in, one record at a time, concatenating each record onto the end of the previous ones. @@ -5933,7 +5969,7 @@ character as a record separator. However, this is a special case: @command{mawk} does not allow embedded @sc{nul} characters in strings. @cindex records, treating files as -@cindex files, as single records +@cindex treating files, as single records The best way to treat a whole file as a single record is to simply read the file in, one record at a time, concatenating each record onto the end of the previous ones. @@ -6011,31 +6047,29 @@ when you are not interested in specific fields. Here are some more examples: @example -$ @kbd{awk '$1 ~ /foo/ @{ print $0 @}' BBS-list} -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sabafoo 555-2127 1200/300 C +$ @kbd{awk '$1 ~ /li/ @{ print $0 @}' mail-list} +@print{} Amelia 555-5553 amelia.zodiacusque@@gmail.com F +@print{} Julie 555-6699 julie.perscrutabor@@skeeve.com F @end example @noindent -This example prints each record in the file @file{BBS-list} whose first -field contains the string @samp{foo}. The operator @samp{~} is called a +This example prints each record in the file @file{mail-list} whose first +field contains the string @samp{li}. The operator @samp{~} is called a @dfn{matching operator} (@pxref{Regexp Usage}); it tests whether a string (here, the field @code{$1}) matches a given regular expression. By contrast, the following example -looks for @samp{foo} in @emph{the entire record} and prints the first +looks for @samp{li} in @emph{the entire record} and prints the first field and the last field for each matching input record: @example -$ @kbd{awk '/foo/ @{ print $1, $NF @}' BBS-list} -@print{} fooey B -@print{} foot B -@print{} macfoo A -@print{} sabafoo C +$ @kbd{awk '/li/ @{ print $1, $NF @}' mail-list} +@print{} Amelia F +@print{} Broderick R +@print{} Julie F +@print{} Samuel A @end example @c ENDOFRANGE fiex @@ -6063,7 +6097,7 @@ the record has fewer than 20 fields, so this prints a blank line. Here is another example of using expressions as field numbers: @example -awk '@{ print $(2*2) @}' BBS-list +awk '@{ print $(2*2) @}' mail-list @end example @command{awk} evaluates the expression @samp{(2*2)} and uses @@ -6072,8 +6106,8 @@ represents multiplication, so the expression @samp{2*2} evaluates to four. The parentheses are used so that the multiplication is done before the @samp{$} operation; they are 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 -@file{BBS-list}. (All of the @command{awk} operators are listed, in +type of relationship (the fourth field) for every line of the file +@file{mail-list}. (All of the @command{awk} operators are listed, in order of decreasing precedence, in @ref{Precedence}.) @@ -6582,10 +6616,8 @@ behaves this way. @node Command Line Field Separator @subsection Setting @code{FS} from the Command Line -@cindex @option{-F} option -@cindex options, command-line -@cindex command line, options -@cindex field separators, on command line +@cindex @option{-F} option, command line +@cindex field separator, on command line @cindex command line, @code{FS} on@comma{} setting @cindex @code{FS} variable, setting from command line @@ -6635,66 +6667,59 @@ figures that you really want your fields to be separated with TABs and not @samp{t}s. Use @samp{-v FS="t"} or @samp{-F"[t]"} on the command line if you really do want to separate your fields with @samp{t}s. -As an example, let's use an @command{awk} program file called @file{baud.awk} -that contains the pattern @code{/300/} and the action @samp{print $1}: +As an example, let's use an @command{awk} program file called @file{edu.awk} +that contains the pattern @code{/edu/} and the action @samp{print $1}: @example -/300/ @{ print $1 @} +/edu/ @{ print $1 @} @end example Let's also set @code{FS} to be the @samp{-} character and run the -program on the file @file{BBS-list}. The following command prints a -list of the names of the bulletin boards that operate at 300 baud and +program on the file @file{mail-list}. The following command prints a +list of the names of the people that work at or attend a university, and the first three digits of their phone numbers: @c tweaked to make the tex output look better in @smallbook @example -$ @kbd{awk -F- -f baud.awk BBS-list} -@print{} aardvark 555 -@print{} alpo -@print{} barfly 555 -@print{} bites 555 -@print{} camelot 555 -@print{} core 555 -@print{} fooey 555 -@print{} foot 555 -@print{} macfoo 555 -@print{} sdace 555 -@print{} sabafoo 555 +$ @kbd{awk -F- -f edu.awk mail-list} +@print{} Fabius 555 +@print{} Samuel 555 +@print{} Jean @end example @noindent -Note the second line of output. The second line +Note the third line of output. The third line in the original file looked like this: @example -alpo-net 555-3412 2400/1200/300 A +Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example -The @samp{-} as part of the system's name was used as the field +The @samp{-} as part of the person's name was used as the field separator, instead of the @samp{-} in the phone number that was originally intended. This demonstrates why you have to be careful in choosing your field and record separators. @cindex Unix @command{awk}, password files@comma{} field separators and -Perhaps the most common use of a single character as the field -separator occurs when processing the Unix system password file. -On many Unix systems, each user has a separate entry in the system password -file, one line per user. The information in these lines is separated -by colons. The first field is the user's login name and the second is -the user's (encrypted or shadow) password. A password file entry might look -like this: +Perhaps the most common use of a single character as the field separator +occurs when processing the Unix system password file. On many Unix +systems, each user has a separate entry in the system password file, one +line per user. The information in these lines is separated by colons. +The first field is the user's login name and the second is the user's +encrypted or shadow password. (A shadow password is indicated by the +presence of a single @samp{x} in the second field.) A password file +entry might look like this: @cindex Robbins, Arnold @example -arnold:xyzzy:2076:10:Arnold Robbins:/home/arnold:/bin/bash +arnold:x:2076:10:Arnold Robbins:/home/arnold:/bin/bash @end example The following program searches the system password file and prints -the entries for users who have no password: +the entries for users whose full name is not indicated: @example -awk -F: '$2 == ""' /etc/passwd +awk -F: '$5 == ""' /etc/passwd @end example @node Full Line Fields @@ -6757,7 +6782,7 @@ POSIX standard.) @cindex POSIX @command{awk}, field separators and -@cindex field separators, POSIX and +@cindex field separator, POSIX and According to the POSIX standard, @command{awk} is supposed to behave as if each record is split into fields at the time it is read. In particular, this means that if you change the value of @code{FS} @@ -6810,7 +6835,7 @@ root:nSijPlPhZZwgE:0:0:Root:/: @cindex POSIX @command{awk}, field separators and -@cindex field separators, POSIX and +@cindex field separator, POSIX and According to the POSIX standard, @command{awk} is supposed to behave as if each record is split into fields at the time it is read. In particular, this means that if you change the value of @code{FS} @@ -7170,6 +7195,7 @@ available for splitting regular strings (@pxref{String Functions}). @node Multiple Line @section Multiple-Line Records +@cindex multiple-line records @c STARTOFRANGE recm @cindex records, multiline @c STARTOFRANGE imr @@ -7221,7 +7247,8 @@ after the last record, the final newline is removed from the record. In the second case, this special processing is not done. @value{DARKCORNER} -@cindex field separators, in multiline records +@cindex field separator, in multiline records +@cindex @code{FS}, in multiline records Now that the input is separated into records, the second step is to separate the fields in the record. One way to do this is to divide each of the lines into fields in the normal manner. This happens by default @@ -7369,7 +7396,7 @@ and study the @code{getline} command @emph{after} you have reviewed the rest of this @value{DOCUMENT} and have a good knowledge of how @command{awk} works. @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @command{getline} command @cindex differences in @command{awk} and @command{gawk}, @code{getline} command @cindex @code{getline} command, return values @cindex @option{--sandbox} option, input redirection with @code{getline} @@ -7465,6 +7492,7 @@ rule in the program. @xref{Next Statement}. @node Getline/Variable @subsection Using @code{getline} into a Variable +@cindex @code{getline} into a variable @cindex variables, @code{getline} command into@comma{} using You can use @samp{getline @var{var}} to read the next record from @@ -7516,6 +7544,7 @@ the value of @code{NF} do not change. @node Getline/File @subsection Using @code{getline} from a File +@cindex @code{getline} from a file @cindex input redirection @cindex redirection of input @cindex @code{<} (left angle bracket), @code{<} operator (I/O) @@ -7564,8 +7593,6 @@ from the file @var{file}, and put it in the variable @var{var}. As above, @var{file} is a string-valued expression that specifies the file from which to read. -@cindex @command{gawk}, @code{RT} variable in -@cindex @code{RT} variable In this version of @code{getline}, none of the built-in variables are changed and the record is not split into fields. The only variable changed is @var{var}.@footnote{This is not quite true. @code{RT} could @@ -7590,7 +7617,6 @@ Note here how the name of the extra input file is not built into the program; it is taken directly from the data, specifically from the second field on the @samp{@@include} line. -@cindex @code{close()} function The @code{close()} function is called to ensure that if two identical @samp{@@include} lines appear in the input, the entire specified file is included twice. @@ -7617,7 +7643,7 @@ Failing that, attention to details would be useful.} @cindex @code{|} (vertical bar), @code{|} operator (I/O) @cindex vertical bar (@code{|}), @code{|} operator (I/O) @cindex input pipeline -@cindex pipes, input +@cindex pipe, input @cindex operators, input/output The output of a command can also be piped into @code{getline}, using @samp{@var{command} | getline}. In @@ -7641,7 +7667,6 @@ produced by running the rest of the line as a shell command: @end example @noindent -@cindex @code{close()} function The @code{close()} function is called to ensure that if two identical @samp{@@execute} lines appear in the input, the command is run for each one. @@ -8265,13 +8290,29 @@ program by using a new value of @code{OFS}. @example $ @kbd{awk 'BEGIN @{ OFS = ";"; ORS = "\n\n" @}} -> @kbd{@{ print $1, $2 @}' BBS-list} -@print{} aardvark;555-5553 -@print{} -@print{} alpo-net;555-3412 -@print{} -@print{} barfly;555-7685 -@dots{} +> @kbd{@{ print $1, $2 @}' mail-list} +@print{} Amelia;555-5553 +@print{} +@print{} Anthony;555-3412 +@print{} +@print{} Becky;555-7685 +@print{} +@print{} Bill;555-1675 +@print{} +@print{} Broderick;555-0542 +@print{} +@print{} Camilla;555-2912 +@print{} +@print{} Fabius;555-1234 +@print{} +@print{} Julie;555-6699 +@print{} +@print{} Martin;555-6480 +@print{} +@print{} Samuel;555-3430 +@print{} +@print{} Jean-Paul;555-2127 +@print{} @end example If the value of @code{ORS} does not contain a newline, the program's output @@ -8293,7 +8334,7 @@ numbers can be formatted. The different format specifications are discussed more fully in @ref{Control Letters}. -@cindex @code{sprintf()} function +@cindexawkfunc{sprintf} @cindex @code{OFMT} variable @cindex output, format specifier@comma{} @code{OFMT} The built-in variable @code{OFMT} contains the default format specification @@ -8745,30 +8786,30 @@ The following simple example shows how to use @code{printf} to make an aligned table: @example -awk '@{ printf "%-10s %s\n", $1, $2 @}' BBS-list +awk '@{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example @noindent This command -prints the names of the bulletin boards (@code{$1}) in the file -@file{BBS-list} as a string of 10 characters that are left-justified. It also +prints the names of the people (@code{$1}) in the file +@file{mail-list} as a string of 10 characters that are left-justified. It also prints the phone numbers (@code{$2}) next on the line. This produces an aligned two-column table of names and phone numbers, as shown here: @example -$ @kbd{awk '@{ printf "%-10s %s\n", $1, $2 @}' BBS-list} -@print{} aardvark 555-5553 -@print{} alpo-net 555-3412 -@print{} barfly 555-7685 -@print{} bites 555-1675 -@print{} camelot 555-0542 -@print{} core 555-2912 -@print{} fooey 555-1234 -@print{} foot 555-6699 -@print{} macfoo 555-6480 -@print{} sdace 555-3430 -@print{} sabafoo 555-2127 +$ @kbd{awk '@{ printf "%-10s %s\n", $1, $2 @}' mail-list} +@print{} Amelia 555-5553 +@print{} Anthony 555-3412 +@print{} Becky 555-7685 +@print{} Bill 555-1675 +@print{} Broderick 555-0542 +@print{} Camilla 555-2912 +@print{} Fabius 555-1234 +@print{} Julie 555-6699 +@print{} Martin 555-6480 +@print{} Samuel 555-3430 +@print{} Jean-Paul 555-2127 @end example In this case, the phone numbers had to be printed as strings because @@ -8789,7 +8830,7 @@ the @command{awk} program: @example awk 'BEGIN @{ print "Name Number" print "---- ------" @} - @{ printf "%-10s %s\n", $1, $2 @}' BBS-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example The above example mixes @code{print} and @code{printf} statements in @@ -8799,7 +8840,7 @@ same results: @example awk 'BEGIN @{ printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" @} - @{ printf "%-10s %s\n", $1, $2 @}' BBS-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example @noindent @@ -8814,7 +8855,7 @@ emphasized by storing it in a variable, like this: awk 'BEGIN @{ format = "%-10s %s\n" printf format, "Name", "Number" printf format, "----", "------" @} - @{ printf format, $1, $2 @}' BBS-list + @{ printf format, $1, $2 @}' mail-list @end example @c !!! exercise @@ -8871,20 +8912,20 @@ before the first output is written to it. Subsequent writes to the same @var{output-file} do not erase @var{output-file}, but append to it. (This is different from how you use redirections in shell scripts.) If @var{output-file} does not exist, it is created. For example, here -is how an @command{awk} program can write a list of BBS names to one +is how an @command{awk} program can write a list of peoples' names to one file named @file{name-list}, and a list of phone numbers to another file named @file{phone-list}: @example $ @kbd{awk '@{ print $2 > "phone-list"} -> @kbd{print $1 > "name-list" @}' BBS-list} +> @kbd{print $1 > "name-list" @}' mail-list} $ @kbd{cat phone-list} @print{} 555-5553 @print{} 555-3412 @dots{} $ @kbd{cat name-list} -@print{} aardvark -@print{} alpo-net +@print{} Amelia +@print{} Anthony @dots{} @end example @@ -8902,7 +8943,7 @@ appended to the file. If @var{output-file} does not exist, then it is created. @cindex @code{|} (vertical bar), @code{|} operator (I/O) -@cindex pipes, output +@cindex pipe, output @cindex output, pipes @item print @var{items} | @var{command} It is possible to send output to another program through a pipe @@ -8913,7 +8954,7 @@ to another process created to execute @var{command}. The redirection argument @var{command} is actually an @command{awk} expression. Its value is converted to a string whose contents give the shell command to be run. For example, the following produces two -files, one unsorted list of BBS names, and one list sorted in reverse +files, one unsorted list of peoples' names, and one list sorted in reverse alphabetical order: @ignore @@ -8926,7 +8967,7 @@ alone for now and let's hope no-one notices. @example awk '@{ print $1 > "names.unsorted" command = "sort -r > names.sorted" - print $1 | command @}' BBS-list + print $1 | command @}' mail-list @end example The unsorted list is written with an ordinary redirection, while @@ -9277,7 +9318,7 @@ Doing so results in unpredictable behavior. @c STARTOFRANGE ofc @cindex output, files@comma{} closing @c STARTOFRANGE pc -@cindex pipes, closing +@cindex pipe, closing @c STARTOFRANGE cc @cindex coprocesses, closing @cindex @code{getline} command, coprocesses@comma{} using from @@ -9295,7 +9336,7 @@ the file name or command associated with it, and subsequent writes to the same file or command are appended to the previous writes. The file or pipe stays open until @command{awk} exits. -@cindex @code{close()} function +@cindexawkfunc{close} This implies that special steps are necessary in order to read the same file again from the beginning, or to rerun a shell command (rather than reading more output from the same command). The @code{close()} function @@ -9380,6 +9421,7 @@ a separate message. @cindex differences in @command{awk} and @command{gawk}, @code{close()} function @cindex portability, @code{close()} function and +@cindex @code{close()} function, portability If you use more files than the system allows you to have open, @command{gawk} attempts to multiplex the available open files among your data files. @command{gawk}'s ability to do this depends upon the @@ -9464,7 +9506,7 @@ retval = close(command) # syntax error in many Unix awks @end example @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @command{close()} function @command{gawk} treats @code{close()} as a function. The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is @@ -9520,7 +9562,7 @@ retval = close(command) # syntax error in many Unix awks @end example @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @command{close()} function @command{gawk} treats @code{close()} as a function. The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is @@ -9620,7 +9662,8 @@ have different forms, but are stored identically internally. @node Scalar Constants @subsubsection Numeric and String Constants -@cindex numeric, constants +@cindex constants, numeric +@cindex numeric constants A @dfn{numeric constant} stands for a number. This number can be an integer, a decimal fraction, or a number in scientific (exponential) notation.@footnote{The internal representation of all numbers, @@ -9646,7 +9689,7 @@ double-quotation marks. For example: @noindent @cindex differences in @command{awk} and @command{gawk}, strings -@cindex strings, length of +@cindex strings, length limitations represents the string whose contents are @samp{parrot}. Strings in @command{gawk} can be of any length, and they can contain any of the possible eight-bit ASCII characters including ASCII @sc{nul} (character code zero). @@ -9862,9 +9905,9 @@ upon the contents of the current input record. @cindex differences in @command{awk} and @command{gawk}, regexp constants @cindex dark corner, regexp constants, as arguments to user-defined functions -@cindex @code{gensub()} function (@command{gawk}) -@cindex @code{sub()} function -@cindex @code{gsub()} function +@cindexgawkfunc{gensub} +@cindexawkfunc{sub} +@cindexawkfunc{gsub} Constant regular expressions are also used as the first argument for the @code{gensub()}, @code{sub()}, and @code{gsub()} functions, as the second argument of the @code{match()} function, @@ -9997,7 +10040,7 @@ its position among the input file arguments---after the processing of the preceding input file argument. For example: @example -awk '@{ print $n @}' n=4 inventory-shipped n=2 BBS-list +awk '@{ print $n @}' n=4 inventory-shipped n=2 mail-list @end example @noindent @@ -10006,10 +10049,10 @@ the first file is read, the command line sets the variable @code{n} equal to four. This causes the fourth field to be printed in lines from @file{inventory-shipped}. After the first file has finished, but before the second file is started, @code{n} is set to two, so that the -second field is printed in lines from @file{BBS-list}: +second field is printed in lines from @file{mail-list}: @example -$ @kbd{awk '@{ print $n @}' n=4 inventory-shipped n=2 BBS-list} +$ @kbd{awk '@{ print $n @}' n=4 inventory-shipped n=2 mail-list} @print{} 15 @print{} 24 @dots{} @@ -10332,9 +10375,9 @@ specific operator to represent it. Instead, concatenation is performed by writing expressions next to one another, with no operator. For example: @example -$ @kbd{awk '@{ print "Field number one: " $1 @}' BBS-list} -@print{} Field number one: aardvark -@print{} Field number one: alpo-net +$ @kbd{awk '@{ print "Field number one: " $1 @}' mail-list} +@print{} Field number one: Amelia +@print{} Field number one: Anthony @dots{} @end example @@ -10342,9 +10385,9 @@ Without the space in the string constant after the @samp{:}, the line runs together. For example: @example -$ @kbd{awk '@{ print "Field number one:" $1 @}' BBS-list} -@print{} Field number one:aardvark -@print{} Field number one:alpo-net +$ @kbd{awk '@{ print "Field number one:" $1 @}' mail-list} +@print{} Field number one:Amelia +@print{} Field number one:Anthony @dots{} @end example @@ -11419,10 +11462,10 @@ The Boolean operators are: @item @var{boolean1} && @var{boolean2} True if both @var{boolean1} and @var{boolean2} are true. For example, the following statement prints the current input record if it contains -both @samp{2400} and @samp{foo}: +both @samp{edu} and @samp{li}: @example -if ($0 ~ /2400/ && $0 ~ /foo/) print +if ($0 ~ /edu/ && $0 ~ /li/) print @end example @cindex side effects, Boolean operators @@ -11435,11 +11478,11 @@ no substring @samp{foo} in the record. @item @var{boolean1} || @var{boolean2} True if at least one of @var{boolean1} or @var{boolean2} is true. For example, the following statement prints all records in the input -that contain @emph{either} @samp{2400} or -@samp{foo} or both: +that contain @emph{either} @samp{edu} or +@samp{li} or both: @example -if ($0 ~ /2400/ || $0 ~ /foo/) print +if ($0 ~ /edu/ || $0 ~ /li/) print @end example The subexpression @var{boolean2} is evaluated only if @var{boolean1} @@ -12034,7 +12077,7 @@ slashes (@code{/@var{regexp}/}), or any expression whose string value is used as a dynamic regular expression (@pxref{Computed Regexps}). The following example prints the second field of each input record -whose first field is precisely @samp{foo}: +whose first field is precisely @samp{li}: @cindex @code{/} (forward slash), patterns and @cindex forward slash (@code{/}), patterns and @@ -12043,68 +12086,65 @@ whose first field is precisely @samp{foo}: @cindex @code{!} (exclamation point), @code{!~} operator @cindex exclamation point (@code{!}), @code{!~} operator @example -$ @kbd{awk '$1 == "foo" @{ print $2 @}' BBS-list} +$ @kbd{awk '$1 == "li" @{ print $2 @}' mail-list} @end example @noindent -(There is no output, because there is no BBS site with the exact name @samp{foo}.) +(There is no output, because there is no person with the exact name @samp{li}.) Contrast this with the following regular expression match, which -accepts any record with a first field that contains @samp{foo}: +accepts any record with a first field that contains @samp{li}: @example -$ @kbd{awk '$1 ~ /foo/ @{ print $2 @}' BBS-list} -@print{} 555-1234 +$ @kbd{awk '$1 ~ /foo/ @{ print $2 @}' mail-list} +@print{} 555-5553 @print{} 555-6699 -@print{} 555-6480 -@print{} 555-2127 @end example @cindex regexp constants, as patterns @cindex patterns, regexp constants as A regexp constant as a pattern is also a special case of an expression -pattern. The expression @code{/foo/} has the value one if @samp{foo} -appears in the current input record. Thus, as a pattern, @code{/foo/} -matches any record containing @samp{foo}. +pattern. The expression @code{/li/} has the value one if @samp{li} +appears in the current input record. Thus, as a pattern, @code{/li/} +matches any record containing @samp{li}. @cindex Boolean expressions, as patterns Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions match. For example, the following command prints all the records in -@file{BBS-list} that contain both @samp{2400} and @samp{foo}: +@file{mail-list} that contain both @samp{edu} and @samp{li}: @example -$ @kbd{awk '/2400/ && /foo/' BBS-list} -@print{} fooey 555-1234 2400/1200/300 B +$ @kbd{awk '/edu/ && /li/' mail-list} +@print{} Samuel 555-3430 samuel.lanceolis@@shu.edu A @end example The following command prints all records in -@file{BBS-list} that contain @emph{either} @samp{2400} or @samp{foo} +@file{mail-list} that contain @emph{either} @samp{edu} or @samp{li} (or both, of course): @example -$ @kbd{awk '/2400/ || /foo/' BBS-list} -@print{} alpo-net 555-3412 2400/1200/300 A -@print{} bites 555-1675 2400/1200/300 A -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sdace 555-3430 2400/1200/300 A -@print{} sabafoo 555-2127 1200/300 C +$ @kbd{awk '/edu/ || /li/' mail-list} +@print{} Amelia 555-5553 amelia.zodiacusque@@gmail.com F +@print{} Broderick 555-0542 broderick.aliquotiens@@yahoo.com R +@print{} Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +@print{} Julie 555-6699 julie.perscrutabor@@skeeve.com F +@print{} Samuel 555-3430 samuel.lanceolis@@shu.edu A +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example The following command prints all records in -@file{BBS-list} that do @emph{not} contain the string @samp{foo}: +@file{mail-list} that do @emph{not} contain the string @samp{li}: @example -$ @kbd{awk '! /foo/' BBS-list} -@print{} aardvark 555-5553 1200/300 B -@print{} alpo-net 555-3412 2400/1200/300 A -@print{} barfly 555-7685 1200/300 A -@print{} bites 555-1675 2400/1200/300 A -@print{} camelot 555-0542 300 C -@print{} core 555-2912 1200/300 C -@print{} sdace 555-3430 2400/1200/300 A +$ @kbd{awk '! /li/' mail-list} +@print{} Anthony 555-3412 anthony.asserturo@@hotmail.com A +@print{} Becky 555-7685 becky.algebrarum@@gmail.com A +@print{} Bill 555-1675 bill.drowning@@hotmail.com A +@print{} Camilla 555-2912 camilla.infusarum@@skynet.be R +@print{} Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +@print{} Martin 555-6480 martin.codicibus@@hotmail.com A +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example @cindex @code{BEGIN} pattern, Boolean patterns and @@ -12237,28 +12277,30 @@ programmers. @node Using BEGIN/END @subsubsection Startup and Cleanup Actions +@cindex @code{BEGIN} pattern +@cindex @code{END} pattern A @code{BEGIN} rule is executed once only, before the first input record is read. Likewise, an @code{END} rule is executed once only, after all the input is read. For example: @example $ @kbd{awk '} -> @kbd{BEGIN @{ print "Analysis of \"foo\"" @}} -> @kbd{/foo/ @{ ++n @}} -> @kbd{END @{ print "\"foo\" appears", n, "times." @}' BBS-list} -@print{} Analysis of "foo" -@print{} "foo" appears 4 times. +> @kbd{BEGIN @{ print "Analysis of \"li\"" @}} +> @kbd{/li/ @{ ++n @}} +> @kbd{END @{ print "\"li\" appears in", n, "records." @}' mail-list} +@print{} Analysis of "li" +@print{} "li" appears in 4 records. @end example @cindex @code{BEGIN} pattern, operators and @cindex @code{END} pattern, operators and -This program finds the number of records in the input file @file{BBS-list} -that contain the string @samp{foo}. The @code{BEGIN} rule prints a title +This program finds the number of records in the input file @file{mail-list} +that contain the string @samp{li}. The @code{BEGIN} rule prints a title for the report. There is no need to use the @code{BEGIN} rule to initialize the counter @code{n} to zero, since @command{awk} does this automatically (@pxref{Variables}). The second rule increments the variable @code{n} every time a -record containing the pattern @samp{foo} is read. The @code{END} rule +record containing the pattern @samp{li} is read. The @code{END} rule prints the value of @code{n} at the end of the run. The special patterns @code{BEGIN} and @code{END} cannot be used in ranges @@ -12380,7 +12422,7 @@ you can bypass the fatal error and move on to the next file on the command line. @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @code{BEGINFILE} pattern @cindex @code{nextfile} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and You do this by checking if the @code{ERRNO} variable is not the empty string; if so, then @command{gawk} was not able to open the file. In @@ -12422,7 +12464,7 @@ both @code{BEGINFILE} and @code{ENDFILE}. Only the @samp{getline In most other @command{awk} implementations, or if @command{gawk} is in compatibility mode (@pxref{Options}), they are not special. -@c FIXME: For 4.1 maybe deal with this? +@c FIXME: For 4.2 maybe deal with this? @ignore Date: Tue, 17 May 2011 02:06:10 PDT From: rankin@pactechdata.com (Pat Rankin) @@ -12453,7 +12495,7 @@ An empty (i.e., nonexistent) pattern is considered to match @emph{every} input record. For example, the program: @example -awk '@{ print $1 @}' BBS-list +awk '@{ print $1 @}' mail-list @end example @noindent @@ -13489,8 +13531,8 @@ is to simply say @samp{FS = FS}, perhaps with an explanatory comment. @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable @cindex differences in @command{awk} and @command{gawk}, @code{IGNORECASE} variable -@cindex case sensitivity, string comparisons and -@cindex case sensitivity, regexps and +@cindex case sensitivity, and string comparisons +@cindex case sensitivity, and regexps @cindex regular expressions, case sensitivity @item IGNORECASE # If @code{IGNORECASE} is nonzero or non-null, then all string comparisons @@ -13655,16 +13697,16 @@ In the following example: $ @kbd{awk 'BEGIN @{} > @kbd{for (i = 0; i < ARGC; i++)} > @kbd{print ARGV[i]} -> @kbd{@}' inventory-shipped BBS-list} +> @kbd{@}' inventory-shipped mail-list} @print{} awk @print{} inventory-shipped -@print{} BBS-list +@print{} mail-list @end example @noindent @code{ARGV[0]} contains @samp{awk}, @code{ARGV[1]} contains @samp{inventory-shipped}, and @code{ARGV[2]} contains -@samp{BBS-list}. The value of @code{ARGC} is three, one more than the +@samp{mail-list}. The value of @code{ARGC} is three, one more than the index of the last element in @code{ARGV}, because the elements are numbered from zero. @@ -13707,7 +13749,7 @@ or if @command{gawk} is in compatibility mode it is not special. @cindex @code{ENVIRON} array -@cindex environment variables +@cindex environment variables, in @code{ENVIRON} array @item ENVIRON An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of @@ -13830,10 +13872,12 @@ The following elements (listed alphabetically) are guaranteed to be available: @table @code +@cindex effective group id of @command{gawk} user @item PROCINFO["egid"] The value of the @code{getegid()} system call. @item PROCINFO["euid"] +@cindex effective user id of @command{gawk} user The value of the @code{geteuid()} system call. @item PROCINFO["FS"] @@ -13843,6 +13887,7 @@ This is or @code{"FPAT"} if field matching with @code{FPAT} is in effect. @item PROCINFO["identifiers"] +@cindex program identifiers A subarray, indexed by the names of all identifiers used in the text of the AWK program. For each identifier, the value of the element is one of the following: @@ -13871,15 +13916,19 @@ after it has finished parsing the program; they are @emph{not} updated while the program runs. @item PROCINFO["gid"] +@cindex group id of @command{gawk} user The value of the @code{getgid()} system call. @item PROCINFO["pgrpid"] +@cindex process group id of @command{gawk} process The process group ID of the current process. @item PROCINFO["pid"] +@cindex process id of @command{gawk} process The process ID of the current process. @item PROCINFO["ppid"] +@cindex parent process id of @command{gawk} process The parent process ID of the current process. @item PROCINFO["sorted_in"] @@ -13899,25 +13948,31 @@ Assigning a new value to this element changes the default. The value of the @code{getuid()} system call. @item PROCINFO["version"] +@cindex version of @command{gawk} +@cindex @command{gawk} version The version of @command{gawk}. @end table The following additional elements in the array are available to provide information about the MPFR and GMP libraries if your version of @command{gawk} supports arbitrary precision numbers -(@pxref{Arbitrary Precision Arithmetic}): +(@pxref{Gawk and MPFR}): @table @code +@cindex version of GNU MPFR library @item PROCINFO["mpfr_version"] The version of the GNU MPFR library. @item PROCINFO["gmp_version"] +@cindex version of GNU MP library The version of the GNU MP library. @item PROCINFO["prec_max"] +@cindex maximum precision supported by MPFR library The maximum precision supported by MPFR. @item PROCINFO["prec_min"] +@cindex minimum precision supported by MPFR library The minimum precision required by MPFR. @end table @@ -13928,12 +13983,15 @@ of @command{gawk} supports dynamic loading of extension functions @table @code @item PROCINFO["api_major"] +@cindex version of @command{gawk} extension API +@cindex extension API, version number The major version of the extension API. @item PROCINFO["api_minor"] The minor version of the extension API. @end table +@cindex supplementary groups of @command{gawk} process On some systems, there may be elements in the array, @code{"group1"} through @code{"group@var{N}"} for some @var{N}. @var{N} is the number of supplementary groups that the process has. Use the @code{in} operator @@ -13941,7 +13999,7 @@ to test for these elements (@pxref{Reference to Elements}). @cindex @command{gawk}, @code{PROCINFO} array in -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, uses The @code{PROCINFO} array has the following additional uses: @itemize @bullet @@ -14127,7 +14185,7 @@ changed. @node ARGC and ARGV @subsection Using @code{ARGC} and @code{ARGV} -@cindex @code{ARGC}/@code{ARGV} variables +@cindex @code{ARGC}/@code{ARGV} variables, how to use @cindex arguments, command-line @cindex command line, arguments @@ -14139,16 +14197,16 @@ and @code{ARGV}: $ @kbd{awk 'BEGIN @{} > @kbd{for (i = 0; i < ARGC; i++)} > @kbd{print ARGV[i]} -> @kbd{@}' inventory-shipped BBS-list} +> @kbd{@}' inventory-shipped mail-list} @print{} awk @print{} inventory-shipped -@print{} BBS-list +@print{} mail-list @end example @noindent In this example, @code{ARGV[0]} contains @samp{awk}, @code{ARGV[1]} contains @samp{inventory-shipped}, and @code{ARGV[2]} contains -@samp{BBS-list}. +@samp{mail-list}. Notice that the @command{awk} program is not entered in @code{ARGV}. The other command-line options, with their arguments, are also not entered. This includes variable assignments done with the @option{-v} @@ -14272,7 +14330,7 @@ ability to support true multidimensional arrays. @cindex variables, names of @cindex functions, names of -@cindex arrays, names of +@cindex arrays, names of, and names of functions/variables @cindex names, arrays/variables @cindex namespace issues @command{awk} maintains a single set @@ -14448,10 +14506,9 @@ Here, the number @code{1} isn't double-quoted, since @command{awk} automatically converts it to a string. @cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex @code{IGNORECASE} variable @cindex case sensitivity, array indices and -@cindex arrays, @code{IGNORECASE} variable and -@cindex @code{IGNORECASE} variable, array subscripts and +@cindex arrays, and @code{IGNORECASE} variable +@cindex @code{IGNORECASE} variable, and array indices The value of @code{IGNORECASE} has no effect upon array subscripting. The identical string value used to store an array element must be used to retrieve it. @@ -14467,8 +14524,9 @@ is independent of the number of elements in the array. @node Reference to Elements @subsection Referring to an Array Element -@cindex arrays, elements, referencing -@cindex elements in arrays +@cindex arrays, referencing elements +@cindex array members +@cindex elements of arrays The principal way to use an array is to refer to one of its elements. An array reference is an expression as follows: @@ -14485,11 +14543,16 @@ The value of the array reference is the current value of that array element. For example, @code{foo[4.3]} is an expression for the element of array @code{foo} at index @samp{4.3}. +@cindex arrays, unassigned elements +@cindex unassigned array elements +@cindex empty array elements A reference to an array element that has no recorded value yields a value of @code{""}, the null string. This includes elements that have not been assigned any value as well as elements that have been deleted (@pxref{Delete}). +@cindex non-existent array elements +@cindex arrays, elements that don't exist @quotation NOTE A reference to an element that does not exist @emph{automatically} creates that array element, with the null string as its value. (In some cases, @@ -14509,7 +14572,7 @@ if it didn't exist before! @end quotation @c @cindex arrays, @code{in} operator and -@cindex @code{in} operator +@cindex @code{in} operator, testing if array element exists To determine whether an element exists in an array at a certain index, use the following expression: @@ -14544,8 +14607,8 @@ if (frequencies[2] != "") @node Assigning Elements @subsection Assigning Array Elements -@cindex arrays, elements, assigning -@cindex elements in arrays, assigning +@cindex arrays, elements, assigning values +@cindex elements in arrays, assigning values Array elements can be assigned values just like @command{awk} variables: @@ -14562,6 +14625,7 @@ assign to that element of the array. @node Array Example @subsection Basic Array Example +@cindex arrays, an example of using The following program takes a list of lines, each beginning with a line number, and prints them out in order of line number. The line numbers @@ -14631,6 +14695,7 @@ END @{ @node Scanning an Array @subsection Scanning All Elements of an Array @cindex elements in arrays, scanning +@cindex scanning arrays @cindex arrays, scanning @cindex loops, @code{for}, array scanning @@ -14649,7 +14714,7 @@ for (@var{var} in @var{array}) @end example @noindent -@cindex @code{in} operator +@cindex @code{in} operator, use in loops This loop executes @var{body} once for each index in @var{array} that the program has previously used, with the variable @var{var} set to that index. @@ -14688,8 +14753,9 @@ END @{ @xref{Word Sorting}, for a more detailed example of this type. -@cindex arrays, elements, order of -@cindex elements in arrays, order of +@cindex arrays, elements, order of access by @code{in} operator +@cindex elements in arrays, order of access by @code{in} operator +@cindex @code{in} operator, order of array access The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array elements within @command{awk} and normally cannot be controlled or changed. This can lead to @@ -14707,6 +14773,8 @@ determines the order in which the array is traversed. This order is usually based on the internal implementation of arrays and will vary from one version of @command{awk} to the next. +@cindex array scanning order, controlling +@cindex controlling array scanning order Often, though, you may wish to do something simple, such as ``traverse the array by comparing the indices in ascending order,'' or ``traverse the array by comparing the values in descending order.'' @@ -14723,6 +14791,7 @@ to use for comparison of array elements. This advanced feature is described later, in @ref{Array Sorting}. @end itemize +@cindex @code{PROCINFO}, values of @code{sorted_in} The following special values for @code{PROCINFO["sorted_in"]} are available: @table @code @@ -14883,7 +14952,7 @@ if (4 in foo) print "This will never be printed" @end example -@cindex null strings, array elements and +@cindex null strings, and deleting array elements It is important to note that deleting an element is @emph{not} the same as assigning it a null value (the empty string, @code{""}). For example: @@ -14905,6 +14974,7 @@ is not in the array is deleted. @cindex extensions, common@comma{} @code{delete} to delete entire arrays @cindex arrays, deleting entire contents @cindex deleting entire arrays +@cindex @code{delete} @var{array} @cindex differences in @command{awk} and @command{gawk}, array elements, deleting All the elements of an array may be deleted with a single statement by leaving off the subscript in the @code{delete} statement, @@ -14962,9 +15032,9 @@ a = 3 @section Using Numbers to Subscript Arrays @cindex numbers, as array subscripts -@cindex arrays, subscripts +@cindex arrays, numeric subscripts @cindex subscripts in arrays, numbers as -@cindex @code{CONVFMT} variable, array subscripts and +@cindex @code{CONVFMT} variable, and array subscripts An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting @@ -14994,7 +15064,8 @@ string value from @code{xyz}---this time @code{"12.15"}---because the value of @code{CONVFMT} only allows two significant digits. This test fails, since @code{"12.15"} is different from @code{"12.153"}. -@cindex converting, during subscripting +@cindex converting integer array subscripts +@cindex integer array indices According to the rules for conversions (@pxref{Conversion}), integer values are always converted to strings as integers, no matter what the @@ -15100,7 +15171,7 @@ languages, including @command{awk}) to refer to an element of a two-dimensional array named @code{grid} is with @code{grid[@var{x},@var{y}]}. -@cindex @code{SUBSEP} variable, multidimensional arrays +@cindex @code{SUBSEP} variable, and multidimensional arrays Multidimensional arrays are supported in @command{awk} through concatenation of indices into one string. @command{awk} converts the indices into strings @@ -15132,6 +15203,7 @@ combined strings that are ambiguous. Suppose that @code{SUBSEP} is "b@@c"]}} are indistinguishable because both are actually stored as @samp{foo["a@@b@@c"]}. +@cindex @code{in} operator, index existence in multidimensional arrays To test whether a particular index sequence exists in a multidimensional array, use the same operator (@code{in}) that is used for single dimensional arrays. Write the whole sequence of indices @@ -15197,6 +15269,7 @@ multidimensional @emph{way of accessing} an array. @cindex subscripts in arrays, multidimensional, scanning @cindex arrays, multidimensional, scanning +@cindex scanning multidimensional arrays 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 @code{for} statement @@ -15238,6 +15311,7 @@ separate indices is recovered. @node Arrays of Arrays @section Arrays of Arrays +@cindex arrays of arrays @command{gawk} goes beyond standard @command{awk}'s multidimensional array access and provides true arrays of @@ -15497,6 +15571,7 @@ two arguments 11 and 10. @node Numeric Functions @subsection Numeric Functions +@cindex numeric functions The following list describes all of the built-in functions that work with numbers. @@ -15505,21 +15580,25 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):} @table @code @item atan2(@var{y}, @var{x}) @cindex @code{atan2()} function +@cindex arctangent Return the arctangent of @code{@var{y} / @var{x}} in radians. You can use @samp{pi = atan2(0, -1)} to retrieve the value of @value{PI}. @item cos(@var{x}) -@cindex @code{cos()} function +@cindexawkfunc{cos} +@cindex cosine Return the cosine of @var{x}, with @var{x} in radians. @item exp(@var{x}) -@cindex @code{exp()} function +@cindexawkfunc{exp} +@cindex exponent Return the exponential of @var{x} (@code{e ^ @var{x}}) or report an error if @var{x} is out of range. The range of values @var{x} can have depends on your machine's floating-point representation. @item int(@var{x}) -@cindex @code{int()} function +@cindexawkfunc{int} +@cindex round to nearest integer Return the nearest integer to @var{x}, located between @var{x} and zero and truncated toward zero. @@ -15527,12 +15606,13 @@ For example, @code{int(3)} is 3, @code{int(3.9)} is 3, @code{int(-3.9)} is @minus{}3, and @code{int(-3)} is @minus{}3 as well. @item log(@var{x}) -@cindex @code{log()} function +@cindexawkfunc{log} +@cindex logarithm Return the natural logarithm of @var{x}, if @var{x} is positive; otherwise, report an error. @item rand() -@cindex @code{rand()} function +@cindexawkfunc{rand} @cindex random numbers, @code{rand()}/@code{srand()} functions Return a random number. The values of @code{rand()} are uniformly distributed between zero and one. @@ -15574,7 +15654,7 @@ function roll(n) @{ return 1 + int(rand() * n) @} @} @end example -@cindex numbers, random +@cindex seeding random number generator @cindex random numbers, seed of @quotation CAUTION In most @command{awk} implementations, including @command{gawk}, @@ -15590,17 +15670,19 @@ use @code{srand()}. @end quotation @item sin(@var{x}) -@cindex @code{sin()} function +@cindexawkfunc{sin} +@cindex sine Return the sine of @var{x}, with @var{x} in radians. @item sqrt(@var{x}) -@cindex @code{sqrt()} function +@cindexawkfunc{sqrt} +@cindex square root Return the positive square root of @var{x}. @command{gawk} prints a warning message if @var{x} is negative. Thus, @code{sqrt(4)} is 2. @item srand(@r{[}@var{x}@r{]}) -@cindex @code{srand()} function +@cindexawkfunc{srand} Set the starting point, or seed, for generating random numbers to the value @var{x}. @@ -15630,6 +15712,7 @@ sequences of random numbers. @node String Functions @subsection String-Manipulation Functions +@cindex string-manipulation functions The functions in this @value{SECTION} look at or change the text of one or more strings. @@ -15658,11 +15741,11 @@ pound sign@w{ (@samp{#}):} @table @code @item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # @itemx asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # -@cindex @code{asorti()} function (@command{gawk}) +@cindexgawkfunc{asorti} +@cindex sort array @cindex arrays, elements, retrieving number of -@cindex @code{asort()} function (@command{gawk}) -@cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex @code{IGNORECASE} variable +@cindexgawkfunc{asort} +@cindex sort array indices These two functions are similar in behavior, so they are described together. @@ -15680,7 +15763,9 @@ sequential integers starting with one. If the optional array @var{dest} is specified, then @var{source} is duplicated into @var{dest}. @var{dest} is then sorted, leaving the indices of @var{source} unchanged. -When comparing strings, @code{IGNORECASE} affects the sorting. If the +@cindex @command{gawk}, @code{IGNORECASE} variable in +When comparing strings, @code{IGNORECASE} affects the sorting +(@pxref{Array Sorting Functions}). If the @var{source} array contains subarrays as values (@pxref{Arrays of Arrays}), they will come last, after all scalar values. @@ -15723,7 +15808,9 @@ a[3] = "middle" are not available in compatibility mode (@pxref{Options}). @item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) # -@cindex @code{gensub()} function (@command{gawk}) +@cindexgawkfunc{gensub} +@cindex search and replace in strings +@cindex substitute in string Search the target string @var{target} for matches of the regular expression @var{regexp}. If @var{how} is a string beginning with @samp{g} or @samp{G} (short for ``global''), then replace all matches of @var{regexp} with @@ -15732,7 +15819,7 @@ which match of @var{regexp} to replace. If no @var{target} is supplied, use @code{$0}. It returns the modified string as the result of the function and the original target string is @emph{not} changed. -@code{gensub()} is a general substitution function. It's purpose is +@code{gensub()} is a general substitution function. Its purpose is to provide more features than the standard @code{sub()} and @code{gsub()} functions. @@ -15786,7 +15873,7 @@ is the original unchanged value of @var{target}. in compatibility mode (@pxref{Options}). @item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) -@cindex @code{gsub()} function +@cindexawkfunc{gsub} Search @var{target} for @emph{all} of the longest, leftmost, @emph{nonoverlapping} matching substrings it can find and replace them with @var{replacement}. @@ -15808,8 +15895,9 @@ As in @code{sub()}, the characters @samp{&} and @samp{\} are special, and the third argument must be assignable. @item index(@var{in}, @var{find}) -@cindex @code{index()} function -@cindex searching +@cindexawkfunc{index} +@cindex search in string +@cindex find substring in string Search the string @var{in} for the first occurrence of the string @var{find}, and return the position in characters where that occurrence begins in the string @var{in}. Consider the following example: @@ -15826,7 +15914,9 @@ If @var{find} is not found, @code{index()} returns zero. It is a fatal error to use a regexp constant for @var{find}. @item length(@r{[}@var{string}@r{]}) -@cindex @code{length()} function +@cindexawkfunc{length} +@cindex string length +@cindex length of string Return the number of characters in @var{string}. If @var{string} is a number, the length of the digit string representing that number is returned. For example, @code{length("abcde")} is five. By @@ -15834,6 +15924,8 @@ contrast, @code{length(15 * 35)} works out to three. In this example, 15 * 35 = 525, and 525 is then converted to the string @code{"525"}, which has three characters. +@cindex length of input record +@cindex input record, length of If no argument is supplied, @code{length()} returns the length of @code{$0}. @c @cindex historical features @@ -15872,6 +15964,8 @@ warning about this. @cindex common extensions, @code{length()} applied to an array @cindex extensions, common@comma{} @code{length()} applied to an array @cindex differences between @command{gawk} and @command{awk} +@cindex number of array elements +@cindex array, number of elements With @command{gawk} and several other @command{awk} implementations, when given an array argument, the @code{length()} function returns the number of elements in the array. @value{COMMONEXT} @@ -15885,7 +15979,9 @@ If @option{--posix} is supplied, using an array argument is a fatal error (@pxref{Arrays}). @item match(@var{string}, @var{regexp} @r{[}, @var{array}@r{]}) -@cindex @code{match()} function +@cindexawkfunc{match} +@cindex string, regular expression match +@cindex match regexp in string Search @var{string} for the longest, leftmost substring matched by the regular expression, @var{regexp} and return the character position, or @dfn{index}, @@ -16000,7 +16096,8 @@ The @var{array} argument to @code{match()} is a using a third argument is a fatal error. @item patsplit(@var{string}, @var{array} @r{[}, @var{fieldpat} @r{[}, @var{seps} @r{]} @r{]}) # -@cindex @code{patsplit()} function (@command{gawk}) +@cindexgawkfunc{patsplit} +@cindex split string into array Divide @var{string} into pieces defined by @var{fieldpat} and store the pieces in @var{array} and the separator strings in the @@ -16031,7 +16128,7 @@ The @code{patsplit()} function is a it is not available. @item split(@var{string}, @var{array} @r{[}, @var{fieldsep} @r{[}, @var{seps} @r{]} @r{]}) -@cindex @code{split()} function +@cindexawkfunc{split} Divide @var{string} into pieces separated by @var{fieldsep} and store the pieces in @var{array} and the separator strings in the @var{seps} array. The first piece is stored in @@ -16060,7 +16157,7 @@ split("cul-de-sac", a, "-", seps) @end example @noindent -@cindex strings, splitting +@cindex strings splitting, example splits the string @samp{cul-de-sac} into three fields using @samp{-} as the separator. It sets the contents of the array @code{a} as follows: @@ -16116,7 +16213,8 @@ If @var{string} does not match @var{fieldsep} at all (but is not null), @var{string}. @item sprintf(@var{format}, @var{expression1}, @dots{}) -@cindex @code{sprintf()} function +@cindexawkfunc{sprintf} +@cindex formatting strings Return (without printing) the string that @code{printf} would have printed out with the same arguments (@pxref{Printf}). @@ -16129,7 +16227,8 @@ pival = sprintf("pi = %.2f (approx.)", 22/7) @noindent assigns the string @w{@samp{pi = 3.14 (approx.)}} to the variable @code{pival}. -@cindex @code{strtonum()} function (@command{gawk}) +@cindexgawkfunc{strtonum} +@cindex convert string to number @item strtonum(@var{str}) # Examine @var{str} and return its numeric value. If @var{str} begins with a leading @samp{0}, @code{strtonum()} assumes that @var{str} @@ -16156,7 +16255,8 @@ for recognizing numbers (@pxref{Locales}). in compatibility mode (@pxref{Options}). @item sub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) -@cindex @code{sub()} function +@cindexawkfunc{sub} +@cindex replace in string Search @var{target}, which is treated as a string, for the leftmost, longest substring matched by the regular expression @var{regexp}. Modify the entire string @@ -16256,7 +16356,8 @@ Finally, if the @var{regexp} is not a regexp constant, it is converted into a string, and then the value of that string is treated as the regexp to match. @item substr(@var{string}, @var{start} @r{[}, @var{length}@r{]}) -@cindex @code{substr()} function +@cindexawkfunc{substr} +@cindex substring Return a @var{length}-character-long substring of @var{string}, starting at character number @var{start}. The first character of a string is character number one.@footnote{This is different from @@ -16313,16 +16414,18 @@ string = substr(string, 1, 2) "CDE" substr(string, 6) @end example @cindex case sensitivity, converting case -@cindex converting, case +@cindex strings, converting letter case @item tolower(@var{string}) -@cindex @code{tolower()} function +@cindexawkfunc{tolower} +@cindex convert string to lower case Return a copy of @var{string}, with each uppercase character in the string replaced with its corresponding lowercase character. Nonalphabetic characters are left unchanged. For example, @code{tolower("MiXeD cAsE 123")} returns @code{"mixed case 123"}. @item toupper(@var{string}) -@cindex @code{toupper()} function +@cindexawkfunc{toupper} +@cindex convert string to upper case Return a copy of @var{string}, with each lowercase character in the string replaced with its corresponding uppercase character. Nonalphabetic characters are left unchanged. For example, @@ -16748,14 +16851,16 @@ Although this makes a certain amount of sense, it can be surprising. @node I/O Functions @subsection Input/Output Functions +@cindex input/output functions The following functions relate to input/output (I/O). Optional parameters are enclosed in square brackets ([ ]): @table @code @item close(@var{filename} @r{[}, @var{how}@r{]}) -@cindex @code{close()} function +@cindexawkfunc{close} @cindex files, closing +@cindex close file or coprocess Close the file @var{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. @@ -16772,7 +16877,8 @@ not matter. which discusses this feature in more detail and gives an example. @item fflush(@r{[}@var{filename}@r{]}) -@cindex @code{fflush()} function +@cindexawkfunc{fflush} +@cindex flush buffered output Flush any buffered output associated with @var{filename}, which is either a file opened for writing or a shell command for redirecting output to a pipe or coprocess. @@ -16831,7 +16937,8 @@ or if @var{filename} is not an open file, pipe, or coprocess. In such a case, @code{fflush()} returns @minus{}1, as well. @item system(@var{command}) -@cindex @code{system()} function +@cindexawkfunc{system} +@cindex invoke shell command @cindex interacting with other programs Execute the operating-system command @var{command} and then return to the @command{awk} program. @@ -17106,6 +17213,7 @@ you would see the latter (undesirable) output. @node Time Functions @subsection Time Functions +@cindex time functions @c STARTOFRANGE tst @cindex timestamps @@ -17144,7 +17252,8 @@ Optional parameters are enclosed in square brackets ([ ]): @table @code @item mktime(@var{datespec}) -@cindex @code{mktime()} function (@command{gawk}) +@cindexgawkfunc{mktime} +@cindex generate time values Turn @var{datespec} into a timestamp in the same form as is returned by @code{systime()}. It is similar to the function of the same name in ISO C. The argument, @var{datespec}, is a string of the form @@ -17174,7 +17283,8 @@ is out of range, @code{mktime()} returns @minus{}1. @cindex @code{PROCINFO} array @item strftime(@r{[}@var{format} @r{[}, @var{timestamp} @r{[}, @var{utc-flag}@r{]]]}) @c STARTOFRANGE strf -@cindex @code{strftime()} function (@command{gawk}) +@cindexgawkfunc{strftime} +@cindex format time string Format the time specified by @var{timestamp} based on the contents of the @var{format} string and return the result. It is similar to the function of the same name in ISO C. @@ -17191,11 +17301,12 @@ The default string value is @code{@w{"%a %b %e %H:%M:%S %Z %Y"}}. This format string produces output that is equivalent to that of the @command{date} utility. You can assign a new value to @code{PROCINFO["strftime"]} to -change the default format. +change the default format; see below for the various format directives. @item systime() -@cindex @code{systime()} function (@command{gawk}) +@cindexgawkfunc{systime} @cindex timestamps +@cindex current system time Return the current time as the number of seconds since the system epoch. On POSIX systems, this is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds. @@ -17489,6 +17600,7 @@ gawk 'BEGIN @{ @node Bitwise Functions @subsection Bit-Manipulation Functions +@cindex bit-manipulation functions @c STARTOFRANGE bit @cindex bitwise, operations @c STARTOFRANGE and @@ -17651,27 +17763,33 @@ bitwise operations just described. They are: @cindex @command{gawk}, bitwise operations in @table @code -@cindex @code{and()} function (@command{gawk}) +@cindexgawkfunc{and} +@cindex bitwise AND @item and(@var{v1}, @var{v2} @r{[}, @r{@dots{}]}) Return the bitwise AND of the arguments. There must be at least two. -@cindex @code{compl()} function (@command{gawk}) +@cindexgawkfunc{compl} +@cindex bitwise complement @item compl(@var{val}) Return the bitwise complement of @var{val}. -@cindex @code{lshift()} function (@command{gawk}) +@cindexgawkfunc{lshift} +@cindex left shift @item lshift(@var{val}, @var{count}) Return the value of @var{val}, shifted left by @var{count} bits. -@cindex @code{or()} function (@command{gawk}) +@cindexgawkfunc{or} +@cindex bitwise OR @item or(@var{v1}, @var{v2} @r{[}, @r{@dots{}]}) Return the bitwise OR of the arguments. There must be at least two. -@cindex @code{rshift()} function (@command{gawk}) +@cindexgawkfunc{rshift} +@cindex right shift @item rshift(@var{val}, @var{count}) Return the value of @var{val}, shifted right by @var{count} bits. -@cindex @code{xor()} function (@command{gawk}) +@cindexgawkfunc{xor} +@cindex bitwise XOR @item xor(@var{v1}, @var{v2} @r{[}, @r{@dots{}]}) Return the bitwise XOR of the arguments. There must be at least two. @end table @@ -17763,6 +17881,7 @@ $ @kbd{gawk -f testbits.awk} @cindex strings, converting @cindex numbers, converting @cindex converting, numbers to strings +@cindex number as string of bits The @code{bits2str()} function turns a binary number into a string. The number @code{1} represents a binary value where the rightmost bit is set to 1. Using this mask, @@ -17798,7 +17917,8 @@ that traverses every element of a true multidimensional array (@pxref{Arrays of Arrays}). @table @code -@cindex @code{isarray()} function (@command{gawk}) +@cindexgawkfunc{isarray} +@cindex scalar or array @item isarray(@var{x}) Return a true value if @var{x} is an array. Otherwise return false. @end table @@ -17820,6 +17940,7 @@ will end up turning it into a scalar. @subsection String-Translation Functions @cindex @command{gawk}, string-translation functions @cindex functions, string-translation +@cindex string-translation functions @cindex internationalization @cindex @command{awk} programs, internationalizing @@ -17831,7 +17952,8 @@ for the full story. Optional parameters are enclosed in square brackets ([ ]): @table @code -@cindex @code{bindtextdomain()} function (@command{gawk}) +@cindexgawkfunc{bindtextdomain} +@cindex set directory of message catalogs @item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]}) Set the directory in which @command{gawk} will look for message translation files, in case they @@ -17844,14 +17966,15 @@ If @var{directory} is the null string (@code{""}), then @code{bindtextdomain()} returns the current binding for the given @var{domain}. -@cindex @code{dcgettext()} function (@command{gawk}) +@cindexgawkfunc{dcgettext} +@cindex translate string @item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. -@cindex @code{dcngettext()} function (@command{gawk}) +@cindexgawkfunc{dcngettext} @item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @@ -17868,7 +17991,7 @@ The default value for @var{category} is @code{"LC_MESSAGES"}. @section User-Defined Functions @c STARTOFRANGE udfunc -@cindex user-defined, functions +@cindex user-defined functions @c STARTOFRANGE funcud @cindex functions, user-defined Complicated @command{awk} programs can often be simplified by defining @@ -17954,6 +18077,7 @@ conventional to place some extra space between the arguments and the local variables, in order to document how your function is supposed to be used. @cindex variables, shadowing +@cindex shadowing of variable values During execution of the function body, the arguments and local variable values hide, or @dfn{shadow}, any variables of the same names used in the rest of the program. The shadowed variables are not accessible in the @@ -18012,6 +18136,7 @@ keyword @code{function} when defining a function. @node Function Example @subsection Function Definition Examples +@cindex function definition example Here is an example of a user-defined function, called @code{myprint()}, that takes a number and prints it in a specific format: @@ -18160,8 +18285,8 @@ an error. @node Variable Scope @subsubsection Controlling Variable Scope -@cindex local variables -@cindex variables, local +@cindex local variables, in a function +@cindex variables, local to a function There is no way to make a variable local to a @code{@{ @dots{} @}} block in @command{awk}, but you can make a variable local to a function. It is good practice to do so whenever a variable is needed only in that @@ -19090,7 +19215,7 @@ The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is not one of @command{awk}'s built-in variables, such as @code{FS}. -@cindex @option{--dump-variables} option +@cindex @option{--dump-variables} option, using for library functions It is also important that @emph{all} variables in library functions that do not need to save state are, in fact, declared local.@footnote{@command{gawk}'s @option{--dump-variables} command-line @@ -20907,7 +21032,7 @@ from anywhere within a user's program, and the user may have his or her own way of splitting records and fields. -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, testing the field splitting The @code{using_fw} variable checks @code{PROCINFO["FS"]}, which is @code{"FIELDWIDTHS"} if field splitting is being done with @code{FIELDWIDTHS}. This makes it possible to restore the correct @@ -21030,7 +21155,7 @@ uses these functions. @cindex group database, reading @c STARTOFRANGE datagr @cindex database, group, reading -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, and group membership @cindex @code{getgrent()} function (C library) @cindex @code{getgrent()} user-defined function @cindex groups@comma{} information about @@ -22209,7 +22334,7 @@ $ @kbd{id} @print{} uid=500(arnold) gid=500(arnold) groups=6(disk),7(lp),19(floppy) @end example -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, and user and group ID numbers This information is part of what is provided by @command{gawk}'s @code{PROCINFO} array (@pxref{Built-in Variables}). However, the @command{id} utility provides a more palatable output than just @@ -22310,7 +22435,6 @@ BEGIN \ @c endfile @end example -@cindex @code{in} operator The test in the @code{for} loop is worth noting. Any supplementary groups in the @code{PROCINFO} array have the indices @code{"group1"} through @code{"group@var{N}"} for some @@ -22320,7 +22444,7 @@ there are. This loop works by starting at one, concatenating the value with @code{"group"}, and then using @code{in} to see if that value is -in the array. Eventually, @code{i} is incremented past +in the array (@pxref{Reference to Elements}). Eventually, @code{i} is incremented past the last group in the array and the loop exits. The loop is also correct if there are @emph{no} supplementary @@ -25432,9 +25556,9 @@ sorted array traversal is not the default. @subsection Sorting Array Values and Indices with @command{gawk} @cindex arrays, sorting -@cindex @code{asort()} function (@command{gawk}) +@cindexgawkfunc{asort} @cindex @code{asort()} function (@command{gawk}), arrays@comma{} sorting -@cindex @code{asorti()} function (@command{gawk}) +@cindexgawkfunc{asorti} @cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting In most @command{awk} implementations, sorting an array requires writing @@ -25529,9 +25653,8 @@ both arrays use the values. @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex @code{IGNORECASE} variable -@cindex arrays, sorting, @code{IGNORECASE} variable and -@cindex @code{IGNORECASE} variable, array sorting and +@cindex arrays, sorting, and @code{IGNORECASE} variable +@cindex @code{IGNORECASE} variable, and array sorting functions Because @code{IGNORECASE} affects string comparisons, the value of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}. Note also that the locale's sorting order does @emph{not} @@ -25700,7 +25823,7 @@ As a side note, the assignment @samp{LC_ALL=C} in the @command{sort} command ensures traditional Unix (ASCII) sorting from @command{sort}. @cindex @command{gawk}, @code{PROCINFO} array in -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, and communications via ptys You may also 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 @@ -25903,8 +26026,8 @@ Here is the @file{awkprof.out} that results from running the illustrates that @command{awk} programmers sometimes get up very early in the morning to work.) -@cindex @code{BEGIN} pattern -@cindex @code{END} pattern +@cindex @code{BEGIN} pattern, and profiling +@cindex @code{END} pattern, and profiling @example # gawk profile, created Thu Feb 27 05:16:21 2014 @@ -25968,7 +26091,7 @@ Multiple @code{BEGIN} and @code{END} rules retain their separate identities, as do multiple @code{BEGINFILE} and @code{ENDFILE} rules. -@cindex patterns, counts +@cindex patterns, counts, in a profile @item Pattern-action rules have two counts. The first count, to the left of the rule, shows how many times @@ -25988,7 +26111,7 @@ is a count showing how many times the condition was true. The count for the @code{else} indicates how many times the test failed. -@cindex loops, count for header +@cindex loops, count for header, in a profile @item The count for a loop header (such as @code{for} or @code{while}) shows how many times the loop test was executed. @@ -25996,8 +26119,8 @@ or @code{while}) shows how many times the loop test was executed. statement in a rule to determine how many times the rule was executed. If the first statement is a loop, the count is misleading.) -@cindex functions, user-defined, counts -@cindex user-defined, functions, counts +@cindex functions, user-defined, counts, in a profile +@cindex user-defined, functions, counts, in a profile @item For user-defined functions, the count next to the @code{function} keyword indicates how many times the function was called. @@ -26011,8 +26134,8 @@ The layout uses ``K&R'' style with TABs. Braces are used everywhere, even when the body of an @code{if}, @code{else}, or loop is only a single statement. -@cindex @code{()} (parentheses) -@cindex parentheses @code{()} +@cindex @code{()} (parentheses), in a profile +@cindex parentheses @code{()}, in a profile @item Parentheses are used only where needed, as indicated by the structure of the program and the precedence rules. @@ -26068,6 +26191,7 @@ which is correct, but possibly surprising. @cindex profiling @command{awk} programs, dynamically @cindex @command{gawk} program, dynamic profiling +@cindex dynamic profiling Besides creating profiles when a program has completed, @command{gawk} can produce a profile while it is running. This is useful if your @command{awk} program goes into an @@ -26081,9 +26205,9 @@ $ @kbd{gawk --profile -f myprog &} @end example @cindex @command{kill} command@comma{} dynamic profiling -@cindex @code{USR1} signal -@cindex @code{SIGUSR1} signal -@cindex signals, @code{USR1}/@code{SIGUSR1} +@cindex @code{USR1} signal, for dynamic profiling +@cindex @code{SIGUSR1} signal, for dynamic profiling +@cindex signals, @code{USR1}/@code{SIGUSR1}, for profiling @noindent The shell prints a job number and process ID number; in this case, 13992. Use the @command{kill} command to send the @code{USR1} signal @@ -26114,9 +26238,9 @@ You may send @command{gawk} the @code{USR1} signal as many times as you like. Each time, the profile and function call trace are appended to the output profile file. -@cindex @code{HUP} signal -@cindex @code{SIGHUP} signal -@cindex signals, @code{HUP}/@code{SIGHUP} +@cindex @code{HUP} signal, for dynamic profiling +@cindex @code{SIGHUP} signal, for dynamic profiling +@cindex signals, @code{HUP}/@code{SIGHUP}, for profiling If you use the @code{HUP} signal instead of the @code{USR1} signal, @command{gawk} produces the profile and the function call trace and then exits. @@ -26414,7 +26538,7 @@ String constants marked with a leading underscore are candidates for translation at runtime. String constants without a leading underscore are not translated. -@cindex @code{dcgettext()} function (@command{gawk}) +@cindexgawkfunc{dcgettext} @item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. @@ -26440,7 +26564,7 @@ chosen to be simple and to allow for reasonable @command{awk}-style default arguments. @end quotation -@cindex @code{dcngettext()} function (@command{gawk}) +@cindexgawkfunc{dcngettext} @item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @@ -26456,7 +26580,7 @@ The same remarks about argument order as for the @code{dcgettext()} function app @cindex files, @code{.gmo}, specifying directory of @cindex message object files, specifying directory of @cindex files, message object, specifying directory of -@cindex @code{bindtextdomain()} function (@command{gawk}) +@cindexgawkfunc{bindtextdomain} @item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]}) Change the directory in which @code{gettext} looks for @file{.gmo} files, in case they @@ -27030,6 +27154,7 @@ The following list defines terms used throughout the rest of this @value{CHAPTER}. @table @dfn +@cindex stack frame @item Stack Frame Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). @@ -27051,6 +27176,7 @@ invoked. Commands that print the call stack print information about each stack frame (as detailed later on). @item Breakpoint +@cindex breakpoint During debugging, you often wish to let the program run until it reaches a certain point, and then continue execution from there one statement (or instruction) at a time. The way to do this is to set @@ -27060,6 +27186,7 @@ take over control of the program's execution. You can add and remove as many breakpoints as you like. @item Watchpoint +@cindex watchpoint A watchpoint is similar to a breakpoint. The difference is that breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution @@ -27091,6 +27218,7 @@ by the higher-level @command{awk} commands. @node Sample Debugging Session @section Sample Debugging Session +@cindex sample debugging session In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample debugging session. We will use the @command{awk} implementation of the @@ -27104,6 +27232,8 @@ as our example. @node Debugger Invocation @subsection How to Start the Debugger +@cindex starting the debugger +@cindex debugger, how to start Starting the debugger is almost exactly like running @command{gawk}, except you have to pass an additional option @option{--debug} or the @@ -27444,6 +27574,8 @@ controlling breakpoints are: @cindex debugger commands, @code{break} @cindex @code{break} debugger command @cindex @code{b} debugger command (alias for @code{break}) +@cindex set breakpoint +@cindex breakpoint, setting @item @code{break} [[@var{filename}@code{:}]@var{n} | @var{function}] [@code{"@var{expression}"}] @itemx @code{b} [[@var{filename}@code{:}]@var{n} | @var{function}] [@code{"@var{expression}"}] Without any argument, set a breakpoint at the next instruction @@ -27474,6 +27606,8 @@ it continues executing the program. @cindex debugger commands, @code{clear} @cindex @code{clear} debugger command +@cindex delete breakpoint at location +@cindex breakpoint at location, how to delete @item @code{clear} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, delete any breakpoint at the next instruction to be executed in the selected stack frame. If the program stops at @@ -27494,6 +27628,7 @@ Delete breakpoint(s) set at entry to function @var{function}. @cindex debugger commands, @code{condition} @cindex @code{condition} debugger command +@cindex breakpoint condition @item @code{condition} @var{n} @code{"@var{expression}"} Add a condition to existing breakpoint or watchpoint @var{n}. The condition is an @command{awk} expression that the debugger evaluates @@ -27507,6 +27642,8 @@ watchpoint is made unconditional. @cindex debugger commands, @code{delete} @cindex @code{delete} debugger command @cindex @code{d} debugger command (alias for @code{delete}) +@cindex delete breakpoint by number +@cindex breakpoint, delete by number @item @code{delete} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{d} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] Delete specified breakpoints or a range of breakpoints. Deletes @@ -27514,6 +27651,8 @@ all defined breakpoints if no argument is supplied. @cindex debugger commands, @code{disable} @cindex @code{disable} debugger command +@cindex disable breakpoint +@cindex breakpoint, how to disable or enable @item @code{disable} [@var{n1 n2} @dots{} | @var{n}--@var{m}] Disable specified breakpoints or a range of breakpoints. Without any argument, disables all breakpoints. @@ -27522,6 +27661,7 @@ any argument, disables all breakpoints. @cindex debugger commands, @code{enable} @cindex @code{enable} debugger command @cindex @code{e} debugger command (alias for @code{enable}) +@cindex enable breakpoint @item @code{enable} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{e} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] Enable specified breakpoints or a range of breakpoints. Without @@ -27541,6 +27681,7 @@ the program stops at the breakpoint. @cindex debugger commands, @code{ignore} @cindex @code{ignore} debugger command +@cindex ignore breakpoint @item @code{ignore} @var{n} @var{count} Ignore breakpoint number @var{n} the next @var{count} times it is hit. @@ -27549,6 +27690,7 @@ hit. @cindex debugger commands, @code{tbreak} @cindex @code{tbreak} debugger command @cindex @code{t} debugger command (alias for @code{tbreak}) +@cindex temporary breakpoint @item @code{tbreak} [[@var{filename}@code{:}]@var{n} | @var{function}] @itemx @code{t} [[@var{filename}@code{:}]@var{n} | @var{function}] Set a temporary breakpoint (enabled for only one stop). @@ -27569,6 +27711,8 @@ execution of the program than we saw in our earlier example: @cindex @code{silent} debugger command @cindex debugger commands, @code{end} @cindex @code{end} debugger command +@cindex breakpoint commands +@cindex commands to execute at breakpoint @item @code{commands} [@var{n}] @itemx @code{silent} @itemx @dots{} @@ -27596,6 +27740,7 @@ gawk> @cindex debugger commands, @code{c} (@code{continue}) @cindex debugger commands, @code{continue} +@cindex continue program, in debugger @item @code{continue} [@var{count}] @itemx @code{c} [@var{count}] Resume program execution. If continued from a breakpoint and @var{count} is @@ -27612,6 +27757,7 @@ Print the returned value. @cindex debugger commands, @code{next} @cindex @code{next} debugger command @cindex @code{n} debugger command (alias for @code{next}) +@cindex single-step execution, in the debugger @item @code{next} [@var{count}] @itemx @code{n} [@var{count}] Continue execution to the next source line, stepping over function calls. @@ -27706,6 +27852,7 @@ items on the list. @cindex debugger commands, @code{eval} @cindex @code{eval} debugger command +@cindex evaluate expressions, in debugger @item @code{eval "@var{awk statements}"} Evaluate @var{awk statements} in the context of the running program. You can do anything that an @command{awk} program would do: assign @@ -27723,6 +27870,7 @@ parameters defined by the program. @cindex debugger commands, @code{print} @cindex @code{print} debugger command @cindex @code{p} debugger command (alias for @code{print}) +@cindex print variables, in debugger @item @code{print} @var{var1}[@code{,} @var{var2} @dots{}] @itemx @code{p} @var{var1}[@code{,} @var{var2} @dots{}] Print the value of a @command{gawk} variable or field. @@ -27756,6 +27904,7 @@ No newline is printed unless one is specified. @cindex debugger commands, @code{set} @cindex @code{set} debugger command +@cindex assign values to variables, in debugger @item @code{set} @var{var}@code{=}@var{value} Assign a constant (number or string) value to an @command{awk} variable or field. @@ -27768,6 +27917,7 @@ You can also set special @command{awk} variables, such as @code{FS}, @cindex debugger commands, @code{watch} @cindex @code{watch} debugger command @cindex @code{w} debugger command (alias for @code{watch}) +@cindex set watchpoint @item @code{watch} @var{var} | @code{$}@var{n} [@code{"@var{expression}"}] @itemx @code{w} @var{var} | @code{$}@var{n} [@code{"@var{expression}"}] Add variable @var{var} (or field @code{$@var{n}}) to the watch list. @@ -27784,12 +27934,14 @@ then the debugger stops execution and prompts for a command. Otherwise, @cindex debugger commands, @code{undisplay} @cindex @code{undisplay} debugger command +@cindex stop automatic display, in debugger @item @code{undisplay} [@var{n}] Remove item number @var{n} (or all items, if no argument) from the automatic display list. @cindex debugger commands, @code{unwatch} @cindex @code{unwatch} debugger command +@cindex delete watchpoint @item @code{unwatch} [@var{n}] Remove item number @var{n} (or all items, if no argument) from the watch list. @@ -27810,6 +27962,8 @@ functions which called the one you are in. The commands for doing this are: @cindex debugger commands, @code{backtrace} @cindex @code{backtrace} debugger command @cindex @code{bt} debugger command (alias for @code{backtrace}) +@cindex call stack, display in debugger +@cindex traceback, display in debugger @item @code{backtrace} [@var{count}] @itemx @code{bt} [@var{count}] Print a backtrace of all function calls (stack frames), or innermost @var{count} @@ -27863,25 +28017,32 @@ The value for @var{what} should be one of the following: @c nested table @table @code @item args +@cindex show function arguments, in debugger Arguments of the selected frame. @item break +@cindex show breakpoints List all currently set breakpoints. @item display +@cindex automatic displays, in debugger List all items in the automatic display list. @item frame +@cindex describe call stack frame, in debugger Description of the selected stack frame. @item functions +@cindex list function definitions, in debugger List all function definitions including source file names and line numbers. @item locals +@cindex show local variables, in debugger Local variables of the selected frame. @item source +@cindex show name of current source file, in debugger The name of the current source file. Each time the program stops, the current source file is the file containing the current instruction. When the debugger first starts, the current source file is the first file @@ -27890,12 +28051,15 @@ included via the @option{-f} option. The be used at any time to change the current source. @item sources +@cindex show all source files, in debugger List all program sources. @item variables +@cindex list all global variables, in debugger List all global variables. @item watch +@cindex show watchpoints List all items in the watch list. @end table @end table @@ -27909,6 +28073,8 @@ from a file. The commands are: @cindex debugger commands, @code{option} @cindex @code{option} debugger command @cindex @code{o} debugger command (alias for @code{option}) +@cindex display debugger options +@cindex debugger options @item @code{option} [@var{name}[@code{=}@var{value}]] @itemx @code{o} [@var{name}[@code{=}@var{value}]] Without an argument, display the available debugger options @@ -27920,6 +28086,7 @@ The available options are: @c nested table @table @code @item history_size +@cindex debugger history size The maximum number of lines to keep in the history file @file{./.gawk_history}. The default is 100. @@ -27927,23 +28094,28 @@ The default is 100. The number of lines that @code{list} prints. The default is 15. @item outfile +@cindex redirect @command{gawk} output, in debugger Send @command{gawk} output to a file; debugger output still goes to standard output. An empty string (@code{""}) resets output to standard output. @item prompt +@cindex debugger prompt The debugger prompt. The default is @samp{@w{gawk> }}. @item save_history @r{[}on @r{|} off@r{]} +@cindex debugger history file Save command history to file @file{./.gawk_history}. The default is @code{on}. @item save_options @r{[}on @r{|} off@r{]} +@cindex save debugger options Save current options to file @file{./.gawkrc} upon exit. The default is @code{on}. Options are read back in to the next session upon startup. @item trace @r{[}on @r{|} off@r{]} +@cindex instruction tracing, in debugger Turn instruction tracing on or off. The default is @code{off}. @end table @@ -27952,6 +28124,7 @@ Save the commands from the current session to the given file name, so that they can be replayed using the @command{source} command. @item @code{source} @var{filename} +@cindex debugger, read commands from a file Run command(s) from a file; an error in any command does not terminate execution of subsequent commands. Comments (lines starting with @samp{#}) are allowed in a command file. @@ -28084,6 +28257,7 @@ function @var{function}. This command may change the current source file. @cindex debugger commands, @code{quit} @cindex @code{quit} debugger command @cindex @code{q} debugger command (alias for @code{quit}) +@cindex exit the debugger @item @code{quit} @itemx @code{q} Exit the debugger. Debugging is great fun, but sometimes we all have @@ -28107,6 +28281,8 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while @node Readline Support @section Readline Support +@cindex command completion, in debugger +@cindex history expansion, in debugger If @command{gawk} is compiled with the @code{readline} library, you can take advantage of that library's command completion and history expansion @@ -28195,8 +28371,6 @@ be added, and of course feel free to try to add them yourself! @cindex multiple precision @cindex infinite precision @cindex floating-point, numbers@comma{} arbitrary precision -@cindex MPFR -@cindex GMP @cindex Knuth, Donald @quotation @@ -28960,6 +29134,8 @@ when you change the rounding mode. @node Gawk and MPFR @section @command{gawk} + MPFR = Powerful Arithmetic +@cindex MPFR +@cindex GMP The rest of this @value{CHAPTER} describes how to use the arbitrary precision (also known as @dfn{multiple precision} or @dfn{infinite precision}) numeric @@ -29064,6 +29240,7 @@ your program. @node Setting Precision @subsection Setting the Working Precision @cindex @code{PREC} variable +@cindex setting working precision @command{gawk} uses a global working precision; it does not keep track of the precision or accuracy of individual numbers. Performing an arithmetic @@ -29139,6 +29316,7 @@ issues that occur because numbers are stored internally in binary. @node Setting Rounding Mode @subsection Setting the Rounding Mode @cindex @code{ROUNDMODE} variable +@cindex setting rounding mode The @code{ROUNDMODE} variable provides program level control over the rounding mode. @@ -29206,6 +29384,7 @@ In the first case, the number is stored with the default precision of 53 bits. @node Changing Precision @subsection Changing the Precision of a Number +@cindex changing precision of a number @cindex Laurie, Dirk @quotation @@ -29324,6 +29503,7 @@ the problem at hand is often the correct approach in such situations. @node Arbitrary Precision Integers @section Arbitrary Precision Integer Arithmetic with @command{gawk} @cindex integers, arbitrary precision +@cindex arbitrary precision integers If one of the options @option{--bignum} or @option{-M} is specified, @command{gawk} performs all @@ -29420,6 +29600,7 @@ gawk -M 'BEGIN @{ n = 13; print n % 2 @}' @node Dynamic Extensions @chapter Writing Extensions for @command{gawk} +@cindex dynamically loaded extensions It is possible to add new functions written in C or C++ to @command{gawk} using dynamically loaded libraries. This facility is available on systems @@ -29454,6 +29635,7 @@ When @option{--sandbox} is specified, extensions are disabled @node Extension Intro @section Introduction +@cindex plug-in An @dfn{extension} (sometimes called a @dfn{plug-in}) is a piece of external compiled code that @command{gawk} can load at runtime to provide additional functionality, over and above the built-in capabilities @@ -29582,6 +29764,7 @@ happen, but we all know how @emph{that} goes.) @node Extension API Description @section API Description +@cindex extension API This (rather large) @value{SECTION} describes the API in detail. @@ -29966,6 +30149,8 @@ value type, as appropriate. This behavior is summarized in @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros +@cindex allocating memory for extensions +@cindex extensions, allocating memory The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, as well as a number of @@ -30080,6 +30265,8 @@ pointed to by @code{result}. @node Registration Functions @subsection Registration Functions +@cindex register extension +@cindex extension registration This @value{SECTION} describes the API functions for registering parts of your extension with @command{gawk}. @@ -30201,6 +30388,7 @@ is invoked with the @option{--version} option. @node Input Parsers @subsubsection Customized Input Parsers +@cindex customized input parser By default, @command{gawk} reads text files as its input. It uses the value of @code{RS} to find the end of the record, and then uses @code{FS} @@ -30448,7 +30636,9 @@ Register the input parser pointed to by @code{input_parser} with @node Output Wrappers @subsubsection Customized Output Wrappers +@cindex customized output wrapper +@cindex output wrapper An @dfn{output wrapper} is the mirror image of an input parser. It allows an extension to take over the output to a file opened with the @samp{>} or @samp{>>} I/O redirection operators (@pxref{Redirection}). @@ -30562,6 +30752,7 @@ Register the output wrapper pointed to by @code{output_wrapper} with @node Two-way processors @subsubsection Customized Two-way Processors +@cindex customized two-way processor A @dfn{two-way processor} combines an input parser and an output wrapper for two-way I/O with the @samp{|&} operator (@pxref{Redirection}). It makes identical @@ -30619,6 +30810,8 @@ Register the two-way processor pointed to by @code{two_way_processor} with @node Printing Messages @subsection Printing Messages +@cindex printing messages from extensions +@cindex messages from extensions You can print different kinds of warning messages from your extension, as described below. Note that for these functions, @@ -30692,6 +30885,7 @@ for more information on creating arrays. @node Symbol Table Access @subsection Symbol Table Access +@cindex accessing global variables from extensions Two sets of routines provide access to global variables, and one set allows you to create and release cached values. @@ -30737,6 +30931,13 @@ An extension can look up the value of @command{gawk}'s special variables. However, with the exception of the @code{PROCINFO} array, an extension cannot change any of those variables. +@quotation NOTE +It is possible for the lookup of @code{PROCINFO} to fail. This happens if +the @command{awk} program being run does not reference @code{PROCINFO}; +in this case @command{gawk} doesn't bother to create the array and +populate it. +@end quotation + @node Symbol table by cookie @subsubsection Variable Access and Update by Cookie @@ -30949,6 +31150,7 @@ you should release any cached values that you created, using @node Array Manipulation @subsection Array Manipulation +@cindex array manipulation in extensions The primary data structure@footnote{Okay, the only data structure.} in @command{awk} is the associative array (@pxref{Arrays}). @@ -31528,6 +31730,8 @@ information about how @command{gawk} was invoked. @node Extension Versioning @subsubsection API Version Constants and Variables +@cindex API version +@cindex extension API version The API provides both a ``major'' and a ``minor'' version number. The API versions are available at compile time as constants: @@ -31581,6 +31785,8 @@ provided in @file{gawkapi.h} (discussed later, in @node Extension API Informational Variables @subsubsection Informational Variables +@cindex API informational variables +@cindex extension API informational variables The API provides access to several variables that describe whether the corresponding command-line options were enabled when @@ -31726,6 +31932,8 @@ the version string with @command{gawk}. @node Finding Extensions @section How @command{gawk} Finds Extensions +@cindex extension search path +@cindex finding extensions Compiled extensions have to be installed in a directory where @command{gawk} can find them. If @command{gawk} is configured and @@ -31736,6 +31944,7 @@ path with a list of directories to search for compiled extensions. @node Extension Example @section Example: Some File Functions +@cindex extension example @quotation @i{No matter where you go, there you are.} @@ -32380,6 +32589,7 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @node Extension Samples @section The Sample Extensions In The @command{gawk} Distribution +@cindex extensions distributed with @command{gawk} This @value{SECTION} provides brief overviews of the sample extensions that come in the @command{gawk} distribution. Some of them are intended @@ -32971,7 +33181,7 @@ ret = reada("arraydump.bin", array) @subsection Reading An Entire File The @code{readfile} extension adds a single function -named @code{readfile()}: +named @code{readfile()}, and an input parser: @table @code @item @@load "readfile" @@ -32982,6 +33192,12 @@ This is how you load the extension. The argument is the name of the file to read. The return value is a string containing the entire contents of the requested file. Upon error, the function returns the empty string and sets @code{ERRNO}. + +@item BEGIN @{ PROCINFO["readfile"] = 1 @} +In addition, the extension adds an input parser that is activated if +@code{PROCINFO["readfile"]} exists. +When activated, each input file is returned in its entirety as @code{$0}. +@code{RT} is set to the null string. @end table Here is an example: @@ -33040,6 +33256,8 @@ tries to use @code{nanosleep()} or @code{select()} to implement the delay. @node gawkextlib @section The @code{gawkextlib} Project +@cindex @code{gawkextlib} +@cindex extensions, where to find @cindex @code{gawkextlib} project The @uref{http://sourceforge.net/projects/gawkextlib/, @code{gawkextlib}} @@ -34752,6 +34970,11 @@ Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. @item +@cindex Colombo, Antonio +Antonio Giovanni Colombo rewrote a number of examples in the early +chapters that were severely dated, for which I am incredibly grateful. + +@item @cindex Robbins, Arnold Arnold Robbins has been working on @command{gawk} since 1988, at first @@ -37494,9 +37717,6 @@ The GNU version of the standard shell @end ifinfo See also ``Bourne Shell.'' -@item BBS -See ``Bulletin Board System.'' - @item Bit Short for ``Binary Digit.'' All values in computer memory ultimately reduce to binary digits: values @@ -37571,11 +37791,6 @@ Changing some of them affects @command{awk}'s running environment. @item Braces See ``Curly Braces.'' -@item Bulletin Board System -A computer system allowing users to log in and read and/or leave messages -for other users of the system, much like leaving paper notes on a bulletin -board. - @item C The system programming language that most GNU software is written in. The @command{awk} programming language has C-like syntax, and this @value{DOCUMENT} @@ -39541,8 +39756,6 @@ Suggestions: % Next edition: % 1. Standardize the error messages from the functions and programs % in the two sample code chapters. -% 2. Nuke the BBS stuff and use something that won't be obsolete -% 3. Turn the advanced notes into sidebars by using @cartouche Better sidebars can almost sort of be done with: @@ -39574,4 +39787,3 @@ But to use it you have to say } which sorta sucks. - diff --git a/doc/gawktexi.in b/doc/gawktexi.in index e9a31935..cb35e37c 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -129,6 +129,30 @@ @end macro @end ifnothtml +@c Indexing macros +@ifinfo + +@macro cindexawkfunc{name} +@cindex @code{\name\} +@end macro + +@macro cindexgawkfunc{name} +@cindex @code{\name\} +@end macro + +@end ifinfo + +@ifnotinfo + +@macro cindexawkfunc{name} +@cindex @code{\name\()} function +@end macro + +@macro cindexgawkfunc{name} +@cindex @code{\name\()} function (@command{gawk}) +@end macro +@end ifnotinfo + @ignore Some comments on the layout for TeX. 1. Use at least texinfo.tex 2014-01-30.15 @@ -2037,11 +2061,11 @@ $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @print{} Don't Panic! @end example -@cindex quoting -@cindex double quote (@code{"}) -@cindex @code{"} (double quote) -@cindex @code{\} (backslash) -@cindex backslash (@code{\}) +@cindex shell quoting, double quote +@cindex double quote (@code{"}) in shell commands +@cindex @code{"} (double quote) in shell commands +@cindex @code{\} (backslash) in shell commands +@cindex backslash (@code{\}) in shell commands This program does not read any input. The @samp{\} before each of the inner double quotes is necessary because of the shell's quoting rules---in particular because it mixes both single quotes and @@ -2081,8 +2105,7 @@ awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{} @end example @cindex @option{-f} option -@cindex command line, options -@cindex options, command-line +@cindex command line, option @option{-f} The @option{-f} instructs the @command{awk} utility to get the @command{awk} program from the file @var{source-file}. Any file name can be used for @var{source-file}. For example, you could put the program: @@ -2105,7 +2128,7 @@ does the same thing as this one: awk "BEGIN @{ print \"Don't Panic!\" @}" @end example -@cindex quoting +@cindex quoting in @command{gawk} command lines @noindent This was explained earlier (@pxref{Read Terminal}). @@ -2116,9 +2139,9 @@ program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. @c STARTOFRANGE sq1x -@cindex single quote (@code{'}) +@cindex single quote (@code{'}) in @command{gawk} command lines @c STARTOFRANGE qs2x -@cindex @code{'} (single quote) +@cindex @code{'} (single quote) in @command{gawk} command lines If you want to clearly identify your @command{awk} program files as such, you can add the extension @file{.awk} to the file name. This doesn't affect the execution of the @command{awk} program but it does make @@ -2228,7 +2251,7 @@ 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. -@cindex quoting +@cindex quoting, for small awk programs @cindex single quote (@code{'}), vs.@: apostrophe @cindex @code{'} (single quote), vs.@: apostrophe @quotation CAUTION @@ -2269,7 +2292,7 @@ The next @value{SUBSECTION} describes the shell's quoting rules. @node Quoting @subsection Shell-Quoting Issues -@cindex quoting, rules for +@cindex shell quoting, rules for @menu * DOS Quoting:: Quoting in Windows Batch Files. @@ -2304,10 +2327,10 @@ that character. The shell removes the backslash and passes the quoted character on to the command. @item -@cindex @code{\} (backslash) -@cindex backslash (@code{\}) -@cindex single quote (@code{'}) -@cindex @code{'} (single quote) +@cindex @code{\} (backslash), in shell commands +@cindex backslash (@code{\}), in shell commands +@cindex single quote (@code{'}), in shell commands +@cindex @code{'} (single quote), in shell commands Single quotes protect everything between the opening and closing quotes. The shell does no interpretation of the quoted text, passing it on verbatim to the command. @@ -2317,8 +2340,8 @@ Refer back to for an example of what happens if you try. @item -@cindex double quote (@code{"}) -@cindex @code{"} (double quote) +@cindex double quote (@code{"}), in shell commands +@cindex @code{"} (double quote), in shell commands Double quotes protect most things between the opening and closing quotes. The shell does at least variable and command substitution on the quoted text. Different shells may do additional kinds of processing on double-quoted text. @@ -2355,7 +2378,7 @@ awk -F "" '@var{program}' @var{files} # correct @end example @noindent -@cindex null strings, quoting and +@cindex null strings in @command{gawk} arguments, quoting and Don't use this: @example @@ -2368,7 +2391,7 @@ as the value of @code{FS}, and the first file name as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize -@cindex quoting, tricks for +@cindex quoting in @command{gawk} command lines, tricks for Mixing single and double quotes is difficult. You have to resort to shell quoting tricks, like this: @@ -2483,40 +2506,39 @@ gawk "@{ print \"\042\" $0 \"\042\" @}" @var{file} @c For gawk >= 4.0, update these data files. No-one has such slow modems! @cindex input files, examples -@cindex @code{BBS-list} file +@cindex @code{mail-list} file Many of the examples in this @value{DOCUMENT} take their input from two sample -data files. The first, @file{BBS-list}, represents a list of -computer bulletin board systems together with information about those systems. +data files. The first, @file{mail-list}, represents a list of peoples' names +together with their email addresses and information about those people. The second data file, called @file{inventory-shipped}, contains information about monthly shipments. In both files, each line is considered to be one @dfn{record}. -In the data file @file{BBS-list}, each record contains the name of a computer -bulletin board, its phone number, the board's baud rate(s), and a code for -the number of hours it is operational. An @samp{A} in the last column -means the board operates 24 hours a day. A @samp{B} in the last -column means the board only operates on evening and weekend hours. -A @samp{C} means the board operates only on weekends: +In the data file @file{mail-list}, each record contains the name of a person, +his/her phone number, his/her email-address, and a code for their relationship +with the author of the list. An @samp{A} in the last column +means that the person is an acquaintance. An @samp{F} in the last +column means that the person is a friend. +An @samp{R} means that the person is a relative: -@c 2e: Update the baud rates to reflect today's faster modems @example @c system if test ! -d eg ; then mkdir eg ; fi @c system if test ! -d eg/lib ; then mkdir eg/lib ; fi @c system if test ! -d eg/data ; then mkdir eg/data ; fi @c system if test ! -d eg/prog ; then mkdir eg/prog ; fi @c system if test ! -d eg/misc ; then mkdir eg/misc ; fi -@c file eg/data/BBS-list -aardvark 555-5553 1200/300 B -alpo-net 555-3412 2400/1200/300 A -barfly 555-7685 1200/300 A -bites 555-1675 2400/1200/300 A -camelot 555-0542 300 C -core 555-2912 1200/300 C -fooey 555-1234 2400/1200/300 B -foot 555-6699 1200/300 B -macfoo 555-6480 1200/300 A -sdace 555-3430 2400/1200/300 A -sabafoo 555-2127 1200/300 C +@c file eg/data/mail-list +Amelia 555-5553 amelia.zodiacusque@@gmail.com F +Anthony 555-3412 anthony.asserturo@@hotmail.com A +Becky 555-7685 becky.algebrarum@@gmail.com A +Bill 555-1675 bill.drowning@@hotmail.com A +Broderick 555-0542 broderick.aliquotiens@@yahoo.com R +Camilla 555-2912 camilla.infusarum@@skynet.be R +Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +Julie 555-6699 julie.perscrutabor@@skeeve.com F +Martin 555-6480 martin.codicibus@@hotmail.com A +Samuel 555-3430 samuel.lanceolis@@shu.edu A +Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @c endfile @end example @@ -2558,23 +2580,23 @@ in the directory @file{awklib/eg/data}. @section Some Simple Examples The following command runs a simple @command{awk} program that searches the -input file @file{BBS-list} for the character string @samp{foo} (a +input file @file{mail-list} for the character string @samp{li} (a grouping of characters is usually called a @dfn{string}; the term @dfn{string} is based on similar usage in English, such as ``a string of pearls,'' or ``a string of cars in a train''): @example -awk '/foo/ @{ print $0 @}' BBS-list +awk '/li/ @{ print $0 @}' mail-list @end example @noindent -When lines containing @samp{foo} are found, they are printed because +When lines containing @samp{li} are found, they are printed because @w{@samp{print $0}} means print the current line. (Just @samp{print} by itself means the same thing, so we could have written that instead.) -You will notice that slashes (@samp{/}) surround the string @samp{foo} -in the @command{awk} program. The slashes indicate that @samp{foo} +You will notice that slashes (@samp{/}) surround the string @samp{li} +in the @command{awk} program. The slashes indicate that @samp{li} is the pattern to search for. This type of pattern is called a @dfn{regular expression}, which is covered in more detail later (@pxref{Regexp}). @@ -2586,11 +2608,11 @@ interpret any of it as special shell characters. Here is what this program prints: @example -$ @kbd{awk '/foo/ @{ print $0 @}' BBS-list} -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sabafoo 555-2127 1200/300 C +$ @kbd{awk '/li/ @{ print $0 @}' mail-list} +@print{} Amelia 555-5553 amelia.zodiacusque@@gmail.com F +@print{} Broderick 555-0542 broderick.aliquotiens@@yahoo.com R +@print{} Julie 555-6699 julie.perscrutabor@@skeeve.com F +@print{} Samuel 555-3430 samuel.lanceolis@@shu.edu A @end example @cindex actions, default @@ -2603,7 +2625,7 @@ action is to print all lines that match the pattern. @cindex actions, empty Thus, we could leave out the action (the @code{print} statement and the curly braces) in the previous example and the result would be the same: -@command{awk} prints all lines matching the pattern @samp{foo}. By comparison, +@command{awk} prints all lines matching the pattern @samp{li}. By comparison, omitting the @code{print} statement but retaining the curly braces makes an empty action that does nothing (i.e., no lines are printed). @@ -2748,29 +2770,23 @@ This program prints every line that contains the string strings, it is printed twice, once by each rule. This is what happens if we run this program on our two sample data files, -@file{BBS-list} and @file{inventory-shipped}: +@file{mail-list} and @file{inventory-shipped}: @example $ @kbd{awk '/12/ @{ print $0 @}} -> @kbd{/21/ @{ print $0 @}' BBS-list inventory-shipped} -@print{} aardvark 555-5553 1200/300 B -@print{} alpo-net 555-3412 2400/1200/300 A -@print{} barfly 555-7685 1200/300 A -@print{} bites 555-1675 2400/1200/300 A -@print{} core 555-2912 1200/300 C -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sdace 555-3430 2400/1200/300 A -@print{} sabafoo 555-2127 1200/300 C -@print{} sabafoo 555-2127 1200/300 C +> @kbd{/21/ @{ print $0 @}' mail-list inventory-shipped} +@print{} Anthony 555-3412 anthony.asserturo@@hotmail.com A +@print{} Camilla 555-2912 camilla.infusarum@@skynet.be R +@print{} Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @print{} Jan 21 36 64 620 @print{} Apr 21 70 74 514 @end example @noindent -Note how the line beginning with @samp{sabafoo} -in @file{BBS-list} was printed twice, once for each rule. +Note how the line beginning with @samp{Jean-Paul} +in @file{mail-list} was printed twice, once for each rule. @node More Complex @section A More Complex Example @@ -2849,7 +2865,7 @@ separate rule, like this: @example awk '/12/ @{ print $0 @} - /21/ @{ print $0 @}' BBS-list inventory-shipped + /21/ @{ print $0 @}' mail-list inventory-shipped @end example @cindex @command{gawk}, newlines in @@ -3257,6 +3273,7 @@ Print the short version of the General Public License and then exit. @itemx --dump-variables@r{[}=@var{file}@r{]} @cindex @option{-d} option @cindex @option{--dump-variables} option +@cindex dump all variables of a program @cindex @file{awkvars.out} file @cindex files, @file{awkvars.out} @cindex variables, global, printing list of @@ -3410,7 +3427,7 @@ care to search for all occurrences of each inappropriate construct. As @cindex @option{--bignum} option Force arbitrary precision arithmetic on numbers. This option has no effect if @command{gawk} is not compiled to use the GNU MPFR and MP libraries -(@pxref{Arbitrary Precision Arithmetic}). +(@pxref{Gawk and MPFR}). @item -n @itemx --non-decimal-data @@ -3663,6 +3680,7 @@ file at all. @cindex @command{gawk}, @code{ARGIND} variable in @cindex @code{ARGIND} variable, command-line arguments +@cindex @code{ARGV} array, indexing into @cindex @code{ARGC}/@code{ARGV} variables, command-line arguments All these arguments are made available to your @command{awk} program in the @code{ARGV} array (@pxref{Built-in Variables}). Command-line options @@ -3673,6 +3691,7 @@ sets the variable @code{ARGIND} to the index in @code{ARGV} of the current element. @cindex input files, variable assignments and +@cindex variable assignments and input files The distinction between file name arguments and variable-assignment arguments is made when @command{awk} is about to open the next input file. At that point in execution, it checks the file name to see whether @@ -3750,6 +3769,7 @@ this file name itself.) @node Environment Variables @section The Environment Variables @command{gawk} Uses +@cindex environment variables used by @command{gawk} A number of environment variables influence how @command{gawk} behaves. @@ -3765,8 +3785,7 @@ behaves. @node AWKPATH Variable @subsection The @env{AWKPATH} Environment Variable @cindex @env{AWKPATH} environment variable -@cindex directories, searching -@cindex search paths +@cindex directories, searching for source files @cindex search paths, for source files @cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable @ifinfo @@ -3778,12 +3797,12 @@ implementations, you must supply a precise path name for each program file, unless the file is in the current directory. But in @command{gawk}, if the file name supplied to the @option{-f} or @option{-i} options -does not contain a @samp{/}, then @command{gawk} searches a list of +does not contain a directory separator @samp{/}, then @command{gawk} searches a list of directories (called the @dfn{search path}), one by one, looking for a file with the specified name. The search path is a string consisting of directory names -separated by colons. @command{gawk} gets its search path from the +separated by colons@footnote{Semicolons on MS-Windows and MS-DOS.}. @command{gawk} gets its search path from the @env{AWKPATH} environment variable. If that variable does not exist, @command{gawk} uses a default path, @samp{.:/usr/local/share/awk}.@footnote{Your version of @command{gawk} @@ -3841,8 +3860,7 @@ found, and @command{gawk} no longer needs to use @env{AWKPATH}. @node AWKLIBPATH Variable @subsection The @env{AWKLIBPATH} Environment Variable @cindex @env{AWKLIBPATH} environment variable -@cindex directories, searching -@cindex search paths +@cindex directories, searching for shared libraries @cindex search paths, for shared libraries @cindex differences in @command{awk} and @command{gawk}, @code{AWKLIBPATH} environment variable @@ -4127,7 +4145,6 @@ they will @emph{not} be in the next release). @c update this section for each release! -@cindex @code{PROCINFO} array The process-related special files @file{/dev/pid}, @file{/dev/ppid}, @file{/dev/pgrpid}, and @file{/dev/user} were deprecated in @command{gawk} 3.1, but still worked. As of version 4.0, they are no longer @@ -4212,7 +4229,7 @@ long-undocumented ``feature'' of Unix @code{awk}. @node Regexp @chapter Regular Expressions -@cindex regexp, See regular expressions +@cindex regexp @c STARTOFRANGE regexp @cindex regular expressions @@ -4221,8 +4238,8 @@ set of strings. Because regular expressions are such a fundamental part of @command{awk} programming, their format and use deserve a separate @value{CHAPTER}. -@cindex forward slash (@code{/}) -@cindex @code{/} (forward slash) +@cindex forward slash (@code{/}) to enclose regular expressions +@cindex @code{/} (forward slash) to enclose regular expressions A regular expression enclosed in slashes (@samp{/}) is an @command{awk} pattern that matches every input record whose text belongs to that set. @@ -4259,14 +4276,14 @@ slashes. Then the regular expression is tested against the entire text of each record. (Normally, it only needs to match some part of the text in order to succeed.) For example, the following prints the second field of each record that contains the string -@samp{foo} anywhere in it: +@samp{li} anywhere in it: @example -$ @kbd{awk '/foo/ @{ print $2 @}' BBS-list} -@print{} 555-1234 +$ @kbd{awk '/li/ @{ print $2 @}' mail-list} +@print{} 555-5553 +@print{} 555-0542 @print{} 555-6699 -@print{} 555-6480 -@print{} 555-2127 +@print{} 555-3430 @end example @cindex regular expressions, operators @@ -4278,9 +4295,9 @@ $ @kbd{awk '/foo/ @{ print $2 @}' BBS-list} @cindex @code{!} (exclamation point), @code{!~} operator @cindex exclamation point (@code{!}), @code{!~} operator @c @cindex operators, @code{!~} -@cindex @code{if} statement -@cindex @code{while} statement -@cindex @code{do}-@code{while} statement +@cindex @code{if} statement, use of regexps in +@cindex @code{while} statement, use of regexps in +@cindex @code{do}-@code{while} statement, use of regexps in @c @cindex statements, @code{if} @c @cindex statements, @code{while} @c @cindex statements, @code{do} @@ -4339,6 +4356,7 @@ $ @kbd{awk '$1 !~ /J/' inventory-shipped} @end example @cindex regexp constants +@cindex constant regexps @cindex regular expressions, constants, See regexp constants When a regexp is enclosed in slashes, such as @code{/foo/}, we call it a @dfn{regexp constant}, much like @code{5.27} is a numeric constant and @@ -4347,7 +4365,7 @@ a @dfn{regexp constant}, much like @code{5.27} is a numeric constant and @node Escape Sequences @section Escape Sequences -@cindex escape sequences +@cindex escape sequences, in strings @cindex backslash (@code{\}), in escape sequences @cindex @code{\} (backslash), in escape sequences Some characters cannot be included literally in string constants @@ -4558,6 +4576,7 @@ escape sequences literally when used in regexp constants. Thus, @section Regular Expression Operators @c STARTOFRANGE regexpo @cindex regular expressions, operators +@cindex metacharacters in regular expressions You can combine regular expressions with special characters, called @dfn{regular expression operators} or @dfn{metacharacters}, to @@ -4576,8 +4595,8 @@ Here is a list of metacharacters. All characters that are not escape sequences and that are not listed in the table stand for themselves: @table @code -@cindex backslash (@code{\}) -@cindex @code{\} (backslash) +@cindex backslash (@code{\}), regexp operator +@cindex @code{\} (backslash), regexp operator @item \ This is used to suppress the special meaning of a character when matching. For example, @samp{\$} @@ -4615,8 +4634,8 @@ The condition in the following example is not true: if ("line1\nLINE 2" ~ /1$/) @dots{} @end example -@cindex @code{.} (period) -@cindex period (@code{.}) +@cindex @code{.} (period), regexp operator +@cindex period (@code{.}), regexp operator @item . @r{(period)} This matches any single character, @emph{including} the newline character. For example, @samp{.P} @@ -4632,8 +4651,8 @@ character, which is a character with all bits equal to zero. Otherwise, @sc{nul} is just another character. Other versions of @command{awk} may not be able to match the @sc{nul} character. -@cindex @code{[]} (square brackets) -@cindex square brackets (@code{[]}) +@cindex @code{[]} (square brackets), regexp operator +@cindex square brackets (@code{[]}), regexp operator @cindex bracket expressions @cindex character sets, See Also bracket expressions @cindex character lists, See bracket expressions @@ -4670,8 +4689,8 @@ means it matches any string that starts with @samp{P} or contains a digit. The alternation applies to the largest possible regexps on either side. -@cindex @code{()} (parentheses) -@cindex parentheses @code{()} +@cindex @code{()} (parentheses), regexp operator +@cindex parentheses @code{()}, regexp operator @item (@dots{}) Parentheses are used for grouping in regular expressions, as in arithmetic. They can be used to concatenate regular expressions @@ -4720,7 +4739,7 @@ This symbol is similar to @samp{*}, except that the preceding expression can be matched either once or not at all. For example, @samp{fe?d} matches @samp{fed} and @samp{fd}, but nothing else. -@cindex interval expressions +@cindex interval expressions, regexp operator @item @{@var{n}@} @itemx @{@var{n},@} @itemx @{@var{n},@var{m}@} @@ -4797,6 +4816,7 @@ expressions are not available in regular expressions. @cindex bracket expressions @cindex bracket expressions, range expressions @cindex range expressions (regexps) +@cindex character lists in regular expression As mentioned earlier, a bracket expression matches any character amongst those listed between the opening and closing square brackets. @@ -5060,7 +5080,7 @@ lesser of two evils. @c @c Should really do this with file inclusion. @cindex regular expressions, @command{gawk}, command-line options -@cindex @command{gawk}, command-line options +@cindex @command{gawk}, command-line options, and regular expressions The various command-line options (@pxref{Options}) control how @command{gawk} interprets characters in regexps: @@ -5139,7 +5159,7 @@ This works in any POSIX-compliant @command{awk}. @cindex tilde (@code{~}), @code{~} operator @cindex @code{!} (exclamation point), @code{!~} operator @cindex exclamation point (@code{!}), @code{!~} operator -@cindex @code{IGNORECASE} variable +@cindex @code{IGNORECASE} variable, with @code{~} and @code{!~} operators @cindex @command{gawk}, @code{IGNORECASE} variable in @c @cindex variables, @code{IGNORECASE} Another method, specific to @command{gawk}, is to set the variable @@ -5360,6 +5380,7 @@ occur often in practice, but it's worth noting for future reference. @chapter Reading Input Files @c STARTOFRANGE infir +@cindex reading input files @cindex input files, reading @cindex input files @cindex @code{FILENAME} variable @@ -5446,68 +5467,79 @@ To do this, use the special @code{BEGIN} pattern (@pxref{BEGIN/END}). For example: -@cindex @code{BEGIN} pattern @example -awk 'BEGIN @{ RS = "/" @} - @{ print $0 @}' BBS-list +awk 'BEGIN @{ RS = "u" @} + @{ print $0 @}' mail-list @end example @noindent -changes the value of @code{RS} to @code{"/"}, before reading any input. -This is a string whose first character is a slash; as a result, records -are separated by slashes. Then the input file is read, and the second +changes the value of @code{RS} to @samp{u}, before reading any input. +This is a string whose first character is the letter ``u;'' as a result, records +are separated by the letter ``u.'' Then the input file is read, and the second rule in the @command{awk} program (the action with no pattern) prints each record. Because each @code{print} statement adds a newline at the end of its output, this @command{awk} program copies the input -with each slash changed to a newline. Here are the results of running -the program on @file{BBS-list}: - -@example -$ @kbd{awk 'BEGIN @{ RS = "/" @}} -> @kbd{@{ print $0 @}' BBS-list} -@print{} aardvark 555-5553 1200 -@print{} 300 B -@print{} alpo-net 555-3412 2400 -@print{} 1200 -@print{} 300 A -@print{} barfly 555-7685 1200 -@print{} 300 A -@print{} bites 555-1675 2400 -@print{} 1200 -@print{} 300 A -@print{} camelot 555-0542 300 C -@print{} core 555-2912 1200 -@print{} 300 C -@print{} fooey 555-1234 2400 -@print{} 1200 -@print{} 300 B -@print{} foot 555-6699 1200 -@print{} 300 B -@print{} macfoo 555-6480 1200 -@print{} 300 A -@print{} sdace 555-3430 2400 -@print{} 1200 -@print{} 300 A -@print{} sabafoo 555-2127 1200 -@print{} 300 C -@print{} +with each @samp{u} changed to a newline. Here are the results of running +the program on @file{mail-list}: + +@example +$ @kbd{awk 'BEGIN @{ RS = "u" @}} +> @kbd{@{ print $0 @}' mail-list} +@print{} Amelia 555-5553 amelia.zodiac +@print{} sq +@print{} e@@gmail.com F +@print{} Anthony 555-3412 anthony.assert +@print{} ro@@hotmail.com A +@print{} Becky 555-7685 becky.algebrar +@print{} m@@gmail.com A +@print{} Bill 555-1675 bill.drowning@@hotmail.com A +@print{} Broderick 555-0542 broderick.aliq +@print{} otiens@@yahoo.com R +@print{} Camilla 555-2912 camilla.inf +@print{} sar +@print{} m@@skynet.be R +@print{} Fabi +@print{} s 555-1234 fabi +@print{} s. +@print{} ndevicesim +@print{} s@@ +@print{} cb.ed +@print{} F +@print{} J +@print{} lie 555-6699 j +@print{} lie.perscr +@print{} tabor@@skeeve.com F +@print{} Martin 555-6480 martin.codicib +@print{} s@@hotmail.com A +@print{} Sam +@print{} el 555-3430 sam +@print{} el.lanceolis@@sh +@print{} .ed +@print{} A +@print{} Jean-Pa +@print{} l 555-2127 jeanpa +@print{} l.campanor +@print{} m@@ny +@print{} .ed +@print{} R +@print{} @end example @noindent -Note that the entry for the @samp{camelot} BBS is not split. +Note that the entry for the name @samp{Bill} is not split. In the original data file (@pxref{Sample Data Files}), the line looks like this: @example -camelot 555-0542 300 C +Bill 555-1675 bill.drowning@@hotmail.com A @end example @noindent -It has one baud rate only, so there are no slashes in the record, -unlike the others which have two or more baud rates. -In fact, this record is treated as part of the record -for the @samp{core} BBS; the newline separating them in the output +It contains no @samp{u} so there is no reason to split the record, +unlike the others which have one or more occurrences of the @samp{u}. +In fact, this record is treated as part of the previous record; +the newline separating them in the output is the original newline in the data file, not the one added by @command{awk} when it printed the record! @@ -5518,14 +5550,17 @@ using the variable-assignment feature (@pxref{Other Arguments}): @example -awk '@{ print $0 @}' RS="/" BBS-list +awk '@{ print $0 @}' RS="u" mail-list @end example @noindent -This sets @code{RS} to @samp{/} before processing @file{BBS-list}. +This sets @code{RS} to @samp{u} before processing @file{mail-list}. -Using an unusual character such as @samp{/} for the record separator -produces correct behavior in the vast majority of cases. +Using an alphabetic character such as @samp{u} for the record separator +is highly likely to produce strange results. +Using an unusual character such as @samp{/} is more likely to +produce correct behavior in the majority of cases, but there +are no guarantees. The moral is: Know Your Data. There is one unusual case, that occurs when @command{gawk} is being fully POSIX-compliant (@pxref{Options}). @@ -5547,6 +5582,7 @@ Reaching the end of an input file terminates the current input record, even if the last character in the file is not the character in @code{RS}. @value{DARKCORNER} +@cindex empty strings @cindex null strings @cindex strings, empty, See null strings The empty string @code{""} (a string without any characters) @@ -5678,7 +5714,7 @@ character as a record separator. However, this is a special case: @command{mawk} does not allow embedded @sc{nul} characters in strings. @cindex records, treating files as -@cindex files, as single records +@cindex treating files, as single records The best way to treat a whole file as a single record is to simply read the file in, one record at a time, concatenating each record onto the end of the previous ones. @@ -5755,31 +5791,29 @@ when you are not interested in specific fields. Here are some more examples: @example -$ @kbd{awk '$1 ~ /foo/ @{ print $0 @}' BBS-list} -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sabafoo 555-2127 1200/300 C +$ @kbd{awk '$1 ~ /li/ @{ print $0 @}' mail-list} +@print{} Amelia 555-5553 amelia.zodiacusque@@gmail.com F +@print{} Julie 555-6699 julie.perscrutabor@@skeeve.com F @end example @noindent -This example prints each record in the file @file{BBS-list} whose first -field contains the string @samp{foo}. The operator @samp{~} is called a +This example prints each record in the file @file{mail-list} whose first +field contains the string @samp{li}. The operator @samp{~} is called a @dfn{matching operator} (@pxref{Regexp Usage}); it tests whether a string (here, the field @code{$1}) matches a given regular expression. By contrast, the following example -looks for @samp{foo} in @emph{the entire record} and prints the first +looks for @samp{li} in @emph{the entire record} and prints the first field and the last field for each matching input record: @example -$ @kbd{awk '/foo/ @{ print $1, $NF @}' BBS-list} -@print{} fooey B -@print{} foot B -@print{} macfoo A -@print{} sabafoo C +$ @kbd{awk '/li/ @{ print $1, $NF @}' mail-list} +@print{} Amelia F +@print{} Broderick R +@print{} Julie F +@print{} Samuel A @end example @c ENDOFRANGE fiex @@ -5807,7 +5841,7 @@ the record has fewer than 20 fields, so this prints a blank line. Here is another example of using expressions as field numbers: @example -awk '@{ print $(2*2) @}' BBS-list +awk '@{ print $(2*2) @}' mail-list @end example @command{awk} evaluates the expression @samp{(2*2)} and uses @@ -5816,8 +5850,8 @@ represents multiplication, so the expression @samp{2*2} evaluates to four. The parentheses are used so that the multiplication is done before the @samp{$} operation; they are 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 -@file{BBS-list}. (All of the @command{awk} operators are listed, in +type of relationship (the fourth field) for every line of the file +@file{mail-list}. (All of the @command{awk} operators are listed, in order of decreasing precedence, in @ref{Precedence}.) @@ -6295,10 +6329,8 @@ behaves this way. @node Command Line Field Separator @subsection Setting @code{FS} from the Command Line -@cindex @option{-F} option -@cindex options, command-line -@cindex command line, options -@cindex field separators, on command line +@cindex @option{-F} option, command line +@cindex field separator, on command line @cindex command line, @code{FS} on@comma{} setting @cindex @code{FS} variable, setting from command line @@ -6348,66 +6380,59 @@ figures that you really want your fields to be separated with TABs and not @samp{t}s. Use @samp{-v FS="t"} or @samp{-F"[t]"} on the command line if you really do want to separate your fields with @samp{t}s. -As an example, let's use an @command{awk} program file called @file{baud.awk} -that contains the pattern @code{/300/} and the action @samp{print $1}: +As an example, let's use an @command{awk} program file called @file{edu.awk} +that contains the pattern @code{/edu/} and the action @samp{print $1}: @example -/300/ @{ print $1 @} +/edu/ @{ print $1 @} @end example Let's also set @code{FS} to be the @samp{-} character and run the -program on the file @file{BBS-list}. The following command prints a -list of the names of the bulletin boards that operate at 300 baud and +program on the file @file{mail-list}. The following command prints a +list of the names of the people that work at or attend a university, and the first three digits of their phone numbers: @c tweaked to make the tex output look better in @smallbook @example -$ @kbd{awk -F- -f baud.awk BBS-list} -@print{} aardvark 555 -@print{} alpo -@print{} barfly 555 -@print{} bites 555 -@print{} camelot 555 -@print{} core 555 -@print{} fooey 555 -@print{} foot 555 -@print{} macfoo 555 -@print{} sdace 555 -@print{} sabafoo 555 +$ @kbd{awk -F- -f edu.awk mail-list} +@print{} Fabius 555 +@print{} Samuel 555 +@print{} Jean @end example @noindent -Note the second line of output. The second line +Note the third line of output. The third line in the original file looked like this: @example -alpo-net 555-3412 2400/1200/300 A +Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example -The @samp{-} as part of the system's name was used as the field +The @samp{-} as part of the person's name was used as the field separator, instead of the @samp{-} in the phone number that was originally intended. This demonstrates why you have to be careful in choosing your field and record separators. @cindex Unix @command{awk}, password files@comma{} field separators and -Perhaps the most common use of a single character as the field -separator occurs when processing the Unix system password file. -On many Unix systems, each user has a separate entry in the system password -file, one line per user. The information in these lines is separated -by colons. The first field is the user's login name and the second is -the user's (encrypted or shadow) password. A password file entry might look -like this: +Perhaps the most common use of a single character as the field separator +occurs when processing the Unix system password file. On many Unix +systems, each user has a separate entry in the system password file, one +line per user. The information in these lines is separated by colons. +The first field is the user's login name and the second is the user's +encrypted or shadow password. (A shadow password is indicated by the +presence of a single @samp{x} in the second field.) A password file +entry might look like this: @cindex Robbins, Arnold @example -arnold:xyzzy:2076:10:Arnold Robbins:/home/arnold:/bin/bash +arnold:x:2076:10:Arnold Robbins:/home/arnold:/bin/bash @end example The following program searches the system password file and prints -the entries for users who have no password: +the entries for users whose full name is not indicated: @example -awk -F: '$2 == ""' /etc/passwd +awk -F: '$5 == ""' /etc/passwd @end example @node Full Line Fields @@ -6465,7 +6490,7 @@ POSIX standard.) @sidebar Changing @code{FS} Does Not Affect the Fields @cindex POSIX @command{awk}, field separators and -@cindex field separators, POSIX and +@cindex field separator, POSIX and According to the POSIX standard, @command{awk} is supposed to behave as if each record is split into fields at the time it is read. In particular, this means that if you change the value of @code{FS} @@ -6788,6 +6813,7 @@ available for splitting regular strings (@pxref{String Functions}). @node Multiple Line @section Multiple-Line Records +@cindex multiple-line records @c STARTOFRANGE recm @cindex records, multiline @c STARTOFRANGE imr @@ -6839,7 +6865,8 @@ after the last record, the final newline is removed from the record. In the second case, this special processing is not done. @value{DARKCORNER} -@cindex field separators, in multiline records +@cindex field separator, in multiline records +@cindex @code{FS}, in multiline records Now that the input is separated into records, the second step is to separate the fields in the record. One way to do this is to divide each of the lines into fields in the normal manner. This happens by default @@ -6987,7 +7014,7 @@ and study the @code{getline} command @emph{after} you have reviewed the rest of this @value{DOCUMENT} and have a good knowledge of how @command{awk} works. @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @command{getline} command @cindex differences in @command{awk} and @command{gawk}, @code{getline} command @cindex @code{getline} command, return values @cindex @option{--sandbox} option, input redirection with @code{getline} @@ -7083,6 +7110,7 @@ rule in the program. @xref{Next Statement}. @node Getline/Variable @subsection Using @code{getline} into a Variable +@cindex @code{getline} into a variable @cindex variables, @code{getline} command into@comma{} using You can use @samp{getline @var{var}} to read the next record from @@ -7134,6 +7162,7 @@ the value of @code{NF} do not change. @node Getline/File @subsection Using @code{getline} from a File +@cindex @code{getline} from a file @cindex input redirection @cindex redirection of input @cindex @code{<} (left angle bracket), @code{<} operator (I/O) @@ -7182,8 +7211,6 @@ from the file @var{file}, and put it in the variable @var{var}. As above, @var{file} is a string-valued expression that specifies the file from which to read. -@cindex @command{gawk}, @code{RT} variable in -@cindex @code{RT} variable In this version of @code{getline}, none of the built-in variables are changed and the record is not split into fields. The only variable changed is @var{var}.@footnote{This is not quite true. @code{RT} could @@ -7208,7 +7235,6 @@ Note here how the name of the extra input file is not built into the program; it is taken directly from the data, specifically from the second field on the @samp{@@include} line. -@cindex @code{close()} function The @code{close()} function is called to ensure that if two identical @samp{@@include} lines appear in the input, the entire specified file is included twice. @@ -7235,7 +7261,7 @@ Failing that, attention to details would be useful.} @cindex @code{|} (vertical bar), @code{|} operator (I/O) @cindex vertical bar (@code{|}), @code{|} operator (I/O) @cindex input pipeline -@cindex pipes, input +@cindex pipe, input @cindex operators, input/output The output of a command can also be piped into @code{getline}, using @samp{@var{command} | getline}. In @@ -7259,7 +7285,6 @@ produced by running the rest of the line as a shell command: @end example @noindent -@cindex @code{close()} function The @code{close()} function is called to ensure that if two identical @samp{@@execute} lines appear in the input, the command is run for each one. @@ -7883,13 +7908,29 @@ program by using a new value of @code{OFS}. @example $ @kbd{awk 'BEGIN @{ OFS = ";"; ORS = "\n\n" @}} -> @kbd{@{ print $1, $2 @}' BBS-list} -@print{} aardvark;555-5553 -@print{} -@print{} alpo-net;555-3412 -@print{} -@print{} barfly;555-7685 -@dots{} +> @kbd{@{ print $1, $2 @}' mail-list} +@print{} Amelia;555-5553 +@print{} +@print{} Anthony;555-3412 +@print{} +@print{} Becky;555-7685 +@print{} +@print{} Bill;555-1675 +@print{} +@print{} Broderick;555-0542 +@print{} +@print{} Camilla;555-2912 +@print{} +@print{} Fabius;555-1234 +@print{} +@print{} Julie;555-6699 +@print{} +@print{} Martin;555-6480 +@print{} +@print{} Samuel;555-3430 +@print{} +@print{} Jean-Paul;555-2127 +@print{} @end example If the value of @code{ORS} does not contain a newline, the program's output @@ -7911,7 +7952,7 @@ numbers can be formatted. The different format specifications are discussed more fully in @ref{Control Letters}. -@cindex @code{sprintf()} function +@cindexawkfunc{sprintf} @cindex @code{OFMT} variable @cindex output, format specifier@comma{} @code{OFMT} The built-in variable @code{OFMT} contains the default format specification @@ -8363,30 +8404,30 @@ The following simple example shows how to use @code{printf} to make an aligned table: @example -awk '@{ printf "%-10s %s\n", $1, $2 @}' BBS-list +awk '@{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example @noindent This command -prints the names of the bulletin boards (@code{$1}) in the file -@file{BBS-list} as a string of 10 characters that are left-justified. It also +prints the names of the people (@code{$1}) in the file +@file{mail-list} as a string of 10 characters that are left-justified. It also prints the phone numbers (@code{$2}) next on the line. This produces an aligned two-column table of names and phone numbers, as shown here: @example -$ @kbd{awk '@{ printf "%-10s %s\n", $1, $2 @}' BBS-list} -@print{} aardvark 555-5553 -@print{} alpo-net 555-3412 -@print{} barfly 555-7685 -@print{} bites 555-1675 -@print{} camelot 555-0542 -@print{} core 555-2912 -@print{} fooey 555-1234 -@print{} foot 555-6699 -@print{} macfoo 555-6480 -@print{} sdace 555-3430 -@print{} sabafoo 555-2127 +$ @kbd{awk '@{ printf "%-10s %s\n", $1, $2 @}' mail-list} +@print{} Amelia 555-5553 +@print{} Anthony 555-3412 +@print{} Becky 555-7685 +@print{} Bill 555-1675 +@print{} Broderick 555-0542 +@print{} Camilla 555-2912 +@print{} Fabius 555-1234 +@print{} Julie 555-6699 +@print{} Martin 555-6480 +@print{} Samuel 555-3430 +@print{} Jean-Paul 555-2127 @end example In this case, the phone numbers had to be printed as strings because @@ -8407,7 +8448,7 @@ the @command{awk} program: @example awk 'BEGIN @{ print "Name Number" print "---- ------" @} - @{ printf "%-10s %s\n", $1, $2 @}' BBS-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example The above example mixes @code{print} and @code{printf} statements in @@ -8417,7 +8458,7 @@ same results: @example awk 'BEGIN @{ printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" @} - @{ printf "%-10s %s\n", $1, $2 @}' BBS-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example @noindent @@ -8432,7 +8473,7 @@ emphasized by storing it in a variable, like this: awk 'BEGIN @{ format = "%-10s %s\n" printf format, "Name", "Number" printf format, "----", "------" @} - @{ printf format, $1, $2 @}' BBS-list + @{ printf format, $1, $2 @}' mail-list @end example @c !!! exercise @@ -8489,20 +8530,20 @@ before the first output is written to it. Subsequent writes to the same @var{output-file} do not erase @var{output-file}, but append to it. (This is different from how you use redirections in shell scripts.) If @var{output-file} does not exist, it is created. For example, here -is how an @command{awk} program can write a list of BBS names to one +is how an @command{awk} program can write a list of peoples' names to one file named @file{name-list}, and a list of phone numbers to another file named @file{phone-list}: @example $ @kbd{awk '@{ print $2 > "phone-list"} -> @kbd{print $1 > "name-list" @}' BBS-list} +> @kbd{print $1 > "name-list" @}' mail-list} $ @kbd{cat phone-list} @print{} 555-5553 @print{} 555-3412 @dots{} $ @kbd{cat name-list} -@print{} aardvark -@print{} alpo-net +@print{} Amelia +@print{} Anthony @dots{} @end example @@ -8520,7 +8561,7 @@ appended to the file. If @var{output-file} does not exist, then it is created. @cindex @code{|} (vertical bar), @code{|} operator (I/O) -@cindex pipes, output +@cindex pipe, output @cindex output, pipes @item print @var{items} | @var{command} It is possible to send output to another program through a pipe @@ -8531,7 +8572,7 @@ to another process created to execute @var{command}. The redirection argument @var{command} is actually an @command{awk} expression. Its value is converted to a string whose contents give the shell command to be run. For example, the following produces two -files, one unsorted list of BBS names, and one list sorted in reverse +files, one unsorted list of peoples' names, and one list sorted in reverse alphabetical order: @ignore @@ -8544,7 +8585,7 @@ alone for now and let's hope no-one notices. @example awk '@{ print $1 > "names.unsorted" command = "sort -r > names.sorted" - print $1 | command @}' BBS-list + print $1 | command @}' mail-list @end example The unsorted list is written with an ordinary redirection, while @@ -8857,7 +8898,7 @@ Doing so results in unpredictable behavior. @c STARTOFRANGE ofc @cindex output, files@comma{} closing @c STARTOFRANGE pc -@cindex pipes, closing +@cindex pipe, closing @c STARTOFRANGE cc @cindex coprocesses, closing @cindex @code{getline} command, coprocesses@comma{} using from @@ -8875,7 +8916,7 @@ the file name or command associated with it, and subsequent writes to the same file or command are appended to the previous writes. The file or pipe stays open until @command{awk} exits. -@cindex @code{close()} function +@cindexawkfunc{close} This implies that special steps are necessary in order to read the same file again from the beginning, or to rerun a shell command (rather than reading more output from the same command). The @code{close()} function @@ -8960,6 +9001,7 @@ a separate message. @cindex differences in @command{awk} and @command{gawk}, @code{close()} function @cindex portability, @code{close()} function and +@cindex @code{close()} function, portability If you use more files than the system allows you to have open, @command{gawk} attempts to multiplex the available open files among your data files. @command{gawk}'s ability to do this depends upon the @@ -9039,7 +9081,7 @@ retval = close(command) # syntax error in many Unix awks @end example @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @command{close()} function @command{gawk} treats @code{close()} as a function. The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is @@ -9138,7 +9180,8 @@ have different forms, but are stored identically internally. @node Scalar Constants @subsubsection Numeric and String Constants -@cindex numeric, constants +@cindex constants, numeric +@cindex numeric constants A @dfn{numeric constant} stands for a number. This number can be an integer, a decimal fraction, or a number in scientific (exponential) notation.@footnote{The internal representation of all numbers, @@ -9164,7 +9207,7 @@ double-quotation marks. For example: @noindent @cindex differences in @command{awk} and @command{gawk}, strings -@cindex strings, length of +@cindex strings, length limitations represents the string whose contents are @samp{parrot}. Strings in @command{gawk} can be of any length, and they can contain any of the possible eight-bit ASCII characters including ASCII @sc{nul} (character code zero). @@ -9351,9 +9394,9 @@ upon the contents of the current input record. @cindex differences in @command{awk} and @command{gawk}, regexp constants @cindex dark corner, regexp constants, as arguments to user-defined functions -@cindex @code{gensub()} function (@command{gawk}) -@cindex @code{sub()} function -@cindex @code{gsub()} function +@cindexgawkfunc{gensub} +@cindexawkfunc{sub} +@cindexawkfunc{gsub} Constant regular expressions are also used as the first argument for the @code{gensub()}, @code{sub()}, and @code{gsub()} functions, as the second argument of the @code{match()} function, @@ -9486,7 +9529,7 @@ its position among the input file arguments---after the processing of the preceding input file argument. For example: @example -awk '@{ print $n @}' n=4 inventory-shipped n=2 BBS-list +awk '@{ print $n @}' n=4 inventory-shipped n=2 mail-list @end example @noindent @@ -9495,10 +9538,10 @@ the first file is read, the command line sets the variable @code{n} equal to four. This causes the fourth field to be printed in lines from @file{inventory-shipped}. After the first file has finished, but before the second file is started, @code{n} is set to two, so that the -second field is printed in lines from @file{BBS-list}: +second field is printed in lines from @file{mail-list}: @example -$ @kbd{awk '@{ print $n @}' n=4 inventory-shipped n=2 BBS-list} +$ @kbd{awk '@{ print $n @}' n=4 inventory-shipped n=2 mail-list} @print{} 15 @print{} 24 @dots{} @@ -9821,9 +9864,9 @@ specific operator to represent it. Instead, concatenation is performed by writing expressions next to one another, with no operator. For example: @example -$ @kbd{awk '@{ print "Field number one: " $1 @}' BBS-list} -@print{} Field number one: aardvark -@print{} Field number one: alpo-net +$ @kbd{awk '@{ print "Field number one: " $1 @}' mail-list} +@print{} Field number one: Amelia +@print{} Field number one: Anthony @dots{} @end example @@ -9831,9 +9874,9 @@ Without the space in the string constant after the @samp{:}, the line runs together. For example: @example -$ @kbd{awk '@{ print "Field number one:" $1 @}' BBS-list} -@print{} Field number one:aardvark -@print{} Field number one:alpo-net +$ @kbd{awk '@{ print "Field number one:" $1 @}' mail-list} +@print{} Field number one:Amelia +@print{} Field number one:Anthony @dots{} @end example @@ -10796,10 +10839,10 @@ The Boolean operators are: @item @var{boolean1} && @var{boolean2} True if both @var{boolean1} and @var{boolean2} are true. For example, the following statement prints the current input record if it contains -both @samp{2400} and @samp{foo}: +both @samp{edu} and @samp{li}: @example -if ($0 ~ /2400/ && $0 ~ /foo/) print +if ($0 ~ /edu/ && $0 ~ /li/) print @end example @cindex side effects, Boolean operators @@ -10812,11 +10855,11 @@ no substring @samp{foo} in the record. @item @var{boolean1} || @var{boolean2} True if at least one of @var{boolean1} or @var{boolean2} is true. For example, the following statement prints all records in the input -that contain @emph{either} @samp{2400} or -@samp{foo} or both: +that contain @emph{either} @samp{edu} or +@samp{li} or both: @example -if ($0 ~ /2400/ || $0 ~ /foo/) print +if ($0 ~ /edu/ || $0 ~ /li/) print @end example The subexpression @var{boolean2} is evaluated only if @var{boolean1} @@ -11411,7 +11454,7 @@ slashes (@code{/@var{regexp}/}), or any expression whose string value is used as a dynamic regular expression (@pxref{Computed Regexps}). The following example prints the second field of each input record -whose first field is precisely @samp{foo}: +whose first field is precisely @samp{li}: @cindex @code{/} (forward slash), patterns and @cindex forward slash (@code{/}), patterns and @@ -11420,68 +11463,65 @@ whose first field is precisely @samp{foo}: @cindex @code{!} (exclamation point), @code{!~} operator @cindex exclamation point (@code{!}), @code{!~} operator @example -$ @kbd{awk '$1 == "foo" @{ print $2 @}' BBS-list} +$ @kbd{awk '$1 == "li" @{ print $2 @}' mail-list} @end example @noindent -(There is no output, because there is no BBS site with the exact name @samp{foo}.) +(There is no output, because there is no person with the exact name @samp{li}.) Contrast this with the following regular expression match, which -accepts any record with a first field that contains @samp{foo}: +accepts any record with a first field that contains @samp{li}: @example -$ @kbd{awk '$1 ~ /foo/ @{ print $2 @}' BBS-list} -@print{} 555-1234 +$ @kbd{awk '$1 ~ /foo/ @{ print $2 @}' mail-list} +@print{} 555-5553 @print{} 555-6699 -@print{} 555-6480 -@print{} 555-2127 @end example @cindex regexp constants, as patterns @cindex patterns, regexp constants as A regexp constant as a pattern is also a special case of an expression -pattern. The expression @code{/foo/} has the value one if @samp{foo} -appears in the current input record. Thus, as a pattern, @code{/foo/} -matches any record containing @samp{foo}. +pattern. The expression @code{/li/} has the value one if @samp{li} +appears in the current input record. Thus, as a pattern, @code{/li/} +matches any record containing @samp{li}. @cindex Boolean expressions, as patterns Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions match. For example, the following command prints all the records in -@file{BBS-list} that contain both @samp{2400} and @samp{foo}: +@file{mail-list} that contain both @samp{edu} and @samp{li}: @example -$ @kbd{awk '/2400/ && /foo/' BBS-list} -@print{} fooey 555-1234 2400/1200/300 B +$ @kbd{awk '/edu/ && /li/' mail-list} +@print{} Samuel 555-3430 samuel.lanceolis@@shu.edu A @end example The following command prints all records in -@file{BBS-list} that contain @emph{either} @samp{2400} or @samp{foo} +@file{mail-list} that contain @emph{either} @samp{edu} or @samp{li} (or both, of course): @example -$ @kbd{awk '/2400/ || /foo/' BBS-list} -@print{} alpo-net 555-3412 2400/1200/300 A -@print{} bites 555-1675 2400/1200/300 A -@print{} fooey 555-1234 2400/1200/300 B -@print{} foot 555-6699 1200/300 B -@print{} macfoo 555-6480 1200/300 A -@print{} sdace 555-3430 2400/1200/300 A -@print{} sabafoo 555-2127 1200/300 C +$ @kbd{awk '/edu/ || /li/' mail-list} +@print{} Amelia 555-5553 amelia.zodiacusque@@gmail.com F +@print{} Broderick 555-0542 broderick.aliquotiens@@yahoo.com R +@print{} Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +@print{} Julie 555-6699 julie.perscrutabor@@skeeve.com F +@print{} Samuel 555-3430 samuel.lanceolis@@shu.edu A +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example The following command prints all records in -@file{BBS-list} that do @emph{not} contain the string @samp{foo}: +@file{mail-list} that do @emph{not} contain the string @samp{li}: @example -$ @kbd{awk '! /foo/' BBS-list} -@print{} aardvark 555-5553 1200/300 B -@print{} alpo-net 555-3412 2400/1200/300 A -@print{} barfly 555-7685 1200/300 A -@print{} bites 555-1675 2400/1200/300 A -@print{} camelot 555-0542 300 C -@print{} core 555-2912 1200/300 C -@print{} sdace 555-3430 2400/1200/300 A +$ @kbd{awk '! /li/' mail-list} +@print{} Anthony 555-3412 anthony.asserturo@@hotmail.com A +@print{} Becky 555-7685 becky.algebrarum@@gmail.com A +@print{} Bill 555-1675 bill.drowning@@hotmail.com A +@print{} Camilla 555-2912 camilla.infusarum@@skynet.be R +@print{} Fabius 555-1234 fabius.undevicesimus@@ucb.edu F +@print{} Martin 555-6480 martin.codicibus@@hotmail.com A +@print{} Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example @cindex @code{BEGIN} pattern, Boolean patterns and @@ -11614,28 +11654,30 @@ programmers. @node Using BEGIN/END @subsubsection Startup and Cleanup Actions +@cindex @code{BEGIN} pattern +@cindex @code{END} pattern A @code{BEGIN} rule is executed once only, before the first input record is read. Likewise, an @code{END} rule is executed once only, after all the input is read. For example: @example $ @kbd{awk '} -> @kbd{BEGIN @{ print "Analysis of \"foo\"" @}} -> @kbd{/foo/ @{ ++n @}} -> @kbd{END @{ print "\"foo\" appears", n, "times." @}' BBS-list} -@print{} Analysis of "foo" -@print{} "foo" appears 4 times. +> @kbd{BEGIN @{ print "Analysis of \"li\"" @}} +> @kbd{/li/ @{ ++n @}} +> @kbd{END @{ print "\"li\" appears in", n, "records." @}' mail-list} +@print{} Analysis of "li" +@print{} "li" appears in 4 records. @end example @cindex @code{BEGIN} pattern, operators and @cindex @code{END} pattern, operators and -This program finds the number of records in the input file @file{BBS-list} -that contain the string @samp{foo}. The @code{BEGIN} rule prints a title +This program finds the number of records in the input file @file{mail-list} +that contain the string @samp{li}. The @code{BEGIN} rule prints a title for the report. There is no need to use the @code{BEGIN} rule to initialize the counter @code{n} to zero, since @command{awk} does this automatically (@pxref{Variables}). The second rule increments the variable @code{n} every time a -record containing the pattern @samp{foo} is read. The @code{END} rule +record containing the pattern @samp{li} is read. The @code{END} rule prints the value of @code{n} at the end of the run. The special patterns @code{BEGIN} and @code{END} cannot be used in ranges @@ -11757,7 +11799,7 @@ you can bypass the fatal error and move on to the next file on the command line. @cindex @command{gawk}, @code{ERRNO} variable in -@cindex @code{ERRNO} variable +@cindex @code{ERRNO} variable, with @code{BEGINFILE} pattern @cindex @code{nextfile} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and You do this by checking if the @code{ERRNO} variable is not the empty string; if so, then @command{gawk} was not able to open the file. In @@ -11799,7 +11841,7 @@ both @code{BEGINFILE} and @code{ENDFILE}. Only the @samp{getline In most other @command{awk} implementations, or if @command{gawk} is in compatibility mode (@pxref{Options}), they are not special. -@c FIXME: For 4.1 maybe deal with this? +@c FIXME: For 4.2 maybe deal with this? @ignore Date: Tue, 17 May 2011 02:06:10 PDT From: rankin@pactechdata.com (Pat Rankin) @@ -11830,7 +11872,7 @@ An empty (i.e., nonexistent) pattern is considered to match @emph{every} input record. For example, the program: @example -awk '@{ print $1 @}' BBS-list +awk '@{ print $1 @}' mail-list @end example @noindent @@ -12866,8 +12908,8 @@ is to simply say @samp{FS = FS}, perhaps with an explanatory comment. @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable @cindex differences in @command{awk} and @command{gawk}, @code{IGNORECASE} variable -@cindex case sensitivity, string comparisons and -@cindex case sensitivity, regexps and +@cindex case sensitivity, and string comparisons +@cindex case sensitivity, and regexps @cindex regular expressions, case sensitivity @item IGNORECASE # If @code{IGNORECASE} is nonzero or non-null, then all string comparisons @@ -13032,16 +13074,16 @@ In the following example: $ @kbd{awk 'BEGIN @{} > @kbd{for (i = 0; i < ARGC; i++)} > @kbd{print ARGV[i]} -> @kbd{@}' inventory-shipped BBS-list} +> @kbd{@}' inventory-shipped mail-list} @print{} awk @print{} inventory-shipped -@print{} BBS-list +@print{} mail-list @end example @noindent @code{ARGV[0]} contains @samp{awk}, @code{ARGV[1]} contains @samp{inventory-shipped}, and @code{ARGV[2]} contains -@samp{BBS-list}. The value of @code{ARGC} is three, one more than the +@samp{mail-list}. The value of @code{ARGC} is three, one more than the index of the last element in @code{ARGV}, because the elements are numbered from zero. @@ -13084,7 +13126,7 @@ or if @command{gawk} is in compatibility mode it is not special. @cindex @code{ENVIRON} array -@cindex environment variables +@cindex environment variables, in @code{ENVIRON} array @item ENVIRON An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of @@ -13207,10 +13249,12 @@ The following elements (listed alphabetically) are guaranteed to be available: @table @code +@cindex effective group id of @command{gawk} user @item PROCINFO["egid"] The value of the @code{getegid()} system call. @item PROCINFO["euid"] +@cindex effective user id of @command{gawk} user The value of the @code{geteuid()} system call. @item PROCINFO["FS"] @@ -13220,6 +13264,7 @@ This is or @code{"FPAT"} if field matching with @code{FPAT} is in effect. @item PROCINFO["identifiers"] +@cindex program identifiers A subarray, indexed by the names of all identifiers used in the text of the AWK program. For each identifier, the value of the element is one of the following: @@ -13248,15 +13293,19 @@ after it has finished parsing the program; they are @emph{not} updated while the program runs. @item PROCINFO["gid"] +@cindex group id of @command{gawk} user The value of the @code{getgid()} system call. @item PROCINFO["pgrpid"] +@cindex process group id of @command{gawk} process The process group ID of the current process. @item PROCINFO["pid"] +@cindex process id of @command{gawk} process The process ID of the current process. @item PROCINFO["ppid"] +@cindex parent process id of @command{gawk} process The parent process ID of the current process. @item PROCINFO["sorted_in"] @@ -13276,25 +13325,31 @@ Assigning a new value to this element changes the default. The value of the @code{getuid()} system call. @item PROCINFO["version"] +@cindex version of @command{gawk} +@cindex @command{gawk} version The version of @command{gawk}. @end table The following additional elements in the array are available to provide information about the MPFR and GMP libraries if your version of @command{gawk} supports arbitrary precision numbers -(@pxref{Arbitrary Precision Arithmetic}): +(@pxref{Gawk and MPFR}): @table @code +@cindex version of GNU MPFR library @item PROCINFO["mpfr_version"] The version of the GNU MPFR library. @item PROCINFO["gmp_version"] +@cindex version of GNU MP library The version of the GNU MP library. @item PROCINFO["prec_max"] +@cindex maximum precision supported by MPFR library The maximum precision supported by MPFR. @item PROCINFO["prec_min"] +@cindex minimum precision supported by MPFR library The minimum precision required by MPFR. @end table @@ -13305,12 +13360,15 @@ of @command{gawk} supports dynamic loading of extension functions @table @code @item PROCINFO["api_major"] +@cindex version of @command{gawk} extension API +@cindex extension API, version number The major version of the extension API. @item PROCINFO["api_minor"] The minor version of the extension API. @end table +@cindex supplementary groups of @command{gawk} process On some systems, there may be elements in the array, @code{"group1"} through @code{"group@var{N}"} for some @var{N}. @var{N} is the number of supplementary groups that the process has. Use the @code{in} operator @@ -13318,7 +13376,7 @@ to test for these elements (@pxref{Reference to Elements}). @cindex @command{gawk}, @code{PROCINFO} array in -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, uses The @code{PROCINFO} array has the following additional uses: @itemize @bullet @@ -13458,7 +13516,7 @@ changed. @node ARGC and ARGV @subsection Using @code{ARGC} and @code{ARGV} -@cindex @code{ARGC}/@code{ARGV} variables +@cindex @code{ARGC}/@code{ARGV} variables, how to use @cindex arguments, command-line @cindex command line, arguments @@ -13470,16 +13528,16 @@ and @code{ARGV}: $ @kbd{awk 'BEGIN @{} > @kbd{for (i = 0; i < ARGC; i++)} > @kbd{print ARGV[i]} -> @kbd{@}' inventory-shipped BBS-list} +> @kbd{@}' inventory-shipped mail-list} @print{} awk @print{} inventory-shipped -@print{} BBS-list +@print{} mail-list @end example @noindent In this example, @code{ARGV[0]} contains @samp{awk}, @code{ARGV[1]} contains @samp{inventory-shipped}, and @code{ARGV[2]} contains -@samp{BBS-list}. +@samp{mail-list}. Notice that the @command{awk} program is not entered in @code{ARGV}. The other command-line options, with their arguments, are also not entered. This includes variable assignments done with the @option{-v} @@ -13603,7 +13661,7 @@ ability to support true multidimensional arrays. @cindex variables, names of @cindex functions, names of -@cindex arrays, names of +@cindex arrays, names of, and names of functions/variables @cindex names, arrays/variables @cindex namespace issues @command{awk} maintains a single set @@ -13779,10 +13837,9 @@ Here, the number @code{1} isn't double-quoted, since @command{awk} automatically converts it to a string. @cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex @code{IGNORECASE} variable @cindex case sensitivity, array indices and -@cindex arrays, @code{IGNORECASE} variable and -@cindex @code{IGNORECASE} variable, array subscripts and +@cindex arrays, and @code{IGNORECASE} variable +@cindex @code{IGNORECASE} variable, and array indices The value of @code{IGNORECASE} has no effect upon array subscripting. The identical string value used to store an array element must be used to retrieve it. @@ -13798,8 +13855,9 @@ is independent of the number of elements in the array. @node Reference to Elements @subsection Referring to an Array Element -@cindex arrays, elements, referencing -@cindex elements in arrays +@cindex arrays, referencing elements +@cindex array members +@cindex elements of arrays The principal way to use an array is to refer to one of its elements. An array reference is an expression as follows: @@ -13816,11 +13874,16 @@ The value of the array reference is the current value of that array element. For example, @code{foo[4.3]} is an expression for the element of array @code{foo} at index @samp{4.3}. +@cindex arrays, unassigned elements +@cindex unassigned array elements +@cindex empty array elements A reference to an array element that has no recorded value yields a value of @code{""}, the null string. This includes elements that have not been assigned any value as well as elements that have been deleted (@pxref{Delete}). +@cindex non-existent array elements +@cindex arrays, elements that don't exist @quotation NOTE A reference to an element that does not exist @emph{automatically} creates that array element, with the null string as its value. (In some cases, @@ -13840,7 +13903,7 @@ if it didn't exist before! @end quotation @c @cindex arrays, @code{in} operator and -@cindex @code{in} operator +@cindex @code{in} operator, testing if array element exists To determine whether an element exists in an array at a certain index, use the following expression: @@ -13875,8 +13938,8 @@ if (frequencies[2] != "") @node Assigning Elements @subsection Assigning Array Elements -@cindex arrays, elements, assigning -@cindex elements in arrays, assigning +@cindex arrays, elements, assigning values +@cindex elements in arrays, assigning values Array elements can be assigned values just like @command{awk} variables: @@ -13893,6 +13956,7 @@ assign to that element of the array. @node Array Example @subsection Basic Array Example +@cindex arrays, an example of using The following program takes a list of lines, each beginning with a line number, and prints them out in order of line number. The line numbers @@ -13962,6 +14026,7 @@ END @{ @node Scanning an Array @subsection Scanning All Elements of an Array @cindex elements in arrays, scanning +@cindex scanning arrays @cindex arrays, scanning @cindex loops, @code{for}, array scanning @@ -13980,7 +14045,7 @@ for (@var{var} in @var{array}) @end example @noindent -@cindex @code{in} operator +@cindex @code{in} operator, use in loops This loop executes @var{body} once for each index in @var{array} that the program has previously used, with the variable @var{var} set to that index. @@ -14019,8 +14084,9 @@ END @{ @xref{Word Sorting}, for a more detailed example of this type. -@cindex arrays, elements, order of -@cindex elements in arrays, order of +@cindex arrays, elements, order of access by @code{in} operator +@cindex elements in arrays, order of access by @code{in} operator +@cindex @code{in} operator, order of array access The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array elements within @command{awk} and normally cannot be controlled or changed. This can lead to @@ -14038,6 +14104,8 @@ determines the order in which the array is traversed. This order is usually based on the internal implementation of arrays and will vary from one version of @command{awk} to the next. +@cindex array scanning order, controlling +@cindex controlling array scanning order Often, though, you may wish to do something simple, such as ``traverse the array by comparing the indices in ascending order,'' or ``traverse the array by comparing the values in descending order.'' @@ -14054,6 +14122,7 @@ to use for comparison of array elements. This advanced feature is described later, in @ref{Array Sorting}. @end itemize +@cindex @code{PROCINFO}, values of @code{sorted_in} The following special values for @code{PROCINFO["sorted_in"]} are available: @table @code @@ -14214,7 +14283,7 @@ if (4 in foo) print "This will never be printed" @end example -@cindex null strings, array elements and +@cindex null strings, and deleting array elements It is important to note that deleting an element is @emph{not} the same as assigning it a null value (the empty string, @code{""}). For example: @@ -14236,6 +14305,7 @@ is not in the array is deleted. @cindex extensions, common@comma{} @code{delete} to delete entire arrays @cindex arrays, deleting entire contents @cindex deleting entire arrays +@cindex @code{delete} @var{array} @cindex differences in @command{awk} and @command{gawk}, array elements, deleting All the elements of an array may be deleted with a single statement by leaving off the subscript in the @code{delete} statement, @@ -14293,9 +14363,9 @@ a = 3 @section Using Numbers to Subscript Arrays @cindex numbers, as array subscripts -@cindex arrays, subscripts +@cindex arrays, numeric subscripts @cindex subscripts in arrays, numbers as -@cindex @code{CONVFMT} variable, array subscripts and +@cindex @code{CONVFMT} variable, and array subscripts An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting @@ -14325,7 +14395,8 @@ string value from @code{xyz}---this time @code{"12.15"}---because the value of @code{CONVFMT} only allows two significant digits. This test fails, since @code{"12.15"} is different from @code{"12.153"}. -@cindex converting, during subscripting +@cindex converting integer array subscripts +@cindex integer array indices According to the rules for conversions (@pxref{Conversion}), integer values are always converted to strings as integers, no matter what the @@ -14431,7 +14502,7 @@ languages, including @command{awk}) to refer to an element of a two-dimensional array named @code{grid} is with @code{grid[@var{x},@var{y}]}. -@cindex @code{SUBSEP} variable, multidimensional arrays +@cindex @code{SUBSEP} variable, and multidimensional arrays Multidimensional arrays are supported in @command{awk} through concatenation of indices into one string. @command{awk} converts the indices into strings @@ -14463,6 +14534,7 @@ combined strings that are ambiguous. Suppose that @code{SUBSEP} is "b@@c"]}} are indistinguishable because both are actually stored as @samp{foo["a@@b@@c"]}. +@cindex @code{in} operator, index existence in multidimensional arrays To test whether a particular index sequence exists in a multidimensional array, use the same operator (@code{in}) that is used for single dimensional arrays. Write the whole sequence of indices @@ -14528,6 +14600,7 @@ multidimensional @emph{way of accessing} an array. @cindex subscripts in arrays, multidimensional, scanning @cindex arrays, multidimensional, scanning +@cindex scanning multidimensional arrays 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 @code{for} statement @@ -14569,6 +14642,7 @@ separate indices is recovered. @node Arrays of Arrays @section Arrays of Arrays +@cindex arrays of arrays @command{gawk} goes beyond standard @command{awk}'s multidimensional array access and provides true arrays of @@ -14828,6 +14902,7 @@ two arguments 11 and 10. @node Numeric Functions @subsection Numeric Functions +@cindex numeric functions The following list describes all of the built-in functions that work with numbers. @@ -14836,21 +14911,25 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):} @table @code @item atan2(@var{y}, @var{x}) @cindex @code{atan2()} function +@cindex arctangent Return the arctangent of @code{@var{y} / @var{x}} in radians. You can use @samp{pi = atan2(0, -1)} to retrieve the value of @value{PI}. @item cos(@var{x}) -@cindex @code{cos()} function +@cindexawkfunc{cos} +@cindex cosine Return the cosine of @var{x}, with @var{x} in radians. @item exp(@var{x}) -@cindex @code{exp()} function +@cindexawkfunc{exp} +@cindex exponent Return the exponential of @var{x} (@code{e ^ @var{x}}) or report an error if @var{x} is out of range. The range of values @var{x} can have depends on your machine's floating-point representation. @item int(@var{x}) -@cindex @code{int()} function +@cindexawkfunc{int} +@cindex round to nearest integer Return the nearest integer to @var{x}, located between @var{x} and zero and truncated toward zero. @@ -14858,12 +14937,13 @@ For example, @code{int(3)} is 3, @code{int(3.9)} is 3, @code{int(-3.9)} is @minus{}3, and @code{int(-3)} is @minus{}3 as well. @item log(@var{x}) -@cindex @code{log()} function +@cindexawkfunc{log} +@cindex logarithm Return the natural logarithm of @var{x}, if @var{x} is positive; otherwise, report an error. @item rand() -@cindex @code{rand()} function +@cindexawkfunc{rand} @cindex random numbers, @code{rand()}/@code{srand()} functions Return a random number. The values of @code{rand()} are uniformly distributed between zero and one. @@ -14905,7 +14985,7 @@ function roll(n) @{ return 1 + int(rand() * n) @} @} @end example -@cindex numbers, random +@cindex seeding random number generator @cindex random numbers, seed of @quotation CAUTION In most @command{awk} implementations, including @command{gawk}, @@ -14921,17 +15001,19 @@ use @code{srand()}. @end quotation @item sin(@var{x}) -@cindex @code{sin()} function +@cindexawkfunc{sin} +@cindex sine Return the sine of @var{x}, with @var{x} in radians. @item sqrt(@var{x}) -@cindex @code{sqrt()} function +@cindexawkfunc{sqrt} +@cindex square root Return the positive square root of @var{x}. @command{gawk} prints a warning message if @var{x} is negative. Thus, @code{sqrt(4)} is 2. @item srand(@r{[}@var{x}@r{]}) -@cindex @code{srand()} function +@cindexawkfunc{srand} Set the starting point, or seed, for generating random numbers to the value @var{x}. @@ -14961,6 +15043,7 @@ sequences of random numbers. @node String Functions @subsection String-Manipulation Functions +@cindex string-manipulation functions The functions in this @value{SECTION} look at or change the text of one or more strings. @@ -14989,11 +15072,11 @@ pound sign@w{ (@samp{#}):} @table @code @item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # @itemx asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # -@cindex @code{asorti()} function (@command{gawk}) +@cindexgawkfunc{asorti} +@cindex sort array @cindex arrays, elements, retrieving number of -@cindex @code{asort()} function (@command{gawk}) -@cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex @code{IGNORECASE} variable +@cindexgawkfunc{asort} +@cindex sort array indices These two functions are similar in behavior, so they are described together. @@ -15011,7 +15094,9 @@ sequential integers starting with one. If the optional array @var{dest} is specified, then @var{source} is duplicated into @var{dest}. @var{dest} is then sorted, leaving the indices of @var{source} unchanged. -When comparing strings, @code{IGNORECASE} affects the sorting. If the +@cindex @command{gawk}, @code{IGNORECASE} variable in +When comparing strings, @code{IGNORECASE} affects the sorting +(@pxref{Array Sorting Functions}). If the @var{source} array contains subarrays as values (@pxref{Arrays of Arrays}), they will come last, after all scalar values. @@ -15054,7 +15139,9 @@ a[3] = "middle" are not available in compatibility mode (@pxref{Options}). @item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) # -@cindex @code{gensub()} function (@command{gawk}) +@cindexgawkfunc{gensub} +@cindex search and replace in strings +@cindex substitute in string Search the target string @var{target} for matches of the regular expression @var{regexp}. If @var{how} is a string beginning with @samp{g} or @samp{G} (short for ``global''), then replace all matches of @var{regexp} with @@ -15063,7 +15150,7 @@ which match of @var{regexp} to replace. If no @var{target} is supplied, use @code{$0}. It returns the modified string as the result of the function and the original target string is @emph{not} changed. -@code{gensub()} is a general substitution function. It's purpose is +@code{gensub()} is a general substitution function. Its purpose is to provide more features than the standard @code{sub()} and @code{gsub()} functions. @@ -15117,7 +15204,7 @@ is the original unchanged value of @var{target}. in compatibility mode (@pxref{Options}). @item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) -@cindex @code{gsub()} function +@cindexawkfunc{gsub} Search @var{target} for @emph{all} of the longest, leftmost, @emph{nonoverlapping} matching substrings it can find and replace them with @var{replacement}. @@ -15139,8 +15226,9 @@ As in @code{sub()}, the characters @samp{&} and @samp{\} are special, and the third argument must be assignable. @item index(@var{in}, @var{find}) -@cindex @code{index()} function -@cindex searching +@cindexawkfunc{index} +@cindex search in string +@cindex find substring in string Search the string @var{in} for the first occurrence of the string @var{find}, and return the position in characters where that occurrence begins in the string @var{in}. Consider the following example: @@ -15157,7 +15245,9 @@ If @var{find} is not found, @code{index()} returns zero. It is a fatal error to use a regexp constant for @var{find}. @item length(@r{[}@var{string}@r{]}) -@cindex @code{length()} function +@cindexawkfunc{length} +@cindex string length +@cindex length of string Return the number of characters in @var{string}. If @var{string} is a number, the length of the digit string representing that number is returned. For example, @code{length("abcde")} is five. By @@ -15165,6 +15255,8 @@ contrast, @code{length(15 * 35)} works out to three. In this example, 15 * 35 = 525, and 525 is then converted to the string @code{"525"}, which has three characters. +@cindex length of input record +@cindex input record, length of If no argument is supplied, @code{length()} returns the length of @code{$0}. @c @cindex historical features @@ -15203,6 +15295,8 @@ warning about this. @cindex common extensions, @code{length()} applied to an array @cindex extensions, common@comma{} @code{length()} applied to an array @cindex differences between @command{gawk} and @command{awk} +@cindex number of array elements +@cindex array, number of elements With @command{gawk} and several other @command{awk} implementations, when given an array argument, the @code{length()} function returns the number of elements in the array. @value{COMMONEXT} @@ -15216,7 +15310,9 @@ If @option{--posix} is supplied, using an array argument is a fatal error (@pxref{Arrays}). @item match(@var{string}, @var{regexp} @r{[}, @var{array}@r{]}) -@cindex @code{match()} function +@cindexawkfunc{match} +@cindex string, regular expression match +@cindex match regexp in string Search @var{string} for the longest, leftmost substring matched by the regular expression, @var{regexp} and return the character position, or @dfn{index}, @@ -15331,7 +15427,8 @@ The @var{array} argument to @code{match()} is a using a third argument is a fatal error. @item patsplit(@var{string}, @var{array} @r{[}, @var{fieldpat} @r{[}, @var{seps} @r{]} @r{]}) # -@cindex @code{patsplit()} function (@command{gawk}) +@cindexgawkfunc{patsplit} +@cindex split string into array Divide @var{string} into pieces defined by @var{fieldpat} and store the pieces in @var{array} and the separator strings in the @@ -15362,7 +15459,7 @@ The @code{patsplit()} function is a it is not available. @item split(@var{string}, @var{array} @r{[}, @var{fieldsep} @r{[}, @var{seps} @r{]} @r{]}) -@cindex @code{split()} function +@cindexawkfunc{split} Divide @var{string} into pieces separated by @var{fieldsep} and store the pieces in @var{array} and the separator strings in the @var{seps} array. The first piece is stored in @@ -15391,7 +15488,7 @@ split("cul-de-sac", a, "-", seps) @end example @noindent -@cindex strings, splitting +@cindex strings splitting, example splits the string @samp{cul-de-sac} into three fields using @samp{-} as the separator. It sets the contents of the array @code{a} as follows: @@ -15447,7 +15544,8 @@ If @var{string} does not match @var{fieldsep} at all (but is not null), @var{string}. @item sprintf(@var{format}, @var{expression1}, @dots{}) -@cindex @code{sprintf()} function +@cindexawkfunc{sprintf} +@cindex formatting strings Return (without printing) the string that @code{printf} would have printed out with the same arguments (@pxref{Printf}). @@ -15460,7 +15558,8 @@ pival = sprintf("pi = %.2f (approx.)", 22/7) @noindent assigns the string @w{@samp{pi = 3.14 (approx.)}} to the variable @code{pival}. -@cindex @code{strtonum()} function (@command{gawk}) +@cindexgawkfunc{strtonum} +@cindex convert string to number @item strtonum(@var{str}) # Examine @var{str} and return its numeric value. If @var{str} begins with a leading @samp{0}, @code{strtonum()} assumes that @var{str} @@ -15487,7 +15586,8 @@ for recognizing numbers (@pxref{Locales}). in compatibility mode (@pxref{Options}). @item sub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) -@cindex @code{sub()} function +@cindexawkfunc{sub} +@cindex replace in string Search @var{target}, which is treated as a string, for the leftmost, longest substring matched by the regular expression @var{regexp}. Modify the entire string @@ -15587,7 +15687,8 @@ Finally, if the @var{regexp} is not a regexp constant, it is converted into a string, and then the value of that string is treated as the regexp to match. @item substr(@var{string}, @var{start} @r{[}, @var{length}@r{]}) -@cindex @code{substr()} function +@cindexawkfunc{substr} +@cindex substring Return a @var{length}-character-long substring of @var{string}, starting at character number @var{start}. The first character of a string is character number one.@footnote{This is different from @@ -15644,16 +15745,18 @@ string = substr(string, 1, 2) "CDE" substr(string, 6) @end example @cindex case sensitivity, converting case -@cindex converting, case +@cindex strings, converting letter case @item tolower(@var{string}) -@cindex @code{tolower()} function +@cindexawkfunc{tolower} +@cindex convert string to lower case Return a copy of @var{string}, with each uppercase character in the string replaced with its corresponding lowercase character. Nonalphabetic characters are left unchanged. For example, @code{tolower("MiXeD cAsE 123")} returns @code{"mixed case 123"}. @item toupper(@var{string}) -@cindex @code{toupper()} function +@cindexawkfunc{toupper} +@cindex convert string to upper case Return a copy of @var{string}, with each lowercase character in the string replaced with its corresponding uppercase character. Nonalphabetic characters are left unchanged. For example, @@ -16046,14 +16149,16 @@ Although this makes a certain amount of sense, it can be surprising. @node I/O Functions @subsection Input/Output Functions +@cindex input/output functions The following functions relate to input/output (I/O). Optional parameters are enclosed in square brackets ([ ]): @table @code @item close(@var{filename} @r{[}, @var{how}@r{]}) -@cindex @code{close()} function +@cindexawkfunc{close} @cindex files, closing +@cindex close file or coprocess Close the file @var{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. @@ -16070,7 +16175,8 @@ not matter. which discusses this feature in more detail and gives an example. @item fflush(@r{[}@var{filename}@r{]}) -@cindex @code{fflush()} function +@cindexawkfunc{fflush} +@cindex flush buffered output Flush any buffered output associated with @var{filename}, which is either a file opened for writing or a shell command for redirecting output to a pipe or coprocess. @@ -16129,7 +16235,8 @@ or if @var{filename} is not an open file, pipe, or coprocess. In such a case, @code{fflush()} returns @minus{}1, as well. @item system(@var{command}) -@cindex @code{system()} function +@cindexawkfunc{system} +@cindex invoke shell command @cindex interacting with other programs Execute the operating-system command @var{command} and then return to the @command{awk} program. @@ -16276,6 +16383,7 @@ you would see the latter (undesirable) output. @node Time Functions @subsection Time Functions +@cindex time functions @c STARTOFRANGE tst @cindex timestamps @@ -16314,7 +16422,8 @@ Optional parameters are enclosed in square brackets ([ ]): @table @code @item mktime(@var{datespec}) -@cindex @code{mktime()} function (@command{gawk}) +@cindexgawkfunc{mktime} +@cindex generate time values Turn @var{datespec} into a timestamp in the same form as is returned by @code{systime()}. It is similar to the function of the same name in ISO C. The argument, @var{datespec}, is a string of the form @@ -16344,7 +16453,8 @@ is out of range, @code{mktime()} returns @minus{}1. @cindex @code{PROCINFO} array @item strftime(@r{[}@var{format} @r{[}, @var{timestamp} @r{[}, @var{utc-flag}@r{]]]}) @c STARTOFRANGE strf -@cindex @code{strftime()} function (@command{gawk}) +@cindexgawkfunc{strftime} +@cindex format time string Format the time specified by @var{timestamp} based on the contents of the @var{format} string and return the result. It is similar to the function of the same name in ISO C. @@ -16361,11 +16471,12 @@ The default string value is @code{@w{"%a %b %e %H:%M:%S %Z %Y"}}. This format string produces output that is equivalent to that of the @command{date} utility. You can assign a new value to @code{PROCINFO["strftime"]} to -change the default format. +change the default format; see below for the various format directives. @item systime() -@cindex @code{systime()} function (@command{gawk}) +@cindexgawkfunc{systime} @cindex timestamps +@cindex current system time Return the current time as the number of seconds since the system epoch. On POSIX systems, this is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds. @@ -16659,6 +16770,7 @@ gawk 'BEGIN @{ @node Bitwise Functions @subsection Bit-Manipulation Functions +@cindex bit-manipulation functions @c STARTOFRANGE bit @cindex bitwise, operations @c STARTOFRANGE and @@ -16821,27 +16933,33 @@ bitwise operations just described. They are: @cindex @command{gawk}, bitwise operations in @table @code -@cindex @code{and()} function (@command{gawk}) +@cindexgawkfunc{and} +@cindex bitwise AND @item and(@var{v1}, @var{v2} @r{[}, @r{@dots{}]}) Return the bitwise AND of the arguments. There must be at least two. -@cindex @code{compl()} function (@command{gawk}) +@cindexgawkfunc{compl} +@cindex bitwise complement @item compl(@var{val}) Return the bitwise complement of @var{val}. -@cindex @code{lshift()} function (@command{gawk}) +@cindexgawkfunc{lshift} +@cindex left shift @item lshift(@var{val}, @var{count}) Return the value of @var{val}, shifted left by @var{count} bits. -@cindex @code{or()} function (@command{gawk}) +@cindexgawkfunc{or} +@cindex bitwise OR @item or(@var{v1}, @var{v2} @r{[}, @r{@dots{}]}) Return the bitwise OR of the arguments. There must be at least two. -@cindex @code{rshift()} function (@command{gawk}) +@cindexgawkfunc{rshift} +@cindex right shift @item rshift(@var{val}, @var{count}) Return the value of @var{val}, shifted right by @var{count} bits. -@cindex @code{xor()} function (@command{gawk}) +@cindexgawkfunc{xor} +@cindex bitwise XOR @item xor(@var{v1}, @var{v2} @r{[}, @r{@dots{}]}) Return the bitwise XOR of the arguments. There must be at least two. @end table @@ -16933,6 +17051,7 @@ $ @kbd{gawk -f testbits.awk} @cindex strings, converting @cindex numbers, converting @cindex converting, numbers to strings +@cindex number as string of bits The @code{bits2str()} function turns a binary number into a string. The number @code{1} represents a binary value where the rightmost bit is set to 1. Using this mask, @@ -16968,7 +17087,8 @@ that traverses every element of a true multidimensional array (@pxref{Arrays of Arrays}). @table @code -@cindex @code{isarray()} function (@command{gawk}) +@cindexgawkfunc{isarray} +@cindex scalar or array @item isarray(@var{x}) Return a true value if @var{x} is an array. Otherwise return false. @end table @@ -16990,6 +17110,7 @@ will end up turning it into a scalar. @subsection String-Translation Functions @cindex @command{gawk}, string-translation functions @cindex functions, string-translation +@cindex string-translation functions @cindex internationalization @cindex @command{awk} programs, internationalizing @@ -17001,7 +17122,8 @@ for the full story. Optional parameters are enclosed in square brackets ([ ]): @table @code -@cindex @code{bindtextdomain()} function (@command{gawk}) +@cindexgawkfunc{bindtextdomain} +@cindex set directory of message catalogs @item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]}) Set the directory in which @command{gawk} will look for message translation files, in case they @@ -17014,14 +17136,15 @@ If @var{directory} is the null string (@code{""}), then @code{bindtextdomain()} returns the current binding for the given @var{domain}. -@cindex @code{dcgettext()} function (@command{gawk}) +@cindexgawkfunc{dcgettext} +@cindex translate string @item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. -@cindex @code{dcngettext()} function (@command{gawk}) +@cindexgawkfunc{dcngettext} @item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @@ -17038,7 +17161,7 @@ The default value for @var{category} is @code{"LC_MESSAGES"}. @section User-Defined Functions @c STARTOFRANGE udfunc -@cindex user-defined, functions +@cindex user-defined functions @c STARTOFRANGE funcud @cindex functions, user-defined Complicated @command{awk} programs can often be simplified by defining @@ -17124,6 +17247,7 @@ conventional to place some extra space between the arguments and the local variables, in order to document how your function is supposed to be used. @cindex variables, shadowing +@cindex shadowing of variable values During execution of the function body, the arguments and local variable values hide, or @dfn{shadow}, any variables of the same names used in the rest of the program. The shadowed variables are not accessible in the @@ -17182,6 +17306,7 @@ keyword @code{function} when defining a function. @node Function Example @subsection Function Definition Examples +@cindex function definition example Here is an example of a user-defined function, called @code{myprint()}, that takes a number and prints it in a specific format: @@ -17330,8 +17455,8 @@ an error. @node Variable Scope @subsubsection Controlling Variable Scope -@cindex local variables -@cindex variables, local +@cindex local variables, in a function +@cindex variables, local to a function There is no way to make a variable local to a @code{@{ @dots{} @}} block in @command{awk}, but you can make a variable local to a function. It is good practice to do so whenever a variable is needed only in that @@ -18260,7 +18385,7 @@ The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is not one of @command{awk}'s built-in variables, such as @code{FS}. -@cindex @option{--dump-variables} option +@cindex @option{--dump-variables} option, using for library functions It is also important that @emph{all} variables in library functions that do not need to save state are, in fact, declared local.@footnote{@command{gawk}'s @option{--dump-variables} command-line @@ -20048,7 +20173,7 @@ from anywhere within a user's program, and the user may have his or her own way of splitting records and fields. -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, testing the field splitting The @code{using_fw} variable checks @code{PROCINFO["FS"]}, which is @code{"FIELDWIDTHS"} if field splitting is being done with @code{FIELDWIDTHS}. This makes it possible to restore the correct @@ -20171,7 +20296,7 @@ uses these functions. @cindex group database, reading @c STARTOFRANGE datagr @cindex database, group, reading -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, and group membership @cindex @code{getgrent()} function (C library) @cindex @code{getgrent()} user-defined function @cindex groups@comma{} information about @@ -21350,7 +21475,7 @@ $ @kbd{id} @print{} uid=500(arnold) gid=500(arnold) groups=6(disk),7(lp),19(floppy) @end example -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, and user and group ID numbers This information is part of what is provided by @command{gawk}'s @code{PROCINFO} array (@pxref{Built-in Variables}). However, the @command{id} utility provides a more palatable output than just @@ -21451,7 +21576,6 @@ BEGIN \ @c endfile @end example -@cindex @code{in} operator The test in the @code{for} loop is worth noting. Any supplementary groups in the @code{PROCINFO} array have the indices @code{"group1"} through @code{"group@var{N}"} for some @@ -21461,7 +21585,7 @@ there are. This loop works by starting at one, concatenating the value with @code{"group"}, and then using @code{in} to see if that value is -in the array. Eventually, @code{i} is incremented past +in the array (@pxref{Reference to Elements}). Eventually, @code{i} is incremented past the last group in the array and the loop exits. The loop is also correct if there are @emph{no} supplementary @@ -24573,9 +24697,9 @@ sorted array traversal is not the default. @subsection Sorting Array Values and Indices with @command{gawk} @cindex arrays, sorting -@cindex @code{asort()} function (@command{gawk}) +@cindexgawkfunc{asort} @cindex @code{asort()} function (@command{gawk}), arrays@comma{} sorting -@cindex @code{asorti()} function (@command{gawk}) +@cindexgawkfunc{asorti} @cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting In most @command{awk} implementations, sorting an array requires writing @@ -24670,9 +24794,8 @@ both arrays use the values. @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex @code{IGNORECASE} variable -@cindex arrays, sorting, @code{IGNORECASE} variable and -@cindex @code{IGNORECASE} variable, array sorting and +@cindex arrays, sorting, and @code{IGNORECASE} variable +@cindex @code{IGNORECASE} variable, and array sorting functions Because @code{IGNORECASE} affects string comparisons, the value of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}. Note also that the locale's sorting order does @emph{not} @@ -24841,7 +24964,7 @@ As a side note, the assignment @samp{LC_ALL=C} in the @command{sort} command ensures traditional Unix (ASCII) sorting from @command{sort}. @cindex @command{gawk}, @code{PROCINFO} array in -@cindex @code{PROCINFO} array +@cindex @code{PROCINFO} array, and communications via ptys You may also 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 @@ -25044,8 +25167,8 @@ Here is the @file{awkprof.out} that results from running the illustrates that @command{awk} programmers sometimes get up very early in the morning to work.) -@cindex @code{BEGIN} pattern -@cindex @code{END} pattern +@cindex @code{BEGIN} pattern, and profiling +@cindex @code{END} pattern, and profiling @example # gawk profile, created Thu Feb 27 05:16:21 2014 @@ -25109,7 +25232,7 @@ Multiple @code{BEGIN} and @code{END} rules retain their separate identities, as do multiple @code{BEGINFILE} and @code{ENDFILE} rules. -@cindex patterns, counts +@cindex patterns, counts, in a profile @item Pattern-action rules have two counts. The first count, to the left of the rule, shows how many times @@ -25129,7 +25252,7 @@ is a count showing how many times the condition was true. The count for the @code{else} indicates how many times the test failed. -@cindex loops, count for header +@cindex loops, count for header, in a profile @item The count for a loop header (such as @code{for} or @code{while}) shows how many times the loop test was executed. @@ -25137,8 +25260,8 @@ or @code{while}) shows how many times the loop test was executed. statement in a rule to determine how many times the rule was executed. If the first statement is a loop, the count is misleading.) -@cindex functions, user-defined, counts -@cindex user-defined, functions, counts +@cindex functions, user-defined, counts, in a profile +@cindex user-defined, functions, counts, in a profile @item For user-defined functions, the count next to the @code{function} keyword indicates how many times the function was called. @@ -25152,8 +25275,8 @@ The layout uses ``K&R'' style with TABs. Braces are used everywhere, even when the body of an @code{if}, @code{else}, or loop is only a single statement. -@cindex @code{()} (parentheses) -@cindex parentheses @code{()} +@cindex @code{()} (parentheses), in a profile +@cindex parentheses @code{()}, in a profile @item Parentheses are used only where needed, as indicated by the structure of the program and the precedence rules. @@ -25209,6 +25332,7 @@ which is correct, but possibly surprising. @cindex profiling @command{awk} programs, dynamically @cindex @command{gawk} program, dynamic profiling +@cindex dynamic profiling Besides creating profiles when a program has completed, @command{gawk} can produce a profile while it is running. This is useful if your @command{awk} program goes into an @@ -25222,9 +25346,9 @@ $ @kbd{gawk --profile -f myprog &} @end example @cindex @command{kill} command@comma{} dynamic profiling -@cindex @code{USR1} signal -@cindex @code{SIGUSR1} signal -@cindex signals, @code{USR1}/@code{SIGUSR1} +@cindex @code{USR1} signal, for dynamic profiling +@cindex @code{SIGUSR1} signal, for dynamic profiling +@cindex signals, @code{USR1}/@code{SIGUSR1}, for profiling @noindent The shell prints a job number and process ID number; in this case, 13992. Use the @command{kill} command to send the @code{USR1} signal @@ -25255,9 +25379,9 @@ You may send @command{gawk} the @code{USR1} signal as many times as you like. Each time, the profile and function call trace are appended to the output profile file. -@cindex @code{HUP} signal -@cindex @code{SIGHUP} signal -@cindex signals, @code{HUP}/@code{SIGHUP} +@cindex @code{HUP} signal, for dynamic profiling +@cindex @code{SIGHUP} signal, for dynamic profiling +@cindex signals, @code{HUP}/@code{SIGHUP}, for profiling If you use the @code{HUP} signal instead of the @code{USR1} signal, @command{gawk} produces the profile and the function call trace and then exits. @@ -25555,7 +25679,7 @@ String constants marked with a leading underscore are candidates for translation at runtime. String constants without a leading underscore are not translated. -@cindex @code{dcgettext()} function (@command{gawk}) +@cindexgawkfunc{dcgettext} @item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. @@ -25581,7 +25705,7 @@ chosen to be simple and to allow for reasonable @command{awk}-style default arguments. @end quotation -@cindex @code{dcngettext()} function (@command{gawk}) +@cindexgawkfunc{dcngettext} @item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @@ -25597,7 +25721,7 @@ The same remarks about argument order as for the @code{dcgettext()} function app @cindex files, @code{.gmo}, specifying directory of @cindex message object files, specifying directory of @cindex files, message object, specifying directory of -@cindex @code{bindtextdomain()} function (@command{gawk}) +@cindexgawkfunc{bindtextdomain} @item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]}) Change the directory in which @code{gettext} looks for @file{.gmo} files, in case they @@ -26171,6 +26295,7 @@ The following list defines terms used throughout the rest of this @value{CHAPTER}. @table @dfn +@cindex stack frame @item Stack Frame Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). @@ -26192,6 +26317,7 @@ invoked. Commands that print the call stack print information about each stack frame (as detailed later on). @item Breakpoint +@cindex breakpoint During debugging, you often wish to let the program run until it reaches a certain point, and then continue execution from there one statement (or instruction) at a time. The way to do this is to set @@ -26201,6 +26327,7 @@ take over control of the program's execution. You can add and remove as many breakpoints as you like. @item Watchpoint +@cindex watchpoint A watchpoint is similar to a breakpoint. The difference is that breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution @@ -26232,6 +26359,7 @@ by the higher-level @command{awk} commands. @node Sample Debugging Session @section Sample Debugging Session +@cindex sample debugging session In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample debugging session. We will use the @command{awk} implementation of the @@ -26245,6 +26373,8 @@ as our example. @node Debugger Invocation @subsection How to Start the Debugger +@cindex starting the debugger +@cindex debugger, how to start Starting the debugger is almost exactly like running @command{gawk}, except you have to pass an additional option @option{--debug} or the @@ -26585,6 +26715,8 @@ controlling breakpoints are: @cindex debugger commands, @code{break} @cindex @code{break} debugger command @cindex @code{b} debugger command (alias for @code{break}) +@cindex set breakpoint +@cindex breakpoint, setting @item @code{break} [[@var{filename}@code{:}]@var{n} | @var{function}] [@code{"@var{expression}"}] @itemx @code{b} [[@var{filename}@code{:}]@var{n} | @var{function}] [@code{"@var{expression}"}] Without any argument, set a breakpoint at the next instruction @@ -26615,6 +26747,8 @@ it continues executing the program. @cindex debugger commands, @code{clear} @cindex @code{clear} debugger command +@cindex delete breakpoint at location +@cindex breakpoint at location, how to delete @item @code{clear} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, delete any breakpoint at the next instruction to be executed in the selected stack frame. If the program stops at @@ -26635,6 +26769,7 @@ Delete breakpoint(s) set at entry to function @var{function}. @cindex debugger commands, @code{condition} @cindex @code{condition} debugger command +@cindex breakpoint condition @item @code{condition} @var{n} @code{"@var{expression}"} Add a condition to existing breakpoint or watchpoint @var{n}. The condition is an @command{awk} expression that the debugger evaluates @@ -26648,6 +26783,8 @@ watchpoint is made unconditional. @cindex debugger commands, @code{delete} @cindex @code{delete} debugger command @cindex @code{d} debugger command (alias for @code{delete}) +@cindex delete breakpoint by number +@cindex breakpoint, delete by number @item @code{delete} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{d} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] Delete specified breakpoints or a range of breakpoints. Deletes @@ -26655,6 +26792,8 @@ all defined breakpoints if no argument is supplied. @cindex debugger commands, @code{disable} @cindex @code{disable} debugger command +@cindex disable breakpoint +@cindex breakpoint, how to disable or enable @item @code{disable} [@var{n1 n2} @dots{} | @var{n}--@var{m}] Disable specified breakpoints or a range of breakpoints. Without any argument, disables all breakpoints. @@ -26663,6 +26802,7 @@ any argument, disables all breakpoints. @cindex debugger commands, @code{enable} @cindex @code{enable} debugger command @cindex @code{e} debugger command (alias for @code{enable}) +@cindex enable breakpoint @item @code{enable} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{e} [@code{del} | @code{once}] [@var{n1 n2} @dots{}] [@var{n}--@var{m}] Enable specified breakpoints or a range of breakpoints. Without @@ -26682,6 +26822,7 @@ the program stops at the breakpoint. @cindex debugger commands, @code{ignore} @cindex @code{ignore} debugger command +@cindex ignore breakpoint @item @code{ignore} @var{n} @var{count} Ignore breakpoint number @var{n} the next @var{count} times it is hit. @@ -26690,6 +26831,7 @@ hit. @cindex debugger commands, @code{tbreak} @cindex @code{tbreak} debugger command @cindex @code{t} debugger command (alias for @code{tbreak}) +@cindex temporary breakpoint @item @code{tbreak} [[@var{filename}@code{:}]@var{n} | @var{function}] @itemx @code{t} [[@var{filename}@code{:}]@var{n} | @var{function}] Set a temporary breakpoint (enabled for only one stop). @@ -26710,6 +26852,8 @@ execution of the program than we saw in our earlier example: @cindex @code{silent} debugger command @cindex debugger commands, @code{end} @cindex @code{end} debugger command +@cindex breakpoint commands +@cindex commands to execute at breakpoint @item @code{commands} [@var{n}] @itemx @code{silent} @itemx @dots{} @@ -26737,6 +26881,7 @@ gawk> @cindex debugger commands, @code{c} (@code{continue}) @cindex debugger commands, @code{continue} +@cindex continue program, in debugger @item @code{continue} [@var{count}] @itemx @code{c} [@var{count}] Resume program execution. If continued from a breakpoint and @var{count} is @@ -26753,6 +26898,7 @@ Print the returned value. @cindex debugger commands, @code{next} @cindex @code{next} debugger command @cindex @code{n} debugger command (alias for @code{next}) +@cindex single-step execution, in the debugger @item @code{next} [@var{count}] @itemx @code{n} [@var{count}] Continue execution to the next source line, stepping over function calls. @@ -26847,6 +26993,7 @@ items on the list. @cindex debugger commands, @code{eval} @cindex @code{eval} debugger command +@cindex evaluate expressions, in debugger @item @code{eval "@var{awk statements}"} Evaluate @var{awk statements} in the context of the running program. You can do anything that an @command{awk} program would do: assign @@ -26864,6 +27011,7 @@ parameters defined by the program. @cindex debugger commands, @code{print} @cindex @code{print} debugger command @cindex @code{p} debugger command (alias for @code{print}) +@cindex print variables, in debugger @item @code{print} @var{var1}[@code{,} @var{var2} @dots{}] @itemx @code{p} @var{var1}[@code{,} @var{var2} @dots{}] Print the value of a @command{gawk} variable or field. @@ -26897,6 +27045,7 @@ No newline is printed unless one is specified. @cindex debugger commands, @code{set} @cindex @code{set} debugger command +@cindex assign values to variables, in debugger @item @code{set} @var{var}@code{=}@var{value} Assign a constant (number or string) value to an @command{awk} variable or field. @@ -26909,6 +27058,7 @@ You can also set special @command{awk} variables, such as @code{FS}, @cindex debugger commands, @code{watch} @cindex @code{watch} debugger command @cindex @code{w} debugger command (alias for @code{watch}) +@cindex set watchpoint @item @code{watch} @var{var} | @code{$}@var{n} [@code{"@var{expression}"}] @itemx @code{w} @var{var} | @code{$}@var{n} [@code{"@var{expression}"}] Add variable @var{var} (or field @code{$@var{n}}) to the watch list. @@ -26925,12 +27075,14 @@ then the debugger stops execution and prompts for a command. Otherwise, @cindex debugger commands, @code{undisplay} @cindex @code{undisplay} debugger command +@cindex stop automatic display, in debugger @item @code{undisplay} [@var{n}] Remove item number @var{n} (or all items, if no argument) from the automatic display list. @cindex debugger commands, @code{unwatch} @cindex @code{unwatch} debugger command +@cindex delete watchpoint @item @code{unwatch} [@var{n}] Remove item number @var{n} (or all items, if no argument) from the watch list. @@ -26951,6 +27103,8 @@ functions which called the one you are in. The commands for doing this are: @cindex debugger commands, @code{backtrace} @cindex @code{backtrace} debugger command @cindex @code{bt} debugger command (alias for @code{backtrace}) +@cindex call stack, display in debugger +@cindex traceback, display in debugger @item @code{backtrace} [@var{count}] @itemx @code{bt} [@var{count}] Print a backtrace of all function calls (stack frames), or innermost @var{count} @@ -27004,25 +27158,32 @@ The value for @var{what} should be one of the following: @c nested table @table @code @item args +@cindex show function arguments, in debugger Arguments of the selected frame. @item break +@cindex show breakpoints List all currently set breakpoints. @item display +@cindex automatic displays, in debugger List all items in the automatic display list. @item frame +@cindex describe call stack frame, in debugger Description of the selected stack frame. @item functions +@cindex list function definitions, in debugger List all function definitions including source file names and line numbers. @item locals +@cindex show local variables, in debugger Local variables of the selected frame. @item source +@cindex show name of current source file, in debugger The name of the current source file. Each time the program stops, the current source file is the file containing the current instruction. When the debugger first starts, the current source file is the first file @@ -27031,12 +27192,15 @@ included via the @option{-f} option. The be used at any time to change the current source. @item sources +@cindex show all source files, in debugger List all program sources. @item variables +@cindex list all global variables, in debugger List all global variables. @item watch +@cindex show watchpoints List all items in the watch list. @end table @end table @@ -27050,6 +27214,8 @@ from a file. The commands are: @cindex debugger commands, @code{option} @cindex @code{option} debugger command @cindex @code{o} debugger command (alias for @code{option}) +@cindex display debugger options +@cindex debugger options @item @code{option} [@var{name}[@code{=}@var{value}]] @itemx @code{o} [@var{name}[@code{=}@var{value}]] Without an argument, display the available debugger options @@ -27061,6 +27227,7 @@ The available options are: @c nested table @table @code @item history_size +@cindex debugger history size The maximum number of lines to keep in the history file @file{./.gawk_history}. The default is 100. @@ -27068,23 +27235,28 @@ The default is 100. The number of lines that @code{list} prints. The default is 15. @item outfile +@cindex redirect @command{gawk} output, in debugger Send @command{gawk} output to a file; debugger output still goes to standard output. An empty string (@code{""}) resets output to standard output. @item prompt +@cindex debugger prompt The debugger prompt. The default is @samp{@w{gawk> }}. @item save_history @r{[}on @r{|} off@r{]} +@cindex debugger history file Save command history to file @file{./.gawk_history}. The default is @code{on}. @item save_options @r{[}on @r{|} off@r{]} +@cindex save debugger options Save current options to file @file{./.gawkrc} upon exit. The default is @code{on}. Options are read back in to the next session upon startup. @item trace @r{[}on @r{|} off@r{]} +@cindex instruction tracing, in debugger Turn instruction tracing on or off. The default is @code{off}. @end table @@ -27093,6 +27265,7 @@ Save the commands from the current session to the given file name, so that they can be replayed using the @command{source} command. @item @code{source} @var{filename} +@cindex debugger, read commands from a file Run command(s) from a file; an error in any command does not terminate execution of subsequent commands. Comments (lines starting with @samp{#}) are allowed in a command file. @@ -27225,6 +27398,7 @@ function @var{function}. This command may change the current source file. @cindex debugger commands, @code{quit} @cindex @code{quit} debugger command @cindex @code{q} debugger command (alias for @code{quit}) +@cindex exit the debugger @item @code{quit} @itemx @code{q} Exit the debugger. Debugging is great fun, but sometimes we all have @@ -27248,6 +27422,8 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while @node Readline Support @section Readline Support +@cindex command completion, in debugger +@cindex history expansion, in debugger If @command{gawk} is compiled with the @code{readline} library, you can take advantage of that library's command completion and history expansion @@ -27336,8 +27512,6 @@ be added, and of course feel free to try to add them yourself! @cindex multiple precision @cindex infinite precision @cindex floating-point, numbers@comma{} arbitrary precision -@cindex MPFR -@cindex GMP @cindex Knuth, Donald @quotation @@ -28101,6 +28275,8 @@ when you change the rounding mode. @node Gawk and MPFR @section @command{gawk} + MPFR = Powerful Arithmetic +@cindex MPFR +@cindex GMP The rest of this @value{CHAPTER} describes how to use the arbitrary precision (also known as @dfn{multiple precision} or @dfn{infinite precision}) numeric @@ -28205,6 +28381,7 @@ your program. @node Setting Precision @subsection Setting the Working Precision @cindex @code{PREC} variable +@cindex setting working precision @command{gawk} uses a global working precision; it does not keep track of the precision or accuracy of individual numbers. Performing an arithmetic @@ -28280,6 +28457,7 @@ issues that occur because numbers are stored internally in binary. @node Setting Rounding Mode @subsection Setting the Rounding Mode @cindex @code{ROUNDMODE} variable +@cindex setting rounding mode The @code{ROUNDMODE} variable provides program level control over the rounding mode. @@ -28347,6 +28525,7 @@ In the first case, the number is stored with the default precision of 53 bits. @node Changing Precision @subsection Changing the Precision of a Number +@cindex changing precision of a number @cindex Laurie, Dirk @quotation @@ -28465,6 +28644,7 @@ the problem at hand is often the correct approach in such situations. @node Arbitrary Precision Integers @section Arbitrary Precision Integer Arithmetic with @command{gawk} @cindex integers, arbitrary precision +@cindex arbitrary precision integers If one of the options @option{--bignum} or @option{-M} is specified, @command{gawk} performs all @@ -28561,6 +28741,7 @@ gawk -M 'BEGIN @{ n = 13; print n % 2 @}' @node Dynamic Extensions @chapter Writing Extensions for @command{gawk} +@cindex dynamically loaded extensions It is possible to add new functions written in C or C++ to @command{gawk} using dynamically loaded libraries. This facility is available on systems @@ -28595,6 +28776,7 @@ When @option{--sandbox} is specified, extensions are disabled @node Extension Intro @section Introduction +@cindex plug-in An @dfn{extension} (sometimes called a @dfn{plug-in}) is a piece of external compiled code that @command{gawk} can load at runtime to provide additional functionality, over and above the built-in capabilities @@ -28723,6 +28905,7 @@ happen, but we all know how @emph{that} goes.) @node Extension API Description @section API Description +@cindex extension API This (rather large) @value{SECTION} describes the API in detail. @@ -29107,6 +29290,8 @@ value type, as appropriate. This behavior is summarized in @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros +@cindex allocating memory for extensions +@cindex extensions, allocating memory The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, as well as a number of @@ -29221,6 +29406,8 @@ pointed to by @code{result}. @node Registration Functions @subsection Registration Functions +@cindex register extension +@cindex extension registration This @value{SECTION} describes the API functions for registering parts of your extension with @command{gawk}. @@ -29342,6 +29529,7 @@ is invoked with the @option{--version} option. @node Input Parsers @subsubsection Customized Input Parsers +@cindex customized input parser By default, @command{gawk} reads text files as its input. It uses the value of @code{RS} to find the end of the record, and then uses @code{FS} @@ -29589,7 +29777,9 @@ Register the input parser pointed to by @code{input_parser} with @node Output Wrappers @subsubsection Customized Output Wrappers +@cindex customized output wrapper +@cindex output wrapper An @dfn{output wrapper} is the mirror image of an input parser. It allows an extension to take over the output to a file opened with the @samp{>} or @samp{>>} I/O redirection operators (@pxref{Redirection}). @@ -29703,6 +29893,7 @@ Register the output wrapper pointed to by @code{output_wrapper} with @node Two-way processors @subsubsection Customized Two-way Processors +@cindex customized two-way processor A @dfn{two-way processor} combines an input parser and an output wrapper for two-way I/O with the @samp{|&} operator (@pxref{Redirection}). It makes identical @@ -29760,6 +29951,8 @@ Register the two-way processor pointed to by @code{two_way_processor} with @node Printing Messages @subsection Printing Messages +@cindex printing messages from extensions +@cindex messages from extensions You can print different kinds of warning messages from your extension, as described below. Note that for these functions, @@ -29833,6 +30026,7 @@ for more information on creating arrays. @node Symbol Table Access @subsection Symbol Table Access +@cindex accessing global variables from extensions Two sets of routines provide access to global variables, and one set allows you to create and release cached values. @@ -29878,6 +30072,13 @@ An extension can look up the value of @command{gawk}'s special variables. However, with the exception of the @code{PROCINFO} array, an extension cannot change any of those variables. +@quotation NOTE +It is possible for the lookup of @code{PROCINFO} to fail. This happens if +the @command{awk} program being run does not reference @code{PROCINFO}; +in this case @command{gawk} doesn't bother to create the array and +populate it. +@end quotation + @node Symbol table by cookie @subsubsection Variable Access and Update by Cookie @@ -30090,6 +30291,7 @@ you should release any cached values that you created, using @node Array Manipulation @subsection Array Manipulation +@cindex array manipulation in extensions The primary data structure@footnote{Okay, the only data structure.} in @command{awk} is the associative array (@pxref{Arrays}). @@ -30669,6 +30871,8 @@ information about how @command{gawk} was invoked. @node Extension Versioning @subsubsection API Version Constants and Variables +@cindex API version +@cindex extension API version The API provides both a ``major'' and a ``minor'' version number. The API versions are available at compile time as constants: @@ -30722,6 +30926,8 @@ provided in @file{gawkapi.h} (discussed later, in @node Extension API Informational Variables @subsubsection Informational Variables +@cindex API informational variables +@cindex extension API informational variables The API provides access to several variables that describe whether the corresponding command-line options were enabled when @@ -30867,6 +31073,8 @@ the version string with @command{gawk}. @node Finding Extensions @section How @command{gawk} Finds Extensions +@cindex extension search path +@cindex finding extensions Compiled extensions have to be installed in a directory where @command{gawk} can find them. If @command{gawk} is configured and @@ -30877,6 +31085,7 @@ path with a list of directories to search for compiled extensions. @node Extension Example @section Example: Some File Functions +@cindex extension example @quotation @i{No matter where you go, there you are.} @@ -31521,6 +31730,7 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @node Extension Samples @section The Sample Extensions In The @command{gawk} Distribution +@cindex extensions distributed with @command{gawk} This @value{SECTION} provides brief overviews of the sample extensions that come in the @command{gawk} distribution. Some of them are intended @@ -32112,7 +32322,7 @@ ret = reada("arraydump.bin", array) @subsection Reading An Entire File The @code{readfile} extension adds a single function -named @code{readfile()}: +named @code{readfile()}, and an input parser: @table @code @item @@load "readfile" @@ -32123,6 +32333,12 @@ This is how you load the extension. The argument is the name of the file to read. The return value is a string containing the entire contents of the requested file. Upon error, the function returns the empty string and sets @code{ERRNO}. + +@item BEGIN @{ PROCINFO["readfile"] = 1 @} +In addition, the extension adds an input parser that is activated if +@code{PROCINFO["readfile"]} exists. +When activated, each input file is returned in its entirety as @code{$0}. +@code{RT} is set to the null string. @end table Here is an example: @@ -32181,6 +32397,8 @@ tries to use @code{nanosleep()} or @code{select()} to implement the delay. @node gawkextlib @section The @code{gawkextlib} Project +@cindex @code{gawkextlib} +@cindex extensions, where to find @cindex @code{gawkextlib} project The @uref{http://sourceforge.net/projects/gawkextlib/, @code{gawkextlib}} @@ -33893,6 +34111,11 @@ Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. @item +@cindex Colombo, Antonio +Antonio Giovanni Colombo rewrote a number of examples in the early +chapters that were severely dated, for which I am incredibly grateful. + +@item @cindex Robbins, Arnold Arnold Robbins has been working on @command{gawk} since 1988, at first @@ -36635,9 +36858,6 @@ The GNU version of the standard shell @end ifinfo See also ``Bourne Shell.'' -@item BBS -See ``Bulletin Board System.'' - @item Bit Short for ``Binary Digit.'' All values in computer memory ultimately reduce to binary digits: values @@ -36712,11 +36932,6 @@ Changing some of them affects @command{awk}'s running environment. @item Braces See ``Curly Braces.'' -@item Bulletin Board System -A computer system allowing users to log in and read and/or leave messages -for other users of the system, much like leaving paper notes on a bulletin -board. - @item C The system programming language that most GNU software is written in. The @command{awk} programming language has C-like syntax, and this @value{DOCUMENT} @@ -38682,8 +38897,6 @@ Suggestions: % Next edition: % 1. Standardize the error messages from the functions and programs % in the two sample code chapters. -% 2. Nuke the BBS stuff and use something that won't be obsolete -% 3. Turn the advanced notes into sidebars by using @cartouche Better sidebars can almost sort of be done with: @@ -38715,4 +38928,3 @@ But to use it you have to say } which sorta sucks. - diff --git a/extension/ChangeLog b/extension/ChangeLog index 61381171..02c26f3d 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,9 @@ +2014-03-27 Arnold D. Robbins <arnold@skeeve.com> + + * readfile.c: Add an input parser that works off of + PROCINFO["readfile"]. + * readfile.3am: Document same. + 2014-03-23 Arnold D. Robbins <arnold@skeeve.com> * gawkfts.c (MAXPATHLEN): Add a default definition. Thanks to diff --git a/extension/readfile.3am b/extension/readfile.3am index 688d9cd5..0cb2eb5b 100644 --- a/extension/readfile.3am +++ b/extension/readfile.3am @@ -1,4 +1,4 @@ -.TH READFILE 3am "Jan 15 2013" "Free Software Foundation" "GNU Awk Extension Modules" +.TH READFILE 3am "Mar 24 2013" "Free Software Foundation" "GNU Awk Extension Modules" .SH NAME readfile \- return the entire contents of a file as a string .SH SYNOPSIS @@ -6,6 +6,14 @@ readfile \- return the entire contents of a file as a string @load "readfile" .sp result = readfile("/some/path") +.sp +.ft R +For making whole files be single records: +.sp +.ft CW +@load "readfile" +.br +BEGIN { PROCINFO["readfile"] = 1 } .ft R .SH DESCRIPTION The @@ -18,6 +26,14 @@ the requested file. .PP Upon error, the function returns the empty string and sets .BR ERRNO . +.PP +In addition, it adds an input parser that is activated if +.ft CW +PROCINFO["readfile"] +.ft R +exists. +When activated, each input file is returned in its entirety as \f(CW$0\fR. +\f(CWRT\fP is set to the null string. ... .SH NOTES ... .SH BUGS .SH EXAMPLE @@ -47,7 +63,7 @@ if (contents == "" && ERRNO != "") { Arnold Robbins, .BR arnold@skeeve.com . .SH COPYING PERMISSIONS -Copyright \(co 2012, 2013, +Copyright \(co 2012, 2013, 2014, Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of diff --git a/extension/readfile.c b/extension/readfile.c index 71d67ee6..67fa9eca 100644 --- a/extension/readfile.c +++ b/extension/readfile.c @@ -61,11 +61,39 @@ static const gawk_api_t *api; /* for convenience macros to work */ static awk_ext_id_t *ext_id; -static const char *ext_version = "readfile extension: version 1.0"; -static awk_bool_t (*init_func)(void) = NULL; +static const char *ext_version = "readfile extension: version 2.0"; +static awk_bool_t init_readfile(); +static awk_bool_t (*init_func)(void) = init_readfile; int plugin_is_GPL_compatible; +/* read_file_to_buffer --- handle the mechanics of reading the file */ + +static char * +read_file_to_buffer(int fd, const struct stat *sbuf) +{ + char *text = NULL; + int ret; + + if ((sbuf->st_mode & S_IFMT) != S_IFREG) { + errno = EINVAL; + update_ERRNO_int(errno); + goto done; + } + + emalloc(text, char *, sbuf->st_size + 2, "do_readfile"); + memset(text, '\0', sbuf->st_size + 2); + + if ((ret = read(fd, text, sbuf->st_size)) != sbuf->st_size) { + update_ERRNO_int(errno); + gawk_free(text); + text = NULL; + /* fall through to return */ + } +done: + return text; +} + /* do_readfile --- read a file into memory */ static awk_value_t * @@ -90,10 +118,6 @@ do_readfile(int nargs, awk_value_t *result) if (ret < 0) { update_ERRNO_int(errno); goto done; - } else if ((sbuf.st_mode & S_IFMT) != S_IFREG) { - errno = EINVAL; - update_ERRNO_int(errno); - goto done; } if ((fd = open(filename.str_value.str, O_RDONLY|O_BINARY)) < 0) { @@ -101,15 +125,9 @@ do_readfile(int nargs, awk_value_t *result) goto done; } - emalloc(text, char *, sbuf.st_size + 2, "do_readfile"); - memset(text, '\0', sbuf.st_size + 2); - - if ((ret = read(fd, text, sbuf.st_size)) != sbuf.st_size) { - (void) close(fd); - update_ERRNO_int(errno); - gawk_free(text); - goto done; - } + text = read_file_to_buffer(fd, & sbuf); + if (text == NULL) + goto done; /* ERRNO already updated */ close(fd); make_malloced_string(text, sbuf.st_size, result); @@ -117,12 +135,110 @@ do_readfile(int nargs, awk_value_t *result) } else if (do_lint) lintwarn(ext_id, _("readfile: called with no arguments")); - done: /* Set the return value */ return result; } +/* readfile_get_record --- read the whole file as one record */ + +static int +readfile_get_record(char **out, awk_input_buf_t *iobuf, int *errcode, + char **rt_start, size_t *rt_len) +{ + char *text; + + /* + * The caller sets *errcode to 0, so we should set it only if an + * error occurs. + */ + + if (out == NULL || iobuf == NULL) + return EOF; + + if (iobuf->opaque != NULL) { + /* + * Already read the whole file, + * free up stuff and return EOF + */ + gawk_free(iobuf->opaque); + iobuf->opaque = NULL; + return EOF; + } + + /* read file */ + text = read_file_to_buffer(iobuf->fd, & iobuf->sbuf); + if (text == NULL) + return EOF; + + /* set up the iobuf for next time */ + iobuf->opaque = text; + + /* set return values */ + *rt_start = NULL; + *rt_len = 0; + *out = text; + + /* return count */ + return iobuf->sbuf.st_size; +} + +/* readfile_can_take_file --- return true if we want the file */ + +static awk_bool_t +readfile_can_take_file(const awk_input_buf_t *iobuf) +{ + awk_value_t array, index, value; + + if (iobuf == NULL) + return awk_false; + + /* + * This could fail if PROCINFO isn't referenced from + * the awk program. It's not a "can't happen" error. + */ + if (! sym_lookup("PROCINFO", AWK_ARRAY, & array)) { + return awk_false; + } + + (void) make_const_string("readfile", 8, & index); + + if (! get_array_element(array.array_cookie, & index, AWK_UNDEFINED, & value)) { + return awk_false; + } + + return awk_true; +} + +/* readfile_take_control_of --- take over the file */ + +static awk_bool_t +readfile_take_control_of(awk_input_buf_t *iobuf) +{ + if (iobuf == NULL) + return awk_false; + + iobuf->get_record = readfile_get_record; + return awk_true; +} + +static awk_input_parser_t readfile_parser = { + "readfile", + readfile_can_take_file, + readfile_take_control_of, + NULL +}; + +/* init_readfile --- set things up */ + +static awk_bool_t +init_readfile() +{ + register_input_parser(& readfile_parser); + + return awk_true; +} + static awk_ext_func_t func_table[] = { { "readfile", do_readfile, 1 }, }; diff --git a/test/ChangeLog b/test/ChangeLog index 99b3e9b9..8340cac4 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,8 @@ +2014-03-27 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (readfile2): New test. + * readfile2.awk, readfile2.ok: New files. + 2014-02-28 Arnold D. Robbins <arnold@skeeve.com> * regrange.ok: Update after code improvements. diff --git a/test/Makefile.am b/test/Makefile.am index 97848a00..23a6b626 100644 --- a/test/Makefile.am +++ b/test/Makefile.am @@ -710,6 +710,7 @@ EXTRA_DIST = \ range1.ok \ readdir.awk \ readdir0.awk \ + readfile2.awk \ rebt8b1.awk \ rebt8b1.ok \ rebt8b2.awk \ @@ -1021,7 +1022,7 @@ LOCALE_CHARSET_TESTS = \ SHLIB_TESTS = \ fnmatch filefuncs fork fork2 fts functab4 inplace1 inplace2 inplace3 \ - ordchr ordchr2 readdir readfile revout revtwoway rwarray testext time + ordchr ordchr2 readdir readfile readfile2 revout revtwoway rwarray testext time # List of the tests which should be run with --lint option: NEED_LINT = \ @@ -1736,6 +1737,11 @@ readfile:: @$(AWK) -l readfile 'BEGIN {printf "%s", readfile("Makefile")}' >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) Makefile _$@ && rm -f _$@ || cp -p Makefile $@.ok +readfile2:: + @echo $@ + @$(AWK) -f "$(srcdir)"/$@.awk "$(srcdir)"/$@.awk "$(srcdir)"/readdir.awk > _$@ || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + include2:: @echo $@ @AWKPATH="$(srcdir)" $(AWK) --include inclib 'BEGIN {print sandwich("a", "b", "c")}' >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ diff --git a/test/Makefile.in b/test/Makefile.in index 468c19c5..3d05bd67 100644 --- a/test/Makefile.in +++ b/test/Makefile.in @@ -956,6 +956,7 @@ EXTRA_DIST = \ range1.ok \ readdir.awk \ readdir0.awk \ + readfile2.awk \ rebt8b1.awk \ rebt8b1.ok \ rebt8b2.awk \ @@ -1263,7 +1264,7 @@ LOCALE_CHARSET_TESTS = \ SHLIB_TESTS = \ fnmatch filefuncs fork fork2 fts functab4 inplace1 inplace2 inplace3 \ - ordchr ordchr2 readdir readfile revout revtwoway rwarray testext time + ordchr ordchr2 readdir readfile readfile2 revout revtwoway rwarray testext time # List of the tests which should be run with --lint option: @@ -2160,6 +2161,11 @@ readfile:: @$(AWK) -l readfile 'BEGIN {printf "%s", readfile("Makefile")}' >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) Makefile _$@ && rm -f _$@ || cp -p Makefile $@.ok +readfile2:: + @echo $@ + @$(AWK) -f "$(srcdir)"/$@.awk "$(srcdir)"/$@.awk "$(srcdir)"/readdir.awk > _$@ || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + include2:: @echo $@ @AWKPATH="$(srcdir)" $(AWK) --include inclib 'BEGIN {print sandwich("a", "b", "c")}' >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ diff --git a/test/readfile2.awk b/test/readfile2.awk new file mode 100644 index 00000000..c21483fc --- /dev/null +++ b/test/readfile2.awk @@ -0,0 +1,12 @@ +@load "readfile" +BEGIN { PROCINFO["readfile"] = 1 } +BEGINFILE { print "Start of", basename(FILENAME) } +{ printf ("%d: <%s>\n", FNR, $0 ) } +ENDFILE { print "End of", basename(FILENAME) } + +function basename(file, result) +{ + result = file + gsub(".*/", "", result) + return result +} diff --git a/test/readfile2.ok b/test/readfile2.ok new file mode 100644 index 00000000..be1ded6c --- /dev/null +++ b/test/readfile2.ok @@ -0,0 +1,21 @@ +Start of readfile2.awk +1: <@load "readfile" +BEGIN { PROCINFO["readfile"] = 1 } +BEGINFILE { print "Start of", basename(FILENAME) } +{ printf ("%d: <%s>\n", FNR, $0 ) } +ENDFILE { print "End of", basename(FILENAME) } + +function basename(file, result) +{ + result = file + gsub(".*/", "", result) + return result +} +> +End of readfile2.awk +Start of readdir.awk +1: <@load "readdir" + +{ print } +> +End of readdir.awk |