From 4cea49ca8f817354ffd513c6ec808152e9299f21 Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Thu, 27 Feb 2014 23:29:44 +0200 Subject: Finish up doc fixes before releasing. --- doc/ChangeLog | 2 +- doc/gawk.info | 520 ++++++++++++++++++++++++++++---------------------------- doc/gawk.texi | 114 ++++++------- doc/gawktexi.in | 114 ++++++------- 4 files changed, 371 insertions(+), 379 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index 89164b93..ccbeaafd 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,7 +1,7 @@ 2014-02-27 Arnold D. Robbins * gawktexi.in: Lots of small fixes throughout, update of - profiling output. + profiling output. Finished fixes needed before a release. 2014-02-20 Arnold D. Robbins diff --git a/doc/gawk.info b/doc/gawk.info index eb7c52fb..73ab988f 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -19134,9 +19134,9 @@ File: gawk.info, Node: Translator i18n, Next: I18N Example, Prev: Programmer =============================== Once a program's translatable strings have been marked, they must be -extracted to create the initial `.po' file. As part of translation, it -is often helpful to rearrange the order in which arguments to `printf' -are output. +extracted to create the initial `.pot' file. As part of translation, +it is often helpful to rearrange the order in which arguments to +`printf' are output. `gawk''s `--gen-pot' command-line option extracts the messages and is discussed next. After that, `printf''s ability to rearrange the @@ -19209,7 +19209,7 @@ second: $ gawk 'BEGIN { > string = "Dont Panic" - > printf _"%2$d characters live in \"%1$s\"\n", + > printf "%2$d characters live in \"%1$s\"\n", > string, length(string) > }' -| 10 characters live in "Dont Panic" @@ -19234,7 +19234,7 @@ precision capability: `gawk' does not allow you to mix regular format specifiers and those with positional specifiers in the same string: - $ gawk 'BEGIN { printf _"%d %3$s\n", 1, 2, "hi" }' + $ gawk 'BEGIN { printf "%d %3$s\n", 1, 2, "hi" }' error--> gawk: cmd. line:1: fatal: must use `count$' on all formats or none NOTE: There are some pathological cases that `gawk' may fail to @@ -19596,7 +19596,7 @@ File: gawk.info, Node: Debugger Invocation, Next: Finding The Bug, Up: Sample 14.2.1 How to Start the Debugger -------------------------------- -Starting the debugger is almost exactly like running `awk', except you +Starting the debugger is almost exactly like running `gawk', except you have to pass an additional option `--debug' or the corresponding short option `-D'. The file(s) containing the program and any supporting code are given on the command line as arguments to one or more `-f' @@ -19709,8 +19709,8 @@ our test input above. Let's look at `NR': -| NR = number (2) So we can see that `are_equal()' was only called for the second record -of the file. Of course, this is because our program contained a rule -for `NR == 1': +of the file. Of course, this is because our program contains a rule for +`NR == 1': NR == 1 { last = $0 @@ -21525,7 +21525,7 @@ floating-point value to begin with: gawk -M 'BEGIN { n = 13.0; print n % 2.0 }' - Note that for the particular example above, there is likely best to + Note that for the particular example above, it is likely best to just use the following: gawk -M 'BEGIN { n = 13; print n % 2 }' @@ -22162,7 +22162,7 @@ Extension functions are described by the following record: `awk_value_t *(*function)(int num_actual_args, awk_value_t *result);' This is a pointer to the C function that provides the desired functionality. The function must fill in the result with either a - number or a string. `awk' takes ownership of any string memory. + number or a string. `gawk' takes ownership of any string memory. As mentioned earlier, string memory *must* come from `malloc()'. The `num_actual_args' argument tells the C function how many @@ -24057,7 +24057,7 @@ declarations and argument checking: awk_array_t array; int ret; struct stat sbuf; - /* default is stat() */ + /* default is lstat() */ int (*statfunc)(const char *path, struct stat *sbuf) = lstat; assert(result != NULL); @@ -24455,12 +24455,16 @@ File: gawk.info, Node: Extension Sample Fnmatch, Next: Extension Sample Fork, This extension provides an interface to the C library `fnmatch()' function. The usage is: - @load "fnmatch" +`@load "fnmatch"' + This is how you load the extension. - result = fnmatch(pattern, string, flags) +`result = fnmatch(pattern, string, flags)' + The return value is zero on success, `FNM_NOMATCH' if the string + did not match the pattern, or a different non-zero value if an + error occurred. - The `fnmatch' extension adds a single function named `fnmatch()', -one constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. + Besides the `fnmatch()' function, the `fnmatch' extension adds one +constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. The arguments to `fnmatch()' are: @@ -24474,10 +24478,6 @@ one constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. Either zero, or the bitwise OR of one or more of the flags in the `FNM' array. - The return value is zero on success, `FNM_NOMATCH' if the string did -not match the pattern, or a different non-zero value if an error -occurred. - The flags are follows: `FNM["CASEFOLD"]' Corresponds to the `FNM_CASEFOLD' flag as defined in @@ -24513,14 +24513,14 @@ The `fork' extension adds three functions, as follows. This is how you load the extension. `pid = fork()' - This function creates a new process. The return value is the zero - in the child and the process-id number of the child in the parent, - or -1 upon error. In the latter case, `ERRNO' indicates the - problem. In the child, `PROCINFO["pid"]' and `PROCINFO["ppid"]' - are updated to reflect the correct values. + This function creates a new process. The return value is zero in + the child and the process-ID number of the child in the parent, or + -1 upon error. In the latter case, `ERRNO' indicates the problem. + In the child, `PROCINFO["pid"]' and `PROCINFO["ppid"]' are updated + to reflect the correct values. `ret = waitpid(pid)' - This function takes a numeric argument, which is the process-id to + This function takes a numeric argument, which is the process-ID to wait for. The return value is that of the `waitpid()' system call. `ret = wait()' @@ -25610,7 +25610,7 @@ in POSIX `awk', in the order they were added to `gawk'. - The `-i' and `--include' options load `awk' library files. - - The `-l' and `--load' options for load compiled dynamic + - The `-l' and `--load' options load compiled dynamic extensions. - The `-M' and `--bignum' options enable MPFR. @@ -25624,8 +25624,9 @@ in POSIX `awk', in the order they were added to `gawk'. * Support for high precision arithmetic with MPFR. (*note Gawk and MPFR::). - * The `and()', `or()' and `xor()' functions allow any number of - arguments, with a minimum of two (*note Bitwise Functions::). + * The `and()', `or()' and `xor()' functions changed to allow any + number of arguments, with a minimum of two (*note Bitwise + Functions::). * The dynamic extension interface was completely redone (*note Dynamic Extensions::). @@ -25644,18 +25645,18 @@ available versions of `awk' (*note Other Versions::). Feature BWK Awk Mawk GNU Awk -------------------------------------------------------- `\x' Escape sequence X X X -`RS' as regexp X X `FS' as null string X X X `/dev/stdin' special file X X X `/dev/stdout' special file X X X `/dev/stderr' special file X X X -`**' and `**=' operators X X -`fflush()' function X X X -`func' keyword X X -`nextfile' statement X X X `delete' without subscript X X X +`fflush()' function X X X `length()' of an array X X X +`nextfile' statement X X X +`**' and `**=' operators X X +`func' keyword X X `BINMODE' variable X X +`RS' as regexp X X Time related functions X X (Technically speaking, as of late 2012, `fflush()', `delete ARRAY', @@ -25751,17 +25752,17 @@ of range expressions was _undefined_.(3) By using this lovely technical term, the standard gives license to implementors to implement ranges in whatever way they choose. The `gawk' maintainer chose to apply the pre-POSIX meaning in all cases: -the default regexp matching; with `--traditional', and with `--posix'; +the default regexp matching; with `--traditional' and with `--posix'; in all cases, `gawk' remains POSIX compliant. ---------- Footnotes ---------- (1) And Life was good. - (2) And thus was born the Campain for Rational Range Interpretation -(or RRI). A number of GNU tools, such as `grep' and `sed', have either -implemented this change, or will soon. Thanks to Karl Berry for -coining the phrase "Rational Range Interpretation." + (2) And thus was born the Campaign for Rational Range Interpretation +(or RRI). A number of GNU tools have either implemented this change, or +will soon. Thanks to Karl Berry for coining the phrase "Rational Range +Interpretation." (3) See the standard (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03_05) @@ -26243,8 +26244,8 @@ failure is not described there, please send in a bug report (*note Bugs::). Of course, once you've built `gawk', it is likely that you will wish -to install it. To do so, you need to run the command `make check', as -a user with the appropriate permissions. How to do this varies by +to install it. To do so, you need to run the command `make install', +as a user with the appropriate permissions. How to do this varies by system, but on many systems you can use the `sudo' command to do so. The command then becomes `sudo make install'. It is likely that you will be asked for your password, and you will have to have been set up @@ -26527,10 +26528,9 @@ File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Testing, Up: PC Inst B.3.1.4 Using `gawk' on PC Operating Systems ............................................ -With the exception of the Cygwin environment, the `|&' operator and -TCP/IP networking (*note TCP/IP Networking::) are not supported for -MS-DOS or MS-Windows. EMX (OS/2 only) does support at least the `|&' -operator. +Under MS-DOS and MS-Windows, the Cygwin and MinGW environments support +both the `|&' operator and TCP/IP networking (*note TCP/IP +Networking::). EMX (OS/2 only) supports at least the `|&' operator. The MS-DOS and MS-Windows versions of `gawk' search for program files as described in *note AWKPATH Variable::. However, semicolons @@ -26623,9 +26623,9 @@ B.3.1.5 Using `gawk' In The Cygwin Environment `gawk' can be built and used "out of the box" under MS-Windows if you are using the Cygwin environment (http://www.cygwin.com). This -environment provides an excellent simulation of Unix, using the GNU -tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and -other GNU programs. Compilation and installation for Cygwin is the +environment provides an excellent simulation of GNU/Linux, using the +GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, +and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: tar -xvpzf gawk-4.1.0.tar.gz @@ -26637,10 +26637,6 @@ same as for a Unix system: on Cygwin takes considerably longer. However, it does finish, and then the `make' proceeds as usual. - NOTE: The `|&' operator and TCP/IP networking (*note TCP/IP - Networking::) are fully supported in the Cygwin environment. This - is not true for any other environment on MS-Windows. -  File: gawk.info, Node: MSYS, Prev: Cygwin, Up: PC Installation @@ -26804,7 +26800,8 @@ add the `gawk' and `awk' to the system wide `DCLTABLES'. The DCL syntax is documented in the `gawk.hlp' file. - Optionally, `gawk.hlp' entry can be loaded into a VMS help library: + Optionally, the `gawk.hlp' entry can be loaded into a VMS help +library: $ LIBRARY/HELP sys$help:helplib [.vms]gawk.hlp @@ -30122,7 +30119,7 @@ Index * /inet4/... special files (gawk): TCP/IP Networking. (line 6) * /inet6/... special files (gawk): TCP/IP Networking. (line 6) * ; (semicolon): Statements/Lines. (line 91) -* ; (semicolon), AWKPATH variable and: PC Using. (line 11) +* ; (semicolon), AWKPATH variable and: PC Using. (line 10) * ; (semicolon), separating statements in actions <1>: Statements. (line 10) * ; (semicolon), separating statements in actions: Action Overview. @@ -30392,7 +30389,7 @@ Index * awk, versions of, See Also Brian Kernighan's awk: BTL. (line 6) * awka compiler for awk: Other Versions. (line 64) * AWKLIBPATH environment variable: AWKLIBPATH Variable. (line 6) -* AWKPATH environment variable <1>: PC Using. (line 11) +* AWKPATH environment variable <1>: PC Using. (line 10) * AWKPATH environment variable: AWKPATH Variable. (line 6) * awkprof.out file: Profiling. (line 6) * awksed.awk program: Simple Sed. (line 25) @@ -30485,7 +30482,7 @@ Index * bindtextdomain() function (gawk): I18N Functions. (line 12) * bindtextdomain() function (gawk), portability and: I18N Portability. (line 33) -* BINMODE variable <1>: PC Using. (line 34) +* BINMODE variable <1>: PC Using. (line 33) * BINMODE variable: User-modified. (line 10) * bits2str() user-defined function: Bitwise Functions. (line 70) * bitwise, complement: Bitwise Functions. (line 25) @@ -30630,7 +30627,7 @@ Index * common extensions, /dev/stdin special file: Special FD. (line 46) * common extensions, /dev/stdout special file: Special FD. (line 46) * common extensions, \x escape sequence: Escape Sequences. (line 61) -* common extensions, BINMODE variable: PC Using. (line 34) +* common extensions, BINMODE variable: PC Using. (line 33) * common extensions, delete to delete entire arrays: Delete. (line 39) * common extensions, func keyword: Definition Syntax. (line 83) * common extensions, length() applied to an array: String Functions. @@ -30899,7 +30896,7 @@ Index * differences in awk and gawk, BEGINFILE/ENDFILE patterns: BEGINFILE/ENDFILE. (line 6) * differences in awk and gawk, BINMODE variable <1>: PC Using. - (line 34) + (line 33) * differences in awk and gawk, BINMODE variable: User-modified. (line 23) * differences in awk and gawk, close() function: Close Files And Pipes. @@ -31086,7 +31083,7 @@ Index * extensions, common, /dev/stdin special file: Special FD. (line 46) * extensions, common, /dev/stdout special file: Special FD. (line 46) * extensions, common, \x escape sequence: Escape Sequences. (line 61) -* extensions, common, BINMODE variable: PC Using. (line 34) +* extensions, common, BINMODE variable: PC Using. (line 33) * extensions, common, delete to delete entire arrays: Delete. (line 39) * extensions, common, func keyword: Definition Syntax. (line 83) * extensions, common, length() applied to an array: String Functions. @@ -31215,7 +31212,7 @@ Index * floating-point, numbers: General Arithmetic. (line 6) * floating-point, VAX/VMS: VMS Running. (line 51) * fnmatch() extension function: Extension Sample Fnmatch. - (line 6) + (line 12) * FNR variable <1>: Auto-set. (line 103) * FNR variable: Records. (line 6) * FNR variable, changing: Auto-set. (line 314) @@ -31375,11 +31372,11 @@ Index * gawk, line continuation in: Conditional Exp. (line 34) * gawk, LINT variable in: User-modified. (line 98) * gawk, list of contributors to: Contributors. (line 6) -* gawk, MS-DOS version of: PC Using. (line 11) -* gawk, MS-Windows version of: PC Using. (line 11) +* gawk, MS-DOS version of: PC Using. (line 10) +* gawk, MS-Windows version of: PC Using. (line 10) * gawk, newlines in: Statements/Lines. (line 12) * gawk, octal numbers and: Nondecimal-numbers. (line 42) -* gawk, OS/2 version of: PC Using. (line 11) +* gawk, OS/2 version of: PC Using. (line 10) * gawk, PROCINFO array in <1>: Two-way I/O. (line 116) * gawk, PROCINFO array in <2>: Time Functions. (line 47) * gawk, PROCINFO array in: Auto-set. (line 133) @@ -31743,7 +31740,7 @@ Index (line 9) * matching, leftmost longest: Multiple Line. (line 26) * matching, null strings: Gory Details. (line 164) -* mawk program: Other Versions. (line 44) +* mawk utility: Other Versions. (line 44) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 41) * message object files, converting from portable object files: I18N Example. @@ -32143,6 +32140,7 @@ Index * r debugger command (alias for run): Debugger Execution Control. (line 62) * Rakitzis, Byron: History Sorting. (line 25) +* Ramey, Chet <1>: General Data Types. (line 6) * Ramey, Chet: Acknowledgments. (line 60) * rand() function: Numeric Functions. (line 34) * random numbers, Cliff: Cliff Random Function. @@ -32255,9 +32253,10 @@ Index * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) * Robbins, Arnold <3>: Contributors. (line 132) -* Robbins, Arnold <4>: Alarm Program. (line 6) -* Robbins, Arnold <5>: Passwd Functions. (line 90) -* Robbins, Arnold <6>: Getline/Pipe. (line 39) +* Robbins, Arnold <4>: General Data Types. (line 6) +* Robbins, Arnold <5>: Alarm Program. (line 6) +* Robbins, Arnold <6>: Passwd Functions. (line 90) +* Robbins, Arnold <7>: Getline/Pipe. (line 39) * Robbins, Arnold: Command Line Field Separator. (line 80) * Robbins, Bill: Getline/Pipe. (line 39) @@ -32299,13 +32298,13 @@ Index * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) * search paths <1>: VMS Running. (line 58) -* search paths <2>: PC Using. (line 11) +* search paths <2>: PC Using. (line 10) * search paths <3>: Igawk Program. (line 368) * search paths <4>: AWKLIBPATH Variable. (line 6) * search paths: AWKPATH Variable. (line 6) * search paths, for shared libraries: AWKLIBPATH Variable. (line 6) * search paths, for source files <1>: VMS Running. (line 58) -* search paths, for source files <2>: PC Using. (line 11) +* search paths, for source files <2>: PC Using. (line 10) * search paths, for source files <3>: Igawk Program. (line 368) * search paths, for source files: AWKPATH Variable. (line 6) * searching: String Functions. (line 150) @@ -32316,7 +32315,7 @@ Index * sed utility: Field Splitting Summary. (line 46) * semicolon (;): Statements/Lines. (line 91) -* semicolon (;), AWKPATH variable and: PC Using. (line 11) +* semicolon (;), AWKPATH variable and: PC Using. (line 10) * semicolon (;), separating statements in actions <1>: Statements. (line 10) * semicolon (;), separating statements in actions: Action Overview. @@ -32337,6 +32336,7 @@ Index (line 12) * shells, quoting, rules for: Quoting. (line 18) * shells, scripts: One-shot. (line 22) +* shells, sea: Undocumented. (line 8) * shells, variables: Using Shell Variables. (line 6) * shift, bitwise: Bitwise Functions. (line 32) @@ -32625,7 +32625,7 @@ Index * Unix awk, password files, field separators and: Command Line Field Separator. (line 72) * Unix, awk scripts and: Executable Scripts. (line 6) -* UNIXROOT variable, on OS/2 systems: PC Using. (line 17) +* UNIXROOT variable, on OS/2 systems: PC Using. (line 16) * unsigned integers: General Arithmetic. (line 15) * until debugger command: Debugger Execution Control. (line 83) @@ -33089,196 +33089,196 @@ Ref: Explaining gettext-Footnote-1767494 Ref: Explaining gettext-Footnote-2767678 Node: Programmer i18n767843 Node: Translator i18n772045 -Node: String Extraction772838 -Ref: String Extraction-Footnote-1773799 -Node: Printf Ordering773885 -Ref: Printf Ordering-Footnote-1776669 -Node: I18N Portability776733 -Ref: I18N Portability-Footnote-1779182 -Node: I18N Example779245 -Ref: I18N Example-Footnote-1781883 -Node: Gawk I18N781955 -Node: Debugger782576 -Node: Debugging783547 -Node: Debugging Concepts783980 -Node: Debugging Terms785836 -Node: Awk Debugging788433 -Node: Sample Debugging Session789325 -Node: Debugger Invocation789845 +Node: String Extraction772839 +Ref: String Extraction-Footnote-1773800 +Node: Printf Ordering773886 +Ref: Printf Ordering-Footnote-1776668 +Node: I18N Portability776732 +Ref: I18N Portability-Footnote-1779181 +Node: I18N Example779244 +Ref: I18N Example-Footnote-1781882 +Node: Gawk I18N781954 +Node: Debugger782575 +Node: Debugging783546 +Node: Debugging Concepts783979 +Node: Debugging Terms785835 +Node: Awk Debugging788432 +Node: Sample Debugging Session789324 +Node: Debugger Invocation789844 Node: Finding The Bug791177 -Node: List of Debugger Commands797665 -Node: Breakpoint Control798999 -Node: Debugger Execution Control802663 -Node: Viewing And Changing Data806023 -Node: Execution Stack809379 -Node: Debugger Info810846 -Node: Miscellaneous Debugger Commands814828 -Node: Readline Support820004 -Node: Limitations820835 -Node: Arbitrary Precision Arithmetic823087 -Ref: Arbitrary Precision Arithmetic-Footnote-1824736 -Node: General Arithmetic824884 -Node: Floating Point Issues826604 -Node: String Conversion Precision827485 -Ref: String Conversion Precision-Footnote-1829190 -Node: Unexpected Results829299 -Node: POSIX Floating Point Problems831452 -Ref: POSIX Floating Point Problems-Footnote-1835277 -Node: Integer Programming835315 -Node: Floating-point Programming837054 -Ref: Floating-point Programming-Footnote-1843385 -Ref: Floating-point Programming-Footnote-2843655 -Node: Floating-point Representation843919 -Node: Floating-point Context845084 -Ref: table-ieee-formats845923 -Node: Rounding Mode847307 -Ref: table-rounding-modes847786 -Ref: Rounding Mode-Footnote-1850801 -Node: Gawk and MPFR850980 -Node: Arbitrary Precision Floats852235 -Ref: Arbitrary Precision Floats-Footnote-1854678 -Node: Setting Precision854994 -Ref: table-predefined-precision-strings855680 -Node: Setting Rounding Mode857825 -Ref: table-gawk-rounding-modes858229 -Node: Floating-point Constants859416 -Node: Changing Precision860845 -Ref: Changing Precision-Footnote-1862242 -Node: Exact Arithmetic862416 -Node: Arbitrary Precision Integers865554 -Ref: Arbitrary Precision Integers-Footnote-1868572 -Node: Dynamic Extensions868719 -Node: Extension Intro870177 -Node: Plugin License871442 -Node: Extension Mechanism Outline872127 -Ref: load-extension872544 -Ref: load-new-function874022 -Ref: call-new-function875017 -Node: Extension API Description877032 -Node: Extension API Functions Introduction878245 -Node: General Data Types883111 -Ref: General Data Types-Footnote-1888713 -Node: Requesting Values889012 -Ref: table-value-types-returned889743 -Node: Constructor Functions890697 -Node: Registration Functions893717 -Node: Extension Functions894402 -Node: Exit Callback Functions896627 -Node: Extension Version String897876 -Node: Input Parsers898526 -Node: Output Wrappers908283 -Node: Two-way processors912793 -Node: Printing Messages915001 -Ref: Printing Messages-Footnote-1916078 -Node: Updating `ERRNO'916230 -Node: Accessing Parameters916969 -Node: Symbol Table Access918199 -Node: Symbol table by name918711 -Node: Symbol table by cookie920458 -Ref: Symbol table by cookie-Footnote-1924588 -Node: Cached values924651 -Ref: Cached values-Footnote-1928100 -Node: Array Manipulation928191 -Ref: Array Manipulation-Footnote-1929289 -Node: Array Data Types929328 -Ref: Array Data Types-Footnote-1932031 -Node: Array Functions932123 -Node: Flattening Arrays935889 -Node: Creating Arrays942741 -Node: Extension API Variables947466 -Node: Extension Versioning948102 -Node: Extension API Informational Variables950003 -Node: Extension API Boilerplate951089 -Node: Finding Extensions954893 -Node: Extension Example955453 -Node: Internal File Description956183 -Node: Internal File Ops960274 -Ref: Internal File Ops-Footnote-1971782 -Node: Using Internal File Ops971922 -Ref: Using Internal File Ops-Footnote-1974275 -Node: Extension Samples974541 -Node: Extension Sample File Functions976065 -Node: Extension Sample Fnmatch984550 -Node: Extension Sample Fork986276 -Node: Extension Sample Inplace987494 -Node: Extension Sample Ord989272 -Node: Extension Sample Readdir990108 -Node: Extension Sample Revout991640 -Node: Extension Sample Rev2way992233 -Node: Extension Sample Read write array992923 -Node: Extension Sample Readfile994806 -Node: Extension Sample API Tests995624 -Node: Extension Sample Time996149 -Node: gawkextlib997513 -Node: Language History1000294 -Node: V7/SVR3.11001887 -Node: SVR41004207 -Node: POSIX1005649 -Node: BTL1007035 -Node: POSIX/GNU1007769 -Node: Feature History1013368 -Node: Common Extensions1026332 -Node: Ranges and Locales1027644 -Ref: Ranges and Locales-Footnote-11032262 -Ref: Ranges and Locales-Footnote-21032289 -Ref: Ranges and Locales-Footnote-31032549 -Node: Contributors1032770 -Node: Installation1037915 -Node: Gawk Distribution1038809 -Node: Getting1039293 -Node: Extracting1040119 -Node: Distribution contents1041811 -Node: Unix Installation1047516 -Node: Quick Installation1048133 -Node: Additional Configuration Options1050577 -Node: Configuration Philosophy1052313 -Node: Non-Unix Installation1054667 -Node: PC Installation1055125 -Node: PC Binary Installation1056424 -Node: PC Compiling1058272 -Node: PC Testing1061216 -Node: PC Using1062392 -Node: Cygwin1066577 -Node: MSYS1067577 -Node: VMS Installation1068091 -Node: VMS Compilation1068855 -Ref: VMS Compilation-Footnote-11070470 -Node: VMS Dynamic Extensions1070528 -Node: VMS Installation Details1071901 -Node: VMS Running1074148 -Node: VMS GNV1076982 -Node: VMS Old Gawk1077705 -Node: Bugs1078175 -Node: Other Versions1082093 -Node: Notes1088177 -Node: Compatibility Mode1088977 -Node: Additions1089760 -Node: Accessing The Source1090687 -Node: Adding Code1092127 -Node: New Ports1098172 -Node: Derived Files1102307 -Ref: Derived Files-Footnote-11107628 -Ref: Derived Files-Footnote-21107662 -Ref: Derived Files-Footnote-31108262 -Node: Future Extensions1108360 -Node: Implementation Limitations1108943 -Node: Extension Design1110195 -Node: Old Extension Problems1111349 -Ref: Old Extension Problems-Footnote-11112857 -Node: Extension New Mechanism Goals1112914 -Ref: Extension New Mechanism Goals-Footnote-11116279 -Node: Extension Other Design Decisions1116465 -Node: Extension Future Growth1118571 -Node: Old Extension Mechanism1119407 -Node: Basic Concepts1121147 -Node: Basic High Level1121828 -Ref: figure-general-flow1122099 -Ref: figure-process-flow1122698 -Ref: Basic High Level-Footnote-11125927 -Node: Basic Data Typing1126112 -Node: Glossary1129467 -Node: Copying1154929 -Node: GNU Free Documentation License1192486 -Node: Index1217623 +Node: List of Debugger Commands797664 +Node: Breakpoint Control798998 +Node: Debugger Execution Control802662 +Node: Viewing And Changing Data806022 +Node: Execution Stack809378 +Node: Debugger Info810845 +Node: Miscellaneous Debugger Commands814827 +Node: Readline Support820003 +Node: Limitations820834 +Node: Arbitrary Precision Arithmetic823086 +Ref: Arbitrary Precision Arithmetic-Footnote-1824735 +Node: General Arithmetic824883 +Node: Floating Point Issues826603 +Node: String Conversion Precision827484 +Ref: String Conversion Precision-Footnote-1829189 +Node: Unexpected Results829298 +Node: POSIX Floating Point Problems831451 +Ref: POSIX Floating Point Problems-Footnote-1835276 +Node: Integer Programming835314 +Node: Floating-point Programming837053 +Ref: Floating-point Programming-Footnote-1843384 +Ref: Floating-point Programming-Footnote-2843654 +Node: Floating-point Representation843918 +Node: Floating-point Context845083 +Ref: table-ieee-formats845922 +Node: Rounding Mode847306 +Ref: table-rounding-modes847785 +Ref: Rounding Mode-Footnote-1850800 +Node: Gawk and MPFR850979 +Node: Arbitrary Precision Floats852234 +Ref: Arbitrary Precision Floats-Footnote-1854677 +Node: Setting Precision854993 +Ref: table-predefined-precision-strings855679 +Node: Setting Rounding Mode857824 +Ref: table-gawk-rounding-modes858228 +Node: Floating-point Constants859415 +Node: Changing Precision860844 +Ref: Changing Precision-Footnote-1862241 +Node: Exact Arithmetic862415 +Node: Arbitrary Precision Integers865553 +Ref: Arbitrary Precision Integers-Footnote-1868568 +Node: Dynamic Extensions868715 +Node: Extension Intro870173 +Node: Plugin License871438 +Node: Extension Mechanism Outline872123 +Ref: load-extension872540 +Ref: load-new-function874018 +Ref: call-new-function875013 +Node: Extension API Description877028 +Node: Extension API Functions Introduction878241 +Node: General Data Types883107 +Ref: General Data Types-Footnote-1888709 +Node: Requesting Values889008 +Ref: table-value-types-returned889739 +Node: Constructor Functions890693 +Node: Registration Functions893713 +Node: Extension Functions894398 +Node: Exit Callback Functions896624 +Node: Extension Version String897873 +Node: Input Parsers898523 +Node: Output Wrappers908280 +Node: Two-way processors912790 +Node: Printing Messages914998 +Ref: Printing Messages-Footnote-1916075 +Node: Updating `ERRNO'916227 +Node: Accessing Parameters916966 +Node: Symbol Table Access918196 +Node: Symbol table by name918708 +Node: Symbol table by cookie920455 +Ref: Symbol table by cookie-Footnote-1924585 +Node: Cached values924648 +Ref: Cached values-Footnote-1928097 +Node: Array Manipulation928188 +Ref: Array Manipulation-Footnote-1929286 +Node: Array Data Types929325 +Ref: Array Data Types-Footnote-1932028 +Node: Array Functions932120 +Node: Flattening Arrays935886 +Node: Creating Arrays942738 +Node: Extension API Variables947463 +Node: Extension Versioning948099 +Node: Extension API Informational Variables950000 +Node: Extension API Boilerplate951086 +Node: Finding Extensions954890 +Node: Extension Example955450 +Node: Internal File Description956180 +Node: Internal File Ops960271 +Ref: Internal File Ops-Footnote-1971780 +Node: Using Internal File Ops971920 +Ref: Using Internal File Ops-Footnote-1974273 +Node: Extension Samples974539 +Node: Extension Sample File Functions976063 +Node: Extension Sample Fnmatch984548 +Node: Extension Sample Fork986317 +Node: Extension Sample Inplace987530 +Node: Extension Sample Ord989308 +Node: Extension Sample Readdir990144 +Node: Extension Sample Revout991676 +Node: Extension Sample Rev2way992269 +Node: Extension Sample Read write array992959 +Node: Extension Sample Readfile994842 +Node: Extension Sample API Tests995660 +Node: Extension Sample Time996185 +Node: gawkextlib997549 +Node: Language History1000330 +Node: V7/SVR3.11001923 +Node: SVR41004243 +Node: POSIX1005685 +Node: BTL1007071 +Node: POSIX/GNU1007805 +Node: Feature History1013404 +Node: Common Extensions1026380 +Node: Ranges and Locales1027692 +Ref: Ranges and Locales-Footnote-11032309 +Ref: Ranges and Locales-Footnote-21032336 +Ref: Ranges and Locales-Footnote-31032570 +Node: Contributors1032791 +Node: Installation1037936 +Node: Gawk Distribution1038830 +Node: Getting1039314 +Node: Extracting1040140 +Node: Distribution contents1041832 +Node: Unix Installation1047537 +Node: Quick Installation1048154 +Node: Additional Configuration Options1050600 +Node: Configuration Philosophy1052336 +Node: Non-Unix Installation1054690 +Node: PC Installation1055148 +Node: PC Binary Installation1056447 +Node: PC Compiling1058295 +Node: PC Testing1061239 +Node: PC Using1062415 +Node: Cygwin1066583 +Node: MSYS1067392 +Node: VMS Installation1067906 +Node: VMS Compilation1068670 +Ref: VMS Compilation-Footnote-11070285 +Node: VMS Dynamic Extensions1070343 +Node: VMS Installation Details1071716 +Node: VMS Running1073967 +Node: VMS GNV1076801 +Node: VMS Old Gawk1077524 +Node: Bugs1077994 +Node: Other Versions1081912 +Node: Notes1087996 +Node: Compatibility Mode1088796 +Node: Additions1089579 +Node: Accessing The Source1090506 +Node: Adding Code1091946 +Node: New Ports1097991 +Node: Derived Files1102126 +Ref: Derived Files-Footnote-11107447 +Ref: Derived Files-Footnote-21107481 +Ref: Derived Files-Footnote-31108081 +Node: Future Extensions1108179 +Node: Implementation Limitations1108762 +Node: Extension Design1110014 +Node: Old Extension Problems1111168 +Ref: Old Extension Problems-Footnote-11112676 +Node: Extension New Mechanism Goals1112733 +Ref: Extension New Mechanism Goals-Footnote-11116098 +Node: Extension Other Design Decisions1116284 +Node: Extension Future Growth1118390 +Node: Old Extension Mechanism1119226 +Node: Basic Concepts1120966 +Node: Basic High Level1121647 +Ref: figure-general-flow1121918 +Ref: figure-process-flow1122517 +Ref: Basic High Level-Footnote-11125746 +Node: Basic Data Typing1125931 +Node: Glossary1129286 +Node: Copying1154748 +Node: GNU Free Documentation License1192305 +Node: Index1217442  End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 50496c26..736c42c3 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -4221,6 +4221,7 @@ in case some option becomes obsolete in a future version of @command{gawk}. @author Obi-Wan @end quotation +@cindex shells, sea This @value{SECTION} intentionally left blank. @@ -4233,7 +4234,7 @@ blank. @table @code @item -W nostalgia @itemx --nostalgia -Print the message @code{"awk: bailing out near line 1"} and dump core. +Print the message @samp{awk: bailing out near line 1} and dump core. This option was inspired by the common behavior of very early versions of Unix @command{awk} and by a t--shirt. The message is @emph{not} subject to translation in non-English locales. @@ -6558,7 +6559,7 @@ $ @kbd{echo a b | gawk 'BEGIN @{ FS = "" @}} @end example @cindex dark corner, @code{FS} as null string -@cindex FS variable, as null string +@cindex @code{FS} variable, as null string Traditionally, the behavior of @code{FS} equal to @code{""} was not defined. In this case, most versions of Unix @command{awk} simply treat the entire record as only having one field. @@ -26475,7 +26476,7 @@ and use translations from @command{awk}. @cindex portable object files @cindex files, portable object Once a program's translatable strings have been marked, they must -be extracted to create the initial @file{.po} file. +be extracted to create the initial @file{.pot} file. As part of translation, it is often helpful to rearrange the order in which arguments to @code{printf} are output. @@ -26570,7 +26571,7 @@ example, @samp{string} is the first argument and @samp{length(string)} is the se @example $ @kbd{gawk 'BEGIN @{} > @kbd{string = "Dont Panic"} -> @kbd{printf _"%2$d characters live in \"%1$s\"\n",} +> @kbd{printf "%2$d characters live in \"%1$s\"\n",} > @kbd{string, length(string)} > @kbd{@}'} @print{} 10 characters live in "Dont Panic" @@ -26604,7 +26605,7 @@ This is somewhat counterintuitive. and those with positional specifiers in the same string: @example -$ @kbd{gawk 'BEGIN @{ printf _"%d %3$s\n", 1, 2, "hi" @}'} +$ @kbd{gawk 'BEGIN @{ printf "%d %3$s\n", 1, 2, "hi" @}'} @error{} gawk: cmd. line:1: fatal: must use `count$' on all formats or none @end example @@ -27020,12 +27021,13 @@ as our example. @node Debugger Invocation @subsection How to Start the Debugger -Starting the debugger is almost exactly like running @command{awk}, except you have to -pass an additional option @option{--debug} or the corresponding short option @option{-D}. -The file(s) containing the program and any supporting code are given on the command -line as arguments to one or more @option{-f} options. (@command{gawk} is not designed -to debug command-line programs, only programs contained in files.) In our case, -we invoke the debugger like this: +Starting the debugger is almost exactly like running @command{gawk}, +except you have to pass an additional option @option{--debug} or the +corresponding short option @option{-D}. The file(s) containing the +program and any supporting code are given on the command line as arguments +to one or more @option{-f} options. (@command{gawk} is not designed +to debug command-line programs, only programs contained in files.) +In our case, we invoke the debugger like this: @example $ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile} @@ -27158,7 +27160,7 @@ gawk> @kbd{p NR} @noindent So we can see that @code{are_equal()} was only called for the second record -of the file. Of course, this is because our program contained a rule for +of the file. Of course, this is because our program contains a rule for @samp{NR == 1}: @example @@ -29325,7 +29327,7 @@ to begin with: gawk -M 'BEGIN @{ n = 13.0; print n % 2.0 @}' @end example -Note that for the particular example above, there is likely best +Note that for the particular example above, it is likely best to just use the following: @example @@ -29670,6 +29672,8 @@ the macros as if they were functions. @node General Data Types @subsection General Purpose Data Types +@cindex Robbins, Arnold +@cindex Ramey, Chet @quotation @i{I have a true love/hate relationship with unions.} @author Arnold Robbins @@ -29997,7 +30001,7 @@ Letter case in function names is significant. This is a pointer to the C function that provides the desired functionality. The function must fill in the result with either a number -or a string. @command{awk} takes ownership of any string memory. +or a string. @command{gawk} takes ownership of any string memory. As mentioned earlier, string memory @strong{must} come from @code{malloc()}. The @code{num_actual_args} argument tells the C function how many @@ -32067,7 +32071,7 @@ do_stat(int nargs, awk_value_t *result) awk_array_t array; int ret; struct stat sbuf; - /* default is stat() */ + /* default is lstat() */ int (*statfunc)(const char *path, struct stat *sbuf) = lstat; assert(result != NULL); @@ -32295,7 +32299,7 @@ upon success or less than zero upon error. In the latter case it updates @code{ERRNO}. @cindex @code{stat()} extension function -@item result = stat("/some/path", statdata [, follow]) +@item result = stat("/some/path", statdata @r{[}, follow@r{]}) The @code{stat()} function provides a hook into the @code{stat()} system call. It returns zero upon success or less than zero upon error. @@ -32505,19 +32509,23 @@ See @file{test/fts.awk} in the @command{gawk} distribution for an example. @node Extension Sample Fnmatch @subsection Interface To @code{fnmatch()} -@cindex @code{fnmatch()} extension function This extension provides an interface to the C library @code{fnmatch()} function. The usage is: -@example -@@load "fnmatch" +@table @code +@item @@load "fnmatch" +This is how you load the extension. -result = fnmatch(pattern, string, flags) -@end example +@cindex @code{fnmatch()} extension function +@item result = fnmatch(pattern, string, flags) +The return value is zero on success, @code{FNM_NOMATCH} +if the string did not match the pattern, or +a different non-zero value if an error occurred. +@end table -The @code{fnmatch} extension adds a single function named -@code{fnmatch()}, one constant (@code{FNM_NOMATCH}), and an array of -flag values named @code{FNM}. +Besides the @code{fnmatch()} function, the @code{fnmatch} extension +adds one constant (@code{FNM_NOMATCH}), and an array of flag values +named @code{FNM}. The arguments to @code{fnmatch()} are: @@ -32533,10 +32541,6 @@ Either zero, or the bitwise OR of one or more of the flags in the @code{FNM} array. @end table -The return value is zero on success, @code{FNM_NOMATCH} -if the string did not match the pattern, or -a different non-zero value if an error occurred. - The flags are follows: @multitable @columnfractions .25 .75 @@ -32580,15 +32584,15 @@ This is how you load the extension. @cindex @code{fork()} extension function @item pid = fork() -This function creates a new process. The return value is the zero in the -child and the process-id number of the child in the parent, or @minus{}1 +This function creates a new process. The return value is zero in the +child and the process-ID number of the child in the parent, or @minus{}1 upon error. In the latter case, @code{ERRNO} indicates the problem. In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are updated to reflect the correct values. @cindex @code{waitpid()} extension function @item ret = waitpid(pid) -This function takes a numeric argument, which is the process-id to +This function takes a numeric argument, which is the process-ID to wait for. The return value is that of the @code{waitpid()} system call. @@ -34212,7 +34216,7 @@ The @option{-i} and @option{--include} options load @command{awk} library files. @item -The @option{-l} and @option{--load} options for load compiled dynamic extensions. +The @option{-l} and @option{--load} options load compiled dynamic extensions. @item The @option{-M} and @option{--bignum} options enable MPFR. @@ -34233,7 +34237,7 @@ Support for high precision arithmetic with MPFR. @item The @code{and()}, @code{or()} and @code{xor()} functions -allow any number of arguments, +changed to allow any number of arguments, with a minimum of two (@pxref{Bitwise Functions}). @@ -34258,18 +34262,18 @@ the three most widely-used freely available versions of @command{awk} @multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} @headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @item @samp{\x} Escape sequence @tab X @tab X @tab X -@item @code{RS} as regexp @tab @tab X @tab X @item @code{FS} as null string @tab X @tab X @tab X @item @file{/dev/stdin} special file @tab X @tab X @tab X @item @file{/dev/stdout} special file @tab X @tab X @tab X @item @file{/dev/stderr} special file @tab X @tab X @tab X -@item @code{**} and @code{**=} operators @tab X @tab @tab X -@item @code{fflush()} function @tab X @tab X @tab X -@item @code{func} keyword @tab X @tab @tab X -@item @code{nextfile} statement @tab X @tab X @tab X @item @code{delete} without subscript @tab X @tab X @tab X +@item @code{fflush()} function @tab X @tab X @tab X @item @code{length()} of an array @tab X @tab X @tab X +@item @code{nextfile} statement @tab X @tab X @tab X +@item @code{**} and @code{**=} operators @tab X @tab @tab X +@item @code{func} keyword @tab X @tab @tab X @item @code{BINMODE} variable @tab @tab X @tab X +@item @code{RS} as regexp @tab @tab X @tab X @item Time related functions @tab @tab X @tab X @end multitable @@ -34358,10 +34362,10 @@ the @command{gawk} maintainer grew weary of trying to explain that was in the user's locale. During the development of version 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And -thus was born the Campain for Rational Range Interpretation (or RRI). A number -of GNU tools, such as @command{grep} and @command{sed}, have either -implemented this change, or will soon. Thanks to Karl Berry for coining the phrase -``Rational Range Interpretation.''} +thus was born the Campaign for Rational Range Interpretation (or +RRI). A number of GNU tools have either implemented this change, +or will soon. Thanks to Karl Berry for coining the phrase ``Rational +Range Interpretation.''} Fortunately, shortly before the final release of @command{gawk} 4.0, the maintainer learned that the 2008 standard had changed the @@ -34374,7 +34378,7 @@ and By using this lovely technical term, the standard gives license to implementors to implement ranges in whatever way they choose. The @command{gawk} maintainer chose to apply the pre-POSIX meaning in all -cases: the default regexp matching; with @option{--traditional}, and with +cases: the default regexp matching; with @option{--traditional} and with @option{--posix}; in all cases, @command{gawk} remains POSIX compliant. @node Contributors @@ -35015,7 +35019,7 @@ please send in a bug report (@pxref{Bugs}). Of course, once you've built @command{gawk}, it is likely that you will wish to install it. To do so, you need to run the command @samp{make -check}, as a user with the appropriate permissions. How to do this +install}, as a user with the appropriate permissions. How to do this varies by system, but on many systems you can use the @command{sudo} command to do so. The command then becomes @samp{sudo make install}. It is likely that you will be asked for your password, and you will have @@ -35341,11 +35345,10 @@ multibyte functionality is not available. @c STARTOFRANGE pcgawon @cindex PC operating systems, @command{gawk} on -With the exception of the Cygwin environment, -the @samp{|&} operator and TCP/IP networking -(@pxref{TCP/IP Networking}) -are not supported for MS-DOS or MS-Windows. EMX (OS/2 only) does support -at least the @samp{|&} operator. +Under MS-DOS and MS-Windows, the Cygwin and MinGW environments support +both the @samp{|&} operator and TCP/IP networking +(@pxref{TCP/IP Networking}). +EMX (OS/2 only) supports at least the @samp{|&} operator. @cindex search paths @cindex search paths, for source files @@ -35475,7 +35478,7 @@ moved into the @code{BEGIN} rule. @command{gawk} can be built and used ``out of the box'' under MS-Windows if you are using the @uref{http://www.cygwin.com, Cygwin environment}. -This environment provides an excellent simulation of Unix, using the +This environment provides an excellent simulation of GNU/Linux, using the GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: @@ -35491,13 +35494,6 @@ When compared to GNU/Linux on the same system, the @samp{configure} step on Cygwin takes considerably longer. However, it does finish, and then the @samp{make} proceeds as usual. -@quotation NOTE -The @samp{|&} operator and TCP/IP networking -(@pxref{TCP/IP Networking}) -are fully supported in the Cygwin environment. This is not true -for any other environment on MS-Windows. -@end quotation - @node MSYS @appendixsubsubsec Using @command{gawk} In The MSYS Environment @@ -35676,7 +35672,7 @@ add the @command{gawk} and @command{awk} to the system wide @samp{DCLTABLES}. The DCL syntax is documented in the @file{gawk.hlp} file. -Optionally, @file{gawk.hlp} entry can be loaded into a VMS help library: +Optionally, the @file{gawk.hlp} entry can be loaded into a VMS help library: @example $ @kbd{LIBRARY/HELP sys$help:helplib [.vms]gawk.hlp} @@ -36018,7 +36014,7 @@ from GCC (the GNU Compiler Collection) works quite nicely. for a list of extensions in this @command{awk} that are not in POSIX @command{awk}. @cindex Brennan, Michael -@cindex @command{mawk} program +@cindex @command{mawk} utility @cindex source code, @command{mawk} @item @command{mawk} Michael Brennan wrote an independent implementation of @command{awk}, diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 48c09f31..cb9546ea 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -4149,6 +4149,7 @@ in case some option becomes obsolete in a future version of @command{gawk}. @author Obi-Wan @end quotation +@cindex shells, sea This @value{SECTION} intentionally left blank. @@ -4161,7 +4162,7 @@ blank. @table @code @item -W nostalgia @itemx --nostalgia -Print the message @code{"awk: bailing out near line 1"} and dump core. +Print the message @samp{awk: bailing out near line 1} and dump core. This option was inspired by the common behavior of very early versions of Unix @command{awk} and by a t--shirt. The message is @emph{not} subject to translation in non-English locales. @@ -6273,7 +6274,7 @@ $ @kbd{echo a b | gawk 'BEGIN @{ FS = "" @}} @end example @cindex dark corner, @code{FS} as null string -@cindex FS variable, as null string +@cindex @code{FS} variable, as null string Traditionally, the behavior of @code{FS} equal to @code{""} was not defined. In this case, most versions of Unix @command{awk} simply treat the entire record as only having one field. @@ -25618,7 +25619,7 @@ and use translations from @command{awk}. @cindex portable object files @cindex files, portable object Once a program's translatable strings have been marked, they must -be extracted to create the initial @file{.po} file. +be extracted to create the initial @file{.pot} file. As part of translation, it is often helpful to rearrange the order in which arguments to @code{printf} are output. @@ -25713,7 +25714,7 @@ example, @samp{string} is the first argument and @samp{length(string)} is the se @example $ @kbd{gawk 'BEGIN @{} > @kbd{string = "Dont Panic"} -> @kbd{printf _"%2$d characters live in \"%1$s\"\n",} +> @kbd{printf "%2$d characters live in \"%1$s\"\n",} > @kbd{string, length(string)} > @kbd{@}'} @print{} 10 characters live in "Dont Panic" @@ -25747,7 +25748,7 @@ This is somewhat counterintuitive. and those with positional specifiers in the same string: @example -$ @kbd{gawk 'BEGIN @{ printf _"%d %3$s\n", 1, 2, "hi" @}'} +$ @kbd{gawk 'BEGIN @{ printf "%d %3$s\n", 1, 2, "hi" @}'} @error{} gawk: cmd. line:1: fatal: must use `count$' on all formats or none @end example @@ -26163,12 +26164,13 @@ as our example. @node Debugger Invocation @subsection How to Start the Debugger -Starting the debugger is almost exactly like running @command{awk}, except you have to -pass an additional option @option{--debug} or the corresponding short option @option{-D}. -The file(s) containing the program and any supporting code are given on the command -line as arguments to one or more @option{-f} options. (@command{gawk} is not designed -to debug command-line programs, only programs contained in files.) In our case, -we invoke the debugger like this: +Starting the debugger is almost exactly like running @command{gawk}, +except you have to pass an additional option @option{--debug} or the +corresponding short option @option{-D}. The file(s) containing the +program and any supporting code are given on the command line as arguments +to one or more @option{-f} options. (@command{gawk} is not designed +to debug command-line programs, only programs contained in files.) +In our case, we invoke the debugger like this: @example $ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile} @@ -26301,7 +26303,7 @@ gawk> @kbd{p NR} @noindent So we can see that @code{are_equal()} was only called for the second record -of the file. Of course, this is because our program contained a rule for +of the file. Of course, this is because our program contains a rule for @samp{NR == 1}: @example @@ -28468,7 +28470,7 @@ to begin with: gawk -M 'BEGIN @{ n = 13.0; print n % 2.0 @}' @end example -Note that for the particular example above, there is likely best +Note that for the particular example above, it is likely best to just use the following: @example @@ -28813,6 +28815,8 @@ the macros as if they were functions. @node General Data Types @subsection General Purpose Data Types +@cindex Robbins, Arnold +@cindex Ramey, Chet @quotation @i{I have a true love/hate relationship with unions.} @author Arnold Robbins @@ -29140,7 +29144,7 @@ Letter case in function names is significant. This is a pointer to the C function that provides the desired functionality. The function must fill in the result with either a number -or a string. @command{awk} takes ownership of any string memory. +or a string. @command{gawk} takes ownership of any string memory. As mentioned earlier, string memory @strong{must} come from @code{malloc()}. The @code{num_actual_args} argument tells the C function how many @@ -31210,7 +31214,7 @@ do_stat(int nargs, awk_value_t *result) awk_array_t array; int ret; struct stat sbuf; - /* default is stat() */ + /* default is lstat() */ int (*statfunc)(const char *path, struct stat *sbuf) = lstat; assert(result != NULL); @@ -31438,7 +31442,7 @@ upon success or less than zero upon error. In the latter case it updates @code{ERRNO}. @cindex @code{stat()} extension function -@item result = stat("/some/path", statdata [, follow]) +@item result = stat("/some/path", statdata @r{[}, follow@r{]}) The @code{stat()} function provides a hook into the @code{stat()} system call. It returns zero upon success or less than zero upon error. @@ -31648,19 +31652,23 @@ See @file{test/fts.awk} in the @command{gawk} distribution for an example. @node Extension Sample Fnmatch @subsection Interface To @code{fnmatch()} -@cindex @code{fnmatch()} extension function This extension provides an interface to the C library @code{fnmatch()} function. The usage is: -@example -@@load "fnmatch" +@table @code +@item @@load "fnmatch" +This is how you load the extension. -result = fnmatch(pattern, string, flags) -@end example +@cindex @code{fnmatch()} extension function +@item result = fnmatch(pattern, string, flags) +The return value is zero on success, @code{FNM_NOMATCH} +if the string did not match the pattern, or +a different non-zero value if an error occurred. +@end table -The @code{fnmatch} extension adds a single function named -@code{fnmatch()}, one constant (@code{FNM_NOMATCH}), and an array of -flag values named @code{FNM}. +Besides the @code{fnmatch()} function, the @code{fnmatch} extension +adds one constant (@code{FNM_NOMATCH}), and an array of flag values +named @code{FNM}. The arguments to @code{fnmatch()} are: @@ -31676,10 +31684,6 @@ Either zero, or the bitwise OR of one or more of the flags in the @code{FNM} array. @end table -The return value is zero on success, @code{FNM_NOMATCH} -if the string did not match the pattern, or -a different non-zero value if an error occurred. - The flags are follows: @multitable @columnfractions .25 .75 @@ -31723,15 +31727,15 @@ This is how you load the extension. @cindex @code{fork()} extension function @item pid = fork() -This function creates a new process. The return value is the zero in the -child and the process-id number of the child in the parent, or @minus{}1 +This function creates a new process. The return value is zero in the +child and the process-ID number of the child in the parent, or @minus{}1 upon error. In the latter case, @code{ERRNO} indicates the problem. In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are updated to reflect the correct values. @cindex @code{waitpid()} extension function @item ret = waitpid(pid) -This function takes a numeric argument, which is the process-id to +This function takes a numeric argument, which is the process-ID to wait for. The return value is that of the @code{waitpid()} system call. @@ -33355,7 +33359,7 @@ The @option{-i} and @option{--include} options load @command{awk} library files. @item -The @option{-l} and @option{--load} options for load compiled dynamic extensions. +The @option{-l} and @option{--load} options load compiled dynamic extensions. @item The @option{-M} and @option{--bignum} options enable MPFR. @@ -33376,7 +33380,7 @@ Support for high precision arithmetic with MPFR. @item The @code{and()}, @code{or()} and @code{xor()} functions -allow any number of arguments, +changed to allow any number of arguments, with a minimum of two (@pxref{Bitwise Functions}). @@ -33401,18 +33405,18 @@ the three most widely-used freely available versions of @command{awk} @multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} @headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @item @samp{\x} Escape sequence @tab X @tab X @tab X -@item @code{RS} as regexp @tab @tab X @tab X @item @code{FS} as null string @tab X @tab X @tab X @item @file{/dev/stdin} special file @tab X @tab X @tab X @item @file{/dev/stdout} special file @tab X @tab X @tab X @item @file{/dev/stderr} special file @tab X @tab X @tab X -@item @code{**} and @code{**=} operators @tab X @tab @tab X -@item @code{fflush()} function @tab X @tab X @tab X -@item @code{func} keyword @tab X @tab @tab X -@item @code{nextfile} statement @tab X @tab X @tab X @item @code{delete} without subscript @tab X @tab X @tab X +@item @code{fflush()} function @tab X @tab X @tab X @item @code{length()} of an array @tab X @tab X @tab X +@item @code{nextfile} statement @tab X @tab X @tab X +@item @code{**} and @code{**=} operators @tab X @tab @tab X +@item @code{func} keyword @tab X @tab @tab X @item @code{BINMODE} variable @tab @tab X @tab X +@item @code{RS} as regexp @tab @tab X @tab X @item Time related functions @tab @tab X @tab X @end multitable @@ -33501,10 +33505,10 @@ the @command{gawk} maintainer grew weary of trying to explain that was in the user's locale. During the development of version 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And -thus was born the Campain for Rational Range Interpretation (or RRI). A number -of GNU tools, such as @command{grep} and @command{sed}, have either -implemented this change, or will soon. Thanks to Karl Berry for coining the phrase -``Rational Range Interpretation.''} +thus was born the Campaign for Rational Range Interpretation (or +RRI). A number of GNU tools have either implemented this change, +or will soon. Thanks to Karl Berry for coining the phrase ``Rational +Range Interpretation.''} Fortunately, shortly before the final release of @command{gawk} 4.0, the maintainer learned that the 2008 standard had changed the @@ -33517,7 +33521,7 @@ and By using this lovely technical term, the standard gives license to implementors to implement ranges in whatever way they choose. The @command{gawk} maintainer chose to apply the pre-POSIX meaning in all -cases: the default regexp matching; with @option{--traditional}, and with +cases: the default regexp matching; with @option{--traditional} and with @option{--posix}; in all cases, @command{gawk} remains POSIX compliant. @node Contributors @@ -34158,7 +34162,7 @@ please send in a bug report (@pxref{Bugs}). Of course, once you've built @command{gawk}, it is likely that you will wish to install it. To do so, you need to run the command @samp{make -check}, as a user with the appropriate permissions. How to do this +install}, as a user with the appropriate permissions. How to do this varies by system, but on many systems you can use the @command{sudo} command to do so. The command then becomes @samp{sudo make install}. It is likely that you will be asked for your password, and you will have @@ -34484,11 +34488,10 @@ multibyte functionality is not available. @c STARTOFRANGE pcgawon @cindex PC operating systems, @command{gawk} on -With the exception of the Cygwin environment, -the @samp{|&} operator and TCP/IP networking -(@pxref{TCP/IP Networking}) -are not supported for MS-DOS or MS-Windows. EMX (OS/2 only) does support -at least the @samp{|&} operator. +Under MS-DOS and MS-Windows, the Cygwin and MinGW environments support +both the @samp{|&} operator and TCP/IP networking +(@pxref{TCP/IP Networking}). +EMX (OS/2 only) supports at least the @samp{|&} operator. @cindex search paths @cindex search paths, for source files @@ -34618,7 +34621,7 @@ moved into the @code{BEGIN} rule. @command{gawk} can be built and used ``out of the box'' under MS-Windows if you are using the @uref{http://www.cygwin.com, Cygwin environment}. -This environment provides an excellent simulation of Unix, using the +This environment provides an excellent simulation of GNU/Linux, using the GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: @@ -34634,13 +34637,6 @@ When compared to GNU/Linux on the same system, the @samp{configure} step on Cygwin takes considerably longer. However, it does finish, and then the @samp{make} proceeds as usual. -@quotation NOTE -The @samp{|&} operator and TCP/IP networking -(@pxref{TCP/IP Networking}) -are fully supported in the Cygwin environment. This is not true -for any other environment on MS-Windows. -@end quotation - @node MSYS @appendixsubsubsec Using @command{gawk} In The MSYS Environment @@ -34819,7 +34815,7 @@ add the @command{gawk} and @command{awk} to the system wide @samp{DCLTABLES}. The DCL syntax is documented in the @file{gawk.hlp} file. -Optionally, @file{gawk.hlp} entry can be loaded into a VMS help library: +Optionally, the @file{gawk.hlp} entry can be loaded into a VMS help library: @example $ @kbd{LIBRARY/HELP sys$help:helplib [.vms]gawk.hlp} @@ -35161,7 +35157,7 @@ from GCC (the GNU Compiler Collection) works quite nicely. for a list of extensions in this @command{awk} that are not in POSIX @command{awk}. @cindex Brennan, Michael -@cindex @command{mawk} program +@cindex @command{mawk} utility @cindex source code, @command{mawk} @item @command{mawk} Michael Brennan wrote an independent implementation of @command{awk}, -- cgit v1.2.1