diff options
| author | Arnold D. Robbins <arnold@skeeve.com> | 2010-12-05 20:37:25 +0200 |
|---|---|---|
| committer | Arnold D. Robbins <arnold@skeeve.com> | 2010-12-05 20:37:25 +0200 |
| commit | 6b9ed56f74baa4af529e100dff19afcd23ed7cd8 (patch) | |
| tree | 9e66902f2792d6e2216a8020805a14b6cccbc028 | |
| parent | 16458663c3bdf640e3352653ea94a89fb2949ad4 (diff) | |
| download | egawk-6b9ed56f74baa4af529e100dff19afcd23ed7cd8.tar.gz egawk-6b9ed56f74baa4af529e100dff19afcd23ed7cd8.tar.bz2 egawk-6b9ed56f74baa4af529e100dff19afcd23ed7cd8.zip | |
More doc and code fixes. See ChangeLogs.
| -rw-r--r-- | ChangeLog | 8 | ||||
| -rw-r--r-- | awk.h | 1 | ||||
| -rw-r--r-- | builtin.c | 26 | ||||
| -rw-r--r-- | debug.c | 30 | ||||
| -rw-r--r-- | doc/gawk.info | 1396 | ||||
| -rw-r--r-- | doc/gawk.texi | 364 | ||||
| -rw-r--r-- | eval.c | 32 | ||||
| -rw-r--r-- | main.c | 4 | ||||
| -rw-r--r-- | node.c | 2 | ||||
| -rw-r--r-- | profile.c | 6 |
10 files changed, 1018 insertions, 851 deletions
@@ -1,3 +1,11 @@ +Sun Dec 5 15:01:35 2010 Arnold D. Robbins <arnold@skeeve.com> + + * eval.c (grow_stack): Change env var to GAWK_STACKSIZE. + * awk.h, main.c, eval.c, profile.c: Removed features added + for those who are Strong In The Ways of the Source. + * debug.c (comp_func): Moved to here from eval.c, where it's + no longer needed. + Sat Dec 4 21:44:38 2010 Arnold D. Robbins <arnold@skeeve.com> * node.c (init_btowc_cache): New function. @@ -876,7 +876,6 @@ extern int do_tidy_mem; extern int do_sandbox; extern int do_optimize; extern int use_lc_numeric; -extern int whiny_users; extern int exit_val; #ifdef NO_LINT @@ -240,17 +240,27 @@ strncasecmpmbs(const char *s1, const char *s2, size_t n) memset(& mbs2, 0, sizeof(mbs2)); for (i1 = i2 = 0 ; i1 < n && i2 < n ;i1 += mbclen1, i2 += mbclen2) { - mbclen1 = mbrtowc(& wc1, s1 + i1, n - i1, & mbs1); - if (mbclen1 == (size_t) -1 || mbclen1 == (size_t) -2 || mbclen1 == 0) { - /* We treat it as a singlebyte character. */ + if (is_valid_character(s1[i1])) { mbclen1 = 1; - wc1 = s1[i1]; + wc1 = btowc_cache[s1[i1]]; + } else { + mbclen1 = mbrtowc(& wc1, s1 + i1, n - i1, & mbs1); + if (mbclen1 == (size_t) -1 || mbclen1 == (size_t) -2 || mbclen1 == 0) { + /* We treat it as a singlebyte character. */ + mbclen1 = 1; + wc1 = btowc_cache[s1[i1]]; + } } - mbclen2 = mbrtowc(& wc2, s2 + i2, n - i2, & mbs2); - if (mbclen2 == (size_t) -1 || mbclen2 == (size_t) -2 || mbclen2 == 0) { - /* We treat it as a singlebyte character. */ + if (is_valid_character(s2[i2])) { mbclen2 = 1; - wc2 = s2[i2]; + wc2 = btowc_cache[s2[i2]]; + } else { + mbclen2 = mbrtowc(& wc2, s2 + i2, n - i2, & mbs2); + if (mbclen2 == (size_t) -1 || mbclen2 == (size_t) -2 || mbclen2 == 0) { + /* We treat it as a singlebyte character. */ + mbclen2 = 1; + wc2 = btowc_cache[s2[i2]]; + } } if ((gap = towlower(wc1) - towlower(wc2)) != 0) /* s1 and s2 are not equivalent. */ @@ -1052,7 +1052,35 @@ print_field(long field_num) } } -extern int comp_func(const void *p1, const void *p2); +/* comp_func --- array index comparison function for qsort */ + +static int +comp_func(const void *p1, const void *p2) +{ + size_t len1, len2; + const char *str1, *str2; + const NODE *t1, *t2; + int cmp1; + + t1 = *((const NODE *const *) p1); + t2 = *((const NODE *const *) p2); + +/* + t1 = force_string(t1); + t2 = force_string(t2); +*/ + len1 = t1->ahname_len; + str1 = t1->ahname_str; + + len2 = t2->ahname_len; + str2 = t2->ahname_str; + + /* Array indexes are strings, compare as such, always! */ + cmp1 = memcmp(str1, str2, len1 < len2 ? len1 : len2); + /* if prefixes are equal, size matters */ + return (cmp1 != 0 ? cmp1 : + len1 < len2 ? -1 : (len1 > len2)); +} /* print_array --- print the contents of an array */ diff --git a/doc/gawk.info b/doc/gawk.info index 3c7816c7..e54b6b4b 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -347,13 +347,16 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Command Line:: How to run `awk'. * Options:: Command-line options and their meanings. * Other Arguments:: Input file names and variable assignments. +* Naming Standard Input:: How to specify standard input with + other files. +* Environment Variables:: The environment variables `gawk' uses. * AWKPATH Variable:: Searching directories for `awk' programs. +* Other Environment Variables:: The environment variables. * Exit Status:: `gawk''s exit status. * Include Files:: Including other files into your program. * Obsolete:: Obsolete Options and/or features. * Undocumented:: Undocumented Options and Features. -* Known Bugs:: Known Bugs in `gawk'. * Library Names:: How to best name private global variables in library functions. * General Functions:: Functions that are of general use. @@ -8254,10 +8257,11 @@ that does this. If an argument is supplied to `exit', its value is used as the exit status code for the `awk' process. If no argument is supplied, `exit' -returns status zero (success). In the case where an argument is -supplied to a first `exit' statement, and then `exit' is called a -second time from an `END' rule with no argument, `awk' uses the -previously supplied exit value. (d.c.) +causes `awk' to return a "success" status. In the case where an +argument is supplied to a first `exit' statement, and then `exit' is +called a second time from an `END' rule with no argument, `awk' uses +the previously supplied exit value. (d.c.) *Note Exit Status::, for +more information. For example, suppose an error condition occurs that is difficult or impossible to handle. Conventionally, programs report this by exiting @@ -13022,25 +13026,23 @@ This major node covers how to run awk, both POSIX-standard and `gawk'-specific command-line options, and what `awk' and `gawk' do with non-option arguments. It then proceeds to cover how `gawk' searches for source files, obsolete options and/or features, and known bugs in -`gawk'. This major node rounds out the discussion of `awk' as a -program and as a language. +`gawk'. - While a number of the options and features described here were -discussed in passing earlier in the book, this major node provides the -full details. + Many of the options and features described here are discussed in +more detail later in the Info file; feel free to skip over things in +this major node that don't interest you right now. * Menu: * Command Line:: How to run `awk'. * Options:: Command-line options and their meanings. * Other Arguments:: Input file names and variable assignments. -* AWKPATH Variable:: Searching directories for `awk' - programs. +* Naming Standard Input:: How to specify standard input with other files. +* Environment Variables:: The environment variables `gawk' uses. * Exit Status:: `gawk''s exit status. * Include Files:: Including other files into your program. * Obsolete:: Obsolete Options and/or features. * Undocumented:: Undocumented Options and Features. -* Known Bugs:: Known Bugs in `gawk'. File: gawk.info, Node: Command Line, Next: Options, Up: Invoking Gawk @@ -13083,20 +13085,22 @@ once, it is the last value that counts. Each long option for `gawk' has a corresponding POSIX-style option. The long and short options are interchangeable in all contexts. The -options and their meanings are as follows: +following list describes options mandated by the POSIX standard: `-F FS' `--field-separator FS' - Sets the `FS' variable to FS (*note Field Separators::). + Set the `FS' variable to FS (*note Field Separators::). `-f SOURCE-FILE' `--file SOURCE-FILE' - Indicates that the `awk' program is to be found in SOURCE-FILE - instead of in the first non-option argument. + Read `awk' program source from SOURCE-FILE instead of in the first + non-option argument. This option may be given multiple times; the + `awk' program consists of the concatenation the contents of each + specified SOURCE-FILE. `-v VAR=VAL' `--assign VAR=VAL' - Sets the variable VAR to the value VAL _before_ execution of the + Set the variable VAR to the value VAL _before_ execution of the program begins. Such variable values are available inside the `BEGIN' rule (*note Other Arguments::). @@ -13110,42 +13114,43 @@ options and their meanings are as follows: value you may have given. `-W GAWK-OPT' - Following the POSIX standard, implementation-specific options are - supplied as arguments to the `-W' option. These options also have - corresponding GNU-style long options. Note that the long options - may be abbreviated, as long as the abbreviations remain unique. - The full list of `gawk'-specific options is provided next. + Provide an implementation-specific option. This is the POSIX + convention for providing implementation-specific options. These + options also have corresponding GNU-style long options. Note that + the long options may be abbreviated, as long as the abbreviations + remain unique. The full list of `gawk'-specific options is + provided next. `--' - Signals the end of the command-line options. The following + Signal the end of the command-line options. The following arguments are not treated as options even if they begin with `-'. 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 `-'. + the user that could start with `-'. It is also useful for passing + options on to the `awk' program; see *note Getopt Function::. - The previous list described options mandated by the POSIX standard. -The following list describes `gawk'-specific options: + The following list describes `gawk'-specific options: `-b' `--characters-as-bytes' - Causes `gawk' to treat all input data as single-byte characters. + Cause `gawk' to treat all input data as single-byte characters. Normally, `gawk' follows the POSIX standard and attempts to process its input data according to the current locale. This can often - involve converting multi-byte characters into wide characters + involve converting multibyte characters into wide characters (internally), and can lead to problems or confusion if the input - data does not contain valid multi-byte characters. This option is + data does not contain valid multibyte characters. This option is an easy way to tell `gawk': "hands off my data!". `-c' `--traditional' - Specifies "compatibility mode", in which the GNU extensions to the + Specify "compatibility mode", in which the GNU extensions to the `awk' language are disabled, so that `gawk' behaves just like the - Bell Laboratories research version of Unix `awk'. `--traditional' - is the preferred form of this option. *Note POSIX/GNU::, which - summarizes the extensions. Also see *note Compatibility Mode::. + Bell Laboratories research version of Unix `awk'. *Note + POSIX/GNU::, which summarizes the extensions. Also see *note + Compatibility Mode::. `-C' `--copyright' @@ -13154,9 +13159,9 @@ The following list describes `gawk'-specific options: `-d [FILE]' `--dump-variables[=FILE]' - Prints a sorted list of global variables, their types, and final - values to FILE. If no FILE is provided, `gawk' prints this list - to the file named `awkvars.out' in the current directory. + Print a sorted list of global variables, their types, and final + values to FILE. If no FILE is provided, print this list to the + file named `awkvars.out' in the current directory. Having a list of all global variables is a good way to look for typographical errors in your programs. You would also use this @@ -13168,19 +13173,22 @@ The following list describes `gawk'-specific options: `-e PROGRAM-TEXT' `--source PROGRAM-TEXT' - Allows you to mix source code in files with source code that you - enter on the command line. Program source code is taken from the - PROGRAM-TEXT. This is particularly useful when you have library - functions that you want to use from your command-line programs - (*note AWKPATH Variable::). + Provide program source code in the PROGRAM-TEXT. This option + allows you to mix source code in files with source code that you + enter on the command line. This is particularly useful when you + have library functions that you want to use from your command-line + programs (*note AWKPATH Variable::). `-E FILE' `--exec FILE' - Similar to `-f', reads `awk' program text from FILE. There are - two differences. The first is that this option also terminates - option processing; anything else on the command line is passed on - directly to the `awk' program. The second is that command line - variable assignments of the form `VAR=VALUE' are disallowed. + Similar to `-f', read `awk' program text from FILE. There are two + differences from `-f': + + * This option terminates option processing; anything else on + the command line is passed on directly to the `awk' program. + + * Command-line variable assignments of the form `VAR=VALUE' are + disallowed. This option is particularly necessary for World Wide Web CGI applications that pass arguments through the URL; using this @@ -13195,19 +13203,19 @@ The following list describes `gawk'-specific options: `-g' `--gen-pot' - Analyzes the source program and generates a GNU `gettext' Portable - Object file on standard output for all string constants that have - been marked for translation. *Note Internationalization::, for - information about this option. + Analyze the source program and generate a GNU `gettext' Portable + Object Template file on standard output for all string constants + that have been marked for translation. *Note + Internationalization::, for information about this option. `-h' `--help' - Prints a "usage" message summarizing the short and long style + Print a "usage" message summarizing the short and long style options that `gawk' accepts and then exit. `-L [value]' `--lint[=value]' - Warns about constructs that are dubious or nonportable to other + Warn about constructs that are dubious or nonportable to other `awk' implementations. Some warnings are issued when `gawk' first reads your program. Others are issued at runtime, as your program executes. With an optional argument of `fatal', lint warnings @@ -13234,12 +13242,12 @@ The following list describes `gawk'-specific options: `-N' `--use-lc-numeric' - This option forces the use of the locale's decimal point character - when parsing numeric input data (*note Locales::). + Force the use of the locale's decimal point character when parsing + numeric input data (*note Locales::). `-O' `--optimize' - Enables some optimizations on the internal representation of the + Enable some optimizations on the internal representation of the program. At the moment this includes just simple constant folding. The `gawk' maintainer hopes to add more optimizations over time. @@ -13258,9 +13266,9 @@ The following list describes `gawk'-specific options: `-P' `--posix' - Operates in strict POSIX mode. This disables all `gawk' - extensions (just like `--traditional') and adds the following - additional restrictions: + Operate in strict POSIX mode. This disables all `gawk' extensions + (just like `--traditional') and adds the following additional + restrictions: * `\x' escape sequences are not recognized (*note Escape Sequences::). @@ -13294,28 +13302,28 @@ The following list describes `gawk'-specific options: `-r' `--re-interval' - Allows interval expressions (*note Regexp Operators::) in regexps. - This is now the default behavior for `gawk'. Nevertheless, this - option remains for both backward compatibility, and for use in + Allow interval expressions (*note Regexp Operators::) in regexps. + This is now `gawk''s default behavior. Nevertheless, this option + remains both for backward compatibility, and for use in combination with the `--traditional' option. `-S' `--sandbox' - In sandbox mode, the `system()' function, input redirections with - `getline', output redirections with `print' and `printf' and - dynamic extensions are disabled. This is particularly useful when - you want to run `awk' scripts from questionable sources and need - to make sure the scripts can't access your system (other then the - specified input data file). + Disable the `system()' function, input redirections with `getline', + output redirections with `print' and `printf', and dynamic + extensions. This is particularly useful when you want to run + `awk' scripts from questionable sources and need to make sure the + scripts can't access your system (other than the specified input + data file). `-t' `--lint-old' - Warns about constructs that are not available in the original + Warn about constructs that are not available in the original version of `awk' from Version 7 Unix (*note V7/SVR3.1::). `-V' `--version' - Prints version information for this particular copy of `gawk'. + Print version information for this particular copy of `gawk'. This allows you to determine if your copy of `gawk' is up to date with respect to whatever the Free Software Foundation is currently distributing. It is also useful for bug reports (*note Bugs::). @@ -13336,12 +13344,12 @@ be written once and then retrieved from a standard place, instead of having to be included into each individual program. (As mentioned in *note Definition Syntax::, function names must be unique.) - Library functions can still be used, even if the program is entered -at the terminal, by specifying `-f /dev/tty'. After typing your -program, type `Ctrl-d' (the end-of-file character) to terminate it. -(You may also use `-f -' to read program source from the standard input -but then you will not be able to also use the standard input as a -source of data.) + With standard `awk', library functions can still be used, even if +the program is entered at the terminal, by specifying `-f /dev/tty'. +After typing your program, type `Ctrl-d' (the end-of-file character) to +terminate it. (You may also use `-f -' to read program source from the +standard input but then you will not be able to also use the standard +input as a source of data.) Because it is clumsy using the standard `awk' mechanisms to mix source file and command-line `awk' programs, `gawk' provides the @@ -13380,7 +13388,7 @@ environments. (1) Not recommended. -File: gawk.info, Node: Other Arguments, Next: AWKPATH Variable, Prev: Options, Up: Invoking Gawk +File: gawk.info, Node: Other Arguments, Next: Naming Standard Input, Prev: Options, Up: Invoking Gawk 11.3 Other Command-Line Arguments ================================= @@ -13388,8 +13396,8 @@ File: gawk.info, Node: Other Arguments, Next: AWKPATH Variable, Prev: Options Any additional arguments on the command line are normally treated as input files to be processed in the order specified. However, an argument that has the form `VAR=VALUE', assigns the value VALUE to the -variable VAR--it does not specify a file at all. (This was discussed -earlier in *note Assignment Options::.) +variable VAR--it does not specify a file at all. (See also *note +Assignment Options::.) All these arguments are made available to your `awk' program in the `ARGV' array (*note Built-in Variables::). Command-line options and @@ -13436,10 +13444,48 @@ the value of `FS' is not strictly necessary. It remains for historical compatibility. -File: gawk.info, Node: AWKPATH Variable, Next: Exit Status, Prev: Other Arguments, Up: Invoking Gawk +File: gawk.info, Node: Naming Standard Input, Next: Environment Variables, Prev: Other Arguments, Up: Invoking Gawk -11.4 The `AWKPATH' Environment Variable -======================================= +11.4 Naming Standard Input +========================== + +Often, you may wish to read standard input together with other files. +For example, you may wish to read one file, read standard input coming +from a pipe, and then read another file. + + The way to name the standard input, with all versions of `awk', is +to use a single, standalone minus sign or dash, `-'. For example: + + SOME_COMMAND | awk -f myprog.awk file1 - file2 + +Here, `awk' first reads `file1', then it reads the output of +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 +`/dev/stdin', both on the command line and with `getline'. Some other +versions of `awk' also support this, but it is not standard. + + +File: gawk.info, Node: Environment Variables, Next: Exit Status, Prev: Naming Standard Input, Up: Invoking Gawk + +11.5 The Environment Variables `gawk' Uses +========================================== + +A number of environment variables influence how `gawk' behaves. + +* Menu: + +* AWKPATH Variable:: Searching directories for `awk' programs. +* Other Environment Variables:: The environment variables. + + +File: gawk.info, Node: AWKPATH Variable, Next: Other Environment Variables, Up: Environment Variables + +11.5.1 The `AWKPATH' Environment Variable +----------------------------------------- The previous minor node described how `awk' program files can be named on the command-line with the `-f' option. In most `awk' @@ -13468,19 +13514,20 @@ Functions::). Path searching is not done if `gawk' is in compatibility mode. This is true for both `--traditional' and `--posix'. *Note Options::. - NOTE: If you want files in the current directory to be found, you - must include the current directory in the path, either by including - `.' explicitly in the path or by writing a null entry in the path. - (A null entry is indicated by starting or ending the path with a - colon or by placing two colons next to each other (`::').) If the - current directory is not included in the path, then files cannot be - found in the current directory. This path search mechanism is - identical to the shell's. + NOTE: To include the current directory in the path, either place + `.' explicitly in the path or write a null entry in the path. (A + null entry is indicated by starting or ending the path with a + colon or by placing two colons next to each other (`::').) This + path search mechanism is similar to the shell's. + + However, `gawk' always looks in the current directory before + before searching `AWKPATH', so there is no real reason to include + the current directory in the search path. - Starting with version 3.0, if `AWKPATH' is not defined in the -environment, `gawk' places its default search path into -`ENVIRON["AWKPATH"]'. This makes it easy to determine the actual search -path that `gawk' will use from within an `awk' program. + If `AWKPATH' is not defined in the environment, `gawk' places its +default search path into `ENVIRON["AWKPATH"]'. This makes it easy to +determine the actual search path that `gawk' will use from within an +`awk' program. While you can change `ENVIRON["AWKPATH"]' within your `awk' program, this has no effect on the running program's behavior. This makes @@ -13496,9 +13543,69 @@ the value of `$(datadir)' generated when `gawk' was configured. You probably don't need to worry about this, though. -File: gawk.info, Node: Exit Status, Next: Include Files, Prev: AWKPATH Variable, Up: Invoking Gawk +File: gawk.info, Node: Other Environment Variables, Prev: AWKPATH Variable, Up: Environment Variables + +11.5.2 Other Environment Variables +---------------------------------- + +A number of other environment variables affect `gawk''s behavior, but +they are more specialized. Those in the following list are meant to be +used by regular users. + +`POSIXLY_CORRECT' + If this variable exists, `gawk' switches to POSIX compatibility + mode, disabling all traditional and GNU extensions. *Note + Options::. + +`GAWK_SOCK_RETRIES' + Controls the number of time `gawk' will attempt to retry a two-way + TCP/IP (socket) connection before giving up. *Note TCP/IP + Networking::. + +`GAWK_MSEC_SLEEP' + Specifies the interval between connection retries, in + milliseconds. On systems that do not support the `usleep()' system + call, the value is rounded up to an integral number of seconds. + + The environment variables in the following table are meant for use +by the `gawk' developers for testing and tuning. They are subject to +change. The variables are: + +`AVG_CHAIN_MAX' + The average number of items `gawk' will maintain on a hash chain + for managing arrays. + +`AWK_HASH' + If this variable exists with a value of `gst', `gawk' will switch + to using the hash function from GNU Smalltalk for managing arrays. + This function may be marginally faster than the standard function. + +`AWKREADFUNC' + If this variable exists, `gawk' switches to reading source files + one line at a time, instead of reading in blocks. This exists for + debugging problems on filesystems on non-POSIX operating systems + where I/O is performed in records, not in blocks. + +`GAWK_NO_DFA' + If this variable exists, `gawk' does not use the DFA regexp matcher + for "does it match" kinds of tests. This can cause `gawk' to be + slower. Its purpose is to help isolate differences between the two + regexp matchers that `gawk' uses internally. (There aren't + supposed to be differences, but occasionally theory and practice + don't match up.) + +`GAWK_STACKSIZE' + This specifies the amount by which `gawk' should grow its internal + evaluation stack, when needed. + +`TIDYMEM' + If this variable exists, `gawk' uses the `mtrace()' library calls + from GNU LIBC to help track down possible memory leaks. + + +File: gawk.info, Node: Exit Status, Next: Include Files, Prev: Environment Variables, Up: Invoking Gawk -11.5 `gawk''s Exit Status +11.6 `gawk''s Exit Status ========================= If the `exit' statement is used with a value (*note Exit Statement::), @@ -13516,37 +13623,36 @@ non-POSIX systems, this value may be mapped to `EXIT_FAILURE'. File: gawk.info, Node: Include Files, Next: Obsolete, Prev: Exit Status, Up: Invoking Gawk -11.6 Including Other Files Into Your Program +11.7 Including Other Files Into Your Program ============================================ *FIXME:* This section still needs some editing. - Beginning with version *FIXME:* 3.1.8-bc of `gawk', the `@include' -keyword can be used to read external source `awk' files. That gives -the ability to split huge `awk' source files into smaller and -manageable files and also to reuse common `awk' code from various `awk' -scripts. In other words, you can group together `awk' functions, used -to carry out some sort of tasks, in external files. These files can be -used just like function libraries, using the `@include' keyword in -conjuction with the `AWKPATH' environment variable. + The `@include' keyword can be used to read external source `awk' +files. That gives the ability to split large `awk' source files into +smaller, more manageable pieces, and also lets you reuse common `awk' +code from various `awk' scripts. In other words, you can group +together `awk' functions, used to carry out specific tasks, in external +files. These files can be used just like function libraries, using the +`@include' keyword in conjuction with the `AWKPATH' environment +variable. Let's see an example to demonstrate file inclusion in `gawk'. To do -so, we'll use two (trivial) `awk' scripts, namely the `test1' and -`test2' `gawk' scripts. Here follows the `test1' `gawk' script file: +so, we'll use two (trivial) `awk' scripts, namely `test1' and `test2'. +Here is the `test1' script: BEGIN { print "This is script test1." } -and the `test2' file: +and here is `test2': @include "test1" BEGIN { print "This is script test2." } - Running `gawk' with the `test2' script you'll get the following -result: + Running `gawk' with `test2' produces the following result: $ gawk -f test2 -| This is file test1. @@ -13555,7 +13661,7 @@ result: `gawk' runs the `test2' script where `test1' has been included in the source of `test2' by means of the `@include' keyword. So, to include external `awk' source files you just use `@include' followed by -the name of the file to be included in double quotes. +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 @@ -13585,34 +13691,32 @@ or @include "/usr/awklib/network" -are valid. The `AWKPATH' environment variable can be of great value in -`@include' constructs. The same rules dominating the use of `AWKPATH' -variable in command line file searches are valid in `@include' -constructs too. That can be prooved very helpful in constructing `gawk' -function libraries. You can edit huge scripts containing usefull -`gawk' libraries and put those files in a special directory. You can -then include those "libraries" using either the full pathnames of the -files or by setting accordingly the `AWKPATH' environment variable and -then use `@include' with just the name part of the full file pathname. -Of course you can have more than one directory to keep library files; -the more complex the working enviroment is, the more directories you -need to organize the files to be included. - - The whole stuff of file inclusion can, of course, be carried out in -the command line, using as many `-f' options as required with the files -to be included as arguments, but the `@include' keyword can help you in -constructing self-contained `gawk' programs, thus reducing the need of -writing complex and tedious command lines. - - `AWKPATH' is also used by the `@include' mechanism, that is the -files to be included will be seeked in the directories specified. Keep -in mind, however, that the current directory is been searched first, -either it's listed in the `AWKPATH' string or not. +are valid. The `AWKPATH' environment variable can be of great value +when using `@include'. The same rules for the use of the `AWKPATH' +variable in command line file searches apply to `@include' also. This +is very helpful in constructing `gawk' function libraries. You can +edit huge scripts containing useful `gawk' libraries and put those +files in a special directory. You can then include those "libraries" +using either the full pathnames of the files or by setting the +`AWKPATH' environment variable accordingly and then using `@include' +with just the name part of the full file pathname. Of course you can +have more than one directory to keep library files; the more complex +the working enviroment is, the more directories you may need to organize +the files to be included. + + Given the ability to specify multiple `-f' options, the `@include' +mechanism is not strictly necessary. However, the `@include' keyword +can help you in constructing self-contained `gawk' programs, thus +reducing the need of writing complex and tedious command lines. + + As mentioned in *note AWKPATH Variable::, the current directory is +always search first for source files, before searching in `AWKPATH', +and this also applies to files named with `@include'. File: gawk.info, Node: Obsolete, Next: Undocumented, Prev: Include Files, Up: Invoking Gawk -11.7 Obsolete Options and/or Features +11.8 Obsolete Options and/or Features ===================================== This minor node describes features and/or command-line options from @@ -13620,18 +13724,15 @@ previous releases of `gawk' that are either not available in the current version or that are still supported but deprecated (meaning that they will _not_ be in the next release). - For version 3.1 of `gawk', there are no deprecated command-line -options from the previous version of `gawk'. - The process-related special files `/dev/pid', `/dev/ppid', `/dev/pgrpid', and `/dev/user' were deprecated in `gawk' 3.1, but still -worked. As of version 3.2, they are no longer interpreted specially by +worked. As of version 4.0, they are no longer interpreted specially by `gawk'. (Use `PROCINFO' instead; see *note Auto-set::.) -File: gawk.info, Node: Undocumented, Next: Known Bugs, Prev: Obsolete, Up: Invoking Gawk +File: gawk.info, Node: Undocumented, Prev: Obsolete, Up: Invoking Gawk -11.8 Undocumented Options and Features +11.9 Undocumented Options and Features ====================================== Use the Source, Luke! @@ -13640,21 +13741,6 @@ File: gawk.info, Node: Undocumented, Next: Known Bugs, Prev: Obsolete, Up: I This minor node intentionally left blank. -File: gawk.info, Node: Known Bugs, Prev: Undocumented, Up: Invoking Gawk - -11.9 Known Bugs in `gawk' -========================= - - * The `-F' option for changing the value of `FS' (*note Options::) - is not necessary given the command-line variable assignment - feature; it remains only for backward compatibility. - - * Syntactically invalid single-character programs tend to overflow - the parse stack, generating a rather unhelpful message. Such - programs are surprisingly difficult to diagnose in the completely - general case, and the effort to do so really is not worth it. - - File: gawk.info, Node: Library Functions, Next: Sample Programs, Prev: Invoking Gawk, Up: Top 12 A Library of `awk' Functions @@ -24357,10 +24443,10 @@ Index (line 86) * * (asterisk), * operator, null strings, matching: Gory Details. (line 96) -* * (asterisk), ** operator <1>: Options. (line 208) +* * (asterisk), ** operator <1>: Options. (line 214) * * (asterisk), ** operator <2>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) -* * (asterisk), **= operator <1>: Options. (line 208) +* * (asterisk), **= operator <1>: Options. (line 214) * * (asterisk), **= operator <2>: Precedence. (line 95) * * (asterisk), **= operator: Assignment Ops. (line 129) * * (asterisk), *= operator <1>: Precedence. (line 95) @@ -24379,77 +24465,76 @@ Index * - (hyphen), -- operator: Increment Ops. (line 48) * - (hyphen), -= operator <1>: Precedence. (line 95) * - (hyphen), -= operator: Assignment Ops. (line 129) -* - (hyphen), filenames beginning with: Options. (line 56) +* - (hyphen), filenames beginning with: Options. (line 59) * - (hyphen), in character lists: Character Lists. (line 16) -* --assign option: Options. (line 30) -* --c option: Options. (line 75) -* --characters-as-bytes option: Options. (line 65) -* --copyright option: Options. (line 83) +* --assign option: Options. (line 32) +* --c option: Options. (line 78) +* --characters-as-bytes option: Options. (line 68) +* --copyright option: Options. (line 86) * --disable-lint configuration option: Additional Configuration Options. (line 13) * --disable-nls configuration option: Additional Configuration Options. (line 28) * --dump-variables option <1>: Library Names. (line 45) -* --dump-variables option: Options. (line 88) -* --exec option: Options. (line 110) +* --dump-variables option: Options. (line 91) +* --exec option: Options. (line 113) * --field-separator option: Options. (line 21) * --file option: Options. (line 25) -* --gen-pot option <1>: Options. (line 129) +* --gen-pot option <1>: Options. (line 135) * --gen-pot option: String Extraction. (line 6) -* --help option: Options. (line 136) -* --L option: Options. (line 244) -* --lint option <1>: Options. (line 141) +* --help option: Options. (line 142) +* --L option: Options. (line 250) +* --lint option <1>: Options. (line 147) * --lint option: Command Line. (line 20) -* --lint-old option: Options. (line 244) -* --non-decimal-data option <1>: Options. (line 160) +* --lint-old option: Options. (line 250) +* --non-decimal-data option <1>: Options. (line 166) * --non-decimal-data option: Nondecimal Data. (line 6) * --non-decimal-data option, strtonum() function and: Nondecimal Data. (line 36) -* --optimize option: Options. (line 173) -* --posix option: Options. (line 192) -* --posix option, --traditional option and: Options. (line 222) -* --profile option <1>: Options. (line 180) +* --optimize option: Options. (line 179) +* --posix option: Options. (line 198) +* --posix option, --traditional option and: Options. (line 228) +* --profile option <1>: Options. (line 186) * --profile option: Profiling. (line 15) -* --re-interval option: Options. (line 228) -* --sandbox option: Options. (line 235) +* --re-interval option: Options. (line 234) +* --sandbox option: Options. (line 241) * --sandbox option, disabling system function: I/O Functions. (line 86) * --sandbox option, input redirection with getline: Getline. (line 19) * --sandbox option, output redirection with print, printf: Redirection. (line 6) -* --source option: Options. (line 102) -* --traditional option: Options. (line 75) -* --traditional option, --posix option and: Options. (line 222) -* --use-lc-numeric option: Options. (line 168) -* --version option: Options. (line 249) +* --source option: Options. (line 105) +* --traditional option: Options. (line 78) +* --traditional option, --posix option and: Options. (line 228) +* --use-lc-numeric option: Options. (line 174) +* --version option: Options. (line 255) * --with-whiny-user-strftime configuration option: Additional Configuration Options. (line 9) -* -b option: Options. (line 65) -* -C option: Options. (line 83) -* -d option: Options. (line 88) -* -E option: Options. (line 110) -* -e option: Options. (line 102) +* -b option: Options. (line 68) +* -C option: Options. (line 86) +* -d option: Options. (line 91) +* -E option: Options. (line 113) +* -e option: Options. (line 105) * -f option: Options. (line 25) * -F option <1>: Options. (line 21) * -F option: Command Line Field Separator. (line 6) * -f option: Long. (line 12) -* -F option, -Ft sets FS to TAB: Options. (line 257) -* -f option, on command line: Options. (line 262) -* -F option, troubleshooting: Known Bugs. (line 6) -* -g option: Options. (line 129) -* -h option: Options. (line 136) -* -l option: Options. (line 141) -* -N option: Options. (line 168) -* -n option: Options. (line 160) -* -O option: Options. (line 173) -* -P option: Options. (line 192) -* -p option: Options. (line 180) -* -r option: Options. (line 228) -* -S option: Options. (line 235) -* -V option: Options. (line 249) -* -v option: Options. (line 30) +* -F option, -Ft sets FS to TAB: Options. (line 263) +* -f option, on command line: Options. (line 268) +* -g option: Options. (line 135) +* -h option: Options. (line 142) +* -l option: Options. (line 147) +* -N option: Options. (line 174) +* -n option: Options. (line 166) +* -O option: Options. (line 179) +* -P option: Options. (line 198) +* -p option: Options. (line 186) +* -r option: Options. (line 234) +* -S option: Options. (line 241) +* -V option: Options. (line 255) +* -v option: Options. (line 32) * -v option, variables, assigning: Assignment Options. (line 12) -* -W option: Options. (line 44) +* -W option: Options. (line 46) * . (period): Regexp Operators. (line 43) * .mo files: Explaining gettext. (line 41) * .mo files, converting from .po: I18N Example. (line 62) @@ -24555,9 +24640,9 @@ Index * ^ (caret) <1>: GNU Regexp Operators. (line 59) * ^ (caret): Regexp Operators. (line 22) -* ^ (caret), ^ operator <1>: Options. (line 208) +* ^ (caret), ^ operator <1>: Options. (line 214) * ^ (caret), ^ operator: Precedence. (line 49) -* ^ (caret), ^= operator <1>: Options. (line 208) +* ^ (caret), ^= operator <1>: Options. (line 214) * ^ (caret), ^= operator <2>: Precedence. (line 95) * ^ (caret), ^= operator: Assignment Ops. (line 129) * ^ (caret), in character lists: Character Lists. (line 16) @@ -24688,10 +24773,10 @@ Index (line 86) * asterisk (*), * operator, null strings, matching: Gory Details. (line 96) -* asterisk (*), ** operator <1>: Options. (line 208) +* asterisk (*), ** operator <1>: Options. (line 214) * asterisk (*), ** operator <2>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) -* asterisk (*), **= operator <1>: Options. (line 208) +* asterisk (*), **= operator <1>: Options. (line 214) * asterisk (*), **= operator <2>: Precedence. (line 95) * asterisk (*), **= operator: Assignment Ops. (line 129) * asterisk (*), *= operator <1>: Precedence. (line 95) @@ -24715,7 +24800,7 @@ Index * awk programs, location of: Options. (line 25) * awk programs, one-line examples: Very Simple. (line 45) * awk programs, profiling: Profiling. (line 6) -* awk programs, profiling, enabling: Options. (line 180) +* awk programs, profiling, enabling: Options. (line 186) * awk programs, running <1>: Long. (line 6) * awk programs, running: Running gawk. (line 6) * awk programs, running, from shell scripts: One-shot. (line 22) @@ -24755,7 +24840,7 @@ Index * AWKPATH environment variable: AWKPATH Variable. (line 6) * awkprof.out file: Profiling. (line 10) * awksed.awk program: Simple Sed. (line 25) -* awkvars.out file: Options. (line 88) +* awkvars.out file: Options. (line 91) * b debugger command (alias for break): Breakpoint Control. (line 11) * backslash (\) <1>: Regexp Operators. (line 18) * backslash (\) <2>: Quoting. (line 31) @@ -24886,7 +24971,7 @@ Index * built-in functions: Functions. (line 6) * built-in functions, evaluation order: Calling Built-in. (line 30) * built-in variables: Built-in Variables. (line 6) -* built-in variables, -v option, setting with: Options. (line 38) +* built-in variables, -v option, setting with: Options. (line 40) * built-in variables, conveying information: Auto-set. (line 6) * built-in variables, user-modifiable: User-modified. (line 6) * call by reference: Pass By Value/Reference. @@ -24896,9 +24981,9 @@ Index * caret (^) <1>: GNU Regexp Operators. (line 59) * caret (^): Regexp Operators. (line 22) -* caret (^), ^ operator <1>: Options. (line 208) +* caret (^), ^ operator <1>: Options. (line 214) * caret (^), ^ operator: Precedence. (line 49) -* caret (^), ^= operator <1>: Options. (line 208) +* caret (^), ^= operator <1>: Options. (line 214) * caret (^), ^= operator <2>: Precedence. (line 95) * caret (^), ^= operator: Assignment Ops. (line 129) * caret (^), in character lists: Character Lists. (line 16) @@ -24910,7 +24995,7 @@ Index * case sensitivity, regexps and <1>: User-modified. (line 82) * case sensitivity, regexps and: Case-sensitivity. (line 6) * case sensitivity, string comparisons and: User-modified. (line 82) -* CGI, awk scripts for: Options. (line 110) +* CGI, awk scripts for: Options. (line 113) * character encodings: Ordinal Functions. (line 44) * character lists <1>: Character Lists. (line 6) * character lists: Regexp Operators. (line 55) @@ -24967,7 +25052,7 @@ Index * command line, options <2>: Command Line Field Separator. (line 6) * command line, options: Long. (line 12) -* command line, options, end of: Options. (line 51) +* command line, options, end of: Options. (line 54) * command line, variables, assigning on: Assignment Options. (line 6) * command-line options, processing: Getopt Function. (line 6) * command-line options, string extraction: String Extraction. (line 6) @@ -24988,7 +25073,7 @@ Index (line 60) * compatibility mode (gawk), octal numbers: Nondecimal-numbers. (line 60) -* compatibility mode (gawk), specifying: Options. (line 75) +* compatibility mode (gawk), specifying: Options. (line 78) * compiled programs <1>: Glossary. (line 155) * compiled programs: Basic High Level. (line 15) * compl() function (gawk): Bitwise Functions. (line 42) @@ -25028,7 +25113,7 @@ Index * cos() function: Numeric Functions. (line 14) * counting: Wc Program. (line 6) * csh utility: Statements/Lines. (line 44) -* csh utility, POSIXLY_CORRECT environment variable: Options. (line 300) +* csh utility, POSIXLY_CORRECT environment variable: Options. (line 306) * csh utility, |& operator, comparison with: Two-way I/O. (line 44) * ctime() user-defined function: Function Example. (line 72) * currency symbols, localization: Explaining gettext. (line 103) @@ -25195,9 +25280,8 @@ Index (line 67) * debugger commands, watch: Viewing And Changing Data. (line 67) -* debugging gawk: Known Bugs. (line 6) * debugging gawk, bug reports: Bugs. (line 9) -* decimal point character, locale specific: Options. (line 216) +* decimal point character, locale specific: Options. (line 222) * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) * Deifik, Scott <1>: Bugs. (line 69) @@ -25360,7 +25444,7 @@ Index * escape processing, gsub()/gensub()/sub() functions: Gory Details. (line 6) * escape sequences: Escape Sequences. (line 6) -* escape sequences, unrecognized: Options. (line 196) +* escape sequences, unrecognized: Options. (line 202) * eval debugger command: Viewing And Changing Data. (line 23) * evaluation order: Increment Ops. (line 61) @@ -25417,7 +25501,7 @@ Index * Fenlason, Jay <1>: Contributors. (line 19) * Fenlason, Jay: History. (line 30) * fflush() function: I/O Functions. (line 25) -* fflush() function, unsupported: Options. (line 219) +* fflush() function, unsupported: Options. (line 225) * field numbers: Nonconstant Fields. (line 6) * field operator $: Fields. (line 19) * field operators, dollar sign as: Fields. (line 19) @@ -25475,7 +25559,7 @@ Index * files, as single records: Records. (line 193) * files, awk programs in: Long. (line 6) * files, awkprof.out: Profiling. (line 10) -* files, awkvars.out: Options. (line 88) +* files, awkvars.out: Options. (line 91) * files, closing: I/O Functions. (line 10) * files, descriptors, See file descriptors: Special FD. (line 6) * files, group: Group Functions. (line 6) @@ -25503,7 +25587,7 @@ Index * files, portable object template: Explaining gettext. (line 30) * files, portable object, converting to message object files: I18N Example. (line 62) -* files, portable object, generating: Options. (line 129) +* files, portable object, generating: Options. (line 135) * files, processing, ARGIND variable and: Auto-set. (line 47) * files, reading: Rewind Function. (line 6) * files, reading, multiline records: Multiple Line. (line 6) @@ -25556,8 +25640,7 @@ Index * FS variable, --field-separator option and: Options. (line 21) * FS variable, as null string: Single Character Fields. (line 20) -* FS variable, as TAB character: Options. (line 212) -* FS variable, changing value of <1>: Known Bugs. (line 6) +* FS variable, as TAB character: Options. (line 218) * FS variable, changing value of: Field Separators. (line 34) * FS variable, running awk programs and: Cut Program. (line 66) * FS variable, setting from command line: Command Line Field Separator. @@ -25633,11 +25716,10 @@ Index * gawk, configuring, options: Additional Configuration Options. (line 6) * gawk, continue statement in: Continue Statement. (line 43) -* gawk, debugging: Known Bugs. (line 6) * gawk, distribution: Distribution contents. (line 6) * gawk, escape sequences: Escape Sequences. (line 125) -* gawk, extensions, disabling: Options. (line 192) +* gawk, extensions, disabling: Options. (line 198) * gawk, features, adding: Adding Code. (line 6) * gawk, features, advanced: Advanced Features. (line 6) * gawk, fflush() function in: I/O Functions. (line 45) @@ -25685,7 +25767,7 @@ Index * gawk, string-translation functions: I18N Functions. (line 6) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 35) -* gawk, versions of, information about, printing: Options. (line 249) +* gawk, versions of, information about, printing: Options. (line 255) * gawk, word-boundary operator: GNU Regexp Operators. (line 63) * General Public License (GPL): Glossary. (line 295) @@ -25743,7 +25825,7 @@ Index * GNU Lesser General Public License: Glossary. (line 373) * GNU long options <1>: Options. (line 6) * GNU long options: Command Line. (line 13) -* GNU long options, printing list of: Options. (line 136) +* GNU long options, printing list of: Options. (line 142) * GNU Project <1>: Glossary. (line 304) * GNU Project: Manual History. (line 11) * GNU/Linux <1>: Glossary. (line 582) @@ -25752,7 +25834,7 @@ Index * GNU/Linux: Manual History. (line 28) * GPL (General Public License) <1>: Glossary. (line 295) * GPL (General Public License): Manual History. (line 11) -* GPL (General Public License), printing: Options. (line 83) +* GPL (General Public License), printing: Options. (line 86) * grcat program: Group Functions. (line 15) * Grigera, Juan: Contributors. (line 55) * group database, reading: Group Functions. (line 6) @@ -25774,7 +25856,7 @@ Index * help debugger command: Miscellaneous Dgawk Commands. (line 71) * hexadecimal numbers: Nondecimal-numbers. (line 6) -* hexadecimal values, enabling interpretation of: Options. (line 160) +* hexadecimal values, enabling interpretation of: Options. (line 166) * histsort.awk program: History Sorting. (line 25) * Hughes, Phil: Acknowledgments. (line 42) * HUP signal: Profiling. (line 204) @@ -25783,7 +25865,7 @@ Index * hyphen (-), -- operator: Increment Ops. (line 48) * hyphen (-), -= operator <1>: Precedence. (line 95) * hyphen (-), -= operator: Assignment Ops. (line 129) -* hyphen (-), filenames beginning with: Options. (line 56) +* hyphen (-), filenames beginning with: Options. (line 59) * hyphen (-), in character lists: Character Lists. (line 16) * i debugger command (alias for info): Dgawk Info. (line 12) * id utility: Id Program. (line 6) @@ -25961,9 +26043,9 @@ Index * lint checking, array subscripts: Uninitialized Subscripts. (line 43) * lint checking, empty programs: Command Line. (line 16) -* lint checking, issuing warnings: Options. (line 141) +* lint checking, issuing warnings: Options. (line 147) * lint checking, POSIXLY_CORRECT environment variable: Options. - (line 287) + (line 293) * lint checking, undefined functions: Pass By Value/Reference. (line 88) * LINT variable: User-modified. (line 98) @@ -25975,7 +26057,7 @@ Index (line 77) * local variables: Variable Scope. (line 6) * locale categories: Explaining gettext. (line 80) -* locale decimal point character: Options. (line 216) +* locale decimal point character: Options. (line 222) * locale, definition of: Locales. (line 6) * localization: I18N and L10N. (line 6) * localization, See internationalization, localization: I18N and L10N. @@ -26042,7 +26124,7 @@ Index * NetBSD: Glossary. (line 582) * networks, programming: TCP/IP Networking. (line 6) * networks, support for: Special Network. (line 6) -* newlines <1>: Options. (line 199) +* newlines <1>: Options. (line 205) * newlines <2>: Boolean Ops. (line 67) * newlines: Statements/Lines. (line 6) * newlines, as field separators: Default Field Splitting. @@ -26122,7 +26204,7 @@ Index * oawk utility: Names. (line 17) * obsolete features: Obsolete. (line 6) * octal numbers: Nondecimal-numbers. (line 6) -* octal values, enabling interpretation of: Options. (line 160) +* octal values, enabling interpretation of: Options. (line 166) * OFMT variable <1>: User-modified. (line 115) * OFMT variable <2>: Conversion. (line 54) * OFMT variable: OFMT. (line 15) @@ -26169,13 +26251,13 @@ Index * options, command-line <2>: Command Line Field Separator. (line 6) * options, command-line: Long. (line 12) -* options, command-line, end of: Options. (line 51) +* options, command-line, end of: Options. (line 54) * options, command-line, invoking awk: Command Line. (line 6) * options, command-line, processing: Getopt Function. (line 6) * options, deprecated: Obsolete. (line 6) * options, long <1>: Options. (line 6) * options, long: Command Line. (line 13) -* options, printing list of: Options. (line 136) +* options, printing list of: Options. (line 142) * OR bitwise operation: Bitwise Functions. (line 6) * or Boolean-logic operator: Boolean Ops. (line 6) * or() function (gawk): Bitwise Functions. (line 48) @@ -26268,13 +26350,13 @@ Index * portability, NF variable, decrementing: Changing Fields. (line 115) * portability, operators: Increment Ops. (line 61) * portability, operators, not in POSIX awk: Precedence. (line 98) -* portability, POSIXLY_CORRECT environment variable: Options. (line 305) +* portability, POSIXLY_CORRECT environment variable: Options. (line 311) * portability, substr() function: String Functions. (line 484) * portable object files <1>: Translator i18n. (line 6) * portable object files: Explaining gettext. (line 36) * portable object files, converting to message object files: I18N Example. (line 62) -* portable object files, generating: Options. (line 129) +* portable object files, generating: Options. (line 135) * portable object template files: Explaining gettext. (line 30) * porting gawk: New Ports. (line 6) * positional specifiers, printf statement <1>: Printf Ordering. @@ -26316,11 +26398,11 @@ Index * POSIX awk, regular expressions and: Regexp Operators. (line 156) * POSIX awk, timestamps and: Time Functions. (line 6) * POSIX awk, | I/O operator and: Getline/Pipe. (line 52) -* POSIX mode: Options. (line 192) +* POSIX mode: Options. (line 198) * POSIX, awk and: Preface. (line 22) * POSIX, gawk extensions not included in: POSIX/GNU. (line 6) * POSIX, programs, implementing in awk: Clones. (line 6) -* POSIXLY_CORRECT environment variable: Options. (line 287) +* POSIXLY_CORRECT environment variable: Options. (line 293) * precedence <1>: Precedence. (line 6) * precedence: Increment Ops. (line 61) * precedence, regexp operators: Regexp Operators. (line 151) @@ -26354,7 +26436,7 @@ Index * printf statement, sprintf() function and: Round Function. (line 6) * printf statement, syntax of: Basic Printf. (line 6) * printing: Printing. (line 6) -* printing, list of options: Options. (line 136) +* printing, list of options: Options. (line 142) * printing, mailing labels: Labels Program. (line 6) * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) @@ -26373,7 +26455,7 @@ Index * programming conventions, --non-decimal-data option: Nondecimal Data. (line 36) * programming conventions, ARGC/ARGV variables: Auto-set. (line 31) -* programming conventions, exit statement: Exit Statement. (line 36) +* programming conventions, exit statement: Exit Statement. (line 37) * programming conventions, function parameters: Return Statement. (line 44) * programming conventions, functions, calling: Calling Built-in. @@ -26473,7 +26555,7 @@ Index (line 59) * regular expressions, gawk, command-line options: GNU Regexp Operators. (line 70) -* regular expressions, interval expressions and: Options. (line 228) +* regular expressions, interval expressions and: Options. (line 234) * regular expressions, leftmost longest match: Leftmost Longest. (line 6) * regular expressions, operators <1>: Regexp Operators. (line 6) @@ -26546,7 +26628,7 @@ Index * rvalues/lvalues: Assignment Ops. (line 32) * s debugger command (alias for step): Dgawk Execution Control. (line 68) -* sandbox mode: Options. (line 235) +* sandbox mode: Options. (line 241) * scalar values: Basic Data Typing. (line 13) * Schorr, Andrew: Acknowledgments. (line 59) * Schreiber, Bert: Acknowledgments. (line 37) @@ -26631,7 +26713,7 @@ Index * source code, Bell Laboratories awk: Other Versions. (line 13) * source code, gawk: Gawk Distribution. (line 6) * source code, mawk: Other Versions. (line 34) -* source code, mixing: Options. (line 102) +* source code, mixing: Options. (line 105) * source files, search path for: Igawk Program. (line 358) * sparse arrays: Array Intro. (line 71) * Spencer, Henry: Glossary. (line 12) @@ -26765,8 +26847,7 @@ Index * trace debugger command: Miscellaneous Dgawk Commands. (line 113) * translate.awk program: Translate Program. (line 55) -* troubleshooting, --non-decimal-data option: Options. (line 163) -* troubleshooting, -F option: Known Bugs. (line 6) +* troubleshooting, --non-decimal-data option: Options. (line 169) * troubleshooting, == operator: Comparison Operators. (line 37) * troubleshooting, awk uses FS not IFS: Field Separators. (line 29) @@ -26779,8 +26860,7 @@ Index (line 159) * troubleshooting, fflush() function: I/O Functions. (line 52) * troubleshooting, function call syntax: Function Calls. (line 28) -* troubleshooting, gawk <1>: Compatibility Mode. (line 6) -* troubleshooting, gawk: Known Bugs. (line 6) +* troubleshooting, gawk: Compatibility Mode. (line 6) * troubleshooting, gawk, bug reports: Bugs. (line 9) * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in. (line 16) @@ -26799,7 +26879,7 @@ Index * troubleshooting, substr() function: String Functions. (line 471) * troubleshooting, system() function: I/O Functions. (line 86) * troubleshooting, typographical errors, global variables: Options. - (line 92) + (line 95) * true, logical: Truth Values. (line 6) * Trueman, David <1>: Contributors. (line 31) * Trueman, David <2>: Acknowledgments. (line 46) @@ -26857,7 +26937,7 @@ Index * variables, assigning on command line: Assignment Options. (line 6) * variables, built-in <1>: Built-in Variables. (line 6) * variables, built-in: Using Variables. (line 20) -* variables, built-in, -v option, setting with: Options. (line 38) +* variables, built-in, -v option, setting with: Options. (line 40) * variables, built-in, conveying information: Auto-set. (line 6) * variables, flag: Boolean Ops. (line 67) * variables, getline command into, using <1>: Getline/Variable/Coprocess. @@ -26868,12 +26948,12 @@ Index (line 6) * variables, getline command into, using: Getline/Variable. (line 6) * variables, global, for library functions: Library Names. (line 11) -* variables, global, printing list of: Options. (line 88) +* variables, global, printing list of: Options. (line 91) * variables, initializing: Using Variables. (line 20) * variables, local: Variable Scope. (line 6) * variables, names of: Arrays. (line 18) * variables, private: Library Names. (line 11) -* variables, setting: Options. (line 30) +* variables, setting: Options. (line 32) * variables, shadowing: Definition Syntax. (line 61) * variables, types of: Assignment Ops. (line 40) * variables, types of, comparison expressions and: Typing and Comparison. @@ -26897,7 +26977,7 @@ Index * Wall, Larry <1>: Future Extensions. (line 6) * Wall, Larry: Array Intro. (line 6) * Wallin, Anders: Acknowledgments. (line 59) -* warnings, issuing: Options. (line 141) +* warnings, issuing: Options. (line 147) * watch debugger command: Viewing And Changing Data. (line 67) * wc utility: Wc Program. (line 6) @@ -26909,7 +26989,7 @@ Index * whitespace, as field separators: Default Field Splitting. (line 6) * whitespace, functions, calling: Calling Built-in. (line 10) -* whitespace, newlines as: Options. (line 199) +* whitespace, newlines as: Options. (line 205) * Williams, Kent: Contributors. (line 37) * Woehlke, Matthew: Contributors. (line 72) * Woods, John: Contributors. (line 28) @@ -26960,405 +27040,407 @@ Index Tag Table: Node: Top1340 -Node: Foreword30113 -Node: Preface34429 -Ref: Preface-Footnote-137381 -Ref: Preface-Footnote-237487 -Node: History37719 -Node: Names39951 -Ref: Names-Footnote-141428 -Node: This Manual41500 -Ref: This Manual-Footnote-146398 -Node: Conventions46498 -Node: Manual History48557 -Ref: Manual History-Footnote-151735 -Ref: Manual History-Footnote-251776 -Node: How To Contribute51850 -Node: Acknowledgments52994 -Node: Getting Started57263 -Node: Running gawk59635 -Node: One-shot60821 -Node: Read Terminal62046 -Ref: Read Terminal-Footnote-163696 -Ref: Read Terminal-Footnote-263970 -Node: Long64141 -Node: Executable Scripts65517 -Ref: Executable Scripts-Footnote-167378 -Ref: Executable Scripts-Footnote-267480 -Node: Comments67931 -Node: Quoting70299 -Node: DOS Quoting74916 -Node: Sample Data Files75584 -Node: Very Simple78616 -Node: Two Rules83213 -Node: More Complex85360 -Ref: More Complex-Footnote-188290 -Node: Statements/Lines88370 -Ref: Statements/Lines-Footnote-192726 -Node: Other Features92991 -Node: When93860 -Node: Regexp96003 -Node: Regexp Usage97457 -Node: Escape Sequences99483 -Node: Regexp Operators105226 -Ref: Regexp Operators-Footnote-1112398 -Ref: Regexp Operators-Footnote-2112545 -Node: Character Lists112643 -Ref: table-char-classes114418 -Node: GNU Regexp Operators117043 -Node: Case-sensitivity120756 -Ref: Case-sensitivity-Footnote-1123711 -Ref: Case-sensitivity-Footnote-2123946 -Node: Leftmost Longest124054 -Node: Computed Regexps125255 -Node: Locales128672 -Node: Reading Files131762 -Node: Records133703 -Ref: Records-Footnote-1142269 -Node: Fields142306 -Ref: Fields-Footnote-1145338 -Node: Nonconstant Fields145424 -Node: Changing Fields147626 -Node: Field Separators152911 -Node: Default Field Splitting155540 -Node: Regexp Field Splitting156657 -Node: Single Character Fields160007 -Node: Command Line Field Separator161058 -Node: Field Splitting Summary164497 -Ref: Field Splitting Summary-Footnote-1167683 -Node: Constant Size167784 -Node: Splitting By Content172255 -Ref: Splitting By Content-Footnote-1175857 -Node: Multiple Line175897 -Ref: Multiple Line-Footnote-1181637 -Node: Getline181816 -Node: Plain Getline184044 -Node: Getline/Variable186133 -Node: Getline/File187274 -Node: Getline/Variable/File188596 -Ref: Getline/Variable/File-Footnote-1190195 -Node: Getline/Pipe190282 -Node: Getline/Variable/Pipe192830 -Node: Getline/Coprocess193937 -Node: Getline/Variable/Coprocess195180 -Node: Getline Notes195894 -Node: Getline Summary197836 -Ref: table-getline-variants198120 -Node: Command line directories199025 -Node: Printing199650 -Node: Print201281 -Node: Print Examples202618 -Node: Output Separators205402 -Node: OFMT207161 -Node: Printf208519 -Node: Basic Printf209425 -Node: Control Letters210962 -Node: Format Modifiers214774 -Node: Printf Examples220785 -Node: Redirection223500 -Node: Special Files230478 -Node: Special FD231011 -Ref: Special FD-Footnote-1234586 -Node: Special Network234660 -Node: Special Caveats235515 -Node: Close Files And Pipes236309 -Ref: Close Files And Pipes-Footnote-1243253 -Ref: Close Files And Pipes-Footnote-2243401 -Node: Expressions243551 -Node: Values244620 -Node: Constants245296 -Node: Scalar Constants245976 -Ref: Scalar Constants-Footnote-1246835 -Node: Nondecimal-numbers247017 -Node: Regexp Constants250076 -Node: Using Constant Regexps250551 -Node: Variables253556 -Node: Using Variables254211 -Node: Assignment Options255938 -Node: Conversion257819 -Ref: table-locale-affects263193 -Ref: Conversion-Footnote-1263817 -Node: All Operators263926 -Node: Arithmetic Ops264556 -Node: Concatenation267055 -Ref: Concatenation-Footnote-1269848 -Node: Assignment Ops269967 -Ref: table-assign-ops274955 -Node: Increment Ops276356 -Node: Truth Values and Conditions279834 -Node: Truth Values280917 -Node: Typing and Comparison281965 -Node: Variable Typing282754 -Ref: Variable Typing-Footnote-1286651 -Node: Comparison Operators286773 -Ref: table-relational-ops287183 -Node: POSIX String Comparison290732 -Ref: POSIX String Comparison-Footnote-1291689 -Node: Boolean Ops291827 -Ref: Boolean Ops-Footnote-1295905 -Node: Conditional Exp295996 -Node: Function Calls297728 -Node: Precedence301287 -Node: Patterns and Actions304940 -Node: Pattern Overview305994 -Node: Regexp Patterns307660 -Node: Expression Patterns308203 -Node: Ranges311777 -Node: BEGIN/END314743 -Node: Using BEGIN/END315493 -Ref: Using BEGIN/END-Footnote-1318224 -Node: I/O And BEGIN/END318338 -Node: Empty320607 -Node: BEGINFILE/ENDFILE320941 -Node: Using Shell Variables323766 -Node: Action Overview326045 -Node: Statements328402 -Node: If Statement330261 -Node: While Statement331760 -Node: Do Statement333804 -Node: For Statement334960 -Node: Switch Statement338112 -Node: Break Statement340209 -Node: Continue Statement342185 -Node: Next Statement343886 -Node: Nextfile Statement346268 -Node: Exit Statement348786 -Node: Built-in Variables351061 -Node: User-modified352156 -Ref: User-modified-Footnote-1360157 -Node: Auto-set360219 -Ref: Auto-set-Footnote-1369010 -Node: ARGC and ARGV369215 -Node: Arrays372974 -Node: Array Basics374545 -Node: Array Intro375256 -Node: Reference to Elements379574 -Node: Assigning Elements381844 -Node: Array Example382335 -Node: Scanning an Array384067 -Node: Delete386344 -Ref: Delete-Footnote-1388742 -Node: Numeric Array Subscripts388799 -Node: Uninitialized Subscripts390982 -Node: Multi-dimensional392610 -Node: Multi-scanning395701 -Node: Array Sorting397285 -Ref: Array Sorting-Footnote-1400483 -Node: Arrays of Arrays400677 -Node: Functions404785 -Node: Built-in405607 -Node: Calling Built-in406621 -Node: Numeric Functions408597 -Ref: Numeric Functions-Footnote-1412306 -Ref: Numeric Functions-Footnote-2412642 -Ref: Numeric Functions-Footnote-3412690 -Node: String Functions412959 -Ref: String Functions-Footnote-1434758 -Ref: String Functions-Footnote-2434887 -Ref: String Functions-Footnote-3435135 -Node: Gory Details435222 -Ref: table-sub-escapes436879 -Ref: table-posix-sub438193 -Ref: table-gensub-escapes439093 -Node: I/O Functions440264 -Ref: I/O Functions-Footnote-1446961 -Node: Time Functions447108 -Ref: Time Functions-Footnote-1457764 -Ref: Time Functions-Footnote-2457832 -Ref: Time Functions-Footnote-3457990 -Ref: Time Functions-Footnote-4458101 -Ref: Time Functions-Footnote-5458213 -Ref: Time Functions-Footnote-6458440 -Node: Bitwise Functions458706 -Ref: table-bitwise-ops459264 -Ref: Bitwise Functions-Footnote-1463424 -Node: I18N Functions463608 -Node: User-defined465238 -Node: Definition Syntax466042 -Ref: Definition Syntax-Footnote-1470672 -Node: Function Example470741 -Node: Function Caveats473335 -Node: Calling A Function473747 -Node: Variable Scope474836 -Node: Pass By Value/Reference476764 -Node: Return Statement480204 -Node: Dynamic Typing483146 -Node: Indirect Calls483883 -Node: Internationalization493568 -Node: I18N and L10N494994 -Node: Explaining gettext495678 -Ref: Explaining gettext-Footnote-1500738 -Ref: Explaining gettext-Footnote-2500921 -Node: Programmer i18n501086 -Node: Translator i18n505347 -Node: String Extraction506138 -Ref: String Extraction-Footnote-1507097 -Node: Printf Ordering507183 -Ref: Printf Ordering-Footnote-1509965 -Node: I18N Portability510029 -Ref: I18N Portability-Footnote-1512476 -Node: I18N Example512539 -Ref: I18N Example-Footnote-1515172 -Node: Gawk I18N515244 -Node: Advanced Features515811 -Node: Nondecimal Data517126 -Node: Two-way I/O518687 -Ref: Two-way I/O-Footnote-1524101 -Node: TCP/IP Networking524178 -Node: Profiling527031 -Node: Invoking Gawk534431 -Node: Command Line535738 -Node: Options536523 -Ref: Options-Footnote-1549611 -Node: Other Arguments549636 -Node: AWKPATH Variable552317 -Ref: AWKPATH Variable-Footnote-1555092 -Node: Exit Status555352 -Node: Include Files556024 -Node: Obsolete559625 -Node: Undocumented560426 -Node: Known Bugs560688 -Node: Library Functions561290 -Ref: Library Functions-Footnote-1564271 -Node: Library Names564442 -Ref: Library Names-Footnote-1567915 -Ref: Library Names-Footnote-2568134 -Node: General Functions568220 -Node: Nextfile Function569283 -Node: Strtonum Function573647 -Node: Assert Function576588 -Node: Round Function579892 -Node: Cliff Random Function581432 -Node: Ordinal Functions582447 -Ref: Ordinal Functions-Footnote-1585507 -Node: Join Function585723 -Ref: Join Function-Footnote-1587485 -Node: Gettimeofday Function587685 -Node: Data File Management591396 -Node: Filetrans Function592028 -Node: Rewind Function595454 -Node: File Checking596900 -Node: Empty Files597930 -Node: Ignoring Assigns600155 -Node: Getopt Function601703 -Ref: Getopt Function-Footnote-1612985 -Node: Passwd Functions613188 -Ref: Passwd Functions-Footnote-1622166 -Node: Group Functions622254 -Node: Sample Programs630351 -Node: Running Examples631020 -Node: Clones631748 -Node: Cut Program632880 -Node: Egrep Program642639 -Ref: Egrep Program-Footnote-1650389 -Node: Id Program650499 -Node: Split Program654106 -Node: Tee Program657574 -Node: Uniq Program660317 -Node: Wc Program667684 -Ref: Wc Program-Footnote-1671928 -Node: Miscellaneous Programs672124 -Node: Dupword Program673244 -Node: Alarm Program675275 -Node: Translate Program679817 -Ref: Translate Program-Footnote-1684196 -Ref: Translate Program-Footnote-2684433 -Node: Labels Program684567 -Ref: Labels Program-Footnote-1687858 -Node: Word Sorting687942 -Node: History Sorting692289 -Node: Extract Program694127 -Node: Simple Sed701485 -Node: Igawk Program704542 -Ref: Igawk Program-Footnote-1719273 -Ref: Igawk Program-Footnote-2719474 -Node: Signature Program719612 -Node: Debugger720692 -Node: Debugging721568 -Node: Debugging Concepts721882 -Node: Debugging Terms723735 -Node: Awk Debugging726283 -Node: Sample dgawk session727175 -Node: dgawk invocation727667 -Node: Finding The Bug728851 -Node: List of Debugger Commands735366 -Node: Breakpoint Control736681 -Node: Dgawk Execution Control739891 -Node: Viewing And Changing Data743240 -Node: Dgawk Stack746536 -Node: Dgawk Info747997 -Node: Miscellaneous Dgawk Commands751935 -Node: Readline Support757651 -Node: Dgawk Limitations758467 -Node: Language History760639 -Node: V7/SVR3.1762016 -Node: SVR4764311 -Node: POSIX765756 -Node: BTL767468 -Node: POSIX/GNU769158 -Node: Contributors778822 -Node: Installation782431 -Node: Gawk Distribution783402 -Node: Getting783886 -Node: Extracting784712 -Node: Distribution contents786100 -Node: Unix Installation791173 -Node: Quick Installation791764 -Node: Additional Configuration Options793466 -Node: Configuration Philosophy795229 -Node: Non-Unix Installation797593 -Node: PC Installation798058 -Node: PC Binary Installation799364 -Node: PC Compiling801207 -Node: PC Dynamic805712 -Node: PC Using808075 -Node: Cygwin812623 -Node: MSYS813607 -Node: VMS Installation814113 -Node: VMS Compilation814717 -Node: VMS Installation Details816294 -Node: VMS Running817924 -Node: VMS POSIX819521 -Node: VMS Old Gawk820819 -Node: Unsupported821288 -Node: Atari Installation821750 -Node: Atari Compiling823037 -Node: Atari Using824926 -Node: BeOS Installation827773 -Node: Tandem Installation828918 -Node: Bugs830597 -Node: Other Versions834429 -Node: Notes839651 -Node: Compatibility Mode840343 -Node: Additions841126 -Node: Adding Code841876 -Node: New Ports847928 -Node: Dynamic Extensions852060 -Node: Internals853441 -Node: Plugin License863846 -Node: Sample Library864480 -Node: Internal File Description865144 -Node: Internal File Ops868839 -Ref: Internal File Ops-Footnote-1873715 -Node: Using Internal File Ops873863 -Node: Future Extensions875888 -Node: Basic Concepts879925 -Node: Basic High Level880682 -Ref: Basic High Level-Footnote-1884801 -Node: Basic Data Typing884995 -Node: Floating Point Issues889432 -Node: String Conversion Precision890515 -Ref: String Conversion Precision-Footnote-1892209 -Node: Unexpected Results892318 -Node: POSIX Floating Point Problems894144 -Ref: POSIX Floating Point Problems-Footnote-1897843 -Node: Glossary897881 -Node: Copying921649 -Node: GNU Free Documentation License959206 -Node: next-edition984350 -Node: unresolved984702 -Node: revision985202 -Node: consistency985625 -Node: Index988978 +Node: Foreword30310 +Node: Preface34626 +Ref: Preface-Footnote-137578 +Ref: Preface-Footnote-237684 +Node: History37916 +Node: Names40148 +Ref: Names-Footnote-141625 +Node: This Manual41697 +Ref: This Manual-Footnote-146595 +Node: Conventions46695 +Node: Manual History48754 +Ref: Manual History-Footnote-151932 +Ref: Manual History-Footnote-251973 +Node: How To Contribute52047 +Node: Acknowledgments53191 +Node: Getting Started57460 +Node: Running gawk59832 +Node: One-shot61018 +Node: Read Terminal62243 +Ref: Read Terminal-Footnote-163893 +Ref: Read Terminal-Footnote-264167 +Node: Long64338 +Node: Executable Scripts65714 +Ref: Executable Scripts-Footnote-167575 +Ref: Executable Scripts-Footnote-267677 +Node: Comments68128 +Node: Quoting70496 +Node: DOS Quoting75113 +Node: Sample Data Files75781 +Node: Very Simple78813 +Node: Two Rules83410 +Node: More Complex85557 +Ref: More Complex-Footnote-188487 +Node: Statements/Lines88567 +Ref: Statements/Lines-Footnote-192923 +Node: Other Features93188 +Node: When94057 +Node: Regexp96200 +Node: Regexp Usage97654 +Node: Escape Sequences99680 +Node: Regexp Operators105423 +Ref: Regexp Operators-Footnote-1112595 +Ref: Regexp Operators-Footnote-2112742 +Node: Character Lists112840 +Ref: table-char-classes114615 +Node: GNU Regexp Operators117240 +Node: Case-sensitivity120953 +Ref: Case-sensitivity-Footnote-1123908 +Ref: Case-sensitivity-Footnote-2124143 +Node: Leftmost Longest124251 +Node: Computed Regexps125452 +Node: Locales128869 +Node: Reading Files131959 +Node: Records133900 +Ref: Records-Footnote-1142466 +Node: Fields142503 +Ref: Fields-Footnote-1145535 +Node: Nonconstant Fields145621 +Node: Changing Fields147823 +Node: Field Separators153108 +Node: Default Field Splitting155737 +Node: Regexp Field Splitting156854 +Node: Single Character Fields160204 +Node: Command Line Field Separator161255 +Node: Field Splitting Summary164694 +Ref: Field Splitting Summary-Footnote-1167880 +Node: Constant Size167981 +Node: Splitting By Content172452 +Ref: Splitting By Content-Footnote-1176054 +Node: Multiple Line176094 +Ref: Multiple Line-Footnote-1181834 +Node: Getline182013 +Node: Plain Getline184241 +Node: Getline/Variable186330 +Node: Getline/File187471 +Node: Getline/Variable/File188793 +Ref: Getline/Variable/File-Footnote-1190392 +Node: Getline/Pipe190479 +Node: Getline/Variable/Pipe193027 +Node: Getline/Coprocess194134 +Node: Getline/Variable/Coprocess195377 +Node: Getline Notes196091 +Node: Getline Summary198033 +Ref: table-getline-variants198317 +Node: Command line directories199222 +Node: Printing199847 +Node: Print201478 +Node: Print Examples202815 +Node: Output Separators205599 +Node: OFMT207358 +Node: Printf208716 +Node: Basic Printf209622 +Node: Control Letters211159 +Node: Format Modifiers214971 +Node: Printf Examples220982 +Node: Redirection223697 +Node: Special Files230675 +Node: Special FD231208 +Ref: Special FD-Footnote-1234783 +Node: Special Network234857 +Node: Special Caveats235712 +Node: Close Files And Pipes236506 +Ref: Close Files And Pipes-Footnote-1243450 +Ref: Close Files And Pipes-Footnote-2243598 +Node: Expressions243748 +Node: Values244817 +Node: Constants245493 +Node: Scalar Constants246173 +Ref: Scalar Constants-Footnote-1247032 +Node: Nondecimal-numbers247214 +Node: Regexp Constants250273 +Node: Using Constant Regexps250748 +Node: Variables253753 +Node: Using Variables254408 +Node: Assignment Options256135 +Node: Conversion258016 +Ref: table-locale-affects263390 +Ref: Conversion-Footnote-1264014 +Node: All Operators264123 +Node: Arithmetic Ops264753 +Node: Concatenation267252 +Ref: Concatenation-Footnote-1270045 +Node: Assignment Ops270164 +Ref: table-assign-ops275152 +Node: Increment Ops276553 +Node: Truth Values and Conditions280031 +Node: Truth Values281114 +Node: Typing and Comparison282162 +Node: Variable Typing282951 +Ref: Variable Typing-Footnote-1286848 +Node: Comparison Operators286970 +Ref: table-relational-ops287380 +Node: POSIX String Comparison290929 +Ref: POSIX String Comparison-Footnote-1291886 +Node: Boolean Ops292024 +Ref: Boolean Ops-Footnote-1296102 +Node: Conditional Exp296193 +Node: Function Calls297925 +Node: Precedence301484 +Node: Patterns and Actions305137 +Node: Pattern Overview306191 +Node: Regexp Patterns307857 +Node: Expression Patterns308400 +Node: Ranges311974 +Node: BEGIN/END314940 +Node: Using BEGIN/END315690 +Ref: Using BEGIN/END-Footnote-1318421 +Node: I/O And BEGIN/END318535 +Node: Empty320804 +Node: BEGINFILE/ENDFILE321138 +Node: Using Shell Variables323963 +Node: Action Overview326242 +Node: Statements328599 +Node: If Statement330458 +Node: While Statement331957 +Node: Do Statement334001 +Node: For Statement335157 +Node: Switch Statement338309 +Node: Break Statement340406 +Node: Continue Statement342382 +Node: Next Statement344083 +Node: Nextfile Statement346465 +Node: Exit Statement348983 +Node: Built-in Variables351314 +Node: User-modified352409 +Ref: User-modified-Footnote-1360410 +Node: Auto-set360472 +Ref: Auto-set-Footnote-1369263 +Node: ARGC and ARGV369468 +Node: Arrays373227 +Node: Array Basics374798 +Node: Array Intro375509 +Node: Reference to Elements379827 +Node: Assigning Elements382097 +Node: Array Example382588 +Node: Scanning an Array384320 +Node: Delete386597 +Ref: Delete-Footnote-1388995 +Node: Numeric Array Subscripts389052 +Node: Uninitialized Subscripts391235 +Node: Multi-dimensional392863 +Node: Multi-scanning395954 +Node: Array Sorting397538 +Ref: Array Sorting-Footnote-1400736 +Node: Arrays of Arrays400930 +Node: Functions405038 +Node: Built-in405860 +Node: Calling Built-in406874 +Node: Numeric Functions408850 +Ref: Numeric Functions-Footnote-1412559 +Ref: Numeric Functions-Footnote-2412895 +Ref: Numeric Functions-Footnote-3412943 +Node: String Functions413212 +Ref: String Functions-Footnote-1435011 +Ref: String Functions-Footnote-2435140 +Ref: String Functions-Footnote-3435388 +Node: Gory Details435475 +Ref: table-sub-escapes437132 +Ref: table-posix-sub438446 +Ref: table-gensub-escapes439346 +Node: I/O Functions440517 +Ref: I/O Functions-Footnote-1447214 +Node: Time Functions447361 +Ref: Time Functions-Footnote-1458017 +Ref: Time Functions-Footnote-2458085 +Ref: Time Functions-Footnote-3458243 +Ref: Time Functions-Footnote-4458354 +Ref: Time Functions-Footnote-5458466 +Ref: Time Functions-Footnote-6458693 +Node: Bitwise Functions458959 +Ref: table-bitwise-ops459517 +Ref: Bitwise Functions-Footnote-1463677 +Node: I18N Functions463861 +Node: User-defined465491 +Node: Definition Syntax466295 +Ref: Definition Syntax-Footnote-1470925 +Node: Function Example470994 +Node: Function Caveats473588 +Node: Calling A Function474000 +Node: Variable Scope475089 +Node: Pass By Value/Reference477017 +Node: Return Statement480457 +Node: Dynamic Typing483399 +Node: Indirect Calls484136 +Node: Internationalization493821 +Node: I18N and L10N495247 +Node: Explaining gettext495931 +Ref: Explaining gettext-Footnote-1500991 +Ref: Explaining gettext-Footnote-2501174 +Node: Programmer i18n501339 +Node: Translator i18n505600 +Node: String Extraction506391 +Ref: String Extraction-Footnote-1507350 +Node: Printf Ordering507436 +Ref: Printf Ordering-Footnote-1510218 +Node: I18N Portability510282 +Ref: I18N Portability-Footnote-1512729 +Node: I18N Example512792 +Ref: I18N Example-Footnote-1515425 +Node: Gawk I18N515497 +Node: Advanced Features516064 +Node: Nondecimal Data517379 +Node: Two-way I/O518940 +Ref: Two-way I/O-Footnote-1524354 +Node: TCP/IP Networking524431 +Node: Profiling527284 +Node: Invoking Gawk534684 +Node: Command Line535935 +Node: Options536720 +Ref: Options-Footnote-1549912 +Node: Other Arguments549937 +Node: Naming Standard Input552602 +Node: Environment Variables553568 +Node: AWKPATH Variable553984 +Ref: AWKPATH Variable-Footnote-1556723 +Node: Other Environment Variables556983 +Node: Exit Status559333 +Node: Include Files560010 +Node: Obsolete563374 +Node: Undocumented564062 +Node: Library Functions564305 +Ref: Library Functions-Footnote-1567286 +Node: Library Names567457 +Ref: Library Names-Footnote-1570930 +Ref: Library Names-Footnote-2571149 +Node: General Functions571235 +Node: Nextfile Function572298 +Node: Strtonum Function576662 +Node: Assert Function579603 +Node: Round Function582907 +Node: Cliff Random Function584447 +Node: Ordinal Functions585462 +Ref: Ordinal Functions-Footnote-1588522 +Node: Join Function588738 +Ref: Join Function-Footnote-1590500 +Node: Gettimeofday Function590700 +Node: Data File Management594411 +Node: Filetrans Function595043 +Node: Rewind Function598469 +Node: File Checking599915 +Node: Empty Files600945 +Node: Ignoring Assigns603170 +Node: Getopt Function604718 +Ref: Getopt Function-Footnote-1616000 +Node: Passwd Functions616203 +Ref: Passwd Functions-Footnote-1625181 +Node: Group Functions625269 +Node: Sample Programs633366 +Node: Running Examples634035 +Node: Clones634763 +Node: Cut Program635895 +Node: Egrep Program645654 +Ref: Egrep Program-Footnote-1653404 +Node: Id Program653514 +Node: Split Program657121 +Node: Tee Program660589 +Node: Uniq Program663332 +Node: Wc Program670699 +Ref: Wc Program-Footnote-1674943 +Node: Miscellaneous Programs675139 +Node: Dupword Program676259 +Node: Alarm Program678290 +Node: Translate Program682832 +Ref: Translate Program-Footnote-1687211 +Ref: Translate Program-Footnote-2687448 +Node: Labels Program687582 +Ref: Labels Program-Footnote-1690873 +Node: Word Sorting690957 +Node: History Sorting695304 +Node: Extract Program697142 +Node: Simple Sed704500 +Node: Igawk Program707557 +Ref: Igawk Program-Footnote-1722288 +Ref: Igawk Program-Footnote-2722489 +Node: Signature Program722627 +Node: Debugger723707 +Node: Debugging724583 +Node: Debugging Concepts724897 +Node: Debugging Terms726750 +Node: Awk Debugging729298 +Node: Sample dgawk session730190 +Node: dgawk invocation730682 +Node: Finding The Bug731866 +Node: List of Debugger Commands738381 +Node: Breakpoint Control739696 +Node: Dgawk Execution Control742906 +Node: Viewing And Changing Data746255 +Node: Dgawk Stack749551 +Node: Dgawk Info751012 +Node: Miscellaneous Dgawk Commands754950 +Node: Readline Support760666 +Node: Dgawk Limitations761482 +Node: Language History763654 +Node: V7/SVR3.1765031 +Node: SVR4767326 +Node: POSIX768771 +Node: BTL770483 +Node: POSIX/GNU772173 +Node: Contributors781837 +Node: Installation785446 +Node: Gawk Distribution786417 +Node: Getting786901 +Node: Extracting787727 +Node: Distribution contents789115 +Node: Unix Installation794188 +Node: Quick Installation794779 +Node: Additional Configuration Options796481 +Node: Configuration Philosophy798244 +Node: Non-Unix Installation800608 +Node: PC Installation801073 +Node: PC Binary Installation802379 +Node: PC Compiling804222 +Node: PC Dynamic808727 +Node: PC Using811090 +Node: Cygwin815638 +Node: MSYS816622 +Node: VMS Installation817128 +Node: VMS Compilation817732 +Node: VMS Installation Details819309 +Node: VMS Running820939 +Node: VMS POSIX822536 +Node: VMS Old Gawk823834 +Node: Unsupported824303 +Node: Atari Installation824765 +Node: Atari Compiling826052 +Node: Atari Using827941 +Node: BeOS Installation830788 +Node: Tandem Installation831933 +Node: Bugs833612 +Node: Other Versions837444 +Node: Notes842666 +Node: Compatibility Mode843358 +Node: Additions844141 +Node: Adding Code844891 +Node: New Ports850943 +Node: Dynamic Extensions855075 +Node: Internals856456 +Node: Plugin License866861 +Node: Sample Library867495 +Node: Internal File Description868159 +Node: Internal File Ops871854 +Ref: Internal File Ops-Footnote-1876730 +Node: Using Internal File Ops876878 +Node: Future Extensions878903 +Node: Basic Concepts882940 +Node: Basic High Level883697 +Ref: Basic High Level-Footnote-1887816 +Node: Basic Data Typing888010 +Node: Floating Point Issues892447 +Node: String Conversion Precision893530 +Ref: String Conversion Precision-Footnote-1895224 +Node: Unexpected Results895333 +Node: POSIX Floating Point Problems897159 +Ref: POSIX Floating Point Problems-Footnote-1900858 +Node: Glossary900896 +Node: Copying924664 +Node: GNU Free Documentation License962221 +Node: next-edition987365 +Node: unresolved987717 +Node: revision988217 +Node: consistency988640 +Node: Index991993 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 42560264..542577e0 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -3,6 +3,9 @@ TODO: Globally add () after built in and awk function names. Go through CAUTION, NOTE, @strong, @quotation, etc. + Document common extensions with COMMONEXT marking & index entry. + Pick a reasonable name for BWK awk and use it everywhere (search + for Bell Laboratories) DONE: @end ignore @c %**start of header (This is for running Texinfo on a region.) @@ -72,6 +75,15 @@ DONE: @set DARKCORNER (d.c.) @set COMMONEXT (c.e.) @end ifdocbook +@ifplaintext +@set DOCUMENT book +@set CHAPTER chapter +@set APPENDIX appendix +@set SECTION section +@set SUBSECTION subsection +@set DARKCORNER (d.c.) +@set COMMONEXT (c.e.) +@end ifplaintext @c some special symbols @iftex @@ -528,13 +540,16 @@ particular records in a file and perform operations upon them. * Command Line:: How to run @command{awk}. * Options:: Command-line options and their meanings. * Other Arguments:: Input file names and variable assignments. +* Naming Standard Input:: How to specify standard input with + other files. +* Environment Variables:: The environment variables @command{gawk} uses. * AWKPATH Variable:: Searching directories for @command{awk} programs. +* Other Environment Variables:: The environment variables. * Exit Status:: @command{gawk}'s exit status. * Include Files:: Including other files into your program. * Obsolete:: Obsolete Options and/or features. * Undocumented:: Undocumented Options and Features. -* Known Bugs:: Known Bugs in @command{gawk}. * Library Names:: How to best name private global variables in library functions. * General Functions:: Functions that are of general use. @@ -11062,11 +11077,13 @@ for an example that does this. @cindex dark corner, @code{exit} statement If an argument is supplied to @code{exit}, its value is used as the exit status code for the @command{awk} process. If no argument is supplied, -@code{exit} returns status zero (success). In the case where an argument +@code{exit} causes @command{awk} to return a ``success'' status. +In the case where an argument is supplied to a first @code{exit} statement, and then @code{exit} is called a second time from an @code{END} rule with no argument, @command{awk} uses the previously supplied exit value. @value{DARKCORNER} +@xref{Exit Status}, for more information. @cindex programming conventions, @code{exit} statement For example, suppose an error condition occurs that is difficult or @@ -17530,8 +17547,6 @@ When called this way, @command{gawk} ``pretty prints'' the program into @c ENDOFRANGE awkp @c ENDOFRANGE proawk - - @node Invoking Gawk @chapter Running @command{awk} and @command{gawk} @@ -17541,24 +17556,21 @@ and @command{gawk}-specific command-line options, and what @command{gawk} do with non-option arguments. It then proceeds to cover how @command{gawk} searches for source files, obsolete options and/or features, and known bugs in @command{gawk}. -This @value{CHAPTER} rounds out the discussion of @command{awk} -as a program and as a language. -While a number of the options and features described here were -discussed in passing earlier in the book, this @value{CHAPTER} provides the -full details. +Many of the options and features described here are discussed in +more detail later in the @value{DOCUMENT}; feel free to skip over +things in this @value{CHAPTER} that don't interest you right now. @menu * Command Line:: How to run @command{awk}. * Options:: Command-line options and their meanings. * Other Arguments:: Input file names and variable assignments. -* AWKPATH Variable:: Searching directories for @command{awk} - programs. +* Naming Standard Input:: How to specify standard input with other files. +* Environment Variables:: The environment variables @command{gawk} uses. * Exit Status:: @command{gawk}'s exit status. * Include Files:: Including other files into your program. * Obsolete:: Obsolete Options and/or features. * Undocumented:: Undocumented Options and Features. -* Known Bugs:: Known Bugs in @command{gawk}. @end menu @node Command Line @@ -17626,7 +17638,7 @@ Each long option for @command{gawk} has a corresponding POSIX-style option. The long and short options are interchangeable in all contexts. -The options and their meanings are as follows: +The following list describes options mandated by the POSIX standard: @table @code @item -F @var{fs} @@ -17634,7 +17646,7 @@ The options and their meanings are as follows: @cindex @code{-F} option @cindex @code{--field-separator} option @cindex @code{FS} variable, @code{--field-separator} option and -Sets the @code{FS} variable to @var{fs} +Set the @code{FS} variable to @var{fs} (@pxref{Field Separators}). @item -f @var{source-file} @@ -17642,15 +17654,18 @@ Sets the @code{FS} variable to @var{fs} @cindex @code{-f} option @cindex @code{--file} option @cindex @command{awk} programs, location of -Indicates that the @command{awk} program is to be found in @var{source-file} +Read @command{awk} program source from @var{source-file} instead of in the first non-option argument. +This option may be given multiple times; the @command{awk} +program consists of the concatenation the contents of +each specified @var{source-file}. @item -v @var{var}=@var{val} @itemx --assign @var{var}=@var{val} @cindex @code{-v} option @cindex @code{--assign} option @cindex variables, setting -Sets the variable @var{var} to the value @var{val} @emph{before} +Set the variable @var{var} to the value @var{val} @emph{before} execution of the program begins. Such variable values are available inside the @code{BEGIN} rule (@pxref{Other Arguments}). @@ -17671,7 +17686,7 @@ predefined value you may have given. @itemx -mr @var{N} @cindex @code{-mf}/@code{-mr} options @cindex memory, setting limits -Sets various memory limits to the value @var{N}. The @samp{f} flag sets +Set various memory limits to the value @var{N}. The @samp{f} flag sets the maximum number of fields and the @samp{r} flag sets the maximum record size. These two flags and the @option{-m} option are from the Bell Laboratories research version of Unix @command{awk}. They are provided @@ -17683,8 +17698,9 @@ it continues to accept them to avoid breaking old programs.) @item -W @var{gawk-opt} @cindex @code{-W} option -Following the POSIX standard, implementation-specific -options are supplied as arguments to the @option{-W} option. These options +Provide an implementation-specific option. +This is the POSIX convention for providing implementation-specific options. +These options also have corresponding GNU-style long options. Note that the long options may be abbreviated, as long as the abbreviations remain unique. @@ -17693,7 +17709,7 @@ The full list of @command{gawk}-specific options is provided next. @item -- @cindex command line, options, end of @cindex options, command-line, end of -Signals the end of the command-line options. The following arguments +Signal the end of the command-line options. The following arguments are not treated as options even if they begin with @samp{-}. This interpretation of @option{--} follows the POSIX argument parsing conventions. @@ -17703,11 +17719,12 @@ conventions. This is useful if you have @value{FN}s that start with @samp{-}, or in shell scripts, if you have @value{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}. @end table @c ENDOFRANGE gnulo @c ENDOFRANGE longo -The previous list described options mandated by the POSIX standard. The following list describes @command{gawk}-specific options: @table @code @@ -17715,12 +17732,12 @@ The following list describes @command{gawk}-specific options: @itemx --characters-as-bytes @cindex @code{-b} option @cindex @code{--characters-as-bytes} option -Causes @command{gawk} to treat all input data as single-byte characters. +Cause @command{gawk} to treat all input data as single-byte characters. Normally, @command{gawk} follows the POSIX standard and attempts to process its input data according to the current locale. This can often involve -converting multi-byte characters into wide characters (internally), and +converting multibyte characters into wide characters (internally), and can lead to problems or confusion if the input data does not contain valid -multi-byte characters. This option is an easy way to tell @command{gawk}: +multibyte characters. This option is an easy way to tell @command{gawk}: ``hands off my data!''. @item -c @@ -17728,10 +17745,9 @@ multi-byte characters. This option is an easy way to tell @command{gawk}: @cindex @code{--c} option @cindex @code{--traditional} option @cindex compatibility mode (@command{gawk}), specifying -Specifies @dfn{compatibility mode}, in which the GNU extensions to +Specify @dfn{compatibility mode}, in which the GNU extensions to the @command{awk} language are disabled, so that @command{gawk} behaves just like the Bell Laboratories research version of Unix @command{awk}. -@option{--traditional} is the preferred form of this option. @xref{POSIX/GNU}, which summarizes the extensions. Also see @ref{Compatibility Mode}. @@ -17750,8 +17766,8 @@ Print the short version of the General Public License and then exit. @cindex @code{awkvars.out} file @cindex files, @code{awkvars.out} @cindex variables, global, printing list of -Prints a sorted list of global variables, their types, and final values -to @var{file}. If no @var{file} is provided, @command{gawk} prints this +Print a sorted list of global variables, their types, and final values +to @var{file}. If no @var{file} is provided, print this list to the file named @file{awkvars.out} in the current directory. @cindex troubleshooting, typographical errors@comma{} global variables @@ -17768,9 +17784,9 @@ names like @code{i}, @code{j}, etc.) @cindex @code{-e} option @cindex @code{--source} option @cindex source code, mixing -Allows you to mix source code in files with source +Provide program source code in the @var{program-text}. +This option allows you to mix source code in files with source code that you enter on the command line. -Program source code is taken from the @var{program-text}. This is particularly useful when you have library functions that you want to use from your command-line programs (@pxref{AWKPATH Variable}). @@ -17781,16 +17797,23 @@ programs (@pxref{AWKPATH Variable}). @cindex @code{--exec} option @cindex @command{awk} programs, location of @cindex CGI, @command{awk} scripts for -Similar to @option{-f}, reads @command{awk} program text from @var{file}. -There are two differences. The first is that this option also terminates option processing; anything +Similar to @option{-f}, read @command{awk} program text from @var{file}. +There are two differences from @option{-f}: + +@itemize @bullet +@item +This option terminates option processing; anything else on the command line is passed on directly to the @command{awk} program. -The second is that command line variable assignments of the form + +@item +Command-line variable assignments of the form @samp{@var{var}=@var{value}} are disallowed. +@end itemize This option is particularly necessary for World Wide Web CGI applications that pass arguments through the URL; using this option prevents a malicious -(or other) user from passing in options, assignments, or @command{awk} source code (via -@option{--source}) to the CGI application. This option should be used +(or other) user from passing in options, assignments, or @command{awk} source +code (via @option{--source}) to the CGI application. This option should be used with @samp{#!} scripts (@pxref{Executable Scripts}), like so: @example @@ -17805,8 +17828,8 @@ with @samp{#!} scripts (@pxref{Executable Scripts}), like so: @cindex @code{--gen-pot} option @cindex portable object files, generating @cindex files, portable object, generating -Analyzes the source program and -generates a GNU @code{gettext} Portable Object file on standard +Analyze the source program and +generate a GNU @code{gettext} Portable Object Template file on standard output for all string constants that have been marked for translation. @xref{Internationalization}, for information about this option. @@ -17818,7 +17841,7 @@ for information about this option. @cindex GNU long options, printing list of @cindex options, printing list of @cindex printing, list of options -Prints a ``usage'' message summarizing the short and long style options +Print a ``usage'' message summarizing the short and long style options that @command{gawk} accepts and then exit. @item -L @r{[}value@r{]} @@ -17827,7 +17850,7 @@ that @command{gawk} accepts and then exit. @cindex @code{--lint} option @cindex lint checking, issuing warnings @cindex warnings, issuing -Warns about constructs that are dubious or nonportable to +Warn about constructs that are dubious or nonportable to other @command{awk} implementations. Some warnings are issued when @command{gawk} first reads your program. Others are issued at runtime, as your program executes. @@ -17862,14 +17885,14 @@ Use with care. @itemx --use-lc-numeric @cindex @code{-N} option @cindex @code{--use-lc-numeric} option -This option forces the use of the locale's decimal point character +Force the use of the locale's decimal point character when parsing numeric input data (@pxref{Locales}). @item -O @itemx --optimize @cindex @code{--optimize} option @cindex @code{-O} option -Enables some optimizations on the internal representation of the program. +Enable some optimizations on the internal representation of the program. At the moment this includes just simple constant folding. The @command{gawk} maintainer hopes to add more optimizations over time. @@ -17895,7 +17918,7 @@ call counts for each function. @cindex @code{--posix} option @cindex POSIX mode @cindex @command{gawk}, extensions@comma{} disabling -Operates in strict POSIX mode. This disables all @command{gawk} +Operate in strict POSIX mode. This disables all @command{gawk} extensions (just like @option{--traditional}) and adds the following additional restrictions: @@ -17966,11 +17989,11 @@ also issues a warning if both options are supplied. @cindex @code{-r} option @cindex @code{--re-interval} option @cindex regular expressions, interval expressions and -Allows interval expressions +Allow interval expressions (@pxref{Regexp Operators}) in regexps. -This is now the default behavior for @command{gawk}. -Nevertheless, this option remains for both backward compatibility, +This is now @command{gawk}'s default behavior. +Nevertheless, this option remains both for backward compatibility, and for use in combination with the @option{--traditional} option. @item -S @@ -17978,19 +18001,19 @@ and for use in combination with the @option{--traditional} option. @cindex @code{-S} option @cindex @code{--sandbox} option @cindex sandbox mode -In sandbox mode, the @code{system()} function, +Disable the @code{system()} function, input redirections with @code{getline}, -output redirections with @code{print} and @code{printf} -and dynamic extensions are disabled. +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 then the specified input data file). +can't access your system (other than the specified input data file). @item -t @itemx --lint-old @cindex @code{--L} option @cindex @code{--lint-old} option -Warns about constructs that are not available in the original version of +Warn about constructs that are not available in the original version of @command{awk} from Version 7 Unix (@pxref{V7/SVR3.1}). @@ -17999,7 +18022,7 @@ Warns about constructs that are not available in the original version of @cindex @code{-V} option @cindex @code{--version} option @cindex @command{gawk}, versions of, information about@comma{} printing -Prints version information for this particular copy of @command{gawk}. +Print version information for this particular copy of @command{gawk}. This allows you to determine if your copy of @command{gawk} is up to date with respect to whatever the Free Software Foundation is currently distributing. @@ -18029,7 +18052,8 @@ of having to be included into each individual program. @ref{Definition Syntax}, function names must be unique.) -Library functions can still be used, even if the program is entered at the terminal, +With standard @command{awk}, library functions can still be used, even +if the program is entered at the terminal, by specifying @samp{-f /dev/tty}. After typing your program, type @kbd{@value{CTL}-d} (the end-of-file character) to terminate it. (You may also use @samp{-f -} to read program source from the standard @@ -18094,7 +18118,7 @@ input files to be processed in the order specified. However, an argument that has the form @code{@var{var}=@var{value}}, assigns the value @var{value} to the variable @var{var}---it does not specify a file at all. -(This was discussed earlier in +(See also @ref{Assignment Options}.) @cindex @code{ARGIND} variable, command-line arguments @@ -18152,8 +18176,47 @@ Given the variable assignment feature, the @option{-F} option for setting the value of @code{FS} is not strictly necessary. It remains for historical compatibility. +@node Naming Standard Input +@section Naming Standard Input + +Often, you may wish to read standard input together with other files. +For example, you may wish to read one file, read standard input coming +from a pipe, and then read another file. + +The way to name the standard input, with all versions of @command{awk}, +is to use a single, standalone minus sign or dash, @samp{-}. For example: + +@example +@var{some_command} | awk -f myprog.awk file1 - file2 +@end example + +@noindent +Here, @command{awk} first reads @file{file1}, then it reads +the output of @var{some_command}, and finally it reads +@file{file2}. + +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 +@value{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. + +@node Environment Variables +@section The Environment Variables @command{gawk} Uses + +A number of environment variables influence how @command{gawk} +behaves. + +@menu +* AWKPATH Variable:: Searching directories for @command{awk} programs. +* Other Environment Variables:: The environment variables. +@end menu + @node AWKPATH Variable -@section The @env{AWKPATH} Environment Variable +@subsection The @env{AWKPATH} Environment Variable @cindex @env{AWKPATH} environment variable @cindex directories, searching @cindex search paths, for source files @@ -18197,18 +18260,23 @@ This is true for both @option{--traditional} and @option{--posix}. @xref{Options}. @quotation NOTE -If you want files in the current directory to be found, -you must include the current directory in the path, either by including -@file{.} explicitly in the path or by writing a null entry in the +To include +the current directory in the path, either place +@file{.} explicitly in the path or write a null entry in the path. (A null entry is indicated by starting or ending the path with a -colon or by placing two colons next to each other (@samp{::}).) If the -current directory is not included in the path, then files cannot be -found in the current directory. This path search mechanism is identical +colon or by placing two colons next to each other (@samp{::}).) +This path search mechanism is similar to the shell's. @c someday, @cite{The Bourne Again Shell}.... + +However, @command{gawk} always looks in the current directory before +before searching @env{AWKPATH}, so there is no real reason to include +the current directory in the search path. +@c Prior to 4.0, gawk searched the current directory after the +@c path search, but it's not worth documenting it. @end quotation -Starting with @value{PVERSION} 3.0, if @env{AWKPATH} is not defined in the +If @env{AWKPATH} is not defined in the environment, @command{gawk} places its default search path into @code{ENVIRON["AWKPATH"]}. This makes it easy to determine the actual search path that @command{gawk} will use @@ -18220,6 +18288,68 @@ sense: the @env{AWKPATH} environment variable is used to find the program source files. Once your program is running, all the files have been found, and @command{gawk} no longer needs to use @env{AWKPATH}. +@node Other Environment Variables +@subsection Other Environment Variables + +A number of other environment variables affect @command{gawk}'s +behavior, but they are more specialized. Those in the following +list are meant to be used by regular users. + +@table @env +@item POSIXLY_CORRECT +If this variable exists, @command{gawk} switches to POSIX compatibility +mode, disabling all traditional and GNU extensions. +@xref{Options}. + +@item GAWK_SOCK_RETRIES +Controls the number of time @command{gawk} will attempt to +retry a two-way TCP/IP (socket) connection before giving up. +@xref{TCP/IP Networking}. + +@item GAWK_MSEC_SLEEP +Specifies the interval between connection retries, +in milliseconds. On systems that do not support +the @code{usleep()} system call, +the value is rounded up to an integral number of seconds. +@end table + +The environment variables in the following table are meant +for use by the @command{gawk} developers for testing and tuning. +They are subject to change. The variables are: + +@table @env +@item AVG_CHAIN_MAX +The average number of items @command{gawk} will maintain on a +hash chain for managing arrays. + +@item AWK_HASH +If this variable exists with a value of @samp{gst}, @command{gawk} +will switch to using the hash function from GNU Smalltalk for +managing arrays. +This function may be marginally faster than the standard function. + +@item AWKREADFUNC +If this variable exists, @command{gawk} switches to reading source +files one line at a time, instead of reading in blocks. This exists +for debugging problems on filesystems on non-POSIX operating systems +where I/O is performed in records, not in blocks. + +@item GAWK_NO_DFA +If this variable exists, @command{gawk} does not use the DFA regexp matcher +for ``does it match'' kinds of tests. This can cause @command{gawk} +to be slower. Its purpose is to help isolate differences between the +two regexp matchers that @command{gawk} uses internally. (There aren't +supposed to be differences, but occasionally theory and practice don't match up.) + +@item GAWK_STACKSIZE +This specifies the amount by which @command{gawk} should grow its +internal evaluation stack, when needed. + +@item TIDYMEM +If this variable exists, @command{gawk} uses the @code{mtrace()} library +calls from GNU LIBC to help track down possible memory leaks. +@end table + @node Exit Status @section @command{gawk}'s Exit Status @@ -18247,20 +18377,18 @@ to @code{EXIT_FAILURE}. @strong{FIXME:} This section still needs some editing. -Beginning with version @strong{FIXME:} 3.1.8-bc of @command{gawk}, the -@samp{@@include} keyword can be used to read external source @command{awk} -files. That gives the ability to split huge @command{awk} source files -into smaller and manageable files and also to reuse common @command{awk} +The @samp{@@include} keyword can be used to read external source @command{awk} +files. That gives the ability to split large @command{awk} source files +into smaller, more manageable pieces, and also lets you reuse common @command{awk} code from various @command{awk} scripts. In other words, you can group -together @command{awk} functions, used to carry out some sort of tasks, +together @command{awk} functions, used to carry out specific tasks, in external files. These files can be used just like function libraries, using the @samp{@@include} keyword in conjuction with the @code{AWKPATH} environment variable. Let's see an example to demonstrate file inclusion in @command{gawk}. -To do so, we'll use two (trivial) @command{awk} scripts, namely the -@file{test1} and @file{test2} @command{gawk} scripts. Here follows the -@file{test1} @command{gawk} script file: +To do so, we'll use two (trivial) @command{awk} scripts, namely +@file{test1} and @file{test2}. Here is the @file{test1} script: @example BEGIN @{ @@ -18269,7 +18397,7 @@ BEGIN @{ @end example @noindent -and the @file{test2} file: +and here is @file{test2}: @example @@include "test1" @@ -18278,8 +18406,8 @@ BEGIN @{ @} @end example -Running @command{gawk} with the @file{test2} -script you'll get the following result: +Running @command{gawk} with @file{test2} +produces the following result: @example $ @kbd{gawk -f test2} @@ -18290,8 +18418,8 @@ $ @kbd{gawk -f test2} @code{gawk} runs the @file{test2} script where @file{test1} has been included in the source of @file{test2} by means of the @samp{@@include} keyword. So, to include external @command{awk} source files you just -use @samp{@@include} followed by the name of the file to be included in -double quotes. +use @samp{@@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 @value{FN} cannot @@ -18334,29 +18462,28 @@ or @noindent are valid. The @code{AWKPATH} environment variable can be of great -value in @samp{@@include} constructs. The same rules dominating the use -of @code{AWKPATH} variable in command line file searches are valid in -@samp{@@include} constructs too. That can be prooved very helpful in +value when using @samp{@@include}. The same rules for the use +of the @code{AWKPATH} variable in command line file searches apply to +@samp{@@include} also. This is very helpful in constructing @command{gawk} function libraries. You can edit huge -scripts containing usefull @command{gawk} libraries and put those +scripts containing useful @command{gawk} libraries and put those files in a special directory. You can then include those ``libraries'' -using either the full pathnames of the files or by setting accordingly -the @code{AWKPATH} environment variable and then use @samp{@@include} +using either the full pathnames of the files or by setting +the @code{AWKPATH} environment variable accordingly and then using @samp{@@include} with just the name part of the full file pathname. Of course you can have more than one directory to keep library files; the more complex -the working enviroment is, the more directories you need to organize +the working enviroment is, the more directories you may need to organize the files to be included. -The whole stuff of file inclusion can, of course, be carried out in the -command line, using as many @option{-f} options as required with the -files to be included as arguments, but the @samp{@@include} keyword +Given the ability to specify multiple @option{-f} options, the +@samp{@@include} mechanism is not strictly necessary. +However, the @samp{@@include} keyword can help you in constructing self-contained @command{gawk} programs, thus reducing the need of writing complex and tedious command lines. -@code{AWKPATH} is also used by the @samp{@@include} mechanism, that is -the files to be included will be seeked in the directories specified. -Keep in mind, however, that the current directory is been searched first, -either it's listed in the @code{AWKPATH} string or not. +As mentioned in @ref{AWKPATH Variable}, the current directory is always +search first for source files, before searching in @env{AWKPATH}, +and this also applies to files named with @samp{@@include}. @node Obsolete @section Obsolete Options and/or Features @@ -18372,27 +18499,11 @@ they will @emph{not} be in the next release). @c update this section for each release! -@ignore -@cindex @code{next file} statement, deprecated -@cindex @code{nextfile} statement, @code{next file} statement and -@end ignore -For @value{PVERSION} @value{VERSION} of @command{gawk}, there are no -deprecated command-line options -@c or other deprecated features -from the previous version of @command{gawk}. -@ignore -The use of @samp{next file} (two words) for @code{nextfile} was deprecated -in @command{gawk} 3.0 but still worked. Starting with @value{PVERSION} 3.1, the -two-word usage is no longer accepted. -@end ignore - -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 @value{PVERSION} 3.2, they are no longer interpreted specially -by @command{gawk}. -(Use @code{PROCINFO} instead; see -@ref{Auto-set}.) +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 @value{PVERSION} 4.0, they are no longer +interpreted specially by @command{gawk}. (Use @code{PROCINFO} instead; +see @ref{Auto-set}.) @ignore This @value{SECTION} @@ -18467,43 +18578,8 @@ Similarly, you may use @code{print} or @code{printf} statements in the @var{init} and @var{increment} parts of a @code{for} loop. This is another long-undocumented ``feature'' of Unix @code{awk}. -If the environment variable @env{WHINY_USERS} exists -when @command{gawk} is run, -then the associative @code{for} loop will go through the array -indices in sorted order. -The comparison used for sorting is simple string comparison; -any non-English or non-ASCII locales are not taken into account. -@code{IGNORECASE} does not affect the comparison either. - -In addition, if @env{WHINY_USERS} is set, the profiled version of a -program generated by @option{--profile} will print all 8-bit characters -verbatim, instead of using the octal equivalent. - @end ignore -@node Known Bugs -@section Known Bugs in @command{gawk} -@cindex @command{gawk}, debugging -@cindex debugging @command{gawk} -@cindex troubleshooting, @command{gawk} - -@itemize @bullet -@cindex troubleshooting, @code{-F} option -@cindex @code{-F} option, troubleshooting -@cindex @code{FS} variable, changing value of -@item -The @option{-F} option for changing the value of @code{FS} -(@pxref{Options}) -is not necessary given the command-line variable -assignment feature; it remains only for backward compatibility. - -@item -Syntactically invalid single-character programs tend to overflow -the parse stack, generating a rather unhelpful message. Such programs -are surprisingly difficult to diagnose in the completely general case, -and the effort to do so really is not worth it. -@end itemize - @ignore @c Try this @iftex @@ -1056,32 +1056,6 @@ update_FNR() } } -/* comp_func --- array index comparison function for qsort */ - -int -comp_func(const void *p1, const void *p2) -{ - size_t len1, len2; - const char *str1, *str2; - const NODE *t1, *t2; - int cmp1; - - t1 = *((const NODE *const *) p1); - t2 = *((const NODE *const *) p2); - - len1 = t1->ahname_len; - str1 = t1->ahname_str; - - len2 = t2->ahname_len; - str2 = t2->ahname_str; - - /* Array indexes are strings, compare as such, always! */ - cmp1 = memcmp(str1, str2, len1 < len2 ? len1 : len2); - /* if prefixes are equal, size matters */ - return (cmp1 != 0 ? cmp1 : - len1 < len2 ? -1 : (len1 > len2)); -} - NODE *frame_ptr; /* current frame */ STACK_ITEM *stack_ptr = NULL; @@ -1105,7 +1079,8 @@ grow_stack() { if (stack_ptr == NULL) { char *val; - if ((val = getenv("STACKSIZE")) != NULL) { + + if ((val = getenv("GAWK_STACKSIZE")) != NULL) { if (isdigit(*val)) { unsigned long n = 0; for (; *val && isdigit(*val); val++) @@ -2279,7 +2254,6 @@ post: NODE *array; size_t num_elems = 0; size_t i, j; - int sort_indices = whiny_users; /* get the array */ array = POP_ARRAY(); @@ -2303,8 +2277,6 @@ post: } } - if (sort_indices) - qsort(list, num_elems, sizeof(NODE *), comp_func); /* shazzam! */ list[num_elems] = array; /* actual array for use in * lint warning in Op_arrayfor_incr */ @@ -161,7 +161,6 @@ int do_optimize = TRUE; /* apply default optimizations */ int do_binary = FALSE; /* hands off my data! */ int do_sandbox = FALSE; /* sandbox mode - disable 'system' function & redirections */ -int whiny_users = FALSE; /* do things that whiny users want */ int use_lc_numeric = FALSE; /* obey locale for decimal point */ #ifdef MBS_SUPPORT int gawk_mb_cur_max; /* MB_CUR_MAX value, see comment in main() */ @@ -244,9 +243,6 @@ main(int argc, char **argv) if (getenv("TIDYMEM") != NULL) do_tidy_mem = TRUE; - if (getenv("WHINY_USERS") != NULL) - whiny_users = TRUE; - #ifdef HAVE_MCHECK_H #ifdef HAVE_MTRACE if (do_tidy_mem) @@ -710,7 +710,7 @@ str2wstr(NODE *n, size_t **ptr) */ if (is_valid_character(*sp)) { count = 1; - wc = *sp; + wc = btowc_cache[*sp]; } else count = mbrtowc(& wc, sp, src_count, & mbs); switch (count) { @@ -1188,11 +1188,7 @@ pp_string(const char *in_str, size_t len, int delim) chksize(8); /* total available space is 10 */ - /* print 'em as they came if for whiny users */ - if (whiny_users) - sprintf(obufout, "%c", *str & 0xff); - else - sprintf(obufout, "\\%03o", *str & 0xff); + sprintf(obufout, "\\%03o", *str & 0xff); len = strlen(obufout); ofre += (10 - len); /* adjust free space count */ obufout += len; |