diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.info | 1509 | ||||
| -rw-r--r-- | doc/gawk.texi | 429 | ||||
| -rw-r--r-- | doc/gawktexi.in | 425 |
4 files changed, 1202 insertions, 1167 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 9d4809ae..b004023b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,9 @@ +2014-06-03 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Restore macros for file name vs. filename etc. + Go through @if... and @ifnot... and fix them up too. Other misc. + cleanup. + 2014-05-29 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Remove some obsolete bits, fix up some other diff --git a/doc/gawk.info b/doc/gawk.info index cb22b934..c5038115 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1483,7 +1483,7 @@ tell `awk' to use that file for its program, you type: awk -f SOURCE-FILE INPUT-FILE1 INPUT-FILE2 ... The `-f' instructs the `awk' utility to get the `awk' program from -the file SOURCE-FILE. Any file name can be used for SOURCE-FILE. For +the file SOURCE-FILE. Any FN can be used for SOURCE-FILE. For example, you could put the program: BEGIN { print "Don't Panic!" } @@ -1497,16 +1497,15 @@ does the same thing as this one: awk "BEGIN { print \"Don't Panic!\" }" This was explained earlier (*note Read Terminal::). Note that you -don't usually need single quotes around the file name that you specify -with `-f', because most file names don't contain any of the shell's -special characters. Notice that in `advice', the `awk' program did not -have single quotes around it. The quotes are only needed for programs -that are provided on the `awk' command line. +don't usually need single quotes around the FN that you specify with +`-f', because most FNs don't contain any of the shell's special +characters. Notice that in `advice', the `awk' program did not have +single quotes around it. The quotes are only needed for programs that +are provided on the `awk' command line. If you want to clearly identify your `awk' program files as such, -you can add the extension `.awk' to the file name. This doesn't affect -the execution of the `awk' program but it does make "housekeeping" -easier. +you can add the extension `.awk' to the FN. This doesn't affect the +execution of the `awk' program but it does make "housekeeping" easier. File: gawk.info, Node: Executable Scripts, Next: Comments, Prev: Long, Up: Running gawk @@ -1561,14 +1560,14 @@ the name of your script (`advice'). (d.c.) Don't rely on the value of (1) The `#!' mechanism works on GNU/Linux systems, BSD-based systems and commercial Unix systems. - (2) The line beginning with `#!' lists the full file name of an -interpreter to run and an optional initial command-line argument to -pass to that interpreter. The operating system then runs the -interpreter with the given argument and the full argument list of the -executed program. The first argument in the list is the full file name -of the `awk' program. The rest of the argument list contains either -options to `awk', or data files, or both. Note that on many systems -`awk' may be found in `/usr/bin' instead of in `/bin'. Caveat Emptor. + (2) The line beginning with `#!' lists the full FN of an interpreter +to run and an optional initial command-line argument to pass to that +interpreter. The operating system then runs the interpreter with the +given argument and the full argument list of the executed program. The +first argument in the list is the full FN of the `awk' program. The +rest of the argument list contains either options to `awk', or data +files, or both. Note that on many systems `awk' may be found in +`/usr/bin' instead of in `/bin'. Caveat Emptor. File: gawk.info, Node: Comments, Next: Quoting, Prev: Executable Scripts, Up: Running gawk @@ -1708,9 +1707,9 @@ the quoting rules. awk -F"" 'PROGRAM' FILES # wrong! In the second case, `awk' will attempt to use the text of the - program as the value of `FS', and the first file name as the text - of the program! This results in syntax errors at best, and - confusing behavior at worst. + program as the value of `FS', and the first FN as the text of the + program! This results in syntax errors at best, and confusing + behavior at worst. Mixing single and double quotes is difficult. You have to resort to shell quoting tricks, like this: @@ -1889,9 +1888,9 @@ description of the program will give you a good idea of what is going on, but please read the rest of the Info file to become an `awk' expert!) Most of the examples use a data file named `data'. This is just a placeholder; if you use these programs yourself, substitute your -own file names for `data'. For future reference, note that there is -often more than one way to do things in `awk'. At some point, you may -want to look back at these examples and see if you can come up with +own FNs for `data'. For future reference, note that there is often +more than one way to do things in `awk'. At some point, you may want +to look back at these examples and see if you can come up with different ways to do the same things shown here: * Print the length of the longest input line: @@ -2035,7 +2034,7 @@ identifies the owner of the file. The fourth field identifies the group of the file. The fifth field contains the size of the file in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the file name.(1) +contains the FN.(1) The `$6 == "Nov"' in our `awk' program is an expression that tests whether the sixth field of the output from `ls -l' matches the string @@ -2349,10 +2348,10 @@ The following list describes options mandated by the POSIX standard: This interpretation of `--' follows the POSIX argument parsing conventions. - This is useful if you have file names that start with `-', or in - shell scripts, if you have file names that will be specified by - the user that could start with `-'. It is also useful for passing - options on to the `awk' program; see *note Getopt Function::. + This is useful if you have FNs that start with `-', or in shell + scripts, if you have FNs that will be specified by the user that + could start with `-'. It is also useful for passing options on to + the `awk' program; see *note Getopt Function::. The following list describes `gawk'-specific options: @@ -2517,8 +2516,8 @@ The following list describes options mandated by the POSIX standard: Enable pretty-printing of `awk' programs. By default, output program is created in a file named `awkprof.out' (*note Profiling::). The optional FILE argument allows you to specify a - different file name for the output. No space is allowed between - the `-o' and FILE, if FILE is supplied. + different FN for the output. No space is allowed between the `-o' + and FILE, if FILE is supplied. NOTE: Due to the way `gawk' has evolved, with this option your program is still executed. This will change in the next @@ -2534,9 +2533,9 @@ The following list describes options mandated by the POSIX standard: `--profile'[`='FILE] Enable profiling of `awk' programs (*note Profiling::). By default, profiles are created in a file named `awkprof.out'. The - optional FILE argument allows you to specify a different file name - for the profile file. No space is allowed between the `-p' and - FILE, if FILE is supplied. + optional FILE argument allows you to specify a different FN for + the profile file. No space is allowed between the `-p' and FILE, + if FILE is supplied. The profile contains execution counts for each statement in the program in the left margin, and function call counts for each @@ -2677,11 +2676,11 @@ arguments, including variable assignments, are included. As each element of `ARGV' is processed, `gawk' sets the variable `ARGIND' to the index in `ARGV' of the current element. - The distinction between file name arguments and variable-assignment + The distinction between FN arguments and variable-assignment arguments is made when `awk' is about to open the next input file. At -that point in execution, it checks the file name to see whether it is -really a variable assignment; if so, `awk' sets the variable instead of -reading a file. +that point in execution, it checks the FN to see whether it is really a +variable assignment; if so, `awk' sets the variable instead of reading +a file. Therefore, the variables actually receive the given values after all previously specified files have been read. In particular, the values of @@ -2693,13 +2692,13 @@ begins scanning the argument list. escape sequences (*note Escape Sequences::). (d.c.) In some very early implementations of `awk', when a variable -assignment occurred before any file names, the assignment would happen -_before_ the `BEGIN' rule was executed. `awk''s behavior was thus -inconsistent; some command-line assignments were available inside the -`BEGIN' rule, while others were not. Unfortunately, some applications -came to depend upon this "feature." When `awk' was changed to be more -consistent, the `-v' option was added to accommodate applications that -depended upon the old behavior. +assignment occurred before any FNs, the assignment would happen _before_ +the `BEGIN' rule was executed. `awk''s behavior was thus inconsistent; +some command-line assignments were available inside the `BEGIN' rule, +while others were not. Unfortunately, some applications came to depend +upon this "feature." When `awk' was changed to be more consistent, the +`-v' option was added to accommodate applications that depended upon +the old behavior. The variable assignment feature is most useful for assigning to variables such as `RS', `OFS', and `ORS', which control input and @@ -2735,11 +2734,11 @@ SOME_COMMAND, and finally it reads `file2'. You may also use `"-"' to name standard input when reading files with `getline' (*note Getline/File::). - In addition, `gawk' allows you to specify the special file name + In addition, `gawk' allows you to specify the special FN `/dev/stdin', both on the command line and with `getline'. Some other versions of `awk' also support this, but it is not standard. (Some operating systems provide a `/dev/stdin' file in the file system; -however, `gawk' always processes this file name itself.) +however, `gawk' always processes this FN itself.) File: gawk.info, Node: Environment Variables, Next: Exit Status, Prev: Naming Standard Input, Up: Invoking Gawk @@ -2767,7 +2766,7 @@ The previous minor node described how `awk' program files can be named 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 +the FN supplied to the `-f' or `-i' options does not contain a directory separator `/', then `gawk' searches a list of directories (called the "search path"), one by one, looking for a file with the specified name. @@ -2780,8 +2779,8 @@ variable. If that variable does not exist, `gawk' uses a default path, The search path feature is particularly helpful for building libraries of useful `awk' functions. The library files can be placed in a standard directory in the default path and then specified on the -command line with a short file name. Otherwise, the full file name -would have to be typed for each file. +command line with a short FN. Otherwise, the full FN would have to be +typed for each file. By using the `-i' option, or the `--source' and `-f' options, your command-line `awk' programs can use facilities in `awk' library files @@ -2790,8 +2789,8 @@ in compatibility mode. This is true for both `--traditional' and `--posix'. *Note Options::. If the source code is not found after the initial search, the path -is searched again after adding the default `.awk' suffix to the -filename. +is searched again after adding the default `.awk' suffix to the file +name. NOTE: To include the current directory in the path, either place `.' explicitly in the path or write a null entry in the path. (A @@ -2989,8 +2988,8 @@ and here is `test2': use `@include' followed by the name of the file to be included, enclosed in double quotes. - NOTE: Keep in mind that this is a language construct and the file - name cannot be a string variable, but rather just a literal string + NOTE: Keep in mind that this is a language construct and the FN + cannot be a string variable, but rather just a literal string constant in double quotes. The files to be included may be nested; e.g., given a third script, @@ -3008,7 +3007,7 @@ Running `gawk' with the `test3' script produces the following results: -| This is file test2. -| This is file test3. - The file name can, of course, be a pathname. For example: + The FN can, of course, be a pathname. For example: @include "../io_funcs" @@ -3060,8 +3059,8 @@ The `AWKLIBPATH' variable is used to search for the extension. Using If the extension is not initially found in `AWKLIBPATH', another search is conducted after appending the platform's default shared -library suffix to the filename. For example, on GNU/Linux systems, the -suffix `.so' is used. +library suffix to the file name. For example, on GNU/Linux systems, +the suffix `.so' is used. $ gawk '@load "ordchr"; BEGIN {print chr(65)}' -| A @@ -5319,11 +5318,11 @@ File: gawk.info, Node: Getline/File, Next: Getline/Variable/File, Prev: Getli --------------------------------- Use `getline < FILE' to read the next record from FILE. Here FILE is a -string-valued expression that specifies the file name. `< FILE' is -called a "redirection" because it directs input to come from a -different place. For example, the following program reads its input -record from the file `secondary.input' when it encounters a first field -with a value equal to 10 in the current input file: +string-valued expression that specifies the FN. `< FILE' is called a +"redirection" because it directs input to come from a different place. +For example, the following program reads its input record from the file +`secondary.input' when it encounters a first field with a value equal +to 10 in the current input file: { if ($1 == 10) { @@ -5756,8 +5755,8 @@ OFMT::.) For printing with specifications, you need the `printf' statement (*note Printf::). Besides basic and formatted printing, this major node also covers -I/O redirections to files and pipes, introduces the special file names -that `gawk' processes internally, and discusses the `close()' built-in +I/O redirections to files and pipes, introduces the special FNs that +`gawk' processes internally, and discusses the `close()' built-in function. * Menu: @@ -6393,9 +6392,8 @@ work identically for `printf': `print ITEMS > OUTPUT-FILE' This redirection prints the items into the output file named - OUTPUT-FILE. The file name OUTPUT-FILE can be any expression. - Its value is changed to a string and then used as a file name - (*note Expressions::). + OUTPUT-FILE. The FN OUTPUT-FILE can be any expression. Its value + is changed to a string and then used as a FN (*note Expressions::). When this type of redirection is used, the OUTPUT-FILE is erased before the first output is written to it. Subsequent writes to @@ -6513,9 +6511,9 @@ underlying operating system permits. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, `sh'. For example, suppose you -have a list of files brought over from a system where all the file names -are stored in uppercase, and you wish to rename them to have names in -all lowercase. The following program is both simple and efficient: +have a list of files brought over from a system where all the FNs are +stored in uppercase, and you wish to rename them to have names in all +lowercase. The following program is both simple and efficient: { printf("mv %s %s\n", $0, tolower($0)) | "sh" } @@ -6529,12 +6527,12 @@ to rename the files. It then sends the list to the shell for execution. File: gawk.info, Node: Special Files, Next: Close Files And Pipes, Prev: Redirection, Up: Printing -5.7 Special File Names in `gawk' -================================ +5.7 Special File Name in `gawk' +=============================== -`gawk' provides a number of special file names that it interprets -internally. These file names provide access to standard file -descriptors and TCP/IP networking. +`gawk' provides a number of special FNs that it interprets internally. +These FNs provide access to standard file descriptors and TCP/IP +networking. * Menu: @@ -6580,13 +6578,13 @@ happens, writing to the screen is not correct. In fact, if `awk' is run from a background job, it may not have a terminal at all. Then opening `/dev/tty' fails. - `gawk' provides special file names for accessing the three standard + `gawk' provides special FNs for accessing the three standard streams. (c.e.) It also provides syntax for accessing any other -inherited open files. If the file name matches one of these special -names when `gawk' redirects input or output, then it directly uses the -stream that the file name stands for. These special file names work -for all operating systems that `gawk' has been ported to, not just -those that are POSIX-compliant: +inherited open files. If the FN matches one of these special names +when `gawk' redirects input or output, then it directly uses the stream +that the FN stands for. These special FNs work for all operating +systems that `gawk' has been ported to, not just those that are +POSIX-compliant: `/dev/stdin' The standard input (file descriptor 0). @@ -6603,18 +6601,18 @@ those that are POSIX-compliant: the shell). Unless special pains are taken in the shell from which `gawk' is invoked, only descriptors 0, 1, and 2 are available. - The file names `/dev/stdin', `/dev/stdout', and `/dev/stderr' are -aliases for `/dev/fd/0', `/dev/fd/1', and `/dev/fd/2', respectively. -However, they are more self-explanatory. The proper way to write an -error message in a `gawk' program is to use `/dev/stderr', like this: + The FNs `/dev/stdin', `/dev/stdout', and `/dev/stderr' are aliases +for `/dev/fd/0', `/dev/fd/1', and `/dev/fd/2', respectively. However, +they are more self-explanatory. The proper way to write an error +message in a `gawk' program is to use `/dev/stderr', like this: print "Serious error detected!" > "/dev/stderr" - Note the use of quotes around the file name. Like any other -redirection, the value must be a string. It is a common error to omit -the quotes, which leads to confusing results. + Note the use of quotes around the FN. Like any other redirection, +the value must be a string. It is a common error to omit the quotes, +which leads to confusing results. - Finally, using the `close()' function on a file name of the form + Finally, using the `close()' function on a FN of the form `"/dev/fd/N"', for file descriptor numbers above two, does actually close the given file descriptor. @@ -6632,16 +6630,15 @@ File: gawk.info, Node: Special Network, Next: Special Caveats, Prev: Special ---------------------------------------------- `gawk' programs can open a two-way TCP/IP connection, acting as either -a client or a server. This is done using a special file name of the -form: +a client or a server. This is done using a special FN of the form: `/NET-TYPE/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT' The NET-TYPE is one of `inet', `inet4' or `inet6'. The PROTOCOL is one of `tcp' or `udp', and the other fields represent the other essential pieces of information for making a networking connection. -These file names are used with the `|&' operator for communicating with -a coprocess (*note Two-way I/O::). This is an advanced feature, +These FNs are used with the `|&' operator for communicating with a +coprocess (*note Two-way I/O::). This is an advanced feature, mentioned here only for completeness. Full discussion is delayed until *note TCP/IP Networking::. @@ -6651,15 +6648,15 @@ File: gawk.info, Node: Special Caveats, Prev: Special Network, Up: Special Fi 5.7.3 Special File Name Caveats ------------------------------- -Here is a list of things to bear in mind when using the special file -names that `gawk' provides: +Here is a list of things to bear in mind when using the special FNs +that `gawk' provides: - * Recognition of these special file names is disabled if `gawk' is in + * Recognition of these special FNs is disabled if `gawk' is in compatibility mode (*note Options::). - * `gawk' _always_ interprets these special file names. For example, - using `/dev/fd/4' for output actually writes on file descriptor 4, - and not on a new file descriptor that is `dup()''ed from file + * `gawk' _always_ interprets these special FNs. For example, using + `/dev/fd/4' for output actually writes on file descriptor 4, and + not on a new file descriptor that is `dup()''ed from file descriptor 4. Most of the time this does not matter; however, it is important to _not_ close any of the files related to file descriptors 0, 1, and 2. Doing so results in unpredictable @@ -6671,17 +6668,17 @@ File: gawk.info, Node: Close Files And Pipes, Prev: Special Files, Up: Printi 5.8 Closing Input and Output Redirections ========================================= -If the same file name or the same shell command is used with `getline' -more than once during the execution of an `awk' program (*note -Getline::), the file is opened (or the command is executed) the first -time only. At that time, the first record of input is read from that -file or command. The next time the same file or command is used with -`getline', another record is read from it, and so on. +If the same FN or the same shell command is used with `getline' more +than once during the execution of an `awk' program (*note Getline::), +the file is opened (or the command is executed) the first time only. +At that time, the first record of input is read from that file or +command. The next time the same file or command is used with `getline', +another record is read from it, and so on. Similarly, when a file or pipe is opened for output, `awk' remembers -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 `awk' exits. +the FN 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 `awk' exits. 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 @@ -6710,8 +6707,8 @@ file or command, or the next `print' or `printf' to that file or command, reopens the file or reruns the command. Because the expression that you use to close a file or pipeline must exactly match the expression used to open the file or run the command, it is good -practice to use a variable to store the file name or command. The -previous example becomes the following: +practice to use a variable to store the FN or command. The previous +example becomes the following: sortcom = "sort -r names" sortcom | getline foo @@ -7166,11 +7163,11 @@ option, as in the following: the variable is set at the very beginning, even before the `BEGIN' rules execute. The `-v' option and its assignment must precede all the -file name arguments, as well as the program text. (*Note Options::, -for more information about the `-v' option.) Otherwise, the variable -assignment is performed at a time determined by its position among the -input file arguments--after the processing of the preceding input file -argument. For example: +FN arguments, as well as the program text. (*Note Options::, for more +information about the `-v' option.) Otherwise, the variable assignment +is performed at a time determined by its position among the input file +arguments--after the processing of the preceding input file argument. +For example: awk '{ print $n }' n=4 inventory-shipped n=2 mail-list @@ -9793,14 +9790,13 @@ Options::), they are not special. `ARGIND #' The index in `ARGV' of the current file being processed. Every time `gawk' opens a new data file for processing, it sets `ARGIND' - to the index in `ARGV' of the file name. When `gawk' is - processing the input files, `FILENAME == ARGV[ARGIND]' is always - true. + to the index in `ARGV' of the FN. When `gawk' is processing the + input files, `FILENAME == ARGV[ARGIND]' is always true. This variable is useful in file processing; it allows you to tell how far along you are in the list of data files as well as to - distinguish between successive instances of the same file name on - the command line. + distinguish between successive instances of the same FN on the + command line. While you can change the value of `ARGIND' within your `awk' program, `gawk' automatically sets it to a new value when the next @@ -10127,13 +10123,13 @@ incrementing `ARGC' causes additional files to be read. If the value of `ARGC' is decreased, that eliminates input files from the end of the list. By recording the old value of `ARGC' elsewhere, a program can treat the eliminated arguments as something -other than file names. +other than FNs. To eliminate a file from the middle of the list, store the null string (`""') into `ARGV' in place of the file's name. As a special -feature, `awk' ignores file names that have been replaced with the null -string. Another option is to use the `delete' statement to remove -elements from `ARGV' (*note Delete::). +feature, `awk' ignores FNs that have been replaced with the null string. +Another option is to use the `delete' statement to remove elements from +`ARGV' (*note Delete::). All of these actions are typically done in the `BEGIN' rule, before actual processing of the input begins. *Note Split Program::, and see @@ -14411,16 +14407,16 @@ does so _portably_; this works with any implementation of `awk': the rule it supplies is executed first. This rule relies on `awk''s `FILENAME' variable that automatically -changes for each new data file. The current file name is saved in a -private variable, `_oldfilename'. If `FILENAME' does not equal -`_oldfilename', then a new data file is being processed and it is -necessary to call `endfile()' for the old file. Because `endfile()' -should only be called if a file has been processed, the program first -checks to make sure that `_oldfilename' is not the null string. The -program then assigns the current file name to `_oldfilename' and calls -`beginfile()' for the file. Because, like all `awk' variables, -`_oldfilename' is initialized to the null string, this rule executes -correctly even for the first data file. +changes for each new data file. The current FN is saved in a private +variable, `_oldfilename'. If `FILENAME' does not equal `_oldfilename', +then a new data file is being processed and it is necessary to call +`endfile()' for the old file. Because `endfile()' should only be +called if a file has been processed, the program first checks to make +sure that `_oldfilename' is not the null string. The program then +assigns the current FN to `_oldfilename' and calls `beginfile()' for +the file. Because, like all `awk' variables, `_oldfilename' is +initialized to the null string, this rule executes correctly even for +the first data file. The program also supplies an `END' rule to do the final processing for the last file. Because this `END' rule comes before any `END' rules @@ -14557,8 +14553,8 @@ program code. possible to detect when an empty data file has been skipped. Similar to the library file presented in *note Filetrans Function::, the following library file calls a function named `zerofile()' that the -user must provide. The arguments passed are the file name and the -position in `ARGV' where it was found: +user must provide. The arguments passed are the FN and the position in +`ARGV' where it was found: # zerofile.awk --- library file to process empty input files @@ -14599,13 +14595,13 @@ intervening value in `ARGV' is a variable assignment. File: gawk.info, Node: Ignoring Assigns, Prev: Empty Files, Up: Data File Management -10.3.5 Treating Assignments as File Names ------------------------------------------ +10.3.5 Treating Assignments as File Name +---------------------------------------- Occasionally, you might not want `awk' to process command-line variable assignments (*note Assignment Options::). In particular, if you have a -file name that contains an `=' character, `awk' treats the file name as -an assignment, and does not process it. +FN that contains an `=' character, `awk' treats the FN as an +assignment, and does not process it. Some users have suggested an additional command-line option for `gawk' to disable command-line assignments. However, some simple @@ -14632,7 +14628,7 @@ programming with a library file does the trick: The function works by looping through the arguments. It prepends `./' to any argument that matches the form of a variable assignment, -turning that argument into a file name. +turning that argument into a FN. The use of `No_command_assign' allows you to disable command-line assignments at invocation time, by giving the variable a true value. @@ -14921,7 +14917,7 @@ that it does not try to interpret the `-a', etc., as its own options. NOTE: After `getopt()' is through, it is the responsibility of the user level code to clear out all the elements of `ARGV' from 1 to `Optind', so that `awk' does not try to process the command-line - options as file names. + options as FNs. Several of the sample programs presented in *note Sample Programs::, use `getopt()' to process their arguments. @@ -15640,7 +15636,7 @@ by characters, the output field separator is set to the null string: OFS = "" } else if (c == "d") { if (length(Optarg) > 1) { - printf("Using first character of %s" \ + printf("cut: using first character of %s" \ " for delimiter\n", Optarg) > "/dev/stderr" Optarg = substr(Optarg, 1, 1) } @@ -15665,7 +15661,7 @@ we want them to be separated with individual spaces. Also remember that after `getopt()' is through (as described in *note Getopt Function::), we have to clear out all the elements of `ARGV' from 1 to `Optind', so that `awk' does not try to process the command-line options -as file names. +as FNs. After dealing with the command-line options, the program verifies that the options make sense. Only one or the other of `-c' and `-f' @@ -15707,7 +15703,7 @@ splitting: if (index(f[i], "-") != 0) { # a range m = split(f[i], g, "-") if (m != 2 || g[1] >= g[2]) { - printf("bad field list: %s\n", + printf("cut: bad field list: %s\n", f[i]) > "/dev/stderr" exit 1 } @@ -15745,7 +15741,7 @@ filler fields: if (index(f[i], "-") != 0) { # range m = split(f[i], g, "-") if (m != 2 || g[1] >= g[2]) { - printf("bad character list: %s\n", + printf("cut: bad character list: %s\n", f[i]) > "/dev/stderr" exit 1 } @@ -15822,10 +15818,9 @@ expressions that are almost identical to those available in `awk' The PATTERN is a regular expression. In typical usage, the regular expression is quoted to prevent the shell from expanding any of the -special characters as file name wildcards. Normally, `egrep' prints -the lines that matched. If multiple file names are provided on the -command line, each output line is preceded by the name of the file and -a colon. +special characters as FN wildcards. Normally, `egrep' prints the lines +that matched. If multiple FNs are provided on the command line, each +output line is preceded by the name of the file and a colon. The options to `egrep' are as follows: @@ -15897,8 +15892,8 @@ pattern is supplied with `-e', the first nonoption on the command line is used. The `awk' command-line arguments up to `ARGV[Optind]' are cleared, so that `awk' won't try to process them as files. If no files are specified, the standard input is used, and if multiple files are -specified, we make sure to note this so that the file names can precede -the matched lines in the output: +specified, we make sure to note this so that the FNs can precede the +matched lines in the output: if (pattern == "") pattern = ARGV[Optind++] @@ -15979,9 +15974,9 @@ just moves on to the next record. are not counting lines. First, if the user only wants exit status (`no_print' is true), then it is enough to know that _one_ line in this file matched, and we can skip on to the next file with `nextfile'. -Similarly, if we are only printing file names, we can print the file -name, and then skip to the next file with `nextfile'. Finally, each -line is printed, with a leading file name and colon if necessary: +Similarly, if we are only printing FNs, we can print the FN, and then +skip to the next file with `nextfile'. Finally, each line is printed, +with a leading FN and colon if necessary: { matches = ($0 ~ pattern) @@ -16167,7 +16162,7 @@ To change the number of lines in each file, supply a number on the command line preceded with a minus; e.g., `-500' for files with 500 lines in them instead of 1000. To change the name of the output files to something like `myfileaa', `myfileab', and so on, supply an -additional argument that specifies the file name prefix. +additional argument that specifies the FN prefix. Here is a version of `split' in `awk'. It uses the `ord()' and `chr()' functions presented in *note Ordinal Functions::. @@ -16892,7 +16887,7 @@ alarm: # how long to sleep for naptime = target - current if (naptime <= 0) { - print "time is in the past!" > "/dev/stderr" + print "alarm: time is in the past!" > "/dev/stderr" exit 1 } @@ -17394,7 +17389,7 @@ with a zero exit status, signifying OK: /^@c(omment)?[ \t]+system/ \ { if (NF < 3) { - e = (FILENAME ":" FNR) + e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") print e > "/dev/stderr" next @@ -17403,7 +17398,7 @@ with a zero exit status, signifying OK: $2 = "" stat = system($0) if (stat != 0) { - e = (FILENAME ":" FNR) + e = ("extract: " FILENAME ":" FNR) e = (e ": warning: system returned " stat) print e > "/dev/stderr" } @@ -17443,7 +17438,7 @@ output file: /^@c(omment)?[ \t]+file/ \ { if (NF != 3) { - e = (FILENAME ":" FNR ": badly formed `file' line") + e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" next } @@ -17494,7 +17489,7 @@ closing the open file: function unexpected_eof() { - printf("%s:%d: unexpected EOF or error\n", + printf("extract: %s:%d: unexpected EOF or error\n", FILENAME, FNR) > "/dev/stderr" exit 1 } @@ -17874,7 +17869,7 @@ zero, the program is done: } fpath = pathto($2) if (fpath == "") { - printf("igawk:%s:%d: cannot find %s\n", + printf("igawk: %s:%d: cannot find %s\n", input[stackptr], FNR, $2) > "/dev/stderr" continue } @@ -19556,8 +19551,8 @@ File: gawk.info, Node: Gawk I18N, Prev: I18N Example, Up: Internationalizatio `gawk' itself has been internationalized using the GNU `gettext' package. (GNU `gettext' is described in complete detail in *note (GNU `gettext' utilities)Top:: gettext, GNU gettext tools.) As of this -writing, the latest version of GNU `gettext' is version 0.18.2.1 -(ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz). +writing, the latest version of GNU `gettext' is version 0.19 +(ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.tar.gz). If a translation of `gawk''s messages exists, then `gawk' produces usage messages, warnings, and fatal errors in the local language. @@ -22784,7 +22779,7 @@ structures as described earlier. `awk_bool_t (*can_take_two_way)(const char *name);' This function returns true if it wants to take over two-way I/O - for this filename. It should not change any state (variable + for this file name. It should not change any state (variable values, etc.) within `gawk'. `awk_bool_t (*take_control_of)(const char *name,' @@ -24542,7 +24537,7 @@ requested hierarchies. The arguments are as follows: `pathlist' - An array of filenames. The element values are used; the index + An array of file names. The element values are used; the index values are ignored. `flags' @@ -24658,10 +24653,10 @@ constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. The arguments to `fnmatch()' are: `pattern' - The filename wildcard to match. + The FN wildcard to match. `string' - The filename string. + The FN string. `flag' Either zero, or the bitwise OR of one or more of the flags in the @@ -24753,8 +24748,8 @@ standard output to a temporary file configured to have the same owner and permissions as the original. After the file has been processed, the extension restores standard output to its original destination. If `INPLACE_SUFFIX' is not an empty string, the original file is linked to -a backup filename created by appending that suffix. Finally, the -temporary file is renamed to the original filename. +a backup FN created by appending that suffix. Finally, the temporary +file is renamed to the original FN. If any error occurs, the extension issues a fatal error to terminate processing immediately without damaging the original file. @@ -24814,9 +24809,9 @@ on the command line (or with `getline'), they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode -number and the filename, separated by a forward slash character. On -systems where the directory entry contains the file type, the record -has a third field (also separated by a slash) which is a single letter +number and the FN, separated by a forward slash character. On systems +where the directory entry contains the file type, the record has a +third field (also separated by a slash) which is a single letter indicating the type of the file. The letters are file types are shown in *note table-readdir-file-types::. @@ -26903,8 +26898,8 @@ or: $ MMK/DESCRIPTION=[.vms]descrip.mms gawk `MMK' is an open source, free, near-clone of `MMS' and can better -handle ODS-5 volumes with upper- and lowercase filenames. `MMK' is -available from `https://github.com/endlesssoftware/mmk'. +handle ODS-5 volumes with upper- and lowercase FNs. `MMK' is available +from `https://github.com/endlesssoftware/mmk'. With ODS-5 volumes and extended parsing enabled, the case of the target parameter may need to be exact. @@ -27024,9 +27019,9 @@ has no device or directory path information in it, `gawk' looks in the current directory first, then in the directory specified by the translation of `AWK_LIBRARY' if the file is not found. If, after searching in both directories, the file still is not found, `gawk' -appends the suffix `.awk' to the filename and retries the file search. -If `AWK_LIBRARY' has no definition, a default value of `SYS$LIBRARY:' -is used for it. +appends the suffix `.awk' to the FN and retries the file search. If +`AWK_LIBRARY' has no definition, a default value of `SYS$LIBRARY:' is +used for it. File: gawk.info, Node: VMS Running, Next: VMS GNV, Prev: VMS Installation Details, Up: VMS Installation @@ -30145,7 +30140,7 @@ Index * Menu: * ! (exclamation point), ! operator: Boolean Ops. (line 67) -* ! (exclamation point), ! operator <1>: Egrep Program. (line 175) +* ! (exclamation point), ! operator <1>: Egrep Program. (line 174) * ! (exclamation point), ! operator <2>: Ranges. (line 48) * ! (exclamation point), ! operator: Precedence. (line 52) * ! (exclamation point), != operator <1>: Precedence. (line 65) @@ -30340,7 +30335,7 @@ Index * > (right angle bracket), >= operator: Comparison Operators. (line 11) * > (right angle bracket), >> operator (I/O) <1>: Precedence. (line 65) -* > (right angle bracket), >> operator (I/O): Redirection. (line 50) +* > (right angle bracket), >> operator (I/O): Redirection. (line 49) * ? (question mark), ?: operator: Precedence. (line 92) * ? (question mark), regexp operator <1>: GNU Regexp Operators. (line 59) @@ -30381,7 +30376,7 @@ Index (line 38) * \ (backslash), as field separator: Command Line Field Separator. (line 27) -* \ (backslash), continuing lines and <1>: Egrep Program. (line 223) +* \ (backslash), continuing lines and <1>: Egrep Program. (line 222) * \ (backslash), continuing lines and: Statements/Lines. (line 19) * \ (backslash), continuing lines and, comments and: Statements/Lines. (line 76) @@ -30588,7 +30583,7 @@ Index * awk, gawk and <1>: This Manual. (line 14) * awk, gawk and: Preface. (line 23) * awk, history of: History. (line 17) -* awk, implementation issues, pipes: Redirection. (line 135) +* awk, implementation issues, pipes: Redirection. (line 134) * awk, implementations: Other Versions. (line 6) * awk, implementations, limits: Getline Notes. (line 14) * awk, invoking: Command Line. (line 6) @@ -30655,7 +30650,7 @@ Index (line 38) * backslash (\), as field separator: Command Line Field Separator. (line 27) -* backslash (\), continuing lines and <1>: Egrep Program. (line 223) +* backslash (\), continuing lines and <1>: Egrep Program. (line 222) * backslash (\), continuing lines and: Statements/Lines. (line 19) * backslash (\), continuing lines and, comments and: Statements/Lines. (line 76) @@ -30966,7 +30961,7 @@ Index (line 6) * cookie: Glossary. (line 149) * coprocesses <1>: Two-way I/O. (line 44) -* coprocesses: Redirection. (line 102) +* coprocesses: Redirection. (line 101) * coprocesses, closing: Close Files And Pipes. (line 6) * coprocesses, getline from: Getline/Coprocess. (line 6) @@ -31009,9 +31004,9 @@ Index * dark corner, exit statement: Exit Statement. (line 30) * dark corner, field separators: Field Splitting Summary. (line 46) -* dark corner, FILENAME variable <1>: Auto-set. (line 90) +* dark corner, FILENAME variable <1>: Auto-set. (line 89) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 301) +* dark corner, FNR/NR variables: Auto-set. (line 300) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) @@ -31195,25 +31190,25 @@ Index (line 81) * differences in awk and gawk, command line directories: Command line directories. (line 6) -* differences in awk and gawk, ERRNO variable: Auto-set. (line 74) +* differences in awk and gawk, ERRNO variable: Auto-set. (line 73) * differences in awk and gawk, error messages: Special FD. (line 16) * differences in awk and gawk, FIELDWIDTHS variable: User-modified. (line 37) * differences in awk and gawk, FPAT variable: User-modified. (line 43) -* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 115) +* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 114) * differences in awk and gawk, function arguments (gawk): Calling Built-in. (line 16) * differences in awk and gawk, getline command: Getline. (line 19) * differences in awk and gawk, IGNORECASE variable: User-modified. (line 76) * differences in awk and gawk, implementation limitations <1>: Redirection. - (line 135) + (line 134) * differences in awk and gawk, implementation limitations: Getline Notes. (line 14) * differences in awk and gawk, indirect function calls: Indirect Calls. (line 6) * differences in awk and gawk, input/output operators <1>: Redirection. - (line 102) + (line 101) * differences in awk and gawk, input/output operators: Getline/Coprocess. (line 6) * differences in awk and gawk, line continuations: Conditional Exp. @@ -31223,7 +31218,7 @@ Index (line 260) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) -* differences in awk and gawk, PROCINFO array: Auto-set. (line 128) +* differences in awk and gawk, PROCINFO array: Auto-set. (line 127) * differences in awk and gawk, read timeouts: Read Timeout. (line 6) * differences in awk and gawk, record separators: awk split records. (line 124) @@ -31233,7 +31228,7 @@ Index (line 26) * differences in awk and gawk, RS/RT variables: gawk split records. (line 58) -* differences in awk and gawk, RT variable: Auto-set. (line 257) +* differences in awk and gawk, RT variable: Auto-set. (line 256) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. @@ -31241,7 +31236,7 @@ Index * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: gawk split records. (line 77) -* differences in awk and gawk, SYMTAB variable: Auto-set. (line 261) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 260) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 152) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. @@ -31282,11 +31277,11 @@ Index * 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 133) -* effective user ID of gawk user: Auto-set. (line 137) +* effective group ID of gawk user: Auto-set. (line 132) +* effective user ID of gawk user: Auto-set. (line 136) * egrep utility <1>: Egrep Program. (line 6) * egrep utility: Bracket Expressions. (line 24) -* egrep.awk program: Egrep Program. (line 54) +* egrep.awk program: Egrep Program. (line 53) * elements in arrays, assigning values: Assigning Elements. (line 6) * elements in arrays, deleting: Delete. (line 6) * elements in arrays, order of access by in operator: Scanning an Array. @@ -31311,7 +31306,7 @@ Index * 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 223) +* END pattern, backslash continuation and: Egrep Program. (line 222) * 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. @@ -31327,10 +31322,10 @@ Index * endgrent() user-defined function: Group Functions. (line 216) * endpwent() function (C library): Passwd Functions. (line 210) * endpwent() user-defined function: Passwd Functions. (line 213) -* ENVIRON array: Auto-set. (line 60) +* ENVIRON array: Auto-set. (line 59) * environment variables used by gawk: Environment Variables. (line 6) -* environment variables, in ENVIRON array: Auto-set. (line 60) +* environment variables, in ENVIRON array: Auto-set. (line 59) * epoch, definition of: Glossary. (line 234) * equals sign (=), = operator: Assignment Ops. (line 6) * equals sign (=), == operator <1>: Precedence. (line 65) @@ -31338,13 +31333,13 @@ Index (line 11) * EREs (Extended Regular Expressions): Bracket Expressions. (line 24) * ERRNO variable <1>: TCP/IP Networking. (line 54) -* ERRNO variable: Auto-set. (line 74) +* ERRNO variable: Auto-set. (line 73) * ERRNO variable, with BEGINFILE pattern: BEGINFILE/ENDFILE. (line 26) * ERRNO variable, with close() function: Close Files And Pipes. (line 139) * ERRNO variable, with getline command: Getline. (line 19) * error handling: Special FD. (line 16) -* error handling, ERRNO variable and: Auto-set. (line 74) +* error handling, ERRNO variable and: Auto-set. (line 73) * error output: Special FD. (line 6) * escape processing, gsub()/gensub()/sub() functions: Gory Details. (line 6) @@ -31357,7 +31352,7 @@ Index * evaluation order, concatenation: Concatenation. (line 41) * evaluation order, functions: Calling Built-in. (line 30) * examining fields: Fields. (line 6) -* exclamation point (!), ! operator <1>: Egrep Program. (line 175) +* exclamation point (!), ! operator <1>: Egrep Program. (line 174) * exclamation point (!), ! operator <2>: Precedence. (line 52) * exclamation point (!), ! operator: Boolean Ops. (line 67) * exclamation point (!), != operator <1>: Precedence. (line 65) @@ -31398,7 +31393,7 @@ Index (line 6) * extension API version: Extension Versioning. (line 6) -* extension API, version number: Auto-set. (line 224) +* extension API, version number: Auto-set. (line 223) * extension example: Extension Example. (line 6) * extension registration: Registration Functions. (line 6) @@ -31474,10 +31469,10 @@ Index * FIELDWIDTHS variable <1>: User-modified. (line 37) * FIELDWIDTHS variable: Constant Size. (line 23) * file descriptors: Special FD. (line 6) -* file names, distinguishing: Auto-set. (line 56) +* file names, distinguishing: Auto-set. (line 55) * file names, in compatibility mode: Special Caveats. (line 9) * file names, standard streams in gawk: Special FD. (line 46) -* FILENAME variable <1>: Auto-set. (line 90) +* FILENAME variable <1>: Auto-set. (line 89) * FILENAME variable: Reading Files. (line 6) * FILENAME variable, getline, setting with: Getline Notes. (line 19) * filenames, assignments as: Ignoring Assigns. (line 6) @@ -31523,7 +31518,7 @@ Index * files, portable object, converting to message object files: I18N Example. (line 63) * files, portable object, generating: Options. (line 147) -* files, processing, ARGIND variable and: Auto-set. (line 51) +* files, processing, ARGIND variable and: Auto-set. (line 50) * files, reading: Rewind Function. (line 6) * files, reading, multiline records: Multiple Line. (line 6) * files, searching for regular expressions: Egrep Program. (line 6) @@ -31547,9 +31542,9 @@ Index * flush buffered output: I/O Functions. (line 28) * fnmatch() extension function: Extension Sample Fnmatch. (line 12) -* FNR variable <1>: Auto-set. (line 99) +* FNR variable <1>: Auto-set. (line 98) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 301) +* FNR variable, changing: Auto-set. (line 300) * for statement: For Statement. (line 6) * for statement, looping over arrays: Scanning an Array. (line 20) * fork() extension function: Extension Sample Fork. @@ -31599,7 +31594,7 @@ Index * FSF (Free Software Foundation): Manual History. (line 6) * fts() extension function: Extension Sample File Functions. (line 61) -* FUNCTAB array: Auto-set. (line 115) +* FUNCTAB array: Auto-set. (line 114) * function calls: Function Calls. (line 6) * function calls, indirect: Indirect Calls. (line 6) * function definition example: Function Example. (line 6) @@ -31649,7 +31644,7 @@ Index * G-d: Acknowledgments. (line 78) * Garfinkle, Scott: Contributors. (line 34) * gawk program, dynamic profiling: Profiling. (line 179) -* gawk version: Auto-set. (line 199) +* gawk version: Auto-set. (line 198) * gawk, ARGIND variable in: Other Arguments. (line 12) * gawk, awk and <1>: This Manual. (line 14) * gawk, awk and: Preface. (line 23) @@ -31670,7 +31665,7 @@ Index * gawk, distribution: Distribution contents. (line 6) * gawk, ERRNO variable in <1>: TCP/IP Networking. (line 54) -* gawk, ERRNO variable in <2>: Auto-set. (line 74) +* gawk, ERRNO variable in <2>: Auto-set. (line 73) * gawk, ERRNO variable in <3>: BEGINFILE/ENDFILE. (line 26) * gawk, ERRNO variable in <4>: Close Files And Pipes. (line 139) @@ -31687,7 +31682,7 @@ Index * gawk, FPAT variable in <1>: User-modified. (line 43) * gawk, FPAT variable in: Splitting By Content. (line 27) -* gawk, FUNCTAB array in: Auto-set. (line 115) +* gawk, FUNCTAB array in: Auto-set. (line 114) * gawk, function arguments and: Calling Built-in. (line 16) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: Array Sorting Functions. @@ -31701,7 +31696,7 @@ Index * gawk, implementation issues, downward compatibility: Compatibility Mode. (line 6) * gawk, implementation issues, limits: Getline Notes. (line 14) -* gawk, implementation issues, pipes: Redirection. (line 135) +* gawk, implementation issues, pipes: Redirection. (line 134) * gawk, installing: Installation. (line 6) * gawk, internationalization and, See internationalization: Internationalization. (line 13) @@ -31718,7 +31713,7 @@ Index * gawk, OS/2 version of: PC Using. (line 16) * gawk, PROCINFO array in <1>: Two-way I/O. (line 117) * gawk, PROCINFO array in <2>: Time Functions. (line 47) -* gawk, PROCINFO array in: Auto-set. (line 128) +* gawk, PROCINFO array in: Auto-set. (line 127) * gawk, regexp constants and: Using Constant Regexps. (line 28) * gawk, regular expressions, case sensitivity: Case-sensitivity. @@ -31726,14 +31721,14 @@ Index * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 162) -* gawk, RT variable in <1>: Auto-set. (line 257) +* gawk, RT variable in <1>: Auto-set. (line 256) * gawk, RT variable in <2>: Multiple Line. (line 129) * gawk, RT variable in: awk split records. (line 124) * gawk, See Also awk: Preface. (line 36) * gawk, source code, obtaining: Getting. (line 6) * gawk, splitting fields and: Constant Size. (line 88) * gawk, string-translation functions: I18N Functions. (line 6) -* gawk, SYMTAB array in: Auto-set. (line 261) +* gawk, SYMTAB array in: Auto-set. (line 260) * gawk, TEXTDOMAIN variable in: User-modified. (line 152) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 36) @@ -31820,7 +31815,7 @@ Index * 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 172) +* group ID of gawk user: Auto-set. (line 171) * groups, information about: Group Functions. (line 6) * gsub <1>: String Functions. (line 139) * gsub: Using Constant Regexps. @@ -31873,7 +31868,7 @@ Index * Illumos, POSIX-compliant awk: Other Versions. (line 105) * 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 <1>: Redirection. (line 134) * implementation issues, gawk, limits: Getline Notes. (line 14) * in operator <1>: For Statement. (line 75) * in operator <2>: Precedence. (line 83) @@ -32116,7 +32111,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 213) +* maximum precision supported by MPFR library: Auto-set. (line 212) * McIlroy, Doug: Glossary. (line 149) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 42) @@ -32129,7 +32124,7 @@ Index * messages from extensions: Printing Messages. (line 6) * metacharacters in regular expressions: Regexp Operators. (line 6) * metacharacters, escape sequences for: Escape Sequences. (line 130) -* minimum precision supported by MPFR library: Auto-set. (line 216) +* minimum precision supported by MPFR library: Auto-set. (line 215) * mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 104) @@ -32183,7 +32178,7 @@ Index (line 47) * nexti debugger command: Debugger Execution Control. (line 49) -* NF variable <1>: Auto-set. (line 104) +* NF variable <1>: Auto-set. (line 103) * NF variable: Fields. (line 33) * NF variable, decrementing: Changing Fields. (line 107) * ni debugger command (alias for nexti): Debugger Execution Control. @@ -32192,9 +32187,9 @@ Index * non-existent array elements: Reference to Elements. (line 23) * not Boolean-logic operator: Boolean Ops. (line 6) -* NR variable <1>: Auto-set. (line 123) +* NR variable <1>: Auto-set. (line 122) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 301) +* NR variable, changing: Auto-set. (line 300) * null strings <1>: Basic Data Typing. (line 26) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -32302,14 +32297,14 @@ Index (line 6) * output, format specifier, OFMT: OFMT. (line 15) * output, formatted: Printf. (line 6) -* output, pipes: Redirection. (line 57) +* output, pipes: Redirection. (line 56) * output, printing, See printing: Printing. (line 6) * output, records: Output Separators. (line 20) * output, standard: Special FD. (line 6) * p debugger command (alias for print): Viewing And Changing Data. (line 36) * Papadopoulos, Panos: Contributors. (line 129) -* parent process ID of gawk process: Auto-set. (line 181) +* parent process ID of gawk process: Auto-set. (line 180) * parentheses (), in a profile: Profiling. (line 146) * parentheses (), regexp operator: Regexp Operators. (line 80) * password file: Passwd Functions. (line 16) @@ -32339,7 +32334,7 @@ Index * pipe, closing: Close Files And Pipes. (line 6) * pipe, input: Getline/Pipe. (line 9) -* pipe, output: Redirection. (line 57) +* pipe, output: Redirection. (line 56) * Pitts, Dave <1>: Bugs. (line 71) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) @@ -32474,24 +32469,24 @@ Index * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) * private variables: Library Names. (line 11) -* process group idIDof gawk process: Auto-set. (line 175) -* process ID of gawk process: Auto-set. (line 178) +* process group idIDof gawk process: Auto-set. (line 174) +* process ID of gawk process: Auto-set. (line 177) * processes, two-way communications with: Two-way I/O. (line 23) * processing data: Basic High Level. (line 6) * PROCINFO array <1>: Passwd Functions. (line 6) * PROCINFO array <2>: Time Functions. (line 47) -* PROCINFO array: Auto-set. (line 128) +* PROCINFO array: Auto-set. (line 127) * PROCINFO array, and communications via ptys: Two-way I/O. (line 117) * 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 234) +* PROCINFO array, uses: Auto-set. (line 233) * PROCINFO, values of sorted_in: Controlling Scanning. (line 26) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 179) -* program identifiers: Auto-set. (line 146) +* program identifiers: Auto-set. (line 145) * program, definition of: Getting Started. (line 21) * programmers, attractiveness of: Two-way I/O. (line 6) * programming conventions, --non-decimal-data option: Nondecimal Data. @@ -32647,11 +32642,11 @@ Index * right angle bracket (>), >= operator: Comparison Operators. (line 11) * right angle bracket (>), >> operator (I/O) <1>: Precedence. (line 65) -* right angle bracket (>), >> operator (I/O): Redirection. (line 50) +* right angle bracket (>), >> operator (I/O): Redirection. (line 49) * right shift: Bitwise Functions. (line 52) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 54) -* RLENGTH variable: Auto-set. (line 244) +* RLENGTH variable: Auto-set. (line 243) * RLENGTH variable, match() function and: String Functions. (line 224) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) @@ -32680,9 +32675,9 @@ Index * RS variable: awk split records. (line 12) * RS variable, multiline records and: Multiple Line. (line 17) * rshift: Bitwise Functions. (line 52) -* RSTART variable: Auto-set. (line 250) +* RSTART variable: Auto-set. (line 249) * RSTART variable, match() function and: String Functions. (line 224) -* RT variable <1>: Auto-set. (line 257) +* RT variable <1>: Auto-set. (line 256) * RT variable <2>: Multiple Line. (line 129) * RT variable: awk split records. (line 124) * Rubin, Paul <1>: Contributors. (line 15) @@ -32702,7 +32697,7 @@ Index * scanning arrays: Scanning an Array. (line 6) * scanning multidimensional arrays: Multiscanning. (line 11) * Schorr, Andrew <1>: Contributors. (line 134) -* Schorr, Andrew <2>: Auto-set. (line 284) +* Schorr, Andrew <2>: Auto-set. (line 283) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) @@ -32752,7 +32747,7 @@ Index * 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, piping commands into: Redirection. (line 141) * shells, quoting: Using Shell Variables. (line 12) * shells, quoting, rules for: Quoting. (line 18) @@ -32790,7 +32785,7 @@ Index (line 110) * sidebar, Changing FS Does Not Affect the Fields: Field Splitting Summary. (line 38) -* sidebar, Changing NR and FNR: Auto-set. (line 299) +* sidebar, Changing NR and FNR: Auto-set. (line 298) * sidebar, Controlling Output Buffering with system(): I/O Functions. (line 138) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. @@ -32801,7 +32796,7 @@ Index (line 107) * sidebar, Matching the Null String: Gory Details. (line 162) * sidebar, Operator Evaluation Order: Increment Ops. (line 58) -* sidebar, Piping into sh: Redirection. (line 140) +* sidebar, Piping into sh: Redirection. (line 139) * sidebar, Portability Issues with #!: Executable Scripts. (line 31) * sidebar, Recipe For A Programming Language: History. (line 6) * sidebar, RS = "\0" Is Not Portable: gawk split records. (line 63) @@ -32952,9 +32947,9 @@ Index * substr: String Functions. (line 479) * substring: String Functions. (line 479) * Sumner, Andrew: Other Versions. (line 64) -* supplementary groups of gawk process: Auto-set. (line 229) +* supplementary groups of gawk process: Auto-set. (line 228) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 261) +* SYMTAB array: Auto-set. (line 260) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) * system: I/O Functions. (line 75) @@ -33038,7 +33033,7 @@ Index * troubleshooting, match() function: String Functions. (line 289) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) -* troubleshooting, printing: Redirection. (line 118) +* troubleshooting, printing: Redirection. (line 117) * troubleshooting, quotes with file names: Special FD. (line 68) * troubleshooting, readable data files: File Checking. (line 6) * troubleshooting, regexp constants vs. string constants: Computed Regexps. @@ -33132,10 +33127,10 @@ Index * variables, uninitialized, as array subscripts: Uninitialized Subscripts. (line 6) * variables, user-defined: Variables. (line 6) -* version of gawk: Auto-set. (line 199) -* version of gawk extension API: Auto-set. (line 224) -* version of GNU MP library: Auto-set. (line 210) -* version of GNU MPFR library: Auto-set. (line 206) +* version of gawk: Auto-set. (line 198) +* version of gawk extension API: Auto-set. (line 223) +* version of GNU MP library: Auto-set. (line 209) +* version of GNU MPFR library: Auto-set. (line 205) * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) @@ -33200,11 +33195,11 @@ Index * {} (braces), statements, grouping: Statements. (line 10) * | (vertical bar): Regexp Operators. (line 70) * | (vertical bar), | operator (I/O) <1>: Precedence. (line 65) -* | (vertical bar), | operator (I/O) <2>: Redirection. (line 57) +* | (vertical bar), | operator (I/O) <2>: Redirection. (line 56) * | (vertical bar), | operator (I/O): Getline/Pipe. (line 9) * | (vertical bar), |& operator (I/O) <1>: Two-way I/O. (line 44) * | (vertical bar), |& operator (I/O) <2>: Precedence. (line 65) -* | (vertical bar), |& operator (I/O) <3>: Redirection. (line 102) +* | (vertical bar), |& operator (I/O) <3>: Redirection. (line 101) * | (vertical bar), |& operator (I/O): Getline/Coprocess. (line 6) * | (vertical bar), |& operator (I/O), pipes, closing: Close Files And Pipes. (line 119) @@ -33245,515 +33240,515 @@ Node: Read Terminal74337 Ref: Read Terminal-Footnote-175987 Ref: Read Terminal-Footnote-276263 Node: Long76434 -Node: Executable Scripts77810 -Ref: Executable Scripts-Footnote-179643 -Ref: Executable Scripts-Footnote-279745 -Node: Comments80292 -Node: Quoting82759 -Node: DOS Quoting88075 -Node: Sample Data Files88750 -Node: Very Simple91265 -Node: Two Rules95903 -Node: More Complex97798 -Ref: More Complex-Footnote-1100730 -Node: Statements/Lines100815 -Ref: Statements/Lines-Footnote-1105270 -Node: Other Features105535 -Node: When106463 -Node: Invoking Gawk108611 -Node: Command Line110074 -Node: Options110865 -Ref: Options-Footnote-1126677 -Node: Other Arguments126702 -Node: Naming Standard Input129364 -Node: Environment Variables130458 -Node: AWKPATH Variable131016 -Ref: AWKPATH Variable-Footnote-1133887 -Ref: AWKPATH Variable-Footnote-2133932 -Node: AWKLIBPATH Variable134192 -Node: Other Environment Variables134951 -Node: Exit Status138606 -Node: Include Files139281 -Node: Loading Shared Libraries142859 -Node: Obsolete144242 -Node: Undocumented144939 -Node: Regexp145181 -Node: Regexp Usage146570 -Node: Escape Sequences148603 -Node: Regexp Operators154270 -Ref: Regexp Operators-Footnote-1161750 -Ref: Regexp Operators-Footnote-2161897 -Node: Bracket Expressions161995 -Ref: table-char-classes163885 -Node: GNU Regexp Operators166408 -Node: Case-sensitivity170131 -Ref: Case-sensitivity-Footnote-1173023 -Ref: Case-sensitivity-Footnote-2173258 -Node: Leftmost Longest173366 -Node: Computed Regexps174567 -Node: Reading Files177916 -Node: Records179918 -Node: awk split records180653 -Node: gawk split records185511 -Ref: gawk split records-Footnote-1190032 -Node: Fields190069 -Ref: Fields-Footnote-1193033 -Node: Nonconstant Fields193119 -Ref: Nonconstant Fields-Footnote-1195349 -Node: Changing Fields195551 -Node: Field Separators201505 -Node: Default Field Splitting204207 -Node: Regexp Field Splitting205324 -Node: Single Character Fields208665 -Node: Command Line Field Separator209724 -Node: Full Line Fields213066 -Ref: Full Line Fields-Footnote-1213574 -Node: Field Splitting Summary213620 -Ref: Field Splitting Summary-Footnote-1216719 -Node: Constant Size216820 -Node: Splitting By Content221427 -Ref: Splitting By Content-Footnote-1225177 -Node: Multiple Line225217 -Ref: Multiple Line-Footnote-1231073 -Node: Getline231252 -Node: Plain Getline233468 -Node: Getline/Variable235563 -Node: Getline/File236710 -Node: Getline/Variable/File238094 -Ref: Getline/Variable/File-Footnote-1239693 -Node: Getline/Pipe239780 -Node: Getline/Variable/Pipe242479 -Node: Getline/Coprocess243586 -Node: Getline/Variable/Coprocess244838 -Node: Getline Notes245575 -Node: Getline Summary248379 -Ref: table-getline-variants248787 -Node: Read Timeout249699 -Ref: Read Timeout-Footnote-1253526 -Node: Command line directories253584 -Node: Printing254466 -Node: Print256097 -Node: Print Examples257438 -Node: Output Separators260217 -Node: OFMT262233 -Node: Printf263591 -Node: Basic Printf264497 -Node: Control Letters266036 -Node: Format Modifiers269890 -Node: Printf Examples275917 -Node: Redirection278624 -Node: Special Files285596 -Node: Special FD286129 -Ref: Special FD-Footnote-1289753 -Node: Special Network289827 -Node: Special Caveats290677 -Node: Close Files And Pipes291473 -Ref: Close Files And Pipes-Footnote-1298611 -Ref: Close Files And Pipes-Footnote-2298759 -Node: Expressions298909 -Node: Values300041 -Node: Constants300717 -Node: Scalar Constants301397 -Ref: Scalar Constants-Footnote-1302256 -Node: Nondecimal-numbers302506 -Node: Regexp Constants305506 -Node: Using Constant Regexps305981 -Node: Variables309051 -Node: Using Variables309706 -Node: Assignment Options311430 -Node: Conversion313305 -Ref: table-locale-affects318741 -Ref: Conversion-Footnote-1319365 -Node: All Operators319474 -Node: Arithmetic Ops320104 -Node: Concatenation322609 -Ref: Concatenation-Footnote-1325405 -Node: Assignment Ops325525 -Ref: table-assign-ops330508 -Node: Increment Ops331825 -Node: Truth Values and Conditions335263 -Node: Truth Values336346 -Node: Typing and Comparison337395 -Node: Variable Typing338188 -Ref: Variable Typing-Footnote-1342088 -Node: Comparison Operators342210 -Ref: table-relational-ops342620 -Node: POSIX String Comparison346168 -Ref: POSIX String Comparison-Footnote-1347252 -Node: Boolean Ops347390 -Ref: Boolean Ops-Footnote-1351460 -Node: Conditional Exp351551 -Node: Function Calls353278 -Node: Precedence357036 -Node: Locales360705 -Node: Patterns and Actions362308 -Node: Pattern Overview363362 -Node: Regexp Patterns365039 -Node: Expression Patterns365582 -Node: Ranges369363 -Node: BEGIN/END372469 -Node: Using BEGIN/END373231 -Ref: Using BEGIN/END-Footnote-1375967 -Node: I/O And BEGIN/END376073 -Node: BEGINFILE/ENDFILE378358 -Node: Empty381289 -Node: Using Shell Variables381606 -Node: Action Overview383889 -Node: Statements386216 -Node: If Statement388064 -Node: While Statement389562 -Node: Do Statement391606 -Node: For Statement392762 -Node: Switch Statement395914 -Node: Break Statement398017 -Node: Continue Statement400072 -Node: Next Statement401865 -Node: Nextfile Statement404255 -Node: Exit Statement406910 -Node: Built-in Variables409314 -Node: User-modified410410 -Ref: User-modified-Footnote-1418095 -Node: Auto-set418157 -Ref: Auto-set-Footnote-1430722 -Ref: Auto-set-Footnote-2430927 -Node: ARGC and ARGV430983 -Node: Arrays434837 -Node: Array Basics436335 -Node: Array Intro437161 -Ref: figure-array-elements439134 -Node: Reference to Elements441541 -Node: Assigning Elements443814 -Node: Array Example444305 -Node: Scanning an Array446037 -Node: Controlling Scanning449052 -Ref: Controlling Scanning-Footnote-1454225 -Node: Delete454541 -Ref: Delete-Footnote-1457306 -Node: Numeric Array Subscripts457363 -Node: Uninitialized Subscripts459546 -Node: Multidimensional461171 -Node: Multiscanning464264 -Node: Arrays of Arrays465853 -Node: Functions470493 -Node: Built-in471312 -Node: Calling Built-in472390 -Node: Numeric Functions474378 -Ref: Numeric Functions-Footnote-1478212 -Ref: Numeric Functions-Footnote-2478569 -Ref: Numeric Functions-Footnote-3478617 -Node: String Functions478886 -Ref: String Functions-Footnote-1501897 -Ref: String Functions-Footnote-2502026 -Ref: String Functions-Footnote-3502274 -Node: Gory Details502361 -Ref: table-sub-escapes504030 -Ref: table-sub-posix-92505384 -Ref: table-sub-proposed506735 -Ref: table-posix-sub508089 -Ref: table-gensub-escapes509634 -Ref: Gory Details-Footnote-1510810 -Ref: Gory Details-Footnote-2510861 -Node: I/O Functions511012 -Ref: I/O Functions-Footnote-1518135 -Node: Time Functions518282 -Ref: Time Functions-Footnote-1528746 -Ref: Time Functions-Footnote-2528814 -Ref: Time Functions-Footnote-3528972 -Ref: Time Functions-Footnote-4529083 -Ref: Time Functions-Footnote-5529195 -Ref: Time Functions-Footnote-6529422 -Node: Bitwise Functions529688 -Ref: table-bitwise-ops530250 -Ref: Bitwise Functions-Footnote-1534495 -Node: Type Functions534679 -Node: I18N Functions535821 -Node: User-defined537466 -Node: Definition Syntax538270 -Ref: Definition Syntax-Footnote-1543195 -Node: Function Example543264 -Ref: Function Example-Footnote-1545908 -Node: Function Caveats545930 -Node: Calling A Function546448 -Node: Variable Scope547403 -Node: Pass By Value/Reference550391 -Node: Return Statement553899 -Node: Dynamic Typing556883 -Node: Indirect Calls557812 -Node: Library Functions567499 -Ref: Library Functions-Footnote-1571012 -Ref: Library Functions-Footnote-2571155 -Node: Library Names571326 -Ref: Library Names-Footnote-1574799 -Ref: Library Names-Footnote-2575019 -Node: General Functions575105 -Node: Strtonum Function576133 -Node: Assert Function579063 -Node: Round Function582389 -Node: Cliff Random Function583930 -Node: Ordinal Functions584946 -Ref: Ordinal Functions-Footnote-1588023 -Ref: Ordinal Functions-Footnote-2588275 -Node: Join Function588486 -Ref: Join Function-Footnote-1590257 -Node: Getlocaltime Function590457 -Node: Readfile Function594193 -Node: Data File Management596032 -Node: Filetrans Function596664 -Node: Rewind Function600733 -Node: File Checking602120 -Ref: File Checking-Footnote-1603252 -Node: Empty Files603453 -Node: Ignoring Assigns605683 -Node: Getopt Function607237 -Ref: Getopt Function-Footnote-1618540 -Node: Passwd Functions618743 -Ref: Passwd Functions-Footnote-1627722 -Node: Group Functions627810 -Ref: Group Functions-Footnote-1635752 -Node: Walking Arrays635965 -Node: Sample Programs638101 -Node: Running Examples638775 -Node: Clones639503 -Node: Cut Program640727 -Node: Egrep Program650580 -Ref: Egrep Program-Footnote-1658551 -Node: Id Program658661 -Node: Split Program662325 -Ref: Split Program-Footnote-1665863 -Node: Tee Program665991 -Node: Uniq Program668798 -Node: Wc Program676228 -Ref: Wc Program-Footnote-1680496 -Ref: Wc Program-Footnote-2680696 -Node: Miscellaneous Programs680788 -Node: Dupword Program681976 -Node: Alarm Program684007 -Node: Translate Program688814 -Ref: Translate Program-Footnote-1693205 -Ref: Translate Program-Footnote-2693475 -Node: Labels Program693609 -Ref: Labels Program-Footnote-1696980 -Node: Word Sorting697064 -Node: History Sorting701107 -Node: Extract Program702943 -Ref: Extract Program-Footnote-1710473 -Node: Simple Sed710602 -Node: Igawk Program713664 -Ref: Igawk Program-Footnote-1728839 -Ref: Igawk Program-Footnote-2729040 -Node: Anagram Program729178 -Node: Signature Program732246 -Node: Advanced Features733493 -Node: Nondecimal Data735379 -Node: Array Sorting736956 -Node: Controlling Array Traversal737653 -Node: Array Sorting Functions745933 -Ref: Array Sorting Functions-Footnote-1749840 -Node: Two-way I/O750034 -Ref: Two-way I/O-Footnote-1755550 -Node: TCP/IP Networking755632 -Node: Profiling758476 -Node: Internationalization765984 -Node: I18N and L10N767409 -Node: Explaining gettext768095 -Ref: Explaining gettext-Footnote-1773235 -Ref: Explaining gettext-Footnote-2773419 -Node: Programmer i18n773584 -Node: Translator i18n777809 -Node: String Extraction778603 -Ref: String Extraction-Footnote-1779564 -Node: Printf Ordering779650 -Ref: Printf Ordering-Footnote-1782432 -Node: I18N Portability782496 -Ref: I18N Portability-Footnote-1784945 -Node: I18N Example785008 -Ref: I18N Example-Footnote-1787730 -Node: Gawk I18N787802 -Node: Debugger788423 -Node: Debugging789394 -Node: Debugging Concepts789835 -Node: Debugging Terms791691 -Node: Awk Debugging794288 -Node: Sample Debugging Session795180 -Node: Debugger Invocation795700 -Node: Finding The Bug797033 -Node: List of Debugger Commands803515 -Node: Breakpoint Control804847 -Node: Debugger Execution Control808511 -Node: Viewing And Changing Data811871 -Node: Execution Stack815229 -Node: Debugger Info816742 -Node: Miscellaneous Debugger Commands820736 -Node: Readline Support825920 -Node: Limitations826812 -Node: Arbitrary Precision Arithmetic829060 -Ref: Arbitrary Precision Arithmetic-Footnote-1830709 -Node: General Arithmetic830857 -Node: Floating Point Issues832577 -Node: String Conversion Precision833458 -Ref: String Conversion Precision-Footnote-1835163 -Node: Unexpected Results835272 -Node: POSIX Floating Point Problems837425 -Ref: POSIX Floating Point Problems-Footnote-1841246 -Node: Integer Programming841284 -Node: Floating-point Programming843095 -Ref: Floating-point Programming-Footnote-1849423 -Ref: Floating-point Programming-Footnote-2849693 -Node: Floating-point Representation849957 -Node: Floating-point Context851122 -Ref: table-ieee-formats851961 -Node: Rounding Mode853345 -Ref: table-rounding-modes853824 -Ref: Rounding Mode-Footnote-1856839 -Node: Gawk and MPFR857018 -Node: Arbitrary Precision Floats858427 -Ref: Arbitrary Precision Floats-Footnote-1860870 -Node: Setting Precision861191 -Ref: table-predefined-precision-strings861875 -Node: Setting Rounding Mode864020 -Ref: table-gawk-rounding-modes864424 -Node: Floating-point Constants865611 -Node: Changing Precision867063 -Ref: Changing Precision-Footnote-1868455 -Node: Exact Arithmetic868629 -Node: Arbitrary Precision Integers871763 -Ref: Arbitrary Precision Integers-Footnote-1874778 -Node: Dynamic Extensions874925 -Node: Extension Intro876383 -Node: Plugin License877648 -Node: Extension Mechanism Outline878333 -Ref: figure-load-extension878757 -Ref: figure-load-new-function880242 -Ref: figure-call-new-function881244 -Node: Extension API Description883228 -Node: Extension API Functions Introduction884678 -Node: General Data Types889544 -Ref: General Data Types-Footnote-1895237 -Node: Requesting Values895536 -Ref: table-value-types-returned896273 -Node: Memory Allocation Functions897231 -Ref: Memory Allocation Functions-Footnote-1899978 -Node: Constructor Functions900074 -Node: Registration Functions901832 -Node: Extension Functions902517 -Node: Exit Callback Functions904819 -Node: Extension Version String906069 -Node: Input Parsers906719 -Node: Output Wrappers916522 -Node: Two-way processors921038 -Node: Printing Messages923241 -Ref: Printing Messages-Footnote-1924318 -Node: Updating `ERRNO'924470 -Node: Accessing Parameters925209 -Node: Symbol Table Access926439 -Node: Symbol table by name926953 -Node: Symbol table by cookie928929 -Ref: Symbol table by cookie-Footnote-1933062 -Node: Cached values933125 -Ref: Cached values-Footnote-1936630 -Node: Array Manipulation936721 -Ref: Array Manipulation-Footnote-1937819 -Node: Array Data Types937858 -Ref: Array Data Types-Footnote-1940561 -Node: Array Functions940653 -Node: Flattening Arrays944527 -Node: Creating Arrays951379 -Node: Extension API Variables956110 -Node: Extension Versioning956746 -Node: Extension API Informational Variables958647 -Node: Extension API Boilerplate959733 -Node: Finding Extensions963537 -Node: Extension Example964097 -Node: Internal File Description964827 -Node: Internal File Ops968918 -Ref: Internal File Ops-Footnote-1980464 -Node: Using Internal File Ops980604 -Ref: Using Internal File Ops-Footnote-1982951 -Node: Extension Samples983219 -Node: Extension Sample File Functions984743 -Node: Extension Sample Fnmatch992310 -Node: Extension Sample Fork993789 -Node: Extension Sample Inplace995002 -Node: Extension Sample Ord996780 -Node: Extension Sample Readdir997616 -Ref: table-readdir-file-types998471 -Node: Extension Sample Revout999270 -Node: Extension Sample Rev2way999861 -Node: Extension Sample Read write array1000602 -Node: Extension Sample Readfile1002481 -Node: Extension Sample API Tests1003581 -Node: Extension Sample Time1004106 -Node: gawkextlib1005421 -Node: Language History1008208 -Node: V7/SVR3.11009802 -Node: SVR41012122 -Node: POSIX1013564 -Node: BTL1014950 -Node: POSIX/GNU1015684 -Node: Feature History1021283 -Node: Common Extensions1034395 -Node: Ranges and Locales1035707 -Ref: Ranges and Locales-Footnote-11040324 -Ref: Ranges and Locales-Footnote-21040351 -Ref: Ranges and Locales-Footnote-31040585 -Node: Contributors1040806 -Node: Installation1046244 -Node: Gawk Distribution1047138 -Node: Getting1047622 -Node: Extracting1048448 -Node: Distribution contents1050090 -Node: Unix Installation1055807 -Node: Quick Installation1056424 -Node: Additional Configuration Options1058866 -Node: Configuration Philosophy1060604 -Node: Non-Unix Installation1062955 -Node: PC Installation1063413 -Node: PC Binary Installation1064724 -Node: PC Compiling1066572 -Ref: PC Compiling-Footnote-11069571 -Node: PC Testing1069676 -Node: PC Using1070852 -Node: Cygwin1075010 -Node: MSYS1075819 -Node: VMS Installation1076333 -Node: VMS Compilation1077129 -Ref: VMS Compilation-Footnote-11078350 -Node: VMS Dynamic Extensions1078408 -Node: VMS Installation Details1079781 -Node: VMS Running1082032 -Node: VMS GNV1084866 -Node: VMS Old Gawk1085589 -Node: Bugs1086059 -Node: Other Versions1090063 -Node: Notes1096288 -Node: Compatibility Mode1097088 -Node: Additions1097870 -Node: Accessing The Source1098795 -Node: Adding Code1100231 -Node: New Ports1106409 -Node: Derived Files1110890 -Ref: Derived Files-Footnote-11115971 -Ref: Derived Files-Footnote-21116005 -Ref: Derived Files-Footnote-31116601 -Node: Future Extensions1116715 -Node: Implementation Limitations1117321 -Node: Extension Design1118569 -Node: Old Extension Problems1119723 -Ref: Old Extension Problems-Footnote-11121240 -Node: Extension New Mechanism Goals1121297 -Ref: Extension New Mechanism Goals-Footnote-11124658 -Node: Extension Other Design Decisions1124847 -Node: Extension Future Growth1126953 -Node: Old Extension Mechanism1127789 -Node: Basic Concepts1129529 -Node: Basic High Level1130210 -Ref: figure-general-flow1130482 -Ref: figure-process-flow1131081 -Ref: Basic High Level-Footnote-11134310 -Node: Basic Data Typing1134495 -Node: Glossary1137822 -Node: Copying1162974 -Node: GNU Free Documentation License1200530 -Node: Index1225666 +Node: Executable Scripts77782 +Ref: Executable Scripts-Footnote-179615 +Ref: Executable Scripts-Footnote-279717 +Node: Comments80250 +Node: Quoting82717 +Node: DOS Quoting88026 +Node: Sample Data Files88701 +Node: Very Simple91216 +Node: Two Rules95847 +Node: More Complex97742 +Ref: More Complex-Footnote-1100667 +Node: Statements/Lines100752 +Ref: Statements/Lines-Footnote-1105207 +Node: Other Features105472 +Node: When106400 +Node: Invoking Gawk108548 +Node: Command Line110011 +Node: Options110802 +Ref: Options-Footnote-1126586 +Node: Other Arguments126611 +Node: Naming Standard Input129252 +Node: Environment Variables130332 +Node: AWKPATH Variable130890 +Ref: AWKPATH Variable-Footnote-1133741 +Ref: AWKPATH Variable-Footnote-2133786 +Node: AWKLIBPATH Variable134046 +Node: Other Environment Variables134805 +Node: Exit Status138460 +Node: Include Files139135 +Node: Loading Shared Libraries142699 +Node: Obsolete144083 +Node: Undocumented144780 +Node: Regexp145022 +Node: Regexp Usage146411 +Node: Escape Sequences148444 +Node: Regexp Operators154111 +Ref: Regexp Operators-Footnote-1161591 +Ref: Regexp Operators-Footnote-2161738 +Node: Bracket Expressions161836 +Ref: table-char-classes163726 +Node: GNU Regexp Operators166249 +Node: Case-sensitivity169972 +Ref: Case-sensitivity-Footnote-1172864 +Ref: Case-sensitivity-Footnote-2173099 +Node: Leftmost Longest173207 +Node: Computed Regexps174408 +Node: Reading Files177757 +Node: Records179759 +Node: awk split records180494 +Node: gawk split records185352 +Ref: gawk split records-Footnote-1189873 +Node: Fields189910 +Ref: Fields-Footnote-1192874 +Node: Nonconstant Fields192960 +Ref: Nonconstant Fields-Footnote-1195190 +Node: Changing Fields195392 +Node: Field Separators201346 +Node: Default Field Splitting204048 +Node: Regexp Field Splitting205165 +Node: Single Character Fields208506 +Node: Command Line Field Separator209565 +Node: Full Line Fields212907 +Ref: Full Line Fields-Footnote-1213415 +Node: Field Splitting Summary213461 +Ref: Field Splitting Summary-Footnote-1216560 +Node: Constant Size216661 +Node: Splitting By Content221268 +Ref: Splitting By Content-Footnote-1225018 +Node: Multiple Line225058 +Ref: Multiple Line-Footnote-1230914 +Node: Getline231093 +Node: Plain Getline233309 +Node: Getline/Variable235404 +Node: Getline/File236551 +Node: Getline/Variable/File237927 +Ref: Getline/Variable/File-Footnote-1239526 +Node: Getline/Pipe239613 +Node: Getline/Variable/Pipe242312 +Node: Getline/Coprocess243419 +Node: Getline/Variable/Coprocess244671 +Node: Getline Notes245408 +Node: Getline Summary248212 +Ref: table-getline-variants248620 +Node: Read Timeout249532 +Ref: Read Timeout-Footnote-1253359 +Node: Command line directories253417 +Node: Printing254299 +Node: Print255923 +Node: Print Examples257264 +Node: Output Separators260043 +Node: OFMT262059 +Node: Printf263417 +Node: Basic Printf264323 +Node: Control Letters265862 +Node: Format Modifiers269716 +Node: Printf Examples275743 +Node: Redirection278450 +Node: Special Files285397 +Node: Special FD285913 +Ref: Special FD-Footnote-1289488 +Node: Special Network289562 +Node: Special Caveats290398 +Node: Close Files And Pipes291173 +Ref: Close Files And Pipes-Footnote-1298289 +Ref: Close Files And Pipes-Footnote-2298437 +Node: Expressions298587 +Node: Values299719 +Node: Constants300395 +Node: Scalar Constants301075 +Ref: Scalar Constants-Footnote-1301934 +Node: Nondecimal-numbers302184 +Node: Regexp Constants305184 +Node: Using Constant Regexps305659 +Node: Variables308729 +Node: Using Variables309384 +Node: Assignment Options311108 +Node: Conversion312975 +Ref: table-locale-affects318411 +Ref: Conversion-Footnote-1319035 +Node: All Operators319144 +Node: Arithmetic Ops319774 +Node: Concatenation322279 +Ref: Concatenation-Footnote-1325075 +Node: Assignment Ops325195 +Ref: table-assign-ops330178 +Node: Increment Ops331495 +Node: Truth Values and Conditions334933 +Node: Truth Values336016 +Node: Typing and Comparison337065 +Node: Variable Typing337858 +Ref: Variable Typing-Footnote-1341758 +Node: Comparison Operators341880 +Ref: table-relational-ops342290 +Node: POSIX String Comparison345838 +Ref: POSIX String Comparison-Footnote-1346922 +Node: Boolean Ops347060 +Ref: Boolean Ops-Footnote-1351130 +Node: Conditional Exp351221 +Node: Function Calls352948 +Node: Precedence356706 +Node: Locales360375 +Node: Patterns and Actions361978 +Node: Pattern Overview363032 +Node: Regexp Patterns364709 +Node: Expression Patterns365252 +Node: Ranges369033 +Node: BEGIN/END372139 +Node: Using BEGIN/END372901 +Ref: Using BEGIN/END-Footnote-1375637 +Node: I/O And BEGIN/END375743 +Node: BEGINFILE/ENDFILE378028 +Node: Empty380959 +Node: Using Shell Variables381276 +Node: Action Overview383559 +Node: Statements385886 +Node: If Statement387734 +Node: While Statement389232 +Node: Do Statement391276 +Node: For Statement392432 +Node: Switch Statement395584 +Node: Break Statement397687 +Node: Continue Statement399742 +Node: Next Statement401535 +Node: Nextfile Statement403925 +Node: Exit Statement406580 +Node: Built-in Variables408984 +Node: User-modified410080 +Ref: User-modified-Footnote-1417765 +Node: Auto-set417827 +Ref: Auto-set-Footnote-1430373 +Ref: Auto-set-Footnote-2430578 +Node: ARGC and ARGV430634 +Node: Arrays434473 +Node: Array Basics435971 +Node: Array Intro436797 +Ref: figure-array-elements438770 +Node: Reference to Elements441177 +Node: Assigning Elements443450 +Node: Array Example443941 +Node: Scanning an Array445673 +Node: Controlling Scanning448688 +Ref: Controlling Scanning-Footnote-1453861 +Node: Delete454177 +Ref: Delete-Footnote-1456942 +Node: Numeric Array Subscripts456999 +Node: Uninitialized Subscripts459182 +Node: Multidimensional460807 +Node: Multiscanning463900 +Node: Arrays of Arrays465489 +Node: Functions470129 +Node: Built-in470948 +Node: Calling Built-in472026 +Node: Numeric Functions474014 +Ref: Numeric Functions-Footnote-1477848 +Ref: Numeric Functions-Footnote-2478205 +Ref: Numeric Functions-Footnote-3478253 +Node: String Functions478522 +Ref: String Functions-Footnote-1501533 +Ref: String Functions-Footnote-2501662 +Ref: String Functions-Footnote-3501910 +Node: Gory Details501997 +Ref: table-sub-escapes503666 +Ref: table-sub-posix-92505020 +Ref: table-sub-proposed506371 +Ref: table-posix-sub507725 +Ref: table-gensub-escapes509270 +Ref: Gory Details-Footnote-1510446 +Ref: Gory Details-Footnote-2510497 +Node: I/O Functions510648 +Ref: I/O Functions-Footnote-1517771 +Node: Time Functions517918 +Ref: Time Functions-Footnote-1528382 +Ref: Time Functions-Footnote-2528450 +Ref: Time Functions-Footnote-3528608 +Ref: Time Functions-Footnote-4528719 +Ref: Time Functions-Footnote-5528831 +Ref: Time Functions-Footnote-6529058 +Node: Bitwise Functions529324 +Ref: table-bitwise-ops529886 +Ref: Bitwise Functions-Footnote-1534131 +Node: Type Functions534315 +Node: I18N Functions535457 +Node: User-defined537102 +Node: Definition Syntax537906 +Ref: Definition Syntax-Footnote-1542831 +Node: Function Example542900 +Ref: Function Example-Footnote-1545544 +Node: Function Caveats545566 +Node: Calling A Function546084 +Node: Variable Scope547039 +Node: Pass By Value/Reference550027 +Node: Return Statement553535 +Node: Dynamic Typing556519 +Node: Indirect Calls557448 +Node: Library Functions567135 +Ref: Library Functions-Footnote-1570648 +Ref: Library Functions-Footnote-2570791 +Node: Library Names570962 +Ref: Library Names-Footnote-1574435 +Ref: Library Names-Footnote-2574655 +Node: General Functions574741 +Node: Strtonum Function575769 +Node: Assert Function578699 +Node: Round Function582025 +Node: Cliff Random Function583566 +Node: Ordinal Functions584582 +Ref: Ordinal Functions-Footnote-1587659 +Ref: Ordinal Functions-Footnote-2587911 +Node: Join Function588122 +Ref: Join Function-Footnote-1589893 +Node: Getlocaltime Function590093 +Node: Readfile Function593829 +Node: Data File Management595668 +Node: Filetrans Function596300 +Node: Rewind Function600355 +Node: File Checking601742 +Ref: File Checking-Footnote-1602874 +Node: Empty Files603075 +Node: Ignoring Assigns605298 +Node: Getopt Function606829 +Ref: Getopt Function-Footnote-1618125 +Node: Passwd Functions618328 +Ref: Passwd Functions-Footnote-1627307 +Node: Group Functions627395 +Ref: Group Functions-Footnote-1635337 +Node: Walking Arrays635550 +Node: Sample Programs637686 +Node: Running Examples638360 +Node: Clones639088 +Node: Cut Program640312 +Node: Egrep Program650173 +Ref: Egrep Program-Footnote-1658102 +Node: Id Program658212 +Node: Split Program661876 +Ref: Split Program-Footnote-1665407 +Node: Tee Program665535 +Node: Uniq Program668342 +Node: Wc Program675772 +Ref: Wc Program-Footnote-1680040 +Ref: Wc Program-Footnote-2680240 +Node: Miscellaneous Programs680332 +Node: Dupword Program681520 +Node: Alarm Program683551 +Node: Translate Program688365 +Ref: Translate Program-Footnote-1692756 +Ref: Translate Program-Footnote-2693026 +Node: Labels Program693160 +Ref: Labels Program-Footnote-1696531 +Node: Word Sorting696615 +Node: History Sorting700658 +Node: Extract Program702494 +Ref: Extract Program-Footnote-1710069 +Node: Simple Sed710198 +Node: Igawk Program713260 +Ref: Igawk Program-Footnote-1728436 +Ref: Igawk Program-Footnote-2728637 +Node: Anagram Program728775 +Node: Signature Program731843 +Node: Advanced Features733090 +Node: Nondecimal Data734976 +Node: Array Sorting736553 +Node: Controlling Array Traversal737250 +Node: Array Sorting Functions745530 +Ref: Array Sorting Functions-Footnote-1749437 +Node: Two-way I/O749631 +Ref: Two-way I/O-Footnote-1755147 +Node: TCP/IP Networking755229 +Node: Profiling758073 +Node: Internationalization765581 +Node: I18N and L10N767006 +Node: Explaining gettext767692 +Ref: Explaining gettext-Footnote-1772832 +Ref: Explaining gettext-Footnote-2773016 +Node: Programmer i18n773181 +Node: Translator i18n777406 +Node: String Extraction778200 +Ref: String Extraction-Footnote-1779161 +Node: Printf Ordering779247 +Ref: Printf Ordering-Footnote-1782029 +Node: I18N Portability782093 +Ref: I18N Portability-Footnote-1784542 +Node: I18N Example784605 +Ref: I18N Example-Footnote-1787327 +Node: Gawk I18N787399 +Node: Debugger788012 +Node: Debugging788983 +Node: Debugging Concepts789424 +Node: Debugging Terms791280 +Node: Awk Debugging793877 +Node: Sample Debugging Session794769 +Node: Debugger Invocation795289 +Node: Finding The Bug796622 +Node: List of Debugger Commands803104 +Node: Breakpoint Control804436 +Node: Debugger Execution Control808100 +Node: Viewing And Changing Data811460 +Node: Execution Stack814818 +Node: Debugger Info816331 +Node: Miscellaneous Debugger Commands820325 +Node: Readline Support825509 +Node: Limitations826401 +Node: Arbitrary Precision Arithmetic828649 +Ref: Arbitrary Precision Arithmetic-Footnote-1830298 +Node: General Arithmetic830446 +Node: Floating Point Issues832166 +Node: String Conversion Precision833047 +Ref: String Conversion Precision-Footnote-1834752 +Node: Unexpected Results834861 +Node: POSIX Floating Point Problems837014 +Ref: POSIX Floating Point Problems-Footnote-1840835 +Node: Integer Programming840873 +Node: Floating-point Programming842684 +Ref: Floating-point Programming-Footnote-1849012 +Ref: Floating-point Programming-Footnote-2849282 +Node: Floating-point Representation849546 +Node: Floating-point Context850711 +Ref: table-ieee-formats851550 +Node: Rounding Mode852934 +Ref: table-rounding-modes853413 +Ref: Rounding Mode-Footnote-1856428 +Node: Gawk and MPFR856607 +Node: Arbitrary Precision Floats858016 +Ref: Arbitrary Precision Floats-Footnote-1860459 +Node: Setting Precision860780 +Ref: table-predefined-precision-strings861464 +Node: Setting Rounding Mode863609 +Ref: table-gawk-rounding-modes864013 +Node: Floating-point Constants865200 +Node: Changing Precision866652 +Ref: Changing Precision-Footnote-1868044 +Node: Exact Arithmetic868218 +Node: Arbitrary Precision Integers871352 +Ref: Arbitrary Precision Integers-Footnote-1874367 +Node: Dynamic Extensions874514 +Node: Extension Intro875972 +Node: Plugin License877237 +Node: Extension Mechanism Outline877922 +Ref: figure-load-extension878346 +Ref: figure-load-new-function879831 +Ref: figure-call-new-function880833 +Node: Extension API Description882817 +Node: Extension API Functions Introduction884267 +Node: General Data Types889133 +Ref: General Data Types-Footnote-1894826 +Node: Requesting Values895125 +Ref: table-value-types-returned895862 +Node: Memory Allocation Functions896820 +Ref: Memory Allocation Functions-Footnote-1899567 +Node: Constructor Functions899663 +Node: Registration Functions901421 +Node: Extension Functions902106 +Node: Exit Callback Functions904408 +Node: Extension Version String905658 +Node: Input Parsers906308 +Node: Output Wrappers916111 +Node: Two-way processors920627 +Node: Printing Messages922831 +Ref: Printing Messages-Footnote-1923908 +Node: Updating `ERRNO'924060 +Node: Accessing Parameters924799 +Node: Symbol Table Access926029 +Node: Symbol table by name926543 +Node: Symbol table by cookie928519 +Ref: Symbol table by cookie-Footnote-1932652 +Node: Cached values932715 +Ref: Cached values-Footnote-1936220 +Node: Array Manipulation936311 +Ref: Array Manipulation-Footnote-1937409 +Node: Array Data Types937448 +Ref: Array Data Types-Footnote-1940151 +Node: Array Functions940243 +Node: Flattening Arrays944117 +Node: Creating Arrays950969 +Node: Extension API Variables955700 +Node: Extension Versioning956336 +Node: Extension API Informational Variables958237 +Node: Extension API Boilerplate959323 +Node: Finding Extensions963127 +Node: Extension Example963687 +Node: Internal File Description964417 +Node: Internal File Ops968508 +Ref: Internal File Ops-Footnote-1980054 +Node: Using Internal File Ops980194 +Ref: Using Internal File Ops-Footnote-1982541 +Node: Extension Samples982809 +Node: Extension Sample File Functions984333 +Node: Extension Sample Fnmatch991901 +Node: Extension Sample Fork993368 +Node: Extension Sample Inplace994581 +Node: Extension Sample Ord996347 +Node: Extension Sample Readdir997183 +Ref: table-readdir-file-types998032 +Node: Extension Sample Revout998831 +Node: Extension Sample Rev2way999422 +Node: Extension Sample Read write array1000163 +Node: Extension Sample Readfile1002042 +Node: Extension Sample API Tests1003142 +Node: Extension Sample Time1003667 +Node: gawkextlib1004982 +Node: Language History1007769 +Node: V7/SVR3.11009363 +Node: SVR41011683 +Node: POSIX1013125 +Node: BTL1014511 +Node: POSIX/GNU1015245 +Node: Feature History1020844 +Node: Common Extensions1033956 +Node: Ranges and Locales1035268 +Ref: Ranges and Locales-Footnote-11039885 +Ref: Ranges and Locales-Footnote-21039912 +Ref: Ranges and Locales-Footnote-31040146 +Node: Contributors1040367 +Node: Installation1045805 +Node: Gawk Distribution1046699 +Node: Getting1047183 +Node: Extracting1048009 +Node: Distribution contents1049651 +Node: Unix Installation1055368 +Node: Quick Installation1055985 +Node: Additional Configuration Options1058427 +Node: Configuration Philosophy1060165 +Node: Non-Unix Installation1062516 +Node: PC Installation1062974 +Node: PC Binary Installation1064285 +Node: PC Compiling1066133 +Ref: PC Compiling-Footnote-11069132 +Node: PC Testing1069237 +Node: PC Using1070413 +Node: Cygwin1074571 +Node: MSYS1075380 +Node: VMS Installation1075894 +Node: VMS Compilation1076690 +Ref: VMS Compilation-Footnote-11077905 +Node: VMS Dynamic Extensions1077963 +Node: VMS Installation Details1079336 +Node: VMS Running1081582 +Node: VMS GNV1084416 +Node: VMS Old Gawk1085139 +Node: Bugs1085609 +Node: Other Versions1089613 +Node: Notes1095838 +Node: Compatibility Mode1096638 +Node: Additions1097420 +Node: Accessing The Source1098345 +Node: Adding Code1099781 +Node: New Ports1105959 +Node: Derived Files1110440 +Ref: Derived Files-Footnote-11115521 +Ref: Derived Files-Footnote-21115555 +Ref: Derived Files-Footnote-31116151 +Node: Future Extensions1116265 +Node: Implementation Limitations1116871 +Node: Extension Design1118119 +Node: Old Extension Problems1119273 +Ref: Old Extension Problems-Footnote-11120790 +Node: Extension New Mechanism Goals1120847 +Ref: Extension New Mechanism Goals-Footnote-11124208 +Node: Extension Other Design Decisions1124397 +Node: Extension Future Growth1126503 +Node: Old Extension Mechanism1127339 +Node: Basic Concepts1129079 +Node: Basic High Level1129760 +Ref: figure-general-flow1130032 +Ref: figure-process-flow1130631 +Ref: Basic High Level-Footnote-11133860 +Node: Basic Data Typing1134045 +Node: Glossary1137372 +Node: Copying1162524 +Node: GNU Free Documentation License1200080 +Node: Index1225216 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 4d63bae9..093c776b 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -51,12 +51,10 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH April, 2014 +@set UPDATE-MONTH June, 2014 @set VERSION 4.1 @set PATCHLEVEL 1 -@set FSF - @set TITLE GAWK: Effective AWK Programming @set SUBTITLE A User's Guide for GNU Awk @set EDITION 4.1 @@ -167,6 +165,21 @@ @end macro @end ifdocbook +@ifclear FOR_PRINT +@set FN file name +@set FFN File Name +@set DF data file +@set DDF Data File +@set PVERSION version +@end ifclear +@ifset FOR_PRINT +@set FN filename +@set FFN Filename +@set DF datafile +@set DDF Datafile +@set PVERSION Version +@end ifset + @c For HTML, spell out email addresses, to avoid problems with @c address harvesters for spammers. @ifhtml @@ -1378,11 +1391,11 @@ wrote the bulk of @cite{TCP/IP Internetworking with @command{gawk}} (a separate document, available as part of the @command{gawk} distribution). His code finally became part of the main @command{gawk} distribution -with @command{gawk} version 3.1. +with @command{gawk} @value{PVERSION} 3.1. John Haque rewrote the @command{gawk} internals, in the process providing an @command{awk}-level debugger. This version became available as -@command{gawk} version 4.0, in 2011. +@command{gawk} @value{PVERSION} 4.0, in 2011. @xref{Contributors}, for a complete list of those who made important contributions to @command{gawk}. @@ -1454,7 +1467,7 @@ the POSIX standard for @command{awk} are noted. This @value{DOCUMENT} has the difficult task of being both a tutorial and a reference. If you are a novice, feel free to skip over details that seem too complex. You should also ignore the many cross-references; they are for the -expert user and for the online Info and HTML versions of the document. +expert user and for the online Info and HTML versions of the @value{DOCUMENT}. @end ifnotinfo There are sidebars @@ -1676,7 +1689,7 @@ emphasized @emph{like this}, and if a point needs to be made strongly, it is done @strong{like this}. The first occurrence of a new term is usually its @dfn{definition} and appears in the same font as the previous occurrence of ``definition'' in this sentence. -Finally, file names are indicated like this: @file{/path/to/ourfile}. +Finally, @var{FN}s are indicated like this: @file{/path/to/ourfile}. @end ifnotinfo Characters that you type at the keyboard look @kbd{like this}. In particular, @@ -2331,7 +2344,7 @@ awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{} @cindex @option{-f} option @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 +from the file @var{source-file}. Any @var{FN} can be used for @var{source-file}. For example, you could put the program: @example @@ -2356,8 +2369,8 @@ awk "BEGIN @{ print \"Don't Panic!\" @}" @noindent This was explained earlier (@pxref{Read Terminal}). -Note that you don't usually need single quotes around the file name that you -specify with @option{-f}, because most file names don't contain any of the shell's +Note that you don't usually need single quotes around the @var{FN} that you +specify with @option{-f}, because most @var{FN}s don't contain any of the shell's special characters. Notice that in @file{advice}, the @command{awk} program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. @@ -2367,7 +2380,7 @@ for programs that are provided on the @command{awk} command line. @c STARTOFRANGE qs2x @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 +you can add the extension @file{.awk} to the @var{FN}. This doesn't affect the execution of the @command{awk} program but it does make ``housekeeping'' easier. @@ -2394,13 +2407,13 @@ BEGIN @{ print "Don't Panic!" @} After making this file executable (with the @command{chmod} utility), simply type @samp{advice} at the shell and the system arranges to run @command{awk}@footnote{The -line beginning with @samp{#!} lists the full file name of an interpreter +line beginning with @samp{#!} lists the full @var{FN} of an interpreter to run and an optional initial command-line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument -in the list is the full file name of the @command{awk} program. +in the list is the full @var{FN} of the @command{awk} program. The rest of the -argument list contains either options to @command{awk}, or data files, +argument list contains either options to @command{awk}, or @value{DF}s, or both. Note that on many systems @command{awk} may be found in @file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had typed @samp{awk -f advice}: @@ -2671,7 +2684,7 @@ awk -F"" '@var{program}' @var{files} # wrong! @noindent In the second case, @command{awk} will attempt to use the text of the program -as the value of @code{FS}, and the first file name as the text of the program! +as the value of @code{FS}, and the first @var{FN} as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize @@ -2787,18 +2800,18 @@ gawk "@{ print \"\042\" $0 \"\042\" @}" @var{file} @node Sample Data Files -@section Data Files for the Examples +@section @value{DDF}s for the Examples @cindex input files, examples @cindex @code{mail-list} file Many of the examples in this @value{DOCUMENT} take their input from two sample -data files. The first, @file{mail-list}, represents a list of peoples' names +@value{DF}s. 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 +The second @value{DF}, 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{mail-list}, each record contains the name of a person, +In the @value{DF} @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 @@ -2827,7 +2840,7 @@ Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example @cindex @code{inventory-shipped} file -The data file @file{inventory-shipped} represents +The @value{DF} @file{inventory-shipped} represents information about shipments during the year. Each record contains the month, the number of green crates shipped, the number of red boxes shipped, the number of @@ -2919,9 +2932,9 @@ collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description of the program will give you a good idea of what is going on, but please read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) -Most of the examples use a data file named @file{data}. This is just a +Most of the examples use a @value{DF} named @file{data}. This is just a placeholder; if you use these programs yourself, substitute -your own file names for @file{data}. +your own @var{FN}s for @file{data}. For future reference, note that there is often more than one way to do things in @command{awk}. At some point, you may want to look back at these examples and see if @@ -3011,7 +3024,7 @@ awk 'END @{ print NR @}' data @end example @item -Print the even-numbered lines in the data file: +Print the even-numbered lines in the @value{DF}: @example awk 'NR % 2 == 0' data @@ -3053,7 +3066,7 @@ This program prints every line that contains the string @samp{12} @emph{or} the string @samp{21}. If a line contains both strings, it is printed twice, once by each rule. -This is what happens if we run this program on our two sample data files, +This is what happens if we run this program on our two sample @value{DF}s, @file{mail-list} and @file{inventory-shipped}: @example @@ -3113,7 +3126,7 @@ the file. The fourth field identifies the group of the file. The fifth field contains the size of the file in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the file name.@footnote{The @samp{LC_ALL=C} is +contains the @var{FN}.@footnote{The @samp{LC_ALL=C} is needed to produce this traditional-style output from @command{ls}.} @c @cindex automatic initialization @@ -3516,8 +3529,8 @@ conventions. @cindex @code{-} (hyphen), filenames beginning with @cindex hyphen (@code{-}), filenames beginning with -This is useful if you have file names that start with @samp{-}, -or in shell scripts, if you have file names that will be specified +This is useful if you have @var{FN}s that start with @samp{-}, +or in shell scripts, if you have @var{FN}s that will be specified by the user that could start with @samp{-}. It is also useful for passing options on to the @command{awk} program; see @ref{Getopt Function}. @@ -3762,7 +3775,7 @@ Enable pretty-printing of @command{awk} programs. By default, output program is created in a file named @file{awkprof.out} (@pxref{Profiling}). The optional @var{file} argument allows you to specify a different -file name for the output. +@var{FN} for the output. No space is allowed between the @option{-o} and @var{file}, if @var{file} is supplied. @@ -3789,7 +3802,7 @@ Enable profiling of @command{awk} programs (@pxref{Profiling}). By default, profiles are created in a file named @file{awkprof.out}. The optional @var{file} argument allows you to specify a different -file name for the profile file. +@var{FN} for the profile file. No space is allowed between the @option{-p} and @var{file}, if @var{file} is supplied. @@ -3869,7 +3882,7 @@ output redirections with @code{print} and @code{printf}, and dynamic extensions. This is particularly useful when you want to run @command{awk} scripts from questionable sources and need to make sure the scripts -can't access your system (other than the specified input data file). +can't access your system (other than the specified input @value{DF}). @item @option{-t} @itemx @option{--lint-old} @@ -4001,9 +4014,9 @@ current element. @cindex input files, variable assignments and @cindex variable assignments and input files -The distinction between file name arguments and variable-assignment +The distinction between @var{FN} 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 +At that point in execution, it checks the @var{FN} to see whether it is really a variable assignment; if so, @command{awk} sets the variable instead of reading a file. @@ -4020,7 +4033,7 @@ sequences (@pxref{Escape Sequences}). @value{DARKCORNER} In some very early implementations of @command{awk}, when a variable assignment -occurred before any file names, the assignment would happen @emph{before} +occurred before any @var{FN}s, the assignment would happen @emph{before} the @code{BEGIN} rule was executed. @command{awk}'s behavior was thus inconsistent; some command-line assignments were available inside the @code{BEGIN} rule, while others were not. Unfortunately, @@ -4031,8 +4044,8 @@ upon the old behavior. The variable assignment feature is most useful for assigning to variables such as @code{RS}, @code{OFS}, and @code{ORS}, which control input and -output formats, before scanning the data files. It is also useful for -controlling state if multiple passes are needed over a data file. For +output formats, before scanning the @value{DF}s. It is also useful for +controlling state if multiple passes are needed over a @value{DF}. For example: @cindex files, multiple passes over @@ -4068,13 +4081,13 @@ You may also use @code{"-"} to name standard input when reading files with @code{getline} (@pxref{Getline/File}). In addition, @command{gawk} allows you to specify the special -file name @file{/dev/stdin}, both on the command line and +@var{FN} @file{/dev/stdin}, both on the command line and with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file in the file system; however, @command{gawk} always processes -this file name itself.) +this @var{FN} itself.) @node Environment Variables @section The Environment Variables @command{gawk} Uses @@ -4104,7 +4117,7 @@ on the command-line with the @option{-f} option. In most @command{awk} implementations, you must supply a precise path name for each program file, unless the file is in the current directory. -But in @command{gawk}, if the file name supplied to the @option{-f} +But in @command{gawk}, if the @var{FN} supplied to the @option{-f} or @option{-i} options 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 @@ -4124,7 +4137,7 @@ though.} The search path feature is particularly helpful for building libraries of useful @command{awk} functions. The library files can be placed in a standard directory in the default path and then specified on -the command line with a short file name. Otherwise, the full file name +the command line with a short @var{FN}. Otherwise, the full @var{FN} would have to be typed for each file. By using the @option{-i} option, or the @option{--source} and @option{-f} options, your command-line @@ -4135,7 +4148,7 @@ This is true for both @option{--traditional} and @option{--posix}. @xref{Options}. If the source code is not found after the initial search, the path is searched -again after adding the default @samp{.awk} suffix to the filename. +again after adding the default @samp{.awk} suffix to the @value{FN}. @quotation NOTE @c 4/2014: @@ -4351,7 +4364,7 @@ use @code{@@include} followed by the name of the file to be included, enclosed in double quotes. @quotation NOTE -Keep in mind that this is a language construct and the file name cannot +Keep in mind that this is a language construct and the @var{FN} cannot be a string variable, but rather just a literal string constant in double quotes. @end quotation @@ -4376,7 +4389,7 @@ $ @kbd{gawk -f test3} @print{} This is file test3. @end example -The file name can, of course, be a pathname. For example: +The @var{FN} can, of course, be a pathname. For example: @example @@include "../io_funcs" @@ -4434,7 +4447,7 @@ to using the @option{-l} command-line option. If the extension is not initially found in @env{AWKLIBPATH}, another search is conducted after appending the platform's default shared library -suffix to the filename. For example, on GNU/Linux systems, the suffix +suffix to the @value{FN}. For example, on GNU/Linux systems, the suffix @samp{.so} is used. @example @@ -4473,7 +4486,7 @@ they will @emph{not} be in the next release). 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 +3.1, but still worked. As of @value{PVERSION} 4.0, they are no longer interpreted specially by @command{gawk}. (Use @code{PROCINFO} instead; see @ref{Auto-set}.) @@ -5185,7 +5198,7 @@ constants, @command{gawk} did @emph{not} match interval expressions in regexps. -However, beginning with version 4.0, +However, beginning with @value{PVERSION} 4.0, @command{gawk} does match interval expressions by default. This is because compatibility with POSIX has become more important to most @command{gawk} users than compatibility with @@ -5503,8 +5516,10 @@ previously described GNU regexp operators. @end ifnotinfo @ifnottex +@ifnotdocbook GNU regexp operators described in @ref{Regexp Operators}. +@end ifnotdocbook @end ifnottex @item @code{--posix} @@ -5894,7 +5909,7 @@ so far from the current input file. This value is stored in a built-in variable called @code{FNR}. It is reset to zero when a new file is started. Another built-in variable, @code{NR}, records the total -number of input records read so far from all data files. It starts at zero, +number of input records read so far from all @value{DF}s. It starts at zero, but is never automatically reset to zero. @menu @@ -5987,7 +6002,7 @@ $ @kbd{awk 'BEGIN @{ RS = "u" @}} @noindent Note that the entry for the name @samp{Bill} is not split. -In the original data file +In the original @value{DF} (@pxref{Sample Data Files}), the line looks like this: @@ -6000,7 +6015,7 @@ 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 +is the original newline in the @value{DF}, not the one added by @command{awk} when it printed the record! @cindex record separators, changing @@ -6149,7 +6164,7 @@ In compatibility mode, only the first character of the value of @end docbook @cindex portability, data files as single record -There are times when you might want to treat an entire data file as a +There are times when you might want to treat an entire @value{DF} as a single record. The only way to make this happen is to give @code{RS} a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary @@ -6199,7 +6214,7 @@ Readfile}, for another option. @cindex portability, data files as single record -There are times when you might want to treat an entire data file as a +There are times when you might want to treat an entire @value{DF} as a single record. The only way to make this happen is to give @code{RS} a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary @@ -7507,7 +7522,7 @@ appear in a row, they are considered one record separator. @cindex dark corner, multiline records However, there is an important difference between @samp{RS = ""} and @samp{RS = "\n\n+"}. In the first case, leading newlines in the input -data file are ignored, and if a file ends without extra blank lines +@value{DF} are ignored, and if a file ends without extra blank lines after the last record, the final newline is removed from the record. In the second case, this special processing is not done. @value{DARKCORNER} @@ -7543,7 +7558,7 @@ Another way to separate fields is to put each field on a separate line: to do this, just set the variable @code{FS} to the string @code{"\n"}. (This single character separator matches a single newline.) -A practical example of a data file organized this way might be a mailing +A practical example of a @value{DF} organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named @file{addresses}, which looks like this: @@ -7608,7 +7623,7 @@ value of @table @code @item RS == "\n" Records are separated by the newline character (@samp{\n}). In effect, -every line in the data file is a separate record, including blank lines. +every line in the @value{DF} is a separate record, including blank lines. This is the default. @item RS == @var{any single character} @@ -7829,7 +7844,7 @@ the value of @code{NF} do not change. @cindex operators, input/output Use @samp{getline < @var{file}} to read the next record from @var{file}. Here @var{file} is a string-valued expression that -specifies the file name. @samp{< @var{file}} is called a @dfn{redirection} +specifies the @var{FN}. @samp{< @var{file}} is called a @dfn{redirection} because it directs input to come from a different place. For example, the following program reads its input record from the file @file{secondary.input} when it @@ -7948,7 +7963,9 @@ 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. @ifnottex +@ifnotdocbook @xref{Close Files And Pipes}. +@end ifnotdocbook @end ifnottex @c Exercise!! @c This example is unrealistic, since you could just use system @@ -8135,10 +8152,10 @@ system permits. @item An interesting side effect occurs if you use @code{getline} without a redirection inside a @code{BEGIN} rule. Because an unredirected @code{getline} -reads from the command-line data files, the first @code{getline} command +reads from the command-line @value{DF}s, the first @code{getline} command causes @command{awk} to set the value of @code{FILENAME}. Normally, @code{FILENAME} does not have a value inside @code{BEGIN} rules, because you -have not yet started to process the command-line data files. +have not yet started to process the command-line @value{DF}s. @value{DARKCORNER} (@xref{BEGIN/END}, also @pxref{Auto-set}.) @@ -8375,7 +8392,7 @@ For printing with specifications, you need the @code{printf} statement @cindex @code{printf} statement Besides basic and formatted printing, this @value{CHAPTER} also covers I/O redirections to files and pipes, introduces -the special file names that @command{gawk} processes internally, +the special @var{FN}s that @command{gawk} processes internally, and discusses the @code{close()} built-in function. @menu @@ -9183,9 +9200,9 @@ but they work identically for @code{printf}: @cindex operators, input/output @item print @var{items} > @var{output-file} This redirection prints the items into the output file named -@var{output-file}. The file name @var{output-file} can be any +@var{output-file}. The @var{FN} @var{output-file} can be any expression. Its value is changed to a string and then used as a -file name (@pxref{Expressions}). +@var{FN} (@pxref{Expressions}). When this type of redirection is used, the @var{output-file} is erased before the first output is written to it. Subsequent writes to the same @@ -9338,7 +9355,9 @@ As mentioned earlier many @end ifnotinfo @ifnottex +@ifnotdocbook Many +@end ifnotdocbook @end ifnottex older @command{awk} implementations limit the number of pipelines that an @command{awk} @@ -9356,7 +9375,7 @@ open as many pipelines as the underlying operating system permits. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, @command{sh}. For example, suppose you -have a list of files brought over from a system where all the file names +have a list of files brought over from a system where all the @var{FN}s are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient: @@ -9388,7 +9407,7 @@ It then sends the list to the shell for execution. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, @command{sh}. For example, suppose you -have a list of files brought over from a system where all the file names +have a list of files brought over from a system where all the @var{FN}s are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient: @@ -9411,12 +9430,12 @@ It then sends the list to the shell for execution. @c ENDOFRANGE reout @node Special Files -@section Special File Names in @command{gawk} +@section Special @value{FFN} in @command{gawk} @c STARTOFRANGE gfn @cindex @command{gawk}, file names in -@command{gawk} provides a number of special file names that it interprets -internally. These file names provide access to standard file descriptors +@command{gawk} provides a number of special @var{FN}s that it interprets +internally. These @var{FN}s provide access to standard file descriptors and TCP/IP networking. @menu @@ -9480,12 +9499,12 @@ that happens, writing to the screen is not correct. In fact, if terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk} provides special file names for accessing the three standard +@command{gawk} provides special @var{FN}s for accessing the three standard streams. @value{COMMONEXT} It also provides syntax for accessing -any other inherited open files. If the file name matches +any other inherited open files. If the @var{FN} matches one of these special names when @command{gawk} redirects input or output, -then it directly uses the stream that the file name stands for. -These special file names work for all operating systems that @command{gawk} +then it directly uses the stream that the @var{FN} stands for. +These special @var{FN}s work for all operating systems that @command{gawk} has been ported to, not just those that are POSIX-compliant: @cindex common extensions, @code{/dev/stdin} special file @@ -9515,7 +9534,7 @@ the shell). Unless special pains are taken in the shell from which @command{gawk} is invoked, only descriptors 0, 1, and 2 are available. @end table -The file names @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} +The @var{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2}, respectively. However, they are more self-explanatory. The proper way to write an error message in a @command{gawk} program @@ -9526,13 +9545,13 @@ print "Serious error detected!" > "/dev/stderr" @end example @cindex troubleshooting, quotes with file names -Note the use of quotes around the file name. +Note the use of quotes around the @var{FN}. Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. @c Exercise: What does it do? :-) -Finally, using the @code{close()} function on a file name of the +Finally, using the @code{close()} function on a @var{FN} of the form @code{"/dev/fd/@var{N}"}, for file descriptor numbers above two, does actually close the given file descriptor. @@ -9548,7 +9567,7 @@ versions of @command{awk}. @command{gawk} programs can open a two-way TCP/IP connection, acting as either a client or a server. -This is done using a special file name of the form: +This is done using a special @var{FN} of the form: @example @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}} @@ -9558,7 +9577,7 @@ The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}. The @var{protocol} is one of @samp{tcp} or @samp{udp}, and the other fields represent the other essential pieces of information for making a networking connection. -These file names are used with the @samp{|&} operator for communicating +These @var{FN}s are used with the @samp{|&} operator for communicating with a coprocess (@pxref{Two-way I/O}). This is an advanced feature, mentioned here only for completeness. @@ -9566,21 +9585,21 @@ Full discussion is delayed until @ref{TCP/IP Networking}. @node Special Caveats -@subsection Special File Name Caveats +@subsection Special @value{FFN} Caveats Here is a list of things to bear in mind when using the -special file names that @command{gawk} provides: +special @var{FN}s that @command{gawk} provides: @itemize @value{BULLET} @cindex compatibility mode (@command{gawk}), file names @cindex file names, in compatibility mode @item -Recognition of these special file names is disabled if @command{gawk} is in +Recognition of these special @var{FN}s is disabled if @command{gawk} is in compatibility mode (@pxref{Options}). @item @command{gawk} @emph{always} -interprets these special file names. +interprets these special @var{FN}s. For example, using @samp{/dev/fd/4} for output actually writes on file descriptor 4, and not on a new file descriptor that is @code{dup()}'ed from file descriptor 4. Most of @@ -9603,7 +9622,7 @@ Doing so results in unpredictable behavior. @cindex coprocesses, closing @cindex @code{getline} command, coprocesses@comma{} using from -If the same file name or the same shell command is used with @code{getline} +If the same @var{FN} or the same shell command is used with @code{getline} more than once during the execution of an @command{awk} program (@pxref{Getline}), the file is opened (or the command is executed) the first time only. @@ -9612,7 +9631,7 @@ The next time the same file or command is used with @code{getline}, another record is read from it, and so on. Similarly, when a file or pipe is opened for output, @command{awk} remembers -the file name or command associated with it, and subsequent +the @var{FN} 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. @@ -9654,7 +9673,7 @@ file or command, or the next @code{print} or @code{printf} to that file or command, reopens the file or reruns the command. Because the expression that you use to close a file or pipeline must exactly match the expression used to open the file or run the command, -it is good practice to use a variable to store the file name or command. +it is good practice to use a variable to store the @var{FN} or command. The previous example becomes the following: @example @@ -9704,7 +9723,7 @@ a separate message. @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 +your @value{DF}s. @command{gawk}'s ability to do this depends upon the facilities of your operating system, so it may not always work. It is therefore both good practice and good portability advice to always use @code{close()} on your files when you are done with them. @@ -10313,7 +10332,7 @@ as in the following: @noindent the variable is set at the very beginning, even before the @code{BEGIN} rules execute. The @option{-v} option and its assignment -must precede all the file name arguments, as well as the program text. +must precede all the @var{FN} arguments, as well as the program text. (@xref{Options}, for more information about the @option{-v} option.) Otherwise, the variable assignment is performed at a time determined by @@ -13590,11 +13609,11 @@ The @code{nextfile} statement is similar to the @code{next} statement. However, instead of abandoning processing of the current record, the @code{nextfile} statement instructs @command{awk} to stop processing the -current data file. +current @value{DF}. Upon execution of the @code{nextfile} statement, @code{FILENAME} is -updated to the name of the next data file listed on the command line, +updated to the name of the next @value{DF} listed on the command line, @code{FNR} is reset to one, and processing starts over with the first rule in the program. @@ -13603,10 +13622,10 @@ then the code in any @code{END} rules is executed. An exception to this is when @code{nextfile} is invoked during execution of any statement in an @code{END} rule; In this case, it causes the program to stop immediately. @xref{BEGIN/END}. -The @code{nextfile} statement is useful when there are many data files +The @code{nextfile} statement is useful when there are many @value{DF}s to process but it isn't necessary to process every record in every file. Without @code{nextfile}, -in order to move on to the next data file, a program +in order to move on to the next @value{DF}, a program would have to continue scanning the unwanted records. The @code{nextfile} statement accomplishes this much more efficiently. @@ -14050,15 +14069,15 @@ about how @command{awk} uses these variables. @cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable @item @code{ARGIND #} The index in @code{ARGV} of the current file being processed. -Every time @command{gawk} opens a new data file for processing, it sets -@code{ARGIND} to the index in @code{ARGV} of the file name. +Every time @command{gawk} opens a new @value{DF} for processing, it sets +@code{ARGIND} to the index in @code{ARGV} of the @var{FN}. When @command{gawk} is processing the input files, @samp{FILENAME == ARGV[ARGIND]} is always true. @cindex files, processing@comma{} @code{ARGIND} variable and This variable is useful in file processing; it allows you to tell how far -along you are in the list of data files as well as to distinguish between -successive instances of the same file name on the command line. +along you are in the list of @value{DF}s as well as to distinguish between +successive instances of the same @var{FN} on the command line. @cindex file names, distinguishing While you can change the value of @code{ARGIND} within your @command{awk} @@ -14106,14 +14125,14 @@ to clear it yourself before doing an I/O operation. @cindex @code{FILENAME} variable @cindex dark corner, @code{FILENAME} variable @item @code{FILENAME} -The name of the current input file. When no data files are listed +The name of the current input file. When no @value{DF}s are listed on the command line, @command{awk} reads from the standard input and @code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} rule, the value of @code{FILENAME} is @code{""}, since there are no input files being processed yet.@footnote{Some early implementations of Unix @command{awk} initialized @code{FILENAME} to @code{"-"}, even if there -were data files to be processed. This behavior was incorrect and should +were @value{DF}s to be processed. This behavior was incorrect and should not be relied upon in your programs.} @value{DARKCORNER} Note, though, that using @code{getline} (@pxref{Getline}) inside a @code{BEGIN} rule can give @code{FILENAME} a value. @@ -14530,11 +14549,11 @@ additional files to be read. If the value of @code{ARGC} is decreased, that eliminates input files from the end of the list. By recording the old value of @code{ARGC} elsewhere, a program can treat the eliminated arguments as -something other than file names. +something other than @var{FN}s. To eliminate a file from the middle of the list, store the null string (@code{""}) into @code{ARGV} in place of the file's name. As a -special feature, @command{awk} ignores file names that have been +special feature, @command{awk} ignores @var{FN}s that have been replaced with the null string. Another option is to use the @code{delete} statement to remove elements from @@ -17183,17 +17202,17 @@ _bigskip} The only case where the difference is noticeable is the last one: @samp{\\\\} is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. -Starting with version 3.1.4, @command{gawk} followed the POSIX rules +Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, it continued to follow the 1996 proposed rules, since that had been its behavior for many years. -When version 4.0.0 was released, the @command{gawk} maintainer +When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer made the POSIX rules the default, breaking well over a decade's worth of backwards compatibility.@footnote{This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules.} Needless to say, this was a bad idea, -and as of version 4.0.1, @command{gawk} resumed its historical +and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical behavior, and only follows the POSIX rules when @option{--posix} is given. The rules for @code{gensub()} are considerably simpler. At the runtime @@ -17373,7 +17392,7 @@ then @command{awk} flushes the buffers for @emph{all} open output files and pipes. @quotation NOTE -Prior to version 4.0.2, @command{gawk} +Prior to @value{PVERSION} 4.0.2, @command{gawk} would flush only the standard output if there was no argument, and flush all output files and pipes if the argument was the null string. This was changed in order to be compatible with Brian @@ -19443,7 +19462,7 @@ function rsort(first, last) @c endfile @end example -Here is an extended version of the data file: +Here is an extended version of the @value{DF}: @example @c file eg/data/class_data2 @@ -19949,7 +19968,7 @@ An @code{END} rule is automatically added to the program calling @code{assert()}. Normally, if a program consists of just a @code{BEGIN} rule, the input files and/or standard input are not read. However, now that the program has an @code{END} rule, @command{awk} -attempts to read the input data files or standard input +attempts to read the input @value{DF}s or standard input (@pxref{Using BEGIN/END}), most likely causing the program to hang as it waits for input. @@ -20436,7 +20455,7 @@ This tests the result to see if it is empty or not. An equivalent test would be @samp{contents == ""}. @node Data File Management -@section Data File Management +@section @value{DDF} Management @c STARTOFRANGE dataf @cindex files, managing @@ -20445,7 +20464,7 @@ test would be @samp{contents == ""}. @c STARTOFRANGE flibdataf @cindex functions, library, managing data files This @value{SECTION} presents functions that are useful for managing -command-line data files. +command-line @value{DF}s. @menu * Filetrans Function:: A function for handling data file transitions. @@ -20456,7 +20475,7 @@ command-line data files. @end menu @node Filetrans Function -@subsection Noting Data File Boundaries +@subsection Noting @value{DDF} Boundaries @cindex files, managing, data file boundaries @cindex files, initialization and cleanup @@ -20464,8 +20483,8 @@ The @code{BEGIN} and @code{END} rules are each executed exactly once at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the -@code{BEGIN} rule is executed at the beginning of each data file and the -@code{END} rule is executed at the end of each data file. +@code{BEGIN} rule is executed at the beginning of each @value{DF} and the +@code{END} rule is executed at the end of each @value{DF}. When informed that this was not the case, the user requested that we add new special @@ -20476,7 +20495,7 @@ Adding these special patterns to @command{gawk} wasn't necessary; the job can be done cleanly in @command{awk} itself, as illustrated by the following library program. It arranges to call two user-supplied functions, @code{beginfile()} and -@code{endfile()}, at the beginning and end of each data file. +@code{endfile()}, at the beginning and end of each @value{DF}. Besides solving the problem in only nine(!) lines of code, it does so @emph{portably}; this works with any implementation of @command{awk}: @@ -20507,17 +20526,17 @@ This file must be loaded before the user's ``main'' program, so that the rule it supplies is executed first. This rule relies on @command{awk}'s @code{FILENAME} variable that -automatically changes for each new data file. The current file name is +automatically changes for each new @value{DF}. The current @var{FN} is saved in a private variable, @code{_oldfilename}. If @code{FILENAME} does -not equal @code{_oldfilename}, then a new data file is being processed and +not equal @code{_oldfilename}, then a new @value{DF} is being processed and it is necessary to call @code{endfile()} for the old file. Because @code{endfile()} should only be called if a file has been processed, the program first checks to make sure that @code{_oldfilename} is not the null -string. The program then assigns the current file name to +string. The program then assigns the current @var{FN} to @code{_oldfilename} and calls @code{beginfile()} for the file. Because, like all @command{awk} variables, @code{_oldfilename} is initialized to the null string, this rule executes correctly even for the -first data file. +first @value{DF}. The program also supplies an @code{END} rule to do the final processing for the last file. Because this @code{END} rule comes before any @code{END} rules @@ -20526,7 +20545,7 @@ again the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function -If the same data file occurs twice in a row on the command line, then +If the same @value{DF} occurs twice in a row on the command line, then @code{endfile()} and @code{beginfile()} are not executed at the end of the first pass and at the beginning of the second pass. The following version solves the problem: @@ -20670,12 +20689,12 @@ The @code{rewind()} function also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). @node File Checking -@subsection Checking for Readable Data Files +@subsection Checking for Readable @value{DDF}s @cindex troubleshooting, readable data files @cindex readable data files@comma{} checking @cindex files, skipping -Normally, if you give @command{awk} a data file that isn't readable, +Normally, if you give @command{awk} a @value{DF} that isn't readable, it stops with a fatal error. There are times when you might want to just ignore such files and keep going.@footnote{The @code{BEGINFILE} special pattern (@pxref{BEGINFILE/ENDFILE}) provides an alternative @@ -20726,15 +20745,15 @@ This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an end of file indication, closes the file, and proceeds on to the next -command-line data file, @emph{without} executing any user-level +command-line @value{DF}, @emph{without} executing any user-level @command{awk} program code. Using @command{gawk}'s @code{ARGIND} variable (@pxref{Built-in Variables}), it is possible to detect when an empty -data file has been skipped. Similar to the library file presented +@value{DF} has been skipped. Similar to the library file presented in @ref{Filetrans Function}, the following library file calls a function named @code{zerofile()} that the user must provide. The arguments passed are -the file name and the position in @code{ARGV} where it was found: +the @var{FN} and the position in @code{ARGV} where it was found: @cindex @code{zerofile.awk} program @example @@ -20822,15 +20841,15 @@ END @{ @end ignore @node Ignoring Assigns -@subsection Treating Assignments as File Names +@subsection Treating Assignments as @value{FFN} @cindex assignments as filenames @cindex filenames, assignments as Occasionally, you might not want @command{awk} to process command-line variable assignments (@pxref{Assignment Options}). -In particular, if you have a file name that contains an @samp{=} character, -@command{awk} treats the file name as an assignment, and does not process it. +In particular, if you have a @var{FN} that contains an @samp{=} character, +@command{awk} treats the @var{FN} as an assignment, and does not process it. Some users have suggested an additional command-line option for @command{gawk} to disable command-line assignments. However, some simple programming with @@ -20874,7 +20893,7 @@ awk -v No_command_assign=1 -f noassign.awk -f yourprog.awk * The function works by looping through the arguments. It prepends @samp{./} to any argument that matches the form -of a variable assignment, turning that argument into a file name. +of a variable assignment, turning that argument into a @var{FN}. The use of @code{No_command_assign} allows you to disable command-line assignments at invocation time, by giving the variable a true value. @@ -21230,7 +21249,7 @@ etc., as its own options. After @code{getopt()} is through, it is the responsibility of the user level code to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the -command-line options as file names. +command-line options as @var{FN}s. @end quotation Several of the sample programs presented in @@ -22101,7 +22120,7 @@ awk -f @var{program} -- @var{options} @var{files} @noindent Here, @var{program} is the name of the @command{awk} program (such as @file{cut.awk}), @var{options} are any command-line options for the -program that start with a @samp{-}, and @var{files} are the actual data files. +program that start with a @samp{-}, and @var{files} are the actual @value{DF}s. If your system supports the @samp{#!} executable interpreter mechanism (@pxref{Executable Scripts}), @@ -22269,7 +22288,7 @@ BEGIN \ OFS = "" @} else if (c == "d") @{ if (length(Optarg) > 1) @{ - printf("Using first character of %s" \ + printf("cut: using first character of %s" \ " for delimiter\n", Optarg) > "/dev/stderr" Optarg = substr(Optarg, 1, 1) @} @@ -22300,7 +22319,7 @@ spaces. Also remember that after @code{getopt()} is through we have to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options -as file names. +as @var{FN}s. After dealing with the command-line options, the program verifies that the options make sense. Only one or the other of @option{-c} and @option{-f} @@ -22350,7 +22369,7 @@ function set_fieldlist( n, m, i, j, k, f, g) m = split(f[i], g, "-") @group if (m != 2 || g[1] >= g[2]) @{ - printf("bad field list: %s\n", + printf("cut: bad field list: %s\n", f[i]) > "/dev/stderr" exit 1 @} @@ -22397,7 +22416,7 @@ function set_charlist( field, i, j, f, g, n, m, t, if (index(f[i], "-") != 0) @{ # range m = split(f[i], g, "-") if (m != 2 || g[1] >= g[2]) @{ - printf("bad character list: %s\n", + printf("cut: bad character list: %s\n", f[i]) > "/dev/stderr" exit 1 @} @@ -22497,8 +22516,8 @@ You invoke it as follows: The @var{pattern} is a regular expression. In typical usage, the regular expression is quoted to prevent the shell from expanding any of the -special characters as file name wildcards. Normally, @command{egrep} -prints the lines that matched. If multiple file names are provided on +special characters as @var{FN} wildcards. Normally, @command{egrep} +prints the lines that matched. If multiple @var{FN}s are provided on the command line, each output line is preceded by the name of the file and a colon. @@ -22589,7 +22608,7 @@ pattern is supplied with @option{-e}, the first nonoption on the command line is used. The @command{awk} command-line arguments up to @code{ARGV[Optind]} are cleared, so that @command{awk} won't try to process them as files. If no files are specified, the standard input is used, and if multiple files are -specified, we make sure to note this so that the file names can precede the +specified, we make sure to note this so that the @var{FN}s can precede the matched lines in the output: @example @@ -22692,9 +22711,9 @@ A number of additional tests are made, but they are only done if we are not counting lines. First, if the user only wants exit status (@code{no_print} is true), then it is enough to know that @emph{one} line in this file matched, and we can skip on to the next file with -@code{nextfile}. Similarly, if we are only printing file names, we can -print the file name, and then skip to the next file with @code{nextfile}. -Finally, each line is printed, with a leading file name and colon +@code{nextfile}. Similarly, if we are only printing @var{FN}s, we can +print the @var{FN}, and then skip to the next file with @code{nextfile}. +Finally, each line is printed, with a leading @var{FN} and colon if necessary: @cindex @code{!} (exclamation point), @code{!} operator @@ -22944,7 +22963,7 @@ number of lines in each file, supply a number on the command line preceded with a minus; e.g., @samp{-500} for files with 500 lines in them instead of 1000. To change the name of the output files to something like @file{myfileaa}, @file{myfileab}, and so on, supply an additional -argument that specifies the file name prefix. +argument that specifies the @var{FN} prefix. Here is a version of @command{split} in @command{awk}. It uses the @code{ord()} and @code{chr()} functions presented in @@ -22954,8 +22973,8 @@ The program first sets its defaults, and then tests to make sure there are not too many arguments. It then looks at each argument in turn. The first argument could be a minus sign followed by a number. If it is, this happens to look like a negative number, so it is made positive, and that is the -count of lines. The data file name is skipped over and the final argument -is used as the prefix for the output file names: +count of lines. The @value{DF} name is skipped over and the final argument +is used as the prefix for the output @value{FN}s: @cindex @code{split.awk} program @example @@ -23005,7 +23024,7 @@ BEGIN @{ The next rule does most of the work. @code{tcount} (temporary count) tracks how many lines have been printed to the output file so far. If it is greater than @code{count}, it is time to close the current file and start a new one. -@code{s1} and @code{s2} track the current suffixes for the file name. If +@code{s1} and @code{s2} track the current suffixes for the @value{FN}. If they are both @samp{z}, the file is just too big. Otherwise, @code{s1} moves to the next letter in the alphabet and @code{s2} starts over again at @samp{a}: @@ -23089,13 +23108,13 @@ The @code{BEGIN} rule first makes a copy of all the command-line arguments into an array named @code{copy}. @code{ARGV[0]} is not copied, since it is not needed. @code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to -process each file name in @code{ARGV} as input data. +process each @value{FN} in @code{ARGV} as input data. @cindex flag variables If the first argument is @option{-a}, then the flag variable @code{append} is set to true, and both @code{ARGV[1]} and @code{copy[1]} are deleted. If @code{ARGC} is less than two, then no -file names were supplied and @code{tee} prints a usage message and exits. +@value{FN}s were supplied and @code{tee} prints a usage message and exits. Finally, @command{awk} is forced to read the standard input by setting @code{ARGV[1]} to @code{"-"} and @code{ARGC} to two: @@ -23561,7 +23580,7 @@ BEGIN @{ @end example The @code{beginfile()} function is simple; it just resets the counts of lines, -words, and characters to zero, and saves the current file name in +words, and characters to zero, and saves the current @value{FN} in @code{fname}: @example @@ -23583,7 +23602,7 @@ you will see that @code{FNR} has already been reset by the time @code{endfile()} is called.} It then prints out those numbers for the file that was just read. It relies on @code{beginfile()} to reset the -numbers for the following data file: +numbers for the following @value{DF}: @c FIXME: ONE DAY: make the above footnote an exercise, @c instead of giving away the answer. @@ -23902,7 +23921,7 @@ is how long to wait before setting off the alarm: # how long to sleep for naptime = target - current if (naptime <= 0) @{ - print "time is in the past!" > "/dev/stderr" + print "alarm: time is in the past!" > "/dev/stderr" exit 1 @} @c endfile @@ -24375,7 +24394,7 @@ The @command{uniq} program (@pxref{Uniq Program}), removes duplicate lines from @emph{sorted} data. -Suppose, however, you need to remove duplicate lines from a data file but +Suppose, however, you need to remove duplicate lines from a @value{DF} but that you want to preserve the order the lines are in. A good example of this might be a shell history file. The history file keeps a copy of all the commands you have entered, and it is not unusual to repeat a command @@ -24571,7 +24590,7 @@ BEGIN @{ IGNORECASE = 1 @} /^@@c(omment)?[ \t]+system/ \ @{ if (NF < 3) @{ - e = (FILENAME ":" FNR) + e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") print e > "/dev/stderr" next @@ -24580,7 +24599,7 @@ BEGIN @{ IGNORECASE = 1 @} $2 = "" stat = system($0) if (stat != 0) @{ - e = (FILENAME ":" FNR) + e = ("extract: " FILENAME ":" FNR) e = (e ": warning: system returned " stat) print e > "/dev/stderr" @} @@ -24593,7 +24612,7 @@ The variable @code{e} is used so that the rule fits nicely on the @value{PAGE}. The second rule handles moving data into files. It verifies that a -file name is given in the directive. If the file named is not the +@value{FN} is given in the directive. If the file named is not the current file, then the current file is closed. Keeping the current file open until a new file is encountered allows the use of the @samp{>} redirection for printing the contents, keeping open file management @@ -24633,7 +24652,7 @@ line. That line is then printed to the output file: /^@@c(omment)?[ \t]+file/ \ @{ if (NF != 3) @{ - e = (FILENAME ":" FNR ": badly formed `file' line") + e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" next @} @@ -24678,7 +24697,7 @@ subsequent output is appended to the file (@pxref{Redirection}). This makes it easy to mix program text and explanatory prose for the same sample source file (as has been done here!) without any hassle. The file is -only closed when a new data file name is encountered or at the end of the +only closed when a new @value{DF} name is encountered or at the end of the input file. Finally, the function @code{@w{unexpected_eof()}} prints an appropriate @@ -24690,7 +24709,7 @@ The @code{END} rule handles the final cleanup, closing the open file: @group function unexpected_eof() @{ - printf("%s:%d: unexpected EOF or error\n", + printf("extract: %s:%d: unexpected EOF or error\n", FILENAME, FNR) > "/dev/stderr" exit 1 @} @@ -24730,7 +24749,7 @@ Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp The following program, @file{awksed.awk}, accepts at least two command-line arguments: the pattern to look for and the text to replace it with. Any -additional arguments are treated as data file names to process. If none +additional arguments are treated as @value{DF} names to process. If none are provided, the standard input is used: @cindex Brennan, Michael @@ -24804,7 +24823,7 @@ The @code{BEGIN} rule handles the setup, checking for the right number of arguments and calling @code{usage()} if there is a problem. Then it sets @code{RS} and @code{ORS} from the command-line arguments and sets @code{ARGV[1]} and @code{ARGV[2]} to the null string, so that they are -not treated as file names +not treated as @value{FN}s (@pxref{ARGC and ARGV}). The @code{usage()} function prints an error message and exits. @@ -24903,7 +24922,7 @@ Literal text, provided with @option{--source} or @option{--source=}. This text is just appended directly. @item -Source file names, provided with @option{-f}. We use a neat trick and append +Source @value{FN}s, provided with @option{-f}. We use a neat trick and append @samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion program works the way @command{gawk} does, this gets the text of the file included into the program at the correct point. @@ -24916,7 +24935,7 @@ shell variable. @item Run the expanded program with @command{gawk} and any other original command-line -arguments that the user supplied (such as the data file names). +arguments that the user supplied (such as the @value{DF} names). @end enumerate This program uses shell variables extensively: for storing command-line arguments, @@ -24948,7 +24967,7 @@ programming trick. Don't worry about it if you are not familiar with These are saved and passed on to @command{gawk}. @item @option{-f}, @option{--file}, @option{--file=}, @option{-Wfile=} -The file name is appended to the shell variable @code{program} with an +The @value{FN} is appended to the shell variable @code{program} with an @code{@@include} statement. The @command{expr} utility is used to remove the leading option part of the argument (e.g., @samp{--file=}). @@ -25073,10 +25092,10 @@ is stored in the shell variable @code{expand_prog}. Doing this keeps the shell script readable. The @command{awk} program reads through the user's program, one line at a time, using @code{getline} (@pxref{Getline}). The input -file names and @code{@@include} statements are managed using a stack. -As each @code{@@include} is encountered, the current file name is +@value{FN}s and @code{@@include} statements are managed using a stack. +As each @code{@@include} is encountered, the current @value{FN} is ``pushed'' onto the stack and the file named in the @code{@@include} -directive becomes the current file name. As each file is finished, +directive becomes the current @value{FN}. As each file is finished, the stack is ``popped,'' and the previous input file becomes the current input file again. The process is started by making the original file the first one on the stack. @@ -25085,16 +25104,16 @@ The @code{pathto()} function does the work of finding the full path to a file. It simulates @command{gawk}'s behavior when searching the @env{AWKPATH} environment variable (@pxref{AWKPATH Variable}). -If a file name has a @samp{/} in it, no path search is done. -Similarly, if the file name is @code{"-"}, then that string is +If a @value{FN} has a @samp{/} in it, no path search is done. +Similarly, if the @value{FN} is @code{"-"}, then that string is used as-is. Otherwise, -the file name is concatenated with the name of each directory in -the path, and an attempt is made to open the generated file name. +the @value{FN} is concatenated with the name of each directory in +the path, and an attempt is made to open the generated @value{FN}. The only way to test if a file can be read in @command{awk} is to go ahead and try to read it with @code{getline}; this is what @code{pathto()} does.@footnote{On some very old versions of @command{awk}, the test @samp{getline junk < t} can loop forever if the file exists but is empty. -Caveat emptor.} If the file can be read, it is closed and the file name +Caveat emptor.} If the file can be read, it is closed and the @value{FN} is returned: @ignore @@ -25152,14 +25171,14 @@ BEGIN @{ The stack is initialized with @code{ARGV[1]}, which will be @code{"/dev/stdin"}. The main loop comes next. Input lines are read in succession. Lines that do not start with @code{@@include} are printed verbatim. -If the line does start with @code{@@include}, the file name is in @code{$2}. +If the line does start with @code{@@include}, the @value{FN} is in @code{$2}. @code{pathto()} is called to generate the full path. If it cannot, then the program prints an error message and continues. The next thing to check is if the file is included already. The -@code{processed} array is indexed by the full file name of each included +@code{processed} array is indexed by the full @value{FN} of each included file and it tracks this information for us. If the file is -seen again, a warning message is printed. Otherwise, the new file name is +seen again, a warning message is printed. Otherwise, the new @value{FN} is pushed onto the stack and processing continues. Finally, when @code{getline} encounters the end of the input file, the file @@ -25180,7 +25199,7 @@ the program is done: fpath = pathto($2) @group if (fpath == "") @{ - printf("igawk:%s:%d: cannot find %s\n", + printf("igawk: %s:%d: cannot find %s\n", input[stackptr], FNR, $2) > "/dev/stderr" continue @} @@ -25237,10 +25256,10 @@ options and command-line arguments that the user supplied. @c this causes more problems than it solves, so leave it out. @ignore -The special file @file{/dev/null} is passed as a data file to @command{gawk} +The special file @file{/dev/null} is passed as a @value{DF} to @command{gawk} to handle an interesting case. Suppose that the user's program only has -a @code{BEGIN} rule and there are no data files to read. -The program should exit without reading any data files. +a @code{BEGIN} rule and there are no @value{DF}s to read. +The program should exit without reading any @value{DF}s. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the @@ -26339,10 +26358,10 @@ another process on another system across an IP network connection. You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is -by recognizing special file names that begin with one of @samp{/inet/}, +by recognizing special @value{FN}s that begin with one of @samp{/inet/}, @samp{/inet4/} or @samp{/inet6}. -The full syntax of the special file name is +The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. The components are: @@ -27523,10 +27542,11 @@ complete detail in @inforef{Top, , GNU @command{gettext} utilities, gettext, GNU gettext tools}.) @end ifinfo @ifnotinfo -@cite{GNU gettext tools}.) +@uref{http://www.gnu.org/software/gettext/manual/, +@cite{GNU gettext tools}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz, version 0.18.2.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.tar.gz, @value{PVERSION} 0.19}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -28432,7 +28452,7 @@ functions which called the one you are in. The commands for doing this are: Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each -function, the source file name, and the line number. +function, the source @value{FN}, and the line number. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -28498,7 +28518,7 @@ Description of the selected stack frame. @item functions @cindex list function definitions, in debugger -List all function definitions including source file names and +List all function definitions including source @value{FN}s and line numbers. @item locals @@ -28586,7 +28606,7 @@ Turn instruction tracing on or off. The default is @code{off}. @end table @item @code{save} @var{filename} -Save the commands from the current session to the given file name, +Save the commands from the current session to the given @value{FN}, so that they can be replayed using the @command{source} command. @item @code{source} @var{filename} @@ -28760,8 +28780,8 @@ of completion are available: @item Command completion Command names. -@item Source file name completion -Source file names. Relevant commands are +@item Source @value{FN} completion +Source @value{FN}s. Relevant commands are @code{break}, @code{clear}, @code{list}, @@ -30019,7 +30039,7 @@ the problem at hand is often the correct approach in such situations. If one of the options @option{--bignum} or @option{-M} is specified, @command{gawk} performs all integer arithmetic using GMP arbitrary precision integers. -Any number that looks like an integer in a program source or data file +Any number that looks like an integer in a program source or @value{DF} is stored as an arbitrary precision integer. The size of the integer is limited only by your computer's memory. The current floating-point context has no effect on operations involving integers. @@ -31441,7 +31461,7 @@ The fields are as follows: The name of the two-way processor. @item awk_bool_t (*can_take_two_way)(const char *name); -This function returns true if it wants to take over two-way I/O for this filename. +This function returns true if it wants to take over two-way I/O for this @value{FN}. It should not change any state (variable values, etc.) within @command{gawk}. @@ -33317,7 +33337,7 @@ array with information retrieved from the filesystem, as follows: @multitable @columnfractions .15 .50 .20 @headitem Subscript @tab Field in @code{struct stat} @tab File type -@item @code{"name"} @tab The file name @tab All +@item @code{"name"} @tab The @value{FN} @tab All @item @code{"dev"} @tab @code{st_dev} @tab All @item @code{"ino"} @tab @code{st_ino} @tab All @item @code{"mode"} @tab @code{st_mode} @tab All @@ -33368,7 +33388,7 @@ The arguments are as follows: @table @code @item pathlist -An array of filenames. The element values are used; the index values are ignored. +An array of @value{FN}s. The element values are used; the index values are ignored. @item flags This should be the bitwise OR of one or more of the following @@ -33492,10 +33512,10 @@ The arguments to @code{fnmatch()} are: @table @code @item pattern -The filename wildcard to match. +The @var{FN} wildcard to match. @item string -The filename string. +The @var{FN} string. @item flag Either zero, or the bitwise OR of one or more of the @@ -33602,8 +33622,8 @@ standard output to a temporary file configured to have the same owner and permissions as the original. After the file has been processed, the extension restores standard output to its original destination. If @code{INPLACE_SUFFIX} is not an empty string, the original file is -linked to a backup filename created by appending that suffix. Finally, -the temporary file is renamed to the original filename. +linked to a backup @var{FN} created by appending that suffix. Finally, +the temporary file is renamed to the original @var{FN}. If any error occurs, the extension issues a fatal error to terminate processing immediately without damaging the original file. @@ -33669,7 +33689,7 @@ on the command line (or with @code{getline}), they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode number and the -filename, separated by a forward slash character. +@var{FN}, separated by a forward slash character. On systems where the directory entry contains the file type, the record has a third field (also separated by a slash) which is a single letter indicating the type of the file. The letters are file types are shown @@ -34352,7 +34372,7 @@ Special files in I/O redirections: @itemize @value{MINUS} @item The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and -@file{/dev/fd/@var{N}} special file names +@file{/dev/fd/@var{N}} special @value{FN}s (@pxref{Special Files}). @item @@ -34576,7 +34596,7 @@ long options @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} version 4.0: +and the documentation for @command{gawk} @value{PVERSION} 4.0: @c nested table @itemize @value{MINUS} @@ -34669,7 +34689,7 @@ The @code{IGNORECASE} variable and its effects @item The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and -@file{/dev/fd/@var{N}} special file names +@file{/dev/fd/@var{N}} special @value{FN}s (@pxref{Special Files}). @end itemize @@ -34706,7 +34726,7 @@ Version 2.14 of @command{gawk} introduced the following feature: @itemize @value{BULLET} @item -The @code{next file} statement for skipping to the next data file +The @code{next file} statement for skipping to the next @value{DF} (@pxref{Nextfile Statement}). @end itemize @@ -34728,7 +34748,7 @@ through @code{ARGV}. @item The @file{/dev/pid}, @file{/dev/ppid}, @file{/dev/pgrpid}, and -@file{/dev/user} special file names. These have since been removed. +@file{/dev/user} special @value{FN}s. These have since been removed. @item The ability to delete all of an array at once with @samp{delete @var{array}} @@ -35350,7 +35370,7 @@ like ``why does @samp{[A-Z]} match lowercase letters?!?'' This situation existed for close to 10 years, if not more, and the @command{gawk} maintainer grew weary of trying to explain that @command{gawk} was being nicely standards-compliant, and that the issue -was in the user's locale. During the development of version 4.0, +was in the user's locale. During the development of @value{PVERSION} 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And thus was born the Campaign for Rational Range Interpretation (or @@ -35731,7 +35751,7 @@ Extracting the archive creates a directory named @file{gawk-@value{VERSION}.@value{PATCHLEVEL}} in the current directory. -The distribution file name is of the form +The distribution @value{FN} is of the form @file{gawk-@var{V}.@var{R}.@var{P}.tar.gz}. The @var{V} represents the major version of @command{gawk}, the @var{R} represents the current release of version @var{V}, and @@ -36400,7 +36420,7 @@ the @command{configure} script as is the case for the Unix versions. If @file{c:/usr} is the prefix directory then the default search path contains @file{.} and @file{c:/usr/share/awk}. Additionally, to support binary distributions of @command{gawk} for OS/2 -systems whose drive @samp{c:} might not support long file names or might not exist +systems whose drive @samp{c:} might not support long @value{FN}s or might not exist at all, there is a special environment variable. If @env{UNIXROOT} specifies a drive then this specific drive is also searched for program files. E.g., if @env{UNIXROOT} is set to @file{e:} the complete default search path is @@ -36595,7 +36615,7 @@ $ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms gawk} @end example @command{MMK} is an open source, free, near-clone of @command{MMS} and -can better handle ODS-5 volumes with upper- and lowercase filenames. +can better handle ODS-5 volumes with upper- and lowercase @var{FN}s. @command{MMK} is available from @uref{https://github.com/endlesssoftware/mmk}. With ODS-5 volumes and extended parsing enabled, the case of the target @@ -36726,11 +36746,11 @@ provides information about both the @command{gawk} implementation and the The logical name @samp{AWK_LIBRARY} can designate a default location for @command{awk} program files. For the @option{-f} option, if the specified -file name has no device or directory path information in it, @command{gawk} +@value{FN} has no device or directory path information in it, @command{gawk} looks in the current directory first, then in the directory specified by the translation of @samp{AWK_LIBRARY} if the file is not found. If, after searching in both directories, the file still is not found, -@command{gawk} appends the suffix @samp{.awk} to the filename and retries +@command{gawk} appends the suffix @samp{.awk} to the @var{FN} and retries the file search. If @samp{AWK_LIBRARY} has no definition, a default value of @samp{SYS$LIBRARY:} is used for it. @@ -36759,7 +36779,7 @@ One side effect of dual command-line parsing is that if there is only a single parameter (as in the quoted string program above), the command becomes ambiguous. To work around this, the normally optional @option{--} flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any -other dash-type options (or multiple parameters such as data files to +other dash-type options (or multiple parameters such as @value{DF}s to process) are present, there is no ambiguity and @option{--} can be omitted. @cindex exit status, of VMS @@ -36868,7 +36888,7 @@ define a symbol, as follows: $ @kbd{gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe} @end example -This is apparently version 2.15.6, which is extremely old. We +This is apparently @value{PVERSION} 2.15.6, which is extremely old. We recommend compiling and using the current version. @c ENDOFRANGE opgawx @@ -36897,8 +36917,8 @@ what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it -to the smallest possible @command{awk} program and input data file that -reproduces the problem. Then send us the program and data file, +to the smallest possible @command{awk} program and input @value{DF} that +reproduces the problem. Then send us the program and @value{DF}, some idea of what kind of Unix system you're using, the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps @@ -38113,7 +38133,7 @@ to any of the above. @ref{Dynamic Extensions}, describes the supported API and mechanisms for writing extensions for @command{gawk}. This API was introduced -in version 4.1. However, for many years @command{gawk} +in @value{PVERSION} 4.1. However, for many years @command{gawk} provided an extension mechanism that required knowledge of @command{gawk} internals and that was not as well designed. @@ -39105,7 +39125,7 @@ numeric values. It is the C type @code{float}. The character generated by hitting the space bar on the keyboard. @item Special File -A file name interpreted internally by @command{gawk}, instead of being handed +A @value{FN} interpreted internally by @command{gawk}, instead of being handed directly to the underlying operating system---for example, @file{/dev/stderr}. (@xref{Special Files}.) @@ -40521,9 +40541,6 @@ ORA uses filename, thus the macro. Suggestions: ------------ -% Next edition: -% 1. Standardize the error messages from the functions and programs -% in the two sample code chapters. Better sidebars can almost sort of be done with: diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 69abf674..b80a6849 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -46,12 +46,10 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH April, 2014 +@set UPDATE-MONTH June, 2014 @set VERSION 4.1 @set PATCHLEVEL 1 -@set FSF - @set TITLE GAWK: Effective AWK Programming @set SUBTITLE A User's Guide for GNU Awk @set EDITION 4.1 @@ -162,6 +160,21 @@ @end macro @end ifdocbook +@ifclear FOR_PRINT +@set FN file name +@set FFN File Name +@set DF data file +@set DDF Data File +@set PVERSION version +@end ifclear +@ifset FOR_PRINT +@set FN filename +@set FFN Filename +@set DF datafile +@set DDF Datafile +@set PVERSION Version +@end ifset + @c For HTML, spell out email addresses, to avoid problems with @c address harvesters for spammers. @ifhtml @@ -1345,11 +1358,11 @@ wrote the bulk of @cite{TCP/IP Internetworking with @command{gawk}} (a separate document, available as part of the @command{gawk} distribution). His code finally became part of the main @command{gawk} distribution -with @command{gawk} version 3.1. +with @command{gawk} @value{PVERSION} 3.1. John Haque rewrote the @command{gawk} internals, in the process providing an @command{awk}-level debugger. This version became available as -@command{gawk} version 4.0, in 2011. +@command{gawk} @value{PVERSION} 4.0, in 2011. @xref{Contributors}, for a complete list of those who made important contributions to @command{gawk}. @@ -1421,7 +1434,7 @@ the POSIX standard for @command{awk} are noted. This @value{DOCUMENT} has the difficult task of being both a tutorial and a reference. If you are a novice, feel free to skip over details that seem too complex. You should also ignore the many cross-references; they are for the -expert user and for the online Info and HTML versions of the document. +expert user and for the online Info and HTML versions of the @value{DOCUMENT}. @end ifnotinfo There are sidebars @@ -1643,7 +1656,7 @@ emphasized @emph{like this}, and if a point needs to be made strongly, it is done @strong{like this}. The first occurrence of a new term is usually its @dfn{definition} and appears in the same font as the previous occurrence of ``definition'' in this sentence. -Finally, file names are indicated like this: @file{/path/to/ourfile}. +Finally, @var{FN}s are indicated like this: @file{/path/to/ourfile}. @end ifnotinfo Characters that you type at the keyboard look @kbd{like this}. In particular, @@ -2298,7 +2311,7 @@ awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{} @cindex @option{-f} option @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 +from the file @var{source-file}. Any @var{FN} can be used for @var{source-file}. For example, you could put the program: @example @@ -2323,8 +2336,8 @@ awk "BEGIN @{ print \"Don't Panic!\" @}" @noindent This was explained earlier (@pxref{Read Terminal}). -Note that you don't usually need single quotes around the file name that you -specify with @option{-f}, because most file names don't contain any of the shell's +Note that you don't usually need single quotes around the @var{FN} that you +specify with @option{-f}, because most @var{FN}s don't contain any of the shell's special characters. Notice that in @file{advice}, the @command{awk} program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. @@ -2334,7 +2347,7 @@ for programs that are provided on the @command{awk} command line. @c STARTOFRANGE qs2x @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 +you can add the extension @file{.awk} to the @var{FN}. This doesn't affect the execution of the @command{awk} program but it does make ``housekeeping'' easier. @@ -2361,13 +2374,13 @@ BEGIN @{ print "Don't Panic!" @} After making this file executable (with the @command{chmod} utility), simply type @samp{advice} at the shell and the system arranges to run @command{awk}@footnote{The -line beginning with @samp{#!} lists the full file name of an interpreter +line beginning with @samp{#!} lists the full @var{FN} of an interpreter to run and an optional initial command-line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument -in the list is the full file name of the @command{awk} program. +in the list is the full @var{FN} of the @command{awk} program. The rest of the -argument list contains either options to @command{awk}, or data files, +argument list contains either options to @command{awk}, or @value{DF}s, or both. Note that on many systems @command{awk} may be found in @file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had typed @samp{awk -f advice}: @@ -2599,7 +2612,7 @@ awk -F"" '@var{program}' @var{files} # wrong! @noindent In the second case, @command{awk} will attempt to use the text of the program -as the value of @code{FS}, and the first file name as the text of the program! +as the value of @code{FS}, and the first @var{FN} as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize @@ -2715,18 +2728,18 @@ gawk "@{ print \"\042\" $0 \"\042\" @}" @var{file} @node Sample Data Files -@section Data Files for the Examples +@section @value{DDF}s for the Examples @cindex input files, examples @cindex @code{mail-list} file Many of the examples in this @value{DOCUMENT} take their input from two sample -data files. The first, @file{mail-list}, represents a list of peoples' names +@value{DF}s. 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 +The second @value{DF}, 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{mail-list}, each record contains the name of a person, +In the @value{DF} @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 @@ -2755,7 +2768,7 @@ Jean-Paul 555-2127 jeanpaul.campanorum@@nyu.edu R @end example @cindex @code{inventory-shipped} file -The data file @file{inventory-shipped} represents +The @value{DF} @file{inventory-shipped} represents information about shipments during the year. Each record contains the month, the number of green crates shipped, the number of red boxes shipped, the number of @@ -2847,9 +2860,9 @@ collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description of the program will give you a good idea of what is going on, but please read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) -Most of the examples use a data file named @file{data}. This is just a +Most of the examples use a @value{DF} named @file{data}. This is just a placeholder; if you use these programs yourself, substitute -your own file names for @file{data}. +your own @var{FN}s for @file{data}. For future reference, note that there is often more than one way to do things in @command{awk}. At some point, you may want to look back at these examples and see if @@ -2939,7 +2952,7 @@ awk 'END @{ print NR @}' data @end example @item -Print the even-numbered lines in the data file: +Print the even-numbered lines in the @value{DF}: @example awk 'NR % 2 == 0' data @@ -2981,7 +2994,7 @@ This program prints every line that contains the string @samp{12} @emph{or} the string @samp{21}. If a line contains both strings, it is printed twice, once by each rule. -This is what happens if we run this program on our two sample data files, +This is what happens if we run this program on our two sample @value{DF}s, @file{mail-list} and @file{inventory-shipped}: @example @@ -3041,7 +3054,7 @@ the file. The fourth field identifies the group of the file. The fifth field contains the size of the file in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the file name.@footnote{The @samp{LC_ALL=C} is +contains the @var{FN}.@footnote{The @samp{LC_ALL=C} is needed to produce this traditional-style output from @command{ls}.} @c @cindex automatic initialization @@ -3444,8 +3457,8 @@ conventions. @cindex @code{-} (hyphen), filenames beginning with @cindex hyphen (@code{-}), filenames beginning with -This is useful if you have file names that start with @samp{-}, -or in shell scripts, if you have file names that will be specified +This is useful if you have @var{FN}s that start with @samp{-}, +or in shell scripts, if you have @var{FN}s that will be specified by the user that could start with @samp{-}. It is also useful for passing options on to the @command{awk} program; see @ref{Getopt Function}. @@ -3690,7 +3703,7 @@ Enable pretty-printing of @command{awk} programs. By default, output program is created in a file named @file{awkprof.out} (@pxref{Profiling}). The optional @var{file} argument allows you to specify a different -file name for the output. +@var{FN} for the output. No space is allowed between the @option{-o} and @var{file}, if @var{file} is supplied. @@ -3717,7 +3730,7 @@ Enable profiling of @command{awk} programs (@pxref{Profiling}). By default, profiles are created in a file named @file{awkprof.out}. The optional @var{file} argument allows you to specify a different -file name for the profile file. +@var{FN} for the profile file. No space is allowed between the @option{-p} and @var{file}, if @var{file} is supplied. @@ -3797,7 +3810,7 @@ output redirections with @code{print} and @code{printf}, and dynamic extensions. This is particularly useful when you want to run @command{awk} scripts from questionable sources and need to make sure the scripts -can't access your system (other than the specified input data file). +can't access your system (other than the specified input @value{DF}). @item @option{-t} @itemx @option{--lint-old} @@ -3929,9 +3942,9 @@ current element. @cindex input files, variable assignments and @cindex variable assignments and input files -The distinction between file name arguments and variable-assignment +The distinction between @var{FN} 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 +At that point in execution, it checks the @var{FN} to see whether it is really a variable assignment; if so, @command{awk} sets the variable instead of reading a file. @@ -3948,7 +3961,7 @@ sequences (@pxref{Escape Sequences}). @value{DARKCORNER} In some very early implementations of @command{awk}, when a variable assignment -occurred before any file names, the assignment would happen @emph{before} +occurred before any @var{FN}s, the assignment would happen @emph{before} the @code{BEGIN} rule was executed. @command{awk}'s behavior was thus inconsistent; some command-line assignments were available inside the @code{BEGIN} rule, while others were not. Unfortunately, @@ -3959,8 +3972,8 @@ upon the old behavior. The variable assignment feature is most useful for assigning to variables such as @code{RS}, @code{OFS}, and @code{ORS}, which control input and -output formats, before scanning the data files. It is also useful for -controlling state if multiple passes are needed over a data file. For +output formats, before scanning the @value{DF}s. It is also useful for +controlling state if multiple passes are needed over a @value{DF}. For example: @cindex files, multiple passes over @@ -3996,13 +4009,13 @@ You may also use @code{"-"} to name standard input when reading files with @code{getline} (@pxref{Getline/File}). In addition, @command{gawk} allows you to specify the special -file name @file{/dev/stdin}, both on the command line and +@var{FN} @file{/dev/stdin}, both on the command line and with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file in the file system; however, @command{gawk} always processes -this file name itself.) +this @var{FN} itself.) @node Environment Variables @section The Environment Variables @command{gawk} Uses @@ -4032,7 +4045,7 @@ on the command-line with the @option{-f} option. In most @command{awk} implementations, you must supply a precise path name for each program file, unless the file is in the current directory. -But in @command{gawk}, if the file name supplied to the @option{-f} +But in @command{gawk}, if the @var{FN} supplied to the @option{-f} or @option{-i} options 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 @@ -4052,7 +4065,7 @@ though.} The search path feature is particularly helpful for building libraries of useful @command{awk} functions. The library files can be placed in a standard directory in the default path and then specified on -the command line with a short file name. Otherwise, the full file name +the command line with a short @var{FN}. Otherwise, the full @var{FN} would have to be typed for each file. By using the @option{-i} option, or the @option{--source} and @option{-f} options, your command-line @@ -4063,7 +4076,7 @@ This is true for both @option{--traditional} and @option{--posix}. @xref{Options}. If the source code is not found after the initial search, the path is searched -again after adding the default @samp{.awk} suffix to the filename. +again after adding the default @samp{.awk} suffix to the @value{FN}. @quotation NOTE @c 4/2014: @@ -4279,7 +4292,7 @@ use @code{@@include} followed by the name of the file to be included, enclosed in double quotes. @quotation NOTE -Keep in mind that this is a language construct and the file name cannot +Keep in mind that this is a language construct and the @var{FN} cannot be a string variable, but rather just a literal string constant in double quotes. @end quotation @@ -4304,7 +4317,7 @@ $ @kbd{gawk -f test3} @print{} This is file test3. @end example -The file name can, of course, be a pathname. For example: +The @var{FN} can, of course, be a pathname. For example: @example @@include "../io_funcs" @@ -4362,7 +4375,7 @@ to using the @option{-l} command-line option. If the extension is not initially found in @env{AWKLIBPATH}, another search is conducted after appending the platform's default shared library -suffix to the filename. For example, on GNU/Linux systems, the suffix +suffix to the @value{FN}. For example, on GNU/Linux systems, the suffix @samp{.so} is used. @example @@ -4401,7 +4414,7 @@ they will @emph{not} be in the next release). 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 +3.1, but still worked. As of @value{PVERSION} 4.0, they are no longer interpreted specially by @command{gawk}. (Use @code{PROCINFO} instead; see @ref{Auto-set}.) @@ -5030,7 +5043,7 @@ constants, @command{gawk} did @emph{not} match interval expressions in regexps. -However, beginning with version 4.0, +However, beginning with @value{PVERSION} 4.0, @command{gawk} does match interval expressions by default. This is because compatibility with POSIX has become more important to most @command{gawk} users than compatibility with @@ -5348,8 +5361,10 @@ previously described GNU regexp operators. @end ifnotinfo @ifnottex +@ifnotdocbook GNU regexp operators described in @ref{Regexp Operators}. +@end ifnotdocbook @end ifnottex @item @code{--posix} @@ -5695,7 +5710,7 @@ so far from the current input file. This value is stored in a built-in variable called @code{FNR}. It is reset to zero when a new file is started. Another built-in variable, @code{NR}, records the total -number of input records read so far from all data files. It starts at zero, +number of input records read so far from all @value{DF}s. It starts at zero, but is never automatically reset to zero. @menu @@ -5788,7 +5803,7 @@ $ @kbd{awk 'BEGIN @{ RS = "u" @}} @noindent Note that the entry for the name @samp{Bill} is not split. -In the original data file +In the original @value{DF} (@pxref{Sample Data Files}), the line looks like this: @@ -5801,7 +5816,7 @@ 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 +is the original newline in the @value{DF}, not the one added by @command{awk} when it printed the record! @cindex record separators, changing @@ -5945,7 +5960,7 @@ In compatibility mode, only the first character of the value of @sidebar @code{RS = "\0"} Is Not Portable @cindex portability, data files as single record -There are times when you might want to treat an entire data file as a +There are times when you might want to treat an entire @value{DF} as a single record. The only way to make this happen is to give @code{RS} a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary @@ -7126,7 +7141,7 @@ appear in a row, they are considered one record separator. @cindex dark corner, multiline records However, there is an important difference between @samp{RS = ""} and @samp{RS = "\n\n+"}. In the first case, leading newlines in the input -data file are ignored, and if a file ends without extra blank lines +@value{DF} are ignored, and if a file ends without extra blank lines after the last record, the final newline is removed from the record. In the second case, this special processing is not done. @value{DARKCORNER} @@ -7162,7 +7177,7 @@ Another way to separate fields is to put each field on a separate line: to do this, just set the variable @code{FS} to the string @code{"\n"}. (This single character separator matches a single newline.) -A practical example of a data file organized this way might be a mailing +A practical example of a @value{DF} organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named @file{addresses}, which looks like this: @@ -7227,7 +7242,7 @@ value of @table @code @item RS == "\n" Records are separated by the newline character (@samp{\n}). In effect, -every line in the data file is a separate record, including blank lines. +every line in the @value{DF} is a separate record, including blank lines. This is the default. @item RS == @var{any single character} @@ -7448,7 +7463,7 @@ the value of @code{NF} do not change. @cindex operators, input/output Use @samp{getline < @var{file}} to read the next record from @var{file}. Here @var{file} is a string-valued expression that -specifies the file name. @samp{< @var{file}} is called a @dfn{redirection} +specifies the @var{FN}. @samp{< @var{file}} is called a @dfn{redirection} because it directs input to come from a different place. For example, the following program reads its input record from the file @file{secondary.input} when it @@ -7567,7 +7582,9 @@ 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. @ifnottex +@ifnotdocbook @xref{Close Files And Pipes}. +@end ifnotdocbook @end ifnottex @c Exercise!! @c This example is unrealistic, since you could just use system @@ -7754,10 +7771,10 @@ system permits. @item An interesting side effect occurs if you use @code{getline} without a redirection inside a @code{BEGIN} rule. Because an unredirected @code{getline} -reads from the command-line data files, the first @code{getline} command +reads from the command-line @value{DF}s, the first @code{getline} command causes @command{awk} to set the value of @code{FILENAME}. Normally, @code{FILENAME} does not have a value inside @code{BEGIN} rules, because you -have not yet started to process the command-line data files. +have not yet started to process the command-line @value{DF}s. @value{DARKCORNER} (@xref{BEGIN/END}, also @pxref{Auto-set}.) @@ -7994,7 +8011,7 @@ For printing with specifications, you need the @code{printf} statement @cindex @code{printf} statement Besides basic and formatted printing, this @value{CHAPTER} also covers I/O redirections to files and pipes, introduces -the special file names that @command{gawk} processes internally, +the special @var{FN}s that @command{gawk} processes internally, and discusses the @code{close()} built-in function. @menu @@ -8802,9 +8819,9 @@ but they work identically for @code{printf}: @cindex operators, input/output @item print @var{items} > @var{output-file} This redirection prints the items into the output file named -@var{output-file}. The file name @var{output-file} can be any +@var{output-file}. The @var{FN} @var{output-file} can be any expression. Its value is changed to a string and then used as a -file name (@pxref{Expressions}). +@var{FN} (@pxref{Expressions}). When this type of redirection is used, the @var{output-file} is erased before the first output is written to it. Subsequent writes to the same @@ -8957,7 +8974,9 @@ As mentioned earlier many @end ifnotinfo @ifnottex +@ifnotdocbook Many +@end ifnotdocbook @end ifnottex older @command{awk} implementations limit the number of pipelines that an @command{awk} @@ -8970,7 +8989,7 @@ open as many pipelines as the underlying operating system permits. A particularly powerful way to use redirection is to build command lines and pipe them into the shell, @command{sh}. For example, suppose you -have a list of files brought over from a system where all the file names +have a list of files brought over from a system where all the @var{FN}s are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient: @@ -8992,12 +9011,12 @@ It then sends the list to the shell for execution. @c ENDOFRANGE reout @node Special Files -@section Special File Names in @command{gawk} +@section Special @value{FFN} in @command{gawk} @c STARTOFRANGE gfn @cindex @command{gawk}, file names in -@command{gawk} provides a number of special file names that it interprets -internally. These file names provide access to standard file descriptors +@command{gawk} provides a number of special @var{FN}s that it interprets +internally. These @var{FN}s provide access to standard file descriptors and TCP/IP networking. @menu @@ -9061,12 +9080,12 @@ that happens, writing to the screen is not correct. In fact, if terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk} provides special file names for accessing the three standard +@command{gawk} provides special @var{FN}s for accessing the three standard streams. @value{COMMONEXT} It also provides syntax for accessing -any other inherited open files. If the file name matches +any other inherited open files. If the @var{FN} matches one of these special names when @command{gawk} redirects input or output, -then it directly uses the stream that the file name stands for. -These special file names work for all operating systems that @command{gawk} +then it directly uses the stream that the @var{FN} stands for. +These special @var{FN}s work for all operating systems that @command{gawk} has been ported to, not just those that are POSIX-compliant: @cindex common extensions, @code{/dev/stdin} special file @@ -9096,7 +9115,7 @@ the shell). Unless special pains are taken in the shell from which @command{gawk} is invoked, only descriptors 0, 1, and 2 are available. @end table -The file names @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} +The @var{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2}, respectively. However, they are more self-explanatory. The proper way to write an error message in a @command{gawk} program @@ -9107,13 +9126,13 @@ print "Serious error detected!" > "/dev/stderr" @end example @cindex troubleshooting, quotes with file names -Note the use of quotes around the file name. +Note the use of quotes around the @var{FN}. Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. @c Exercise: What does it do? :-) -Finally, using the @code{close()} function on a file name of the +Finally, using the @code{close()} function on a @var{FN} of the form @code{"/dev/fd/@var{N}"}, for file descriptor numbers above two, does actually close the given file descriptor. @@ -9129,7 +9148,7 @@ versions of @command{awk}. @command{gawk} programs can open a two-way TCP/IP connection, acting as either a client or a server. -This is done using a special file name of the form: +This is done using a special @var{FN} of the form: @example @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}} @@ -9139,7 +9158,7 @@ The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}. The @var{protocol} is one of @samp{tcp} or @samp{udp}, and the other fields represent the other essential pieces of information for making a networking connection. -These file names are used with the @samp{|&} operator for communicating +These @var{FN}s are used with the @samp{|&} operator for communicating with a coprocess (@pxref{Two-way I/O}). This is an advanced feature, mentioned here only for completeness. @@ -9147,21 +9166,21 @@ Full discussion is delayed until @ref{TCP/IP Networking}. @node Special Caveats -@subsection Special File Name Caveats +@subsection Special @value{FFN} Caveats Here is a list of things to bear in mind when using the -special file names that @command{gawk} provides: +special @var{FN}s that @command{gawk} provides: @itemize @value{BULLET} @cindex compatibility mode (@command{gawk}), file names @cindex file names, in compatibility mode @item -Recognition of these special file names is disabled if @command{gawk} is in +Recognition of these special @var{FN}s is disabled if @command{gawk} is in compatibility mode (@pxref{Options}). @item @command{gawk} @emph{always} -interprets these special file names. +interprets these special @var{FN}s. For example, using @samp{/dev/fd/4} for output actually writes on file descriptor 4, and not on a new file descriptor that is @code{dup()}'ed from file descriptor 4. Most of @@ -9184,7 +9203,7 @@ Doing so results in unpredictable behavior. @cindex coprocesses, closing @cindex @code{getline} command, coprocesses@comma{} using from -If the same file name or the same shell command is used with @code{getline} +If the same @var{FN} or the same shell command is used with @code{getline} more than once during the execution of an @command{awk} program (@pxref{Getline}), the file is opened (or the command is executed) the first time only. @@ -9193,7 +9212,7 @@ The next time the same file or command is used with @code{getline}, another record is read from it, and so on. Similarly, when a file or pipe is opened for output, @command{awk} remembers -the file name or command associated with it, and subsequent +the @var{FN} 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. @@ -9235,7 +9254,7 @@ file or command, or the next @code{print} or @code{printf} to that file or command, reopens the file or reruns the command. Because the expression that you use to close a file or pipeline must exactly match the expression used to open the file or run the command, -it is good practice to use a variable to store the file name or command. +it is good practice to use a variable to store the @var{FN} or command. The previous example becomes the following: @example @@ -9285,7 +9304,7 @@ a separate message. @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 +your @value{DF}s. @command{gawk}'s ability to do this depends upon the facilities of your operating system, so it may not always work. It is therefore both good practice and good portability advice to always use @code{close()} on your files when you are done with them. @@ -9803,7 +9822,7 @@ as in the following: @noindent the variable is set at the very beginning, even before the @code{BEGIN} rules execute. The @option{-v} option and its assignment -must precede all the file name arguments, as well as the program text. +must precede all the @var{FN} arguments, as well as the program text. (@xref{Options}, for more information about the @option{-v} option.) Otherwise, the variable assignment is performed at a time determined by @@ -12970,11 +12989,11 @@ The @code{nextfile} statement is similar to the @code{next} statement. However, instead of abandoning processing of the current record, the @code{nextfile} statement instructs @command{awk} to stop processing the -current data file. +current @value{DF}. Upon execution of the @code{nextfile} statement, @code{FILENAME} is -updated to the name of the next data file listed on the command line, +updated to the name of the next @value{DF} listed on the command line, @code{FNR} is reset to one, and processing starts over with the first rule in the program. @@ -12983,10 +13002,10 @@ then the code in any @code{END} rules is executed. An exception to this is when @code{nextfile} is invoked during execution of any statement in an @code{END} rule; In this case, it causes the program to stop immediately. @xref{BEGIN/END}. -The @code{nextfile} statement is useful when there are many data files +The @code{nextfile} statement is useful when there are many @value{DF}s to process but it isn't necessary to process every record in every file. Without @code{nextfile}, -in order to move on to the next data file, a program +in order to move on to the next @value{DF}, a program would have to continue scanning the unwanted records. The @code{nextfile} statement accomplishes this much more efficiently. @@ -13430,15 +13449,15 @@ about how @command{awk} uses these variables. @cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable @item @code{ARGIND #} The index in @code{ARGV} of the current file being processed. -Every time @command{gawk} opens a new data file for processing, it sets -@code{ARGIND} to the index in @code{ARGV} of the file name. +Every time @command{gawk} opens a new @value{DF} for processing, it sets +@code{ARGIND} to the index in @code{ARGV} of the @var{FN}. When @command{gawk} is processing the input files, @samp{FILENAME == ARGV[ARGIND]} is always true. @cindex files, processing@comma{} @code{ARGIND} variable and This variable is useful in file processing; it allows you to tell how far -along you are in the list of data files as well as to distinguish between -successive instances of the same file name on the command line. +along you are in the list of @value{DF}s as well as to distinguish between +successive instances of the same @var{FN} on the command line. @cindex file names, distinguishing While you can change the value of @code{ARGIND} within your @command{awk} @@ -13486,14 +13505,14 @@ to clear it yourself before doing an I/O operation. @cindex @code{FILENAME} variable @cindex dark corner, @code{FILENAME} variable @item @code{FILENAME} -The name of the current input file. When no data files are listed +The name of the current input file. When no @value{DF}s are listed on the command line, @command{awk} reads from the standard input and @code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} rule, the value of @code{FILENAME} is @code{""}, since there are no input files being processed yet.@footnote{Some early implementations of Unix @command{awk} initialized @code{FILENAME} to @code{"-"}, even if there -were data files to be processed. This behavior was incorrect and should +were @value{DF}s to be processed. This behavior was incorrect and should not be relied upon in your programs.} @value{DARKCORNER} Note, though, that using @code{getline} (@pxref{Getline}) inside a @code{BEGIN} rule can give @code{FILENAME} a value. @@ -13864,11 +13883,11 @@ additional files to be read. If the value of @code{ARGC} is decreased, that eliminates input files from the end of the list. By recording the old value of @code{ARGC} elsewhere, a program can treat the eliminated arguments as -something other than file names. +something other than @var{FN}s. To eliminate a file from the middle of the list, store the null string (@code{""}) into @code{ARGV} in place of the file's name. As a -special feature, @command{awk} ignores file names that have been +special feature, @command{awk} ignores @var{FN}s that have been replaced with the null string. Another option is to use the @code{delete} statement to remove elements from @@ -16517,17 +16536,17 @@ _bigskip} The only case where the difference is noticeable is the last one: @samp{\\\\} is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. -Starting with version 3.1.4, @command{gawk} followed the POSIX rules +Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, it continued to follow the 1996 proposed rules, since that had been its behavior for many years. -When version 4.0.0 was released, the @command{gawk} maintainer +When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer made the POSIX rules the default, breaking well over a decade's worth of backwards compatibility.@footnote{This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules.} Needless to say, this was a bad idea, -and as of version 4.0.1, @command{gawk} resumed its historical +and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical behavior, and only follows the POSIX rules when @option{--posix} is given. The rules for @code{gensub()} are considerably simpler. At the runtime @@ -16674,7 +16693,7 @@ then @command{awk} flushes the buffers for @emph{all} open output files and pipes. @quotation NOTE -Prior to version 4.0.2, @command{gawk} +Prior to @value{PVERSION} 4.0.2, @command{gawk} would flush only the standard output if there was no argument, and flush all output files and pipes if the argument was the null string. This was changed in order to be compatible with Brian @@ -18616,7 +18635,7 @@ function rsort(first, last) @c endfile @end example -Here is an extended version of the data file: +Here is an extended version of the @value{DF}: @example @c file eg/data/class_data2 @@ -19122,7 +19141,7 @@ An @code{END} rule is automatically added to the program calling @code{assert()}. Normally, if a program consists of just a @code{BEGIN} rule, the input files and/or standard input are not read. However, now that the program has an @code{END} rule, @command{awk} -attempts to read the input data files or standard input +attempts to read the input @value{DF}s or standard input (@pxref{Using BEGIN/END}), most likely causing the program to hang as it waits for input. @@ -19609,7 +19628,7 @@ This tests the result to see if it is empty or not. An equivalent test would be @samp{contents == ""}. @node Data File Management -@section Data File Management +@section @value{DDF} Management @c STARTOFRANGE dataf @cindex files, managing @@ -19618,7 +19637,7 @@ test would be @samp{contents == ""}. @c STARTOFRANGE flibdataf @cindex functions, library, managing data files This @value{SECTION} presents functions that are useful for managing -command-line data files. +command-line @value{DF}s. @menu * Filetrans Function:: A function for handling data file transitions. @@ -19629,7 +19648,7 @@ command-line data files. @end menu @node Filetrans Function -@subsection Noting Data File Boundaries +@subsection Noting @value{DDF} Boundaries @cindex files, managing, data file boundaries @cindex files, initialization and cleanup @@ -19637,8 +19656,8 @@ The @code{BEGIN} and @code{END} rules are each executed exactly once at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the -@code{BEGIN} rule is executed at the beginning of each data file and the -@code{END} rule is executed at the end of each data file. +@code{BEGIN} rule is executed at the beginning of each @value{DF} and the +@code{END} rule is executed at the end of each @value{DF}. When informed that this was not the case, the user requested that we add new special @@ -19649,7 +19668,7 @@ Adding these special patterns to @command{gawk} wasn't necessary; the job can be done cleanly in @command{awk} itself, as illustrated by the following library program. It arranges to call two user-supplied functions, @code{beginfile()} and -@code{endfile()}, at the beginning and end of each data file. +@code{endfile()}, at the beginning and end of each @value{DF}. Besides solving the problem in only nine(!) lines of code, it does so @emph{portably}; this works with any implementation of @command{awk}: @@ -19680,17 +19699,17 @@ This file must be loaded before the user's ``main'' program, so that the rule it supplies is executed first. This rule relies on @command{awk}'s @code{FILENAME} variable that -automatically changes for each new data file. The current file name is +automatically changes for each new @value{DF}. The current @var{FN} is saved in a private variable, @code{_oldfilename}. If @code{FILENAME} does -not equal @code{_oldfilename}, then a new data file is being processed and +not equal @code{_oldfilename}, then a new @value{DF} is being processed and it is necessary to call @code{endfile()} for the old file. Because @code{endfile()} should only be called if a file has been processed, the program first checks to make sure that @code{_oldfilename} is not the null -string. The program then assigns the current file name to +string. The program then assigns the current @var{FN} to @code{_oldfilename} and calls @code{beginfile()} for the file. Because, like all @command{awk} variables, @code{_oldfilename} is initialized to the null string, this rule executes correctly even for the -first data file. +first @value{DF}. The program also supplies an @code{END} rule to do the final processing for the last file. Because this @code{END} rule comes before any @code{END} rules @@ -19699,7 +19718,7 @@ again the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function -If the same data file occurs twice in a row on the command line, then +If the same @value{DF} occurs twice in a row on the command line, then @code{endfile()} and @code{beginfile()} are not executed at the end of the first pass and at the beginning of the second pass. The following version solves the problem: @@ -19814,12 +19833,12 @@ The @code{rewind()} function also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). @node File Checking -@subsection Checking for Readable Data Files +@subsection Checking for Readable @value{DDF}s @cindex troubleshooting, readable data files @cindex readable data files@comma{} checking @cindex files, skipping -Normally, if you give @command{awk} a data file that isn't readable, +Normally, if you give @command{awk} a @value{DF} that isn't readable, it stops with a fatal error. There are times when you might want to just ignore such files and keep going.@footnote{The @code{BEGINFILE} special pattern (@pxref{BEGINFILE/ENDFILE}) provides an alternative @@ -19870,15 +19889,15 @@ This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an end of file indication, closes the file, and proceeds on to the next -command-line data file, @emph{without} executing any user-level +command-line @value{DF}, @emph{without} executing any user-level @command{awk} program code. Using @command{gawk}'s @code{ARGIND} variable (@pxref{Built-in Variables}), it is possible to detect when an empty -data file has been skipped. Similar to the library file presented +@value{DF} has been skipped. Similar to the library file presented in @ref{Filetrans Function}, the following library file calls a function named @code{zerofile()} that the user must provide. The arguments passed are -the file name and the position in @code{ARGV} where it was found: +the @var{FN} and the position in @code{ARGV} where it was found: @cindex @code{zerofile.awk} program @example @@ -19966,15 +19985,15 @@ END @{ @end ignore @node Ignoring Assigns -@subsection Treating Assignments as File Names +@subsection Treating Assignments as @value{FFN} @cindex assignments as filenames @cindex filenames, assignments as Occasionally, you might not want @command{awk} to process command-line variable assignments (@pxref{Assignment Options}). -In particular, if you have a file name that contains an @samp{=} character, -@command{awk} treats the file name as an assignment, and does not process it. +In particular, if you have a @var{FN} that contains an @samp{=} character, +@command{awk} treats the @var{FN} as an assignment, and does not process it. Some users have suggested an additional command-line option for @command{gawk} to disable command-line assignments. However, some simple programming with @@ -20018,7 +20037,7 @@ awk -v No_command_assign=1 -f noassign.awk -f yourprog.awk * The function works by looping through the arguments. It prepends @samp{./} to any argument that matches the form -of a variable assignment, turning that argument into a file name. +of a variable assignment, turning that argument into a @var{FN}. The use of @code{No_command_assign} allows you to disable command-line assignments at invocation time, by giving the variable a true value. @@ -20374,7 +20393,7 @@ etc., as its own options. After @code{getopt()} is through, it is the responsibility of the user level code to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the -command-line options as file names. +command-line options as @var{FN}s. @end quotation Several of the sample programs presented in @@ -21245,7 +21264,7 @@ awk -f @var{program} -- @var{options} @var{files} @noindent Here, @var{program} is the name of the @command{awk} program (such as @file{cut.awk}), @var{options} are any command-line options for the -program that start with a @samp{-}, and @var{files} are the actual data files. +program that start with a @samp{-}, and @var{files} are the actual @value{DF}s. If your system supports the @samp{#!} executable interpreter mechanism (@pxref{Executable Scripts}), @@ -21413,7 +21432,7 @@ BEGIN \ OFS = "" @} else if (c == "d") @{ if (length(Optarg) > 1) @{ - printf("Using first character of %s" \ + printf("cut: using first character of %s" \ " for delimiter\n", Optarg) > "/dev/stderr" Optarg = substr(Optarg, 1, 1) @} @@ -21444,7 +21463,7 @@ spaces. Also remember that after @code{getopt()} is through we have to clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options -as file names. +as @var{FN}s. After dealing with the command-line options, the program verifies that the options make sense. Only one or the other of @option{-c} and @option{-f} @@ -21494,7 +21513,7 @@ function set_fieldlist( n, m, i, j, k, f, g) m = split(f[i], g, "-") @group if (m != 2 || g[1] >= g[2]) @{ - printf("bad field list: %s\n", + printf("cut: bad field list: %s\n", f[i]) > "/dev/stderr" exit 1 @} @@ -21541,7 +21560,7 @@ function set_charlist( field, i, j, f, g, n, m, t, if (index(f[i], "-") != 0) @{ # range m = split(f[i], g, "-") if (m != 2 || g[1] >= g[2]) @{ - printf("bad character list: %s\n", + printf("cut: bad character list: %s\n", f[i]) > "/dev/stderr" exit 1 @} @@ -21641,8 +21660,8 @@ You invoke it as follows: The @var{pattern} is a regular expression. In typical usage, the regular expression is quoted to prevent the shell from expanding any of the -special characters as file name wildcards. Normally, @command{egrep} -prints the lines that matched. If multiple file names are provided on +special characters as @var{FN} wildcards. Normally, @command{egrep} +prints the lines that matched. If multiple @var{FN}s are provided on the command line, each output line is preceded by the name of the file and a colon. @@ -21733,7 +21752,7 @@ pattern is supplied with @option{-e}, the first nonoption on the command line is used. The @command{awk} command-line arguments up to @code{ARGV[Optind]} are cleared, so that @command{awk} won't try to process them as files. If no files are specified, the standard input is used, and if multiple files are -specified, we make sure to note this so that the file names can precede the +specified, we make sure to note this so that the @var{FN}s can precede the matched lines in the output: @example @@ -21836,9 +21855,9 @@ A number of additional tests are made, but they are only done if we are not counting lines. First, if the user only wants exit status (@code{no_print} is true), then it is enough to know that @emph{one} line in this file matched, and we can skip on to the next file with -@code{nextfile}. Similarly, if we are only printing file names, we can -print the file name, and then skip to the next file with @code{nextfile}. -Finally, each line is printed, with a leading file name and colon +@code{nextfile}. Similarly, if we are only printing @var{FN}s, we can +print the @var{FN}, and then skip to the next file with @code{nextfile}. +Finally, each line is printed, with a leading @var{FN} and colon if necessary: @cindex @code{!} (exclamation point), @code{!} operator @@ -22088,7 +22107,7 @@ number of lines in each file, supply a number on the command line preceded with a minus; e.g., @samp{-500} for files with 500 lines in them instead of 1000. To change the name of the output files to something like @file{myfileaa}, @file{myfileab}, and so on, supply an additional -argument that specifies the file name prefix. +argument that specifies the @var{FN} prefix. Here is a version of @command{split} in @command{awk}. It uses the @code{ord()} and @code{chr()} functions presented in @@ -22098,8 +22117,8 @@ The program first sets its defaults, and then tests to make sure there are not too many arguments. It then looks at each argument in turn. The first argument could be a minus sign followed by a number. If it is, this happens to look like a negative number, so it is made positive, and that is the -count of lines. The data file name is skipped over and the final argument -is used as the prefix for the output file names: +count of lines. The @value{DF} name is skipped over and the final argument +is used as the prefix for the output @value{FN}s: @cindex @code{split.awk} program @example @@ -22149,7 +22168,7 @@ BEGIN @{ The next rule does most of the work. @code{tcount} (temporary count) tracks how many lines have been printed to the output file so far. If it is greater than @code{count}, it is time to close the current file and start a new one. -@code{s1} and @code{s2} track the current suffixes for the file name. If +@code{s1} and @code{s2} track the current suffixes for the @value{FN}. If they are both @samp{z}, the file is just too big. Otherwise, @code{s1} moves to the next letter in the alphabet and @code{s2} starts over again at @samp{a}: @@ -22233,13 +22252,13 @@ The @code{BEGIN} rule first makes a copy of all the command-line arguments into an array named @code{copy}. @code{ARGV[0]} is not copied, since it is not needed. @code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to -process each file name in @code{ARGV} as input data. +process each @value{FN} in @code{ARGV} as input data. @cindex flag variables If the first argument is @option{-a}, then the flag variable @code{append} is set to true, and both @code{ARGV[1]} and @code{copy[1]} are deleted. If @code{ARGC} is less than two, then no -file names were supplied and @code{tee} prints a usage message and exits. +@value{FN}s were supplied and @code{tee} prints a usage message and exits. Finally, @command{awk} is forced to read the standard input by setting @code{ARGV[1]} to @code{"-"} and @code{ARGC} to two: @@ -22705,7 +22724,7 @@ BEGIN @{ @end example The @code{beginfile()} function is simple; it just resets the counts of lines, -words, and characters to zero, and saves the current file name in +words, and characters to zero, and saves the current @value{FN} in @code{fname}: @example @@ -22727,7 +22746,7 @@ you will see that @code{FNR} has already been reset by the time @code{endfile()} is called.} It then prints out those numbers for the file that was just read. It relies on @code{beginfile()} to reset the -numbers for the following data file: +numbers for the following @value{DF}: @c FIXME: ONE DAY: make the above footnote an exercise, @c instead of giving away the answer. @@ -23046,7 +23065,7 @@ is how long to wait before setting off the alarm: # how long to sleep for naptime = target - current if (naptime <= 0) @{ - print "time is in the past!" > "/dev/stderr" + print "alarm: time is in the past!" > "/dev/stderr" exit 1 @} @c endfile @@ -23519,7 +23538,7 @@ The @command{uniq} program (@pxref{Uniq Program}), removes duplicate lines from @emph{sorted} data. -Suppose, however, you need to remove duplicate lines from a data file but +Suppose, however, you need to remove duplicate lines from a @value{DF} but that you want to preserve the order the lines are in. A good example of this might be a shell history file. The history file keeps a copy of all the commands you have entered, and it is not unusual to repeat a command @@ -23715,7 +23734,7 @@ BEGIN @{ IGNORECASE = 1 @} /^@@c(omment)?[ \t]+system/ \ @{ if (NF < 3) @{ - e = (FILENAME ":" FNR) + e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") print e > "/dev/stderr" next @@ -23724,7 +23743,7 @@ BEGIN @{ IGNORECASE = 1 @} $2 = "" stat = system($0) if (stat != 0) @{ - e = (FILENAME ":" FNR) + e = ("extract: " FILENAME ":" FNR) e = (e ": warning: system returned " stat) print e > "/dev/stderr" @} @@ -23737,7 +23756,7 @@ The variable @code{e} is used so that the rule fits nicely on the @value{PAGE}. The second rule handles moving data into files. It verifies that a -file name is given in the directive. If the file named is not the +@value{FN} is given in the directive. If the file named is not the current file, then the current file is closed. Keeping the current file open until a new file is encountered allows the use of the @samp{>} redirection for printing the contents, keeping open file management @@ -23777,7 +23796,7 @@ line. That line is then printed to the output file: /^@@c(omment)?[ \t]+file/ \ @{ if (NF != 3) @{ - e = (FILENAME ":" FNR ": badly formed `file' line") + e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" next @} @@ -23822,7 +23841,7 @@ subsequent output is appended to the file (@pxref{Redirection}). This makes it easy to mix program text and explanatory prose for the same sample source file (as has been done here!) without any hassle. The file is -only closed when a new data file name is encountered or at the end of the +only closed when a new @value{DF} name is encountered or at the end of the input file. Finally, the function @code{@w{unexpected_eof()}} prints an appropriate @@ -23834,7 +23853,7 @@ The @code{END} rule handles the final cleanup, closing the open file: @group function unexpected_eof() @{ - printf("%s:%d: unexpected EOF or error\n", + printf("extract: %s:%d: unexpected EOF or error\n", FILENAME, FNR) > "/dev/stderr" exit 1 @} @@ -23874,7 +23893,7 @@ Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp The following program, @file{awksed.awk}, accepts at least two command-line arguments: the pattern to look for and the text to replace it with. Any -additional arguments are treated as data file names to process. If none +additional arguments are treated as @value{DF} names to process. If none are provided, the standard input is used: @cindex Brennan, Michael @@ -23948,7 +23967,7 @@ The @code{BEGIN} rule handles the setup, checking for the right number of arguments and calling @code{usage()} if there is a problem. Then it sets @code{RS} and @code{ORS} from the command-line arguments and sets @code{ARGV[1]} and @code{ARGV[2]} to the null string, so that they are -not treated as file names +not treated as @value{FN}s (@pxref{ARGC and ARGV}). The @code{usage()} function prints an error message and exits. @@ -24047,7 +24066,7 @@ Literal text, provided with @option{--source} or @option{--source=}. This text is just appended directly. @item -Source file names, provided with @option{-f}. We use a neat trick and append +Source @value{FN}s, provided with @option{-f}. We use a neat trick and append @samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion program works the way @command{gawk} does, this gets the text of the file included into the program at the correct point. @@ -24060,7 +24079,7 @@ shell variable. @item Run the expanded program with @command{gawk} and any other original command-line -arguments that the user supplied (such as the data file names). +arguments that the user supplied (such as the @value{DF} names). @end enumerate This program uses shell variables extensively: for storing command-line arguments, @@ -24092,7 +24111,7 @@ programming trick. Don't worry about it if you are not familiar with These are saved and passed on to @command{gawk}. @item @option{-f}, @option{--file}, @option{--file=}, @option{-Wfile=} -The file name is appended to the shell variable @code{program} with an +The @value{FN} is appended to the shell variable @code{program} with an @code{@@include} statement. The @command{expr} utility is used to remove the leading option part of the argument (e.g., @samp{--file=}). @@ -24217,10 +24236,10 @@ is stored in the shell variable @code{expand_prog}. Doing this keeps the shell script readable. The @command{awk} program reads through the user's program, one line at a time, using @code{getline} (@pxref{Getline}). The input -file names and @code{@@include} statements are managed using a stack. -As each @code{@@include} is encountered, the current file name is +@value{FN}s and @code{@@include} statements are managed using a stack. +As each @code{@@include} is encountered, the current @value{FN} is ``pushed'' onto the stack and the file named in the @code{@@include} -directive becomes the current file name. As each file is finished, +directive becomes the current @value{FN}. As each file is finished, the stack is ``popped,'' and the previous input file becomes the current input file again. The process is started by making the original file the first one on the stack. @@ -24229,16 +24248,16 @@ The @code{pathto()} function does the work of finding the full path to a file. It simulates @command{gawk}'s behavior when searching the @env{AWKPATH} environment variable (@pxref{AWKPATH Variable}). -If a file name has a @samp{/} in it, no path search is done. -Similarly, if the file name is @code{"-"}, then that string is +If a @value{FN} has a @samp{/} in it, no path search is done. +Similarly, if the @value{FN} is @code{"-"}, then that string is used as-is. Otherwise, -the file name is concatenated with the name of each directory in -the path, and an attempt is made to open the generated file name. +the @value{FN} is concatenated with the name of each directory in +the path, and an attempt is made to open the generated @value{FN}. The only way to test if a file can be read in @command{awk} is to go ahead and try to read it with @code{getline}; this is what @code{pathto()} does.@footnote{On some very old versions of @command{awk}, the test @samp{getline junk < t} can loop forever if the file exists but is empty. -Caveat emptor.} If the file can be read, it is closed and the file name +Caveat emptor.} If the file can be read, it is closed and the @value{FN} is returned: @ignore @@ -24296,14 +24315,14 @@ BEGIN @{ The stack is initialized with @code{ARGV[1]}, which will be @code{"/dev/stdin"}. The main loop comes next. Input lines are read in succession. Lines that do not start with @code{@@include} are printed verbatim. -If the line does start with @code{@@include}, the file name is in @code{$2}. +If the line does start with @code{@@include}, the @value{FN} is in @code{$2}. @code{pathto()} is called to generate the full path. If it cannot, then the program prints an error message and continues. The next thing to check is if the file is included already. The -@code{processed} array is indexed by the full file name of each included +@code{processed} array is indexed by the full @value{FN} of each included file and it tracks this information for us. If the file is -seen again, a warning message is printed. Otherwise, the new file name is +seen again, a warning message is printed. Otherwise, the new @value{FN} is pushed onto the stack and processing continues. Finally, when @code{getline} encounters the end of the input file, the file @@ -24324,7 +24343,7 @@ the program is done: fpath = pathto($2) @group if (fpath == "") @{ - printf("igawk:%s:%d: cannot find %s\n", + printf("igawk: %s:%d: cannot find %s\n", input[stackptr], FNR, $2) > "/dev/stderr" continue @} @@ -24381,10 +24400,10 @@ options and command-line arguments that the user supplied. @c this causes more problems than it solves, so leave it out. @ignore -The special file @file{/dev/null} is passed as a data file to @command{gawk} +The special file @file{/dev/null} is passed as a @value{DF} to @command{gawk} to handle an interesting case. Suppose that the user's program only has -a @code{BEGIN} rule and there are no data files to read. -The program should exit without reading any data files. +a @code{BEGIN} rule and there are no @value{DF}s to read. +The program should exit without reading any @value{DF}s. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the @@ -25483,10 +25502,10 @@ another process on another system across an IP network connection. You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is -by recognizing special file names that begin with one of @samp{/inet/}, +by recognizing special @value{FN}s that begin with one of @samp{/inet/}, @samp{/inet4/} or @samp{/inet6}. -The full syntax of the special file name is +The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. The components are: @@ -26667,10 +26686,11 @@ complete detail in @inforef{Top, , GNU @command{gettext} utilities, gettext, GNU gettext tools}.) @end ifinfo @ifnotinfo -@cite{GNU gettext tools}.) +@uref{http://www.gnu.org/software/gettext/manual/, +@cite{GNU gettext tools}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.18.2.1.tar.gz, version 0.18.2.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.tar.gz, @value{PVERSION} 0.19}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -27576,7 +27596,7 @@ functions which called the one you are in. The commands for doing this are: Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each -function, the source file name, and the line number. +function, the source @value{FN}, and the line number. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -27642,7 +27662,7 @@ Description of the selected stack frame. @item functions @cindex list function definitions, in debugger -List all function definitions including source file names and +List all function definitions including source @value{FN}s and line numbers. @item locals @@ -27730,7 +27750,7 @@ Turn instruction tracing on or off. The default is @code{off}. @end table @item @code{save} @var{filename} -Save the commands from the current session to the given file name, +Save the commands from the current session to the given @value{FN}, so that they can be replayed using the @command{source} command. @item @code{source} @var{filename} @@ -27904,8 +27924,8 @@ of completion are available: @item Command completion Command names. -@item Source file name completion -Source file names. Relevant commands are +@item Source @value{FN} completion +Source @value{FN}s. Relevant commands are @code{break}, @code{clear}, @code{list}, @@ -29163,7 +29183,7 @@ the problem at hand is often the correct approach in such situations. If one of the options @option{--bignum} or @option{-M} is specified, @command{gawk} performs all integer arithmetic using GMP arbitrary precision integers. -Any number that looks like an integer in a program source or data file +Any number that looks like an integer in a program source or @value{DF} is stored as an arbitrary precision integer. The size of the integer is limited only by your computer's memory. The current floating-point context has no effect on operations involving integers. @@ -30585,7 +30605,7 @@ The fields are as follows: The name of the two-way processor. @item awk_bool_t (*can_take_two_way)(const char *name); -This function returns true if it wants to take over two-way I/O for this filename. +This function returns true if it wants to take over two-way I/O for this @value{FN}. It should not change any state (variable values, etc.) within @command{gawk}. @@ -32461,7 +32481,7 @@ array with information retrieved from the filesystem, as follows: @multitable @columnfractions .15 .50 .20 @headitem Subscript @tab Field in @code{struct stat} @tab File type -@item @code{"name"} @tab The file name @tab All +@item @code{"name"} @tab The @value{FN} @tab All @item @code{"dev"} @tab @code{st_dev} @tab All @item @code{"ino"} @tab @code{st_ino} @tab All @item @code{"mode"} @tab @code{st_mode} @tab All @@ -32512,7 +32532,7 @@ The arguments are as follows: @table @code @item pathlist -An array of filenames. The element values are used; the index values are ignored. +An array of @value{FN}s. The element values are used; the index values are ignored. @item flags This should be the bitwise OR of one or more of the following @@ -32636,10 +32656,10 @@ The arguments to @code{fnmatch()} are: @table @code @item pattern -The filename wildcard to match. +The @var{FN} wildcard to match. @item string -The filename string. +The @var{FN} string. @item flag Either zero, or the bitwise OR of one or more of the @@ -32746,8 +32766,8 @@ standard output to a temporary file configured to have the same owner and permissions as the original. After the file has been processed, the extension restores standard output to its original destination. If @code{INPLACE_SUFFIX} is not an empty string, the original file is -linked to a backup filename created by appending that suffix. Finally, -the temporary file is renamed to the original filename. +linked to a backup @var{FN} created by appending that suffix. Finally, +the temporary file is renamed to the original @var{FN}. If any error occurs, the extension issues a fatal error to terminate processing immediately without damaging the original file. @@ -32813,7 +32833,7 @@ on the command line (or with @code{getline}), they are read, with each entry returned as a record. The record consists of three fields. The first two are the inode number and the -filename, separated by a forward slash character. +@var{FN}, separated by a forward slash character. On systems where the directory entry contains the file type, the record has a third field (also separated by a slash) which is a single letter indicating the type of the file. The letters are file types are shown @@ -33496,7 +33516,7 @@ Special files in I/O redirections: @itemize @value{MINUS} @item The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and -@file{/dev/fd/@var{N}} special file names +@file{/dev/fd/@var{N}} special @value{FN}s (@pxref{Special Files}). @item @@ -33720,7 +33740,7 @@ long options @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} version 4.0: +and the documentation for @command{gawk} @value{PVERSION} 4.0: @c nested table @itemize @value{MINUS} @@ -33813,7 +33833,7 @@ The @code{IGNORECASE} variable and its effects @item The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and -@file{/dev/fd/@var{N}} special file names +@file{/dev/fd/@var{N}} special @value{FN}s (@pxref{Special Files}). @end itemize @@ -33850,7 +33870,7 @@ Version 2.14 of @command{gawk} introduced the following feature: @itemize @value{BULLET} @item -The @code{next file} statement for skipping to the next data file +The @code{next file} statement for skipping to the next @value{DF} (@pxref{Nextfile Statement}). @end itemize @@ -33872,7 +33892,7 @@ through @code{ARGV}. @item The @file{/dev/pid}, @file{/dev/ppid}, @file{/dev/pgrpid}, and -@file{/dev/user} special file names. These have since been removed. +@file{/dev/user} special @value{FN}s. These have since been removed. @item The ability to delete all of an array at once with @samp{delete @var{array}} @@ -34494,7 +34514,7 @@ like ``why does @samp{[A-Z]} match lowercase letters?!?'' This situation existed for close to 10 years, if not more, and the @command{gawk} maintainer grew weary of trying to explain that @command{gawk} was being nicely standards-compliant, and that the issue -was in the user's locale. During the development of version 4.0, +was in the user's locale. During the development of @value{PVERSION} 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And thus was born the Campaign for Rational Range Interpretation (or @@ -34875,7 +34895,7 @@ Extracting the archive creates a directory named @file{gawk-@value{VERSION}.@value{PATCHLEVEL}} in the current directory. -The distribution file name is of the form +The distribution @value{FN} is of the form @file{gawk-@var{V}.@var{R}.@var{P}.tar.gz}. The @var{V} represents the major version of @command{gawk}, the @var{R} represents the current release of version @var{V}, and @@ -35544,7 +35564,7 @@ the @command{configure} script as is the case for the Unix versions. If @file{c:/usr} is the prefix directory then the default search path contains @file{.} and @file{c:/usr/share/awk}. Additionally, to support binary distributions of @command{gawk} for OS/2 -systems whose drive @samp{c:} might not support long file names or might not exist +systems whose drive @samp{c:} might not support long @value{FN}s or might not exist at all, there is a special environment variable. If @env{UNIXROOT} specifies a drive then this specific drive is also searched for program files. E.g., if @env{UNIXROOT} is set to @file{e:} the complete default search path is @@ -35739,7 +35759,7 @@ $ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms gawk} @end example @command{MMK} is an open source, free, near-clone of @command{MMS} and -can better handle ODS-5 volumes with upper- and lowercase filenames. +can better handle ODS-5 volumes with upper- and lowercase @var{FN}s. @command{MMK} is available from @uref{https://github.com/endlesssoftware/mmk}. With ODS-5 volumes and extended parsing enabled, the case of the target @@ -35870,11 +35890,11 @@ provides information about both the @command{gawk} implementation and the The logical name @samp{AWK_LIBRARY} can designate a default location for @command{awk} program files. For the @option{-f} option, if the specified -file name has no device or directory path information in it, @command{gawk} +@value{FN} has no device or directory path information in it, @command{gawk} looks in the current directory first, then in the directory specified by the translation of @samp{AWK_LIBRARY} if the file is not found. If, after searching in both directories, the file still is not found, -@command{gawk} appends the suffix @samp{.awk} to the filename and retries +@command{gawk} appends the suffix @samp{.awk} to the @var{FN} and retries the file search. If @samp{AWK_LIBRARY} has no definition, a default value of @samp{SYS$LIBRARY:} is used for it. @@ -35903,7 +35923,7 @@ One side effect of dual command-line parsing is that if there is only a single parameter (as in the quoted string program above), the command becomes ambiguous. To work around this, the normally optional @option{--} flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any -other dash-type options (or multiple parameters such as data files to +other dash-type options (or multiple parameters such as @value{DF}s to process) are present, there is no ambiguity and @option{--} can be omitted. @cindex exit status, of VMS @@ -36012,7 +36032,7 @@ define a symbol, as follows: $ @kbd{gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe} @end example -This is apparently version 2.15.6, which is extremely old. We +This is apparently @value{PVERSION} 2.15.6, which is extremely old. We recommend compiling and using the current version. @c ENDOFRANGE opgawx @@ -36041,8 +36061,8 @@ what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it -to the smallest possible @command{awk} program and input data file that -reproduces the problem. Then send us the program and data file, +to the smallest possible @command{awk} program and input @value{DF} that +reproduces the problem. Then send us the program and @value{DF}, some idea of what kind of Unix system you're using, the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps @@ -37257,7 +37277,7 @@ to any of the above. @ref{Dynamic Extensions}, describes the supported API and mechanisms for writing extensions for @command{gawk}. This API was introduced -in version 4.1. However, for many years @command{gawk} +in @value{PVERSION} 4.1. However, for many years @command{gawk} provided an extension mechanism that required knowledge of @command{gawk} internals and that was not as well designed. @@ -38249,7 +38269,7 @@ numeric values. It is the C type @code{float}. The character generated by hitting the space bar on the keyboard. @item Special File -A file name interpreted internally by @command{gawk}, instead of being handed +A @value{FN} interpreted internally by @command{gawk}, instead of being handed directly to the underlying operating system---for example, @file{/dev/stderr}. (@xref{Special Files}.) @@ -39665,9 +39685,6 @@ ORA uses filename, thus the macro. Suggestions: ------------ -% Next edition: -% 1. Standardize the error messages from the functions and programs -% in the two sample code chapters. Better sidebars can almost sort of be done with: |